interfaces

type ActivityRecord = usertypes.ActivityRecord

type ActivitySink interface {
	Log(ctx context.Context, record ActivityRecord) error
}

type AuthClaims interface {
	Subject() string
	UserID() string
	Role() string
	CanRead(resource string) bool
	CanEdit(resource string) bool
	CanCreate(resource string) bool
	CanDelete(resource string) bool
	HasRole(role string) bool
	IsAtLeast(minRole string) bool
	Expires() time.Time
	IssuedAt() time.Time
}

type AuthService interface {
	Authenticator() Authenticator
	TokenService() TokenService
	TemplateHelpers() map[string]any
}

type Authenticator interface {
	Login(ctx context.Context, identifier, password string) (string, error)
	Impersonate(ctx context.Context, identifier string) (string, error)
	SessionFromToken(token string) (Session, error)
	IdentityFromSession(ctx context.Context, session Session) (Identity, error)
	TokenService() TokenService
}

type CacheProvider interface {
	Get(ctx context.Context, key string) (any, error)
	Set(ctx context.Context, key string, value any, ttl time.Duration) error
	Delete(ctx context.Context, key string) error
	Clear(ctx context.Context) error
}

type Config interface {
	GetSigningKey() string
	GetSigningMethod() string
	GetContextKey() string
	GetTokenExpiration() int
	GetExtendedTokenDuration() int
	GetTokenLookup() string
	GetAuthScheme() string
	GetIssuer() string
	GetAudience() []string
	GetRejectedRouteKey() string
	GetRejectedRouteDefault() string
}

type ContentCreateRequest struct {
	ContentTypeID            uuid.UUID
	Slug                     string
	Status                   string
	CreatedBy                uuid.UUID
	UpdatedBy                uuid.UUID
	Translations             []ContentTranslationInput
	Metadata                 map[string]any
	AllowMissingTranslations bool
}

type ContentDeleteRequest struct {
	ID         uuid.UUID
	DeletedBy  uuid.UUID
	HardDelete bool
}

type ContentDeleteTranslationRequest struct {
	ContentID uuid.UUID
	Locale    string
	DeletedBy uuid.UUID
}

type ContentRecord struct {
	ID           uuid.UUID
	ContentType  uuid.UUID
	Slug         string
	Status       string
	Translations []ContentTranslation
	Metadata     map[string]any
}

type ContentService interface {
	Create(ctx context.Context, req ContentCreateRequest) (*ContentRecord, error)
	Update(ctx context.Context, req ContentUpdateRequest) (*ContentRecord, error)
	GetBySlug(ctx context.Context, slug string) (*ContentRecord, error)
	List(ctx context.Context) ([]*ContentRecord, error)
	Delete(ctx context.Context, req ContentDeleteRequest) error
	UpdateTranslation(ctx context.Context, req ContentUpdateTranslationRequest) (*ContentTranslation, error)
	DeleteTranslation(ctx context.Context, req ContentDeleteTranslationRequest) error
}

type ContentTranslation struct {
	ID      uuid.UUID
	Locale  string
	Title   string
	Summary *string
	Fields  map[string]any
}

type ContentTranslationInput struct {
	Locale  string
	Title   string
	Summary *string
	Fields  map[string]any
}

type ContentUpdateRequest struct {
	ID                       uuid.UUID
	Status                   string
	UpdatedBy                uuid.UUID
	Translations             []ContentTranslationInput
	Metadata                 map[string]any
	AllowMissingTranslations bool
}

type ContentUpdateTranslationRequest struct {
	ContentID uuid.UUID
	Locale    string
	Title     string
	Summary   *string
	Fields    map[string]any
	UpdatedBy uuid.UUID
}

type CultureService interface {
	GetCurrencyCode(locale string) (string, error)
	GetCurrency(locale string) (any, error)
	GetSupportNumber(locale string) (string, error)
	GetList(locale, name string) ([]string, error)
	GetMeasurementPreference(locale, measurementType string) (any, error)
	ConvertMeasurement(locale string, value float64, fromUnit, measurementType string) (float64, string, string, error)
}

type Document struct {
	FilePath     string
	Locale       string
	FrontMatter  FrontMatter
	Body         []byte
	BodyHTML     []byte
	LastModified time.Time
	// Checksum stores a digest of the original file content (typically SHA-256)
	// so sync workflows can detect changes without re-importing unchanged files.
	Checksum []byte
}

type FieldsLogger interface {
	WithFields(fields map[string]any) Logger
}

type Formatter interface {
	Format(template string, args ...any) (string, error)
}

type FormatterRegistry interface {
	FuncMap(locale string) map[string]any
}

type FrontMatter struct {
	Title    string         `yaml:"title" json:"title"`
	Slug     string         `yaml:"slug" json:"slug"`
	Summary  string         `yaml:"summary" json:"summary"`
	Status   string         `yaml:"status" json:"status"`
	Template string         `yaml:"template" json:"template"`
	Tags     []string       `yaml:"tags" json:"tags"`
	Author   string         `yaml:"author" json:"author"`
	Date     time.Time      `yaml:"date" json:"date"`
	Draft    bool           `yaml:"draft" json:"draft"`
	Custom   map[string]any `yaml:",inline" json:"custom"`
	Raw      map[string]any `yaml:"-" json:"raw"`
}

type HelperConfig struct {
	LocaleKey         string
	TemplateHelperKey string
	OnMissing         MissingTranslationHandler
	Registry          FormatterRegistry
}

type Identity interface {
	ID() string
	Username() string
	Email() string
	Role() string
}

type IdentityProvider interface {
	VerifyIdentity(ctx context.Context, identifier, password string) (Identity, error)
	FindIdentityByIdentifier(ctx context.Context, identifier string) (Identity, error)
}

type ImportOptions struct {
	ContentTypeID                   uuid.UUID
	AuthorID                        uuid.UUID
	CreatePages                     bool
	TemplateID                      *uuid.UUID
	DryRun                          bool
	ContentAllowMissingTranslations bool
	PageAllowMissingTranslations    bool
	ProcessShortcodes               bool
}

type ImportResult struct {
	CreatedContentIDs []uuid.UUID
	UpdatedContentIDs []uuid.UUID
	SkippedContentIDs []uuid.UUID
	Errors            []error
}

type Job struct {
	JobSpec
	ID        string
	Attempt   int
	LastError string
	Status    JobStatus
	CreatedAt time.Time
	UpdatedAt time.Time
}

type JobSpec struct {
	// Key uniquely identifies the job so that new requests can safely replace existing entries.
	Key string
	// Type describes the action to perform (e.g. cms.content.publish).
	Type string
	// RunAt specifies when the job should execute.
	RunAt time.Time
	// Payload carries contextual data required by the worker.
	Payload map[string]any
	// MaxAttempts limits retries when a worker reports failure. Zero means unlimited.
	MaxAttempts int
}

type JobStatus string

type LoadOptions struct {
	Recursive      *bool
	Pattern        string
	LocalePatterns map[string]string
	Parser         ParseOptions
}

type Logger interface {
	Trace(msg string, args ...any)
	Debug(msg string, args ...any)
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
	Fatal(msg string, args ...any)
	// WithFields returns a child logger that will attach the provided fields
	// to every emitted log entry. Implementations should avoid mutating the
	// current instance so callers can safely reuse loggers across requests.
	WithFields(fields map[string]any) Logger
	// WithContext returns a logger that binds the supplied context and should
	// propagate correlation identifiers when available.
	WithContext(ctx context.Context) Logger
}

type LoggerProvider interface {
	GetLogger(name string) Logger
}

type LoginPayload interface {
	GetIdentifier() string
	GetPassword() string
	GetExtendedSession() bool
}

type MarkdownParser interface {
	// Parse converts Markdown into HTML using the parser's default settings.
	Parse(markdown []byte) ([]byte, error)
	// ParseWithOptions converts Markdown into HTML using the supplied overrides.
	ParseWithOptions(markdown []byte, opts ParseOptions) ([]byte, error)
}

type MarkdownService interface {
	Load(ctx context.Context, path string, opts LoadOptions) (*Document, error)
	LoadDirectory(ctx context.Context, dir string, opts LoadOptions) ([]*Document, error)
	Render(ctx context.Context, markdown []byte, opts ParseOptions) ([]byte, error)
	RenderDocument(ctx context.Context, doc *Document, opts ParseOptions) ([]byte, error)
	Import(ctx context.Context, doc *Document, opts ImportOptions) (*ImportResult, error)
	ImportDirectory(ctx context.Context, dir string, opts ImportOptions) (*ImportResult, error)
	Sync(ctx context.Context, dir string, opts SyncOptions) (*SyncResult, error)
}

type MediaAsset struct {
	Reference  MediaReference
	Source     *MediaResource
	Renditions map[string]*MediaResource
	Metadata   MediaMetadata
}

type MediaMetadata struct {
	ID          string
	Name        string
	Description string
	MimeType    string
	Size        int64
	Width       int
	Height      int
	Duration    time.Duration
	AltText     string
	Caption     string
	Tags        []string
	Attributes  map[string]any
	Checksums   map[string]string
	CreatedAt   time.Time
	UpdatedAt   time.Time
	CreatedBy   string
	UpdatedBy   string
}

type MediaProvider interface {
	// Resolve fetches a single media asset using the supplied request parameters.
	Resolve(ctx context.Context, req MediaResolveRequest) (*MediaAsset, error)
	// ResolveBatch fetches multiple media assets. Implementations should de-duplicate references internally.
	ResolveBatch(ctx context.Context, reqs []MediaResolveRequest) (map[string]*MediaAsset, error)
	// Invalidate clears cached lookups for the provided references, allowing subsequent resolve calls to refresh state.
	Invalidate(ctx context.Context, refs ...MediaReference) error
}

type MediaReference struct {
	ID         string
	Path       string
	Collection string
	Locale     string
	Variant    string
	Attributes map[string]string
}

type MediaResolveRequest struct {
	Reference         MediaReference
	Renditions        []string
	IncludeSource     bool
	IncludeSignedURLs bool
	SignedURLTTL      time.Duration
	Purpose           string
	Context           map[string]string
}

type MediaResource struct {
	URL          string
	SignedURL    *SignedURL
	MimeType     string
	Size         int64
	Width        int
	Height       int
	Duration     time.Duration
	Hash         string
	LastModified time.Time
	Metadata     map[string]any
}

type MissingTranslationHandler func(locale, key string, args []any, err error) string

type PageCreateRequest struct {
	ContentID                uuid.UUID
	TemplateID               uuid.UUID
	ParentID                 *uuid.UUID
	Slug                     string
	Status                   string
	CreatedBy                uuid.UUID
	UpdatedBy                uuid.UUID
	Translations             []PageTranslationInput
	Metadata                 map[string]any
	AllowMissingTranslations bool
}

type PageDeleteRequest struct {
	ID         uuid.UUID
	DeletedBy  uuid.UUID
	HardDelete bool
}

type PageDeleteTranslationRequest struct {
	PageID    uuid.UUID
	Locale    string
	DeletedBy uuid.UUID
}

type PageDuplicateRequest struct {
	PageID    uuid.UUID
	Slug      string
	ParentID  *uuid.UUID
	Status    string
	CreatedBy uuid.UUID
	UpdatedBy uuid.UUID
}

type PageMoveRequest struct {
	PageID      uuid.UUID
	NewParentID *uuid.UUID
	ActorID     uuid.UUID
}

type PageRecord struct {
	ID           uuid.UUID
	ContentID    uuid.UUID
	TemplateID   uuid.UUID
	Slug         string
	Status       string
	Translations []PageTranslation
	Metadata     map[string]any
}

type PageService interface {
	Create(ctx context.Context, req PageCreateRequest) (*PageRecord, error)
	Update(ctx context.Context, req PageUpdateRequest) (*PageRecord, error)
	GetBySlug(ctx context.Context, slug string) (*PageRecord, error)
	List(ctx context.Context) ([]*PageRecord, error)
	Delete(ctx context.Context, req PageDeleteRequest) error
	UpdateTranslation(ctx context.Context, req PageUpdateTranslationRequest) (*PageTranslation, error)
	DeleteTranslation(ctx context.Context, req PageDeleteTranslationRequest) error
	Move(ctx context.Context, req PageMoveRequest) (*PageRecord, error)
	Duplicate(ctx context.Context, req PageDuplicateRequest) (*PageRecord, error)
}

type PageTranslation struct {
	ID      uuid.UUID
	Locale  string
	Title   string
	Path    string
	Summary *string
	Fields  map[string]any
}

type PageTranslationInput struct {
	Locale  string
	Title   string
	Path    string
	Summary *string
	Fields  map[string]any
}

type PageUpdateRequest struct {
	ID                       uuid.UUID
	TemplateID               *uuid.UUID
	Status                   string
	UpdatedBy                uuid.UUID
	Translations             []PageTranslationInput
	Metadata                 map[string]any
	AllowMissingTranslations bool
}

type PageUpdateTranslationRequest struct {
	PageID    uuid.UUID
	Locale    string
	Title     string
	Path      string
	Summary   *string
	Fields    map[string]any
	UpdatedBy uuid.UUID
}

type ParseOptions struct {
	Extensions        []string
	Sanitize          bool
	HardWraps         bool
	SafeMode          bool
	ProcessShortcodes bool
	ShortcodeOptions  ShortcodeProcessOptions
}

type ParsedShortcode struct {
	Name   string
	Params map[string]any
	Inner  string
}

type ResourceRoleProvider interface {
	FindResourceRoles(ctx context.Context, identity Identity) (map[string]string, error)
}

type Result = storage.Result

type RoleCapableSession interface {
	Session
	CanRead(resource string) bool
	CanEdit(resource string) bool
	CanCreate(resource string) bool
	CanDelete(resource string) bool
	HasRole(role string) bool
	IsAtLeast(minRole UserRole) bool
}

type Rows = storage.Rows

type Scheduler interface {
	// Enqueue registers a job for future execution. If a job with the same key already exists,
	// it is replaced with the new definition to keep scheduling idempotent.
	Enqueue(ctx context.Context, spec JobSpec) (*Job, error)
	// Cancel marks the job as cancelled so it will not be executed.
	Cancel(ctx context.Context, id string) error
	// CancelByKey cancels the job associated to the supplied unique key.
	CancelByKey(ctx context.Context, key string) error
	// Get returns the stored job by identifier.
	Get(ctx context.Context, id string) (*Job, error)
	// GetByKey returns the stored job that matches the supplied key.
	GetByKey(ctx context.Context, key string) (*Job, error)
	// ListDue returns pending jobs scheduled to run at or before the supplied instant.
	ListDue(ctx context.Context, until time.Time, limit int) ([]*Job, error)
	// MarkDone marks the job as successfully processed.
	MarkDone(ctx context.Context, id string) error
	// MarkFailed updates the job after a failed attempt.
	MarkFailed(ctx context.Context, id string, err error) error
}

type Service interface {
	Translator() Translator
	Culture() CultureService
	TemplateHelpers(cfg HelperConfig) map[string]any
	DefaultLocale() string
}

type Session interface {
	GetUserID() string
	GetUserUUID() (uuid.UUID, error)
	GetAudience() []string
	GetIssuer() string
	GetIssuedAt() *time.Time
	GetData() map[string]any
}

type ShortcodeContext struct {
	Context   context.Context
	Locale    string
	Cache     CacheProvider
	Sanitizer ShortcodeSanitizer
}

type ShortcodeDefinition struct {
	Name        string
	Version     string
	Description string
	Category    string
	Icon        string
	AllowInner  bool
	Async       bool
	CacheTTL    time.Duration
	Schema      ShortcodeSchema
	Template    string
	Handler     ShortcodeHandler
}

type ShortcodeHandler func(ctx ShortcodeContext, params map[string]any, inner string) (template.HTML, error)

type ShortcodeMetrics interface {
	// ObserveRenderDuration captures the elapsed time for a single shortcode render attempt.
	ObserveRenderDuration(shortcode string, duration time.Duration)
	// IncrementRenderError increments a counter tracking render failures.
	IncrementRenderError(shortcode string)
	// IncrementCacheHit records when a cached value satisfied a render request.
	IncrementCacheHit(shortcode string)
}

type ShortcodeParam struct {
	Name     string
	Type     ShortcodeParamType
	Required bool
	Default  any
	Validate ShortcodeValidator
}

type ShortcodeParamType string

type ShortcodeParser interface {
	Parse(content string) ([]ParsedShortcode, error)
	Extract(content string) (placeholders string, shortcodes []ParsedShortcode, err error)
}

type ShortcodeProcessOptions struct {
	Locale          string
	Cache           CacheProvider
	Sanitizer       ShortcodeSanitizer
	EnableWordPress bool
}

type ShortcodeRegistry interface {
	// Register stores a definition and returns an error when a shortcode
	// with the same name already exists or the definition fails validation.
	Register(definition ShortcodeDefinition) error

	// Get returns the definition for the supplied shortcode name.
	Get(name string) (ShortcodeDefinition, bool)

	// List exposes the current catalogue, sorted at the implementor's discretion.
	List() []ShortcodeDefinition

	// Remove deletes the shortcode from the registry. Removing an unknown shortcode
	// must be a no-op.
	Remove(name string)
}

type ShortcodeRenderer interface {
	Render(ctx ShortcodeContext, shortcode string, params map[string]any, inner string) (template.HTML, error)
	RenderAsync(ctx ShortcodeContext, shortcode string, params map[string]any, inner string) (<-chan template.HTML, <-chan error)
}

type ShortcodeSanitizer interface {
	Sanitize(html string) (string, error)
	ValidateURL(raw string) error
	ValidateAttributes(attrs map[string]any) error
}

type ShortcodeSchema struct {
	Params   []ShortcodeParam
	Defaults map[string]any
}

type ShortcodeService interface {
	// Process scans the provided content, rendering any shortcode invocations using the supplied options.
	Process(ctx context.Context, content string, opts ShortcodeProcessOptions) (string, error)
	// Render executes a single shortcode directly via the renderer pipeline.
	Render(ctx ShortcodeContext, shortcode string, params map[string]any, inner string) (template.HTML, error)
}

type ShortcodeValidator func(value any) error

type SignedURL struct {
	URL       string
	Method    string
	Headers   map[string]string
	ExpiresAt time.Time
}

type StorageCapabilityReporter interface {
	Capabilities() storage.Capabilities
}

type StorageProvider = storage.Provider

type StorageReloadable interface {
	Reload(ctx context.Context, cfg storage.Config) error
}

type SyncOptions struct {
	ImportOptions
	DeleteOrphaned bool
	UpdateExisting bool
}

type SyncResult struct {
	Created int
	Updated int
	Deleted int
	Skipped int
	Errors  []error
}

type TemplateHelperProvider interface {
	TemplateHelpers(translator Translator, cfg HelperConfig) map[string]any
}

type TemplateRenderer interface {
	Render(name string, data any, out ...io.Writer) (string, error)
	RenderTemplate(name string, data any, out ...io.Writer) (string, error)
	RenderString(templateContent string, data any, out ...io.Writer) (string, error)
	RegisterFilter(name string, fn func(input any, param any) (any, error)) error
	GlobalContext(data any) error
}

type TokenService interface {
	Generate(identity Identity, resourceRoles map[string]string) (string, error)
	Validate(token string) (AuthClaims, error)
}

type Transaction = storage.Transaction

type TransitionInput struct {
	EntityID     uuid.UUID
	EntityType   string
	CurrentState WorkflowState
	Transition   string
	TargetState  WorkflowState
	ActorID      uuid.UUID
	Metadata     map[string]any
}

type TransitionQuery struct {
	EntityType string
	State      WorkflowState
	Context    map[string]any
}

type TransitionResult struct {
	EntityID      uuid.UUID
	EntityType    string
	Transition    string
	FromState     WorkflowState
	ToState       WorkflowState
	CompletedAt   time.Time
	ActorID       uuid.UUID
	Metadata      map[string]any
	Events        []WorkflowEvent
	Notifications []WorkflowNotification
}

type Translator interface {
	Translate(locale, key string, args ...any) (string, error)
}

type TranslatorWithMetadata interface {
	TranslatorWithMetadata(locale, key string, args ...any) (string, map[string]any, error)
}

type UserRole string

type WorkflowAuthorizer interface {
	AuthorizeTransition(ctx context.Context, input TransitionInput, guard string) error
}

type WorkflowDefinition struct {
	EntityType   string
	InitialState WorkflowState
	States       []WorkflowStateDefinition
	Transitions  []WorkflowTransition
}

type WorkflowDefinitionStore interface {
	ListWorkflowDefinitions(ctx context.Context) ([]WorkflowDefinition, error)
}

type WorkflowEngine interface {
	// Transition applies the named transition (or explicit state change) to the entity.
	Transition(ctx context.Context, input TransitionInput) (*TransitionResult, error)
	// AvailableTransitions lists the possible transitions from the supplied state.
	AvailableTransitions(ctx context.Context, query TransitionQuery) ([]WorkflowTransition, error)
	// RegisterWorkflow installs or replaces a workflow definition for the given entity type.
	RegisterWorkflow(ctx context.Context, definition WorkflowDefinition) error
}

type WorkflowEvent struct {
	Name      string
	Timestamp time.Time
	Payload   map[string]any
}

type WorkflowNotification struct {
	Channel string
	Message string
	Data    map[string]any
}

type WorkflowState string

type WorkflowStateDefinition struct {
	Name        WorkflowState
	Description string
	Terminal    bool
}

type WorkflowTransition struct {
	Name        string
	Description string
	From        WorkflowState
	To          WorkflowState
	Guard       string
}