@relyio/sdk 0.7.0 → 0.8.0

package/dist/{index-DbsTUw3Q.d.cts → index-B_rIWO_l.d.cts}

@@ -1,4 +1,4 @@
-import { aJ as paths, Q as EntryMetadata, aK as components } from './define-content-type-DiVpbwNs.cjs';
+import { aJ as paths, Q as EntryMetadata, aK as components } from './define-content-type-cEGjIwT5.cjs';
 
 /**
  * Where the SDK's transport gets its truth.
@@ -197,6 +197,34 @@ interface RelyIOConfig {
      * })
      */
     fetch?: typeof globalThis.fetch;
+    /**
+     * RelyIO's live edge, which `liveChanges()` — and `<RelyIOProvider live>` from `@relyio/react`
+     * with a publishable key — follows a dataset's published changes at. An `https:` or `wss:` URL
+     * (`http:` or `ws:` for a local one); the socket and the poll each use the scheme they need.
+     *
+     * Omitted, it is derived from `baseUrl` for RelyIO's own API only: `https://api.relyio.com`
+     * (the default) follows `https://live.relyio.com`. For any other `baseUrl` there is no address to
+     * derive, so set this, or `liveChanges()` ends at once with a `LiveEdgeError` naming it and sends
+     * nothing.
+     *
+     * @example
+     * const relyio = createClient({
+     *   apiKey: 'rly_pub_…',
+     *   baseUrl: 'http://localhost:3000',
+     *   liveUrl: 'http://localhost:8787',
+     * })
+     */
+    liveUrl?: string;
+    /**
+     * The `WebSocket` class `liveChanges()` opens its socket with. Omit it and the client uses the
+     * runtime's global `WebSocket` — every browser, and Node 22 or later — looked up per connection.
+     * Where there is none, as in Node 18 and 20, it polls the edge instead, about every fifteen
+     * seconds.
+     *
+     * Supply one to use a library's socket where the runtime has none, or to add what your runtime
+     * lets a socket carry.
+     */
+    webSocket?: LiveWebSocketConstructor;
     /** Browser-specific configuration */
     browser?: BrowserConfig;
     /**
@@ -213,6 +241,19 @@ interface RelyIOConfig {
      */
     dev?: boolean;
 }
+/**
+ * The part of a `WebSocket` the live edge transport uses. A browser's `WebSocket` and Node's (22 and
+ * later) are assignable as they are; `src/__tests__/changes.types.ts` holds the platform's to it.
+ * Each event reaches its listener as `unknown` and is read field by field.
+ */
+interface LiveWebSocket {
+    /** `0` connecting, `1` open, `2` closing, `3` closed. */
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (event: unknown) => void): void;
+}
+type LiveWebSocketConstructor = new (url: string) => LiveWebSocket;
 /**
  * What `updateConfig()` takes: any option of {@link RelyIOConfig}, each laid over the value the
  * client holds rather than over its default.
@@ -378,10 +419,11 @@ type Environment = 'development' | 'staging' | 'production';
 type WithDefaults<T, NoDefault extends keyof T = never> = Required<Omit<T, NoDefault>> & Pick<T, NoDefault>;
 /**
  * The options with no default, absent from a merged configuration until the caller gives one.
- * `fetch` among them: absent means the runtime's own, and that is read per request rather than
- * captured here.
+ * `fetch` and `webSocket` among them: absent means the runtime's own, and that is read per request
+ * or per connection rather than captured here. `liveUrl` too: absent is derived from `baseUrl` when
+ * the live transport opens, where RelyIO's own API names its edge, and is otherwise no address.
  */
-type UndefaultedOption = 'apiKey' | 'dataset' | 'locale' | 'dev' | 'fetch';
+type UndefaultedOption = 'apiKey' | 'dataset' | 'locale' | 'dev' | 'fetch' | 'liveUrl' | 'webSocket';
 /** The options that are themselves bags of options, each merged field by field. */
 type OptionBag = 'browser' | 'cache' | 'realtime' | 'debug';
 /**
@@ -815,4 +857,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, ValidationError as G, type MergedRelyIOConfig as H, InvalidPayloadError as I, type PathParamsOf as J, type FieldDefinition as K, type LogLevel as L, type MatchRouteOptions 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 RelyIOConfigUpdate as a, type ApiMethod as b, type ApiSuccessBody as c, type RouteMatch as d, type WhereScalar as e, type WhereFieldCondition as f, type WhereClause as g, type WhereOperator as h, type SortOptions as i, type ContentQueryResult as j, type SingletonContent as k, type CustomQuery as l, matchRoute as m, type ContentTypeSchema as n, type FieldOptions as o, type RealtimeEventType as p, type RealtimeEvent as q, type SubscriptionOptions as r, type CacheConfig as s, type RealtimeConfig as t, type RequestConfig as u, type ApiResponse as v, type RetryConfig as w, type CacheStrategy as x, type ValidationViolation as y, BaseValidationError 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, type ValidationViolation as G, BaseValidationError as H, ValidationError as I, InvalidPayloadError as J, type MergedRelyIOConfig as K, type LiveWebSocket as L, type MatchRouteOptions as M, type PathParamsOf as N, type FieldDefinition as O, 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 RelyIOConfigUpdate as a, type LiveWebSocketConstructor as b, type ApiMethod as c, type ApiSuccessBody as d, type RouteMatch as e, type WhereScalar as f, type WhereFieldCondition as g, type WhereClause as h, type WhereOperator as i, type SortOptions as j, type ContentQueryResult as k, type SingletonContent as l, matchRoute as m, type CustomQuery as n, type ContentTypeSchema as o, type FieldOptions as p, type RealtimeEventType as q, type RealtimeEvent as r, type SubscriptionOptions as s, type CacheConfig as t, type RealtimeConfig as u, type RequestConfig as v, type ApiResponse as w, type RetryConfig as x, type CacheStrategy as y, type LogLevel as z };

package/dist/{index-BOQIHnsh.d.ts → index-Cv4tmcrw.d.ts}

@@ -1,4 +1,4 @@
-import { aJ as paths, Q as EntryMetadata, aK as components } from './define-content-type-DiVpbwNs.js';
+import { aJ as paths, Q as EntryMetadata, aK as components } from './define-content-type-cEGjIwT5.js';
 
 /**
  * Where the SDK's transport gets its truth.
@@ -197,6 +197,34 @@ interface RelyIOConfig {
      * })
      */
     fetch?: typeof globalThis.fetch;
+    /**
+     * RelyIO's live edge, which `liveChanges()` — and `<RelyIOProvider live>` from `@relyio/react`
+     * with a publishable key — follows a dataset's published changes at. An `https:` or `wss:` URL
+     * (`http:` or `ws:` for a local one); the socket and the poll each use the scheme they need.
+     *
+     * Omitted, it is derived from `baseUrl` for RelyIO's own API only: `https://api.relyio.com`
+     * (the default) follows `https://live.relyio.com`. For any other `baseUrl` there is no address to
+     * derive, so set this, or `liveChanges()` ends at once with a `LiveEdgeError` naming it and sends
+     * nothing.
+     *
+     * @example
+     * const relyio = createClient({
+     *   apiKey: 'rly_pub_…',
+     *   baseUrl: 'http://localhost:3000',
+     *   liveUrl: 'http://localhost:8787',
+     * })
+     */
+    liveUrl?: string;
+    /**
+     * The `WebSocket` class `liveChanges()` opens its socket with. Omit it and the client uses the
+     * runtime's global `WebSocket` — every browser, and Node 22 or later — looked up per connection.
+     * Where there is none, as in Node 18 and 20, it polls the edge instead, about every fifteen
+     * seconds.
+     *
+     * Supply one to use a library's socket where the runtime has none, or to add what your runtime
+     * lets a socket carry.
+     */
+    webSocket?: LiveWebSocketConstructor;
     /** Browser-specific configuration */
     browser?: BrowserConfig;
     /**
@@ -213,6 +241,19 @@ interface RelyIOConfig {
      */
     dev?: boolean;
 }
+/**
+ * The part of a `WebSocket` the live edge transport uses. A browser's `WebSocket` and Node's (22 and
+ * later) are assignable as they are; `src/__tests__/changes.types.ts` holds the platform's to it.
+ * Each event reaches its listener as `unknown` and is read field by field.
+ */
+interface LiveWebSocket {
+    /** `0` connecting, `1` open, `2` closing, `3` closed. */
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (event: unknown) => void): void;
+}
+type LiveWebSocketConstructor = new (url: string) => LiveWebSocket;
 /**
  * What `updateConfig()` takes: any option of {@link RelyIOConfig}, each laid over the value the
  * client holds rather than over its default.
@@ -378,10 +419,11 @@ type Environment = 'development' | 'staging' | 'production';
 type WithDefaults<T, NoDefault extends keyof T = never> = Required<Omit<T, NoDefault>> & Pick<T, NoDefault>;
 /**
  * The options with no default, absent from a merged configuration until the caller gives one.
- * `fetch` among them: absent means the runtime's own, and that is read per request rather than
- * captured here.
+ * `fetch` and `webSocket` among them: absent means the runtime's own, and that is read per request
+ * or per connection rather than captured here. `liveUrl` too: absent is derived from `baseUrl` when
+ * the live transport opens, where RelyIO's own API names its edge, and is otherwise no address.
  */
-type UndefaultedOption = 'apiKey' | 'dataset' | 'locale' | 'dev' | 'fetch';
+type UndefaultedOption = 'apiKey' | 'dataset' | 'locale' | 'dev' | 'fetch' | 'liveUrl' | 'webSocket';
 /** The options that are themselves bags of options, each merged field by field. */
 type OptionBag = 'browser' | 'cache' | 'realtime' | 'debug';
 /**
@@ -815,4 +857,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, ValidationError as G, type MergedRelyIOConfig as H, InvalidPayloadError as I, type PathParamsOf as J, type FieldDefinition as K, type LogLevel as L, type MatchRouteOptions 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 RelyIOConfigUpdate as a, type ApiMethod as b, type ApiSuccessBody as c, type RouteMatch as d, type WhereScalar as e, type WhereFieldCondition as f, type WhereClause as g, type WhereOperator as h, type SortOptions as i, type ContentQueryResult as j, type SingletonContent as k, type CustomQuery as l, matchRoute as m, type ContentTypeSchema as n, type FieldOptions as o, type RealtimeEventType as p, type RealtimeEvent as q, type SubscriptionOptions as r, type CacheConfig as s, type RealtimeConfig as t, type RequestConfig as u, type ApiResponse as v, type RetryConfig as w, type CacheStrategy as x, type ValidationViolation as y, BaseValidationError 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, type ValidationViolation as G, BaseValidationError as H, ValidationError as I, InvalidPayloadError as J, type MergedRelyIOConfig as K, type LiveWebSocket as L, type MatchRouteOptions as M, type PathParamsOf as N, type FieldDefinition as O, 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 RelyIOConfigUpdate as a, type LiveWebSocketConstructor as b, type ApiMethod as c, type ApiSuccessBody as d, type RouteMatch as e, type WhereScalar as f, type WhereFieldCondition as g, type WhereClause as h, type WhereOperator as i, type SortOptions as j, type ContentQueryResult as k, type SingletonContent as l, matchRoute as m, type CustomQuery as n, type ContentTypeSchema as o, type FieldOptions as p, type RealtimeEventType as q, type RealtimeEvent as r, type SubscriptionOptions as s, type CacheConfig as t, type RealtimeConfig as u, type RequestConfig as v, type ApiResponse as w, type RetryConfig as x, type CacheStrategy as y, type LogLevel as z };

package/dist/{index-M0X45k7J.d.cts → index-DBoPPlT1.d.cts}

@@ -1,6 +1,7 @@
-import { H as MergedRelyIOConfig, A as ApiPath, b as ApiMethod, J as PathParamsOf, v as ApiResponse, W as Wire, u as RequestConfig, B as BaseContent, g as WhereClause, Q as QueryOptions, i as SortOptions, j as ContentQueryResult, C as CreateInput, U as UpdateInput, S as SDKError, z as BaseValidationError, y as ValidationViolation, R as RelyIOConfig, a as RelyIOConfigUpdate } from './index-DbsTUw3Q.cjs';
-import { aK as components, aJ as paths, W as InferContentType, aa as InferAssetType, a3 as InferSingleton } from './define-content-type-DiVpbwNs.cjs';
-import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, ay as FilterOperator, h as SchemaAssetTypeNames, c as SchemaSingletonNames, g as SchemaSettingsGroupNames, I as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-D7MButVt.cjs';
+import { K as MergedRelyIOConfig, A as ApiPath, c as ApiMethod, N as PathParamsOf, w as ApiResponse, W as Wire, v as RequestConfig, B as BaseContent, h as WhereClause, Q as QueryOptions, j as SortOptions, k as ContentQueryResult, C as CreateInput, U as UpdateInput, S as SDKError, H as BaseValidationError, G as ValidationViolation, R as RelyIOConfig, a as RelyIOConfigUpdate } from './index-B_rIWO_l.cjs';
+import { aK as components, aJ as paths, W as InferContentType, aa as InferAssetType, a3 as InferSingleton } from './define-content-type-cEGjIwT5.cjs';
+import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, ay as FilterOperator, h as SchemaAssetTypeNames, c as SchemaSingletonNames, g as SchemaSettingsGroupNames, I as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-DgbJ5Kwn.cjs';
+import { VisitorResyncReason } from './live-visitor.js';
 import { DevUnreadableReason } from './dev-handshake/index.cjs';
 
 /**
@@ -301,11 +302,20 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent, F extends
     private requestHeaders?;
     /** The client's locale, asked when the query is sent rather than copied when it was built. */
     private readonly clientLocale;
+    private freshValue?;
     /**
      * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when the
      *   query names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
      */
     constructor(httpClient: HttpClient, contentType: string, locale?: ClientLocale);
+    /**
+     * The feed position this read follows — a change's `fresh` (`FeedChange`), or a resync's. Sent as
+     * `?_fresh`, the one term the API declares for it: no cache — the Content API's edge or the
+     * browser's own — holds an answer for that position from before it, so the read is answered after
+     * the change, and every read naming the same position shares that answer. The answer is the
+     * read's own; omit it for a read no change prompted.
+     */
+    fresh(position: string): this;
     /**
      * Headers this query adds to the client's own, e.g. `X-RelyIO-Dataset` to list another dataset
      * the key can see. A name the client already sends is replaced for this query only; the client
@@ -516,11 +526,20 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
     private requestHeaders?;
     /** The client's locale, asked when the read is sent rather than copied when it was built. */
     private readonly clientLocale;
+    private freshValue?;
     /**
      * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when the
      *   read names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
      */
     constructor(httpClient: HttpClient, contentType: string, id: string, locale?: ClientLocale);
+    /**
+     * The feed position this read follows — a change's `fresh` (`FeedChange`), or a resync's. Sent as
+     * `?_fresh`, the one term the API declares for it: no cache — the Content API's edge or the
+     * browser's own — holds an answer for that position from before it, so the read is answered after
+     * the change, and every read naming the same position shares that answer. The answer is the
+     * read's own; omit it for a read no change prompted.
+     */
+    fresh(position: string): this;
     /**
      * Include related content in the response
      */
@@ -1352,6 +1371,12 @@ interface SingletonFetchOptions {
     locale?: string;
     /** Reference fields to populate */
     include?: string[];
+    /**
+     * The feed position this read follows — a change's `fresh` (`FeedChange`), or a resync's. Sent as
+     * `?_fresh`: no cache holds an answer for it from before that position, so the read is answered
+     * after the change. The answer is the read's own; omit it for a read no change prompted.
+     */
+    fresh?: string;
 }
 /**
  * Singleton client for managing singleton content operations
@@ -1738,6 +1763,7 @@ declare class SearchBuilder<T extends BaseContent = BaseContent, S extends AnySc
     private query;
     private searchOptions;
     private requestHeaders?;
+    private freshValue?;
     /** The client's locale, asked when the query is sent rather than copied when it was built. */
     private readonly clientLocale;
     /**
@@ -1750,6 +1776,12 @@ declare class SearchBuilder<T extends BaseContent = BaseContent, S extends AnySc
      * dataset the key can see. A name the client already sends is replaced for this search only.
      */
     headers(headers: Record<string, string>): this;
+    /**
+     * The feed position this search follows — a change's `fresh` (`FeedChange`), or a resync's. Sent
+     * as `?_fresh` on the query string beside the body: the edge keys a search on both, so no answer
+     * it holds from before that position can answer it. The answer is the search's own.
+     */
+    fresh(position: string): this;
     /**
      * Search within a single content type. Where a schema types the client, the name is one of its
      * content types and the results are that type's entries.
@@ -2833,8 +2865,34 @@ type ChangesPageBody = PollChanges['responses'][200]['content']['application/jso
  * 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';
+/**
+ * A change as `relyio.changes()` and `relyio.liveChanges()` deliver it: the document's
+ * {@link Change}, and `fresh`.
+ *
+ * `fresh` is the feed position a refetch for this change names, as the one query term the API
+ * declares on every read its edge may keep (`?_fresh`, `sdk-surfaces-spec.md` decision 32): hand it
+ * to the read — `.fresh(change.fresh)` on `findById()`, `query()` and `search()`, `{ fresh }` to a
+ * singleton's `fetch()`. A position no request named before the change is a key no cache holds a
+ * body under, so the read is answered after the change — at the edge and in the browser, whether
+ * or not the change's purge has reached them — and every later read naming it shares that answer.
+ *
+ * It is at or after the change, never before: on `/v1/changes` the change's own cursor, the ledger
+ * row it came from; at the live edge the cursor of the batch it arrived in. It is not always
+ * `cursor`: at the edge an earlier change of a batch carries the position **before** the batch as
+ * its `cursor`, so a failure part-way through replays the batch, and a refetch naming that position
+ * would be answered from before the change.
+ */
+type FeedChange = Change & {
+    /** The feed position a refetch for this change names (`?_fresh`); at or after the change. */
+    readonly fresh: string;
+};
+/**
+ * Why a cursor could no longer be replayed, or why everything must be refetched. `/v1/changes`
+ * names `retention` and `dataset-replaced`; the live edge's `feed.resync` may name any reason its
+ * wire declares (`VisitorResyncReason` in `@relyio/api-contract`, read from there rather than
+ * restated). `unknown` when the message named none.
+ */
+type ChangesExpiredReason = VisitorResyncReason | '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
@@ -2843,12 +2901,28 @@ type ChangesExpiredReason = 'retention' | 'dataset-replaced' | 'unknown';
  * 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`).
+ *
+ * The live edge's `feed.resync` — a socket's frame or a poll's answer — is the
+ * same instruction and arrives as the same error ({@link ChangesExpiredError.resync}),
+ * so `onExpired` means one thing on both transports.
  */
 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;
+    /**
+     * The position the feed resynced to, which a refetch of everything names as `?_fresh`, as a
+     * change's {@link FeedChange.fresh} is named: the head a `/v1/changes` resync took, or the cursor
+     * the edge's `feed.resync` sent. `undefined` when there was no resync to take one — the error was
+     * thrown (`onExpired: 'throw'`) — and on an error a caller built itself.
+     */
+    readonly fresh: string | undefined;
+    /** The base class's signature, so `withContext` can rebuild one; then the position resynced to. */
+    constructor(message: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>, fresh?: string);
+    /** The base class rebuilds from its four arguments, which would drop the position resynced to. */
+    withContext(context: Record<string, unknown>): this;
+    /** `/v1/changes`' refusal, with the head the feed resynced to when it did. */
+    static of(expired: ResourceExpiredError, fresh?: string): ChangesExpiredError;
+    /** The live edge's `feed.resync`: refetch everything, then continue from the cursor it sent. */
+    static resync(reason: VisitorResyncReason, cursor: string): ChangesExpiredError;
 }
 interface ChangesOptions {
     /**
@@ -2882,7 +2956,8 @@ interface ChangesOptions {
      * - 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.
+     *   function is where it invalidates everything — naming the error's `fresh`,
+     *   the new position, on every refetch. The iterator waits for it.
      */
     onExpired?: 'throw' | 'resync' | ((expired: ChangesExpiredError) => void | Promise<void>);
 }
@@ -2891,6 +2966,81 @@ interface ChangesHeadOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * `relyio.liveChanges()` — a dataset's published changes at RelyIO's live edge, for a publishable key
+ * (`live-layer-spec.md` decision 20; LV5.2, REL-1158).
+ *
+ * The wire is `@relyio/api-contract`'s `live-visitor.ts`, read from there and never restated: the
+ * path and query names, the frames and their reader, the keepalive, the poll's answer and its reader,
+ * the poll interval, and what each close code and each refused poll means a client does next.
+ *
+ * **One open, two ways in.** A subscription opens a WebSocket to the edge. Where it cannot — the
+ * runtime has no `WebSocket` (Node 18 and 20), constructing one throws, or the socket fails before it
+ * opens (a network that blocks sockets) — it polls the edge instead, from the same cursor, about
+ * every {@link VISITOR_POLL_INTERVAL_MS}, and tries a socket again about once a minute. Both carry
+ * one cursor space, so a switch either way loses nothing.
+ *
+ * **It ends only when its signal aborts, and throws every other end** — a socket closed by a refusal
+ * or a deploy, a refused poll, a keepalive nobody answered — as a `LiveEdgeError` saying what to do
+ * next, so `followChanges()` reconnects, backs off or stops by the edge's own tables. That loop is
+ * the one reconnect policy (`INV-SS-ONE-CORE`, REL-1215); this module keeps no back-off of its own.
+ *
+ * **Cursors.** The edge sends one cursor after a batch of changes. The last change of a batch carries
+ * it; each earlier one carries the position before the batch, so a failure part-way through a batch
+ * replays the whole batch rather than skipping its rest. Delivery is at-least-once: a replay and the
+ * live frames after it may name one change twice, and a refetch makes a repeat cost a read, never a
+ * wrong view (`INV-SS-CHANGE-IS-IDS`).
+ *
+ * **What a refetch names.** Every change of a batch carries the batch's own cursor as `fresh`
+ * (`FeedChange`), the position its refetch names as `?_fresh` — not `cursor`, which for an earlier
+ * change is the position before the batch: the previous batch's refetches were answered under that
+ * one, before this batch, and a cache would hand the same answer back. A `feed.resync`'s error
+ * carries the cursor it sent the same way.
+ */
+
+/**
+ * How often an open socket sends the keepalive, which the edge's runtime answers without waking the
+ * feed — the Studio's dataset room sends its own on the same interval. A socket that has heard
+ * nothing by the next one, not even the answer, is presumed dead and reconnected: a client that only
+ * receives never learns otherwise that a network change dropped its connection.
+ */
+declare const LIVE_KEEPALIVE_INTERVAL_MS = 30000;
+interface LiveChangesOptions {
+    /**
+     * A change's cursor from an earlier subscription. Omitted, the edge answers the dataset's current
+     * position first and replays nothing; fetch what you show **after** that position arrives — with
+     * `followChanges()`, after `onState` reports `following` — so nothing lands in between unseen.
+     */
+    since?: string;
+    /** Content types to keep. Omitted keeps every type; an empty list is refused. At most 50. */
+    types?: readonly string[];
+    /** Entry ids to keep. Omitted keeps every entry; an empty list is refused. At most 100. */
+    ids?: readonly string[];
+    /**
+     * Ends the subscription. An abort — while connected, while polling, or between polls — makes the
+     * `for await` **complete**, with the socket closed, no further request and nothing thrown.
+     */
+    signal?: AbortSignal;
+    /**
+     * What to do when the edge says to refetch everything (`feed.resync`: the cursor is too old, was
+     * never this dataset's, or the dataset was replaced) — as `relyio.changes()` takes it: `'throw'`
+     * (default) throws a `ChangesExpiredError`, `'resync'` carries on from the edge's position, and a
+     * function is awaited with the error before any change after that position is yielded.
+     */
+    onExpired?: ChangesOptions['onExpired'];
+    /**
+     * Called when the edge has the subscription in hand — its `feed.opened` frame, or an answered
+     * poll. `followChanges()` passes it to reset its back-off; see `ChangeSourceOptions.opened`.
+     */
+    opened?: () => void;
+    /**
+     * Called with a position reached without a change to carry it. `followChanges()` passes it so a
+     * connection dropped before its first change reconnects from there; see
+     * `ChangeSourceOptions.reached`.
+     */
+    reached?: (cursor: string) => void;
+}
+
 /**
  * The key's project, as `GET /v1/project` describes it: organization, project, dataset and branch,
  * each by id and name, and `studioUrl` — the Studio root the preview toolbar deep-links from
@@ -2952,6 +3102,8 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * locale, or none after `locale: null` (REL-1453).
      */
     private readonly currentLocale;
+    /** The live edge's poll client id: chosen once, when first needed, and kept for this client's life. */
+    private _liveClientId;
     constructor(config: TypedClientConfig<TSchema>);
     /**
      * Get the schema definition
@@ -3114,13 +3266,15 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * 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`).
+     * (`INV-SS-CHANGE-IS-IDS`), naming its `fresh` so no cache answers with the
+     * body from before it (`FeedChange`).
      *
      * @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 }
+     *   // { entryId, contentType, locale, kind, cursor, fresh }
+     *   await relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute()
      * }
      * ```
      *
@@ -3128,11 +3282,42 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```typescript
      * for await (const change of relyio.changes({
      *   since: cursor,
-     *   onExpired: async () => invalidateEverything(),
+     *   onExpired: async expired => refetchEverything(expired.fresh),
      * })) { … }
      * ```
      */
-    changes(options?: ChangesOptions): AsyncIterable<Change>;
+    changes(options?: ChangesOptions): AsyncIterable<FeedChange>;
+    /**
+     * Follow the dataset's **published** changes at RelyIO's live edge, with a publishable key
+     * (`rly_pub_…`): each change as ids, in order — the transport a browser follows changes with.
+     *
+     * A WebSocket to the edge, from `since` or the dataset's current position; where a socket cannot
+     * open — the runtime has none, or the network refuses it — it polls the edge instead, about every
+     * fifteen seconds, from the same cursor. The edge is `liveUrl`, or derived from the default
+     * `baseUrl` (see `RelyIOConfig.liveUrl`).
+     *
+     * One subscription ends only when `signal` aborts, which ends the `for await` cleanly; every other
+     * end — a socket a deploy dropped, a refusal, a refused poll — is thrown as a `LiveEdgeError`
+     * that says whether to stop, retry or back off. Hand it to `followChanges()`, the one loop that
+     * reconnects from the last cursor with jittered back-off and honours those answers:
+     *
+     * @example
+     * ```typescript
+     * const relyio = createClient({ apiKey: 'rly_pub_…' })
+     * const controller = new AbortController()
+     * await followChanges(from => relyio.liveChanges({ ...from, types: ['post'] }), {
+     *   signal: controller.signal,
+     *   // `fresh` names a position no cache holds a body for from before the change.
+     *   onChange: change =>
+     *     relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute(),
+     *   onResync: resync => refetchEverything(resync.cause === 'expired' ? resync.expired.fresh : undefined),
+     * })
+     * ```
+     *
+     * A client without a publishable key sends nothing: a secret or preview key is never put in the
+     * edge's URL. On a server, follow `changes()` with it instead.
+     */
+    liveChanges(options?: LiveChangesOptions): AsyncIterable<FeedChange>;
     /**
      * The dataset's current position in the changes feed, as a cursor to start
      * `changes({ since })` or `followChanges(…, { since })` from. One
@@ -3414,4 +3599,4 @@ declare function createClient<TSchema extends AnySchemaDefinition>(config: Typed
  */
 type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
 
-export { AdhocQueryClient as $, type ActiveSandbox as A, type SearchHitMetadata as B, ChangesExpiredError as C, type SearchResponse as D, type ExtendedQueryResult as E, type AutocompleteSuggestion as F, type AutocompleteResponse as G, HttpClient as H, type SimilarResult as I, type SimilarResponse as J, type SearchFilter as K, type SearchFields as L, type SearchSort as M, type SearchTypeName as N, type SearchEntry as O, type Project as P, BatchClient as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, BatchBuilder as U, type BatchMethod as V, type BatchOperation as W, type BatchOptions as X, type BatchOperationResult as Y, type BatchSummary as Z, type BatchResponse as _, type Change as a, AdhocQueryBuilder as a0, type FetchBlock as a1, type AggregateBlock as a2, type AggregateMetric as a3, type SearchBlock as a4, type FilterValue as a5, type FullTextConfig as a6, type AdhocQueryDefinition as a7, type AdhocQueryOptions as a8, type QueryMetadata as a9, ResourceNotFoundError as aA, ResourceConflictError as aB, ResourceExpiredError as aC, isResourceNotFound as aD, type FileErrorCode as aE, type FileUploadErrorCode as aF, FileUploadError as aG, FileValidationError as aH, type FileValidationConstraints as aI, validateFile as aJ, type AdhocQueryResult as aa, AssetClient as ab, AssetFileBuilder as ac, AssetUploadBuilder as ad, isAssetEntry as ae, type AssetVisibility as af, type FileStatus as ag, type FileBackend as ah, type AssetFileBlock as ai, type AssetFileExtracted as aj, type FileStatusResult as ak, type AssetUrls as al, type AssetEntryResponse as am, type PopulatedAssetReference as an, type PresignInput as ao, type PresignResult as ap, type ConfirmInput as aq, type ConfirmResult as ar, type ResolveUrlInput as as, type ResolveUrlResult as at, type CreateAssetOptions as au, type WaitUntilReadyOptions as av, type MultipartCreateResult as aw, type MultipartPart as ax, type MultipartTarget as ay, type UploadProgress as az, type ChangesExpiredReason as b, createClient as c, type TypedClientConfig as d, type ClientSchema as e, type RegisteredSchema as f, type SendOptions as g, entityTagOf as h, type ConditionalWriteOptions as i, type RetryableWriteOptions as j, type ChangesHeadOptions as k, type ChangesOptions as l, ContentClient as m, SingletonClient as n, SettingsClient as o, ContentQueryBuilder as p, ContentByIdBuilder as q, type ChildrenOptions as r, type SingletonFetchOptions as s, type SettingsFetchOptions as t, SearchClient as u, SearchBuilder as v, AutocompleteBuilder as w, SimilarBuilder as x, type SearchMode as y, type SearchResultItem as z };
+export { type BatchOperationResult as $, type ActiveSandbox as A, type SearchResultItem as B, type Change as C, type SearchHitMetadata as D, type ExtendedQueryResult as E, type FeedChange as F, type SearchResponse as G, HttpClient as H, type AutocompleteSuggestion as I, type AutocompleteResponse as J, type SimilarResult as K, LIVE_KEEPALIVE_INTERVAL_MS as L, type SimilarResponse as M, type SearchFilter as N, type SearchFields as O, type Project as P, type SearchSort as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type SearchTypeName as U, type SearchEntry as V, BatchClient as W, BatchBuilder as X, type BatchMethod as Y, type BatchOperation as Z, type BatchOptions as _, ChangesExpiredError as a, type BatchSummary as a0, type BatchResponse as a1, AdhocQueryClient as a2, AdhocQueryBuilder as a3, type FetchBlock as a4, type AggregateBlock as a5, type AggregateMetric as a6, type SearchBlock as a7, type FilterValue as a8, type FullTextConfig as a9, type MultipartPart as aA, type MultipartTarget as aB, type UploadProgress as aC, ResourceNotFoundError as aD, ResourceConflictError as aE, ResourceExpiredError as aF, isResourceNotFound as aG, type FileErrorCode as aH, type FileUploadErrorCode as aI, FileUploadError as aJ, FileValidationError as aK, type FileValidationConstraints as aL, validateFile as aM, type AdhocQueryDefinition as aa, type AdhocQueryOptions as ab, type QueryMetadata as ac, type AdhocQueryResult as ad, AssetClient as ae, AssetFileBuilder as af, AssetUploadBuilder as ag, isAssetEntry as ah, type AssetVisibility as ai, type FileStatus as aj, type FileBackend as ak, type AssetFileBlock as al, type AssetFileExtracted as am, type FileStatusResult as an, type AssetUrls as ao, type AssetEntryResponse as ap, type PopulatedAssetReference as aq, type PresignInput as ar, type PresignResult as as, type ConfirmInput as at, type ConfirmResult as au, type ResolveUrlInput as av, type ResolveUrlResult as aw, type CreateAssetOptions as ax, type WaitUntilReadyOptions as ay, type MultipartCreateResult as az, type ChangesExpiredReason as b, createClient as c, type TypedClientConfig as d, type ClientSchema as e, type RegisteredSchema as f, type SendOptions as g, entityTagOf as h, type ConditionalWriteOptions as i, type RetryableWriteOptions as j, type ChangesHeadOptions as k, type ChangesOptions as l, type LiveChangesOptions as m, ContentClient as n, SingletonClient as o, SettingsClient as p, ContentQueryBuilder as q, ContentByIdBuilder as r, type ChildrenOptions as s, type SingletonFetchOptions as t, type SettingsFetchOptions as u, SearchClient as v, SearchBuilder as w, AutocompleteBuilder as x, SimilarBuilder as y, type SearchMode as z };