content

type Action string

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 AnswerGroup struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	Count int    `json:"count"`
}

type AuthError struct{ Err error }

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

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 BannedWord struct {
	Word      string     `json:"word"`
	Action    WordAction `json:"action"`
	CreatedBy string     `json:"created_by"`
	CreatedAt time.Time  `json:"created_at"`
}

type BannedWordInput struct {
	Word   string     `json:"word"`
	Action WordAction `json:"action,omitempty"`
}

type BasicModerator struct {
	AllowLinks bool          // default false: reject bodies containing URLs
	DupWindow  time.Duration // 0 = 30s; negative disables
	// 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"`
	Language   string      `json:"language,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"`
	// Language is the thread the comment joins: one of the site's languages,
	// or none. A reply joins its comment's.
	Language string `json:"language,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"`
	// Comments is the target's comments setting: open, closed or hidden.
	Comments string `json:"comments"`
	// Locked: the caller can't open the content (or the version), so its
	// comments are withheld from them and take none of their writes.
	Locked bool       `json:"locked"`
	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
	// (root:comments:moderate).
	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 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 FavoriteState struct {
	Favorited bool `json:"favorited"`
	Count     int  `json:"count"`
}

type FeedItem struct {
	Comment
	contentref.ContentRef
}

type GroupAssignment struct {
	GroupID string
	Label   string
}

type HeldItem struct {
	Kind     string `json:"kind"`     // KindComment, or a HeldSource's kind
	Revision int64  `json:"revision"` // required when resolving this exact screened text
	ID       string `json:"id"`
	// Ref is the commented content, or the held item'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 HeldSource interface {
	// Held pages held items oldest first, after (after, afterID).
	Held(ctx context.Context, after time.Time, afterID string, limit int) ([]HeldItem, error)
	// ResolveHeld applies a reviewer's decision at the listed revision;
	// ErrNotFound when the item is not held at it.
	ResolveHeld(ctx context.Context, id string, d ReviewDecision) error
}

type IPBan struct {
	Network  string     `json:"network"`
	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 IPBanInput struct {
	Network string     `json:"network"`
	Reason  string     `json:"reason,omitempty"`
	Until   *time.Time `json:"until,omitempty"`
}

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

type ImportAnswer struct {
	PollID    string
	UserID    string
	Text      string
	CreatedAt *time.Time
	UpdatedAt *time.Time
}

type ImportComment struct {
	ID        string
	Ref       contentref.ContentRef
	Language  string
	ReplyToID string
	UserID    string
	AnonName  string
	Body      string
	DeletedAt *time.Time
	CreatedAt *time.Time
	UpdatedAt *time.Time
}

type ImportFavorite struct {
	Ref       contentref.ContentRef
	UserID    string
	CreatedAt *time.Time
}

type ImportPoll struct {
	ID        string
	Kind      string
	Question  string
	Language  string
	Active    bool
	LiveAt    *time.Time
	ClosesAt  *time.Time
	DeletedAt *time.Time
	CreatedAt *time.Time
	UpdatedAt *time.Time
	Options   []ImportPollOption
}

type ImportPollOption struct {
	ID       string `json:"id"`
	Label    string `json:"label"`
	Position int    `json:"position"`
}

type ImportReaction struct {
	Ref       contentref.ContentRef
	UserID    string
	IP        string
	Value     int16
	CreatedAt *time.Time
	UpdatedAt *time.Time
}

type ImportVote struct {
	PollID    string
	OptionID  string
	UserID    string
	IP        string
	CreatedAt *time.Time
}

type Limits struct {
	Comment         []Rate // default 5 per 5 minutes and 20 per hour
	CommentReaction []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 reads items as the media read API does; the engine fills it
	// from its Reader.
	Reader   MediaReader
	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)
	Avatars(ctx context.Context, ids ...string) ([]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 content for a
	// comment, the item's own reference for catalog text.
	Ref    contentref.ContentRef
	Kind   string // KindComment, or a HeldSource's kind (catalog.HeldKind)
	ItemID string // the existing item on an edit; empty on create
	Title  string // catalog text 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 ContentKit's schema.
	Schema string
	// Tenant scopes every row, index, cursor and result. Required.
	Tenant string

	// Auth says who a request is (authkit/auth; AuthKit's ak.Authenticator()).
	// The routes ask it at most once per request and build the actor from
	// its Verified: anonymous without a credential, 401 for one that fails.
	// Staff hold ContentKit's permissions (access.Permissions) in its root
	// scope (auth.Root), checked by the Verified's Can: declare them in its
	// roles. Required.
	Auth auth.Authenticator
	// UserInfo is the host's directory (authkit/userinfo; AuthKit's
	// ak.UserInfo()): authors' names and usernames, read once per response
	// and never copied. Nil shows authors by id.
	UserInfo userinfo.Lookup
	// Resolver decides interaction targets: content items and their versions
	// (the catalog's) and groups. Required.
	Resolver resolve.Resolver
	// Kinds is the site's content model: interactions target its content
	// kinds and group kinds, and comments carry one of its languages.
	Kinds kinds.Config

	// 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).
	Processor ContentProcessor // comments; default: strip tags
	// Moderator screens comment writes, and the catalog's (Screen); 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 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

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

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

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      []AnswerGroup `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 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"`
	Name         string `json:"name,omitempty"`
	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 {
	// Notifications is this tenant's user inbox.
	Notifications *notification.Store
	// contains filtered or unexported fields
}

type Screening struct {
	State   string
	Reason  *string
	Verdict []byte
}

type StatelessPolicy interface{ StatelessPolicy() }

type TargetType string

type TooLongError struct{ Max int }

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

type WordAction string