@relyio/sdk 0.3.0 → 0.4.0

package/dist/{index-ulOrcfPa.d.cts → index-DFehx5sI.d.cts}

@@ -452,6 +452,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/v1/changes': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Poll the changes feed
+         * @description Long-polls: when nothing after `since` is visible to this key yet, the request is held until a write lands in the dataset or the hold ends, then answered with what the ledger says. Each change carries ids only — entry, content type, locale, kind and cursor — and is refetched through the ordinary read path. The key decides what is visible: a published key sees publication changes, a preview key sees draft changes as well. `RESOURCE_EXPIRED` means the cursor can no longer be replayed; resync and start again without one. With `Accept: text/event-stream` the same request is a Server-Sent Events stream instead: a `change` frame per change, a `heartbeat` carrying the cursor when nothing has happened for a while, and `complete` with the cursor to reconnect from before the stream ends — which it does after a few minutes, by design. A refusal before the stream opens is an `error` frame at the refusal’s status; one after it is the last frame. When the service is holding as many of these as it can, or the key as many as its plan allows, the request is answered at once instead — an empty page whose `nextCursor` is `since`, or a stream that is only `complete` — with `Retry-After` saying how many seconds to wait before asking again.
+         */
+        get: operations['pollChanges'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/v1/meta/content-types': {
         parameters: {
             query?: never;
@@ -797,6 +817,17 @@ interface paths {
 }
 interface components {
     schemas: {
+        /** @description One change to one entry, ids only. Refetch the entry through the ordinary read path to see it. */
+        Change: {
+            entryId: string;
+            contentType: string;
+            /** @description The locale the write addressed, or null when it addressed the whole entry. */
+            locale: string | null;
+            /** @enum {string} */
+            kind: 'deleted' | 'published' | 'unpublished' | 'updated';
+            /** @description Opaque. The cursor of the ledger row this change came from; changes from one row share it. */
+            cursor: string;
+        };
         CursorPage: {
             nextCursor: string | null;
             hasMore: boolean;
@@ -804,7 +835,7 @@ interface components {
         ErrorResponse: {
             error: {
                 /** @enum {string} */
-                code: 'ACCESS_DENIED' | 'CONTENT_INVALID' | 'INTERNAL_ERROR' | 'INVALID_API_KEY' | 'METHOD_NOT_ALLOWED' | 'MISSING_API_KEY' | 'PAYLOAD_TOO_LARGE' | 'PLAN_FEATURE_UNAVAILABLE' | 'RATE_LIMIT_EXCEEDED' | 'READ_ONLY_KEY' | 'REQUEST_INVALID' | 'REQUEST_TIMEOUT' | 'RESOURCE_CONFLICT' | 'RESOURCE_EXPIRED' | 'RESOURCE_NOT_FOUND' | 'REVERIFICATION_REQUIRED' | 'SERVICE_INDETERMINATE' | 'TRANSACTION_ROLLED_BACK' | 'USAGE_QUOTA_EXCEEDED';
+                code: 'ACCESS_DENIED' | 'CONTENT_INVALID' | 'INTERNAL_ERROR' | 'INVALID_API_KEY' | 'METHOD_NOT_ALLOWED' | 'MISSING_API_KEY' | 'PAYLOAD_TOO_LARGE' | 'PLAN_DOWNGRADE_BLOCKED' | 'PLAN_FEATURE_UNAVAILABLE' | 'RATE_LIMIT_EXCEEDED' | 'READ_ONLY_KEY' | 'REQUEST_INVALID' | 'REQUEST_TIMEOUT' | 'RESOURCE_CONFLICT' | 'RESOURCE_EXPIRED' | 'RESOURCE_NOT_FOUND' | 'REVERIFICATION_REQUIRED' | 'SERVICE_INDETERMINATE' | 'TRANSACTION_ROLLED_BACK' | 'USAGE_QUOTA_EXCEEDED';
                 messages: string[];
                 details?: {
                     [key: string]: unknown;
@@ -967,7 +998,7 @@ interface components {
             id?: string;
             error: {
                 /** @enum {string} */
-                code: 'ACCESS_DENIED' | 'CONTENT_INVALID' | 'INTERNAL_ERROR' | 'INVALID_API_KEY' | 'METHOD_NOT_ALLOWED' | 'MISSING_API_KEY' | 'PAYLOAD_TOO_LARGE' | 'PLAN_FEATURE_UNAVAILABLE' | 'RATE_LIMIT_EXCEEDED' | 'READ_ONLY_KEY' | 'REQUEST_INVALID' | 'REQUEST_TIMEOUT' | 'RESOURCE_CONFLICT' | 'RESOURCE_EXPIRED' | 'RESOURCE_NOT_FOUND' | 'REVERIFICATION_REQUIRED' | 'SERVICE_INDETERMINATE' | 'TRANSACTION_ROLLED_BACK' | 'USAGE_QUOTA_EXCEEDED';
+                code: 'ACCESS_DENIED' | 'CONTENT_INVALID' | 'INTERNAL_ERROR' | 'INVALID_API_KEY' | 'METHOD_NOT_ALLOWED' | 'MISSING_API_KEY' | 'PAYLOAD_TOO_LARGE' | 'PLAN_DOWNGRADE_BLOCKED' | 'PLAN_FEATURE_UNAVAILABLE' | 'RATE_LIMIT_EXCEEDED' | 'READ_ONLY_KEY' | 'REQUEST_INVALID' | 'REQUEST_TIMEOUT' | 'RESOURCE_CONFLICT' | 'RESOURCE_EXPIRED' | 'RESOURCE_NOT_FOUND' | 'REVERIFICATION_REQUIRED' | 'SERVICE_INDETERMINATE' | 'TRANSACTION_ROLLED_BACK' | 'USAGE_QUOTA_EXCEEDED';
                 messages: string[];
                 details?: {
                     [key: string]: unknown;
@@ -3526,6 +3557,150 @@ interface operations {
             };
         };
     };
+    pollChanges: {
+        parameters: {
+            query?: {
+                /** @description Comma-separated entry ids to keep, at most 100. Omitted keeps every entry. */
+                ids?: string;
+                /** @description Ledger rows to scan, 1 to 500; default 100. Rows, not changes: one write can name many entries, and a page never ends inside one. */
+                limit?: number;
+                /** @description The opaque cursor a previous page returned as `page.nextCursor`. Omitted, the answer is the dataset’s current position and no changes, at once. */
+                since?: string;
+                /** @description Comma-separated content types to keep. Omitted keeps every type. */
+                types?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Success. */
+            200: {
+                headers: {
+                    'Retry-After'?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': {
+                        data: components['schemas']['Change'][];
+                        page: components['schemas']['CursorPage'];
+                    };
+                    'text/event-stream': {
+                        /** @enum {string} */
+                        type: 'change' | 'complete' | 'error' | 'heartbeat';
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description REQUEST_INVALID */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['RefusalRequestInvalid'];
+                    'text/event-stream': {
+                        /** @enum {string} */
+                        type: 'change' | 'complete' | 'error' | 'heartbeat';
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description INVALID_API_KEY, MISSING_API_KEY */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['RefusalInvalidApiKeyOrMissingApiKey'];
+                    'text/event-stream': {
+                        /** @enum {string} */
+                        type: 'change' | 'complete' | 'error' | 'heartbeat';
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description ACCESS_DENIED, PLAN_FEATURE_UNAVAILABLE, USAGE_QUOTA_EXCEEDED */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['RefusalAccessDeniedOrPlanFeatureUnavailableOrUsageQuotaExceeded'];
+                    'text/event-stream': {
+                        /** @enum {string} */
+                        type: 'change' | 'complete' | 'error' | 'heartbeat';
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description RESOURCE_EXPIRED */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['RefusalResourceExpired'];
+                    'text/event-stream': {
+                        /** @enum {string} */
+                        type: 'change' | 'complete' | 'error' | 'heartbeat';
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description RATE_LIMIT_EXCEEDED */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['RefusalRateLimitExceeded'];
+                    'text/event-stream': {
+                        /** @enum {string} */
+                        type: 'change' | 'complete' | 'error' | 'heartbeat';
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description INTERNAL_ERROR */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['RefusalInternalError'];
+                    'text/event-stream': {
+                        /** @enum {string} */
+                        type: 'change' | 'complete' | 'error' | 'heartbeat';
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description SERVICE_INDETERMINATE */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['RefusalServiceIndeterminate'];
+                    'text/event-stream': {
+                        /** @enum {string} */
+                        type: 'change' | 'complete' | 'error' | 'heartbeat';
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+    };
     listContentTypes: {
         parameters: {
             query?: never;
@@ -3539,7 +3714,6 @@ interface operations {
             200: {
                 headers: {
                     'Cache-Control'?: string;
-                    ETag?: string;
                     Vary?: string;
                     'X-Cache'?: string;
                     'X-Cache-Key'?: string;
@@ -3621,7 +3795,6 @@ interface operations {
             200: {
                 headers: {
                     'Cache-Control'?: string;
-                    ETag?: string;
                     Vary?: string;
                     'X-Cache'?: string;
                     'X-Cache-Key'?: string;
@@ -3712,7 +3885,6 @@ interface operations {
             200: {
                 headers: {
                     'Cache-Control'?: string;
-                    ETag?: string;
                     Vary?: string;
                     'X-Cache'?: string;
                     'X-Cache-Key'?: string;
@@ -3794,7 +3966,6 @@ interface operations {
             200: {
                 headers: {
                     'Cache-Control'?: string;
-                    ETag?: string;
                     Vary?: string;
                     'X-Cache'?: string;
                     'X-Cache-Key'?: string;
@@ -3887,7 +4058,6 @@ interface operations {
             200: {
                 headers: {
                     'Cache-Control'?: string;
-                    ETag?: string;
                     Vary?: string;
                     'X-Cache'?: string;
                     'X-Cache-Key'?: string;
@@ -3980,7 +4150,6 @@ interface operations {
             200: {
                 headers: {
                     'Cache-Control'?: string;
-                    ETag?: string;
                     Vary?: string;
                     'X-Cache'?: string;
                     'X-Cache-Key'?: string;
@@ -5629,6 +5798,35 @@ type PathParamsOf<P extends ApiPath, M extends ApiMethod<P>> = Operation<P, M> e
         path?: infer X;
     };
 } ? [X] extends [undefined] ? never : NonNullable<X> : never;
+/** What {@link matchRoute} recovers from a URL the client emitted. */
+interface RouteMatch {
+    /** The document's path template — the value a tag translator switches on. */
+    path: ApiPath;
+    /** The template's `{name}` segments, decoded: the inverse of {@link fillPath}. */
+    params: Record<string, string>;
+    /** The query string; a key that appears more than once comes back as an array. */
+    query: Record<string, string | string[]>;
+}
+interface MatchRouteOptions {
+    /**
+     * The client's `baseUrl`, when it carries a path prefix of its own
+     * (`https://example.com/relyio`). Its path is removed before the template is
+     * matched. Unneeded for the default `https://api.relyio.com`.
+     */
+    baseUrl?: string;
+}
+/**
+ * Recover the route a URL names: the inverse of {@link fillPath}, over the same
+ * committed document (`INV-API-CLIENT-IS-DERIVED`).
+ *
+ * `matchRoute(url).path` is an `ApiPath`, so anything that keys behaviour on a
+ * request — a cache-tag translator, say — switches on the document's templates
+ * and never on a route table of its own.
+ *
+ * Returns `null` for a URL no declared template matches — a presigned storage
+ * URL, or a path outside `baseUrl` — rather than a guess.
+ */
+declare function matchRoute(url: string | URL, options?: MatchRouteOptions): RouteMatch | null;
 
 /**
  * Configuration types for the RelyIO SDK
@@ -5659,7 +5857,13 @@ interface RelyIOConfig {
     useSsl?: boolean;
     /** Environment mode */
     environment?: 'development' | 'staging' | 'production';
-    /** Cache configuration */
+    /**
+     * Cache configuration.
+     *
+     * Declarative only: the client keeps no response cache, and nothing in it reads
+     * these values, so every call goes to `fetch`. There is no SDK-side cache to
+     * turn off under a framework that caches `fetch` itself (Next.js).
+     */
     cache?: CacheConfig;
     /** Real-time configuration */
     realtime?: RealtimeConfig;
@@ -5667,6 +5871,25 @@ interface RelyIOConfig {
     debug?: DebugConfig;
     /** Custom headers to include with requests */
     headers?: Record<string, string>;
+    /**
+     * The function every request to the RelyIO API is sent through. Omit it and the
+     * client calls the runtime's `globalThis.fetch`, looked up per request. File
+     * bytes an asset upload PUTs straight to a presigned storage URL do not pass
+     * through it.
+     *
+     * The client still builds every request — URL, method, headers, body, signal —
+     * and hands this function that `RequestInit` unchanged, retries included, so an
+     * `Idempotency-Key` minted for a write is the same on every attempt. Supply one
+     * to add what your framework reads off the `RequestInit`, for example Next.js
+     * cache tags:
+     *
+     * @example
+     * const client = createClient({
+     *   apiKey: '...',
+     *   fetch: (input, init) => fetch(input, { ...init, next: { tags: ['posts'] } }),
+     * })
+     */
+    fetch?: typeof globalThis.fetch;
     /** Browser-specific configuration */
     browser?: BrowserConfig;
     /**
@@ -5800,7 +6023,12 @@ interface BrowserConfig {
 type CacheStrategy = 'memory' | 'persistent' | 'network-first' | 'cache-first' | 'stale-while-revalidate';
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 type Environment = 'development' | 'staging' | 'production';
-type MergedRelyIOConfig = Required<Omit<RelyIOConfig, 'dataset' | 'locale' | 'dev'>> & Pick<RelyIOConfig, 'dataset' | 'locale' | 'dev'>;
+/**
+ * `fetch` stays optional after the merge: absent means the runtime's own, and
+ * that is read per request rather than captured here, so no default value
+ * stands in for it.
+ */
+type MergedRelyIOConfig = Required<Omit<RelyIOConfig, 'dataset' | 'locale' | 'dev' | 'fetch'>> & Pick<RelyIOConfig, 'dataset' | 'locale' | 'dev' | 'fetch'>;
 
 /**
  * Base error class for all RelyIO SDK errors
@@ -6213,4 +6441,4 @@ interface PerformanceMetrics {
     cacheHitRatio?: number;
 }
 
-export { type ApiPath as A, type BaseContent as B, type CreateInput as C, type DebugConfig as D, type Environment as E, type FieldTypeName as F, type PathParamsOf as G, type components as H, InvalidPayloadError as I, type FieldDefinition as J, type LogLevel as L, type MergedRelyIOConfig as M, type PerformanceMetrics as P, type QueryOptions as Q, type RelyIOConfig as R, SDKError as S, type UpdateInput as U, type ValidationRule as V, type Wire as W, type ApiMethod as a, type ApiSuccessBody as b, type WhereClause as c, type WhereOperator as d, type SortOptions as e, type ContentQueryResult as f, type SingletonContent as g, type SettingsGroup as h, type CustomQuery as i, type ContentTypeSchema as j, type FieldOptions as k, type RealtimeEventType as l, type RealtimeEvent as m, type SubscriptionOptions as n, type CacheConfig as o, type RealtimeConfig as p, type RequestConfig as q, type ApiResponse as r, type RetryConfig as s, type CacheStrategy as t, type ValidationViolation as u, BaseValidationError as v, ValidationError as w, SchemaValidationError as x, RequiredFieldError as y, InvalidFieldTypeError as z };
+export { type ApiPath as A, type BaseContent as B, type CreateInput as C, type DebugConfig as D, type Environment as E, type FieldTypeName as F, RequiredFieldError as G, InvalidFieldTypeError as H, InvalidPayloadError as I, type MergedRelyIOConfig as J, type PathParamsOf as K, type LogLevel as L, type MatchRouteOptions as M, type components as N, type paths as O, type PerformanceMetrics as P, type QueryOptions as Q, type RelyIOConfig as R, SDKError as S, type FieldDefinition as T, type UpdateInput as U, type ValidationRule as V, type Wire as W, type ApiMethod as a, type ApiSuccessBody as b, type RouteMatch as c, type WhereClause as d, type WhereOperator as e, type SortOptions as f, type ContentQueryResult as g, type SingletonContent as h, type SettingsGroup as i, type CustomQuery as j, type ContentTypeSchema as k, type FieldOptions as l, matchRoute as m, type RealtimeEventType as n, type RealtimeEvent as o, type SubscriptionOptions as p, type CacheConfig as q, type RealtimeConfig as r, type RequestConfig as s, type ApiResponse as t, type RetryConfig as u, type CacheStrategy as v, type ValidationViolation as w, BaseValidationError as x, ValidationError as y, SchemaValidationError as z };