@relyio/sdk 0.7.0 → 0.9.0

package/dist/{index-M0X45k7J.d.cts → index-B9axQW8s.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,15 +2956,152 @@ 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>);
+    /**
+     * Called once, when the feed was opened without `since`, with the position it starts from: the
+     * first poll's answer, the dataset's head — before the next poll is sent. Read what you show
+     * **after** it and a write your read did not see is after the position, so this feed delivers it,
+     * with no second request to take the position first (`changesHead()` is that request) (REL-1513).
+     *
+     * `followChanges()` passes it (`ChangeSourceOptions.reached`), so a feed that drops before its first
+     * change reopens from there rather than re-reading everything. Never called with a later empty
+     * page's cursor: filtered, that cursor is past rows the filter hid, and a caller that widens the
+     * filter must not reopen from it.
+     */
+    reached?: (cursor: string) => void;
 }
 interface ChangesHeadOptions {
     /** Cancels the request; the promise then rejects. */
     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, the socket fails before it
+ * opens (a network that blocks sockets), or it has not opened and been caught up within
+ * {@link LIVE_SOCKET_OPEN_TIMEOUT_MS} (a network that holds it) — 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.
+ *
+ * **Where it starts.** Without `since`, the edge answers the dataset's current position before
+ * anything else — the socket's `feed.opened`, or the first poll's answer — and the subscription hands
+ * it to `reached`. That call is the position, with no request of its own for it: a read sent after it
+ * is answered at or after the position, and every change after it is delivered here, so a publish the
+ * read did not see is announced (REL-1513). The edge counts the subscription as one live connection,
+ * whichever way in it took (`INV-LV-LIVE-IS-METERED`).
+ *
+ * **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;
+/**
+ * How long a socket has to open and be caught up — the feed's `feed.opened` — before the subscription
+ * stops waiting on it, closes it and polls instead, as it does for a socket that fails before it opens
+ * (REL-1513).
+ *
+ * The poll interval, because that is what a socket is for: telling the page sooner than a poll would.
+ * A poll is answered at once and polled again within this interval, so a socket that has not caught
+ * up by then has already served the page worse than polling would have. It is well past a healthy
+ * open — the door's checks and one ledger read at the edge — and half the keepalive's verdict on an
+ * open socket that has gone quiet ({@link LIVE_KEEPALIVE_INTERVAL_MS}, twice). It bounds how long
+ * `<RelyIOProvider live>`'s first reads wait for a position on a network that neither opens a socket
+ * nor refuses one — a proxy that holds the upgrade — which without it they would wait on for as long
+ * as the page is open.
+ */
+declare const LIVE_SOCKET_OPEN_TIMEOUT_MS = 15000;
+interface LiveChangesOptions {
+    /**
+     * A change's cursor from an earlier subscription. Omitted, the edge answers the dataset's current
+     * position first and replays nothing, and the subscription hands that position to `reached` before
+     * anything after it. Read what you show **after** that first call — a read sent before it, from a
+     * subscription opened afterwards without `since`, leaves a publish between the two that neither
+     * sees (REL-1513). With `followChanges()`, which hands the source its own `reached`, call both —
+     * and let the read go if the loop fails first, so content never waits on a feed that is down:
+     *
+     * ```ts
+     * let positioned!: () => void
+     * const position = new Promise<void>(resolve => (positioned = resolve))
+     * const following = followChanges(
+     *   from =>
+     *     relyio.liveChanges({
+     *       ...from,
+     *       ids: [id],
+     *       reached: cursor => {
+     *         from.reached(cursor)
+     *         positioned()
+     *       },
+     *     }),
+     *   { signal, onChange, onResync, onState: state => state.kind !== 'following' && positioned() },
+     * )
+     * await position
+     * const post = await relyio.content('post').findById(id).execute()
+     * ```
+     *
+     * The wait is bounded: a socket that has not opened and been told its position within
+     * {@link LIVE_SOCKET_OPEN_TIMEOUT_MS} is given up for a poll, answered at once.
+     */
+    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`. Without `since`, its first call is the position the subscription
+     * starts from (see `since`).
+     */
+    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 +3163,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 +3327,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 +3343,47 @@ 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, the network refuses it, or it has not opened and been told its
+     * position within `LIVE_SOCKET_OPEN_TIMEOUT_MS` — 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`).
+     *
+     * Without `since` it starts at the dataset's current position, which it hands `reached` before
+     * anything after it: read what you show after that call, and a publish your read did not see is
+     * one this subscription announces (see `LiveChangesOptions.since`).
+     *
+     * 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 +3665,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 BatchOptions as $, type ActiveSandbox as A, type SearchMode as B, type Change as C, type SearchResultItem as D, type ExtendedQueryResult as E, type FeedChange as F, type SearchHitMetadata as G, HttpClient as H, type SearchResponse as I, type AutocompleteSuggestion as J, type AutocompleteResponse as K, LIVE_KEEPALIVE_INTERVAL_MS as L, type SimilarResult as M, type SimilarResponse as N, type SearchFilter as O, type Project as P, type SearchFields as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type SearchSort as U, type SearchTypeName as V, type SearchEntry as W, BatchClient as X, BatchBuilder as Y, type BatchMethod as Z, type BatchOperation as _, ChangesExpiredError as a, type BatchOperationResult as a0, type BatchSummary as a1, type BatchResponse as a2, AdhocQueryClient as a3, AdhocQueryBuilder as a4, type FetchBlock as a5, type AggregateBlock as a6, type AggregateMetric as a7, type SearchBlock as a8, type FilterValue as a9, type MultipartCreateResult as aA, type MultipartPart as aB, type MultipartTarget as aC, type UploadProgress as aD, ResourceNotFoundError as aE, ResourceConflictError as aF, ResourceExpiredError as aG, isResourceNotFound as aH, type FileErrorCode as aI, type FileUploadErrorCode as aJ, FileUploadError as aK, FileValidationError as aL, type FileValidationConstraints as aM, validateFile as aN, type FullTextConfig as aa, type AdhocQueryDefinition as ab, type AdhocQueryOptions as ac, type QueryMetadata as ad, type AdhocQueryResult as ae, AssetClient as af, AssetFileBuilder as ag, AssetUploadBuilder as ah, isAssetEntry as ai, type AssetVisibility as aj, type FileStatus as ak, type FileBackend as al, type AssetFileBlock as am, type AssetFileExtracted as an, type FileStatusResult as ao, type AssetUrls as ap, type AssetEntryResponse as aq, type PopulatedAssetReference as ar, type PresignInput as as, type PresignResult as at, type ConfirmInput as au, type ConfirmResult as av, type ResolveUrlInput as aw, type ResolveUrlResult as ax, type CreateAssetOptions as ay, type WaitUntilReadyOptions 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, LIVE_SOCKET_OPEN_TIMEOUT_MS as m, type LiveChangesOptions as n, ContentClient as o, SingletonClient as p, SettingsClient as q, ContentQueryBuilder as r, ContentByIdBuilder as s, type ChildrenOptions as t, type SingletonFetchOptions as u, type SettingsFetchOptions as v, SearchClient as w, SearchBuilder as x, AutocompleteBuilder as y, SimilarBuilder as z };

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 };