pluginsdk/plugin/types.go

package plugin

import (
	"context"
	"encoding/json"

	"github.com/google/uuid"
	"github.com/jackc/pgx/v5"
)

// Pool interface for database transactions (satisfied by *pgxpool.Pool).
type Pool interface {
	Begin(ctx context.Context) (pgx.Tx, error)
}

// JobHandlerFunc is the signature for background job handlers.
type JobHandlerFunc func(ctx context.Context, config json.RawMessage, progress func(current, total int, message string)) (json.RawMessage, error)

// Dependency declares that a plugin requires another plugin.
type Dependency struct {
	Plugin     string
	MinVersion string
	Required   bool
}

// EmailSender is the narrow plugin-facing interface for sending emails.
type EmailSender interface {
	Send(to, subject, body string) error
}

// AdminPage defines a page that a plugin registers in the admin sidebar.
type AdminPage struct {
	Key   string
	Title string
	Icon  string
	Route string
}

// AIAction declares an AI task registered in the AI Action Matrix.
type AIAction struct {
	Key             string
	Title           string
	Description     string
	DefaultProvider string
	DefaultModel    string
}

// MasterPageBlock defines a block to add to a master page during provisioning.
type MasterPageBlock struct {
	BlockKey    string         `json:"block_key"`
	Title       string         `json:"title"`
	Content     map[string]any `json:"content"`
	HtmlContent *string        `json:"html_content"`
	Slot        string         `json:"slot"`
	SortOrder   int32          `json:"sort_order"`
}

// MasterPageDefinition defines a default master page that a plugin provisions.
type MasterPageDefinition struct {
	Key           string            `json:"key"`
	Title         string            `json:"title"`
	PageTemplates []string          `json:"page_templates"`
	Blocks        []MasterPageBlock `json:"blocks"`
}

// Plugin status constants.
const (
	StatusLoaded         = "loaded"
	StatusFailed         = "failed"
	StatusDisabled       = "disabled"
	StatusRebuilding     = "rebuilding"
	StatusPendingRestart = "pending_restart"
)

// Plugin source constants.
const (
	SourceBundled   = "bundled"
	SourceInstalled = "installed"
)

// MediaAnalyzedEvent is emitted after media scanning completes.
type MediaAnalyzedEvent struct {
	MediaID      uuid.UUID
	AnalysisID   uuid.UUID
	ContentHash  string
	Status       string
	SourcePlugin string
	SourceType   string
	SourceRefID  uuid.UUID
	SafeAdult    string
	SafeViolence string
	SafeRacy     string
}

// ModerationDecisionEvent is emitted when a moderation decision is made.
type ModerationDecisionEvent struct {
	MediaID        uuid.UUID
	AnalysisID     uuid.UUID
	Status         string
	PreviousStatus string
	SourcePlugin   string
	SourceType     string
	SourceRefID    uuid.UUID
	ModeratedBy    uuid.UUID
	Note           string
}

// MediaHooksProvider is the interface plugins implement to receive media lifecycle events.
type MediaHooksProvider interface {
	OnMediaAnalyzed(ctx context.Context, event MediaAnalyzedEvent) error
	OnModerationDecision(ctx context.Context, event ModerationDecisionEvent) error
}

// DirectoryExtensions allows plugins to customize the directory handler UI.
type DirectoryExtensions struct {
	PanelSections       []func(data map[string]any) string
	PinDecorators       []func(pin map[string]any, data map[string]any)
	BooleanFilterFields []string
	SelectFilterFields  []string
	BadgeLabels         map[string][2]string
}