taxonomy

type AssignOptions struct {
	// SuppressCounts skips the per-node recount (bulk loads); run
	// RebuildCounts afterwards.
	SuppressCounts bool
}

type Assignment struct {
	contentref.ContentRef
	TaxonomyID     TaxonomyID      `json:"taxonomy_id"`
	Relation       string          `json:"relation"`
	State          AssignmentState `json:"state,omitempty"`
	SourceRevision int64           `json:"source_revision"`
}

type AssignmentState string

type BrowseHit struct {
	contentref.ContentRef
	Language string `json:"language"`
	Priority int32  `json:"priority"`
}

type BrowseOptions struct {
	ContentKind string
	Language    string
	RequireAll  []TaxonomyID
	// Eligibility is the request's host join (see search.Eligibility).
	// Reserved arg names: tenant, kind, language, limit, offset, taxonomy_ids.
	Eligibility *search.Eligibility
	// Limit defaults to 50 and is capped at search.MaxCandidateLimit.
	Limit  int
	Offset int
}

type BrowsePage struct {
	Hits    []BrowseHit `json:"hits"`
	HasMore bool        `json:"has_more"`
}

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

type Edge struct {
	From           TaxonomyID `json:"from_taxonomy_id"`
	Relation       Relation   `json:"relation"`
	To             TaxonomyID `json:"to_taxonomy_id"`
	SourceRevision int64      `json:"source_revision"`
}

type EffectiveTag struct {
	TaxonomyID TaxonomyID `json:"taxonomy_id"`
	Kind       string     `json:"kind"`
	Slug       string     `json:"slug"`
	Relation   string     `json:"relation"`
	Scope      Scope      `json:"scope"`
}

type EffectiveTagsOf struct {
	Content contentref.ContentRef `json:"content"`
	Tags    []EffectiveTag        `json:"tags"`
}

type LanguageMode string

type ListOptions struct {
	// Kind selects one registered node kind; empty lists every kind.
	Kind string
	// States lists nodes in any of these states; empty means active only.
	States []State
	// IDs selects exactly these nodes; empty does not filter.
	IDs []TaxonomyID
	// Slug selects one slug exactly.
	Slug string
	// Related keeps nodes with an edge pointing at this node; with Relation,
	// only that relation. The characters of a series are
	// {Related: seriesID, Relation: RelationMemberOf}.
	Related TaxonomyID
	// Relation narrows Related; empty accepts any relation.
	Relation Relation

	// Language resolves NodeRow.Name and scopes the counts Count, MinCount and
	// SortCount read. Empty uses the store's first configured language.
	Language string
	// LanguageMode decides the display name when the node has none in Language.
	LanguageMode LanguageMode
	// NamePrefix keeps nodes whose display name starts with it: the A-Z index.
	// Matched normalized, so "e" also matches "Étude".
	NamePrefix string
	// Query keeps nodes with a name or alias containing it, in any language.
	// Matched normalized; % and _ are literal.
	Query string
	// ContentKind scopes the count to one host content kind; empty sums them.
	ContentKind string
	// MinCount keeps nodes whose Count is at least this. 1 hides empty nodes.
	MinCount int

	// FilterSQL is trusted host SQL appended as AND (<FilterSQL>) against
	// node alias n. Use it for host-owned sidecar policy, never request SQL.
	// FilterArgs binds pgx @name placeholders. Library parameter names are
	// reserved even when their corresponding option is unset.
	FilterSQL  string
	FilterArgs map[string]any

	// OrderSQL is a trusted host ORDER BY expression for host-owned directory
	// ordering, such as phonetic names stored in a sidecar. It excludes Sort
	// and Cursor; use Offset. Node alias n is available, FilterArgs binds values,
	// and taxonomy_id is appended as a stable tiebreak. Never accept request SQL.
	OrderSQL string

	// Sort orders the page.
	Sort Sort

	// Cursor is the previous page's NextCursor. Keyset paging: it requires the
	// default Sort, excludes Offset, and skips the total — a full sync pages in
	// constant time instead of paying for a count per page.
	Cursor string
	// Offset pages from the start of the ordered result.
	Offset int
	// Limit defaults to 50 and is capped at 500.
	Limit int
}

type MergeReport struct {
	From              TaxonomyID `json:"from_taxonomy_id"`
	Into              TaxonomyID `json:"into_taxonomy_id"`
	AssignmentsMoved  int64      `json:"assignments_moved"`
	NamesMoved        int64      `json:"names_moved"`
	EdgesRewritten    int64      `json:"edges_rewritten"`
	AssignmentsMerged int64      `json:"assignments_merged"`
}

type Name struct {
	Language       string   `json:"language"`
	Kind           NameKind `json:"kind"`
	Name           string   `json:"name"`
	Normalized     string   `json:"normalized,omitempty"`
	SourceRevision int64    `json:"source_revision"`
}

type NameKind string

type Node struct {
	TaxonomyID     TaxonomyID `json:"taxonomy_id"`
	TenantID       string     `json:"tenant_id"`
	Kind           string     `json:"kind"`
	Slug           string     `json:"slug"`
	State          State      `json:"state"`
	SourceRevision int64      `json:"source_revision"`
	CreatedAt      time.Time  `json:"created_at"`
	UpdatedAt      time.Time  `json:"updated_at"`
}

type NodeDetail struct {
	Node
	Names  []Name  `json:"names"`
	Edges  []Edge  `json:"edges"`
	Counts []Count `json:"counts"`
}

type NodeInput struct {
	// TaxonomyID is optional; omitted ids are generated.
	TaxonomyID     TaxonomyID `json:"taxonomy_id,omitempty"`
	Kind           string     `json:"kind"`
	Slug           string     `json:"slug"`
	Names          []Name     `json:"names,omitempty"`
	SourceRevision int64      `json:"source_revision"`
}

type NodePage struct {
	Nodes []NodeRow `json:"nodes"`
	// NextCursor pages the default Sort; empty on the last page and under any
	// other order.
	NextCursor string `json:"next_cursor,omitempty"`
	// Total is the unpaged match count, zero on a Cursor page.
	Total int `json:"total"`
}

type NodeRow struct {
	Node
	// Name is the canonical name resolved for ListOptions.Language, empty when
	// the node has none (see LanguageMode).
	Name string `json:"name,omitempty"`
	// NameLanguage is the language Name came from.
	NameLanguage string `json:"name_language,omitempty"`
	// Count is the number of distinct works of ContentKind with an eligible
	// document in Language whose effective assignments include the node.
	Count int `json:"count"`
}

type NodeUpdate struct {
	Slug           *string `json:"slug,omitempty"`
	State          *State  `json:"state,omitempty"`
	SourceRevision *int64  `json:"source_revision,omitempty"`
}

type Options struct {
	Pool   *pgxpool.Pool
	Schema string
	Tenant string
	// Kinds are the node kinds this tenant registers (tag, artist, creator,
	// character, series, season, voice_actor, listing, ...). Required; a kind
	// must never collide with a host content kind.
	Kinds []string
	// Languages are the document languages typeahead documents are built in
	// (one document per node and language). Required.
	Languages []string
	// CountEligibility is the host's public visibility join used to derive
	// counts (see search.Eligibility). Without it every document counts.
	// Reserved arg names: tenant, ids, taxonomy_kinds.
	CountEligibility *search.Eligibility
	// Logger receives the admin API access log: each request at DEBUG, a 5xx
	// at ERROR, both with the cause the response withheld. nil -> slog.Default().
	Logger *slog.Logger
}

type Relation string

type Scope string

type Sort string

type State string

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

type TaxonomyID = contentref.TaxonomyID