content

type Action string

type ActorReaction struct {
	contentref.ContentRef
	Value     int16     `json:"value"` // -1 or 1 (neutral rows are excluded)
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type AdminComment struct {
	Comment
	contentref.ContentRef
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
}

type Anonymous struct {
	// Comments: comment and reply under a name (anon_name).
	Comments bool `json:"comments"`
	// Reactions: like and dislike works, posts and comments, keyed by IP.
	Reactions bool `json:"reactions"`
	// Votes: vote in multiple-choice polls, keyed by IP. Free-text answers
	// always need a signed-in actor.
	Votes bool `json:"votes"`
}

type Answer struct {
	Tenant     string
	QuestionID string
	AnswerID   string
	Revision   int64  // monotonic per answer; retries retain this revision
	SubjectID  string // opaque authenticated actor, never an IP
	Text       string
}

type AnswerClassifier interface {
	Classify(ctx context.Context, a Answer) (GroupAssignment, error)
}

type AuthorReactions struct {
	Likes    int64 `json:"likes"`
	Dislikes int64 `json:"dislikes"`
}

type Authorizer interface {
	Can(ctx context.Context, actor access.Actor, perm string) (bool, error)
}

type BanInput struct {
	Reason string     `json:"reason,omitempty"`
	Until  *time.Time `json:"until"`
}

type BanNotice struct {
	Scope  string     `json:"scope"`
	Reason string     `json:"reason,omitempty"`
	Until  *time.Time `json:"until,omitempty"`
}

type BanScope string

type BannedError struct{ BanNotice }

type BasicModerator struct {
	AllowLinks  bool          // default false: reject bodies containing URLs
	DupWindow   time.Duration // 0 = 30s; negative disables
	CensorWords []string      // nil = built-in set; empty = none; whole words, case-insensitive
	// contains filtered or unexported fields
}

type Chain []ContentModerator

type ClassificationPage struct {
	Classified int
	Next       string
}

type Comment struct {
	ID         string      `json:"id"`
	ReplyToID  string      `json:"reply_to_id,omitempty"`
	UserID     string      `json:"user_id,omitempty"`
	AnonName   string      `json:"anon_name,omitempty"`
	Body       string      `json:"body"`
	Deleted    bool        `json:"deleted"`
	Likes      int         `json:"likes"`
	Dislikes   int         `json:"dislikes"`
	Mine       int16       `json:"mine"` // caller's own reaction: -1/0/1
	ReplyCount int         `json:"reply_count"`
	Author     *PublicUser `json:"author,omitempty"`
	// Moderation is "held" or "rejected" on the author's own unpublished
	// comments (with the reason); absent on published ones.
	Moderation       string    `json:"moderation,omitempty"`
	ModerationReason string    `json:"moderation_reason,omitempty"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

type CommentBan struct {
	UserID   string      `json:"user_id"`
	User     *PublicUser `json:"user,omitempty"`
	Scope    string      `json:"scope"`
	Reason   string      `json:"reason,omitempty"`
	Until    *time.Time  `json:"until,omitempty"`
	BannedBy string      `json:"banned_by"`
	BannedAt time.Time   `json:"banned_at"`
	Expired  bool        `json:"expired"`
}

type CommentEdit struct {
	Body string `json:"body"`
}

type CommentInput struct {
	Body      string `json:"body"`
	ReplyToID string `json:"reply_to_id,omitempty"`
	AnonName  string `json:"anon_name,omitempty"`
}

type CommentStanding struct {
	// CanComment: the caller may comment now. A signed-out caller may only
	// where Anonymous says so.
	CanComment bool       `json:"can_comment"`
	Ban        *BanNotice `json:"ban,omitempty"`
	// Anonymous: signed-out visitors may comment here, under a name
	// (Options.Anonymous.Comments); otherwise they are asked to sign in.
	Anonymous bool `json:"anonymous"`
	// MaxLength is the longest comment, in characters (Options.CommentMaxLength).
	MaxLength int `json:"max_length"`
	// UserID is the caller's user id, absent when anonymous: the comments it
	// wrote are the ones it may edit and delete.
	UserID string `json:"user_id,omitempty"`
	// Moderate: the caller may edit, delete and restore anyone's comments
	// (Perms.CommentModerate).
	Moderate bool `json:"moderate"`
	// BanScopes are the scopes the caller may ban the target's commenters in.
	BanScopes []BanScope `json:"ban_scopes"`
}

type Config struct {
	Anonymous Anonymous `json:"anonymous"`
	// CommentMaxLength is the longest comment, in characters.
	CommentMaxLength int `json:"comment_max_length"`
}

type ContentCanonicalizer interface {
	Canonical(ref contentref.ContentRef) (contentref.ContentRef, bool)
}

type ContentCanonicalizerFunc func(ref contentref.ContentRef) (contentref.ContentRef, bool)

type ContentModerator interface {
	Screen(ctx context.Context, in ModerationInput) (Verdict, error)
}

type ContentProcessor interface {
	Sanitize(ctx context.Context, raw string) (string, error)
}

type Counts struct {
	Likes        int `json:"likes"`
	Dislikes     int `json:"dislikes"`
	Favorites    int `json:"favorites"`
	CommentCount int `json:"comment_count"`
}

type Decision string

type FavoriteItem struct {
	contentref.ContentRef
	CreatedAt time.Time `json:"created_at"`
}

type FavoriteState struct {
	Favorited bool `json:"favorited"`
	Count     int  `json:"count"`
}

type FeedItem struct {
	Comment
	contentref.ContentRef
}

type Group struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	Count int    `json:"count"`
}

type GroupAssignment struct {
	GroupID string
	Label   string
}

type HeldItem struct {
	Kind     string `json:"kind"`     // KindComment | KindPost
	Revision int64  `json:"revision"` // required when resolving this exact screened text
	ID       string `json:"id"`
	// Ref is the commented content, or the post's own reference.
	Ref           contentref.ContentRef `json:"ref"`
	AuthorID      string                `json:"author_id,omitempty"`
	Author        *PublicUser           `json:"author,omitempty"`
	AnonName      string                `json:"anon_name,omitempty"`
	Title         string                `json:"title,omitempty"`
	Body          string                `json:"body"`
	Reason        string                `json:"reason"`
	Model         string                `json:"model,omitempty"`
	PromptVersion string                `json:"prompt_version,omitempty"`
	Confidence    float64               `json:"confidence,omitempty"`
	Error         string                `json:"error,omitempty"` // moderator failure that forced the hold
	HeldAt        time.Time             `json:"held_at"`
	CreatedAt     time.Time             `json:"created_at"`
}

type HeldPage struct {
	Items []HeldItem `json:"items"`
	Next  string     `json:"next,omitempty"`
}

type Identity interface {
	Actor(ctx context.Context) (access.Actor, bool)
}

type ImageInput struct {
	Image *string `json:"image"`
}

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

type Limits struct {
	Comment         []Rate // default 5 per 5 minutes and 20 per hour
	CommentReaction []Rate // default 30 per minute
	PostReaction    []Rate // default 30 per minute
	Reaction        []Rate // default 30 per minute
	Favorite        []Rate // default 20 per minute
	PollVote        []Rate // default 30 per minute

	// Redis (or Garnet) shares the limits across replicas; pass the host's
	// client. Without it each process counts alone, so N replicas allow N
	// times the limit. Redis errors fall back to the per-process count.
	Redis     redis.UniversalClient
	KeyPrefix string // default "contentkit:content:rl:"; the tenant follows it
	// Disabled turns every limit off.
	Disabled bool
}

type Media struct {
	Images  MediaImages  // *media.Manifests
	Folders MediaFolders // *media.Jobs
	// Reader gives editors an unpublished post's image previews (POST
	// /posts/{id}/images); contentkit.NewRuntime fills it from its Reader.
	Reader   MediaReader
	PostKind string // media kind of post folders; default "post"
	PollKind string // media kind of poll folders; default "poll"
}

type MediaFolders interface {
	ExposeTx(ctx context.Context, tx pgx.Tx, refs ...contentref.ContentRef) error
	DeleteItemsTx(ctx context.Context, tx pgx.Tx, items ...media.Deletion) error
}

type MediaImages interface {
	Images(ctx context.Context, qs ...media.ImageQuery) ([][]media.PublicImage, error)
}

type MediaReader interface {
	Read(ctx context.Context, ref contentref.ContentRef, actor access.Actor, o media.ReadOptions) (*media.ReadResult, error)
}

type ModerationInput struct {
	SubjectID string // opaque content author; may differ from editing moderator
	Tenant    string
	Actor     access.Actor
	// Ref is the content the item belongs to: the commented work for a
	// comment, the post's own reference for a post.
	Ref    contentref.ContentRef
	Kind   string // KindComment | KindPost
	ItemID string // the existing item on an edit; empty on create
	Title  string // posts only
	Text   string
}

type Nullable[T any] struct {
	Set   bool
	Value *T
}

type Options struct {
	// Pool is the host's shared pgx pool; the runtime does not own its lifecycle.
	Pool *pgxpool.Pool
	// Schema is the host-selected schema holding all ContentKit tables.
	Schema string
	// Tenant scopes every row, index, cursor and result. Required.
	Tenant string

	// Mandatory ports.
	Identity Identity
	Authz    Authorizer
	Resolver access.ContentResolver

	// Canonicalizer enables the preference boundary (preferences.go): the
	// reaction/favorite row, the counts rollup and the export all use the
	// reference it returns. nil = no preference export.
	Canonicalizer ContentCanonicalizer
	// PreferenceSyncOverlap bounds how long a preference write may take to
	// commit and still be picked up by SyncPreferences.
	// Default DefaultPreferenceSyncOverlap.
	PreferenceSyncOverlap time.Duration

	// Optional ports (nil -> default).
	Users             UserEnricher     // default: no enrichment (ids only)
	Processor         ContentProcessor // comments and post excerpts; default: strip tags
	PostBodyProcessor ContentProcessor // post bodies; default: Processor
	// Moderator screens comment/post writes; nil publishes everything.
	// Compose a BasicModerator in front of an AI moderator with Chain.
	Moderator ContentModerator
	// ModeratorTimeout bounds one Screen call (default 5s); a slower
	// moderator counts as failed and the write is held.
	ModeratorTimeout time.Duration
	// ModeratorCooldown is how long writes are held without calling the
	// moderator after it failed repeatedly (default 30s); see CheckModerator.
	ModeratorCooldown time.Duration
	// Classifier groups free-text poll answers; nil refuses free-text polls.
	Classifier AnswerClassifier

	// Media stores post and poll images in ContentKit media; nil refuses
	// image writes with 501 not_configured. See Media.
	Media *Media

	// ProviderDataEraser is required when moderator/classifier ports retain
	// external personal data.
	// Nil explicitly means stateless ports; never remove it during an outage.
	ProviderDataEraser ProviderDataEraser

	// Perms are the opaque host permission strings gating privileged writes.
	Perms Perms

	// Limits are the per-actor interaction rate limits (limits.go); the zero
	// value takes the defaults, counted per process.
	Limits Limits

	// Anonymous is what signed-out visitors may do; the zero value lets them
	// only read.
	Anonymous Anonymous
	// CommentMaxLength is the longest comment in characters (runes);
	// default DefaultCommentMaxLength.
	CommentMaxLength int

	// ContentKinds are the commentable/reactable/favoritable kinds the host
	// registers (e.g. "gallery", "video", "post"). Unregistered kinds are 404.
	ContentKinds []string

	// Logger receives the access log: each request at DEBUG, a 500 at ERROR
	// with its cause. nil -> slog.Default().
	Logger *slog.Logger
}

type Perms struct {
	PostWrite        string // create/update/delete posts
	PollWrite        string // create/update/delete polls + options
	CommentModerate  string // moderator delete/restore of another actor's comment
	ModerationReview string // list and resolve held comments and posts
	CommentBan       string // ban users from commenting anywhere in the tenant (global scope)
	Taxonomy         string // the taxonomy admin API contentkit.Runtime.Handler serves at /taxonomy
}

type Poll struct {
	ID       string `json:"id"`
	Kind     string `json:"kind"`
	Question string `json:"question"`
	Language string `json:"language"`
	IsActive bool   `json:"is_active"`
	ImageURL string `json:"image_url,omitempty"`

	LiveAt     time.Time    `json:"live_at"`
	ClosesAt   *time.Time   `json:"closes_at,omitempty"`
	Closed     bool         `json:"closed"` // inactive or past closes_at: no more votes/answers
	TotalVotes int          `json:"total_votes"`
	Options    []PollOption `json:"options"`
	Voted      bool         `json:"voted"`
	MyOption   string       `json:"my_option,omitempty"`
	// free_text only
	AnswerCount int         `json:"answer_count,omitempty"`
	Groups      []Group     `json:"groups,omitempty"`
	MyAnswer    *PollAnswer `json:"my_answer,omitempty"`
	// contains filtered or unexported fields
}

type PollAnswer struct {
	ID         string    `json:"id"`
	Text       string    `json:"text"`
	Classified bool      `json:"classified"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type PollAnswerInput struct {
	Text string `json:"text"`
}

type PollImage struct {
	ImageURL *string `json:"image_url"`
}

type PollInput struct {
	Kind     string            `json:"kind,omitempty"` // default multiple_choice
	Question string            `json:"question"`
	Language string            `json:"language"`
	LiveAt   *time.Time        `json:"live_at,omitempty"`   // nil = live now
	ClosesAt *time.Time        `json:"closes_at,omitempty"` // nil = open until deactivated
	Options  []PollOptionInput `json:"options,omitempty"`
}

type PollOption struct {
	ID        string `json:"id"`
	Label     string `json:"label"`
	ImageURL  string `json:"image_url,omitempty"`
	Position  int    `json:"position"`
	VoteCount int    `json:"vote_count"`
	// contains filtered or unexported fields
}

type PollOptionInput struct {
	Label    string `json:"label"`
	Position int    `json:"position"`
}

type PollOptionPatch struct {
	Label    *string `json:"label"`
	Position *int    `json:"position"`
}

type PollUpdate struct {
	Question *string             `json:"question"`
	IsActive *bool               `json:"is_active"`
	LiveAt   *time.Time          `json:"live_at"`
	ClosesAt Nullable[time.Time] `json:"closes_at,omitzero"`
}

type PollVote struct {
	OptionID string `json:"option_id"`
}

type Post struct {
	ID       string  `json:"id"`
	AuthorID string  `json:"author_id"`
	Title    string  `json:"title"`
	Slug     *string `json:"slug,omitempty"`
	// Body shows each image reference (ImageRef) whose image has a current
	// public file as that file's URL; the rest stay references.
	Body    string  `json:"body"`
	Excerpt *string `json:"excerpt,omitempty"`
	// Cover is the cover's image name; CoverURL its current public URL,
	// absent until it has one.
	Cover    *string `json:"cover,omitempty"`
	CoverURL *string `json:"cover_url,omitempty"`
	// Images maps each resolved image name of Body and Cover to its URL: an
	// editor turns those URLs back into references (ImageRef) to save.
	Images        map[string]string `json:"images,omitempty"`
	Language      string            `json:"language"`
	IsDraft       bool              `json:"is_draft"`
	LiveAt        *time.Time        `json:"live_at,omitempty"`
	TotalLikes    int               `json:"total_likes"`
	TotalDislikes int               `json:"total_dislikes"`
	CommentCount  int               `json:"comment_count"`
	// Moderation is "held" or "rejected" (with the reason) on an unpublished
	// post; absent when approved.
	Moderation       string `json:"moderation,omitempty"`
	ModerationReason string `json:"moderation_reason,omitempty"`
	// Code and URLSlug build the post's page URL: /{route}/{code}/{url_slug}
	// (contenturl).
	Code      string    `json:"code"`
	URLSlug   string    `json:"url_slug"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	// DeletedAt is set on a deleted post in the staff list (deleted=true).
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
}

type PostCover struct {
	CoverURL *string `json:"cover_url"`
}

type PostInput struct {
	Title    *string    `json:"title"`
	Body     *string    `json:"body"`
	Excerpt  *string    `json:"excerpt"`
	Language *string    `json:"language"`
	Slug     *string    `json:"slug"`
	IsDraft  *bool      `json:"is_draft"`
	LiveAt   *time.Time `json:"live_at"`
}

type Preference struct {
	contentref.ContentRef
	ActorID   string
	Axis      string
	Value     int16
	Revision  int64
	UpdatedAt time.Time
}

type PreferenceSender func(ctx context.Context, page []Preference) error

type PreferenceSyncReport struct {
	From int64
	Sent int
}

type ProviderDataEraser interface {
	EraseSubjects(ctx context.Context, tenant string, actorIDs []string) error
}

type PublicUser struct {
	ID           string `json:"id"`
	Username     string `json:"username"`
	Avatar       string `json:"avatar,omitempty"`
	AvatarSrcSet string `json:"avatar_srcset,omitempty"`
}

type Rate struct {
	Count int
	Per   time.Duration
}

type RateLimitError struct {
	Action     Action
	RetryAfter time.Duration
}

type ReactionCounts struct {
	Likes    int   `json:"likes"`
	Dislikes int   `json:"dislikes"`
	Mine     int16 `json:"mine"` // -1, 0, or 1; 0 also means "no reaction"
}

type RejectedError struct{ Reason string }

type ResolveInput struct {
	Decision Decision `json:"decision"`
	Revision int64    `json:"revision"`
	Reason   string   `json:"reason,omitempty"`
}

type Restored struct {
	Restored bool `json:"restored"`
}

type ReviewDecision struct {
	Revision int64 // the revision returned by ListHeld; stale decisions cannot publish edits
	Decision Decision
	Reviewer string
	Reason   string
}

type ReviewOutcome struct {
	Decision Decision `json:"decision"`
}

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

type StatelessPolicy interface{ StatelessPolicy() }

type TooLongError struct{ Max int }

type UserEnricher interface {
	UsersByIDs(ctx context.Context, ids []string) (map[string]PublicUser, error)
}

type Verdict struct {
	Decision      Decision
	Reason        string
	Model         string
	PromptVersion string
	Confidence    float64
}