@relyio/sdk 0.2.1 → 0.4.0

package/dist/dev-handshake/index.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+var chunkLSRPMNPT_cjs = require('../chunk-LSRPMNPT.cjs');
+require('../chunk-MWMSFIWN.cjs');
+
+
+
+Object.defineProperty(exports, "DEV_CONTEXT_DIR", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.DEV_CONTEXT_DIR; }
+});
+Object.defineProperty(exports, "DEV_CONTEXT_FILE", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.DEV_CONTEXT_FILE; }
+});
+Object.defineProperty(exports, "DEV_CONTEXT_FILENAME", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.DEV_CONTEXT_FILENAME; }
+});
+Object.defineProperty(exports, "DEV_ENV", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.DEV_ENV; }
+});
+Object.defineProperty(exports, "buildDevEnv", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.buildDevEnv; }
+});
+Object.defineProperty(exports, "parseDevContextFile", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.parseDevContextFile; }
+});
+Object.defineProperty(exports, "parseDevEnv", {
+  enumerable: true,
+  get: function () { return chunkLSRPMNPT_cjs.parseDevEnv; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/dev-handshake/index.d.cts

@@ -0,0 +1,144 @@
+/**
+ * The `relyio dev` handshake: the one declaration of how a sandbox reaches a running app.
+ *
+ * `relyio dev` provisions an ephemeral sandbox and hands its connection details to the developer's
+ * app by two carriers, which `sandboxes-spec.md` presents as interchangeable:
+ *
+ *  1. **Env** — `relyio dev -- pnpm dev` injects `RELYIO_DEV_*` into the wrapped child process.
+ *  2. **File** — `.relyio/dev.json`, for an app started standalone beside the cockpit.
+ *
+ * Three consumers read this: the SDK (both carriers), and `relyio promote` (the file, to work out
+ * which sandbox this repo is developing against). Before REL-647 each had its own copy of the
+ * answer and the three disagreed — the file required `branchId` in the CLI and not in the SDK, an
+ * unparseable deadline read as *unbounded*, and **the env carrier had no expiry at all**, so
+ * `relyio dev` and `relyio dev -- pnpm dev` were not in fact interchangeable: the same lapsed
+ * sandbox stopped working under one and kept working for the life of the process under the other.
+ *
+ * So this module is the declaration, and it is deliberately **pure** — no `node:*`, no I/O, no
+ * clock of its own. Each consumer keeps the I/O shell it needs (the SDK cannot statically import
+ * `node:fs`; the CLI is async and knows the project root) and none of them keeps a rule.
+ *
+ * **On the direction of the dependency.** The CLI *writes* this file and the SDK *reads* it, so
+ * publishing the declaration from the reader inverts writer→reader, which is worth knowing when
+ * you change it. It is the right trade anyway: the SDK is already dependency-free and browser-safe
+ * by construction, so the declaration costs it nothing, while the CLI bundles every `@relyio/*`
+ * into its published artifact and can absorb the import. The alternative — a third package — buys
+ * a version stream for four constants and a parser.
+ */
+/** Directory, relative to the project root, that holds the dev artifact. Hidden, git-ignored. */
+declare const DEV_CONTEXT_DIR = ".relyio";
+/** Filename of the dev artifact inside {@link DEV_CONTEXT_DIR}. */
+declare const DEV_CONTEXT_FILENAME = "dev.json";
+/**
+ * Path of the dev artifact relative to the project root, POSIX-separated.
+ *
+ * The one place this path is spelled. It is also exactly the `.gitignore` entry, which must use a
+ * forward slash on every platform — so the constant is a literal rather than a `path.join`, and
+ * callers that need a filesystem path join it onto their own root.
+ */
+declare const DEV_CONTEXT_FILE = ".relyio/dev.json";
+/**
+ * The environment variables `relyio dev` injects into a wrapped child process.
+ *
+ * `expiresAt` is the REL-647 addition. Without it the env carrier could not express a deadline, so
+ * it was exempt from the expiry the file carrier enforced — which is the whole of Gap 3.
+ */
+declare const DEV_ENV: {
+    readonly dataset: "RELYIO_DEV_DATASET";
+    readonly apiKey: "RELYIO_DEV_API_KEY";
+    readonly expiresAt: "RELYIO_DEV_EXPIRES_AT";
+};
+/** The `.relyio/dev.json` shape, as `relyio dev` writes it. All four keys; `expiresAt` nullable. */
+interface DevContext {
+    /** Ephemeral sandbox dataset the app should read (`X-RelyIO-Dataset`). */
+    datasetId: string;
+    /** Scoped read-only preview key for the sandbox dataset (`X-API-Key`). */
+    previewApiKey: string;
+    /** Sandbox branch id — informational to the SDK; `relyio promote` identifies the sandbox by it. */
+    branchId: string;
+    /**
+     * ISO deadline of the sandbox's current lifecycle state, or null when unbounded.
+     *
+     * This is `sandbox.expiresAt` from the provisioning bundle — when the sandbox is due to be
+     * suspended or archived — not the preview key's own `expiresAt`. Past it, the dataset may be
+     * archived and the key deactivated, so the handshake names a sandbox that no longer answers.
+     */
+    expiresAt: string | null;
+}
+/** The credentials a carrier yields once it has been accepted. */
+interface DevCredentials {
+    dataset: string;
+    apiKey: string;
+}
+/** Why a carrier's payload could not be understood. */
+type DevUnreadableReason = 'not-json' | 'missing-fields' | 'bad-expiry';
+/**
+ * What a carrier says, as a closed set of named states.
+ *
+ * There is deliberately no `null` or falsy arm, on any path. "Expired", "absent" and "corrupt" lead
+ * to different advice — refresh the key, start a sandbox, delete the file — and collapsing them to
+ * one falsy value is what let an app with a lapsed sandbox read **production** in silence and let
+ * `relyio promote` act on a stale identity. An absent input is a declared state, not a default.
+ */
+type DevContextVerdict = {
+    state: 'active';
+    context: DevContext;
+} | {
+    state: 'expired';
+    context: DevContext;
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+};
+/** What the env carrier says. It carries no `branchId`; only the file identifies a branch. */
+type DevEnvVerdict = {
+    state: 'active';
+    credentials: DevCredentials;
+    expiresAt: string | null;
+} | {
+    state: 'expired';
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+};
+/**
+ * Decide what the text of `.relyio/dev.json` says, against a caller-supplied clock.
+ *
+ * All three of `datasetId`, `previewApiKey` and `branchId` are **required**. `relyio dev` has
+ * always written all four keys and the spec documents all four, so a file missing one is corrupt
+ * rather than a narrower dialect — before REL-647 the CLI required `branchId` and the SDK did not,
+ * so one file read as absent to one binary and usable to the other.
+ *
+ * The clock is a parameter rather than a `Date.now()` inside, so the boundary is testable without
+ * faking time, and so this module stays pure.
+ */
+declare function parseDevContextFile(raw: string, now: number): DevContextVerdict;
+/**
+ * Build the `RELYIO_DEV_*` environment `relyio dev` injects into a wrapped child.
+ *
+ * The counterpart of {@link parseDevEnv}, and the reason the env names are single-sourced: the
+ * binary that writes them and the library that reads them now use one object. `expiresAt` is
+ * omitted rather than emitted empty when the sandbox is unbounded, so the variable's presence
+ * means "there is a deadline".
+ */
+declare function buildDevEnv(context: Pick<DevContext, 'datasetId' | 'previewApiKey' | 'expiresAt'>): Record<string, string>;
+/**
+ * Decide what the `RELYIO_DEV_*` environment says, against a caller-supplied clock.
+ *
+ * The env carrier names no branch, so it yields credentials rather than a {@link DevContext}. It
+ * applies the same deadline rule the file does — that equivalence is Gap 3, and the reason
+ * {@link DEV_ENV}`.expiresAt` exists at all.
+ *
+ * A deadline present but unreadable refuses the credentials. That is deliberate and is the same
+ * choice the file path makes: a wrapped process whose deadline we cannot read is not a process we
+ * can say is inside its window.
+ */
+declare function parseDevEnv(env: Record<string, string | undefined> | undefined, now: number): DevEnvVerdict;
+
+export { DEV_CONTEXT_DIR, DEV_CONTEXT_FILE, DEV_CONTEXT_FILENAME, DEV_ENV, type DevContext, type DevContextVerdict, type DevCredentials, type DevEnvVerdict, type DevUnreadableReason, buildDevEnv, parseDevContextFile, parseDevEnv };

package/dist/dev-handshake/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The `relyio dev` handshake: the one declaration of how a sandbox reaches a running app.
+ *
+ * `relyio dev` provisions an ephemeral sandbox and hands its connection details to the developer's
+ * app by two carriers, which `sandboxes-spec.md` presents as interchangeable:
+ *
+ *  1. **Env** — `relyio dev -- pnpm dev` injects `RELYIO_DEV_*` into the wrapped child process.
+ *  2. **File** — `.relyio/dev.json`, for an app started standalone beside the cockpit.
+ *
+ * Three consumers read this: the SDK (both carriers), and `relyio promote` (the file, to work out
+ * which sandbox this repo is developing against). Before REL-647 each had its own copy of the
+ * answer and the three disagreed — the file required `branchId` in the CLI and not in the SDK, an
+ * unparseable deadline read as *unbounded*, and **the env carrier had no expiry at all**, so
+ * `relyio dev` and `relyio dev -- pnpm dev` were not in fact interchangeable: the same lapsed
+ * sandbox stopped working under one and kept working for the life of the process under the other.
+ *
+ * So this module is the declaration, and it is deliberately **pure** — no `node:*`, no I/O, no
+ * clock of its own. Each consumer keeps the I/O shell it needs (the SDK cannot statically import
+ * `node:fs`; the CLI is async and knows the project root) and none of them keeps a rule.
+ *
+ * **On the direction of the dependency.** The CLI *writes* this file and the SDK *reads* it, so
+ * publishing the declaration from the reader inverts writer→reader, which is worth knowing when
+ * you change it. It is the right trade anyway: the SDK is already dependency-free and browser-safe
+ * by construction, so the declaration costs it nothing, while the CLI bundles every `@relyio/*`
+ * into its published artifact and can absorb the import. The alternative — a third package — buys
+ * a version stream for four constants and a parser.
+ */
+/** Directory, relative to the project root, that holds the dev artifact. Hidden, git-ignored. */
+declare const DEV_CONTEXT_DIR = ".relyio";
+/** Filename of the dev artifact inside {@link DEV_CONTEXT_DIR}. */
+declare const DEV_CONTEXT_FILENAME = "dev.json";
+/**
+ * Path of the dev artifact relative to the project root, POSIX-separated.
+ *
+ * The one place this path is spelled. It is also exactly the `.gitignore` entry, which must use a
+ * forward slash on every platform — so the constant is a literal rather than a `path.join`, and
+ * callers that need a filesystem path join it onto their own root.
+ */
+declare const DEV_CONTEXT_FILE = ".relyio/dev.json";
+/**
+ * The environment variables `relyio dev` injects into a wrapped child process.
+ *
+ * `expiresAt` is the REL-647 addition. Without it the env carrier could not express a deadline, so
+ * it was exempt from the expiry the file carrier enforced — which is the whole of Gap 3.
+ */
+declare const DEV_ENV: {
+    readonly dataset: "RELYIO_DEV_DATASET";
+    readonly apiKey: "RELYIO_DEV_API_KEY";
+    readonly expiresAt: "RELYIO_DEV_EXPIRES_AT";
+};
+/** The `.relyio/dev.json` shape, as `relyio dev` writes it. All four keys; `expiresAt` nullable. */
+interface DevContext {
+    /** Ephemeral sandbox dataset the app should read (`X-RelyIO-Dataset`). */
+    datasetId: string;
+    /** Scoped read-only preview key for the sandbox dataset (`X-API-Key`). */
+    previewApiKey: string;
+    /** Sandbox branch id — informational to the SDK; `relyio promote` identifies the sandbox by it. */
+    branchId: string;
+    /**
+     * ISO deadline of the sandbox's current lifecycle state, or null when unbounded.
+     *
+     * This is `sandbox.expiresAt` from the provisioning bundle — when the sandbox is due to be
+     * suspended or archived — not the preview key's own `expiresAt`. Past it, the dataset may be
+     * archived and the key deactivated, so the handshake names a sandbox that no longer answers.
+     */
+    expiresAt: string | null;
+}
+/** The credentials a carrier yields once it has been accepted. */
+interface DevCredentials {
+    dataset: string;
+    apiKey: string;
+}
+/** Why a carrier's payload could not be understood. */
+type DevUnreadableReason = 'not-json' | 'missing-fields' | 'bad-expiry';
+/**
+ * What a carrier says, as a closed set of named states.
+ *
+ * There is deliberately no `null` or falsy arm, on any path. "Expired", "absent" and "corrupt" lead
+ * to different advice — refresh the key, start a sandbox, delete the file — and collapsing them to
+ * one falsy value is what let an app with a lapsed sandbox read **production** in silence and let
+ * `relyio promote` act on a stale identity. An absent input is a declared state, not a default.
+ */
+type DevContextVerdict = {
+    state: 'active';
+    context: DevContext;
+} | {
+    state: 'expired';
+    context: DevContext;
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+};
+/** What the env carrier says. It carries no `branchId`; only the file identifies a branch. */
+type DevEnvVerdict = {
+    state: 'active';
+    credentials: DevCredentials;
+    expiresAt: string | null;
+} | {
+    state: 'expired';
+    expiredAt: string;
+} | {
+    state: 'unreadable';
+    reason: DevUnreadableReason;
+} | {
+    state: 'absent';
+};
+/**
+ * Decide what the text of `.relyio/dev.json` says, against a caller-supplied clock.
+ *
+ * All three of `datasetId`, `previewApiKey` and `branchId` are **required**. `relyio dev` has
+ * always written all four keys and the spec documents all four, so a file missing one is corrupt
+ * rather than a narrower dialect — before REL-647 the CLI required `branchId` and the SDK did not,
+ * so one file read as absent to one binary and usable to the other.
+ *
+ * The clock is a parameter rather than a `Date.now()` inside, so the boundary is testable without
+ * faking time, and so this module stays pure.
+ */
+declare function parseDevContextFile(raw: string, now: number): DevContextVerdict;
+/**
+ * Build the `RELYIO_DEV_*` environment `relyio dev` injects into a wrapped child.
+ *
+ * The counterpart of {@link parseDevEnv}, and the reason the env names are single-sourced: the
+ * binary that writes them and the library that reads them now use one object. `expiresAt` is
+ * omitted rather than emitted empty when the sandbox is unbounded, so the variable's presence
+ * means "there is a deadline".
+ */
+declare function buildDevEnv(context: Pick<DevContext, 'datasetId' | 'previewApiKey' | 'expiresAt'>): Record<string, string>;
+/**
+ * Decide what the `RELYIO_DEV_*` environment says, against a caller-supplied clock.
+ *
+ * The env carrier names no branch, so it yields credentials rather than a {@link DevContext}. It
+ * applies the same deadline rule the file does — that equivalence is Gap 3, and the reason
+ * {@link DEV_ENV}`.expiresAt` exists at all.
+ *
+ * A deadline present but unreadable refuses the credentials. That is deliberate and is the same
+ * choice the file path makes: a wrapped process whose deadline we cannot read is not a process we
+ * can say is inside its window.
+ */
+declare function parseDevEnv(env: Record<string, string | undefined> | undefined, now: number): DevEnvVerdict;
+
+export { DEV_CONTEXT_DIR, DEV_CONTEXT_FILE, DEV_CONTEXT_FILENAME, DEV_ENV, type DevContext, type DevContextVerdict, type DevCredentials, type DevEnvVerdict, type DevUnreadableReason, buildDevEnv, parseDevContextFile, parseDevEnv };

package/dist/dev-handshake/index.js

@@ -0,0 +1,4 @@
+export { DEV_CONTEXT_DIR, DEV_CONTEXT_FILE, DEV_CONTEXT_FILENAME, DEV_ENV, buildDevEnv, parseDevContextFile, parseDevEnv } from '../chunk-BBUB7C2Z.js';
+import '../chunk-XQ4QHWZE.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/{index-DGWaawHt.d.cts → index-BvO6HDtY.d.cts}

@@ -1,5 +1,6 @@
-import { M as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, G as PathParamsOf, r as ApiResponse, W as Wire, q as RequestConfig, B as BaseContent, c as WhereClause, e as SortOptions, f as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, v as BaseValidationError, u as ValidationViolation, H as components, R as RelyIOConfig } from './index-BsUqCAu8.cjs';
-import { x as SchemaDefinition, y as SchemaContentTypeNames, a6 as InferContentType, K as SchemaAssetTypeNames, at as InferAssetType, z as SchemaSingletonNames, ac as InferSingleton, J as SchemaSettingsGroupNames, an as InferSettingsGroup, G as SchemaQueryNames, H as SchemaLocaleCodes } from './define-schema-DHvUCKwj.cjs';
+import { J as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, K as PathParamsOf, t as ApiResponse, W as Wire, s as RequestConfig, B as BaseContent, d as WhereClause, f as SortOptions, g as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, x as BaseValidationError, w as ValidationViolation, N as components, O as paths, R as RelyIOConfig } from './index-DFehx5sI.cjs';
+import { a as SchemaDefinition, b as SchemaContentTypeNames, h as SchemaAssetTypeNames, M as InferAssetType, c as SchemaSingletonNames, t as InferSingleton, g as SchemaSettingsGroupNames, E as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-2xbHgtK-.cjs';
+import { J as InferContentType } from './define-content-type-CBfnTWSS.cjs';
 
 /**
  * What a call site supplies beside the route it named.
@@ -38,7 +39,7 @@ declare class HttpClient {
     private baseUrl;
     private defaultHeaders;
     private timeout;
-    private retryConfig;
+    private retryPolicy;
     private debug;
     private logger?;
     private config;
@@ -56,7 +57,16 @@ declare class HttpClient {
         data: unknown;
     } ? Wire<P, M, T>['data'] : never>;
     /**
-     * Make an HTTP request with retry logic
+     * Make an HTTP request, retrying only where a retry is safe.
+     *
+     * The headers are merged **once**, before the first attempt, and every attempt
+     * sends that same object. That is what makes a minted `Idempotency-Key` stable
+     * across the retries of one logical write: the service sees one key and
+     * answers the replay from the original outcome instead of applying it twice.
+     *
+     * The loop always makes one attempt. The incumbent's `while (attempt <
+     * maxAttempts)` made none at `retryAttempts: 0` — a value the config validator
+     * accepts — and then dereferenced an unassigned `lastError`.
      */
     request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
     /**
@@ -99,6 +109,16 @@ declare class HttpClient {
      * Get current base URL
      */
     getBaseUrl(): string;
+    /**
+     * One attempt.
+     *
+     * The caller's `signal` and the timeout both end it, through one controller.
+     * The incumbent handed `fetch` the caller's signal **instead of** its own, so a
+     * request that passed a signal had no timeout at all — and a caller abort then
+     * surfaced as `Request timed out`. `timedOut` is what tells the two apart: a
+     * timeout is a `TimeoutError`, a caller abort is the platform's `AbortError`,
+     * rethrown as it came.
+     */
     private makeRequest;
     /**
      * Filter headers that browsers don't allow to be set manually
@@ -113,7 +133,7 @@ declare class HttpClient {
     private mergeRequestConfig;
     private buildQueryString;
     private headersToObject;
-    private calculateRetryDelay;
+    /** A backoff the caller's abort cuts short; the next attempt then refuses to send. */
     private sleep;
     private log;
 }
@@ -427,13 +447,20 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
  */
 interface RetryableWriteOptions {
     /**
-     * A caller-chosen key that makes a retry of **this** write safe.
+     * A key that makes a retry of **this** write safe.
      *
      * A replay inside the service's window returns the original outcome rather
      * than applying twice. The service derives that response from committed state
      * pinned to the recorded version — it does not store bytes — so a replay after
      * the version has been pruned is refused `RESOURCE_EXPIRED` rather than
      * answered from a stale copy.
+     *
+     * **The SDK mints one when you do not.** It used to be caller-supplied and
+     * nothing else, which meant the default write carried no key while the retry
+     * loop replayed it anyway — the one mechanism that makes a replay safe was
+     * optional on the one path that needed it. Supply your own to make a key
+     * outlive the process: a job that may be restarted wants a key derived from
+     * the work, not one minted per call.
      */
     idempotencyKey?: string;
 }
@@ -2370,11 +2397,166 @@ declare class AdhocQueryClient {
 }
 
 /**
- * Type alias for any schema definition.
- * Uses `any` intentionally to accept schemas with any content types, components, etc.
- * This is necessary for the SDK to be flexible with user-defined schemas.
+ * Content and resource errors.
+ *
+ * `ContentTypeNotFoundError` and `ContentNotFoundError` were deleted at API5.
+ * The mapper reached them by sniffing `CONTENT_TYPE_NOT_FOUND` and
+ * `CONTENT_NOT_FOUND`, neither of which is in the closed vocabulary, so neither
+ * class was reachable. Both cases are `RESOURCE_NOT_FOUND`, whose declared
+ * `details` are `{ kind, id? }` — the same two facts, from the one code a route
+ * can actually declare.
+ */
+declare class ResourceNotFoundError extends SDKError {
+    readonly code = "RESOURCE_NOT_FOUND";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+declare class ResourceConflictError extends SDKError {
+    readonly code = "RESOURCE_CONFLICT";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+declare class ResourceExpiredError extends SDKError {
+    readonly code = "RESOURCE_EXPIRED";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+/**
+ * "Did the service say this resource does not exist?"
+ *
+ * Reads the **code**, not the status. Four contract codes are 4xx on a read and
+ * only one of them means "not there"; the incumbent checked `statusCode === 404`
+ * on the thrown value, and a second arm duck-typed a plain object for the same
+ * number so a hand-written test double would pass. Both are the branch
+ * `INV-API-CLIENT-IS-DERIVED` forbids where a code exists — and the second one
+ * only existed because the tests faked the boundary (rule 20). They now stub
+ * `fetch`, so the double is gone with the branch.
+ */
+declare function isResourceNotFound(error: unknown): boolean;
+
+/**
+ * `relyio.changes()` — the changes feed as a typed long-poll iterator
+ * (`sdk-surfaces-spec.md` decisions 16–18).
+ *
+ * Long-poll only, on purpose. `GET /v1/changes` is an ordinary cursor-paged
+ * collection the committed document declares, so each poll is one `send` over
+ * the one HTTP client (`INV-SS-ONE-CORE`, `INV-API-CLIENT-IS-DERIVED`). The SSE
+ * branch the route also serves would be a second transport path inside that
+ * client, and `parseResponse` buffers a whole body; it stays for `EventSource`
+ * and curl consumers.
+ */
+
+type PollChanges = paths['/v1/changes']['get'];
+/**
+ * The 200 body the document declares, read from its `application/json` content
+ * **by name**. The route also negotiates `text/event-stream`; naming the JSON
+ * content is what keeps that alternate from changing this type when the
+ * document gains it.
+ */
+type ChangesPageBody = PollChanges['responses'][200]['content']['application/json'];
+/**
+ * One change, as the committed document describes an item of the feed's `data`
+ * (`INV-SS-CHANGE-IS-IDS`: ids, content type, locale, kind and cursor — never a
+ * document).
+ *
+ * Read from the document, never written here: the api's route row names the
+ * `Change` component schema, and a change to it reaches this type when the
+ * document is regenerated. `changes.types.ts` holds it equal to the document's
+ * item, and fails if it is ever `unknown` again.
+ */
+type Change = ChangesPageBody['data'][number];
+/** Why a cursor could no longer be replayed. `unknown` when the message named neither. */
+type ChangesExpiredReason = 'retention' | 'dataset-replaced' | 'unknown';
+/**
+ * `RESOURCE_EXPIRED` from the changes feed: the cursor names a position the
+ * ledger can no longer replay from (`INV-SS-CURSOR-REPLAYS`). The consumer
+ * resyncs from the read path and starts again without a cursor.
+ *
+ * A `ResourceExpiredError`, so code that already catches that still does. The
+ * refusal declares no details, so `reason` is read from the message the api
+ * writes (`apps/services/api/src/changes/changes-request.ts` `refusalOf`).
+ */
+declare class ChangesExpiredError extends ResourceExpiredError {
+    readonly reason: ChangesExpiredReason;
+    /** The base class's signature, so `withContext` can rebuild one. */
+    constructor(message: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    static of(expired: ResourceExpiredError): ChangesExpiredError;
+}
+interface ChangesOptions {
+    /**
+     * A `page.nextCursor` — or a change's `cursor` — from an earlier poll. Omitted,
+     * the first poll answers the dataset's current position and no changes, at
+     * once, and the feed starts from there.
+     */
+    since?: string;
+    /** Content types to keep. Omitted keeps every type; an empty list is refused (400). */
+    types?: readonly string[];
+    /**
+     * Entry ids to keep. Omitted keeps every entry. The api refuses more than it
+     * allows (100 today) as `REQUEST_INVALID`, thrown from the iterator as an
+     * `InvalidPayloadError` on the first poll; the SDK does not restate the
+     * cap, so it cannot drift from the service's.
+     */
+    ids?: readonly string[];
+    /** Ledger rows one poll scans, 1 to 500; the api defaults to 100. */
+    limit?: number;
+    /**
+     * Ends the iteration. An abort — in flight, between polls, or while waiting
+     * out a `Retry-After` — makes the `for await` **complete**, with no further
+     * request and no `AbortError` thrown into the loop.
+     */
+    signal?: AbortSignal;
+    /**
+     * What to do when the cursor has expired.
+     *
+     * - `'throw'` (default) — the iterator throws {@link ChangesExpiredError}.
+     * - `'resync'` — restart from the dataset's current position and keep going.
+     * - a function — resync, and call it with the error once the new position is
+     *   taken and before any change after it is yielded. This is the observable
+     *   form: whatever the consumer derived from the feed may be stale, so the
+     *   function is where it invalidates everything. The iterator waits for it.
+     */
+    onExpired?: 'throw' | 'resync' | ((expired: ChangesExpiredError) => void | Promise<void>);
+}
+
+/**
+ * Any schema the client can be typed by. `any` is deliberate: the client accepts whatever content
+ * types, components, singletons, queries and settings groups a customer declares.
+ *
+ * This is the constraint `TypedRelyIOClient`'s `TSchema` carries, so `RegisteredSchema` is inferred
+ * against the same one — `createClient` returns `TypedRelyIOClient<RegisteredSchema>`, and a schema
+ * inferred against any wider alias would not be provably inside the client's bound.
  */
 type AnySchemaDefinition = SchemaDefinition<any, any, any, any, any>;
+/**
+ * The seam `relyio generate-types` fills (`INV-SS-TYPES-INFERRED`).
+ *
+ * Empty here on purpose. The generated `schema.ts` augments it —
+ *
+ * ```ts
+ * declare module '@relyio/sdk' {
+ *   interface Register {
+ *     schema: typeof schema
+ *   }
+ * }
+ * ```
+ *
+ * — and from then on `createClient({ apiKey })`, with no generic and no `schema:`, is typed by that
+ * schema. The pattern is TanStack Router's. It is type-level only: nothing at runtime reads it.
+ */
+interface Register {
+}
+/**
+ * The schema the project registered through `Register`, or `undefined` when nothing did — which is
+ * the untyped client, exactly as before the generator ran.
+ */
+type RegisteredSchema = Register extends {
+    schema: infer S extends AnySchemaDefinition;
+} ? S : undefined;
+
 /**
  * Client configuration with optional schema
  */
@@ -2539,6 +2721,32 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```
      */
     batch(): BatchBuilder<NonNullable<TSchema>>;
+    /**
+     * Follow the dataset's changes feed: each write this key can see, as ids, in
+     * order, long-polled from `GET /v1/changes`.
+     *
+     * Lazy — nothing is requested until the first `next()`. It runs until
+     * `signal` aborts, which ends the `for await` cleanly rather than throwing.
+     * A change names what changed; refetch it through the ordinary read path
+     * (`INV-SS-CHANGE-IS-IDS`).
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController()
+     * for await (const change of relyio.changes({ since: cursor, types: ['post'], signal: controller.signal })) {
+     *   // { entryId, contentType, locale, kind, cursor }
+     * }
+     * ```
+     *
+     * @example Resync when the cursor has expired
+     * ```typescript
+     * for await (const change of relyio.changes({
+     *   since: cursor,
+     *   onExpired: async () => invalidateEverything(),
+     * })) { … }
+     * ```
+     */
+    changes(options?: ChangesOptions): AsyncIterable<Change>;
     /**
      * Build and execute an ad-hoc query dynamically
      *
@@ -2697,12 +2905,29 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
  * // Content type names autocomplete!
  * const products = await relyio.content('product').fetchAll()
  * ```
- */
+ *
+ * @example After `relyio generate-types` (inferred, `INV-SS-TYPES-INFERRED`)
+ * ```typescript
+ * import { createClient } from '@relyio/sdk'
+ *
+ * // The generated `schema.ts` augments `Register`, so no generic and no `schema:` are needed
+ * const relyio = createClient({ apiKey: process.env.RELYIO_API_KEY! })
+ * ```
+ *
+ * The overload without a schema comes first on purpose. Behind the generic one it was never
+ * chosen: with no `schema` to infer from, `TSchema` fell back to its constraint and the call
+ * resolved to `TypedRelyIOClient<AnySchemaDefinition>`. First, it takes every call that passes no
+ * schema, and returns the registered schema's client — or the untyped one when nothing registered.
+ * A `schema:` value fails its `schema?: undefined`, and an explicit generic skips it because it has
+ * no type parameter, so both reach the generic overload unchanged.
+ */
+declare function createClient(config: RelyIOConfig & {
+    schema?: undefined;
+}): TypedRelyIOClient<RegisteredSchema>;
 declare function createClient<TSchema extends AnySchemaDefinition>(config: TypedClientConfig<TSchema>): TypedRelyIOClient<TSchema>;
-declare function createClient(config: RelyIOConfig): TypedRelyIOClient<undefined>;
 /**
  * Helper type to extract schema from client
  */
 type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
 
-export { AssetFileBuilder as $, AutocompleteBuilder as A, BatchClient as B, type ClientSchema as C, type BatchOperation as D, type ExtendedQueryResult as E, type BatchOptions as F, type BatchOperationResult as G, HttpClient as H, type BatchSummary as I, type BatchResponse as J, AdhocQueryClient as K, AdhocQueryBuilder as L, type FetchBlock as M, type AggregateBlock as N, type AggregateMetric as O, type SearchBlock as P, type SimilarBlock as Q, type RetryableWriteOptions as R, type SendOptions as S, TypedRelyIOClient as T, type FilterValue as U, type FullTextConfig as V, type AdhocQueryDefinition as W, type AdhocQueryOptions as X, type QueryMetadata as Y, type AdhocQueryResult as Z, AssetClient as _, type TypedClientConfig as a, AssetUploadBuilder as a0, isAssetEntry as a1, type AssetVisibility as a2, type FileStatus as a3, type FileBackend as a4, type AssetFileBlock as a5, type AssetFileExtracted as a6, type AssetUrls as a7, type AssetEntryResponse as a8, type PopulatedAssetReference as a9, type PresignInput as aa, type PresignResult as ab, type ConfirmInput as ac, type ConfirmResult as ad, type ResolveUrlInput as ae, type ResolveUrlResult as af, type CreateAssetOptions as ag, type WaitUntilReadyOptions as ah, type MultipartCreateResult as ai, type MultipartPart as aj, type MultipartTarget as ak, type UploadProgress as al, type FileErrorCode as am, FileUploadError as an, FileValidationError as ao, type FileValidationConstraints as ap, validateFile as aq, type ConditionalWriteOptions as b, createClient as c, ContentClient as d, entityTagOf as e, SingletonClient as f, SettingsClient as g, ContentQueryBuilder as h, ContentByIdBuilder as i, type ChildrenOptions as j, type SingletonFetchOptions as k, type SettingsFetchOptions as l, SearchClient as m, SearchBuilder as n, SimilarBuilder as o, type SearchMode as p, type SearchResultItem as q, type SearchResponse as r, type AutocompleteSuggestion as s, type AutocompleteResponse as t, type SimilarResult as u, type SimilarResponse as v, type SearchFilter as w, type SearchFields as x, BatchBuilder as y, type BatchMethod as z };
+export { type FullTextConfig as $, AutocompleteBuilder as A, type SimilarResult as B, type ClientSchema as C, type SimilarResponse as D, type ExtendedQueryResult as E, type SearchFilter as F, type SearchFields as G, HttpClient as H, BatchClient as I, BatchBuilder as J, type BatchMethod as K, type BatchOperation as L, type BatchOptions as M, type BatchOperationResult as N, type BatchSummary as O, type BatchResponse as P, AdhocQueryClient as Q, type Register as R, type SendOptions as S, TypedRelyIOClient as T, AdhocQueryBuilder as U, type FetchBlock as V, type AggregateBlock as W, type AggregateMetric as X, type SearchBlock as Y, type SimilarBlock as Z, type FilterValue as _, type TypedClientConfig as a, type AdhocQueryDefinition as a0, type AdhocQueryOptions as a1, type QueryMetadata as a2, type AdhocQueryResult as a3, AssetClient as a4, AssetFileBuilder as a5, AssetUploadBuilder as a6, isAssetEntry as a7, type AssetVisibility as a8, type FileStatus as a9, validateFile as aA, type FileBackend as aa, type AssetFileBlock as ab, type AssetFileExtracted as ac, type AssetUrls as ad, type AssetEntryResponse as ae, type PopulatedAssetReference as af, type PresignInput as ag, type PresignResult as ah, type ConfirmInput as ai, type ConfirmResult as aj, type ResolveUrlInput as ak, type ResolveUrlResult as al, type CreateAssetOptions as am, type WaitUntilReadyOptions as an, type MultipartCreateResult as ao, type MultipartPart as ap, type MultipartTarget as aq, type UploadProgress as ar, ResourceNotFoundError as as, ResourceConflictError as at, ResourceExpiredError as au, isResourceNotFound as av, type FileErrorCode as aw, FileUploadError as ax, FileValidationError as ay, type FileValidationConstraints as az, type RegisteredSchema as b, createClient as c, type ConditionalWriteOptions as d, entityTagOf as e, type RetryableWriteOptions as f, ChangesExpiredError as g, type Change as h, type ChangesOptions as i, type ChangesExpiredReason as j, ContentClient as k, SingletonClient as l, SettingsClient as m, ContentQueryBuilder as n, ContentByIdBuilder as o, type ChildrenOptions as p, type SingletonFetchOptions as q, type SettingsFetchOptions as r, SearchClient as s, SearchBuilder as t, SimilarBuilder as u, type SearchMode as v, type SearchResultItem as w, type SearchResponse as x, type AutocompleteSuggestion as y, type AutocompleteResponse as z };