versions

type Anchor struct {
	ID              string   `json:"id"`
	Page            string   `json:"page"`
	OffsetPercent   float64  `json:"offset_percent"`
	DurationSeconds *float64 `json:"duration_seconds,omitempty"`
}

type Archive struct {
	Name string // the attachment's file name
	Type string // application/zip, or the configured single file's content type
	Size int64  // single-file size; ZIPs stream without a known size
	// contains filtered or unexported fields
}

type ArchiveRequest struct {
	Target
	Viewer, Account              string
	AccountSet                   bool
	Kind                         auth.SubjectKind
	Editor                       bool
	Claims                       []string
	Mark, Name, Revision, Ticket string
	Pages                        int  // exact authorized ZIP prefix; bound into the ticket
	File                         bool // the configured exact single-file download, never a caller-supplied path
}

type BackgroundCue struct {
	File       string  `json:"file"`
	FromPage   *string `json:"from_page,omitempty"`
	ToPage     *string `json:"to_page,omitempty"`
	FromAnchor *string `json:"from_anchor,omitempty"`
	ToAnchor   *string `json:"to_anchor,omitempty"`
	Loop       *bool   `json:"loop,omitempty"`
	Layer      *string `json:"layer,omitempty"`
}

type CoverOf struct {
	Kind      string
	ID        string
	Image     string
	ContentID string
	Version   string
	Language  string
	Preset    string
}

type DownloadDecision struct {
	Allowed bool
	// A refusal's stable code of the host's ("release_window") and, when it
	// is a matter of time, when the viewer may download.
	Reason      string
	AvailableAt *time.Time
	// Mark are the pages (from 1) of a page download to mark; files ignore it.
	Mark []int
	// Name is the download's file name without its extension; "" keeps
	// ContentKit's. ContentKit cleans and bounds it.
	Name string
}

type DownloadEntity struct {
	kinds.EntityRef
	Name       string
	Attributes map[string]any
}

type DownloadPolicy interface {
	// Decide rules on a download after the access check, before the quota.
	Decide(ctx context.Context, r DownloadRequest) (DownloadDecision, error)
	// Mark returns page's (from 1) marked bytes for actor and their
	// extension (".png"): a page Decide named.
	Mark(ctx context.Context, actor access.Actor, v Target, page int, b []byte) ([]byte, string, error)
}

type DownloadRequest struct {
	Actor  access.Actor
	Tiers  []string // the tiers Actor holds
	Editor bool     // Actor edits the version
	Target
	Kind string
	// Language is the version's language; Title is its title, in Language
	// when it has one there (its content's id when it has none).
	Language, Title string
	// Entities are the version's entities, its own and its content's.
	Entities []DownloadEntity
	// Rule is the version's effective access rule.
	Rule access.Rule
	// Released is when the version went live; zero while it is not.
	Released time.Time
	// Pages are a page download's pages; 0 for a file.
	Pages int
}

type Downloads struct {
	Anonymous []Quota     `json:"anonymous,omitempty" yaml:"anonymous"`
	User      []Quota     `json:"user,omitempty" yaml:"user"`
	Tiers     []TierQuota `json:"tiers,omitempty" yaml:"tiers"`
	// TTL is how long a file download's URL opens its file; 0 is DefaultDownloadTTL.
	TTL time.Duration `json:"ttl,omitempty" yaml:"ttl"`
	// Redis shares the counts across replicas; nil keeps them per process.
	Redis redis.UniversalClient `json:"-" yaml:"-"`
}

type Facets interface {
	RefreshTx(ctx context.Context, tx pgx.Tx, versions []string) error
}

type FileDownload struct {
	URL       string    `json:"url"`
	Name      string    `json:"name"`
	Type      string    `json:"type"`
	Size      int64     `json:"size,omitempty"`
	ExpiresAt time.Time `json:"expires_at"`
}

type ForegroundCue struct {
	File   string  `json:"file"`
	Page   *string `json:"page,omitempty"`
	Anchor *string `json:"anchor,omitempty"`
}

type Media struct {
	Manifests *media.Manifests
	Uploads   *media.Uploads
	Jobs      *media.Jobs
	Reader    *media.Reader // signs file downloads; nil serves none
}

type MediaPending struct {
	Target
	Reason string `json:"reason"`
}

type NoticePage struct {
	ID         string `json:"id"`
	SourceName string `json:"source_name"`
	Reason     string `json:"reason,omitempty"`
	From       int    `json:"from,omitempty"`
	To         int    `json:"to,omitempty"`
	PreviewURL string `json:"preview_url,omitempty"`
}

type Options struct {
	Tenant string // the content tables' tenant
	Schema string // ContentKit's schema
	Pool   *pgxpool.Pool
	Kinds  kinds.Config       // the site's content and entity kinds
	Auth   auth.Authenticator // the host's: staff and group scope checks
	// MediaConfigured requires Bind before a release can run. A service without
	// media still owns publication requests, completed access and deadlines.
	MediaConfigured bool
	// AccountExists verifies avatar targets in this tenant's account directory.
	// Scoped engines install it; nil preserves the legacy host contract.
	AccountExists func(context.Context, string) (bool, error)
	// Resolver decides versions ({kind, content, version}) for a viewer:
	// Visible (live, or edited by them), Accessible (opened by them) and
	// Editor.
	Resolver resolve.Resolver
	// Gate answers the tiers a viewer holds for download quotas; optional.
	Gate      *access.Gate
	Facets    Facets
	Others    Others         // nil refuses every other kind
	Policy    DownloadPolicy // the host's download policy; nil allows every download and marks none
	Downloads Downloads
	Logger    *slog.Logger
	Now       func() time.Time
}

type Others interface {
	resolve.Resolver
	media.UploadAuthorizer
}

type PageNotice struct {
	ID    string       `json:"id"`
	Kind  string       `json:"kind"` // removed | reordered
	Pages []NoticePage `json:"pages"`
}

type PageNotices struct {
	Notices []PageNotice `json:"notices"`
	Cookie  *http.Cookie `json:"-"`
}

type PageSpan struct {
	From int `json:"from"`
	To   int `json:"to"`
}

type Pending struct {
	Status string `json:"status"` // "pending"
}

type PlanPage struct {
	ID    string            `json:"id"` // original image SHA-256; the canonical page identity
	Name  string            `json:"name"`
	Span  *PageSpan         `json:"span,omitempty"`
	W     int               `json:"w"`
	H     int               `json:"h"`
	Files map[string]string `json:"files"`
}

type PlanPlayback struct {
	Item       media.RefBody `json:"item"`
	Tracks     []PlanTrack   `json:"tracks"`
	Inspection bool          `json:"inspection,omitempty"`
}

type PlanPreview struct {
	ID    string `json:"id"` // original image SHA-256
	Index int    `json:"index"`
	Name  string `json:"name"`
	URL   string `json:"url"`
	W     int    `json:"w"`
	H     int    `json:"h"`
}

type PlanSegment struct {
	Position   *int           `json:"position,omitempty"`
	Title      string         `json:"title,omitempty"`
	Start      int            `json:"start"`
	End        int            `json:"end"`
	Released   bool           `json:"released"`
	ReleaseAt  *time.Time     `json:"release_at,omitempty"`
	Locked     bool           `json:"locked"`
	Inspection bool           `json:"inspection,omitempty"` // authorized prepared derivatives; fetch with explicit management read
	Item       *media.RefBody `json:"item,omitempty"`       // read it at GET /media/{kind}/{id}
	Pages      []PlanPage     `json:"pages,omitempty"`
}

type PlanTrack struct {
	Name     string  `json:"name"`
	Path     string  `json:"path"`
	Duration float64 `json:"duration,omitempty"`
}

type Quota struct {
	Limit int           `json:"limit" yaml:"limit"`
	Per   time.Duration `json:"per" yaml:"per"`
}

type QuotaError struct {
	Bucket     string
	RetryAfter time.Duration
}

type ReaderDefaults struct {
	AutoAdvanceSeconds float64 `json:"auto_advance_seconds,omitempty"`
}

type ReaderMeta struct {
	SchemaVersion int             `json:"schema_version"` // 1
	Defaults      *ReaderDefaults `json:"defaults,omitempty"`
	Anchors       []Anchor        `json:"anchors,omitempty"`
	Background    []BackgroundCue `json:"background,omitempty"`
	Foreground    []ForegroundCue `json:"foreground,omitempty"`
}

type ReaderPlan struct {
	NextReleaseAt *time.Time    `json:"next_release_at,omitempty"`
	Content       string        `json:"content_id"`
	Version       string        `json:"version_id"`
	Publication   string        `json:"publication_id"`
	Pages         *int          `json:"pages,omitempty"`
	Segments      []PlanSegment `json:"segments"`
	Previews      []PlanPreview `json:"previews"`
	Playback      *PlanPlayback `json:"playback,omitempty"`
	Reader        *ReaderMeta   `json:"reader,omitempty"`
	Expires       int64         `json:"expires,omitempty"` // signed preview URL expiry, Unix seconds
}

type ReleaseRequest struct {
	ID string
	Target
	ScheduledAt time.Time
	State       string
	Current     bool
	Plan        json.RawMessage
	Result      json.RawMessage
	Error       string
	CompletedAt *time.Time
}

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

type Target struct {
	Content string `json:"content"`
	Version string `json:"version,omitempty"`
}

type TierQuota struct {
	Tier   string  `json:"tier" yaml:"tier"`
	Quotas []Quota `json:"quotas" yaml:"quotas"`
}

type UnavailableError struct {
	Reason      string
	AvailableAt *time.Time
}