@riverbankcms/sdk 0.7.0 → 0.7.2

package/dist/server/{types-BvcJU7zk.d.ts → types-DnkRh0UL.d.ts}

@@ -33,10 +33,17 @@ interface PaginationMeta {
 type EntriesResponseWithMeta = {
     entries: EntriesResponse['entries'];
 } & PaginationMeta;
+/**
+ * Common options for all SDK methods
+ */
+interface SdkMethodOptions {
+    /** AbortSignal for cancelling the request */
+    signal?: AbortSignal;
+}
 /**
  * Base parameters for getEntries - shared across all overloads
  */
-interface GetEntriesBaseParams {
+interface GetEntriesBaseParams extends SdkMethodOptions {
     /** The site ID */
     siteId: string;
     /** The content type key (e.g., 'blog-post', 'product') */
@@ -54,6 +61,92 @@ interface GetEntriesBaseParams {
     /** Entry IDs to fetch when mode is 'manual' */
     entryIds?: string[];
 }
+/**
+ * Source of the data returned by a resilient fetch
+ */
+type ResilienceSource = 'live' | 'cache' | 'stale' | 'prebuild' | 'error';
+/**
+ * Status information from a resilient fetch operation
+ */
+interface ResilienceStatus {
+    /** Where the data came from */
+    source: ResilienceSource;
+    /** Whether this was a preview request */
+    isPreview: boolean;
+    /** Cache key used for this request */
+    cacheKey?: string;
+    /** Error details if fetch failed */
+    error?: {
+        code?: string;
+        message: string;
+    };
+    /** Seconds since cache TTL expired (when source='stale') */
+    staleAgeSec?: number;
+    /** Seconds since prebuild was generated (when source='prebuild') */
+    prebuildAgeSec?: number;
+    /** Circuit breaker state at time of request */
+    circuit: CircuitState;
+    /** Correlation ID for debugging */
+    requestId?: string;
+    /** Total request duration including retries (ms) */
+    durationMs?: number;
+}
+/**
+ * Circuit breaker state information
+ */
+interface CircuitState {
+    state: 'closed' | 'open' | 'half-open';
+    failureCount: number;
+    /** Timestamp when circuit will transition from open to half-open */
+    openUntil?: number;
+}
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /** Maximum number of attempts (including initial) */
+    maxAttempts?: number;
+    /** Base delay between retries in ms */
+    baseDelayMs?: number;
+    /** Maximum delay between retries in ms */
+    maxDelayMs?: number;
+    /** Jitter strategy: 'full' adds randomization, 'none' uses exact delays */
+    jitter?: 'full' | 'none';
+    /** Custom function to determine if an error should be retried */
+    retryOn?: (error: Error, statusCode?: number) => boolean;
+}
+/**
+ * Circuit breaker configuration
+ */
+interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold?: number;
+    /** Time in ms before attempting to close circuit */
+    resetTimeoutMs?: number;
+    /** Number of successful requests needed to close from half-open */
+    halfOpenMaxRequests?: number;
+}
+/**
+ * Resilience configuration for the SDK client
+ */
+interface ResilienceConfig {
+    /** Enable resilience features (default: true) */
+    enabled?: boolean;
+    /** Serve stale data on fetch failure (default: true) */
+    staleIfError?: boolean;
+    /** Seconds AFTER cache TTL expires that stale data remains valid (default: 300) */
+    staleTtlSec?: number;
+    /** Request timeout in ms (default: 8000 server, 5000 browser) */
+    requestTimeoutMs?: number;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Circuit breaker configuration */
+    circuitBreaker?: CircuitBreakerConfig;
+    /** Callback fired on every request with status information */
+    onStatusChange?: (status: ResilienceStatus) => void;
+    /** Callback fired only when transitioning into/out of degraded mode */
+    onDegradedMode?: (degraded: boolean, status: ResilienceStatus) => void;
+}
 /**
  * Configuration for creating a Riverbank CMS client
  */
@@ -85,6 +178,10 @@ interface RiverbankClientConfig {
          */
         maxSize?: number;
     };
+    /**
+     * Resilience configuration for error handling, retries, and fallbacks
+     */
+    resilience?: ResilienceConfig;
 }
 /**
  * Riverbank CMS client interface
@@ -97,7 +194,7 @@ interface RiverbankClient {
         slug?: string;
         domain?: string;
         id?: string;
-    }): Promise<SiteResponse>;
+    } & SdkMethodOptions): Promise<SiteResponse>;
     /**
      * Fetch a specific page by path
      *
@@ -107,7 +204,7 @@ interface RiverbankClient {
         siteId: string;
         path: string;
         preview?: boolean;
-    }): Promise<PageResponse>;
+    } & SdkMethodOptions): Promise<PageResponse>;
     /**
      * Fetch published content entries with optional pagination, sorting, and preview mode
      *
@@ -168,20 +265,20 @@ interface RiverbankClient {
         siteId: string;
         contentType: string;
         slug: string;
-    }): Promise<EntryResponse>;
+    } & SdkMethodOptions): Promise<EntryResponse>;
     /**
      * Fetch a public form definition by ID
      */
     getPublicFormById(params: {
         formId: string;
-    }): Promise<PublicFormResponse>;
+    } & SdkMethodOptions): Promise<PublicFormResponse>;
     /**
      * Fetch public booking services for a site
      */
     getPublicBookingServices(params: {
         siteId: string;
         ids?: string;
-    }): Promise<PublicBookingServicesResponse>;
+    } & SdkMethodOptions): Promise<PublicBookingServicesResponse>;
     /**
      * List public events for a site (optionally time-filtered)
      */
@@ -191,7 +288,7 @@ interface RiverbankClient {
         from?: string;
         to?: string;
         stage?: string;
-    }): Promise<PublicEventsResponse>;
+    } & SdkMethodOptions): Promise<PublicEventsResponse>;
     /**
      * Resolve an event occurrence by URL segment (date or UUID)
      *
@@ -220,7 +317,7 @@ interface RiverbankClient {
         siteId: string;
         entryId: string;
         segment: string;
-    }): Promise<ResolveEventOccurrenceResponse>;
+    } & SdkMethodOptions): Promise<ResolveEventOccurrenceResponse>;
     /**
      * Check if a path has a configured redirect rule
      *
@@ -241,11 +338,23 @@ interface RiverbankClient {
     checkRedirect(params: {
         siteId: string;
         path: string;
-    }): Promise<CheckRedirectResponse>;
+    } & SdkMethodOptions): Promise<CheckRedirectResponse>;
     /**
      * Force clear the cache
      */
     clearCache(): void;
+    /**
+     * Get the status from the most recently emitted request
+     *
+     * Note: With concurrent requests, this returns the last status emitted,
+     * which may not be from the request you're interested in. For reliable
+     * per-request status, use the onStatusChange callback instead.
+     */
+    getLastEmittedStatus(): ResilienceStatus | null;
+    /**
+     * Get the current circuit breaker state
+     */
+    getCircuitState(): CircuitState;
 }
 
 export type { EntriesResponse as E, PageResponse as P, RiverbankClient as R, SiteResponse as S, RiverbankClientConfig as a, EntryResponse as b, EntriesResponseWithMeta as c, PaginationMeta as d, ResolveEventOccurrenceResponse as e };

package/dist/server/{types-1cLz0vnq.d.mts → types-MF2AWoKv.d.mts}

@@ -33,10 +33,17 @@ interface PaginationMeta {
 type EntriesResponseWithMeta = {
     entries: EntriesResponse['entries'];
 } & PaginationMeta;
+/**
+ * Common options for all SDK methods
+ */
+interface SdkMethodOptions {
+    /** AbortSignal for cancelling the request */
+    signal?: AbortSignal;
+}
 /**
  * Base parameters for getEntries - shared across all overloads
  */
-interface GetEntriesBaseParams {
+interface GetEntriesBaseParams extends SdkMethodOptions {
     /** The site ID */
     siteId: string;
     /** The content type key (e.g., 'blog-post', 'product') */
@@ -54,6 +61,92 @@ interface GetEntriesBaseParams {
     /** Entry IDs to fetch when mode is 'manual' */
     entryIds?: string[];
 }
+/**
+ * Source of the data returned by a resilient fetch
+ */
+type ResilienceSource = 'live' | 'cache' | 'stale' | 'prebuild' | 'error';
+/**
+ * Status information from a resilient fetch operation
+ */
+interface ResilienceStatus {
+    /** Where the data came from */
+    source: ResilienceSource;
+    /** Whether this was a preview request */
+    isPreview: boolean;
+    /** Cache key used for this request */
+    cacheKey?: string;
+    /** Error details if fetch failed */
+    error?: {
+        code?: string;
+        message: string;
+    };
+    /** Seconds since cache TTL expired (when source='stale') */
+    staleAgeSec?: number;
+    /** Seconds since prebuild was generated (when source='prebuild') */
+    prebuildAgeSec?: number;
+    /** Circuit breaker state at time of request */
+    circuit: CircuitState;
+    /** Correlation ID for debugging */
+    requestId?: string;
+    /** Total request duration including retries (ms) */
+    durationMs?: number;
+}
+/**
+ * Circuit breaker state information
+ */
+interface CircuitState {
+    state: 'closed' | 'open' | 'half-open';
+    failureCount: number;
+    /** Timestamp when circuit will transition from open to half-open */
+    openUntil?: number;
+}
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /** Maximum number of attempts (including initial) */
+    maxAttempts?: number;
+    /** Base delay between retries in ms */
+    baseDelayMs?: number;
+    /** Maximum delay between retries in ms */
+    maxDelayMs?: number;
+    /** Jitter strategy: 'full' adds randomization, 'none' uses exact delays */
+    jitter?: 'full' | 'none';
+    /** Custom function to determine if an error should be retried */
+    retryOn?: (error: Error, statusCode?: number) => boolean;
+}
+/**
+ * Circuit breaker configuration
+ */
+interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold?: number;
+    /** Time in ms before attempting to close circuit */
+    resetTimeoutMs?: number;
+    /** Number of successful requests needed to close from half-open */
+    halfOpenMaxRequests?: number;
+}
+/**
+ * Resilience configuration for the SDK client
+ */
+interface ResilienceConfig {
+    /** Enable resilience features (default: true) */
+    enabled?: boolean;
+    /** Serve stale data on fetch failure (default: true) */
+    staleIfError?: boolean;
+    /** Seconds AFTER cache TTL expires that stale data remains valid (default: 300) */
+    staleTtlSec?: number;
+    /** Request timeout in ms (default: 8000 server, 5000 browser) */
+    requestTimeoutMs?: number;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Circuit breaker configuration */
+    circuitBreaker?: CircuitBreakerConfig;
+    /** Callback fired on every request with status information */
+    onStatusChange?: (status: ResilienceStatus) => void;
+    /** Callback fired only when transitioning into/out of degraded mode */
+    onDegradedMode?: (degraded: boolean, status: ResilienceStatus) => void;
+}
 /**
  * Configuration for creating a Riverbank CMS client
  */
@@ -85,6 +178,10 @@ interface RiverbankClientConfig {
          */
         maxSize?: number;
     };
+    /**
+     * Resilience configuration for error handling, retries, and fallbacks
+     */
+    resilience?: ResilienceConfig;
 }
 /**
  * Riverbank CMS client interface
@@ -97,7 +194,7 @@ interface RiverbankClient {
         slug?: string;
         domain?: string;
         id?: string;
-    }): Promise<SiteResponse>;
+    } & SdkMethodOptions): Promise<SiteResponse>;
     /**
      * Fetch a specific page by path
      *
@@ -107,7 +204,7 @@ interface RiverbankClient {
         siteId: string;
         path: string;
         preview?: boolean;
-    }): Promise<PageResponse>;
+    } & SdkMethodOptions): Promise<PageResponse>;
     /**
      * Fetch published content entries with optional pagination, sorting, and preview mode
      *
@@ -168,20 +265,20 @@ interface RiverbankClient {
         siteId: string;
         contentType: string;
         slug: string;
-    }): Promise<EntryResponse>;
+    } & SdkMethodOptions): Promise<EntryResponse>;
     /**
      * Fetch a public form definition by ID
      */
     getPublicFormById(params: {
         formId: string;
-    }): Promise<PublicFormResponse>;
+    } & SdkMethodOptions): Promise<PublicFormResponse>;
     /**
      * Fetch public booking services for a site
      */
     getPublicBookingServices(params: {
         siteId: string;
         ids?: string;
-    }): Promise<PublicBookingServicesResponse>;
+    } & SdkMethodOptions): Promise<PublicBookingServicesResponse>;
     /**
      * List public events for a site (optionally time-filtered)
      */
@@ -191,7 +288,7 @@ interface RiverbankClient {
         from?: string;
         to?: string;
         stage?: string;
-    }): Promise<PublicEventsResponse>;
+    } & SdkMethodOptions): Promise<PublicEventsResponse>;
     /**
      * Resolve an event occurrence by URL segment (date or UUID)
      *
@@ -220,7 +317,7 @@ interface RiverbankClient {
         siteId: string;
         entryId: string;
         segment: string;
-    }): Promise<ResolveEventOccurrenceResponse>;
+    } & SdkMethodOptions): Promise<ResolveEventOccurrenceResponse>;
     /**
      * Check if a path has a configured redirect rule
      *
@@ -241,11 +338,23 @@ interface RiverbankClient {
     checkRedirect(params: {
         siteId: string;
         path: string;
-    }): Promise<CheckRedirectResponse>;
+    } & SdkMethodOptions): Promise<CheckRedirectResponse>;
     /**
      * Force clear the cache
      */
     clearCache(): void;
+    /**
+     * Get the status from the most recently emitted request
+     *
+     * Note: With concurrent requests, this returns the last status emitted,
+     * which may not be from the request you're interested in. For reliable
+     * per-request status, use the onStatusChange callback instead.
+     */
+    getLastEmittedStatus(): ResilienceStatus | null;
+    /**
+     * Get the current circuit breaker state
+     */
+    getCircuitState(): CircuitState;
 }
 
 export type { EntriesResponse as E, PageResponse as P, RiverbankClient as R, SiteResponse as S, RiverbankClientConfig as a, EntryResponse as b, EntriesResponseWithMeta as c, PaginationMeta as d, ResolveEventOccurrenceResponse as e };

package/dist/server/webhooks.d.mts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+
+/**
+ * Webhook verification utilities for Riverbank SDK
+ *
+ * Provides framework-agnostic webhook signature verification and payload parsing.
+ */
+
+/**
+ * Zod schema for webhook payload validation.
+ */
+declare const WebhookPayloadSchema: z.ZodObject<{
+    event: z.ZodString;
+    timestamp: z.ZodString;
+    siteId: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodAny>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Webhook payload structure sent by the CMS.
+ */
+type WebhookPayload = z.infer<typeof WebhookPayloadSchema>;
+/**
+ * Verify a webhook signature using HMAC-SHA256.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param payload - The raw request body as a string
+ * @param signature - The X-Riverbank-Signature header value
+ * @param secret - The webhook signing secret (RIVERBANK_WEBHOOK_SECRET)
+ * @returns true if signature is valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * const body = await request.text();
+ * const signature = request.headers.get('x-riverbank-signature');
+ * const secret = process.env.RIVERBANK_WEBHOOK_SECRET;
+ *
+ * if (!verifyWebhookSignature(body, signature, secret)) {
+ *   return new Response('Invalid signature', { status: 401 });
+ * }
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
+/**
+ * Result type for webhook payload parsing.
+ */
+type ParseWebhookResult = {
+    success: true;
+    payload: WebhookPayload;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Parse and validate a webhook payload from the request body.
+ *
+ * Uses Zod schema validation to ensure the payload has the expected structure.
+ *
+ * @param body - The raw request body as a string
+ * @returns A result object with either the validated payload or an error message
+ *
+ * @example
+ * ```ts
+ * const body = await request.text();
+ * const result = parseWebhookPayload(body);
+ * if (!result.success) {
+ *   return new Response(result.error, { status: 400 });
+ * }
+ * console.log(`Received ${result.payload.event} for site ${result.payload.siteId}`);
+ * ```
+ */
+declare function parseWebhookPayload(body: string): ParseWebhookResult;
+
+export { type ParseWebhookResult, type WebhookPayload, WebhookPayloadSchema, parseWebhookPayload, verifyWebhookSignature };

package/dist/server/webhooks.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+
+/**
+ * Webhook verification utilities for Riverbank SDK
+ *
+ * Provides framework-agnostic webhook signature verification and payload parsing.
+ */
+
+/**
+ * Zod schema for webhook payload validation.
+ */
+declare const WebhookPayloadSchema: z.ZodObject<{
+    event: z.ZodString;
+    timestamp: z.ZodString;
+    siteId: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodAny>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Webhook payload structure sent by the CMS.
+ */
+type WebhookPayload = z.infer<typeof WebhookPayloadSchema>;
+/**
+ * Verify a webhook signature using HMAC-SHA256.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param payload - The raw request body as a string
+ * @param signature - The X-Riverbank-Signature header value
+ * @param secret - The webhook signing secret (RIVERBANK_WEBHOOK_SECRET)
+ * @returns true if signature is valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * const body = await request.text();
+ * const signature = request.headers.get('x-riverbank-signature');
+ * const secret = process.env.RIVERBANK_WEBHOOK_SECRET;
+ *
+ * if (!verifyWebhookSignature(body, signature, secret)) {
+ *   return new Response('Invalid signature', { status: 401 });
+ * }
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
+/**
+ * Result type for webhook payload parsing.
+ */
+type ParseWebhookResult = {
+    success: true;
+    payload: WebhookPayload;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Parse and validate a webhook payload from the request body.
+ *
+ * Uses Zod schema validation to ensure the payload has the expected structure.
+ *
+ * @param body - The raw request body as a string
+ * @returns A result object with either the validated payload or an error message
+ *
+ * @example
+ * ```ts
+ * const body = await request.text();
+ * const result = parseWebhookPayload(body);
+ * if (!result.success) {
+ *   return new Response(result.error, { status: 400 });
+ * }
+ * console.log(`Received ${result.payload.event} for site ${result.payload.siteId}`);
+ * ```
+ */
+declare function parseWebhookPayload(body: string): ParseWebhookResult;
+
+export { type ParseWebhookResult, type WebhookPayload, WebhookPayloadSchema, parseWebhookPayload, verifyWebhookSignature };

package/dist/server/webhooks.js

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+var _chunkVODFQMUWjs = require('./chunk-VODFQMUW.js');
+
+
+
+
+exports.WebhookPayloadSchema = _chunkVODFQMUWjs.WebhookPayloadSchema; exports.parseWebhookPayload = _chunkVODFQMUWjs.parseWebhookPayload; exports.verifyWebhookSignature = _chunkVODFQMUWjs.verifyWebhookSignature;
+//# sourceMappingURL=webhooks.js.map

package/dist/server/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/will/Projects/Business/cms/builder/packages/sdk/dist/server/webhooks.js"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACF,sDAA4B;AAC5B;AACE;AACA;AACA;AACF,mNAAC","file":"/Users/will/Projects/Business/cms/builder/packages/sdk/dist/server/webhooks.js"}

package/dist/server/webhooks.mjs

@@ -0,0 +1,11 @@
+import {
+  WebhookPayloadSchema,
+  parseWebhookPayload,
+  verifyWebhookSignature
+} from "./chunk-AET56TQX.mjs";
+export {
+  WebhookPayloadSchema,
+  parseWebhookPayload,
+  verifyWebhookSignature
+};
+//# sourceMappingURL=webhooks.mjs.map

package/dist/server/webhooks.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riverbankcms/sdk",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Riverbank CMS SDK for headless content consumption",
   "main": "./dist/server/index.js",
   "module": "./dist/server/index.mjs",
@@ -104,6 +104,26 @@
       "import": "./dist/server/theme-bridge.mjs",
       "require": "./dist/server/theme-bridge.js"
     },
+    "./env": {
+      "types": "./dist/server/env.d.ts",
+      "import": "./dist/server/env.mjs",
+      "require": "./dist/server/env.js"
+    },
+    "./next/revalidate": {
+      "types": "./dist/server/next/revalidate.d.ts",
+      "import": "./dist/server/next/revalidate.mjs",
+      "require": "./dist/server/next/revalidate.js"
+    },
+    "./next/tags": {
+      "types": "./dist/server/next/tags.d.ts",
+      "import": "./dist/server/next/tags.mjs",
+      "require": "./dist/server/next/tags.js"
+    },
+    "./webhooks": {
+      "types": "./dist/server/webhooks.d.ts",
+      "import": "./dist/server/webhooks.mjs",
+      "require": "./dist/server/webhooks.js"
+    },
     "./styles.css": "./src/styles/index.css"
   },
   "files": [
@@ -128,7 +148,7 @@
     "zod": "^4.1.1"
   },
   "peerDependencies": {
-    "next": "^14.0.0 || ^15.0.0",
+    "next": ">=14.0.0",
     "react": "^19.2.1",
     "react-dom": "^19.2.1"
   },
@@ -147,7 +167,7 @@
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "eslint": "^9.15.0",
-    "next": "^15.0.0",
+    "next": "^15.5.0",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "vitest": "^1.6.1"