@riverbankcms/sdk 0.88.0 → 0.89.1

package/dist/_dts/sdk/src/client/runtimeCachePolicy.d.ts

@@ -0,0 +1,160 @@
+import type { PublicEndpointName } from '../public-api/contracts';
+import type { GetPageParams, GetSiteParams } from './types';
+declare const publishedRuntimeCacheKeyBrand: unique symbol;
+declare const publishedRuntimeCachePayloadSchemaVersionBrand: unique symbol;
+export type PublishedRuntimeCacheKey = string & {
+    readonly [publishedRuntimeCacheKeyBrand]: 'PublishedRuntimeCacheKey';
+};
+export type PublishedRuntimeCachePayloadSchemaVersion = number & {
+    readonly [publishedRuntimeCachePayloadSchemaVersionBrand]: 'PublishedRuntimeCachePayloadSchemaVersion';
+};
+export declare const DEFAULT_PUBLISHED_RUNTIME_CACHE_PAYLOAD_SCHEMA_VERSION: PublishedRuntimeCachePayloadSchemaVersion;
+export type RuntimeCachePolicyKind = 'durable-public-stale' | 'memory-only' | 'live-only';
+export type RuntimeCacheLiveOnlyReason = 'unknown_endpoint' | 'non_get_request' | 'preview_request' | 'force_refresh' | 'opaque_batch_loader' | 'challenge_endpoint' | 'auth_required' | 'safety_sensitive_booking';
+export type RuntimeCachePolicy = Readonly<{
+    kind: 'durable-public-stale';
+    endpoint: PublicEndpointName;
+    freshTtlSec: number;
+    staleTtlSec: number;
+}> | Readonly<{
+    kind: 'memory-only';
+    endpoint: PublicEndpointName;
+    freshTtlSec: number;
+    reason: 'durable_rollout_pending';
+}> | Readonly<{
+    kind: 'live-only';
+    endpoint: string;
+    reason: RuntimeCacheLiveOnlyReason;
+}>;
+export type RuntimeCacheParams = Readonly<Record<string, string | number | boolean | null | undefined>>;
+export type ResolveRuntimeCachePolicyInput = Readonly<{
+    endpoint: string;
+    method?: string;
+    params?: RuntimeCacheParams;
+}>;
+export declare function resolveRuntimeCachePolicy(input: ResolveRuntimeCachePolicyInput): RuntimeCachePolicy;
+export type GetSiteRuntimeCacheParams = Readonly<Pick<GetSiteParams, 'id' | 'slug' | 'domain' | 'currentPath' | 'force'>>;
+export type GetContentByPathRuntimeCacheParams = Readonly<Pick<GetPageParams, 'siteId' | 'path' | 'preview'>>;
+type KeyDeriverInputByEndpoint = Readonly<{
+    getSite: GetSiteRuntimeCacheParams;
+    getContentByPath: GetContentByPathRuntimeCacheParams;
+}>;
+export type PublishedRuntimeCacheKeyEndpoint = keyof typeof DURABLE_RUNTIME_CACHE_KEY_DERIVERS;
+export type ParsePublishedRuntimeCacheKeyResult = Readonly<{
+    ok: true;
+    key: PublishedRuntimeCacheKey;
+    endpoint: PublishedRuntimeCacheKeyEndpoint;
+}> | Readonly<{
+    ok: false;
+    error: 'not_string' | 'invalid_prefix' | 'unknown_endpoint' | 'invalid_param_encoding';
+}>;
+export type ParsePublishedRuntimeCacheKeyDetailsResult = Readonly<{
+    ok: true;
+    key: PublishedRuntimeCacheKey;
+    endpoint: PublishedRuntimeCacheKeyEndpoint;
+    normalizedParams: PublishedRuntimeNormalizedParams;
+}> | Readonly<{
+    ok: false;
+    error: 'not_string' | 'invalid_prefix' | 'unknown_endpoint' | 'invalid_param_encoding';
+}>;
+export type ParsePublishedRuntimeCachePayloadSchemaVersionResult = Readonly<{
+    ok: true;
+    value: PublishedRuntimeCachePayloadSchemaVersion;
+}> | Readonly<{
+    ok: false;
+    error: 'not_number' | 'not_integer' | 'not_positive';
+}>;
+export type PublishedRuntimeCacheFreshness = Readonly<{
+    kind: 'fresh';
+    staleAgeSec: 0;
+}> | Readonly<{
+    kind: 'stale';
+    staleAgeSec: number;
+}> | Readonly<{
+    kind: 'expired';
+}> | Readonly<{
+    kind: 'invalid_timestamp';
+    field: 'freshUntil' | 'staleUntil';
+}>;
+export type ClassifyPublishedRuntimeCacheFreshnessInput = Readonly<{
+    freshUntil: string;
+    staleUntil: string;
+    now: Date;
+}>;
+export type PublishedRuntimeCacheReadInput = Readonly<{
+    cacheKey: PublishedRuntimeCacheKey;
+    endpoint: PublishedRuntimeCacheKeyEndpoint;
+    payloadSchemaVersion?: PublishedRuntimeCachePayloadSchemaVersion;
+}>;
+export type PublishedRuntimeCacheReadResult<TPayload = unknown> = Readonly<{
+    kind: 'hit';
+    freshness: 'fresh' | 'stale';
+    payload: TPayload;
+    staleAgeSec: number;
+}> | Readonly<{
+    kind: 'miss';
+    reason: 'not_found' | 'expired' | 'schema_mismatch';
+}> | Readonly<{
+    kind: 'error';
+    error: Readonly<{
+        kind: PublishedRuntimeCacheAdapterErrorKind;
+        message: string;
+    }>;
+}>;
+export type PublishedRuntimeCacheAdapterErrorKind = 'read_failed' | 'corrupt_row' | 'adapter_exception';
+export type PublishedRuntimeCacheWriteInput<TPayload = unknown> = Readonly<{
+    cacheKey: PublishedRuntimeCacheKey;
+    endpoint: PublishedRuntimeCacheKeyEndpoint;
+    normalizedParams: PublishedRuntimeNormalizedParams;
+    payload: TPayload;
+    siteId?: string | null;
+    freshTtlSec: number;
+    staleTtlSec: number;
+    payloadSchemaVersion?: PublishedRuntimeCachePayloadSchemaVersion;
+    writeReason?: string;
+}>;
+export type PublishedRuntimeCacheAdapter = Readonly<{
+    read?: <TPayload = unknown>(input: PublishedRuntimeCacheReadInput) => Promise<PublishedRuntimeCacheReadResult<TPayload>>;
+    write?: <TPayload = unknown>(input: PublishedRuntimeCacheWriteInput<TPayload>) => void | Promise<void>;
+}>;
+export type DerivePublishedRuntimeCacheKeyInput = {
+    [E in PublishedRuntimeCacheKeyEndpoint]: Readonly<{
+        endpoint: E;
+        params: KeyDeriverInputByEndpoint[E];
+    }>;
+}[PublishedRuntimeCacheKeyEndpoint];
+export type PublishedRuntimeNormalizedParams = Readonly<Record<string, string>>;
+export type PublishedRuntimeCacheKeyError = Readonly<{
+    kind: 'not_durable_eligible';
+    policy: RuntimeCachePolicy;
+}> | Readonly<{
+    kind: 'missing_site_identity';
+    acceptedParams: readonly ['slug', 'domain', 'id'];
+}> | Readonly<{
+    kind: 'missing_required_param';
+    endpoint: PublishedRuntimeCacheKeyEndpoint;
+    param: 'siteId';
+}>;
+export type DerivePublishedRuntimeCacheKeyResult = Readonly<{
+    ok: true;
+    endpoint: PublishedRuntimeCacheKeyEndpoint;
+    key: PublishedRuntimeCacheKey;
+    normalizedParams: PublishedRuntimeNormalizedParams;
+}> | Readonly<{
+    ok: false;
+    error: PublishedRuntimeCacheKeyError;
+}>;
+export declare function normalizeRuntimePublicPath(value: unknown): string;
+declare function deriveGetSiteKey(params: GetSiteRuntimeCacheParams): DerivePublishedRuntimeCacheKeyResult;
+declare function deriveGetContentByPathKey(params: GetContentByPathRuntimeCacheParams): DerivePublishedRuntimeCacheKeyResult;
+declare const DURABLE_RUNTIME_CACHE_KEY_DERIVERS: {
+    readonly getSite: typeof deriveGetSiteKey;
+    readonly getContentByPath: typeof deriveGetContentByPathKey;
+};
+export declare function isPublishedRuntimeCacheKeyEndpoint(value: unknown): value is PublishedRuntimeCacheKeyEndpoint;
+export declare function parsePublishedRuntimeCacheKey(value: unknown): ParsePublishedRuntimeCacheKeyResult;
+export declare function parsePublishedRuntimeCacheKeyDetails(value: unknown): ParsePublishedRuntimeCacheKeyDetailsResult;
+export declare function parsePublishedRuntimeCachePayloadSchemaVersion(value: unknown): ParsePublishedRuntimeCachePayloadSchemaVersionResult;
+export declare function classifyPublishedRuntimeCacheFreshness(input: ClassifyPublishedRuntimeCacheFreshnessInput): PublishedRuntimeCacheFreshness;
+export declare function derivePublishedRuntimeCacheKey(input: DerivePublishedRuntimeCacheKeyInput): DerivePublishedRuntimeCacheKeyResult;
+export {};

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

@@ -1,4 +1,5 @@
 import type { CheckRedirectResponse, EntriesResponse, EntryResponse, PageResponse, PublicBookingServicesResponse, PublicCoursesResponse, PublicFormResponse, PublicFormsResponse, PublicProductsResponse, PublicTeamMembersResponse, PublicMembershipsResponse, PublicPassesResponse, PublicEventDetailsResponse, PublicEventsResponse, ResolveEntrySubrouteResponse, ResolveEventOccurrenceResponse, RoutableContentResponse, SiteResponse, SitemapRoutesResponse, PublicProductCategorySelector } from '../public-api/contracts';
+import type { PublishedRuntimeCacheAdapter, PublishedRuntimeCacheAdapterErrorKind } from './runtimeCachePolicy';
 export type { CheckRedirectResponse, EntriesResponse, EntryResponse, PageResponse, PublicBookingServicesResponse, PublicCoursesResponse, PublicEventsResponse, PublicFormResponse, PublicFormsResponse, PublicProductsResponse, PublicTeamMembersResponse, PublicMembershipsResponse, PublicPassesResponse, PublicEventDetailsResponse, ResolveEntrySubrouteResponse, ResolveEventOccurrenceResponse, RoutableContentResponse, SiteResponse, SitemapRoutesResponse, } from '../public-api/contracts';
 /**
  * Pagination metadata returned when `includeMeta: true`
@@ -88,12 +89,27 @@ export type GetEntriesByIdentifiersParams = {
  * Source of the data returned by a resilient fetch
  */
 export type ResilienceSource = 'live' | 'cache' | 'stale' | 'prebuild' | 'error';
+export type ResilienceCacheTier = 'memory-fresh' | 'memory-stale' | 'durable-fresh' | 'durable-stale' | 'prebuild';
+export type ResilienceDurableCacheDiagnostic = Readonly<{
+    outcome: 'miss';
+    reason: 'not_found' | 'expired' | 'schema_mismatch';
+}> | Readonly<{
+    outcome: 'error';
+    error: Readonly<{
+        kind: PublishedRuntimeCacheAdapterErrorKind;
+        message: string;
+    }>;
+}>;
 /**
  * Status information from a resilient fetch operation
  */
 export interface ResilienceStatus {
     /** Where the data came from */
     source: ResilienceSource;
+    /** More precise cache tier when source is cache/stale/prebuild */
+    cacheTier?: ResilienceCacheTier;
+    /** Durable cache miss/error details when live origin failed and no durable hit was served */
+    durableCache?: ResilienceDurableCacheDiagnostic;
     /** Whether this was a preview request */
     isPreview: boolean;
     /** Cache key used for this request */
@@ -243,7 +259,8 @@ export type SdkAuthConfig = {
 };
 export declare const SDK_CORRELATION_HEADER_NAMES: readonly ["x-request-id", "x-correlation-id", "x-riverbank-monitor-run-id"];
 export type SdkCorrelationHeaderName = (typeof SDK_CORRELATION_HEADER_NAMES)[number];
-export type SdkCorrelationHeaders = Readonly<Partial<Record<SdkCorrelationHeaderName, string>>>;
+export type SdkDefaultHeaderName = SdkCorrelationHeaderName | 'x-vercel-protection-bypass';
+export type SdkCorrelationHeaders = Readonly<Partial<Record<SdkDefaultHeaderName, string>>>;
 /**
  * Configuration for creating a Riverbank CMS client
  */
@@ -286,6 +303,14 @@ export interface RiverbankClientConfig {
      * Per-request headers still win when an individual SDK method supplies `options.headers`.
      */
     defaultHeaders?: SdkCorrelationHeaders;
+    /**
+     * Optional durable published runtime cache adapter.
+     *
+     * Used only for default-closed, anonymous published endpoints that the SDK
+     * policy marks durable-stale eligible. The SDK owns fallback ordering and
+     * metadata; the app owns the storage implementation.
+     */
+    publishedRuntimeCache?: PublishedRuntimeCacheAdapter;
     /**
      * Cache configuration
      */

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

@@ -19,12 +19,14 @@
  */
 export { createRiverbankClient, getResilienceStatusFromError, RiverbankApiError, } from './client/index';
 export { SDK_CORRELATION_HEADER_NAMES } from './client/types';
-export type { RiverbankClient, RiverbankClientConfig, SdkCorrelationHeaderName, SdkCorrelationHeaders, SdkAuthConfig, SiteResponse, PageResponse, EntriesResponse, EntriesResponseWithMeta, GetEntriesByIdentifiersParams, GetPageParams, GetSiteParams, PaginationMeta, EntryResponse, ResilienceConfig, ResilienceStatus, ResilientData, ResilienceSource, CircuitState, RetryConfig, CircuitBreakerConfig, } from './client/types';
+export type { RiverbankClient, RiverbankClientConfig, SdkCorrelationHeaderName, SdkCorrelationHeaders, SdkAuthConfig, SiteResponse, PageResponse, EntriesResponse, EntriesResponseWithMeta, GetEntriesByIdentifiersParams, GetPageParams, GetSiteParams, PaginationMeta, EntryResponse, ResilienceConfig, ResilienceDurableCacheDiagnostic, ResilienceStatus, ResilientData, ResilienceSource, CircuitState, RetryConfig, CircuitBreakerConfig, } from './client/types';
 export { prebuildCache } from './prebuild/index';
 export type { PrebuildOptions, PrebuildResult, PrebuildProgress, PrebuildManifest, PrebuildContentType, } from './prebuild/types';
 export { PrebuildLoader, createPrebuildLoader, canUsePrebuild, } from './prebuild/loader';
 export type { PrebuildLoaderConfig, LoadResult } from './prebuild/loader';
 export type { ApiClient } from './public-api/runtime';
 export { buildEndpointURL, API_ENDPOINTS } from './public-api/runtime';
+export { DEFAULT_PUBLISHED_RUNTIME_CACHE_PAYLOAD_SCHEMA_VERSION, classifyPublishedRuntimeCacheFreshness, derivePublishedRuntimeCacheKey, isPublishedRuntimeCacheKeyEndpoint, normalizeRuntimePublicPath, parsePublishedRuntimeCacheKey, parsePublishedRuntimeCacheKeyDetails, parsePublishedRuntimeCachePayloadSchemaVersion, resolveRuntimeCachePolicy, } from './client/runtimeCachePolicy';
+export type { ClassifyPublishedRuntimeCacheFreshnessInput, DerivePublishedRuntimeCacheKeyInput, DerivePublishedRuntimeCacheKeyResult, GetContentByPathRuntimeCacheParams, GetSiteRuntimeCacheParams, ParsePublishedRuntimeCacheKeyResult, ParsePublishedRuntimeCacheKeyDetailsResult, ParsePublishedRuntimeCachePayloadSchemaVersionResult, PublishedRuntimeCacheAdapter, PublishedRuntimeCacheAdapterErrorKind, PublishedRuntimeCacheFreshness, PublishedRuntimeCacheKey, PublishedRuntimeCacheKeyEndpoint, PublishedRuntimeCacheKeyError, PublishedRuntimeCachePayloadSchemaVersion, PublishedRuntimeCacheReadInput, PublishedRuntimeCacheReadResult, PublishedRuntimeCacheWriteInput, PublishedRuntimeNormalizedParams, ResolveRuntimeCachePolicyInput, RuntimeCacheLiveOnlyReason, RuntimeCacheParams, RuntimeCachePolicy, RuntimeCachePolicyKind, } from './client/runtimeCachePolicy';
 export type { RiverbankSiteConfig, SiteStyleConfig, SectionBackground, SectionOptionsConfig, ContainerOptionsConfig, SectionSpacing, ContainerMaxWidth, ContainerAlignment, } from './config';
 export { SYSTEM_BLOCK_KINDS, type SystemBlockKind, type CustomBlockKind, type BlockKind, } from './types';

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.88.0";
+export declare const SDK_VERSION = "0.89.1";