pluginsdk/content/author.go

package content

import (
	"context"

	"github.com/google/uuid"
)

// Author provides imperative page/post authoring for plugins (WO-WZ-019).
// The CMS implements this interface and wires it into CoreServices.
//
// These are the runtime counterparts of the idempotent seed-time operations
// on plugin.Provisioner: CreatePage is create-or-return-existing, the rest
// mutate an existing page/post. Blog posts live in the CMS's dedicated
// blog_posts table (not the pages table).
type Author interface {
	CreatePage(ctx context.Context, params CreatePageParams) (CreatePageResult, error)
	SetPageBlocks(ctx context.Context, pageID uuid.UUID, blocks []PageBlock) error
	PublishPage(ctx context.Context, pageID uuid.UUID) error
	SetPageSEO(ctx context.Context, pageID uuid.UUID, seo PageSEO) error
	UpsertPost(ctx context.Context, params UpsertPostParams) (UpsertPostResult, error)
}

// CreatePageParams describes a page to create.
type CreatePageParams struct {
	Slug          string
	ParentSlug    string // "" = root
	Title         string
	TemplateKey   string
	MasterPageKey string // "" = none
}

// CreatePageResult reports the created (or pre-existing) page.
type CreatePageResult struct {
	PageID uuid.UUID
	// Created is false when a page with the slug already existed; the
	// existing ID is returned and nothing is modified.
	Created bool
}

// PageBlock is one block instance placed on a page.
type PageBlock struct {
	BlockKey    string
	Title       string
	Content     map[string]any
	HTMLContent *string
	Slot        string
	SortOrder   int32
}

// PageSEO carries the SEO fields settable on a page. Nil pointers leave the
// existing value untouched.
type PageSEO struct {
	MetaTitle          *string
	MetaDescription    *string
	OGTitle            *string
	OGDescription      *string
	OGImage            *string
	FocusKeyphrase     *string
	CanonicalURL       *string
	RobotsDirective    *string
	TwitterTitle       *string
	TwitterDescription *string
	TwitterImage       *string
}

// UpsertPostParams creates or updates a blog post by slug.
type UpsertPostParams struct {
	Slug     string
	Title    string
	Document map[string]any // BlockNote document
	Excerpt  *string
	// AuthorProfileID / FeaturedImageID reference existing rows (e.g. a
	// media.deposit result for the image).
	AuthorProfileID *uuid.UUID
	FeaturedImageID *uuid.UUID
	// Publish publishes the post immediately after the upsert.
	Publish    bool
	IsFeatured bool
}

// UpsertPostResult reports the upserted post.
type UpsertPostResult struct {
	PostID  uuid.UUID
	Created bool
}