discovery

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

type Candidate struct {
	Ref   contentref.ContentRef
	Score float64
}

type Candidates interface {
	Similar(ctx context.Context, anchor contentref.ContentRef, q Query) ([]Candidate, error)
	ForSubject(ctx context.Context, subject signal.Subject, q Query) ([]Candidate, error)
}

type Card 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"`
	// 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"`
	// Groups are the version's effective groups with a page, by group kind.
	Groups map[string][]Chip `json:"groups"`
	// Owner is the owner group's card (a channel's name, path, avatar and
	// cover).
	Owner       *groups.GroupCard `json:"owner,omitempty"`
	Counts      Counts            `json:"counts"`
	Access      CardAccess        `json:"access"`
	Viewer      *ViewerState      `json:"viewer,omitempty"`
	PublishedAt *time.Time        `json:"published_at,omitempty"`
	Attributes  map[string]any    `json:"attributes"`
}

type CardAccess struct {
	Allowed bool `json:"allowed"`
	// 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"`
	FreeAfter *time.Time      `json:"free_after,omitempty"`
	// Offers are the purchasable offers of Sell's keys; tiers are the host's
	// to label.
	Offers []offers.Sale `json:"offers,omitempty"`
}

type CardVersion struct {
	ID         string   `json:"id"`
	Languages  []string `json:"languages"`
	Traits     []string `json:"traits"`
	Label      string   `json:"label,omitempty"`
	Pages      *int     `json:"pages,omitempty"`
	DurationMS *int64   `json:"duration_ms,omitempty"`
}

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

type ContentFilterState struct {
	Group groups.GroupCard `json:"group"`
	// Label is the configured label in the requested language, else the
	// group's name.
	Label          string `json:"label"`
	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 {
	Filters []ContentFilterState `json:"filters"`
	// IncludeDeleted lists deleted content the reader holds.
	IncludeDeleted bool `json:"include_deleted"`
}

type ContentFiltersUpdate struct {
	Filters        []FilterSetting `json:"filters"`
	IncludeDeleted bool            `json:"include_deleted"`
}

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

type Counts struct {
	Likes     int   `json:"likes"`
	Dislikes  int   `json:"dislikes"`
	Favorites int   `json:"favorites"`
	Views     int64 `json:"views"`
}

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

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 Engagement struct {
	Store  *signal.Store
	Tenant string
	// RRFK is the seed fusion constant (default 60).
	RRFK int
}

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"`
	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 Fallback struct {
	Primary, Secondary Candidates
	OnError            func(error)
}

type Filter struct {
	Kind string
	// Groups are all required (effective on the card's version); a position
	// sort orders by the first.
	Groups        []string
	ExcludeGroups []string
	// Traits are all required on the card's version.
	Traits []string
	// Attributes are "name:value" equalities on Kind's declared filterable
	// attributes, all required.
	Attributes []string
	// ReleasedOn is a day (YYYY-MM-DD) or month (YYYY-MM) of publication in
	// TimeZone.
	ReleasedOn string
	// TimeZone is an IANA zone; UTC by default.
	TimeZone string
	// ViewStatus is unseen, in_progress or completed: the signed-in
	// reader's own.
	ViewStatus string
	// OwnerGroups keeps content one of these groups owns (a channel's feed);
	// owning is not membership and opens nothing.
	OwnerGroups []string
}

type FilterSetting struct {
	GroupID string `json:"group_id"`
	Visible bool   `json:"visible"`
}

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

type Hit struct {
	contentref.ContentRef
	Score float32
}

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

type Interaction struct {
	Content *Card             `json:"content,omitempty"`
	Group   *groups.GroupCard `json:"group,omitempty"`
	// Value is the reaction: 1 like, -1 dislike; 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"`
}

type ListOptions struct {
	Reader
	Filter
	// Sort is newest, oldest, title, popular[:period], top_rated[:period],
	// most_favorited, most_viewed, position or random; the kind's configured
	// sort, else newest, by default. Periods are popularity.Periods.
	Sort string
	// CardGroups are the group kinds cards name; every kind with a page by
	// default.
	CardGroups []string
	Cursor     string
	// Limit defaults to 24 and is capped at 100.
	Limit int
}

type MineOptions struct {
	Reader
	// Target is contents (the default) or groups.
	Target string
	// Kind is one content kind or group kind; every kind by default.
	Kind string
	// Value narrows reactions: like or dislike; both by default.
	Value      string
	CardGroups []string
	Cursor     string
	// Limit defaults to 24 and is capped at 100.
	Limit int
}

type Options struct {
	Pool   *pgxpool.Pool
	Schema string
	Tenant string
	Kinds  kinds.Config
	// Visibility is the catalog's visibility rule; every read applies it.
	Visibility Visibility
	// Resolver decides direct reads: the anchor of a similar list and the
	// content a signal names.
	Resolver resolve.Resolver
	// Gate decides each card's access.
	Gate *access.Gate
	// Groups names the groups on cards and in typeahead.
	Groups *groups.Store
	// Covers resolves cards' covers; nil leaves them out.
	Covers Covers
	// Sales fills cards' paywall offers; nil leaves them out.
	Sales Sales
	// Hub is the keyword search client and the signal plane. Without a
	// signal plane, history, signals, exposures, view_status, similar,
	// recommendations and popularity are unavailable.
	Hub *hub.Hub
	// Candidates sources similar and recommendations; nil is co-engagement
	// over the signal plane.
	Candidates Candidates
	// Policy ranks popular sorts; zero is popularity.PolicyV1.
	Policy popularity.Policy
	Logger *slog.Logger
	Now    func() time.Time
}

type Placement struct {
	ContentID string `json:"content_id"`
	Position  uint32 `json:"position"`
}

type Query struct {
	// ContentKinds limits candidate kinds (empty = any).
	ContentKinds []string
	// Limit is the number of results the caller returns after filtering.
	Limit int
	// Window bounds the evidence (zero = all time).
	Window signal.Window
	// SeedLimit and SeedContentKinds bound which of the subject's history
	// informs ForSubject (0 / empty = implementation default).
	SeedLimit        int
	SeedContentKinds []string
}

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 group 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

	// PopularWindow is the popularity window used to fill out results on
	// cold start or thin candidate sets (zero = all time, like every Window).
	PopularWindow signal.Window

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

type RecommendationOptions struct {
	Reader
	Filter
	CardGroups []string
	// Limit defaults to 12 and is capped at 50.
	Limit int
}

type Recommender struct {
	Candidates Candidates
	Store      *signal.Store
	Tenant     string
	// DefaultLimit applies when options leave Limit zero (default 20).
	DefaultLimit int
	// RRFK scales popularity-fill tail scores (default 60).
	RRFK int
}

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

type ReleaseDatesOptions struct {
	Reader
	Filter
	// By is month (the default) or day.
	By string
	// Cursor is the previous page's next_cursor: dates before it follow.
	Cursor string
	// Limit defaults to 60 and is capped at 1000.
	Limit int
}

type Sales interface {
	Sales(ctx context.Context, keys []string) (map[string]offers.Sale, error)
}

type SearchOptions struct {
	Reader
	Filter
	Query string
	// Sort is relevance (the default) or a list sort of the best matches.
	Sort       string
	CardGroups []string
	Cursor     string
	// Limit defaults to 24 and is capped at 100.
	Limit int
	// Unpersonalized ranks a signed-in reader's results as anyone's.
	Unpersonalized bool
}

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

type SignalInput struct {
	ContentID string `json:"content_id"`
	VersionID string `json:"version_id,omitempty"`
	// Type is view or click.
	Type string `json:"type"`
	// EventID is the client's stable identity of the event; retries reuse it.
	EventID string `json:"event_id"`
	// Revision orders cumulative snapshots of one view.
	Revision   uint64    `json:"revision,omitempty"`
	OccurredAt time.Time `json:"occurred_at"`
	DurationS  uint32    `json:"duration_s,omitempty"`
	// Progress is pages read (reader kinds), seconds watched (player kinds)
	// or percent scrolled (post kinds).
	Progress uint32 `json:"progress,omitempty"`
	Resume   string `json:"resume,omitempty"`
	// 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"`
}

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 Typeahead struct {
	Contents []Card             `json:"contents"`
	Groups   []groups.GroupCard `json:"groups"`
}

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

type ViewerState struct {
	Favorited bool `json:"favorited"`
	// Seen, Completed and Progress come from the signal plane.
	Seen        bool       `json:"seen"`
	Completed   bool       `json:"completed"`
	Progress    uint32     `json:"progress"`
	ProgressMax uint32     `json:"progress_max"`
	Resume      string     `json:"resume,omitempty"`
	LastViewAt  *time.Time `json:"last_view_at,omitempty"`
}

type Visibility interface {
	Viewer(ctx context.Context, o catalog.ViewerOptions) (*catalog.Viewer, error)
}