@riverbankcms/sdk 0.107.0 → 0.109.0

package/dist/_dts/content-model/src/content-types/scaffold.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Entry scaffold emitter.
+ *
+ * Produces a MACHINE-READABLE template for a content type from its normalized
+ * field DSL ({@link ContentTypeSchema}): required fields are stubbed with explicit
+ * placeholder sentinels (`"<REQUIRED: text>"`, `"<REQUIRED: media-identifier>"`, …
+ * per field type, from the shared vocabulary in `sentinels.ts`), optional fields
+ * are omitted.
+ *
+ * The `diagnostics` list is derived from the entry-instance {@link
+ * validateEntryInstance} run against the emitted template, so it can never drift
+ * from what the validator actually rejects — plus a sentinel sweep so every
+ * emitted placeholder is reported even where the schema-walk can't recurse.
+ *
+ * This is NOT itself a validator: an unfilled template is not upsert-valid. The
+ * contract is: replace every placeholder with a valid value and `entry upsert`
+ * accepts the result without structural edits (enforced by the validator, used
+ * both here and as a CLI pre-flight).
+ */
+import type { ContentTypeSchema } from './schema';
+/** Which existing site resource a field points at (must exist before upsert). */
+export type ScaffoldResourceKind = 'media' | 'file' | 'reference';
+/** One required field an agent must fill before the template is upsert-valid. */
+export interface EntryScaffoldDiagnostic {
+    /** Dotted path to the field within the entry data (e.g. `hero.cta.link`). */
+    path: string;
+    /** The field's DSL type. */
+    fieldType: string;
+    /** The site resource this field references, when applicable. */
+    needsResource?: ScaffoldResourceKind;
+    /** Short instruction for the agent. */
+    message: string;
+}
+export interface EntryScaffold {
+    /** Content-type key the template was generated for. */
+    contentType: string;
+    /**
+     * Template with required fields stubbed with placeholder sentinels and optional
+     * fields omitted. Replace every sentinel with a valid value before upsert.
+     */
+    template: Record<string, unknown>;
+    /** Required fields to fill, and which of them need existing site resources. */
+    diagnostics: EntryScaffoldDiagnostic[];
+    /**
+     * True when the template contains no placeholders (the type has no required
+     * fields) — such a template can be upserted structurally as-is.
+     */
+    ready: boolean;
+}
+/**
+ * Emit a placeholder template + diagnostics for a content type from its field DSL.
+ * Diagnostics come from the entry-instance validator run against the template,
+ * merged with a sentinel sweep so no emitted placeholder goes unreported.
+ */
+export declare function buildEntryScaffold(input: {
+    key: string;
+    schema: ContentTypeSchema;
+}): EntryScaffold;

package/dist/_dts/content-model/src/content-types/schema.d.ts

@@ -8,11 +8,11 @@ declare const BaseContentFieldSchema: z.ZodObject<{
         number: "number";
         boolean: "boolean";
         date: "date";
+        url: "url";
         text: "text";
         textarea: "textarea";
         select: "select";
         link: "link";
-        url: "url";
         file: "file";
         media: "media";
         reference: "reference";

package/dist/_dts/content-model/src/content-types/sentinels.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Placeholder sentinel vocabulary — the SINGLE source of truth shared by the
+ * scaffold emitter and the entry-instance validator so the two can never drift.
+ *
+ * Every sentinel is a string of the closed form `"<REQUIRED: …>"`. The emitter
+ * produces them with {@link buildSentinel}; the validator rejects any value the
+ * shared {@link isPlaceholderSentinel} predicate recognizes. Both sides import
+ * from here, so adding a field type or changing the shape updates both at once.
+ */
+import type { ContentFieldConfig } from './schema';
+/** Leaf field types that receive a placeholder sentinel (containers recurse). */
+export declare const SENTINEL_LEAF_TYPES: readonly ["text", "textarea", "richText", "number", "date", "datetime", "url", "link", "media", "file", "boolean", "select", "reference"];
+export type SentinelLeafType = (typeof SENTINEL_LEAF_TYPES)[number];
+/** Matches the closed sentinel shape `"<REQUIRED: …>"`. */
+export declare const SENTINEL_PATTERN: RegExp;
+/**
+ * True when a value is an unfilled placeholder sentinel. Shared by the emitter
+ * (self-check) and the validator (rejection) so recognition can't drift.
+ */
+export declare function isPlaceholderSentinel(value: unknown): value is string;
+/**
+ * The placeholder sentinel for a leaf field. Container types (group/button/
+ * repeater) do not have a leaf sentinel — they expand structurally — and calling
+ * this for them returns a generic marker only for completeness.
+ */
+export declare function buildSentinel(field: ContentFieldConfig): string;
+/** A placeholder sentinel found in entry data, with its dotted path. */
+export interface UnfilledSentinel {
+    path: string;
+    value: string;
+}
+/**
+ * Deep-scan arbitrary entry data for any unfilled placeholder sentinels. Needs no
+ * schema, so it powers the CLI's pre-HTTP upsert pre-flight.
+ */
+export declare function findUnfilledSentinels(data: unknown, pathPrefix?: string): UnfilledSentinel[];

package/dist/_dts/content-model/src/definitions/shared.d.ts

@@ -38,6 +38,9 @@ type SnapshotDefaults = {
     slug?: string | null;
 };
 export declare function createSnapshotFromContentEntry<TStatus extends string = string>(data: ContentEntryLike, routing: RoutingHelpers, defaults: SnapshotDefaults, titleField?: string | null): ContentEntrySnapshot<TStatus>;
+export declare function createSnapshotFromRoutableContent<TStatus extends string = string>(owner: Readonly<{
+    id: string;
+}>, route: NonNullable<ContentEntryLike["route"]>, routing: RoutingHelpers, defaults: SnapshotDefaults): RoutableContentSnapshot<TStatus>;
 type PageRecordLike = {
     id: string;
     draftTitle?: string | null;

package/dist/_dts/content-model/src/index.d.ts

@@ -7,6 +7,9 @@ export * from './routeTemplate';
 export * from './definitions/canonicalizePageRouteMetadata';
 export * from './definitions/shared';
 export * from './content-types/schema';
+export * from './content-types/sentinels';
+export * from './content-types/entryValidation';
+export * from './content-types/scaffold';
 export * from './content-types/defaults';
 export * from './content-types/builtins';
 export * from './content-types/builtin-schemas';

package/dist/_dts/core/src/booking-date-time.d.ts

@@ -108,6 +108,14 @@ export declare function toScheduledBookingDateRange(input: BookingRangeFormatInp
 export declare function formatBookingInstant(isoString: string, options: BookingInstantFormatOptions): string;
 export declare function formatBookingDate(input: ScheduledBookingDateTime, format?: Intl.DateTimeFormatOptions): string;
 export declare function formatBookingTime(input: ScheduledBookingDateTime, format?: Intl.DateTimeFormatOptions): string;
+/**
+ * Formats the compact English event-time presentation used by public surfaces.
+ *
+ * This intentionally owns the lowercase day-period token and zero-minute
+ * omission instead of depending on locale-specific spacing or punctuation.
+ * Callers must only use it for an English presentation contract.
+ */
+export declare function formatBookingCompactEnglishTime(input: ScheduledBookingDateTime): string;
 export declare function formatBookingDateTime(input: ScheduledBookingDateTime, format?: Intl.DateTimeFormatOptions): string;
 export declare function formatBookingDateParts(input: ScheduledBookingDateRange, options?: Readonly<{
     dateFormat?: Intl.DateTimeFormatOptions;

package/dist/_dts/core/src/branded.d.ts

@@ -96,6 +96,7 @@ export type BookingCalendarFeedTokenPublicId = Brand<string, 'BookingCalendarFee
 export type BookingCalendarFeedTokenSecret = Brand<string, 'BookingCalendarFeedTokenSecret'>;
 export type BookingCalendarFeedTokenSecretHash = Brand<string, 'BookingCalendarFeedTokenSecretHash'>;
 export type ContentEntryId = Brand<string, 'ContentEntryId'>;
+export type ContentBlockId = Brand<string, 'ContentBlockId'>;
 export type ContentVersionId = Brand<string, 'ContentVersionId'>;
 export type EntryContentHash = Brand<string, 'EntryContentHash'>;
 export type StripeInvoiceId = Brand<string, 'StripeInvoiceId'>;
@@ -230,6 +231,7 @@ export declare const unsafeAsBookingCalendarFeedTokenPublicId: (id: string) => B
 export declare const unsafeAsBookingCalendarFeedTokenSecret: (value: string) => BookingCalendarFeedTokenSecret;
 export declare const unsafeAsBookingCalendarFeedTokenSecretHash: (value: string) => BookingCalendarFeedTokenSecretHash;
 export declare const unsafeAsContentEntryId: (id: string) => ContentEntryId;
+export declare const unsafeAsContentBlockId: (id: string) => ContentBlockId;
 export declare const unsafeAsContentVersionId: (id: string) => ContentVersionId;
 export declare const unsafeAsEntryContentHash: (value: string) => EntryContentHash;
 export declare const unsafeAsStripeInvoiceId: (id: string) => StripeInvoiceId;
@@ -280,6 +282,7 @@ export declare const parseProductVariantId: (value: unknown) => Result<ProductVa
 export declare const parseProductCategoryId: (value: unknown) => Result<ProductCategoryId, BrandedIdParseError>;
 export declare const parseMediaAssetId: (value: unknown) => Result<MediaAssetId, BrandedIdParseError>;
 export declare const parseContentEntryId: (value: unknown) => Result<ContentEntryId, BrandedIdParseError>;
+export declare const parseContentBlockId: (value: unknown) => Result<ContentBlockId, BrandedIdParseError>;
 export declare const parseContentVersionId: (value: unknown) => Result<ContentVersionId, BrandedIdParseError>;
 export declare const parseNavigationMenuId: (value: unknown) => Result<NavigationMenuId, BrandedIdParseError>;
 export declare const parseNavigationItemId: (value: unknown) => Result<NavigationItemId, BrandedIdParseError>;

package/dist/_dts/core/src/editor-state.d.ts

@@ -27,6 +27,7 @@ export type EditorStructuralDraftMeta = Readonly<{
     purpose: string | null;
     orderIndex: number | null;
     publishedContent: EditorBlockValues | null;
+    optimisticHash: string | null;
 }>;
 export type EditorStructuralDraftSnapshot = Readonly<{
     id: EditorBlockId;
@@ -45,12 +46,14 @@ export type EditorDraftBlockInitMetaInput = Readonly<{
     purpose?: string | null;
     orderIndex?: number | null;
     publishedContent?: EditorBlockBaselineInput;
+    optimisticHash?: string | null;
 }>;
 export type EditorDraftBlockBaselineUpdateMetaInput = Readonly<{
     kind?: string;
     purpose?: string | null;
     orderIndex?: number | null;
     publishedContent?: EditorBlockBaselineInput;
+    optimisticHash?: string | null;
 }>;
 export type EditorBlockPublishedBaselineInput = Readonly<{
     id: EditorBlockId;
@@ -66,6 +69,7 @@ export type EditorPersistedBlock = Readonly<{
     publishedContent: EditorBlockValues | null;
     bindings: EditorBlockValues | null;
     purpose: string | null;
+    optimisticHash: string | null;
 }>;
 export type EditorInsertBlockCommand = Readonly<{
     type: 'insert-block';

package/dist/_dts/core/src/footer-composition.d.ts

@@ -0,0 +1,143 @@
+import type { Brand } from './branded';
+import { type Result } from './result';
+export type FooterModuleId = Brand<string, 'FooterModuleId'>;
+export type FooterMembershipKey = Brand<string, 'FooterMembershipKey'>;
+export type FooterRichText = Readonly<Record<string, unknown>>;
+export type FooterNavigationRole = 'main' | 'legal-policy';
+type FooterSectionBase<TKind extends string> = Readonly<{
+    id: FooterModuleId;
+    kind: TKind;
+    heading: string | null;
+    selected: boolean;
+}>;
+export type FooterSection = (FooterSectionBase<'brand'> & Readonly<{
+    showLogo: boolean;
+    showTitle: boolean;
+}>) | (FooterSectionBase<'navigation'> & Readonly<{
+    source: Readonly<{
+        kind: 'menu-role';
+        role: 'main';
+    }>;
+}>) | (FooterSectionBase<'legal-navigation'> & Readonly<{
+    source: Readonly<{
+        kind: 'menu-role';
+        role: 'legal-policy';
+    }>;
+}>) | (FooterSectionBase<'business-address'> & Readonly<{
+    source: Readonly<{
+        kind: 'business-address';
+    }>;
+}>) | (FooterSectionBase<'contact'> & Readonly<{
+    source: Readonly<{
+        kind: 'public-profile';
+    }>;
+}>) | (FooterSectionBase<'opening-hours'> & Readonly<{
+    source: Readonly<{
+        kind: 'public-profile';
+    }>;
+}>) | (FooterSectionBase<'social-links'> & Readonly<{
+    source: Readonly<{
+        kind: 'public-profile';
+    }>;
+}>) | (FooterSectionBase<'supporting-text'> & Readonly<{
+    content: FooterRichText | null;
+}>) | (FooterSectionBase<'legal'> & Readonly<{
+    content: FooterRichText | null;
+}>);
+/** Retained as a source-compatible name while callers move from modules to sections. */
+export type FooterModule = FooterSection;
+export type FooterModuleKind = FooterSection['kind'];
+export type FooterCompositionV1 = Readonly<{
+    schemaVersion: 1;
+    sections: readonly FooterSection[];
+}>;
+export type FooterCompositionError = Readonly<{
+    code: 'invalid_shape' | 'unsupported_schema_version' | 'invalid_section' | 'duplicate_section_id' | 'duplicate_section_kind' | 'unknown_section';
+    path: string;
+    message: string;
+}>;
+export type FooterLookPolicy = Readonly<{
+    kind: 'integrated-legal';
+}> | Readonly<{
+    kind: 'separate-legal-region';
+}>;
+export type FooterVisualGroupKind = 'identity' | 'main-navigation' | 'visit' | 'legal-ending';
+export type FooterColumnCount = 1 | 2 | 3 | 4;
+export type FooterVisualGroup = Readonly<{
+    kind: FooterVisualGroupKind;
+    sections: readonly FooterSection[];
+    span: 1;
+}>;
+export type FooterRenderRegion = Readonly<{
+    kind: 'main' | 'bottom';
+    columns: FooterColumnCount;
+    groups: readonly FooterVisualGroup[];
+}>;
+export type FooterArrangementPlan = Readonly<{
+    membershipKey: FooterMembershipKey;
+    regions: readonly FooterRenderRegion[];
+    mobileGroups: readonly FooterVisualGroup[];
+}>;
+export type FooterRepairTarget = Readonly<{
+    kind: 'site-identity';
+}> | Readonly<{
+    kind: 'navigation';
+    role: FooterNavigationRole;
+}> | Readonly<{
+    kind: 'business-address';
+}> | Readonly<{
+    kind: 'public-profile';
+    section: 'contact' | 'opening-hours' | 'social-links';
+}> | Readonly<{
+    kind: 'footer-section';
+    sectionId: FooterModuleId;
+}>;
+export type ResolvedFooterSection = Readonly<{
+    kind: 'renderable';
+    section: FooterSection;
+}> | Readonly<{
+    kind: 'missing-source';
+    section: FooterSection;
+    repairTarget: FooterRepairTarget;
+}>;
+export type RenderableFooterSection = Extract<ResolvedFooterSection, {
+    kind: 'renderable';
+}>;
+export type FooterSourceAvailability = Readonly<{
+    hasLogo: boolean;
+    hasMainNavigation: boolean;
+    hasLegalPolicyNavigation: boolean;
+    hasBusinessAddress: boolean;
+    hasContact: boolean;
+    hasOpeningHours: boolean;
+    hasSocialLinks: boolean;
+}>;
+export declare function unsafeAsFooterModuleId(value: string): FooterModuleId;
+export declare function parseFooterModuleId(value: unknown): Result<FooterModuleId, FooterCompositionError>;
+export declare function validateFooterComposition(composition: FooterCompositionV1): Result<FooterCompositionV1, FooterCompositionError>;
+export declare function parseFooterCompositionV1(value: unknown): Result<FooterCompositionV1, FooterCompositionError>;
+/**
+ * Bounded pre-production upgrader for the placement-shaped V1 that never reached production.
+ * It is intentionally not called by the runtime parser.
+ */
+export declare function upgradePlacementFooterCompositionV1(value: unknown): Result<FooterCompositionV1, FooterCompositionError>;
+export declare function setFooterSectionSelected(composition: FooterCompositionV1, sectionId: FooterModuleId, selected: boolean): Result<FooterCompositionV1, FooterCompositionError>;
+export declare function resolveFooterSections(composition: FooterCompositionV1, availability: FooterSourceAvailability): readonly ResolvedFooterSection[];
+export declare function planFooterArrangement(renderableSections: readonly RenderableFooterSection[], policy: FooterLookPolicy): FooterArrangementPlan;
+export type FooterEditorOverviewItem = Readonly<{
+    section: FooterSection;
+    status: 'selected' | 'available';
+}>;
+export declare function deriveFooterEditorOverview(composition: FooterCompositionV1): Readonly<{
+    selected: readonly FooterEditorOverviewItem[];
+    available: readonly FooterEditorOverviewItem[];
+}>;
+type LegacyFooterNormalizationOptions = Readonly<{
+    brand?: Readonly<{
+        showLogo: boolean;
+        showTitle: boolean;
+    }>;
+    footerVisible?: boolean;
+}>;
+export declare function normalizeLegacyFooterContentToV1(value: unknown, options?: LegacyFooterNormalizationOptions): Result<FooterCompositionV1, FooterCompositionError>;
+export {};

package/dist/_dts/core/src/index.d.ts

@@ -29,6 +29,8 @@ export * from './assertNever';
 export * from './participants';
 export * from './participant-identity';
 export * from './public-url-validation';
+export * from './public-profile';
+export * from './footer-composition';
 export * from './number-input';
 export * from './field-errors';
 export * from './form-submission-preview';

package/dist/_dts/core/src/public-profile.d.ts

@@ -0,0 +1,73 @@
+import type { Brand } from './branded';
+import { type Result } from './result';
+export type PublicProfileTimeZone = Brand<string, 'PublicProfileTimeZone'>;
+export type OpeningHoursTime = Brand<string, 'OpeningHoursTime'>;
+export type PublicSocialLinkId = Brand<string, 'PublicSocialLinkId'>;
+export declare const publicProfileWeekdays: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+export type PublicProfileWeekday = (typeof publicProfileWeekdays)[number];
+export declare const knownSocialPlatforms: readonly ["facebook", "instagram", "linkedin", "tiktok", "x", "youtube"];
+export type KnownSocialPlatform = (typeof knownSocialPlatforms)[number];
+export type PublicContactDetails = Readonly<{
+    kind: 'phone';
+    phone: string;
+    email: null;
+}> | Readonly<{
+    kind: 'email';
+    phone: null;
+    email: string;
+}> | Readonly<{
+    kind: 'phone-and-email';
+    phone: string;
+    email: string;
+}>;
+export type OpeningHoursInterval = Readonly<{
+    opensAt: OpeningHoursTime;
+    closesAt: OpeningHoursTime;
+}>;
+export type OpeningHoursDay = Readonly<{
+    kind: 'closed';
+    weekday: PublicProfileWeekday;
+}> | Readonly<{
+    kind: 'open';
+    weekday: PublicProfileWeekday;
+    intervals: readonly [OpeningHoursInterval, ...OpeningHoursInterval[]];
+}>;
+export type WeeklyOpeningHours = Readonly<{
+    timeZone: PublicProfileTimeZone;
+    days: readonly [
+        OpeningHoursDay,
+        OpeningHoursDay,
+        OpeningHoursDay,
+        OpeningHoursDay,
+        OpeningHoursDay,
+        OpeningHoursDay,
+        OpeningHoursDay
+    ];
+}>;
+export type PublicSocialLink = Readonly<{
+    id: PublicSocialLinkId;
+    kind: 'known';
+    platform: KnownSocialPlatform;
+    url: string;
+}> | Readonly<{
+    id: PublicSocialLinkId;
+    kind: 'custom';
+    label: string;
+    url: string;
+}>;
+export type PublicProfile = Readonly<{
+    contact: PublicContactDetails | null;
+    openingHours: WeeklyOpeningHours | null;
+    socialLinks: readonly PublicSocialLink[];
+}>;
+export type PublicProfileParseError = Readonly<{
+    code: 'invalid_shape' | 'contact_method_required' | 'invalid_email' | 'invalid_phone' | 'invalid_timezone' | 'invalid_weekdays' | 'invalid_time' | 'invalid_interval' | 'overlapping_intervals' | 'invalid_social_link' | 'duplicate_social_link_id';
+    path: string;
+    message: string;
+}>;
+export declare function parsePublicContactDetails(value: unknown): Result<PublicContactDetails, PublicProfileParseError>;
+export declare function parsePublicProfileTimeZone(value: unknown): Result<PublicProfileTimeZone, PublicProfileParseError>;
+export declare function parseWeeklyOpeningHours(value: unknown): Result<WeeklyOpeningHours, PublicProfileParseError>;
+export declare function parsePublicSocialLinks(value: unknown): Result<readonly PublicSocialLink[], PublicProfileParseError>;
+export declare function parsePublicProfile(value: unknown): Result<PublicProfile, PublicProfileParseError>;
+export declare function emptyPublicProfile(): PublicProfile;