pluginsdk/plugin/provisioner.go

package plugin

import (
	"context"
	"encoding/json"

	"github.com/google/uuid"
)

// Provisioner allows plugins to ensure required resources exist on startup.
// All methods are idempotent — they check first and only create if missing.
type Provisioner interface {
	EnsureDataTable(config DataTableConfig) error
	MergeSiteSettings(defaults map[string]any) error
	EnsureSetting(key string, defaultValue any) error
	EnsurePage(config PageConfig) error
	OverrideSiteSettings(overrides map[string]any) error
	EnsureMenuItem(menuName string, config MenuItemConfig) error
	RegisterEmbeddingConfig(config EmbeddingConfigDef) error
	EnsureEmbed(config EmbedConfig) error
	EnsureJobSchedule(config JobScheduleConfig) error
	UpdateDataTableRowField(ctx context.Context, rowID uuid.UUID, fieldKey string, value any) error
	DisableOrphanedJobSchedules(registeredTypes []string) error
	EnsurePlugin(name string) error
	EnsureCustomColor(config CustomColorConfig) error
	// EnsureMedia deposits an image under the plugin-chosen MediaDeposit.ID if a
	// row with that ID does not already exist. Idempotent: an existing ID is a
	// no-op; if the bytes differ from what was first deposited it logs a warning
	// rather than overwriting (seeded media is immutable once placed).
	EnsureMedia(deposit MediaDeposit) error
}

// DataTableConfig defines a data table to provision.
type DataTableConfig struct {
	Key         string
	Name        string
	Description string
	Schema      json.RawMessage
	PrimaryKey  string
}

// PageConfig defines a page to provision.
type PageConfig struct {
	Slug              string
	ParentSlug        string
	Title             string
	TemplateKey       string
	Blocks            []PageBlockConfig
	DetailSourceType  string
	DetailSourceKey   string
	DetailSlugField   string
	ReconcileBlocks   bool
	ReconcileTemplate bool
}

// PageBlockConfig defines a block within a provisioned page.
type PageBlockConfig struct {
	BlockKey    string
	Title       string
	Content     map[string]any
	HtmlContent *string
	Slot        string
	SortOrder   int32
}

// EmbeddingConfigDef defines embedding text generation for a data table.
type EmbeddingConfigDef struct {
	TableKey     string
	TextTemplate string
	Enabled      bool
}

// MenuItemConfig defines a menu item to provision.
type MenuItemConfig struct {
	Label     string
	URL       string
	PageSlug  string
	SortOrder int32
}

// EmbedConfig defines an embeddable component template.
type EmbedConfig struct {
	Key         string
	Title       string
	Description string
	Icon        string
	LabelField  string
	Template    string
	RenderFunc  func(ctx context.Context, content map[string]any) string
	DataSource  EmbedDataSource
}

// EmbedDataSource specifies where embed data comes from.
type EmbedDataSource struct {
	Type     string
	TableKey string
}

// JobScheduleConfig defines a cron schedule for a background job.
type JobScheduleConfig struct {
	JobType        string
	CronExpression string
	Config         json.RawMessage
}

// CustomColorConfig defines a custom theme color variable.
type CustomColorConfig struct {
	Name       string
	LightValue string
	DarkValue  string
	Source     string
}