@riverbankcms/sdk 0.77.1 → 0.78.2

package/dist/_dts/sdk/src/next/content-load-failure.d.ts

@@ -0,0 +1,51 @@
+export { RiverbankContentLoadError } from '../routing/resolvePageContent';
+import { RiverbankContentLoadError } from '../routing/resolvePageContent';
+export type SdkContentLoadFailureKind = 'timeout' | 'network' | 'http_5xx' | 'http_non_404' | 'circuit_open' | 'aborted' | 'unknown';
+export type SdkContentLoadNotFound = Readonly<{
+    kind: 'not_found';
+    status: 404;
+    message: string;
+    upstreamCode?: string;
+    requestId?: string;
+}>;
+export type SdkContentLoadFailure = Readonly<{
+    kind: SdkContentLoadFailureKind;
+    message: string;
+    status?: number;
+    upstreamCode?: string;
+    requestId?: string;
+    retryAfterMs?: number;
+}>;
+export type ClassifiedContentLoadError = SdkContentLoadNotFound | Readonly<{
+    kind: 'upstream_failed';
+    failure: SdkContentLoadFailure;
+}>;
+export type CatchAllRequestContext = Readonly<{
+    host?: string;
+    requestId?: string;
+    correlationId?: string;
+    monitorRunId?: string;
+}>;
+export type CatchAllContentLoadFailureContext = Readonly<{
+    siteId: string;
+    path: string;
+    preview: boolean;
+    sdkVersion: string;
+    failure: SdkContentLoadFailure;
+    requestContext?: CatchAllRequestContext;
+}>;
+export type SdkContentLoadError = RiverbankContentLoadError & {
+    readonly context: CatchAllContentLoadFailureContext;
+};
+export declare const SdkContentLoadError: typeof RiverbankContentLoadError;
+export declare function isSdkContentLoadError(error: unknown): error is SdkContentLoadError;
+export declare function classifyContentLoadError(error: unknown): ClassifiedContentLoadError;
+export declare function createSdkContentLoadError(input: {
+    siteId: string;
+    path: string;
+    preview: boolean;
+    failure: SdkContentLoadFailure;
+    requestContext?: CatchAllRequestContext;
+    cause?: unknown;
+}): SdkContentLoadError;
+export declare function toContentLoadFailureLogFields(error: SdkContentLoadError): Record<string, string | number | boolean | undefined>;

package/dist/_dts/sdk/src/next/index.d.ts

@@ -38,9 +38,10 @@
  * @packageDocumentation
  */
 export { createCatchAllPage } from './catch-all';
+export { RiverbankContentLoadError, SdkContentLoadError, classifyContentLoadError, isSdkContentLoadError, toContentLoadFailureLogFields, type CatchAllContentLoadFailureContext, type CatchAllRequestContext, type ClassifiedContentLoadError, type SdkContentLoadFailure, type SdkContentLoadFailureKind, type SdkContentLoadNotFound, } from './content-load-failure';
 export type { CreateCatchAllPageOptions, CreateCatchAllPageResult, CatchAllPageProps, CatchAllContext, ThemeSwitchConfigV1, ThemeResolverContext, } from './types';
 export { generateAllStaticParams, validateStaticParamsEnv, pathToSlugArray, type StaticParamsEnvResult, } from './static-params';
-export { createSitemap, type CreateSitemapOptions, type SitemapGenerator } from './sitemap';
+export { createSitemap, type CreateSitemapOptions, type SitemapGenerator, } from './sitemap';
 export { createRobots, type CreateRobotsOptions } from './robots';
 /**
  * ISR revalidation duration in seconds for production mode.

package/dist/_dts/sdk/src/next/types.d.ts

@@ -11,6 +11,7 @@ import type { Theme } from '../contracts';
 import type { BlockOverrideRegistrations } from '../rendering/overrides';
 import type { Metadata } from '../metadata/generatePageMetadata';
 import type { LoadContentResult } from '../rendering/helpers/loadContent';
+import type { CatchAllContentLoadFailureContext, CatchAllRequestContext } from './content-load-failure';
 /**
  * Context passed to escape hatch callbacks.
  */
@@ -219,6 +220,24 @@ export type CreateCatchAllPageOptions = {
      * ```
      */
     beforeRender?: (context: CatchAllContext) => ReactNode | null | Promise<ReactNode | null>;
+    /**
+     * Optional per-request context used for SDK content-load failure logs.
+     *
+     * The SDK does not call Next's `headers()` automatically because that would
+     * change caching/dynamic behavior for all consumers. If you need host,
+     * request ID, correlation ID, or monitor run ID in failure logs, pass them
+     * through this hook from your app router page.
+     */
+    getRequestContext?: () => CatchAllRequestContext | Promise<CatchAllRequestContext>;
+    /**
+     * Optional escape hatch for upstream CMS/API failures while loading content.
+     *
+     * By default, `createCatchAllPage()` throws `RiverbankContentLoadError`
+     * for timeout/network/5xx/circuit-open failures so they cannot be mistaken
+     * for content 404s. Return a React node here only if your site deliberately
+     * wants to render a custom temporary-unavailable UI for those failures.
+     */
+    onContentLoadFailure?: (context: CatchAllContentLoadFailureContext) => ReactNode | undefined | Promise<ReactNode | undefined>;
     /**
      * Custom metadata generator. If provided, replaces default metadata generation.
      *

package/dist/_dts/sdk/src/portal/redirects.d.ts

@@ -1,4 +1,4 @@
-import { type SafeAppPath } from '@riverbankcms/path-utils';
+import { type SafeAppPath } from '../../../path-utils/src/index';
 type RedirectOptions = {
     defaultRedirectPath?: string;
     redirectPath?: string;

package/dist/_dts/sdk/src/routing/index.d.ts

@@ -9,11 +9,12 @@ export { getContentEntryPrefixes, getContentEntryPrefixesFromContentTypes, isCon
 export type { ContentEntryMatch } from './contentRoutes';
 export { toRoutingInfo } from './contentTypeResolver';
 export type { ContentTypeRoutingInfo } from './contentTypeResolver';
-export { isISODateString, isUUID, isValidSegment, } from './segmentValidators';
+export { isISODateString, isUUID, isValidSegment } from './segmentValidators';
 export { detectEntrySubrouteFromTypes, extractPotentialEntrySubroute, defaultShouldAttemptEntrySubroute, inferKnownEntrySubrouteKind, } from './entrySubroutes';
 export type { EntrySubrouteCandidate, ShouldAttemptEntrySubrouteArgs, KnownEntrySubrouteKind, } from './entrySubroutes';
 export { resolvePageContent } from './resolvePageContent';
-export type { OccurrenceData, EntrySubrouteData, ResolvePageContentOptions, PageResolutionResult, } from './resolvePageContent';
+export { contentFound, contentLoadFailed, contentNotFound, RiverbankContentLoadError, } from './resolvePageContent';
+export type { OccurrenceData, EntrySubrouteData, LoadContentResult, PublicContentLoadError, PublicLoadStage, ResolvePageContentOptions, PageResolutionResult, RiverbankContentLoadErrorOptions, } from './resolvePageContent';
 export { resolveEntrySubrouteFromSegment } from './resolveEntrySubroute';
 export type { ResolveEntrySubrouteParams } from './resolveEntrySubroute';
 export { checkRedirectForPath } from './checkRedirect';

package/dist/_dts/sdk/src/routing/resolvePageContent.d.ts

@@ -22,6 +22,61 @@ export type EntrySubrouteData = {
     kind: 'course-run';
     run: CourseRunData;
 };
+export type PublicLoadStage = 'site_lookup' | 'content_lookup' | 'entry_subroute_lookup' | 'redirect_lookup' | 'content_normalization';
+export type PublicContentLoadError = {
+    kind: 'timeout';
+    stage: PublicLoadStage;
+    message: string;
+    requestId?: string | null;
+} | {
+    kind: 'network';
+    stage: PublicLoadStage;
+    message: string;
+    code?: string | null;
+    requestId?: string | null;
+} | {
+    kind: 'api_error';
+    stage: PublicLoadStage;
+    status: number;
+    message: string;
+    code?: string | null;
+    requestId?: string | null;
+} | {
+    kind: 'invalid_payload';
+    stage: PublicLoadStage;
+    message: string;
+    requestId?: string | null;
+} | {
+    kind: 'unknown';
+    stage: PublicLoadStage;
+    message: string;
+    requestId?: string | null;
+};
+export type RiverbankContentLoadErrorOptions = Readonly<{
+    surface: string;
+    reason?: string | null;
+    path?: string | null;
+    cause?: unknown;
+}>;
+export declare class RiverbankContentLoadError extends Error {
+    readonly surface: string;
+    readonly reason: string | null;
+    readonly path: string | null;
+    readonly cause?: unknown;
+    constructor(message: string, options: RiverbankContentLoadErrorOptions);
+}
+export type LoadContentResult<TContent> = {
+    kind: 'found';
+    content: TContent;
+} | {
+    kind: 'not_found';
+} | {
+    kind: 'failed';
+    error: PublicContentLoadError;
+};
+export declare function contentFound<TContent>(content: TContent): LoadContentResult<TContent>;
+export declare function contentNotFound<TContent>(): LoadContentResult<TContent>;
+export declare function contentLoadFailed<TContent>(error: PublicContentLoadError): LoadContentResult<TContent>;
 /**
  * Options for resolving page content.
  *
@@ -35,13 +90,14 @@ export interface ResolvePageContentOptions<TContent> {
     /**
      * Load content by path.
      *
-     * **Contract:** MUST return null for not-found (not throw).
-     * Callers should wrap their client to normalize exceptions.
+     * **Contract:** MUST return a closed result that distinguishes not-found
+     * from upstream failure. Callers should wrap their client to normalize
+     * exceptions before they reach this routing helper.
      *
      * @param path - The path to load
-     * @returns Content if found, null if not found
+     * @returns Content load result
      */
-    loadContent: (path: string) => Promise<TContent | null>;
+    loadContent: (path: string) => Promise<LoadContentResult<TContent>>;
     /**
      * Resolve occurrence by entry ID and segment.
      *
@@ -99,6 +155,14 @@ export type PageResolutionResult<TContent> = {
     found: false;
     /** Reason for not finding content */
     reason: 'not-found' | 'invalid-subroute';
+} | {
+    /** Content could not be loaded due to an upstream failure */
+    found: false;
+    reason: 'load-failed';
+    /** The path whose content load failed */
+    failedPath: string;
+    /** Normalized load failure */
+    error: PublicContentLoadError;
 };
 /**
  * Resolve page content for a given path.
@@ -112,8 +176,9 @@ export type PageResolutionResult<TContent> = {
  *
  * ## Error Handling
  *
- * The `loadContent` function MUST return `null` for not-found, not throw.
- * SDK callers should wrap their client to catch and normalize exceptions.
+ * The `loadContent` function MUST return `not_found` for absence and `failed`
+ * for upstream errors. SDK callers should wrap their client to catch and
+ * normalize exceptions.
  *
  * @template TContent - The content type
  * @param options - Resolution options with injected loaders

package/dist/_dts/sdk/src/version.d.ts

@@ -8,4 +8,4 @@
  * 1. This constant
  * 2. The "version" field in package.json
  */
-export declare const SDK_VERSION = "0.77.1";
+export declare const SDK_VERSION = "0.78.2";

package/dist/_dts/site-commands/src/commands.d.ts

@@ -190,8 +190,8 @@ export declare const upsertNavigationMenuCommandSchema: z.ZodObject<{
     input: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
         location: z.ZodOptional<z.ZodEnum<{
-            footer: "footer";
             header: "header";
+            footer: "footer";
             main: "main";
         }>>;
         role: z.ZodOptional<z.ZodEnum<{
@@ -268,6 +268,7 @@ export declare const upsertContentEntryCommandSchema: z.ZodObject<{
         contentTypeKey: z.ZodString;
         slug: z.ZodOptional<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
+        manualOrder: z.ZodOptional<z.ZodNumber>;
         data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         linkedSubjectRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;
         mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
@@ -409,9 +410,9 @@ export declare const upsertEventSeriesCommandSchema: z.ZodObject<{
         }>;
         status: z.ZodOptional<z.ZodEnum<{
             active: "active";
-            cancelled: "cancelled";
             draft: "draft";
             archived: "archived";
+            cancelled: "cancelled";
         }>>;
         visibility: z.ZodEnum<{
             draft: "draft";
@@ -533,8 +534,8 @@ export declare const upsertCourseCommandSchema: z.ZodObject<{
         title: z.ZodString;
         status: z.ZodOptional<z.ZodEnum<{
             active: "active";
-            cancelled: "cancelled";
             draft: "draft";
+            cancelled: "cancelled";
         }>>;
         visibility: z.ZodEnum<{
             draft: "draft";
@@ -723,8 +724,8 @@ export declare const grantCustomerPassCommandSchema: z.ZodObject<{
         expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         status: z.ZodDefault<z.ZodEnum<{
             active: "active";
-            refunded: "refunded";
             expired: "expired";
+            refunded: "refunded";
             exhausted: "exhausted";
         }>>;
         note: z.ZodOptional<z.ZodString>;
@@ -1091,8 +1092,8 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     input: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
         location: z.ZodOptional<z.ZodEnum<{
-            footer: "footer";
             header: "header";
+            footer: "footer";
             main: "main";
         }>>;
         role: z.ZodOptional<z.ZodEnum<{
@@ -1166,6 +1167,7 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         contentTypeKey: z.ZodString;
         slug: z.ZodOptional<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
+        manualOrder: z.ZodOptional<z.ZodNumber>;
         data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         linkedSubjectRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;
         mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
@@ -1311,9 +1313,9 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>;
         status: z.ZodOptional<z.ZodEnum<{
             active: "active";
-            cancelled: "cancelled";
             draft: "draft";
             archived: "archived";
+            cancelled: "cancelled";
         }>>;
         visibility: z.ZodEnum<{
             draft: "draft";
@@ -1432,8 +1434,8 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         title: z.ZodString;
         status: z.ZodOptional<z.ZodEnum<{
             active: "active";
-            cancelled: "cancelled";
             draft: "draft";
+            cancelled: "cancelled";
         }>>;
         visibility: z.ZodEnum<{
             draft: "draft";
@@ -1572,8 +1574,8 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         status: z.ZodDefault<z.ZodEnum<{
             active: "active";
-            refunded: "refunded";
             expired: "expired";
+            refunded: "refunded";
             exhausted: "exhausted";
         }>>;
         note: z.ZodOptional<z.ZodString>;
@@ -1924,8 +1926,8 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
         input: z.ZodObject<{
             name: z.ZodOptional<z.ZodString>;
             location: z.ZodOptional<z.ZodEnum<{
-                footer: "footer";
                 header: "header";
+                footer: "footer";
                 main: "main";
             }>>;
             role: z.ZodOptional<z.ZodEnum<{
@@ -1999,6 +2001,7 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
             contentTypeKey: z.ZodString;
             slug: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
+            manualOrder: z.ZodOptional<z.ZodNumber>;
             data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             linkedSubjectRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;
             mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
@@ -2144,9 +2147,9 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
             }>;
             status: z.ZodOptional<z.ZodEnum<{
                 active: "active";
-                cancelled: "cancelled";
                 draft: "draft";
                 archived: "archived";
+                cancelled: "cancelled";
             }>>;
             visibility: z.ZodEnum<{
                 draft: "draft";
@@ -2265,8 +2268,8 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
             title: z.ZodString;
             status: z.ZodOptional<z.ZodEnum<{
                 active: "active";
-                cancelled: "cancelled";
                 draft: "draft";
+                cancelled: "cancelled";
             }>>;
             visibility: z.ZodEnum<{
                 draft: "draft";
@@ -2405,8 +2408,8 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
             expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             status: z.ZodDefault<z.ZodEnum<{
                 active: "active";
-                refunded: "refunded";
                 expired: "expired";
+                refunded: "refunded";
                 exhausted: "exhausted";
             }>>;
             note: z.ZodOptional<z.ZodString>;

package/dist/_dts/site-commands/src/index.d.ts

@@ -4,6 +4,7 @@ export * from './commands';
 export * from './domain';
 export * from './exposure';
 export * from './metadata';
+export * from './pagePaths';
 export * from './planner';
 export * from './refContributions';
 export * from './refs';

package/dist/_dts/site-commands/src/pagePaths.d.ts

@@ -0,0 +1,6 @@
+export declare const HOME_PAGE_COMMAND_SLUG = "home";
+export declare const ROOT_PAGE_PATH = "/";
+export declare function commandPageSlug(slug: string): string;
+export declare function normalizedPagePath(slug: string): string;
+export declare function normalizedNavigationHref(href: string): string;
+export declare function isInternalPageHref(href: string): boolean;

package/dist/_dts/theme-core/src/accordions/siteStyleDefaults.d.ts

@@ -0,0 +1,26 @@
+export declare const softEarthAccordionSystem: {
+    readonly background: {
+        readonly type: "solid";
+        readonly colorToken: "background";
+    };
+    readonly spacing: "comfortable";
+    readonly corners: "square";
+    readonly border: null;
+    readonly shadow: null;
+    readonly icon: {
+        readonly style: "plus-minus";
+        readonly position: "right";
+        readonly size: "md";
+        readonly colorToken: "primary";
+    };
+    readonly trigger: {
+        readonly textColorToken: "text";
+        readonly fontWeight: "medium";
+    };
+    readonly hover: {
+        readonly textColorToken: "primary";
+    };
+    readonly content: {
+        readonly textColorToken: "neutral-700";
+    };
+};

package/dist/_dts/theme-core/src/accordions/types.d.ts

@@ -76,6 +76,7 @@ export declare const accordionSystemSchema: z.ZodObject<{
             md: "md";
             lg: "lg";
         }>;
+        colorToken: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     trigger: z.ZodObject<{
         textColorToken: z.ZodString;

package/dist/_dts/theme-core/src/blocks/vars/index.d.ts

@@ -14,6 +14,7 @@ export { generateEventCalendarVars } from './event-calendar';
 export { generateEventListingVars, generateEventSpotlightVars, generateEventCombinedVars, } from './event-cards';
 export { generateAppointmentBookingVars } from './appointment-booking';
 export { generateFormBlockVars } from './form-block';
+export { generateCustomerPortalVars } from './customer-portal';
 export { generateTestimonialsVars } from './testimonials';
 export { generateCourseDetailsVars } from './course-details';
 export { generateCourseRegistrationVars } from './course-registration';

package/dist/_dts/theme-core/src/fonts/index.d.ts

@@ -1 +1,2 @@
+export { detectFontFormatFromBytes, detectFontSourceFormatFromFilename, FONT_TOO_LARGE_MESSAGE, FONT_UPLOAD_ACCEPT, getFontUploadValidationMessage, MAX_FONT_UPLOAD_BYTES, normalizeUserFontFilename, SUPPORTED_FONT_FORMAT_LABEL, UNSUPPORTED_FONT_MESSAGE, validateFontUploadFile, type FontByteFormatDecision, type FontFilenameFormatDecision, type FontUploadFileLike, type KnownFontSourceFormat, type SanitizedFontFilename, type SupportedFontExtension, type SupportedFontSourceFormat, } from './uploadFormat';
 export { type SiteFont, type SiteFontFile, SITE_FONTS_BUCKET, getSiteFontsStorageUrl, generateFontFaceCss, generateFontFaceForFile, generateFontFaceForVariableFont, } from './types';

package/dist/_dts/theme-core/src/fonts/uploadFormat.d.ts

@@ -0,0 +1,44 @@
+export declare const MAX_FONT_UPLOAD_BYTES: number;
+export declare const FONT_UPLOAD_ACCEPT = ".woff2,.ttf,.otf";
+export declare const SUPPORTED_FONT_FORMAT_LABEL = "WOFF2, TTF, or OTF";
+export declare const UNSUPPORTED_FONT_MESSAGE = "Upload a WOFF2, TTF, or OTF font file.";
+export declare const FONT_TOO_LARGE_MESSAGE = "File too large. Maximum size is 5MB.";
+export type SupportedFontSourceFormat = 'woff2' | 'ttf' | 'otf';
+export type KnownFontSourceFormat = SupportedFontSourceFormat | 'woff';
+export type SupportedFontExtension = '.woff2' | '.ttf' | '.otf';
+export type FontUploadFileLike = Readonly<{
+    name: string;
+    size: number;
+}>;
+export type FontFilenameFormatDecision = Readonly<{
+    tag: 'supported';
+    format: SupportedFontSourceFormat;
+    extension: SupportedFontExtension;
+}> | Readonly<{
+    tag: 'unsupported';
+    extension: string | null;
+    reason: 'empty_filename' | 'missing_extension' | 'empty_basename' | 'unsupported_extension';
+}>;
+export type FontByteFormatDecision = Readonly<{
+    tag: 'detected';
+    format: KnownFontSourceFormat;
+}> | Readonly<{
+    tag: 'unknown';
+}>;
+export type SanitizedFontFilename = Readonly<{
+    tag: 'valid';
+    filename: string;
+    format: SupportedFontSourceFormat;
+    extension: SupportedFontExtension;
+}> | Readonly<{
+    tag: 'invalid';
+    reason: Extract<FontFilenameFormatDecision, {
+        tag: 'unsupported';
+    }>['reason'];
+    extension: string | null;
+}>;
+export declare function detectFontSourceFormatFromFilename(filename: string): FontFilenameFormatDecision;
+export declare function normalizeUserFontFilename(filename: string): SanitizedFontFilename;
+export declare function detectFontFormatFromBytes(bytes: Uint8Array): FontByteFormatDecision;
+export declare function getFontUploadValidationMessage(filename: string): string | null;
+export declare function validateFontUploadFile(file: FontUploadFileLike): string | null;