catalog

type AuthError struct{ Err error }

type BodyImageInput struct {
	Image   *string `json:"image"`
	Version string  `json:"version"`
}

type Content struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
	// Code and Path are its page: /{lang}/{route}/{code}/{slug}.
	Code string `json:"code"`
	Path string `json:"path"`
	// Language is the localized text language. Title may instead come from the
	// selected edition or OriginalTitle under the kind's title policy.
	Language string `json:"language"`
	Title    string `json:"title"`
	// OriginalTitle is the shared source-language title, independent of editions.
	// OriginalLanguage is optional: unknown source languages are never guessed.
	OriginalTitle    string `json:"original_title,omitempty"`
	OriginalLanguage string `json:"original_language,omitempty"`
	// Slug is Path's decorative tail in the page's language (entity and
	// title, "/"-joined); Slugs is it per language. Links built from them
	// equal Path.
	Slug        string            `json:"slug,omitempty"`
	Slugs       map[string]string `json:"slugs,omitempty"`
	Description string            `json:"description,omitempty"`
	// Body shows each inline image with a current public file as its URL;
	// only editors and viewers Decision allows get it. Description is the
	// teaser everyone reads.
	Body string `json:"body,omitempty"`
	// Decision is the viewer's access to the item: allowed when they open any
	// of its versions, else its first version's paywall.
	Decision Decision `json:"decision"`
	// Images maps each resolved image name of Body to its URL: the body
	// images of the edition the viewer opens (DefaultVersion among them).
	Images map[string]string `json:"images,omitempty"`
	// Cover is the cover of the edition the request's language opens by
	// default (DefaultVersion): what cards and meta tags show.
	Cover *Cover `json:"cover,omitempty"`
	State string `json:"state"`
	// Comments is open, closed or hidden.
	Comments      string         `json:"comments"`
	PublishAt     *time.Time     `json:"publish_at,omitempty"`
	PublishedAt   *time.Time     `json:"published_at,omitempty"`
	Live          bool           `json:"live"`
	Access        access.Rule    `json:"access"`
	Restrictions  []string       `json:"restrictions"`
	Attributes    map[string]any `json:"attributes"`
	OwnerEntityID string         `json:"owner_group_id,omitempty"`
	// Owner is the owner entity's card (a channel's name, path, avatar and
	// cover) while it is active.
	Owner    *entities.EntityCard `json:"owner,omitempty"`
	Creators []Creator            `json:"creators"`
	// Entities are shared/null-version memberships. Version-specific entities
	// are carried by each Version.Entities, never merged across editions here.
	Entities []EntitySummary `json:"entities"`
	Versions []Version       `json:"versions"`
	// SelectedVersionID is the edition selected for this response: the direct
	// version lookup's edition, or the default among the visible versions.
	SelectedVersionID string `json:"selected_version_id,omitempty"`
	// Viewer is the signed-in reader's standing with the item, to resume
	// it; each version carries its own.
	Viewer *ViewerState `json:"viewer,omitempty"`
	// Editor: the viewer may edit it; the fields below are theirs.
	Editor           bool            `json:"editor"`
	Text             map[string]Text `json:"text,omitempty"`
	Moderation       string          `json:"moderation,omitempty"`
	ModerationReason string          `json:"moderation_reason,omitempty"`
	EverSold         bool            `json:"ever_sold,omitempty"`
	// Offer is the item's current offer, for its offer editors.
	Offer     *offers.Offer `json:"offer,omitempty"`
	Revision  int64         `json:"revision"`
	CreatedAt time.Time     `json:"created_at"`
	UpdatedAt time.Time     `json:"updated_at"`
	DeletedAt *time.Time    `json:"deleted_at,omitempty"`
}

type ContentInput struct {
	Kind string `json:"kind"`
	// Text is the text per language.
	Text             map[string]Text `json:"text,omitempty"`
	OriginalTitle    string          `json:"original_title,omitempty"`
	OriginalLanguage string          `json:"original_language,omitempty"`
	// Comments is open (the default when permitted), closed (existing ones
	// show, new ones are refused) or hidden. A kind excluding open defaults to
	// its first configured comment mode.
	Comments string `json:"comments,omitempty"`
	// Access defaults to public when permitted, otherwise the kind's first
	// allowed level (and the first configured tier for tier access).
	Access       *access.Rule   `json:"access,omitempty"`
	Restrictions []string       `json:"restrictions,omitempty"`
	Attributes   map[string]any `json:"attributes,omitempty"`
	// OwnerEntityID is the home entity (a channel); its editors edit the item.
	// It never changes.
	OwnerEntityID string `json:"owner_group_id,omitempty"`
	// Creators nil credits the creating person as its author.
	Creators *[]Creator `json:"creators,omitempty"`
	// Versions: none gives the item one serving its text's languages (a
	// kind with hidden versions takes none).
	Versions []VersionInput `json:"versions,omitempty"`
}

type ContentPatch struct {
	OriginalTitle    *string        `json:"original_title,omitempty"`
	OriginalLanguage *string        `json:"original_language,omitempty"`
	Comments         *string        `json:"comments,omitempty"`
	Access           *access.Rule   `json:"access,omitempty"`
	Restrictions     *[]string      `json:"restrictions,omitempty"`
	Attributes       map[string]any `json:"attributes,omitempty"` // replaces all
	Creators         *[]Creator     `json:"creators,omitempty"`
	// Revision, when set, refuses the edit (409) unless it is current.
	Revision *int64 `json:"revision,omitempty"`
}

type Cover struct {
	Image      string                  `json:"image,omitempty"`
	URL        *string                 `json:"url,omitempty"`
	Renditions []media.PublicRendition `json:"renditions,omitempty"`
}

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

type Creator struct {
	UserID   string `json:"user_id"`
	Role     string `json:"role,omitempty"`
	Position int    `json:"position"`
}

type CreatorsInput struct {
	Creators []Creator `json:"creators"`
}

type Decision struct {
	Allowed bool `json:"allowed"`
	// Unknown: entitlements could not be read; denied, nothing offered.
	Unknown bool `json:"unknown,omitempty"`
	// Sell is the keys a paywall offers; Requires the key a buyer holds first.
	Sell     []string `json:"sell,omitempty"`
	Requires string   `json:"requires,omitempty"`
	// Preview is what a locked viewer still reads; Releases describe additional audiences.
	Preview  *access.Preview  `json:"preview,omitempty"`
	Releases []access.Release `json:"releases,omitempty"`
	// Offers are the purchasable offers of Sell's keys; tiers are the host's
	// to label.
	Offers []offers.Sale `json:"offers,omitempty"`
}

type Entities interface {
	EffectiveEntities(ctx context.Context, q entities.Querier, versionIDs []string) (map[string][]string, error)
	Cards(ctx context.Context, ids []entities.EntityID, o entities.CardOptions) ([]entities.EntityCard, error)
}

type EntitySummary struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
	Slug string `json:"slug"`
	Name string `json:"name"`
	Code string `json:"code,omitempty"`
	Path string `json:"path,omitempty"`
}

type Event struct {
	Type       string
	Kind       string
	ContentID  string
	VersionID  string
	OccurredAt time.Time
	Release    *access.Release
}

type EventPage struct {
	Events           []EventRecord `json:"events"`
	NextCursor       string        `json:"next_cursor"`
	HasMore          bool          `json:"has_more"`
	RetentionSeconds int64         `json:"retention_seconds"`
}

type EventQuery struct {
	After string
	Limit int
	Types []string
}

type EventRecord struct {
	ID         string          `json:"id"`
	Version    int             `json:"version"`
	Type       string          `json:"type"`
	Kind       string          `json:"kind"`
	ContentID  string          `json:"content_id"`
	VersionID  string          `json:"version_id,omitempty"`
	OccurredAt time.Time       `json:"occurred_at"`
	RecordedAt time.Time       `json:"recorded_at"`
	Source     string          `json:"source"`
	Scope      string          `json:"scope"`
	Data       json.RawMessage `json:"data,omitempty"`
}

type ImportContent struct {
	ID               string
	Kind             string
	State            string
	PublishAt        *time.Time
	PublishedAt      *time.Time
	DeletedAt        *time.Time
	OriginalTitle    *string
	OriginalLanguage *string
	// Comments is open (when empty), closed or hidden.
	Comments      string
	Access        *access.Rule
	Restrictions  []string
	Attributes    map[string]any
	OwnerEntityID string
	Creators      []Creator
	Text          map[string]Text
	Versions      []ImportVersion
	Code          string
	CreatedAt     *time.Time
	UpdatedAt     *time.Time
}

type ImportVersion struct {
	ID string
	// Code is the version code to keep; empty keeps the stored one or
	// assigns one. A version never changes its code.
	Code        string
	Languages   []string
	Traits      []string
	Label       string
	State       string
	PublishAt   *time.Time
	PublishedAt *time.Time
	DeletedAt   *time.Time
	Access      *access.Rule
	Attributes  map[string]any
	Ordinal     *int
	// Cover selects one of the version's cover uploads (i-{uuid}).
	Cover     string
	Text      map[string]VersionText
	Segments  []Segment
	CreatedAt *time.Time
	UpdatedAt *time.Time
}

type InlineImage struct {
	Ref string  `json:"ref"`
	URL *string `json:"url"`
}

type LanguageTotal struct {
	Public int64            `json:"public"`
	Tiers  map[string]int64 `json:"tiers"`
}

type ManageCount struct {
	Total int `json:"total"`
	// Truncated makes Total a lower bound.
	Truncated bool `json:"truncated,omitempty"`
}

type ManageQuery struct {
	Kind string
	// State is draft, scheduled, published (live) or deleted; "" is every
	// state but deleted.
	State       string
	OwnerEntity string
	// Text matches title, description or body, ignoring case.
	Text string
	// Code selects the item with this content code; with State "" it matches
	// deleted items too, so editor links keep resolving.
	Code string
	// IDs selects these items (at most MaxManageIDs); with State "" it
	// matches deleted items too, so member lists resolve every member.
	IDs []string
	// Access keeps items whose own rule has this level; Tier those whose rule
	// names this configured tier (implying the tier level).
	Access, Tier  string
	Limit, Offset int
}

type ManagementName struct{ ID, Kind, Title, Language string }

type ManagementNames struct {
	Contents []ManagementName
	Entities []entities.EntityCard
}

type ManagementSearchQuery struct {
	Query, Language                  string
	ContentKinds, EntityKinds        []string
	IncludeContents, IncludeEntities bool
	Limit                            int
}

type Media struct {
	// Registry constructs media references in each kind's effective namespace.
	// Nil retains the legacy standalone binding to the catalog key.
	Registry *media.Registry
	// Reader signs opened versions' body images and gives editors previews.
	Reader   Reader
	Versions VersionMedia // *versions.Service
}

type Moderation interface {
	Screen(ctx context.Context, in content.ModerationInput) (content.Screening, error)
}

type NotReadyError struct{ Pending []versions.MediaPending }

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

type Options struct {
	Pool   *pgxpool.Pool
	Schema string
	Tenant string
	// Kinds is the site's content model. Required.
	Kinds kinds.Config
	// Auth gates the routes and answers staff and owner-entity permissions.
	Auth auth.Authenticator
	// Gate answers viewers' entitlements; nil builds one without billing
	// (only free rules and claimed tiers open).
	Gate *access.Gate
	// Offers renames the products of content whose title changes and answers
	// paywalls' offers; nil when nothing is sold.
	Offers Offers
	// Entities answers effective entity ids for content_facets; nil: none. Wire
	// its Options.ContentChanged to Store.ContentChanged and its
	// Options.NamesChanged to Store.EntitiesRenamed.
	Entities Entities
	// Moderation screens text of content that is or goes live; nil approves
	// unless contentkit.NewRuntime binds its content runtime (BindModeration).
	Moderation Moderation
	// Body sanitizes text bodies; nil strips tags.
	Body Sanitizer
	// DeletedRetention: see DefaultDeletedRetention.
	DeletedRetention time.Duration
	// EventRetention keeps committed facts independently of reader progress. Zero is ninety days.
	EventRetention time.Duration
	// OnPurge records required application cleanup in the same transaction.
	OnPurge func(context.Context, pgx.Tx, []contentref.ContentRef) error
	// PlayableKinds are the kinds whose versions list only once their media
	// plays (an HLS rendition is out): a new version starts not playable until
	// media records otherwise. Only kinds media streams belong here.
	PlayableKinds []string
	// 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 clears host-owned edition links during permanent purge.
	References VersionReferenceOwner
	Now        func() time.Time
	Logger     *slog.Logger
}

type OrderInput struct {
	IDs []string `json:"ids"`
}

type Publish struct {
	ContentID string
	At        *time.Time
}

type PublishInput struct {
	PublishAt *time.Time `json:"publish_at,omitempty"`
}

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

type Reader interface {
	Read(ctx context.Context, ref contentref.ContentRef, actor access.Actor, o media.ReadOptions) (*media.ReadResult, error)
	// NamedURLs signs an opened item's named images that have no public files.
	NamedURLs(ctx context.Context, ref contentref.ContentRef, actor access.Actor, names []string) (map[string]string, error)
}

type Sanitizer = content.ContentProcessor

type Segment struct {
	Position  int        `json:"position"`
	Title     string     `json:"title,omitempty"`
	StartPage string     `json:"start_page,omitempty"`
	Start     int        `json:"start"`
	End       int        `json:"end"`
	ReleaseAt *time.Time `json:"release_at,omitempty"`
	// Released is computed on reads.
	Released bool `json:"released"`
}

type SegmentInput struct {
	Position  int        `json:"position,omitempty"`
	Title     string     `json:"title,omitempty"`
	StartPage string     `json:"start_page,omitempty"`
	Start     int        `json:"start,omitempty"`
	End       int        `json:"end,omitempty"`
	ReleaseAt *time.Time `json:"release_at,omitempty"`
	Released  bool       `json:"released,omitempty"` // ignored, retained for older clients
}

type SegmentsInput struct {
	Segments []SegmentInput `json:"segments"`
}

type Standing interface {
	Standing(ctx context.Context, actor access.Actor, refs []contentref.ContentRef) ([]ViewerState, error)
}

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

type Text struct {
	Title       string   `json:"title"`
	Slug        string   `json:"slug,omitempty"`
	Description string   `json:"description,omitempty"`
	Body        string   `json:"body,omitempty"`
	SortKey     string   `json:"sort_key,omitempty"`
	Aliases     []string `json:"aliases,omitempty"`
}

type TextPut struct {
	ContentID string
	Language  string
	Text      *Text
}

type Total struct {
	Public    int64                    `json:"public"`
	Tiers     map[string]int64         `json:"tiers"`
	Languages map[string]LanguageTotal `json:"languages"`
}

type Totals struct {
	Kinds map[string]Total `json:"kinds"`
}

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

type TotalsQuery struct {
	// Kinds are content kinds; empty means all of them.
	Kinds []string
	// Languages are the languages Total.Languages reports; empty means every
	// language with a counted item. Kind totals ignore it.
	Languages []string
	// Domain is the stable domain name whose scope applies; empty selects
	// main. The HTTP route takes it from the request's host.
	Domain string
}

type Update struct {
	ID string
	ContentPatch
}

type Version struct {
	ID string `json:"id"`
	// Code selects it on its content's page (?v=): unique within the content,
	// fixed for the version's life.
	Code      string   `json:"code"`
	Position  int      `json:"position"`
	Languages []string `json:"languages"`
	Traits    []string `json:"traits"`
	Label     string   `json:"label,omitempty"`
	// Title and Description are the override in the detail's language.
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	// State is the editors' to see.
	State       string     `json:"state,omitempty"`
	PublishAt   *time.Time `json:"publish_at,omitempty"`
	PublishedAt *time.Time `json:"published_at,omitempty"`
	// Live: published, past PublishAt, its content live.
	Live bool `json:"live"`
	// Access is the version's own rule; nil inherits the content's.
	Access     *access.Rule   `json:"access,omitempty"`
	Attributes map[string]any `json:"attributes"`
	// Entities are entities attached specifically to this version. Combine them
	// with Content.Entities when presenting the selected version's credits.
	Entities   []EntitySummary `json:"entities"`
	Pages      *int            `json:"pages,omitempty"`
	DurationMS *int64          `json:"duration_ms,omitempty"`
	Width      *int            `json:"width,omitempty"`
	Height     *int            `json:"height,omitempty"`
	HasAudio   bool            `json:"has_audio"`
	Ordinal    *int            `json:"ordinal,omitempty"`
	// Cover is absent when its kind's locked view hides it from the viewer.
	Cover    *Cover    `json:"cover,omitempty"`
	Segments []Segment `json:"segments"`
	Decision Decision  `json:"decision"`
	// Text is every language's override, for editors.
	Text map[string]VersionText `json:"text,omitempty"`
	// Offer is the version's current offer, for its offer editors.
	Offer *offers.Offer `json:"offer,omitempty"`
	// Viewer is the signed-in reader's standing with the version.
	Viewer *ViewerState `json:"viewer,omitempty"`
}

type VersionFork struct {
	From     string `json:"from"`
	Playback bool   `json:"playback,omitempty"`
	Segments bool   `json:"segments,omitempty"`
}

type VersionInput struct {
	Languages []string  `json:"languages,omitempty"`
	Traits    *[]string `json:"traits,omitempty"`
	Label     *string   `json:"label,omitempty"`
	// State is draft or published: a published version is live once its
	// content is and PublishAt passed. A version created with its item
	// defaults to published, one added later to draft.
	State     string     `json:"state,omitempty"`
	PublishAt *time.Time `json:"publish_at,omitempty"`
	// Access overrides the content's rule; ClearAccess inherits it again.
	Access      *access.Rule           `json:"access,omitempty"`
	ClearAccess bool                   `json:"clear_access,omitempty"`
	Attributes  map[string]any         `json:"attributes,omitempty"` // replaces all
	Text        map[string]VersionText `json:"text,omitempty"`       // replaces all
	Segments    *[]SegmentInput        `json:"segments,omitempty"`   // replaces all
	Ordinal     *int                   `json:"ordinal,omitempty"`
	// Cover selects one of the version's cover uploads by name (i-{uuid});
	// "" returns to its first.
	Cover *string `json:"cover,omitempty"`
	// Fork fills a new version's media from a sibling (creation only).
	Fork *VersionFork `json:"fork,omitempty"`
}

type VersionKey struct{ ContentID, VersionID string }

type VersionMedia interface {
	// Covers resolves versions' covers.
	Covers(ctx context.Context, covers []versions.CoverOf) ([][]media.PublicRendition, error)
	// CopyBodiesTx copies body images between a content's versions.
	CopyBodiesTx(ctx context.Context, tx pgx.Tx, copies []versions.BodyCopy) error
	// ExposeTx follows a visibility change.
	ExposeTx(ctx context.Context, tx pgx.Tx, targets []versions.Target) error
	// RepublishTx follows a change of a version's effective rule or segments.
	RepublishTx(ctx context.Context, tx pgx.Tx, versions []versions.Target) error
	// DeleteTx deletes media before the rows go.
	DeleteTx(ctx context.Context, tx pgx.Tx, targets []versions.Target) error
	// ForkTx fills new versions' media from siblings.
	ForkTx(ctx context.Context, tx pgx.Tx, forks []versions.Fork) error
	// PendingTx reports versions whose media is not ready to go live.
	PendingTx(ctx context.Context, tx pgx.Tx, targets []versions.Target) ([]versions.MediaPending, error)
}

type VersionPut struct {
	ContentID string
	VersionID string
	VersionInput
}

type VersionReferenceOwner interface {
	PurgeVersions(ctx context.Context, q Querier, catalog string, versionIDs []string) error
}

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

type VersionText struct {
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
}

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

type ViewerOptions struct {
	Actor access.Actor
	// Host is the request's host; it picks the site (kinds.Config.DomainFor).
	Host string
	// Language, when set, lists only content with a live version serving it.
	Language string
	// Mode defaults to access.Lock.
	Mode access.Mode
	// EditorEntities are owner entities (channels) whose editors see their whole
	// content in lists; the viewer's editorship of each is checked.
	EditorEntities []string
	// Requested are entities a list requires (an entity's page): the viewer's
	// content filters do not hide them, so the page shows what the entity's
	// count counts.
	Requested []string
}

type ViewerState struct {
	Favorited bool `json:"favorited"`
	// Reaction is their like (1) or dislike (-1) of the item; absent for neither.
	Reaction int `json:"reaction,omitempty"`
	// Seen, Completed, Progress, ProgressMax and Resume (the client's own
	// pointer, such as a page) come from the signal plane. Progress counts
	// whole pages for a reader and seconds for a player.
	Seen        bool       `json:"seen"`
	Completed   bool       `json:"completed"`
	Progress    uint32     `json:"progress"`
	ProgressMax uint32     `json:"progress_max"`
	Resume      string     `json:"resume,omitempty"`
	LastReadAt  *time.Time `json:"last_read_at,omitempty"`
}