@riverbankcms/sdk 0.107.0 → 0.109.0

package/dist/_dts/api/src/sdkContracts.d.ts

@@ -1,5 +1,7 @@
-import type { FieldDefinition, FieldDefinitionInput, SdkCustomBlock, SdkCustomBlockInput, SiteFooterContent, Theme } from '../../blocks/src/index';
+import type { BlockContentSource, BlockContentSourceKind, FieldDefinition, FieldDefinitionInput, SdkCustomBlock, SdkCustomBlockInput, SiteFooterContent, Theme } from '../../blocks/src/index';
+import type { ContentTypeSchema } from '../../content-model/src/index';
 import type { LinkPayload } from './navigation/types';
+import type { JsonValue } from './shared-contracts';
 import type { SdkEventPricing, SdkEventPricingInput } from './sdk-event-pricing';
 import type { SdkEventPaymentTerms, SdkEventPaymentTermsInput } from './sdk-event-payment-terms';
 /**
@@ -368,6 +370,89 @@ export interface SdkGetPageBlock {
 export interface SdkGetPageBlockResponse {
     block: SdkGetPageBlock;
 }
+/**
+ * A single PATCH operation against a block's draft content.
+ *
+ * Discriminated on `op`. Only `set` exists today; additional operations
+ * (e.g. `unset`) extend this union without breaking existing callers.
+ *
+ * `path` must resolve to a manifest-defined field of the block (dot/bracket
+ * syntax, e.g. `title`, `items[0].label`, `cta.label`). Paths that do not
+ * resolve to a manifest field — including prototype-chain segments such as
+ * `__proto__` — are rejected with a 400 naming the offending operation index.
+ *
+ * Numeric repeater indices must address an EXISTING item (strictly below the
+ * current array length). To append or resize, `set` the whole repeater field.
+ */
+export type SdkPatchPageBlockOperation = Readonly<{
+    op: 'set';
+    path: string;
+    value: JsonValue;
+}>;
+/**
+ * Body for `PATCH pages/{identifier}/blocks/{blockIdentifier}`.
+ *
+ * Operations apply atomically to an in-memory copy of the block's draft
+ * data; the result is validated once against the block manifest, then
+ * persisted in a single guarded draft write (published rows are untouched —
+ * publish remains page-boundary). Any invalid operation aborts the whole
+ * request.
+ *
+ * `baseContentHash` is required and must equal the `contentHash` returned by
+ * the block GET. On mismatch (including a concurrent write landing between
+ * read and write) the endpoint returns 409 carrying
+ * `SdkPatchPageBlockStaleContentFieldError` in `fieldErrors`.
+ */
+export interface SdkPatchPageBlockBody {
+    operations: readonly SdkPatchPageBlockOperation[];
+    baseContentHash: string;
+    /**
+     * Optional catalog-coherence precondition: the `activeTheme.selectionVersion`
+     * from `catalog/blocks`. When provided and the site's current style-selection
+     * version differs (the theme changed since the catalog was read), the write is
+     * rejected with 409 and error tag `STALE_CATALOG` instead of risking a
+     * confusing validation failure on a variant the stale catalog advertised.
+     */
+    baseSelectionVersion?: number;
+}
+export declare const SDK_PATCH_STALE_CONTENT_FIELD = "baseContentHash";
+export declare const SDK_PATCH_STALE_CONTENT_CODE = "STALE_CONTENT";
+/**
+ * Typed stale-conflict detail for block PATCH 409 responses, transported in
+ * the standard envelope's `fieldErrors`. `message` is EXACTLY the current
+ * draft content hash (no prose) — echo it back as `baseContentHash` to
+ * retry. The SDK client surfaces this as a discriminated
+ * `BlockPatchStaleContentError` so callers never string-sniff.
+ */
+export interface SdkPatchPageBlockStaleContentFieldError {
+    field: typeof SDK_PATCH_STALE_CONTENT_FIELD;
+    code: typeof SDK_PATCH_STALE_CONTENT_CODE;
+    /** Exactly the current draft content hash. */
+    message: string;
+}
+/**
+ * Non-blocking warning emitted on a block write. Currently used for button-variant
+ * values that ARE valid manifest options but the ACTIVE theme does not implement:
+ * the write is accepted (themes can change under content), but the variant will not
+ * render until a personality that provides it is selected.
+ */
+export interface SdkBlockContentWarning {
+    /** Data path of the value (e.g. `ctas[0].variant`). */
+    field: string;
+    code: 'theme-unavailable-variant';
+    message: string;
+    /** The offending value. */
+    value: string;
+}
+/**
+ * Success response mirrors the block GET shape; `block.contentHash` is the
+ * NEW draft content hash (use it as `baseContentHash` for the next patch).
+ */
+export interface SdkPatchPageBlockResponse {
+    block: SdkGetPageBlock;
+    /** Non-blocking content warnings (e.g. theme-unavailable button variants). */
+    warnings?: SdkBlockContentWarning[];
+}
 export interface SdkPullNavigationItem {
     id: string;
     menuId: string;
@@ -387,6 +472,7 @@ export interface SdkPullNavigationMenu {
     name: string;
     isPrimary: boolean;
     isFooter: boolean;
+    footerRole: 'main' | 'legal-policy' | null;
     items: SdkPullNavigationItem[];
     createdAt: string;
     updatedAt: string;
@@ -396,6 +482,8 @@ export interface SdkPullNavigationResponse {
     meta: SdkPullMeta;
 }
 export interface SdkPullSettings {
+    /** Site title (stored on `sites.title`). Present on pull; writable via PATCH. */
+    siteTitle?: string;
     homepageId: string | null;
     seoDefaults: {
         title?: string;
@@ -463,6 +551,223 @@ export interface SdkPullThemeResponse {
     selectionVersion: number;
     meta: SdkPullThemeMeta;
 }
+/** One curated-style recommendation choice; the catalog lists them in preference order. */
+export interface SdkCatalogChoice {
+    id: string;
+    note?: string;
+}
+export interface SdkCatalogHeaderLayoutStyleChoice {
+    layoutId: string;
+    styleId: string;
+}
+export interface SdkCatalogSiteStyle {
+    id: string;
+    name: string;
+    description: string;
+    /** Button personality recommendations in preference order (first = default). */
+    buttonPersonalityChoices: SdkCatalogChoice[];
+    defaultButtonPersonalityId: string;
+    /** Curated palette recommendations (value-keys) in preference order (first = default). */
+    paletteRecommendations: SdkCatalogChoice[];
+    defaultPaletteValueKey: string;
+    /**
+     * Concrete typography the style applies. NOTE: current theme-core carries a resolved
+     * `typography` object per style, not a preset-choice list (see deviation notes).
+     */
+    typography: Theme['typography'];
+    /** Canonical header layout+style pair (replaces the older single `defaultHeaderSelection` look id). */
+    defaultHeaderSelection: SdkCatalogHeaderLayoutStyleChoice;
+    recommendedHeaderLookIds: string[];
+    recommendedFooterLookIds: string[];
+}
+export interface SdkCatalogButtonPersonality {
+    id: string;
+    name: string;
+    description: string;
+    /** Enabled variant ids this personality provides. */
+    variantIds: string[];
+}
+export interface SdkCatalogPalette {
+    /** Human-readable source alias. */
+    authoringKey: string;
+    /** Canonical persistence/runtime identity (colors+mode hash). */
+    valueKey: string;
+    name: string;
+    description: string;
+    mode: string;
+}
+export interface SdkCatalogTypographyPreset {
+    /** Recipe id: `serif-editorial` | `clean-sans` | `classic-serif` | `friendly-sans`. */
+    id: string;
+    /** Concrete typography this preset resolves to. */
+    typography: Theme['typography'];
+}
+/**
+ * The site's current resolved selection, so one catalog read primes an apply.
+ * Carries everything the apply endpoint requires — including `siteStyleId`
+ * (read from the active compiled theme). This is the single wire shape;
+ * services map to it explicitly (no structural pass-through of domain rows).
+ */
+export interface SdkCatalogCurrentSelection {
+    /** Pass as `baseSelectionVersion` on apply; 0 when no selection exists. */
+    selectionVersion: number;
+    /** The curated site style the active theme was compiled from (null when unknown). */
+    siteStyleId: string | null;
+    buttonPersonalityId: string | null;
+    paletteValueKey: string | null;
+    headerLayoutId: string | null;
+    headerStyleId: string | null;
+    headerLookId: string | null;
+    footerLookId: string | null;
+    typographyPresetId: string | null;
+}
+export interface SdkCatalogThemeResponse {
+    siteStyles: SdkCatalogSiteStyle[];
+    buttonPersonalities: SdkCatalogButtonPersonality[];
+    palettes: SdkCatalogPalette[];
+    typographyPresets: SdkCatalogTypographyPreset[];
+    headerLookIds: string[];
+    footerLookIds: string[];
+    headerLayoutIds: string[];
+    headerStyleIds: string[];
+    currentSelection: SdkCatalogCurrentSelection;
+    meta: SdkPullMeta;
+}
+/**
+ * Content-source classification, derived DIRECTLY from the blocks package's
+ * authoring type (`BlockContentSource` / `blockContentSourceKinds`) so the wire
+ * union can never drift from what block definitions declare.
+ */
+export type SdkCatalogContentSourceKind = BlockContentSourceKind;
+export type SdkCatalogContentSource = BlockContentSource;
+export interface SdkCatalogSelectOption {
+    value: string;
+    label: string;
+}
+export interface SdkCatalogField {
+    id: string;
+    type: string;
+    label?: string;
+    required: boolean;
+    /** Present for `select` fields. */
+    options?: SdkCatalogSelectOption[];
+    /** Present for container fields (group/repeater/tabGroup/modal). */
+    fields?: SdkCatalogField[];
+}
+/** Machine-readable reason a manifest variant option is not currently renderable. */
+export type SdkCatalogVariantUnavailableReason = 'not-implemented-by-personality';
+/** Where a resolved variant value originates. */
+export type SdkCatalogVariantSource = 'manifest' | 'theme' | 'both';
+/**
+ * One button-variant option, discriminated on `availability`:
+ * - `available`   — the active theme implements it (never carries a reason).
+ * - `unavailable` — a manifest option the active theme does NOT implement;
+ *                   always carries a machine-readable `reason`. Writes accept it
+ *                   with a warning.
+ * - `unknown`     — the site has no active theme/button system, so availability
+ *                   cannot be determined; only manifest options appear.
+ */
+export type SdkCatalogVariantOption = Readonly<{
+    value: string;
+    availability: 'available';
+    source: SdkCatalogVariantSource;
+}> | Readonly<{
+    value: string;
+    availability: 'unavailable';
+    source: 'manifest';
+    reason: SdkCatalogVariantUnavailableReason;
+}> | Readonly<{
+    value: string;
+    availability: 'unknown';
+    source: 'manifest';
+}>;
+export interface SdkCatalogVariantAvailability {
+    /** Structural field-id path of the button-variant field (e.g. `ctas.variant`). */
+    fieldPath: string;
+    variants: SdkCatalogVariantOption[];
+}
+export interface SdkCatalogBlock {
+    identifier: string;
+    title: string;
+    category?: string;
+    contentSource: SdkCatalogContentSource;
+    fields: SdkCatalogField[];
+    /** Button-variant availability against the active theme (shared resolver). */
+    variantAvailability: SdkCatalogVariantAvailability[];
+}
+/**
+ * The active-theme context the blocks catalog was computed against. `selectionVersion`
+ * doubles as an optional write precondition: pass it as `baseSelectionVersion` on block
+ * upsert/PATCH to fail loudly (409, tag `STALE_CATALOG`) if the theme changed since
+ * the catalog was read — a catalog-advertised theme-only variant may otherwise be
+ * rejected after a mid-air theme change.
+ */
+export type SdkCatalogActiveTheme = Readonly<{
+    state: 'active';
+    selectionVersion: number;
+}> | Readonly<{
+    state: 'none';
+}>;
+export interface SdkCatalogBlocksResponse {
+    blocks: SdkCatalogBlock[];
+    /** Theme context the variant availability was computed against. */
+    activeTheme: SdkCatalogActiveTheme;
+    meta: SdkPullMeta;
+}
+export interface SdkCatalogContentType {
+    key: string;
+    name: string;
+    hasPages: boolean;
+    routePattern: string | null;
+    isSingleton: boolean;
+    /** Normalized stored field DSL (NOT generated JSON Schema). */
+    schema: ContentTypeSchema;
+}
+export interface SdkCatalogContentTypesResponse {
+    contentTypes: SdkCatalogContentType[];
+    meta: SdkPullMeta;
+}
+export interface SdkCapabilityCatalogLink {
+    /** Relative path under `/api/sdk/{siteId}`. */
+    path: string;
+    /** Stable content hash of the catalog body, for caching + drift detection. */
+    contentHash: string;
+}
+export interface SdkCapabilitiesResponse {
+    apiVersion: string;
+    catalogs: {
+        theme: SdkCapabilityCatalogLink;
+        blocks: SdkCapabilityCatalogLink;
+        contentTypes: SdkCapabilityCatalogLink;
+    };
+    meta: SdkPullMeta;
+}
+/** One provenance ledger row: a resource a demo recipe run created/linked on this site. */
+export interface SdkDemoSeedProvenanceEntry {
+    id: string;
+    /** The recipe run that created/linked the resource. */
+    runId: string;
+    /** The command ref within the run (e.g. `content:testimonial-ava`). */
+    commandKey: string;
+    /** The command type (e.g. `upsertContentEntry`). */
+    commandType: string;
+    /** Closed resource kind (e.g. `content`, `customer`, `page`, `staff`). */
+    resourceKind: string;
+    /** The recipe resource ref (e.g. `content:testimonial-ava`). */
+    resourceRef: string;
+    /** The concrete resource id. */
+    resourceId: string;
+    /**
+     * `created` — the run authored this resource (a cleanup candidate);
+     * `existing` — the run only linked/configured a pre-existing resource.
+     */
+    disposition: 'created' | 'existing';
+    createdAt: string;
+}
+export interface SdkDemoContentResponse {
+    items: SdkDemoSeedProvenanceEntry[];
+    meta: SdkPullMeta;
+}
 export interface SdkPullFooterMeta extends SdkPullMeta {
     updatedAt: string | null;
 }
@@ -763,6 +1068,8 @@ export interface SdkPullDraftsResponse {
 }
 export interface SdkUpsertBlockResponse {
     block: SdkManagementBlock;
+    /** Non-blocking content warnings (e.g. theme-unavailable button variants). */
+    warnings?: SdkBlockContentWarning[];
 }
 export interface SdkDeleteResponse {
     deleted: true;
@@ -882,6 +1189,7 @@ export interface SdkUpsertNavigationMenuResponse {
         name: string;
         isPrimary: boolean;
         isFooter: boolean;
+        footerRole: 'main' | 'legal-policy' | null;
         items: SdkPullNavigationItem[];
         createdAt: string;
         updatedAt: string;

package/dist/_dts/api/src/siteBanner.d.ts

@@ -89,8 +89,8 @@ export declare const siteBannerSettingsSchema: z.ZodDiscriminatedUnion<[z.ZodObj
             routeId: z.ZodString;
             entityId: z.ZodString;
             entityType: z.ZodEnum<{
-                page: "page";
                 content: "content";
+                page: "page";
             }>;
             href: z.ZodString;
             title: z.ZodString;
@@ -155,8 +155,8 @@ export declare const siteBannerSettingsInputSchema: z.ZodDiscriminatedUnion<[z.Z
             routeId: z.ZodString;
             entityId: z.ZodString;
             entityType: z.ZodEnum<{
-                page: "page";
                 content: "content";
+                page: "page";
             }>;
             href: z.ZodString;
             title: z.ZodString;

package/dist/_dts/api/src/siteInfrastructure.d.ts

@@ -250,11 +250,16 @@ export type CreateSitePreviewKeyResponse = {
     keyId: string;
     message: string;
 };
+/** Access mode for a management API key: read-only or full write access. */
+export type ManagementKeyAccessMode = 'read' | 'write';
 export type ManagementKeyRecord = {
     id: string;
     name: string | null;
     keyPrefix: string;
     keyHint: string | null;
+    accessMode: ManagementKeyAccessMode;
+    /** ISO timestamp when the key expires, or null if it never expires. */
+    expiresAt: string | null;
     createdAt: string;
     lastUsedAt: string | null;
 };
@@ -263,10 +268,18 @@ export type ListManagementKeysResponse = {
 };
 export type CreateManagementKeyRequest = {
     name?: string;
+    /** Defaults to 'write' when omitted (preserves prior all-access behavior). */
+    accessMode?: ManagementKeyAccessMode;
+    /** Optional ISO timestamp; must be in the future. Null/omitted = never expires. */
+    expiresAt?: string | null;
 };
 export type CreateManagementKeyResponse = {
     key: string;
     keyId: string;
+    /** Normalized access mode the key was issued with. */
+    accessMode: ManagementKeyAccessMode;
+    /** Normalized expiry (ISO) or null when the key never expires. */
+    expiresAt: string | null;
     message: string;
 };
 export type RevokeManagementKeyRequest = {