@velora-cms/plugin-sdk 0.9.0

package/dist/manifest.d.ts

@@ -0,0 +1,370 @@
+import type { ComponentType } from "react";
+import type { CreateDocumentTypeRequest } from "@velora-cms/api-schemas";
+import type { ThemeTokenOverrides } from "@velora-cms/design-tokens";
+import type { ZodType } from "zod";
+import type { DataTypePlugin } from "./data-type-plugin.js";
+import type { PluginApiRouteContext, PublishedContent, ScopedStructuredStorage } from "./structured-storage-types.js";
+/**
+ * The seven plugin types. A plugin's type determines which contributions
+ * it may declare — see the contribution matrix in docs/PROJECT_CONTEXT.md
+ * (Plugin System), which the per-type manifest variants below encode
+ * structurally: TypeScript rejects a disallowed contribution at compile
+ * time, and the Zod manifest validation (Session 60) enforces the same
+ * matrix at runtime for non-TS authors.
+ */
+export type PluginType = "datatype" | "section" | "template" | "theme" | "integration" | "utility" | "bundle";
+/** The types whose contribution-matrix rows can carry browser-rendered
+ * contributions (views, widgets, settings pages, toolbar/tree items) —
+ * exactly these ship a Module Federation client bundle
+ * (remoteEntry.js). theme/template/bundle are data-only: their packages
+ * carry manifest.json + server/plugin.js (the manifest carrier) and
+ * nothing client-side. Single source of truth for velora-plugin's
+ * build/validate, apps/server's install path, and (as a documented
+ * static mirror) the marketplace's submission checks. */
+export declare const CLIENT_BUNDLE_TYPES: readonly ["datatype", "section", "integration", "utility"];
+export declare function hasClientBundle(type: PluginType): boolean;
+/**
+ * Databases a plugin can declare support for. Deliberately NOT
+ * db-adapter's DatabaseDialect: that union includes 'mock' (the in-memory
+ * test adapter), which no plugin may target — and the SDK is a published
+ * package that must not depend on the unpublished adapter internals.
+ */
+export type DatabaseDialect = "postgresql" | "mysql" | "sqlite" | "mssql" | "mongodb";
+/**
+ * How the plugin stores data and where it can run. Required on every
+ * manifest (plugin-sdk.md) — the marketplace pre-filters by the site's
+ * active database and install is blocked with a clear reason, never a
+ * silent failure.
+ */
+export interface DatabaseCompatibility {
+    /** 'simple' = JSON key-value SimpleStorageAPI (default, ~80% of
+     * plugins); 'structured' = relational StructuredStorageAPI, which
+     * requires needsStructuredData and manual marketplace review. */
+    storageType: "simple" | "structured";
+    supported: DatabaseDialect[];
+    /** Optional human-readable reason per UNSUPPORTED dialect (shown on the
+     * blocked-install screen) — hence Partial: supported dialects carry no
+     * reason. */
+    unsupportedReason?: Partial<Record<DatabaseDialect, string>>;
+}
+/**
+ * Capability declarations surfaced to the user at install time (and, for
+ * needsStructuredData, triggering manual marketplace review). Required on
+ * every manifest — validation rejects a manifest missing it.
+ */
+export interface PluginPermissions {
+    needsStructuredData: boolean;
+    needsExternalNetwork: boolean;
+    needsFileSystemAccess: boolean;
+}
+/**
+ * The storage surface a plugin migration runs against. Deliberately empty
+ * for now: plugins never construct raw SQL (non-negotiable), so this is
+ * NOT db-adapter's TransactionContext — Month 6's plugin-storage work
+ * fills it in (defineTable etc.). Widening a parameter the plugin
+ * receives is backward-compatible for plugin authors.
+ */
+export interface PluginMigrationContext {
+}
+/** A database change applied at plugin install/update time. */
+export interface PluginMigration {
+    id: string;
+    name: string;
+    up: (ctx: PluginMigrationContext) => void | Promise<void>;
+    down: (ctx: PluginMigrationContext) => void | Promise<void>;
+}
+/** Result of a plugin's validateMigration hook. */
+export interface PluginMigrationValidation {
+    compatible: boolean;
+    issues: string[];
+}
+/**
+ * Participation in a site-wide dialect migration (e.g. SQLite →
+ * PostgreSQL, the v1.x wizard): a plugin with its own stored data can
+ * veto, transform rows in flight, and run before/after steps.
+ */
+export interface PluginMigrationHooks {
+    beforeMigration?: (from: DatabaseDialect, to: DatabaseDialect) => void | Promise<void>;
+    transformRow?: (table: string, row: Record<string, unknown>, from: DatabaseDialect, to: DatabaseDialect) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    afterMigration?: (from: DatabaseDialect, to: DatabaseDialect) => void | Promise<void>;
+    validateMigration?: (from: DatabaseDialect, to: DatabaseDialect) => PluginMigrationValidation | Promise<PluginMigrationValidation>;
+}
+/** The events a plugin can hook. The hook engine (S159) actually FIRES
+ * only three of these — content:afterPublish (including rollbacks),
+ * content:afterTrash, content:afterRestore — with the
+ * ContentLifecycleHookPayload shape declared below; every other event in
+ * this catalog is declared for forward compatibility and stays inert. */
+export type HookEvent = "content:beforeSave" | "content:afterSave" | "content:beforePublish" | "content:afterPublish" | "content:afterTrash" | "content:afterRestore" | "content:beforeDelete" | "media:afterUpload" | "user:afterLogin" | "api:beforeResponse";
+export interface ContentLifecycleHookPayload {
+    event: "content:afterPublish" | "content:afterTrash" | "content:afterRestore";
+    contentId: string;
+    path: string;
+    documentTypeId: string;
+    occurredAt: string;
+}
+export interface PluginHookContext {
+    structuredStorage: ScopedStructuredStorage;
+    getPublishedContent(contentId: string): Promise<PublishedContent | null>;
+}
+export type HookHandler = (payload: unknown, context?: PluginHookContext) => void | Promise<void>;
+export type PluginHooks = Partial<Record<HookEvent, HookHandler>>;
+/** A major admin feature area with its own app-bar section (e.g. the
+ * Commerce plugin's Orders). First consumer: Month 8. */
+export interface AdminSectionContribution {
+    id: string;
+    name: string;
+    icon: string;
+    view: ComponentType;
+    /** When true, only admin-role users see this section in the app bar and
+     * may reach its route — the same gate built-in Settings/Users use
+     * (Session 91 closed the plugin bypass in Session 108). Default (unset)
+     * = visible to any authenticated user. */
+    adminOnly?: boolean;
+}
+export interface DashboardWidgetContribution {
+    id: string;
+    name: string;
+    view: ComponentType;
+}
+/** Mounted under /api/plugins/:pluginId/… so two plugins can never
+ * collide on a path (api-design.md) — the host dispatches to this exact
+ * (method, path) pair at request time (Month 8, Session 89: the first
+ * real server-side consumer). `handler` stays untyped at the SDK
+ * boundary (same cross-boundary erasure as view ComponentType fields)
+ * — the host casts to real Fastify types internally, since it always
+ * passes real FastifyRequest/FastifyReply instances. */
+export interface ApiRouteContribution {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Relative to /api/plugins/:pluginId/ — must start with "/". */
+    path: string;
+    /** Who may call this route.
+     *  - "admin" (the default when omitted) requires a JWT admin session —
+     *    for admin-facing plugin UIs like Commerce Orders or the Forms
+     *    builder.
+     *  - "apiKey" requires a valid public API key — for credentialed
+     *    headless callers like a storefront checkout.
+     *  - "public" requires NO credentials — for genuinely anonymous
+     *    browser traffic such as a contact-form submission. Session 108
+     *    deliberately deferred this tier ("a webhook/public level can be
+     *    added when a real consumer needs it"); Session 160's Forms
+     *    plugin is that consumer. A public route owns its own abuse
+     *    controls (honeypot, per-IP bucket, body caps) and only reaches
+     *    browsers cross-origin when the operator allowlists their origin
+     *    in VELORA_CORS_ORIGINS.
+     *  Anything unrecognized falls back to "admin" — secure by default. */
+    access?: "admin" | "apiKey" | "public";
+    /** Optional request-side validation. The handler's response is NOT
+     * schema-validated — trusted, same as SimpleStorageAPI's handlers
+     * today. */
+    schema?: {
+        body?: ZodType;
+        querystring?: ZodType;
+        params?: ZodType;
+    };
+    /** Third argument added Month 8, Session 90 — the first server-side
+     * consumer needing privileged host access. Existing two-argument (or
+     * fewer) handlers remain perfectly valid: TypeScript allows a function
+     * with fewer declared parameters to satisfy a type expecting more. */
+    handler: (request: unknown, reply: unknown, context: PluginApiRouteContext) => unknown;
+}
+export interface ScheduledTaskContribution {
+    id: string;
+    name: string;
+    /** Standard 5-field cron expression. */
+    cron: string;
+    run: () => void | Promise<void>;
+}
+/** Media pipeline processor (thumbnails, optimization). The file/result
+ * contract firms up when the BullMQ media pipeline lands. */
+export interface MediaProcessorContribution {
+    id: string;
+    name: string;
+    process: (file: unknown) => unknown | Promise<unknown>;
+}
+export interface SettingsPageContribution {
+    id: string;
+    name: string;
+    view: ComponentType;
+}
+export interface ContentTreeActionContribution {
+    id: string;
+    label: string;
+    onSelect: (nodeId: string) => void | Promise<void>;
+}
+/** A button in the rich-text editor's toolbar. TipTap wiring comes with
+ * the first consumer. */
+export interface EditorToolbarContribution {
+    id: string;
+    label: string;
+    icon: string;
+    onClick: () => void | Promise<void>;
+}
+/** A service an integration plugin exposes for other plugins to consume
+ * (e.g. a Stripe client). Shape intentionally opaque until the
+ * cross-plugin service registry exists. */
+export interface ExposedServiceContribution {
+    id: string;
+    name: string;
+    service: unknown;
+}
+/** A ready-made frontend starter shipped alongside a plugin (e.g. the
+ * Commerce plugin's "Online Store" Next.js starter) — one marketplace
+ * listing, working site immediately. Packaging lands Month 13. */
+export interface BundledTemplateContribution {
+    name: string;
+    description?: string;
+    /** Where the starter's source lives until marketplace packaging exists. */
+    repository?: string;
+}
+export interface SerializerContext {
+    /** The public core item, post field-serialization. */
+    item: {
+        id: string;
+        documentTypeId: string;
+        locale: string;
+        publishedAt: string | null;
+        version: number;
+    };
+    /** SERIALIZED field data — contributions run after core serialization. */
+    data: Record<string, unknown>;
+    documentType: {
+        id: string;
+        name: string;
+    };
+}
+export interface CustomFormatContribution {
+    /** Plugin-scoped name, /^[a-z0-9-]+$/ — addressed as `<pluginId>:<name>`. */
+    name: string;
+    build: (context: SerializerContext) => unknown | Promise<unknown>;
+}
+export interface SerializerContribution {
+    extendContentResponse?: (context: SerializerContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    customFormats?: CustomFormatContribution[];
+}
+export interface DataTypePluginContributions {
+    /** The Month 3 datatype contract, referenced verbatim — a datatype
+     * plugin can ship several field types (id/version on each entry are the
+     * datatype's own, distinct from the plugin's). */
+    dataTypes?: DataTypePlugin[];
+    mediaProcessors?: MediaProcessorContribution[];
+    settingsPages?: SettingsPageContribution[];
+}
+export interface SectionPluginContributions {
+    dataTypes?: DataTypePlugin[];
+    adminSections?: AdminSectionContribution[];
+    dashboardWidgets?: DashboardWidgetContribution[];
+    apiRoutes?: ApiRouteContribution[];
+    hooks?: PluginHooks;
+    scheduledTasks?: ScheduledTaskContribution[];
+    settingsPages?: SettingsPageContribution[];
+    /** Document types the plugin provisions at install — the creation shape
+     * (server mints ids), same schema the admin's builder POSTs. */
+    documentTypes?: CreateDocumentTypeRequest[];
+    bundledTemplate?: BundledTemplateContribution;
+}
+export interface TemplatePluginContributions {
+    /** A template plugin IS a bundled template (per the matrix), so there
+     * is no separate bundledTemplate key — it contributes the document
+     * types its starter needs. */
+    documentTypes?: CreateDocumentTypeRequest[];
+}
+export interface ThemePluginContributions {
+    /** Tokens only, never components — the same ThemeTokenOverrides shape
+     * the built-in Light/Dark themes use (color scales + radius, enforced
+     * structurally by @velora-cms/design-tokens). */
+    themeTokens?: ThemeTokenOverrides;
+}
+export interface IntegrationPluginContributions {
+    hooks?: PluginHooks;
+    settingsPages?: SettingsPageContribution[];
+    exposedServices?: ExposedServiceContribution[];
+    serializers?: SerializerContribution;
+}
+export interface UtilityPluginContributions {
+    dashboardWidgets?: DashboardWidgetContribution[];
+    hooks?: PluginHooks;
+    scheduledTasks?: ScheduledTaskContribution[];
+    mediaProcessors?: MediaProcessorContribution[];
+    settingsPages?: SettingsPageContribution[];
+    contentTreeActions?: ContentTreeActionContribution[];
+    editorToolbar?: EditorToolbarContribution[];
+    serializers?: SerializerContribution;
+}
+export interface BundlePluginContributions {
+    /** Plugin ids installed together — resolved by the marketplace. */
+    bundledPlugins?: string[];
+    bundledTemplate?: BundledTemplateContribution;
+}
+/** Fields shared by every plugin type. */
+export interface PluginManifestBase {
+    /** Reverse domain, e.g. 'com.yourname.googlemaps'. */
+    id: string;
+    name: string;
+    /** The plugin's own semver. */
+    version: string;
+    type: PluginType;
+    description: string;
+    author: string;
+    license: string;
+    /** Marketplace price; 0 or absent = free. */
+    price?: number;
+    /**
+     * Marketplace verification hash. Optional BY DESIGN, not oversight:
+     * per the Trust model, sideloaded/local dev plugins are unsigned by
+     * definition (Tier 2 'unverified') — only marketplace-signed plugins
+     * carry one. Signing is authenticity, not a sandbox; the safety layer
+     * is identical for both tiers.
+     */
+    signature?: string;
+    /** Semver range of compatible CMS versions, e.g. '^1.0.0'. */
+    cmsVersion: string;
+    /** Ids of plugins this one requires. */
+    pluginDependencies?: string[];
+    databaseCompatibility: DatabaseCompatibility;
+    permissions: PluginPermissions;
+    /** DB changes applied on install (through plugin storage — never raw
+     * SQL). */
+    migrations?: PluginMigration[];
+    onInstall?: () => void | Promise<void>;
+    onUninstall?: () => void | Promise<void>;
+    onActivate?: () => void | Promise<void>;
+    onDeactivate?: () => void | Promise<void>;
+    onUpdate?: (previousVersion: string) => void | Promise<void>;
+    migrationHooks?: PluginMigrationHooks;
+}
+export interface DataTypePluginManifest extends PluginManifestBase {
+    type: "datatype";
+    contributions: DataTypePluginContributions;
+}
+export interface SectionPluginManifest extends PluginManifestBase {
+    type: "section";
+    contributions: SectionPluginContributions;
+}
+export interface TemplatePluginManifest extends PluginManifestBase {
+    type: "template";
+    contributions: TemplatePluginContributions;
+}
+export interface ThemePluginManifest extends PluginManifestBase {
+    type: "theme";
+    contributions: ThemePluginContributions;
+}
+export interface IntegrationPluginManifest extends PluginManifestBase {
+    type: "integration";
+    contributions: IntegrationPluginContributions;
+}
+export interface UtilityPluginManifest extends PluginManifestBase {
+    type: "utility";
+    contributions: UtilityPluginContributions;
+}
+export interface BundlePluginManifest extends PluginManifestBase {
+    type: "bundle";
+    contributions: BundlePluginContributions;
+}
+/**
+ * The full plugin manifest — a discriminated union on `type`, so the
+ * contribution matrix is enforced by the compiler for TypeScript authors
+ * (a 'datatype' plugin declaring adminSections is a type error, not a
+ * runtime surprise). Built-ins and Module Federation remotes both
+ * register through this same contract.
+ */
+export type CMSPlugin = DataTypePluginManifest | SectionPluginManifest | TemplatePluginManifest | ThemePluginManifest | IntegrationPluginManifest | UtilityPluginManifest | BundlePluginManifest;

package/dist/manifest.js

@@ -0,0 +1,12 @@
+/** The types whose contribution-matrix rows can carry browser-rendered
+ * contributions (views, widgets, settings pages, toolbar/tree items) —
+ * exactly these ship a Module Federation client bundle
+ * (remoteEntry.js). theme/template/bundle are data-only: their packages
+ * carry manifest.json + server/plugin.js (the manifest carrier) and
+ * nothing client-side. Single source of truth for velora-plugin's
+ * build/validate, apps/server's install path, and (as a documented
+ * static mirror) the marketplace's submission checks. */
+export const CLIENT_BUNDLE_TYPES = ["datatype", "section", "integration", "utility"];
+export function hasClientBundle(type) {
+    return CLIENT_BUNDLE_TYPES.includes(type);
+}

package/dist/plugin-context.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+interface PluginValueProviderProps {
+    value: unknown;
+    onChange: (value: unknown) => void;
+    children: ReactNode;
+}
+export declare function PluginValueProvider({ value, onChange, children }: PluginValueProviderProps): import("react").JSX.Element;
+export declare function usePluginValue<T = unknown>(): {
+    value: T;
+    onChange: (value: T) => void;
+};
+interface PluginSettingsProviderProps {
+    settings: Record<string, unknown>;
+    onSettingsChange?: (settings: Record<string, unknown>) => void;
+    children: ReactNode;
+}
+export declare function PluginSettingsProvider({ settings, onSettingsChange, children }: PluginSettingsProviderProps): import("react").JSX.Element;
+export declare function usePluginSettings<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+export declare function usePluginSettingsValue<T extends Record<string, unknown> = Record<string, unknown>>(): {
+    value: T;
+    onChange: (value: T) => void;
+};
+export type PluginFetch = (input: string, init?: RequestInit) => Promise<Response>;
+interface PluginApiProviderProps {
+    fetch: PluginFetch;
+    children: ReactNode;
+}
+export declare function PluginApiProvider({ fetch, children }: PluginApiProviderProps): import("react").JSX.Element;
+export declare function usePluginApi(): PluginFetch;
+export {};

package/dist/plugin-context.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const PluginValueContext = createContext(null);
+export function PluginValueProvider({ value, onChange, children }) {
+    return _jsx(PluginValueContext.Provider, { value: { value, onChange }, children: children });
+}
+// A view calling this outside a host-rendered PluginValueProvider is a
+// real bug (the host forgot to wrap it) — throw loudly, don't hand back
+// a silently-undefined value/no-op onChange.
+export function usePluginValue() {
+    const ctx = useContext(PluginValueContext);
+    if (!ctx) {
+        throw new Error("usePluginValue must be called from a view rendered inside a PluginValueProvider");
+    }
+    return ctx;
+}
+const PluginSettingsContext = createContext(null);
+export function PluginSettingsProvider({ settings, onSettingsChange, children }) {
+    return (_jsx(PluginSettingsContext.Provider, { value: { settings, onSettingsChange }, children: children }));
+}
+// Returns settings directly (not {settings, onChange}) — this is the
+// READ-ONLY path used by input/readOnly/preview views (Session 69). For a
+// settings-EDITING view (the "settings" DataTypePluginViews slot), use
+// usePluginSettingsValue() below instead.
+export function usePluginSettings() {
+    const ctx = useContext(PluginSettingsContext);
+    if (!ctx) {
+        throw new Error("usePluginSettings must be called from a view rendered inside a PluginSettingsProvider");
+    }
+    return ctx.settings;
+}
+// Mirrors usePluginValue()'s {value, onChange} shape, for settings-EDITING
+// views only (Session 69) — the host (e.g. the Data Types editor) must
+// supply onSettingsChange via PluginSettingsProvider, or this throws:
+// a settings view rendered in a read-only context is a host bug, same
+// "throw loudly" philosophy as usePluginValue().
+export function usePluginSettingsValue() {
+    const ctx = useContext(PluginSettingsContext);
+    if (!ctx) {
+        throw new Error("usePluginSettingsValue must be called from a view rendered inside a PluginSettingsProvider");
+    }
+    if (!ctx.onSettingsChange) {
+        throw new Error("usePluginSettingsValue must be called from a settings view rendered inside a PluginSettingsProvider " +
+            "that supplies onSettingsChange (read-only contexts should use usePluginSettings() instead)");
+    }
+    return { value: ctx.settings, onChange: ctx.onSettingsChange };
+}
+const PluginApiContext = createContext(null);
+export function PluginApiProvider({ fetch, children }) {
+    return _jsx(PluginApiContext.Provider, { value: fetch, children: children });
+}
+export function usePluginApi() {
+    const ctx = useContext(PluginApiContext);
+    if (!ctx) {
+        throw new Error("usePluginApi must be called from a view rendered inside a PluginApiProvider");
+    }
+    return ctx;
+}

package/dist/registry.d.ts

@@ -0,0 +1,4 @@
+import type { DataTypePlugin } from "./data-type-plugin.js";
+export declare function registerDataType(plugin: DataTypePlugin): void;
+export declare function getDataType(id: string): DataTypePlugin | undefined;
+export declare function listDataTypes(): DataTypePlugin[];

package/dist/registry.js

@@ -0,0 +1,17 @@
+// Static registry: built-ins register into this exact same map at module
+// load (Core vs Plugin — built-ins are statically registered, dynamically
+// loaded marketplace plugins are a second registration path into this same
+// registry, not a different kind of plugin).
+const dataTypes = new Map();
+export function registerDataType(plugin) {
+    if (dataTypes.has(plugin.id)) {
+        throw new Error(`A datatype with id "${plugin.id}" is already registered`);
+    }
+    dataTypes.set(plugin.id, plugin);
+}
+export function getDataType(id) {
+    return dataTypes.get(id);
+}
+export function listDataTypes() {
+    return [...dataTypes.values()];
+}

package/dist/simple-storage-value-provider.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+interface SimpleStorageValueProviderProps {
+    contentId: string;
+    fieldId: string;
+    pluginId: string;
+    children: ReactNode;
+}
+export declare function SimpleStorageValueProvider({ contentId, fieldId, pluginId, children, }: SimpleStorageValueProviderProps): import("react").JSX.Element;
+export {};

package/dist/simple-storage-value-provider.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { PluginValueProvider, usePluginApi } from "./plugin-context.js";
+// The only SDK code path that ever hits /api/plugins/:pluginId/storage/...
+// (SimpleStorageAPI, Session 68) — a plugin's view code (and usePluginValue()
+// itself) never touches the storage API directly, matching plugin-sdk.md's
+// "SDK handles all host communication" rule. Fetches the current value on
+// mount and feeds it into the SAME PluginValueContext usePluginValue()
+// already reads, so a view wrapped in this provider is indistinguishable
+// from one wrapped in a plain PluginValueProvider — swap this in wherever a
+// field's value should live in content_field_values instead of the local
+// content blob (see document-type-form.tsx for the blob-backed default).
+//
+// Shape mirrors views/image-view.tsx's useMediaPreview(): usePluginApi(),
+// a cancelled-guarded effect, local value/error state. A GET returning
+// {value: null} is the normal "never set" state, not an error.
+export function SimpleStorageValueProvider({ contentId, fieldId, pluginId, children, }) {
+    const fetchApi = usePluginApi();
+    const [value, setValue] = useState(null);
+    const [error, setError] = useState(null);
+    const path = `/api/plugins/${pluginId}/storage/${contentId}/${fieldId}`;
+    useEffect(() => {
+        let cancelled = false;
+        setError(null);
+        fetchApi(path)
+            .then(async (response) => {
+            if (!response.ok)
+                throw new Error(`Failed to load plugin value (${response.status})`);
+            const body = (await response.json());
+            if (!cancelled)
+                setValue(body.value);
+        })
+            .catch((err) => {
+            if (!cancelled)
+                setError(err instanceof Error ? err.message : String(err));
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [fetchApi, path]);
+    function onChange(next) {
+        setValue(next); // optimistic — the view should feel instant
+        fetchApi(path, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ value: next }),
+        })
+            .then((response) => {
+            if (!response.ok)
+                throw new Error(`Failed to save plugin value (${response.status})`);
+            setError(null);
+        })
+            .catch((err) => {
+            setError(err instanceof Error ? err.message : String(err));
+        });
+    }
+    return (_jsxs(_Fragment, { children: [error && (_jsx("p", { role: "alert", className: "text-xs text-danger-600", children: error })), _jsx(PluginValueProvider, { value: value, onChange: onChange, children: children })] }));
+}

package/dist/structured-storage-types.d.ts

@@ -0,0 +1,53 @@
+export type PluginColumnType = "text" | "integer" | "boolean" | "json" | "timestamp";
+export interface PluginColumnSchema {
+    name: string;
+    type: PluginColumnType;
+    primaryKey?: boolean;
+    notNull?: boolean;
+    unique?: boolean;
+}
+export interface PluginIndexSchema {
+    columns: string[];
+    unique?: boolean;
+}
+export interface PluginTableSchema {
+    tableName: string;
+    columns: PluginColumnSchema[];
+    indexes?: PluginIndexSchema[];
+}
+export interface StructuredQueryBuilder<T = Record<string, unknown>> extends PromiseLike<T[]> {
+    where(conditions: Record<string, unknown>): this;
+    orderBy(column: string, direction?: "asc" | "desc"): this;
+    limit(n: number): this;
+    paginate(options: {
+        cursor?: string;
+        limit: number;
+    }): this;
+}
+export interface StructuredStorageTransaction {
+    insert(tableName: string, data: Record<string, unknown>): Promise<void>;
+    update(tableName: string, where: Record<string, unknown>, data: Record<string, unknown>): Promise<number>;
+    delete(tableName: string, where: Record<string, unknown>): Promise<number>;
+    query<T = Record<string, unknown>>(tableName: string): StructuredQueryBuilder<T>;
+}
+export interface ScopedStructuredStorage {
+    defineTable(schema: PluginTableSchema): Promise<void>;
+    insert(tableName: string, data: Record<string, unknown>): Promise<void>;
+    update(tableName: string, where: Record<string, unknown>, data: Record<string, unknown>): Promise<number>;
+    delete(tableName: string, where: Record<string, unknown>): Promise<number>;
+    query<T = Record<string, unknown>>(tableName: string): StructuredQueryBuilder<T>;
+    transaction(fn: (tx: StructuredStorageTransaction) => Promise<void>): Promise<void>;
+}
+export interface PublishedContent {
+    id: string;
+    documentTypeId: string;
+    data: Record<string, unknown>;
+}
+export interface PluginApiRouteContext {
+    structuredStorage: ScopedStructuredStorage;
+    /** Null if the content id doesn't exist OR isn't published (a
+     * draft-only save never satisfies this) — deliberately conflates
+     * "missing" and "not yet purchasable," since callers treat both the
+     * same way. */
+    getPublishedContent(contentId: string): Promise<PublishedContent | null>;
+}

package/dist/structured-storage-types.js

@@ -0,0 +1,11 @@
+// Local, SDK-owned duplicates of packages/db-adapter's structured-storage
+// shapes and apps/server's StructuredStorageAPI/StructuredQueryBuilder/
+// StructuredStorageTransaction classes — never imported directly, since
+// @velora-cms/plugin-sdk is a published package that must not depend on
+// unpublished adapter/server internals (same reasoning manifest.ts's
+// DatabaseDialect duplication already uses). TypeScript's structural
+// typing means the real apps/server classes satisfy these interfaces
+// without any cast, as long as their member shapes match (they do —
+// this is exactly the public contract apps/docs/src/content/docs/v1/plugin-sdk/storage.md
+// already documents).
+export {};

package/dist/views/image-view.d.ts

@@ -0,0 +1,3 @@
+export declare function ImageInputView(): import("react").JSX.Element;
+export declare function ImageSettingsView(): import("react").JSX.Element;
+export declare function ImageReadOnlyView(): import("react").JSX.Element;