blocks

package

v0.41.0 Latest Latest Go to latest Published: Mar 17, 2026 License: MIT Imports: 7 Imported by: 1

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/goliatone/go-cms

Links

Open Source Insights

Documentation ¶

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	ErrDefinitionNameRequired          = errors.New("blocks: definition name required")
	ErrDefinitionSlugRequired          = errors.New("blocks: definition slug required")
	ErrDefinitionSlugInvalid           = errors.New("blocks: definition slug invalid")
	ErrDefinitionSlugExists            = errors.New("blocks: definition slug already exists")
	ErrDefinitionSchemaRequired        = errors.New("blocks: definition schema required")
	ErrDefinitionSchemaInvalid         = errors.New("blocks: definition schema invalid")
	ErrDefinitionSchemaVersionInvalid  = errors.New("blocks: definition schema version invalid")
	ErrDefinitionExists                = errors.New("blocks: definition already exists")
	ErrDefinitionIDRequired            = errors.New("blocks: definition id required")
	ErrDefinitionInUse                 = errors.New("blocks: definition has active instances")
	ErrDefinitionSoftDeleteUnsupported = errors.New("blocks: soft delete not supported for definitions")
	ErrDefinitionVersionRequired       = errors.New("blocks: definition version required")
	ErrDefinitionVersionExists         = errors.New("blocks: definition version already exists")
	ErrDefinitionVersioningDisabled    = errors.New("blocks: definition versioning disabled")

	ErrInstanceDefinitionRequired    = errors.New("blocks: definition id required")
	ErrInstanceRegionRequired        = errors.New("blocks: region required")
	ErrInstancePositionInvalid       = errors.New("blocks: position cannot be negative")
	ErrInstanceUpdaterRequired       = errors.New("blocks: updated_by is required")
	ErrInstanceSoftDeleteUnsupported = errors.New("blocks: soft delete not supported for instances")

	ErrTranslationContentRequired       = errors.New("blocks: translation content required")
	ErrTranslationExists                = errors.New("blocks: translation already exists for locale")
	ErrTranslationLocaleRequired        = errors.New("blocks: translation locale required")
	ErrTranslationSchemaInvalid         = errors.New("blocks: translation content invalid")
	ErrTranslationNotFound              = errors.New("blocks: translation not found")
	ErrTranslationMinimum               = errors.New("blocks: at least one translation is required")
	ErrTranslationsDisabled             = errors.New("blocks: translations feature disabled")
	ErrInstanceIDRequired               = errors.New("blocks: instance id required")
	ErrVersioningDisabled               = errors.New("blocks: versioning feature disabled")
	ErrInstanceVersionRequired          = errors.New("blocks: version identifier required")
	ErrInstanceVersionConflict          = errors.New("blocks: base version mismatch")
	ErrInstanceVersionAlreadyPublished  = errors.New("blocks: version already published")
	ErrInstanceVersionRetentionExceeded = errors.New("blocks: version retention limit reached")
	ErrMediaReferenceRequired           = errors.New("blocks: media reference requires id or path")
	ErrBlockSchemaMigrationRequired     = errors.New("blocks: schema migration required")
	ErrBlockSchemaValidationFailed      = errors.New("blocks: schema validation failed")
)

View Source

var BlockVersionSnapshotSchema = map[string]any{
	"type": "object",
	"properties": map[string]any{
		"configuration": map[string]any{
			"type":                 "object",
			"additionalProperties": true,
		},
		"translations": map[string]any{
			"type": "array",
			"items": map[string]any{
				"type":     "object",
				"required": []string{"locale", "content"},
				"properties": map[string]any{
					"locale": map[string]any{"type": "string"},
					"content": map[string]any{
						"type":                 "object",
						"additionalProperties": true,
					},
					"attribute_overrides": map[string]any{
						"type":                 "object",
						"additionalProperties": true,
					},
				},
			},
		},
		"metadata": map[string]any{
			"type":                 "object",
			"additionalProperties": true,
		},
		"media": map[string]any{
			"type": "object",
			"additionalProperties": map[string]any{
				"type":  "array",
				"items": map[string]any{"$ref": "#/$defs/mediaBinding"},
			},
		},
	},
	"$defs": map[string]any{
		"mediaBinding": map[string]any{
			"type":     "object",
			"required": []string{"slot", "reference"},
			"properties": map[string]any{
				"slot": map[string]any{"type": "string"},
				"reference": map[string]any{
					"type":                 "object",
					"additionalProperties": true,
					"properties": map[string]any{
						"id":         map[string]any{"type": "string"},
						"path":       map[string]any{"type": "string"},
						"collection": map[string]any{"type": "string"},
						"locale":     map[string]any{"type": "string"},
						"variant":    map[string]any{"type": "string"},
						"attributes": map[string]any{
							"type":                 "object",
							"additionalProperties": true,
						},
					},
				},
				"renditions": map[string]any{
					"type":  "array",
					"items": map[string]any{"type": "string"},
				},
				"required": map[string]any{
					"type":  "array",
					"items": map[string]any{"type": "string"},
				},
				"locale":          map[string]any{"type": "string"},
				"fallback_locale": map[string]any{"type": "string"},
				"gallery":         map[string]any{"type": "boolean"},
				"position": map[string]any{
					"type":    "integer",
					"minimum": 0,
				},
				"metadata": map[string]any{
					"type":                 "object",
					"additionalProperties": true,
				},
			},
		},
	},
}

BlockVersionSnapshotSchema documents the JSON schema enforced for block snapshots.

Functions ¶

This section is empty.

Types ¶

type AddTranslationInput ¶ added in v0.33.0

type AddTranslationInput struct {
	BlockInstanceID    uuid.UUID
	LocaleID           uuid.UUID
	Content            map[string]any
	AttributeOverrides map[string]any
	MediaBindings      media.BindingSet
}

AddTranslationInput captures localized content additions.

type BlockVersionSnapshot ¶

type BlockVersionSnapshot struct {
	Configuration map[string]any                    `json:"configuration,omitempty"`
	Translations  []BlockVersionTranslationSnapshot `json:"translations,omitempty"`
	Metadata      map[string]any                    `json:"metadata,omitempty"`
	Media         media.BindingSet                  `json:"media,omitempty"`
}

BlockVersionSnapshot captures the persisted JSON snapshot for a block instance.

type BlockVersionTranslationSnapshot ¶

type BlockVersionTranslationSnapshot struct {
	Locale             string         `json:"locale"`
	Content            map[string]any `json:"content"`
	AttributeOverrides map[string]any `json:"attribute_overrides,omitempty"`
}

BlockVersionTranslationSnapshot encodes localized payloads within a block snapshot.

type CreateDefinitionVersionInput ¶ added in v0.33.0

type CreateDefinitionVersionInput struct {
	DefinitionID uuid.UUID
	Schema       map[string]any
	Defaults     map[string]any
}

CreateDefinitionVersionInput captures schema version updates for a definition.

type CreateInstanceDraftRequest ¶ added in v0.33.0

type CreateInstanceDraftRequest struct {
	InstanceID  uuid.UUID
	Snapshot    BlockVersionSnapshot
	CreatedBy   uuid.UUID
	UpdatedBy   uuid.UUID
	BaseVersion *int
}

CreateInstanceDraftRequest captures draft snapshot data for an instance.

type CreateInstanceInput ¶ added in v0.33.0

type CreateInstanceInput struct {
	DefinitionID  uuid.UUID
	PageID        *uuid.UUID
	Region        string
	Position      int
	Configuration map[string]any
	IsGlobal      bool
	CreatedBy     uuid.UUID
	UpdatedBy     uuid.UUID
}

CreateInstanceInput defines the payload required to create a block instance.

type Definition ¶

type Definition struct {
	bun.BaseModel `bun:"table:block_definitions,alias:bd"`

	ID               uuid.UUID      `bun:",pk,type:uuid" json:"id"`
	Name             string         `bun:"name,notnull" json:"name"`
	Slug             string         `bun:"slug,notnull" json:"slug"`
	Description      *string        `bun:"description" json:"description,omitempty"`
	Icon             *string        `bun:"icon" json:"icon,omitempty"`
	Category         *string        `bun:"category" json:"category,omitempty"`
	Status           string         `bun:"status" json:"status,omitempty"`
	Schema           map[string]any `bun:"schema,type:jsonb,notnull" json:"schema"`
	UISchema         map[string]any `bun:"ui_schema,type:jsonb" json:"ui_schema,omitempty"`
	SchemaVersion    string         `bun:"schema_version" json:"schema_version,omitempty"`
	MigrationStatus  string         `bun:"migration_status" json:"migration_status,omitempty"`
	Defaults         map[string]any `bun:"defaults,type:jsonb" json:"defaults,omitempty"`
	EditorStyleURL   *string        `bun:"editor_style_url" json:"editor_style_url,omitempty"`
	FrontendStyleURL *string        `bun:"frontend_style_url" json:"frontend_style_url,omitempty"`
	EnvironmentID    uuid.UUID      `bun:"environment_id,type:uuid" json:"environment_id,omitempty"`
	DeletedAt        *time.Time     `bun:"deleted_at,nullzero" json:"deleted_at,omitempty"`
	CreatedAt        time.Time      `bun:"created_at,nullzero,default:current_timestamp" json:"created_at"`
	UpdatedAt        time.Time      `bun:"updated_at,nullzero,default:current_timestamp" json:"updated_at"`
}

Definition represents a reusable block template and associated metadata.

type DefinitionVersion ¶ added in v0.21.0

type DefinitionVersion struct {
	bun.BaseModel `bun:"table:block_definition_versions,alias:bdv"`

	ID            uuid.UUID      `bun:",pk,type:uuid" json:"id"`
	DefinitionID  uuid.UUID      `bun:"definition_id,notnull,type:uuid" json:"definition_id"`
	SchemaVersion string         `bun:"schema_version,notnull" json:"schema_version"`
	Schema        map[string]any `bun:"schema,type:jsonb,notnull" json:"schema"`
	Defaults      map[string]any `bun:"defaults,type:jsonb" json:"defaults,omitempty"`
	CreatedAt     time.Time      `bun:"created_at,nullzero,default:current_timestamp" json:"created_at"`
	UpdatedAt     time.Time      `bun:"updated_at,nullzero,default:current_timestamp" json:"updated_at"`
}

DefinitionVersion tracks a specific schema revision for a block definition.

type DeleteDefinitionRequest ¶ added in v0.33.0

type DeleteDefinitionRequest struct {
	ID         uuid.UUID
	HardDelete bool
}

DeleteDefinitionRequest captures block definition deletion inputs.

type DeleteInstanceRequest ¶ added in v0.33.0

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

DeleteInstanceRequest captures block instance deletion inputs.

type DeleteTranslationRequest ¶ added in v0.33.0

type DeleteTranslationRequest struct {
	BlockInstanceID          uuid.UUID
	LocaleID                 uuid.UUID
	DeletedBy                uuid.UUID
	AllowMissingTranslations bool
}

DeleteTranslationRequest removes a localized block translation.

type Instance ¶

type Instance struct {
	bun.BaseModel `bun:"table:block_instances,alias:bi"`

	ID               uuid.UUID      `bun:",pk,type:uuid" json:"id"`
	PageID           *uuid.UUID     `bun:"page_id,type:uuid" json:"page_id,omitempty"`
	Region           string         `bun:"region,notnull" json:"region"`
	Position         int            `bun:"position,notnull,default:0" json:"position"`
	DefinitionID     uuid.UUID      `bun:"definition_id,notnull,type:uuid" json:"definition_id"`
	Configuration    map[string]any `bun:"configuration,type:jsonb,notnull,default:'{}'::jsonb" json:"configuration"`
	IsGlobal         bool           `bun:"is_global,notnull,default:false" json:"is_global"`
	CurrentVersion   int            `bun:"current_version,notnull,default:1" json:"current_version"`
	PublishedVersion *int           `bun:"published_version" json:"published_version,omitempty"`
	PublishedAt      *time.Time     `bun:"published_at,nullzero" json:"published_at,omitempty"`
	PublishedBy      *uuid.UUID     `bun:"published_by,type:uuid" json:"published_by,omitempty"`
	CreatedBy        uuid.UUID      `bun:"created_by,notnull,type:uuid" json:"created_by"`
	UpdatedBy        uuid.UUID      `bun:"updated_by,notnull,type:uuid" json:"updated_by"`
	DeletedAt        *time.Time     `bun:"deleted_at,nullzero" json:"deleted_at,omitempty"`
	CreatedAt        time.Time      `bun:"created_at,nullzero,default:current_timestamp" json:"created_at"`
	UpdatedAt        time.Time      `bun:"updated_at,nullzero,default:current_timestamp" json:"updated_at"`

	Definition   *Definition        `bun:"rel:belongs-to,join:definition_id=id" json:"definition,omitempty"`
	Translations []*Translation     `bun:"rel:has-many,join:id=block_instance_id" json:"translations,omitempty"`
	Versions     []*InstanceVersion `bun:"rel:has-many,join:id=block_instance_id" json:"versions,omitempty"`
}

Instance captures a concrete usage of a block definition on a page or region.

type InstanceVersion ¶

type InstanceVersion struct {
	bun.BaseModel `bun:"table:block_versions,alias:bv"`

	ID              uuid.UUID            `bun:",pk,type:uuid" json:"id"`
	BlockInstanceID uuid.UUID            `bun:"block_instance_id,notnull,type:uuid" json:"block_instance_id"`
	Version         int                  `bun:"version,notnull" json:"version"`
	Status          domain.Status        `bun:"status,notnull,default:'draft'" json:"status"`
	Snapshot        BlockVersionSnapshot `bun:"snapshot,type:jsonb,notnull" json:"snapshot"`
	CreatedBy       uuid.UUID            `bun:"created_by,notnull,type:uuid" json:"created_by"`
	CreatedAt       time.Time            `bun:"created_at,nullzero,default:current_timestamp" json:"created_at"`
	PublishedAt     *time.Time           `bun:"published_at,nullzero" json:"published_at,omitempty"`
	PublishedBy     *uuid.UUID           `bun:"published_by,type:uuid" json:"published_by,omitempty"`

	Instance *Instance `bun:"rel:belongs-to,join:block_instance_id=id" json:"instance,omitempty"`
}

InstanceVersion captures a snapshot of a block instance's configuration and translations.

type PublishInstanceDraftRequest ¶ added in v0.33.0

type PublishInstanceDraftRequest struct {
	InstanceID  uuid.UUID
	Version     int
	PublishedBy uuid.UUID
	PublishedAt *time.Time
}

PublishInstanceDraftRequest captures publish inputs for a draft snapshot.

type RegisterDefinitionInput ¶ added in v0.33.0

type RegisterDefinitionInput struct {
	Name             string
	Slug             string
	Description      *string
	Icon             *string
	Category         *string
	Status           string
	Schema           map[string]any
	UISchema         map[string]any
	Defaults         map[string]any
	EditorStyleURL   *string
	FrontendStyleURL *string
	EnvironmentKey   string
}

RegisterDefinitionInput captures definition attributes for creation.

type RestoreInstanceVersionRequest ¶ added in v0.33.0

type RestoreInstanceVersionRequest struct {
	InstanceID uuid.UUID
	Version    int
	RestoredBy uuid.UUID
}

RestoreInstanceVersionRequest captures restore inputs for an instance version.

type Service ¶ added in v0.33.0

type Service interface {
	RegisterDefinition(ctx context.Context, input RegisterDefinitionInput) (*Definition, error)
	GetDefinition(ctx context.Context, id uuid.UUID) (*Definition, error)
	ListDefinitions(ctx context.Context, env ...string) ([]*Definition, error)
	UpdateDefinition(ctx context.Context, input UpdateDefinitionInput) (*Definition, error)
	DeleteDefinition(ctx context.Context, req DeleteDefinitionRequest) error
	SyncRegistry(ctx context.Context) error
	CreateDefinitionVersion(ctx context.Context, input CreateDefinitionVersionInput) (*DefinitionVersion, error)
	GetDefinitionVersion(ctx context.Context, definitionID uuid.UUID, version string) (*DefinitionVersion, error)
	ListDefinitionVersions(ctx context.Context, definitionID uuid.UUID) ([]*DefinitionVersion, error)

	CreateInstance(ctx context.Context, input CreateInstanceInput) (*Instance, error)
	ListPageInstances(ctx context.Context, pageID uuid.UUID) ([]*Instance, error)
	ListGlobalInstances(ctx context.Context) ([]*Instance, error)
	UpdateInstance(ctx context.Context, input UpdateInstanceInput) (*Instance, error)
	DeleteInstance(ctx context.Context, req DeleteInstanceRequest) error

	AddTranslation(ctx context.Context, input AddTranslationInput) (*Translation, error)
	UpdateTranslation(ctx context.Context, input UpdateTranslationInput) (*Translation, error)
	DeleteTranslation(ctx context.Context, req DeleteTranslationRequest) error
	GetTranslation(ctx context.Context, instanceID uuid.UUID, localeID uuid.UUID) (*Translation, error)

	CreateDraft(ctx context.Context, req CreateInstanceDraftRequest) (*InstanceVersion, error)
	PublishDraft(ctx context.Context, req PublishInstanceDraftRequest) (*InstanceVersion, error)
	ListVersions(ctx context.Context, instanceID uuid.UUID) ([]*InstanceVersion, error)
	RestoreVersion(ctx context.Context, req RestoreInstanceVersionRequest) (*InstanceVersion, error)
}

Service exposes block definition and instance management capabilities.

type Translation ¶

type Translation struct {
	bun.BaseModel `bun:"table:block_translations,alias:bt"`

	ID                uuid.UUID                      `bun:",pk,type:uuid" json:"id"`
	BlockInstanceID   uuid.UUID                      `bun:"block_instance_id,notnull,type:uuid" json:"block_instance_id"`
	LocaleID          uuid.UUID                      `bun:"locale_id,notnull,type:uuid" json:"locale_id"`
	Content           map[string]any                 `bun:"content,type:jsonb,notnull" json:"content"`
	AttributeOverride map[string]any                 `bun:"attribute_overrides,type:jsonb" json:"attribute_overrides,omitempty"`
	MediaBindings     media.BindingSet               `bun:"media_bindings,type:jsonb" json:"media_bindings,omitempty"`
	ResolvedMedia     map[string][]*media.Attachment `bun:"-" json:"media,omitempty"`
	DeletedAt         *time.Time                     `bun:"deleted_at,nullzero" json:"deleted_at,omitempty"`
	CreatedAt         time.Time                      `bun:"created_at,nullzero,default:current_timestamp" json:"created_at"`
	UpdatedAt         time.Time                      `bun:"updated_at,nullzero,default:current_timestamp" json:"updated_at"`
}

Translation stores localized block content and attribute overrides.

type UpdateDefinitionInput ¶ added in v0.33.0

type UpdateDefinitionInput struct {
	ID               uuid.UUID
	Name             *string
	Slug             *string
	Description      *string
	Icon             *string
	Category         *string
	Status           *string
	Schema           map[string]any
	UISchema         map[string]any
	Defaults         map[string]any
	EditorStyleURL   *string
	FrontendStyleURL *string
	EnvironmentKey   *string
}

UpdateDefinitionInput captures mutable definition fields.

type UpdateInstanceInput ¶ added in v0.33.0

type UpdateInstanceInput struct {
	InstanceID    uuid.UUID
	PageID        *uuid.UUID
	Region        *string
	Position      *int
	Configuration map[string]any
	IsGlobal      *bool
	UpdatedBy     uuid.UUID
}

UpdateInstanceInput defines mutable block instance fields.

type UpdateTranslationInput ¶ added in v0.33.0

type UpdateTranslationInput struct {
	BlockInstanceID    uuid.UUID
	LocaleID           uuid.UUID
	Content            map[string]any
	AttributeOverrides map[string]any
	MediaBindings      media.BindingSet
	UpdatedBy          uuid.UUID
}

UpdateTranslationInput captures localized content updates.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL