discovery

type Activity struct {
	Days []ActivityDay `json:"days"`
	// Cohorts lists application-defined category IDs in matching priority order.
	Cohorts []string `json:"cohorts"`
}

type ActivityContext struct {
	ActivityTarget
	Token      string    `json:"token"`
	OccurredAt time.Time `json:"occurred_at"`
}

type ActivityContexts struct {
	Enabled  bool              `json:"enabled"`
	Contexts []ActivityContext `json:"contexts"`
}

type ActivityContextsInput struct {
	Session  string           `json:"session,omitempty"`
	Language string           `json:"language,omitempty"`
	Targets  []ActivityTarget `json:"targets"`
}

type ActivityDay struct {
	Date     string            `json:"date"`
	Readers  uint64            `json:"readers"`
	Cohorts  map[string]uint64 `json:"cohorts"`
	ActiveMS uint64            `json:"active_ms"`
}

type ActivitySigner interface {
	SignTicket(scope string, expires time.Time) string
	VerifyTicket(ticket, scope string) error
}

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

type Admit func(ctx context.Context, refs []contentref.ContentRef) (map[contentref.ContentKey]bool, error)

type Backfill func(ctx context.Context, kind string, exclude []string, limit int) ([]contentref.ContentRef, error)

type Card struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
	// Code and Path are its page, /{lang}/{route}/{code}/{slug}, which opens
	// the card's version: with ?v= when that is not the page's default.
	Code string `json:"code"`
	Path string `json:"path"`
	// Title is in Language: the display language, else a fallback.
	Title    string                  `json:"title"`
	Language string                  `json:"language"`
	Cover    []media.PublicRendition `json:"cover"`
	Version  CardVersion             `json:"version"`
	// Entities are the version's effective entities with a page, by entity kind.
	Entities map[string][]Chip `json:"entities"`
	// Channel is the original authoring home; reposts do not replace it.
	Channel     *channels.Card       `json:"channel,omitempty"`
	Repost      *channels.Repost     `json:"repost,omitempty"`
	Counts      Counts               `json:"counts"`
	Access      CardAccess           `json:"access"`
	Viewer      *catalog.ViewerState `json:"viewer,omitempty"`
	PublishedAt *time.Time           `json:"published_at,omitempty"`
	Attributes  map[string]any       `json:"attributes"`
	// UpdatedAt is when the work last gained something after this card's
	// version was published: a newer version, or pages added to this one
	// (new chapters); absent until then.
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
	// Deleted marks a deleted item or version for staff and its creators.
	Deleted bool `json:"deleted,omitempty"`
	// Excerpt is a post kind's plain-text summary, about 300 characters: its
	// description, else its body's opening for readers who open it.
	Excerpt string `json:"excerpt,omitempty"`
}

type CardAccess struct {
	Allowed bool `json:"allowed"`
	// Level and Tiers are the version's effective rule, the same for every
	// reader (public once free): what a premium badge shows.
	Level access.Level `json:"level"`
	Tiers []string     `json:"tiers,omitempty"`
	// Unknown: entitlements could not be read; denied, nothing offered.
	Unknown bool `json:"unknown,omitempty"`
	// Sell are the keys whose purchase opens it; Requires is the key a buyer
	// holds first.
	Sell     []string         `json:"sell,omitempty"`
	Requires string           `json:"requires,omitempty"`
	Preview  *access.Preview  `json:"preview,omitempty"`
	Releases []access.Release `json:"releases,omitempty"`
}

type CardVersion struct {
	ID         string   `json:"id"`
	Code       string   `json:"code"`
	Languages  []string `json:"languages"`
	Traits     []string `json:"traits"`
	Label      string   `json:"label,omitempty"`
	Pages      *int     `json:"pages,omitempty"`
	DurationMS *int64   `json:"duration_ms,omitempty"`
	HasAudio   bool     `json:"has_audio"`
	// HLS is the folder of its ladder (a read's hls entry) once its video is
	// in, for a reader who opens it: the card previews it inline.
	HLS string `json:"hls,omitempty"`
}

type Chip struct {
	ID       string `json:"id"`
	Slug     string `json:"slug"`
	Name     string `json:"name"`
	Path     string `json:"path,omitempty"`
	Position *int   `json:"position,omitempty"`
}

type ContentFilterState struct {
	Entity         entities.EntityCard `json:"entity"`
	DefaultVisible bool                `json:"default_visible"`
	// Visible is the reader's setting, Overridden whether it is their own.
	Visible    bool `json:"visible"`
	Overridden bool `json:"overridden"`
}

type ContentFilters struct {
	AppliesTo []string             `json:"applies_to"`
	Filters   []ContentFilterState `json:"filters"`
}

type ContentFiltersInitialization struct {
	AccountID string               `json:"account_id"`
	Filters   []GuestFilterSetting `json:"filters"`
}

type ContentFiltersUpdate struct {
	Filters []GuestFilterSetting `json:"filters,omitempty"`
}

type ContentPage struct {
	Popularity *PopularitySnapshot `json:"popularity,omitempty"`
	Contents   []Card              `json:"contents"`
	Summary    *ListingSummary     `json:"summary,omitempty"`
	// NextCursor pages on; empty on the last page.
	NextCursor string `json:"next_cursor,omitempty"`
}

type Counts struct {
	Likes     *int `json:"likes,omitempty"`
	Dislikes  *int `json:"dislikes,omitempty"`
	Favorites *int `json:"favorites,omitempty"`
}

type DailyReleases struct {
	TimeZone    string       `json:"time_zone"`
	FromDate    string       `json:"from_date"`
	ThroughDate string       `json:"through_date"`
	Days        []ReleaseDay `json:"days"`
}

type DateCount struct {
	// Date is YYYY-MM-DD or YYYY-MM in the filter's time zone.
	Date string `json:"date"`
	// Count is the contents released then; Free those open to anyone.
	Count int `json:"count"`
	Free  int `json:"free"`
}

type EngagementBatch struct {
	Session   string               `json:"session,omitempty"`
	Snapshots []EngagementSnapshot `json:"snapshots"`
}

type EngagementSnapshot struct {
	ContentID     string           `json:"content_id"`
	VersionID     string           `json:"version_id,omitempty"`
	VisitID       string           `json:"visit_id"`
	OriginClickID string           `json:"origin_click_id,omitempty"`
	SegmentID     string           `json:"segment_id"`
	Revision      uint64           `json:"revision"`
	ActivityToken string           `json:"activity_token"`
	ActiveMS      uint32           `json:"active_ms"`
	Resume        string           `json:"resume,omitempty"`
	Pages         []PageEngagement `json:"pages,omitempty"`
	Watched       []WatchedRange   `json:"watched,omitempty"`
}

type ExposureInput struct {
	// RenderID is stable per render and shared with its clicks.
	RenderID string `json:"render_id"`
	// Stage is served, rendered or visible.
	Stage    string `json:"stage"`
	Revision uint64 `json:"revision,omitempty"`
	QueryID  string `json:"query_id,omitempty"`
	// SearchQuery is normalized like recent search history, at most 200 runes.
	SearchQuery string `json:"search_query,omitempty"`
	Surface     string `json:"surface,omitempty"`
	Ranker      string `json:"ranker,omitempty"`
	Language    string `json:"language,omitempty"`
	// OccurredAt is the render's time; now by default.
	OccurredAt *time.Time  `json:"occurred_at,omitempty"`
	Shown      []Placement `json:"shown"`
}

type Exposures struct {
	Session   string          `json:"session,omitempty"`
	Exposures []ExposureInput `json:"exposures"`
}

type GuestFilterSetting struct {
	EntityID string `json:"entity_id"`
	Visible  *bool  `json:"visible,omitempty"`
	Default  *bool  `json:"default,omitempty"`
}

type HistoryOptions struct {
	Reader
	Kind string
	// Status is seen, in_progress or completed; anything they touched by
	// default.
	Status       string
	CardEntities []string
	Cursor       string
	Summary      bool
	// Limit defaults to 24 and is capped at 100.
	Limit int
}

type Hit struct {
	contentref.ContentRef
	Score float32
}

type ImportLegacyReading struct {
	ContentID   string
	VersionID   string
	Subject     signal.Subject
	FirstReadAt *time.Time
	LastReadAt  time.Time
	Progress    uint32
	ProgressMax uint32
	Completed   bool
	Resume      string
	Revision    uint64
}

type ImportSignal struct {
	ContentID  string
	VersionID  string
	Subject    signal.Subject
	Type       string
	EventID    string
	Revision   uint64
	OccurredAt time.Time
}

type Interaction struct {
	Channel *channels.Card `json:"channel,omitempty"`
	Content *Card          `json:"content,omitempty"`
	// Value is 1 for a favorite.
	Value int16 `json:"value"`
	// At is when the reader favorited or last reacted.
	At time.Time `json:"at"`
}

type InteractionPage struct {
	Items []Interaction `json:"items"`
	// NextCursor pages on; empty on the last page.
	NextCursor string          `json:"next_cursor,omitempty"`
	Summary    *ListingSummary `json:"summary,omitempty"`
}

type KnownCardsOptions struct {
	Reader
	IDs          []string
	Kind         string
	CardEntities []string
	Summary      bool
}

type LibraryItem struct {
	ContentID string `json:"content_id"`
	Kind      string `json:"kind"`
	Title     string `json:"title"`
	Language  string `json:"language,omitempty"`
	// Deleted marks a purchase whose content is deleted: it stays in the
	// buyer's library but is unreadable unless restored.
	Deleted bool `json:"deleted"`
	// Whole is always false: a gallery parent does not grant audience access.
	// VersionIDs lists only currently eligible, individually granted editions.
	Whole      bool     `json:"whole"`
	VersionIDs []string `json:"version_ids"`
}

type LibraryPage struct {
	Items      []LibraryItem `json:"items"`
	NextCursor string        `json:"next_cursor,omitempty"`
	// Complete is false when the viewer holds more keys than one billing read
	// returns (access.HeldLimit); the library lists those it read.
	Complete bool `json:"complete"`
}

type LibraryQuery struct {
	// Language picks the titles; the configured languages follow.
	Language string
	Cursor   string // the previous page's next_cursor
	Limit    int    // 20 by default, at most 100
}

type ListingSummary struct {
	FilteredCount    int                     `json:"filtered_count"`
	FilteredEntities []ReleaseFilteredEntity `json:"filtered_entities"`
	LockedCount      int                     `json:"locked_count"`
	// Total is the contents the list pages through under its access mode.
	Total int `json:"total"`
	// Truncated makes counts lower bounds for bounded keyword or recommendation
	// candidate windows. Ordinary lists have exact selection counts.
	Truncated bool `json:"truncated,omitempty"`
}

type ManagementCatalog interface {
	ManagementSearch(context.Context, access.Actor, catalog.ManagementSearchQuery) (catalog.ManagementNames, error)
}

type ManagementSuggestionsOptions struct {
	Actor                            access.Actor
	Query, DisplayLanguage           string
	ContentKinds, EntityKinds        []string
	IncludeContents, IncludeEntities bool
	Limit                            int
}

type Media interface {
	Covers(ctx context.Context, covers []versions.CoverOf) ([][]media.PublicRendition, error)
	Ladder(kind string) string
}

type MineOptions struct {
	Reader
	// Target is contents (the default) or channels.
	Target string
	// Kind is one content kind; every kind by default.
	Kind         string
	CardEntities []string
	Cursor       string
	// Limit defaults to 24 and is capped at 100.
	Limit int
	// Summary adds counts scoped to this reader's matching contents, before pagination.
	Summary bool
}

type MyStats struct {
	// Completed counts the contents they finished, per kind; empty without
	// a signal plane.
	Completed map[string]int64 `json:"completed"`
	// AccessSeconds is elapsed access to each configured tier, from billing's
	// recorded product windows and entitlement history. Overlaps count once;
	// future access does not count. Absent when history is unavailable.
	AccessSeconds map[string]int64 `json:"access_seconds,omitempty"`
	// Comments counts their published comments; CommentLikes and
	// CommentDislikes the reactions those received.
	Comments        int64 `json:"comments"`
	CommentLikes    int64 `json:"comment_likes"`
	CommentDislikes int64 `json:"comment_dislikes"`
}

type PageEngagement = signal.PageEngagement

type Placement struct {
	ContentID     string `json:"content_id"`
	Position      uint32 `json:"position"`
	VersionID     string `json:"version_id,omitempty"`
	ActivityToken string `json:"activity_token,omitempty"`
}

type PopularitySnapshot struct {
	Bucket string `json:"bucket"`
	Ready  bool   `json:"ready"`
	// WindowFrom/WindowUntil are the resolved bucket requested at preparation.
	WindowFrom  *time.Time `json:"window_from,omitempty"`
	WindowUntil *time.Time `json:"window_until,omitempty"`
	// From/Until are the covered whole UTC days actually ranked.
	From          *time.Time `json:"from,omitempty"`
	Until         *time.Time `json:"until,omitempty"`
	AvailableFrom *time.Time `json:"available_from,omitempty"`
	ComputedAt    *time.Time `json:"computed_at,omitempty"`
	// Provisional marks recent days still accepting measurements. Absence does
	// not certify that every older day has completed its final preparation.
	Provisional bool `json:"provisional,omitempty"`
}

type Reader struct {
	Actor access.Actor
	// Host is the request's host: it picks the site scope.
	Host string
	// Language lists only content with a live version serving it.
	Language string
	// DisplayLanguage is the language of titles and entity names and the
	// preferred language of each card's version; Language, else the site's
	// first.
	DisplayLanguage string
	// Mode is lock (the default) or hide.
	Mode access.Mode
}

type RecentSearch struct {
	Query string `json:"query"`
	// Results is how many cards its first page showed.
	Results    int       `json:"results"`
	SearchedAt time.Time `json:"searched_at"`
}

type RecentSearches struct {
	Searches []RecentSearch `json:"searches"`
}

type RecommendOptions struct {
	// ContentKinds are the candidate kinds to recommend. Required.
	ContentKinds []string

	// Limit caps results (default: Recommender.DefaultLimit).
	Limit int

	// SeedLimit is how many of the subject's highest-signal works inform
	// candidates (source default; Engagement: 5).
	SeedLimit int

	// SeedContentKinds limits which kinds may seed (default: any).
	SeedContentKinds []string

	// IncludeSeen keeps already-seen works in results (default: excluded).
	IncludeSeen bool

	// Popular fills cold or thin results from the kind's default prepared bucket.
	// Nil skips popularity fill.
	Popular func(ctx context.Context, kind string, limit int) ([]string, error)

	// Backfill fills what popularity leaves short, from works no signal
	// names; nil leaves the list short.
	Backfill Backfill

	// Admit keeps the works the reader may be shown; nil admits all.
	Admit Admit
}

type ReleaseDates struct {
	Dates      []DateCount `json:"dates"`
	NextCursor string      `json:"next_cursor,omitempty"`
}

type ReleaseDay struct {
	Date     string `json:"date"`
	Contents []Card `json:"contents"`
	// FilteredCount is the unique contents omitted only by optional entity
	// preferences, not by access or hard domain policy.
	FilteredCount int `json:"filtered_count"`
	// Counts overlap, so their sum is not FilteredCount. Hidden public filters
	// with no matches have count zero. Locked entity redaction still applies.
	FilteredEntities []ReleaseFilteredEntity `json:"filtered_entities"`
}

type ReleaseFilteredEntity struct {
	Entity entities.EntityCard `json:"entity"`
	Count  int                 `json:"count"`
}

type SearchPage struct {
	ContentPage
	Entities []entities.EntityCard `json:"entities,omitempty"`
}

type SignalInput struct {
	ContentID string `json:"content_id"`
	VersionID string `json:"version_id,omitempty"`
	// Only click is accepted here. Measured reading has its own snapshot route.
	Type       string    `json:"type"`
	EventID    string    `json:"event_id"`
	Revision   uint64    `json:"revision,omitempty"`
	OccurredAt time.Time `json:"occurred_at"`
	// RenderID, Surface and Position attribute it to an exposure.
	RenderID string `json:"render_id,omitempty"`
	Surface  string `json:"surface,omitempty"`
	Position uint32 `json:"position,omitempty"`
	// ActivityToken is the server's immutable access snapshot from /activity-contexts.
	ActivityToken string `json:"activity_token,omitempty"`
}

type Signals struct {
	Session string        `json:"session,omitempty"`
	Signals []SignalInput `json:"signals"`
}

type SimilarOptions struct {
	Limit int
	// ContentKinds limits result kinds (default: any).
	ContentKinds []string
	// Window bounds the candidate evidence (default all time).
	Window signal.Window

	// ExcludeSeenFor drops works this subject has already seen (and always
	// drops works they negatively reacted to).
	ExcludeSeenFor *signal.Subject

	// Admit keeps the works the reader may be shown; nil admits all.
	Admit Admit
}

type SitemapAlias struct {
	Language string `json:"language"`
	Path     string `json:"path"`
	Image    string `json:"image,omitempty"`
}

type SitemapEntry struct {
	ID   string `json:"id"`
	Code string `json:"code"`
	// Path is the page in the first of the site's languages it serves;
	// Languages are its page in each, for hreflang alternates.
	Path      string         `json:"path"`
	LastMod   time.Time      `json:"lastmod"`
	Languages []SitemapAlias `json:"languages"`
}

type SitemapOptions struct {
	// Host picks the site scope.
	Host string
	Kind string
	// Cursor is the previous page's NextCursor.
	Cursor string
	// Limit defaults to 1000 and is capped at 10000.
	Limit int
}

type SitemapPage struct {
	Entries []SitemapEntry `json:"entries"`
	// NextCursor pages on; empty on the last page.
	NextCursor string `json:"next_cursor,omitempty"`
}

type Typeahead struct {
	Contents []Card                `json:"contents"`
	Entities []entities.EntityCard `json:"entities"`
}

type TypeaheadOptions struct {
	Reader
	Query string
	// Kind limits content suggestions to one kind.
	Kind string
	// EntityKinds are the entity kinds suggested; every kind with a page by
	// default.
	EntityKinds []string
	// Limit is per section: 8 by default, at most 20.
	Limit int
}

type WatchedRange = signal.WatchedRange