organization

type API struct {
	// contains filtered or unexported fields
}

type APIConfig struct {
	// BasePath is the base path for all endpoints (default: "/api/v1").
	BasePath string
	// Logger is the logger to use (default: slog.Default()).
	Logger *slog.Logger
	// Authorizer checks the caller's organization permissions
	// (authz.PermOrgView, PermOrgSettings, PermOrgInviteMember, and so
	// on). Until it is set, every endpoint except creating an
	// organization and checking a slug answers 501.
	Authorizer authz.Authorizer
	// Caller identifies the authenticated principal (default:
	// requestprincipal.PrincipalUUID, set by requestprincipal.Middleware).
	Caller func(ctx context.Context) (uuid.UUID, error)
	// Entitlements lists what an organization may use, derived from its
	// marketplace subscriptions and licenses (see
	// marketplace.EntitlementSource). Without it, responses carry an
	// empty entitlements list.
	Entitlements EntitlementSource
	// AppRoles manages application roles. Until it is set, the
	// application role endpoints answer 501.
	AppRoles *approle.Service
}

type AddMemberInput struct {
	OrganizationID uuid.UUID
	PrincipalID    uuid.UUID
	Role           string
	Permissions    []string
}

type AddMemberRequest struct {
	Slug string `path:"slug"`
	Body struct {
		PrincipalID string   `json:"principal_id" required:"true" format:"uuid"`
		Role        string   `json:"role" required:"true" enum:"owner,admin,member,collaborator"`
		Permissions []string `json:"permissions,omitempty"`
	}
}

type AddMemberResponse struct {
	Body *MemberResponse
}

type AfterCommit func(ctx context.Context) error

type AppRoleResponse struct {
	PrincipalID string  `json:"principal_id"`
	Application string  `json:"application"`
	Role        string  `json:"role"`
	AssignedBy  *string `json:"assigned_by,omitempty"`
}

type CheckSlugInput struct {
	Slug string `path:"slug"`
}

type CheckSlugOutput struct {
	Body struct {
		Available bool   `json:"available"`
		Slug      string `json:"slug"`
	}
}

type ConvertResult struct {
	// Team is the converted organization: same ID, data and memberships.
	Team *Organization
	// Personal is the new personal organization holding the owner's handle.
	Personal *Organization
}

type CreateOrgInput struct {
	Body struct {
		Name        string         `json:"name" required:"true" minLength:"1" maxLength:"100"`
		Slug        string         `json:"slug" required:"true" minLength:"3" maxLength:"63" pattern:"^[a-z][a-z0-9-]*[a-z0-9]$"`
		OrgType     string         `json:"org_type,omitempty" enum:"team,enterprise" default:"team"`
		LogoURL     *string        `json:"logo_url,omitempty"`
		Description *string        `json:"description,omitempty"`
		WebsiteURL  *string        `json:"website_url,omitempty"`
		Settings    map[string]any `json:"settings,omitempty"`
	}
}

type CreateOrgOutput struct {
	Body *OrgResponse
}

type CreateOrganizationInput struct {
	Name             string
	Slug             string
	OrgType          OrgType
	OwnerPrincipalID *uuid.UUID // Required for personal orgs
	LogoURL          *string
	Description      *string
	WebsiteURL       *string
	Settings         map[string]any
}

type CreatePersonalOrgInput struct {
	OwnerPrincipalID uuid.UUID
	Name             string  // Display name (usually user's name)
	Slug             string  // URL-safe username
	LogoURL          *string // Optional avatar
}

type DefaultService struct {
	// contains filtered or unexported fields
}

type DeleteOrgInput struct {
	Slug string `path:"slug"`
}

type Entitlement struct {
	// Source is EntitlementSourceSubscription, EntitlementSourceLicense or
	// EntitlementSourceDefault.
	Source string `json:"source"`
	// Application is the registered application identifier the entitlement
	// grants, when it grants one. A platform-wide subscription has none.
	Application string `json:"application,omitempty"`
	// Seats caps the principals who may hold a role in Application, for a
	// seat-licensed entitlement. Nil means unlimited.
	Seats *int `json:"seats,omitempty"`
	// ListingID is the marketplace listing a license is for. It is empty
	// for a subscription, which is organization-wide.
	ListingID string `json:"listing_id,omitempty"`
	// Tier is the subscription's plan tier or the license type.
	Tier string `json:"tier,omitempty"`
	// ValidUntil is when the entitlement ends, when it does.
	ValidUntil *time.Time `json:"valid_until,omitempty"`
}

type EntitlementSource func(ctx context.Context, organizationID uuid.UUID) ([]Entitlement, error)

type GetMemberAppRolesInput struct {
	Slug        string `path:"slug"`
	PrincipalID string `path:"principal_id" format:"uuid"`
}

type GetMemberAppRolesOutput struct {
	Body struct {
		AppRoles  []*AppRoleResponse `json:"app_roles"`
		Effective map[string]string  `json:"effective"`
	}
}

type GetMemberInput struct {
	Slug        string `path:"slug"`
	PrincipalID string `path:"principal_id" format:"uuid"`
}

type GetMemberOutput struct {
	Body *MemberResponse
}

type GetOrgInput struct {
	Slug string `path:"slug"`
}

type GetOrgOutput struct {
	Body *OrgResponse
}

type ListAppRolesInput struct {
	Slug        string `path:"slug"`
	Application string `query:"application" doc:"Only roles in this application"`
}

type ListAppRolesOutput struct {
	Body struct {
		AppRoles []*AppRoleResponse `json:"app_roles"`
	}
}

type ListMembersInput struct {
	Slug            string `path:"slug"`
	IncludeInactive bool   `query:"includeInactive" doc:"Also list deactivated memberships"`
}

type ListMembersOutput struct {
	Body struct {
		Members []*MemberResponse `json:"members"`
	}
}

type ListOption func(*listOptions)

type ListOrganizationsInput struct {
	OrgType *OrgType
	Active  *bool
	// MemberPrincipalID limits the list to organizations the principal is
	// an active member of.
	MemberPrincipalID *uuid.UUID
	Limit             int
	Offset            int
}

type ListOrgsInput struct {
	// Huma does not support pointer parameters; an empty value means
	// the filter is not applied.
	OrgType string `query:"org_type" enum:"personal,team,enterprise"`
	Active  string `query:"active" enum:"true,false"`
	Limit   int    `query:"limit" default:"20" minimum:"1" maximum:"100"`
	Offset  int    `query:"offset" default:"0" minimum:"0"`
}

type ListOrgsOutput struct {
	Body struct {
		Organizations []*OrgResponse `json:"organizations"`
		Total         int            `json:"total"`
	}
}

type MemberResponse struct {
	ID             string    `json:"id"`
	PrincipalID    string    `json:"principal_id"`
	OrganizationID string    `json:"organization_id"`
	Role           string    `json:"role"`
	Permissions    []string  `json:"permissions,omitempty"`
	Active         bool      `json:"active"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

type Membership struct {
	ID             uuid.UUID
	PrincipalID    uuid.UUID
	OrganizationID uuid.UUID
	Role           string
	Permissions    []string
	Active         bool
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

type OrgResponse struct {
	ID               string         `json:"id"`
	Name             string         `json:"name"`
	Slug             string         `json:"slug"`
	OrgType          string         `json:"org_type"`
	OwnerPrincipalID *string        `json:"owner_principal_id,omitempty"`
	LogoURL          *string        `json:"logo_url,omitempty"`
	Description      *string        `json:"description,omitempty"`
	WebsiteURL       *string        `json:"website_url,omitempty"`
	Active           bool           `json:"active"`
	Settings         map[string]any `json:"settings,omitempty"`
	// Entitlements summarizes what the organization may use, derived from
	// its marketplace subscriptions and licenses.
	Entitlements []Entitlement `json:"entitlements"`
	CreatedAt    time.Time     `json:"created_at"`
	UpdatedAt    time.Time     `json:"updated_at"`
}

type OrgType string

type Organization struct {
	ID               uuid.UUID
	Name             string
	Slug             string
	OrgType          OrgType
	OwnerPrincipalID *uuid.UUID // For personal orgs
	LogoURL          *string
	Description      *string
	WebsiteURL       *string
	Settings         map[string]any
	Active           bool
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

type PersonalOrgTxCreator interface {
	// CreatePersonalOrgInTx writes the personal organization and its owner
	// membership in tx and leaves committing to the caller. The owner
	// principal may be a row created earlier in the same transaction. The
	// returned AfterCommit registers the organization with the
	// authorization syncer; call it after a successful commit.
	CreatePersonalOrgInTx(ctx context.Context, tx *ent.Tx, input CreatePersonalOrgInput) (*Organization, *Membership, AfterCommit, error)
}

type RemoveAppRoleInput struct {
	Slug        string `path:"slug"`
	PrincipalID string `path:"principal_id" format:"uuid"`
	Application string `path:"application"`
}

type RemoveMemberInput struct {
	Slug        string `path:"slug"`
	PrincipalID string `path:"principal_id" format:"uuid"`
}

type Service interface {
	// Create creates a new organization.
	Create(ctx context.Context, input CreateOrganizationInput) (*Organization, error)

	// CreatePersonalOrg creates a personal organization for a user.
	CreatePersonalOrg(ctx context.Context, input CreatePersonalOrgInput) (*Organization, error)

	// GetByID retrieves an organization by ID.
	GetByID(ctx context.Context, id uuid.UUID) (*Organization, error)

	// GetBySlug retrieves an organization by slug.
	GetBySlug(ctx context.Context, slug string) (*Organization, error)

	// GetPersonalOrg retrieves a principal's personal organization.
	GetPersonalOrg(ctx context.Context, principalID uuid.UUID) (*Organization, error)

	// Update updates an organization.
	Update(ctx context.Context, id uuid.UUID, input UpdateOrganizationInput) (*Organization, error)

	// Delete soft-deletes an organization.
	Delete(ctx context.Context, id uuid.UUID) error

	// List lists organizations with optional filters.
	List(ctx context.Context, input ListOrganizationsInput) ([]*Organization, error)

	// AddMember adds a principal as a member of an organization.
	AddMember(ctx context.Context, input AddMemberInput) (*Membership, error)

	// UpdateMember updates a membership.
	UpdateMember(ctx context.Context, membershipID uuid.UUID, input UpdateMemberInput) (*Membership, error)

	// RemoveMember removes a principal from an organization.
	RemoveMember(ctx context.Context, organizationID, principalID uuid.UUID) error

	// GetMembership retrieves a specific membership.
	GetMembership(ctx context.Context, organizationID, principalID uuid.UUID) (*Membership, error)

	// ListMembers lists the active members of an organization. Pass
	// IncludeInactive to also list deactivated memberships.
	ListMembers(ctx context.Context, organizationID uuid.UUID, opts ...ListOption) ([]*Membership, error)

	// ListMemberships lists the organizations a principal is an active
	// member of. Pass IncludeInactive to also list deactivated memberships.
	ListMemberships(ctx context.Context, principalID uuid.UUID, opts ...ListOption) ([]*Membership, error)

	// ResolveSlug returns the organization using slug or, within the
	// cooling-off period after a rename, the organization that released it
	// (alias true).
	ResolveSlug(ctx context.Context, slug string) (*Organization, bool, error)

	// Rename changes an organization's slug on behalf of actor, who must
	// own it. The old slug is held for actor for the cooling-off period.
	Rename(ctx context.Context, orgID uuid.UUID, slug string, actor uuid.UUID) error

	// ConvertToTeam turns a personal organization into a team organization
	// under teamSlug and gives its owner a new personal organization with
	// the old handle, in one transaction.
	ConvertToTeam(ctx context.Context, orgID uuid.UUID, teamSlug string, actor uuid.UUID) (*ConvertResult, error)

	// SlugAvailable checks if a slug is available. A reserved slug is
	// refused with ErrSlugReserved, and one in its cooling-off period with
	// ErrSlugCoolingOff (both with false).
	SlugAvailable(ctx context.Context, slug string) (bool, error)

	// GenerateSlug generates a unique slug from a name.
	GenerateSlug(ctx context.Context, name string) (string, error)

	// TransferOwnership transfers ownership of an organization to another principal.
	TransferOwnership(ctx context.Context, input TransferOwnershipInput) error
}

type ServiceOption func(*DefaultService)

type SetAppRoleInput struct {
	Slug        string `path:"slug"`
	PrincipalID string `path:"principal_id" format:"uuid"`
	Application string `path:"application"`
	Body        struct {
		Role string `json:"role" required:"true" minLength:"1"`
	}
}

type SetAppRoleOutput struct {
	Body *AppRoleResponse
}

type TransferOwnershipInput struct {
	OrganizationID uuid.UUID
	FromPrincipal  uuid.UUID // Current owner
	ToPrincipal    uuid.UUID // New owner
	NewRoleForOld  string    // Role for the previous owner (default: "admin")
}

type TransferOwnershipRequest struct {
	Slug string `path:"slug"`
	Body struct {
		NewOwnerPrincipalID string `json:"new_owner_principal_id" required:"true" format:"uuid"`
		NewRoleForOldOwner  string `json:"new_role_for_old_owner,omitempty" enum:"admin,member"`
	}
}

type TransferOwnershipResponse struct {
	Body struct {
		Message string `json:"message"`
	}
}

type UpdateMemberInput struct {
	Role        *string
	Permissions []string
	Active      *bool
}

type UpdateMemberRequest struct {
	Slug        string `path:"slug"`
	PrincipalID string `path:"principal_id" format:"uuid"`
	Body        struct {
		Role        *string  `json:"role,omitempty" enum:"owner,admin,member,collaborator"`
		Permissions []string `json:"permissions,omitempty"`
		Active      *bool    `json:"active,omitempty"`
	}
}

type UpdateMemberResponse struct {
	Body *MemberResponse
}

type UpdateOrgInput struct {
	Slug string `path:"slug"`
	Body struct {
		Name        *string        `json:"name,omitempty" maxLength:"100"`
		LogoURL     *string        `json:"logo_url,omitempty"`
		Description *string        `json:"description,omitempty"`
		WebsiteURL  *string        `json:"website_url,omitempty"`
		Settings    map[string]any `json:"settings,omitempty"`
	}
}

type UpdateOrgOutput struct {
	Body *OrgResponse
}

type UpdateOrganizationInput struct {
	Name        *string
	LogoURL     *string
	Description *string
	WebsiteURL  *string
	Settings    map[string]any
}