entities

type AppBinding interface {
	ContentKitScope() (tenantID, appID string)
}

type Avatar struct {
	Image string `json:"image,omitempty"`
	// Renditions are its public images, filled on reads (Options.Covers).
	Renditions []Rendition `json:"renditions,omitempty"`
}

type CardOptions struct {
	// IncludeInternal is a trusted management read; As stores require staff.
	IncludeInternal bool
	// Language resolves names and paths as ListOptions.Language does.
	Language string
	// Covers fills covers' and avatars' renditions in one call; chips leave
	// them out.
	Covers bool
}

type ContentEntities struct {
	// ContentID names the content; routes take it from the path.
	ContentID string `json:"-"`
	// VersionScope limits replacement to one ownership scope. Nil preserves
	// the legacy all-version replacement; empty means shared content links;
	// otherwise it names the one version whose links may change.
	VersionScope *string `json:"-"`
	// Kinds limits the write to these entity kinds; empty means every entity
	// kind the content's kind declares.
	Kinds       []string     `json:"kinds,omitempty"`
	Memberships []Membership `json:"memberships"`
	// Create links these names too, creating entities of creatable kinds that
	// no active entity names yet, in the same transaction.
	Create []NewEntity `json:"create,omitempty"`
}

type ContentMemberships struct {
	ContentID   string       `json:"content_id"`
	Memberships []Membership `json:"memberships"`
	Entities    []EntityCard `json:"entities"`
}

type Count struct {
	ContentKind string `json:"content_kind"`
	Language    string `json:"language"`
	Count       int    `json:"count"`
}

type Cover struct {
	Image     string `json:"image,omitempty"`
	ContentID string `json:"content_id,omitempty"`
	Auto      bool   `json:"auto,omitempty"`
	// Renditions are its public images, filled on reads (Options.Covers).
	Renditions []Rendition `json:"renditions,omitempty"`
}

type CoverOf struct {
	Kind     string
	ID       EntityID
	Cover    Cover
	Language string
	Preset   string
}

type CoverResolver interface {
	Covers(ctx context.Context, covers []CoverOf) ([][]Rendition, error)
}

type Edge struct {
	From     EntityID `json:"from"`
	Relation string   `json:"relation"`
	To       EntityID `json:"to"`
}

type EdgeInput struct {
	Relation string   `json:"relation"`
	To       EntityID `json:"to"`
}

type Entity struct {
	ID   EntityID `json:"id"`
	Kind string   `json:"kind"`
	Slug string   `json:"slug"`
	// Internal marks a classification used by policy rather than public metadata.
	Internal bool `json:"internal"`
	// ScopeID is the entity the slug is unique within (a character's series).
	ScopeID     EntityID       `json:"scope_id,omitempty"`
	ParentID    EntityID       `json:"parent_id,omitempty"`
	State       State          `json:"state"`
	MergedInto  EntityID       `json:"merged_into,omitempty"`
	Attributes  map[string]any `json:"attributes"`
	Cover       *Cover         `json:"cover,omitempty"`
	Avatar      *Avatar        `json:"avatar,omitempty"`
	OwnerUserID string         `json:"owner_user_id,omitempty"`
	// AuthScope is the AuthKit group whose holders of
	// access.EntitySettingsManage edit it; ContentKit provisions it for a
	// kind with auth_scope (Options.Scopes).
	AuthScope string    `json:"auth_scope,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Revision  int64     `json:"revision"`
}

type EntityCard struct {
	ID           EntityID `json:"id"`
	Kind         string   `json:"kind"`
	Slug         string   `json:"slug"`
	Internal     bool     `json:"internal"`
	ScopeID      EntityID `json:"scope_id,omitempty"`
	ParentID     EntityID `json:"parent_id,omitempty"`
	Name         string   `json:"name"`
	NameLanguage string   `json:"name_language,omitempty"`
	Code         string   `json:"code,omitempty"`
	Path         string   `json:"path,omitempty"`
	Cover        *Cover   `json:"cover,omitempty"`
	// Avatar is a user-owned entity's avatar.
	Avatar     *Avatar        `json:"avatar,omitempty"`
	Count      int            `json:"count"`
	Attributes map[string]any `json:"attributes"`
	// Access is a sellable entity's sale: its key, active offer and the
	// viewer's standing.
	Access    *offers.EntityAccess `json:"access,omitempty"`
	CreatedAt time.Time            `json:"created_at"`
}

type EntityDetail struct {
	Entity
	Name         string       `json:"name"`
	NameLanguage string       `json:"name_language,omitempty"`
	Code         string       `json:"code,omitempty"`
	Path         string       `json:"path,omitempty"`
	Names        []Name       `json:"names"`
	Text         []Text       `json:"text"`
	Parent       *EntityCard  `json:"parent,omitempty"`
	Scope        *EntityCard  `json:"scope,omitempty"`
	Children     []EntityCard `json:"children"`
	Edges        []Edge       `json:"edges"`
	Counts       []Count      `json:"counts"`
	// Access is a sellable entity's sale: its key, active offer and the
	// viewer's standing.
	Access *offers.EntityAccess `json:"access,omitempty"`
	// Offer is a sellable entity's current offer, for its offer editors.
	Offer *offers.Offer `json:"offer,omitempty"`
}

type EntityID = contentref.EntityID

type EntityInput struct {
	// ID is optional; omitted ids are generated.
	ID   EntityID `json:"id,omitempty"`
	Kind string   `json:"kind"`
	Slug string   `json:"slug"`
	// Internal classifications are visible only through management reads.
	Internal bool `json:"internal,omitempty"`
	// ScopeID is required for a kind scoped by another (a character's series).
	ScopeID    EntityID       `json:"scope_id,omitempty"`
	ParentID   EntityID       `json:"parent_id,omitempty"`
	Attributes map[string]any `json:"attributes,omitempty"`
	Cover      *Cover         `json:"cover,omitempty"`
	Avatar     *Avatar        `json:"avatar,omitempty"`
	// OwnerUserID owns a user-owned entity; a person creating one owns it.
	OwnerUserID string `json:"owner_user_id,omitempty"`
	// AuthScope is staff's (an import's); ContentKit provisions it otherwise.
	AuthScope string `json:"auth_scope,omitempty"`
	Names     []Name `json:"names,omitempty"`
	Text      []Text `json:"text,omitempty"`
}

type EntityNames struct {
	ID    EntityID `json:"id"`
	Names []Name   `json:"names"`
}

type EntityPage struct {
	Entities []EntityCard `json:"entities"`
	// NextCursor pages on; empty on the last page.
	NextCursor string `json:"next_cursor,omitempty"`
	// Total is every matching entity, on numbered pages only.
	Total *int `json:"total,omitempty"`
}

type EntityUpdate struct {
	// ID names the entity; routes take it from the path.
	ID       EntityID  `json:"-"`
	Slug     *string   `json:"slug,omitempty"`
	Internal *bool     `json:"internal,omitempty"`
	ScopeID  *EntityID `json:"scope_id,omitempty"`
	// ParentID "" detaches the entity from its parent.
	ParentID *EntityID `json:"parent_id,omitempty"`
	// State restores (active) or deletes an entity.
	State *State `json:"state,omitempty"`
	// Attributes replaces every attribute.
	Attributes map[string]any `json:"attributes,omitempty"`
	// Cover selects a cover; an empty one returns to the automatic cover.
	Cover *Cover `json:"cover,omitempty"`
	// Avatar selects the entity's avatar (kinds with avatars); an empty one returns to
	// the first.
	Avatar      *Avatar `json:"avatar,omitempty"`
	OwnerUserID *string `json:"owner_user_id,omitempty"`
	AuthScope   *string `json:"auth_scope,omitempty"`
	// Names replaces every name and alias.
	Names []Name `json:"names,omitempty"`
	// Text replaces the text of every language.
	Text []Text `json:"text,omitempty"`
}

type Folders interface {
	ExposeTx(ctx context.Context, tx pgx.Tx, entities []Ref) error
	DeleteTx(ctx context.Context, tx pgx.Tx, entities []Ref) error
}

type ImportEntity struct {
	ID   EntityID
	Kind string
	Slug string
	// Internal preserves the stored classification when omitted.
	Internal    *bool
	ScopeID     EntityID
	ParentID    EntityID
	State       State
	Attributes  map[string]any
	Cover       *Cover
	Avatar      *Avatar
	OwnerUserID string
	// AuthScope names the entity's AuthKit scope; empty keeps the stored one.
	AuthScope string
	Names     []Name
	Text      []Text
	// Edges are the entity's edges to others (From is the entity).
	Edges     []Edge
	Code      string
	CreatedAt *time.Time
	UpdatedAt *time.Time
}

type ListOptions struct {
	Kind string
	// Query matches a name, alias or slug for management selectors.
	Query string
	// IncludeInternal is a trusted management read; As stores require staff.
	IncludeInternal bool
	// Deleted lists deleted entities instead of active ones; with IncludeInternal only.
	Deleted bool
	// Parent keeps the children of one entity (sub-series of a series).
	Parent EntityID
	// Scope keeps the entities scoped by one entity (characters of a series).
	Scope EntityID
	Slug  string
	// Letter keeps entities whose sort name starts with it (a-z), or with
	// anything else ("#").
	Letter string
	// Language resolves names, sort keys and slugs, scopes counts and
	// prefixes paths. Empty: names and paths in the first configured
	// language, counts over every language.
	Language string
	// ContentKind scopes counts to one content kind; empty sums them.
	ContentKind string
	Sort        Sort
	// Cursor is the previous page's NextCursor under the same Sort.
	Cursor string
	// Page numbers pages from 1 instead of Cursor; the page then carries Total.
	Page int
	// Limit defaults to 50 and is capped at 200.
	Limit int
}

type LocalScopes interface {
	HoldingScopes(ctx context.Context, user string, kinds, scopeIDs []string) (map[string][]string, error)
}

type MemberOptions struct {
	// Cursor is the previous page's NextCursor.
	Cursor string
	// Limit defaults to 50 and is capped at 500.
	Limit int
}

type MemberPage struct {
	Members []Membership `json:"members"`
	// NextCursor pages on; empty on the last page.
	NextCursor string `json:"next_cursor,omitempty"`
}

type MemberRef struct {
	ContentID string `json:"content_id"`
	VersionID string `json:"version_id,omitempty"`
}

type Membership struct {
	EntityID    EntityID        `json:"group_id,omitempty"`
	ContentID   string          `json:"content_id,omitempty"`
	VersionID   string          `json:"version_id,omitempty"`
	Role        string          `json:"role,omitempty"`
	Position    *int            `json:"position,omitempty"`
	ActiveFrom  *time.Time      `json:"active_from,omitempty"`
	ActiveUntil *time.Time      `json:"active_until,omitempty"`
	State       MembershipState `json:"state,omitempty"`
}

type MembershipState string

type Merge struct {
	From EntityID `json:"from"`
	Into EntityID `json:"into"`
}

type MergeInput struct {
	Into EntityID `json:"into"`
}

type MergeReport struct {
	From             EntityID `json:"from"`
	Into             EntityID `json:"into"`
	MembershipsMoved int64    `json:"memberships_moved"`
	NamesMoved       int64    `json:"names_moved"`
	EdgesMoved       int64    `json:"edges_moved"`
	EntitiesMoved    int64    `json:"groups_moved"`
}

type MyEntity struct {
	EntityCard
	// Owner: the viewer owns it.
	Owner bool `json:"owner"`
	// Editor: the viewer holds its kind's access.EntitySettingsManage in its
	// AuthKit scope.
	Editor bool `json:"editor"`
	// Writer: the viewer holds its kind's access.EntityContentWrite there.
	Writer bool `json:"writer"`
	// Moderator: the viewer holds its kind's access.EntityCommentsModerate
	// there, or owns it.
	Moderator bool `json:"moderator"`
	// Member: the viewer holds its key.
	Member bool `json:"member"`
}

type MyEntityPage struct {
	Entities   []MyEntity `json:"entities"`
	NextCursor string     `json:"next_cursor,omitempty"`
}

type Name struct {
	Language string   `json:"language"`
	Kind     NameKind `json:"kind"`
	Name     string   `json:"name"`
}

type NameKind string

type NewEntity struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
	// Language of a created entity's canonical name; the catalog's first by default.
	Language string `json:"language,omitempty"`
}

type Options struct {
	Pool   *pgxpool.Pool
	Schema string
	Tenant string
	// Kinds is the site's content model; its EntityKinds govern every write.
	Kinds kinds.Config
	// ContentChanged runs whenever the effective entities of contents may have
	// changed (their facets' entity_ids are already re-derived), so the engine
	// can rebuild what else depends on them, such as search documents: in the
	// writing transaction, or for a large reach in the refresh job's batch
	// transactions. Optional.
	ContentChanged func(ctx context.Context, q Querier, contentIDs []string) error
	// NamesChanged runs in the writing transaction after the names or slugs
	// of entities changed, so the engine can requeue the documents of content
	// that shows them, such as search documents keyed by entity names. Their
	// facets are unchanged; it must not lock content. Optional.
	NamesChanged func(ctx context.Context, q Querier, entityIDs []string) error
	// DocumentsChanged runs in the writing transaction after a write queued
	// search documents, so the engine can sync them at once. Optional.
	DocumentsChanged func(ctx context.Context, q Querier) error
	// References preserves host-owned links when an entity is merged or made
	// unavailable. Nil means no host-owned references are registered.
	References References
	// Covers fills covers' and avatars' renditions on reads. Optional.
	Covers CoverResolver
	// Sales fills sellable entities' offers and the viewer's standing on
	// reads: offers.Service. Optional.
	Sales Sales
	// Scopes provisions and retires the AuthKit scopes of auth_scope kinds,
	// and lists a person's. Optional: without it auth_scope is whatever staff
	// set.
	Scopes Scopes
	// Folders hides a deleted entity's media and shows it again on restore,
	// in the writing transaction, and purges a user-owned entity's once it
	// stayed deleted for DeletedRetention: media/versions.Service.EntityFolders.
	// Optional.
	Folders Folders
	// DeletedRetention is how long a deleted user-owned entity keeps its media
	// for a restore; zero is DefaultDeletedRetention.
	DeletedRetention time.Duration
	// Owned deletes the content a deleted user-owned entity owns
	// (owner_entity) and restores it with the entity: the catalog. Optional.
	Owned OwnedContent
	// Queue is the River queue of entity syncs; contentkit_groups when empty.
	Queue string
	// Logger receives the HTTP API's failures. nil -> slog.Default().
	Logger *slog.Logger
}

type Order struct {
	// EntityID names the entity; routes take it from the path.
	EntityID EntityID    `json:"-"`
	Members  []MemberRef `json:"members"`
}

type OwnedContent interface {
	// DeleteOwned deletes the live content of the deleted ones among entities,
	// recording each entity as its content's cause; bought content stays
	// readable to its buyers.
	DeleteOwned(ctx context.Context, entities []string) error
	// RestoreOwned restores the content the active ones among entities
	// deleted when they were, unless it was purged since; content deleted
	// for another reason stays deleted.
	RestoreOwned(ctx context.Context, entities []string) error
}

type Querier interface {
	Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
}

type Ref struct {
	Kind string
	ID   EntityID
}

type References interface {
	// CheckUnavailable rejects deletion or public-to-internal reclassification
	// while host links still require the entities. Return ErrConflict to refuse.
	CheckUnavailable(ctx context.Context, q Querier, tenant string, refs []Ref) error
	// Merge moves From's host links to Into, collapsing duplicate pairs.
	Merge(ctx context.Context, q Querier, tenant string, from, into Ref) error
}

type Rendition struct {
	URL string `json:"url"`
	W   int    `json:"w"`
	H   int    `json:"h"`
}

type Sales interface {
	EntityAccess(ctx context.Context, viewer access.Actor, entities []string) ([]offers.EntityAccess, error)
	Joined(ctx context.Context, viewer access.Actor) ([]string, error)
	Current(ctx context.Context, a auth.Authenticator, actor access.Actor, targets []offers.Target) ([]*offers.Offer, error)
	Resync(ctx context.Context, tx pgx.Tx, targets []offers.Target) error
}

type Scope struct {
	ID    string
	Kind  string
	Owner string
}

type Scopes interface {
	// Provision makes each scope a live AuthKit group of its kind's persona,
	// seeded with Owner as its owner when new; a scope retired before is
	// replaced by a new entity under the same id.
	Provision(ctx context.Context, scopes []Scope) error
	// Retire stops each scope resolving and granting.
	Retire(ctx context.Context, ids []string) error
	// Holding answers, per live scope of the kinds' personas user belongs
	// to, the kind's access.EntityPermissions user holds there.
	Holding(ctx context.Context, user string, kinds []string) (map[string][]string, error)
}

type Sort string

type State string

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

type Text struct {
	Language    string `json:"language"`
	Description string `json:"description,omitempty"`
	SortKey     string `json:"sort_key,omitempty"`
}

type Written struct {
	Count int `json:"count"`
}