@relyio/sdk 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,11 +1,13 @@
-import { C as ChangesExpiredError, a as Change, b as ChangesExpiredReason } from './index-Df1VsfJR.cjs';
-export { A as ActiveSandbox, a1 as AdhocAggregateBlock, a0 as AdhocFetchBlock, $ as AdhocQueryBuilder, _ as AdhocQueryClient, a7 as AdhocQueryDefinition, a8 as AdhocQueryOptions, aa as AdhocQueryResult, a3 as AdhocSearchBlock, a4 as AdhocSimilarBlock, a2 as AggregateMetric, ab as AssetClient, al as AssetEntryResponse, ai as AssetFileBlock, ac as AssetFileBuilder, aj as AssetFileExtracted, ad as AssetUploadBuilder, ak as AssetUrls, af as AssetVisibility, w as AutocompleteBuilder, F as AutocompleteResponse, D as AutocompleteSuggestion, Q as BatchBuilder, O as BatchClient, U as BatchMethod, V as BatchOperation, X as BatchOperationResult, W as BatchOptions, Z as BatchResponse, Y as BatchSummary, k as ChangesHeadOptions, l as ChangesOptions, r as ChildrenOptions, e as ClientSchema, i as ConditionalWriteOptions, ap as ConfirmInput, aq as ConfirmResult, q as ContentByIdBuilder, m as ContentClient, p as ContentQueryBuilder, at as CreateAssetOptions, E as ExtendedQueryResult, ah as FileBackend, aD as FileErrorCode, ag as FileStatus, aE as FileUploadError, aG as FileValidationConstraints, aF as FileValidationError, a5 as FilterValue, a6 as FullTextConfig, H as HttpClient, av as MultipartCreateResult, aw as MultipartPart, ax as MultipartTarget, am as PopulatedAssetReference, an as PresignInput, ao as PresignResult, P as Project, a9 as QueryMetadata, R as Register, f as RegisteredSchema, ar as ResolveUrlInput, as as ResolveUrlResult, aA as ResourceConflictError, aB as ResourceExpiredError, az as ResourceNotFoundError, j as RetryableWriteOptions, S as SandboxState, v as SearchBuilder, u as SearchClient, N as SearchEntry, K as SearchFields, J as SearchFilter, y as SearchMode, B as SearchResponse, z as SearchResultItem, L as SearchSort, M as SearchTypeName, g as SendOptions, o as SettingsClient, t as SettingsFetchOptions, x as SimilarBuilder, I as SimilarResponse, G as SimilarResult, n as SingletonClient, s as SingletonFetchOptions, d as TypedClientConfig, T as TypedRelyIOClient, ay as UploadProgress, au as WaitUntilReadyOptions, c as createClient, c as default, h as entityTagOf, ae as isAssetEntry, aC as isResourceNotFound, aH as validateFile } from './index-Df1VsfJR.cjs';
+import { C as Change, a as ChangesExpiredError, b as ChangesExpiredReason } from './index-DBoPPlT1.cjs';
+export { A as ActiveSandbox, a5 as AdhocAggregateBlock, a4 as AdhocFetchBlock, a3 as AdhocQueryBuilder, a2 as AdhocQueryClient, aa as AdhocQueryDefinition, ab as AdhocQueryOptions, ad as AdhocQueryResult, a7 as AdhocSearchBlock, a6 as AggregateMetric, ae as AssetClient, ap as AssetEntryResponse, al as AssetFileBlock, af as AssetFileBuilder, am as AssetFileExtracted, ag as AssetUploadBuilder, ao as AssetUrls, ai as AssetVisibility, x as AutocompleteBuilder, J as AutocompleteResponse, I as AutocompleteSuggestion, X as BatchBuilder, W as BatchClient, Y as BatchMethod, Z as BatchOperation, $ as BatchOperationResult, _ as BatchOptions, a1 as BatchResponse, a0 as BatchSummary, k as ChangesHeadOptions, l as ChangesOptions, s as ChildrenOptions, e as ClientSchema, i as ConditionalWriteOptions, at as ConfirmInput, au as ConfirmResult, r as ContentByIdBuilder, n as ContentClient, q as ContentQueryBuilder, ax as CreateAssetOptions, E as ExtendedQueryResult, F as FeedChange, ak as FileBackend, aH as FileErrorCode, aj as FileStatus, an as FileStatusResult, aJ as FileUploadError, aI as FileUploadErrorCode, aL as FileValidationConstraints, aK as FileValidationError, a8 as FilterValue, a9 as FullTextConfig, H as HttpClient, L as LIVE_KEEPALIVE_INTERVAL_MS, m as LiveChangesOptions, az as MultipartCreateResult, aA as MultipartPart, aB as MultipartTarget, aq as PopulatedAssetReference, ar as PresignInput, as as PresignResult, P as Project, ac as QueryMetadata, R as Register, f as RegisteredSchema, av as ResolveUrlInput, aw as ResolveUrlResult, aE as ResourceConflictError, aF as ResourceExpiredError, aD as ResourceNotFoundError, j as RetryableWriteOptions, S as SandboxState, w as SearchBuilder, v as SearchClient, V as SearchEntry, O as SearchFields, N as SearchFilter, D as SearchHitMetadata, z as SearchMode, G as SearchResponse, B as SearchResultItem, Q as SearchSort, U as SearchTypeName, g as SendOptions, p as SettingsClient, u as SettingsFetchOptions, y as SimilarBuilder, M as SimilarResponse, K as SimilarResult, o as SingletonClient, t as SingletonFetchOptions, d as TypedClientConfig, T as TypedRelyIOClient, aC as UploadProgress, ay as WaitUntilReadyOptions, c as createClient, c as default, h as entityTagOf, ah as isAssetEntry, aG as isResourceNotFound, aM as validateFile } from './index-DBoPPlT1.cjs';
 export { fields } from './schema/index.cjs';
-import { S as SDKError, B as BaseContent } from './index-d1Kz1e19.cjs';
-export { a as ApiMethod, A as ApiPath, v as ApiResponse, b as ApiSuccessBody, z as BaseValidationError, s as CacheConfig, x as CacheStrategy, i as ContentQueryResult, n as ContentTypeSchema, C as CreateInput, l as CustomQuery, D as DebugConfig, E as Environment, o as FieldOptions, F as FieldTypeName, K as InvalidFieldTypeError, I as InvalidPayloadError, L as LogLevel, M as MatchRouteOptions, P as PerformanceMetrics, Q as QueryOptions, t as RealtimeConfig, q as RealtimeEvent, p as RealtimeEventType, R as RelyIOConfig, u as RequestConfig, J as RequiredFieldError, w as RetryConfig, c as RouteMatch, H as SchemaValidationError, k as SettingsGroup, j as SingletonContent, h as SortOptions, r as SubscriptionOptions, U as UpdateInput, G as ValidationError, V as ValidationRule, y as ValidationViolation, f as WhereClause, e as WhereFieldCondition, g as WhereOperator, d as WhereScalar, W as Wire, m as matchRoute } from './index-d1Kz1e19.cjs';
+import { S as SDKError, B as BaseContent } from './index-B_rIWO_l.cjs';
+export { c as ApiMethod, A as ApiPath, w as ApiResponse, d as ApiSuccessBody, H as BaseValidationError, t as CacheConfig, y as CacheStrategy, k as ContentQueryResult, o as ContentTypeSchema, C as CreateInput, n as CustomQuery, D as DebugConfig, E as Environment, p as FieldOptions, F as FieldTypeName, J as InvalidPayloadError, L as LiveWebSocket, b as LiveWebSocketConstructor, z as LogLevel, M as MatchRouteOptions, P as PerformanceMetrics, Q as QueryOptions, u as RealtimeConfig, r as RealtimeEvent, q as RealtimeEventType, R as RelyIOConfig, a as RelyIOConfigUpdate, v as RequestConfig, x as RetryConfig, e as RouteMatch, l as SingletonContent, j as SortOptions, s as SubscriptionOptions, U as UpdateInput, I as ValidationError, V as ValidationRule, G as ValidationViolation, h as WhereClause, g as WhereFieldCondition, i as WhereOperator, f as WhereScalar, W as Wire, m as matchRoute } from './index-B_rIWO_l.cjs';
+import { VisitorRetry } from './live-visitor.js';
 export { camelToSnake, createDeferred, debounce, deepClone, generateId, isBrowser, isNode, isPlainObject, isValidEmail, isValidUrl, mergeDeep, omit, pick, retry, sleep, snakeToCamel, throttle, toSafeString } from './utils/index.cjs';
-export { a6 as AggregateBlock, C as ComponentConfig, s as ComponentDefinition, t as ComponentMetadata, a5 as FetchBlock, ag as FilterDefinition, ae as IncludeDefinition, aq as InferQueryParams, ap as InferQueryResponse, a3 as QueryConfig, a4 as QueryDefinition, h as SchemaAssetTypeNames, S as SchemaConfig, b as SchemaContentTypeNames, a as SchemaDefinition, i as SchemaEntry, j as SchemaEntryOf, f as SchemaLocaleCodes, e as SchemaQueryNames, g as SchemaSettingsGroupNames, c as SchemaSingletonNames, a7 as SearchBlock, af as SelectMapping, x as SettingsGroupConfig, y as SettingsGroupDefinition, a8 as SimilarBlock, ac as SortCondition, a9 as WhereCondition, r as defineComponent, a2 as defineQuery, d as defineSchema, w as defineSettingsGroup } from './define-schema-1kr2HIzN.cjs';
-export { a2 as AssetTypeConfig, a5 as AssetTypeDefinition, n as BaseFieldConfig, K as ContentTypeConfig, M as ContentTypeConfigWithFields, N as ContentTypeConfigWithFieldsets, O as ContentTypeDefinition, P as EntryMetadata, c as FieldDefinition, b as FieldRule, u as FieldSchemaContext, o as FieldType, F as FieldUIConfig, v as FieldValue, w as FieldValues, J as Fieldset, a9 as FileKindConfig, an as FileScanConfig, am as FileUploadConfig, af as ImageExifConfig, a7 as ImageKindConfig, ae as ImageSourceConfig, ad as ImageUploadConfig, a6 as InferAssetType, Q as InferContentType, a0 as InferSingleton, $ as InferSingletonContentType, W as LocalePublicationFields, L as LocalizationConfig, Z as SingletonContentTypeDefinition, _ as SingletonMetadata, z as UnresolvedComponent, y as UnresolvedEntry, ag as VariantDefinition, aj as VideoCaptionsConfig, ak as VideoDownloadConfig, a8 as VideoKindConfig, ai as VideoPosterConfig, ah as VideoUploadConfig, al as VideoWatermarkConfig, a1 as defineAssetType, G as defineContentType, Y as defineSingleton, X as defineSingletonContentType, H as fieldset } from './define-content-type-CDB3kyeA.cjs';
+import { Q as EntryMetadata } from './define-content-type-cEGjIwT5.cjs';
+export { a5 as AssetTypeConfig, a9 as AssetTypeDefinition, n as BaseFieldConfig, M as ContentTypeConfig, N as ContentTypeConfigWithFields, O as ContentTypeConfigWithFieldsets, P as ContentTypeDefinition, c as FieldDefinition, b as FieldRule, v as FieldSchemaContext, p as FieldType, F as FieldUIConfig, w as FieldValue, x as FieldValues, K as Fieldset, ad as FileKindConfig, ar as FileScanConfig, aq as FileUploadConfig, aj as ImageExifConfig, ab as ImageKindConfig, ai as ImageSourceConfig, ah as ImageUploadConfig, aa as InferAssetType, W as InferContentType, a3 as InferSingleton, a2 as InferSingletonContentType, X as LocalePublicationFields, L as LocalizationConfig, a0 as SingletonContentTypeDefinition, a1 as SingletonMetadata, G as UnresolvedComponent, z as UnresolvedEntry, ak as VariantDefinition, an as VideoCaptionsConfig, ao as VideoDownloadConfig, ac as VideoKindConfig, am as VideoPosterConfig, al as VideoUploadConfig, ap as VideoWatermarkConfig, a4 as defineAssetType, H as defineContentType, Z as defineSingleton, Y as defineSingletonContentType, J as fieldset } from './define-content-type-cEGjIwT5.cjs';
+export { aa as AggregateBlock, C as ComponentConfig, s as ComponentDefinition, t as ComponentMetadata, a9 as FetchBlock, an as FilterDefinition, aj as IncludeDefinition, ax as InferQueryParams, aw as InferQueryResponse, a5 as QueryConfig, a6 as QueryDefinition, h as SchemaAssetTypeNames, S as SchemaConfig, b as SchemaContentTypeNames, a as SchemaDefinition, i as SchemaEntry, j as SchemaEntryOf, f as SchemaLocaleCodes, e as SchemaQueryNames, g as SchemaSettingsGroupNames, c as SchemaSingletonNames, ab as SearchBlock, am as SelectMapping, x as SettingsGroupConfig, y as SettingsGroupDefinition, ah as SortCondition, ac as WhereCondition, r as defineComponent, a4 as defineQuery, d as defineSchema, w as defineSettingsGroup } from './define-schema-DgbJ5Kwn.cjs';
 import './dev-handshake/index.cjs';
 
 /**
@@ -43,25 +45,35 @@ declare const isPublishableKey: (apiKey: string | undefined) => boolean;
  * state mean to it.
  *
  * **The transport is a parameter.** A source opens from a cursor and yields
- * changes. Today that is `relyio.changes()`, the long-poll, with whatever filter
- * the caller binds in. LV5.2 (REL-1158, `live-layer-spec.md` LV5) adds a
- * second — a WebSocket to the live edge, falling back to polling the edge when a
- * socket cannot open — and hands it to this loop, with a classifier for its
- * refusal close codes. That source calls `opened()` on the socket's `open`: a
- * Worker deploy drops every socket, and a quiet dataset delivers no change, so
- * without it each deploy would double the next reconnect's wait up to thirty
- * seconds. With it, every drop after a healthy connection waits the base
- * ceiling. The loop, and every handler a surface passes it, stay as they are.
- *
- * The long-poll does not call `opened()`: `relyio.changes()` takes the public
- * `ChangesOptions`, which does not carry it, so its back-off resets only on a
- * delivered change — as it did before this loop existed.
+ * changes. There are two: `relyio.changes()`, the long-poll over `/v1/changes`,
+ * and `relyio.liveChanges()` (LV5.2, REL-1158), a WebSocket to the live edge that
+ * polls the edge when a socket cannot open — each with whatever filter the caller
+ * binds in. The edge's refusals are `LiveEdgeError`s, which the default
+ * classifier reads, so neither needs a classifier of its own.
+ *
+ * The edge source calls `opened()` on the feed's `feed.opened` frame — not the
+ * socket's `open` event, which a refusal fires too, because the edge accepts a
+ * socket to close it with a code — and on each answered poll. A Worker deploy
+ * drops every socket, and a quiet dataset delivers no change, so without it each
+ * deploy would double the next reconnect's wait up to thirty seconds. It calls
+ * `reached()` with the cursor `feed.opened` names, so a socket dropped before its
+ * first change reconnects from that cursor instead of re-reading everything.
+ *
+ * The long-poll calls neither: `relyio.changes()` takes the public
+ * `ChangesOptions`, which carries neither, so its back-off resets only on a
+ * delivered change and a failure before its first change resyncs — as before
+ * this loop existed.
  */
 
 /** The ceiling of the first wait after a failure worth retrying; doubled per consecutive failure. */
 declare const FOLLOW_RETRY_BASE_MS = 1000;
 /** The ceiling never doubles past this. A server's hint is not capped by it. */
 declare const FOLLOW_RETRY_MAX_MS = 30000;
+/**
+ * A failure that backs off (a verdict's `backOffMs`) never waits longer than this, however often it
+ * repeats. A server's hint is not capped by it.
+ */
+declare const FOLLOW_BACK_OFF_MAX_MS: number;
 /** What the loop hands a source each time it opens one. */
 interface ChangeSourceOptions {
     /**
@@ -90,11 +102,29 @@ interface ChangeSourceOptions {
      * already failed changes nothing.
      */
     readonly opened: () => void;
+    /**
+     * Call with a position the transport has reached without a change to carry
+     * it — the cursor a socket's `feed.opened` names, or a poll's answer with no
+     * changes. The loop reopens from it after a failure, as it would from a
+     * delivered change's cursor, so a connection dropped before its first change
+     * replays from there rather than re-reading everything.
+     *
+     * Call it only between changes, once every change before that position has
+     * been yielded and the loop has asked for the next — a position ahead of a
+     * change still being applied would skip that change on the next open. A call
+     * from an open that has already failed changes nothing.
+     */
+    readonly reached: (cursor: string) => void;
 }
 /**
  * A transport for the changes feed: open from a position and yield each change,
  * in feed order, as ids (`INV-SS-CHANGE-IS-IDS`).
  *
+ * `C` is what it yields. `relyio.changes()` and `relyio.liveChanges()` yield a
+ * `FeedChange` — a `Change` with the position a refetch for it names
+ * (`fresh`) — and the loop hands `onChange` exactly that. A source of plain
+ * `Change`s is followed alike and hands plain `Change`s on.
+ *
  * A source ends **only** when its signal aborts. Every other end — a dropped
  * connection, a refusal, a socket closed by a deploy — is thrown, so the loop's
  * classifier can decide between reconnecting and stopping. `relyio.changes()` is
@@ -104,7 +134,7 @@ interface ChangeSourceOptions {
  * const source: ChangeSource = from => relyio.changes({ ...from, types: ['post'] })
  * ```
  */
-type ChangeSource = (options: ChangeSourceOptions) => AsyncIterable<Change>;
+type ChangeSource<C extends Change = Change> = (options: ChangeSourceOptions) => AsyncIterable<C>;
 /**
  * Why everything derived from the feed may be stale, so the consumer re-reads
  * what it holds:
@@ -112,9 +142,10 @@ type ChangeSource = (options: ChangeSourceOptions) => AsyncIterable<Change>;
  * - `expired` — the cursor could no longer be replayed. The source has resynced
  *   to the current position and yields nothing after it until the handler
  *   settles.
- * - `no-cursor` — the source failed before any change arrived, so there is no
- *   cursor to reopen from and whatever happened meanwhile cannot be replayed. The
- *   loop reopens from the current position once the handler settles.
+ * - `no-cursor` — the source failed before any change arrived or any position
+ *   was `reached()`, so there is no cursor to reopen from and whatever happened
+ *   meanwhile cannot be replayed. The loop reopens from the current position once
+ *   the handler settles.
  */
 type FollowResync = {
     readonly cause: 'expired';
@@ -147,19 +178,14 @@ type FollowState = {
     readonly kind: 'stopped';
     readonly error: unknown;
 };
-/**
- * A classifier's answer for one failure. `afterMs` is the server's hint — HTTP's
- * `Retry-After`, a socket's close code — and a floor under the loop's own
- * back-off: the wait is never shorter than it, and a hint longer than
- * {@link FOLLOW_RETRY_MAX_MS} is waited out in full.
- */
 type FollowVerdict = {
     readonly retry: false;
 } | {
     readonly retry: true;
     readonly afterMs?: number;
+    readonly backOffMs?: number;
 };
-interface FollowOptions {
+interface FollowOptions<C extends Change = Change> {
     /** Where to start: a change's cursor from an earlier follow. Omitted, the current position. */
     readonly since?: string;
     /** Ends the loop, which then resolves; a wait in progress ends at once. */
@@ -169,9 +195,16 @@ interface FollowOptions {
      * cursor counts as reached — a change whose handler has not settled is
      * replayed by the next open, never skipped. A throw is a failure like the
      * source's own, and the classifier sees it.
+     *
+     * It is handed what the source yields: from `relyio.changes()` or
+     * `relyio.liveChanges()`, a `FeedChange`, whose `fresh` a refetch names.
+     */
+    readonly onChange: (change: C) => void | Promise<void>;
+    /**
+     * Re-read everything derived from the feed. Awaited; see {@link FollowResync}.
+     * An `expired` resync's error carries the position it resynced to as `fresh`,
+     * which the re-reads name as a change's refetch does.
      */
-    readonly onChange: (change: Change) => void | Promise<void>;
-    /** Re-read everything derived from the feed. Awaited; see {@link FollowResync}. */
     readonly onResync: (resync: FollowResync) => void | Promise<void>;
     /** Observes each transition; see {@link FollowState}. It must not throw. */
     readonly onState?: (state: FollowState) => void;
@@ -209,6 +242,11 @@ type FollowEnd = {
  * service asked for: `Retry-After`, or a rate limit's `resetAt`. Anything else —
  * a refused key, a malformed request, a defect — stops the loop, because
  * retrying would meet the same refusal forever.
+ *
+ * A `LiveEdgeError` says what to do itself, from the edge's own tables: `stop`,
+ * `retry` (carrying a refused poll's `Retry-After`), or `back-off` — at least
+ * `VISITOR_ADMISSION_RETRY_AFTER_SECONDS` on the doubling schedule `backOffMs`
+ * describes.
  */
 declare function classifyFollowFailure(error: unknown): FollowVerdict;
 /**
@@ -220,12 +258,13 @@ declare function classifyFollowFailure(error: unknown): FollowVerdict;
  * - **A failure worth retrying** (`classify`) reopens the source after a
  *   jittered, doubling wait — a ceiling of {@link FOLLOW_RETRY_BASE_MS} doubled
  *   per consecutive failure up to {@link FOLLOW_RETRY_MAX_MS}, shortened by the
- *   jitter to no less than half of it, and never below the server's hint. A
+ *   jitter to no less than half of it, and never below the server's hint; a
+ *   verdict's `backOffMs` puts it on the longer schedule that field describes. A
  *   delivered change resets the doubling, and so does the source calling
  *   `opened()` once its transport is up. The source reopens from the last
- *   change's cursor so nothing is skipped; with no change seen yet there is none,
- *   so `onResync({ cause: 'no-cursor' })` runs first and the source reopens from
- *   the current position.
+ *   change's cursor — or the last position it `reached()` — so nothing is
+ *   skipped; with neither there is none, so `onResync({ cause: 'no-cursor' })`
+ *   runs first and the source reopens from the current position.
  * - **Anything else** stops the loop: reported once as `stopped`, and returned.
  *
  * It never rejects. An abort — in the source, in a handler, or during a wait —
@@ -236,13 +275,14 @@ declare function classifyFollowFailure(error: unknown): FollowVerdict;
  * const controller = new AbortController()
  * const end = await followChanges(from => relyio.changes({ ...from, types: ['post'] }), {
  *   signal: controller.signal,
- *   onChange: change => refetch(change.contentType, change.entryId),
- *   onResync: () => refetchEverything(),
+ *   onChange: change => refetch(change.contentType, change.entryId, change.fresh),
+ *   onResync: resync =>
+ *     refetchEverything(resync.cause === 'expired' ? resync.expired.fresh : undefined),
  * })
  * if (end.kind === 'stopped') console.error(end.error)
  * ```
  */
-declare function followChanges(source: ChangeSource, options: FollowOptions): Promise<FollowEnd>;
+declare function followChanges<C extends Change>(source: ChangeSource<C>, options: FollowOptions<C>): Promise<FollowEnd>;
 
 /**
  * Network-related errors
@@ -279,13 +319,13 @@ declare class ConnectionError extends SDKError {
  * (`INV-API-CODES-ARE-A-CLOSED-UNION`: a code no route declares is deleted, not
  * retained). An API key that has expired arrives as `INVALID_API_KEY` with
  * `details.reason: 'expired'`.
+ *
+ * `AuthenticationError` was deleted by REL-1471 for the same reason. The
+ * vocabulary's two 401 codes are `MISSING_API_KEY` and `INVALID_API_KEY`, and
+ * the mapper throws `MissingApiKeyError` and `InvalidApiKeyError` for them —
+ * so a generic 401 class had no refusal left to stand for, and nothing
+ * constructed it.
  */
-declare class AuthenticationError extends SDKError {
-    readonly code = "AUTHENTICATION_ERROR";
-    readonly retryable = false;
-    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
-    getUserMessage(): string;
-}
 declare class AuthorizationError extends SDKError {
     readonly code = "AUTHORIZATION_ERROR";
     readonly retryable = false;
@@ -446,6 +486,77 @@ declare class UnknownContractError extends SDKError {
     getUserMessage(): string;
 }
 
+/**
+ * What ended a subscription at RelyIO's live edge (`relyio.liveChanges()`):
+ *
+ * - `closed` — the edge closed the socket, or it dropped. `code` and `reason` are the close's. A
+ *   refusal is a socket accepted and closed at once, because a browser cannot read a refused
+ *   handshake's status (`@relyio/api-contract`'s `VISITOR_CLOSE_CODES`); a Worker deploy drops every
+ *   socket with a code of its own.
+ * - `refused` — a poll was refused with this contract code (`VISITOR_POLL_ROUTE`). The mapped error
+ *   is the `cause`.
+ * - `lost` — the socket stopped answering its keepalive, so the connection is presumed dead.
+ * - `unreadable` — the edge sent a frame or a poll answer the wire does not declare.
+ * - `needs-publishable-key` — the client holds no publishable key (`rly_pub_…`), so nothing was
+ *   sent: a secret or preview key never travels to the edge in a URL.
+ * - `needs-live-url` — the client cannot name the edge: `liveUrl` is not set and cannot be derived
+ *   from `baseUrl`, or it is not a URL. Nothing was sent.
+ */
+type LiveEdgeEnd = {
+    readonly kind: 'closed';
+    readonly code: number;
+    readonly reason: string;
+} | {
+    readonly kind: 'refused';
+    readonly code: string;
+} | {
+    readonly kind: 'lost';
+} | {
+    readonly kind: 'unreadable';
+    readonly what: string;
+} | {
+    readonly kind: 'needs-publishable-key';
+} | {
+    readonly kind: 'needs-live-url';
+};
+/**
+ * Every end of a live-edge subscription other than its signal aborting, and what to do about it.
+ *
+ * `retry` is the wire's own answer, read from `@relyio/api-contract`'s tables rather than restated
+ * here — `VISITOR_CLOSE_RETRY` for a close, `VISITOR_POLL_RETRY` for a refused poll:
+ *
+ * - `stop` — the same request meets the same answer (a refused key, origin or dataset, a malformed
+ *   query, a configuration the client lacks). `retryable` is `false`.
+ * - `retry` — a dropped connection, or the edge could not decide just now: reconnect with back-off
+ *   and jitter, from the last cursor.
+ * - `back-off` — the project, or this address, holds as many connections as it may (REL-1159). Wait
+ *   at least `VISITOR_ADMISSION_RETRY_AFTER_SECONDS`, with jitter, doubling while it repeats — and do
+ *   not fall back to polling, which the same admission refuses.
+ *
+ * `followChanges()`'s default classifier reads it, so a loop over `liveChanges()` needs no
+ * classifier of its own.
+ */
+declare class LiveEdgeError extends SDKError {
+    readonly code = "LIVE_EDGE_ENDED";
+    readonly retryable: boolean;
+    readonly end: LiveEdgeEnd;
+    readonly retry: VisitorRetry;
+    /** A refused poll's `Retry-After`, in milliseconds, where it carried a readable one. */
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, end: LiveEdgeEnd, retry: VisitorRetry, options?: {
+        readonly statusCode?: number;
+        readonly cause?: Error;
+        readonly retryAfterMs?: number;
+        readonly context?: Record<string, unknown>;
+    });
+    /**
+     * The base class rebuilds an error through its own four-argument constructor, which this class
+     * does not have; rebuilt that way, `end` would be a string and `retry` a number.
+     */
+    withContext(context: Record<string, unknown>): this;
+    getUserMessage(): string;
+}
+
 /**
  * Map a RelyIO refusal onto an SDK error class.
  *
@@ -508,28 +619,27 @@ declare class ErrorMapper {
  * })
  * ```
  */
+
 /**
- * Locale status information from entry metadata
+ * One locale an entry has content in, as `_metadata.availableLocales` lists it: the document's
+ * `EntryLocale`. `version` is that locale's own counter and is always sent.
  */
-interface LocaleStatus {
-    code: string;
-    status: 'published' | 'draft' | 'archived';
-    version?: number;
-    publishedAt?: string;
-}
+type LocaleStatus = EntryMetadata['availableLocales'][number];
 /**
- * Entry metadata with locale information
+ * The locale facts of an entry's `_metadata` that these helpers read — a `Pick` of the document's
+ * `EntryMetadata`, so what they read is what a read declares, not a second, looser copy of it.
+ * `locale`, `defaultLocale` and `availableLocales` are always sent; `requestedLocale`,
+ * `localeFallbacksApplied` and `localizations` only when the request asked for them.
  */
-interface LocaleMetadata {
-    locale?: string;
-    requestedLocale?: string;
-    defaultLocale?: string;
-    localeFallbacksApplied?: Record<string, string>;
-    availableLocales?: LocaleStatus[];
-    localizations?: Record<string, unknown>;
-}
+type LocaleMetadata = Pick<EntryMetadata, 'locale' | 'requestedLocale' | 'defaultLocale' | 'localeFallbacksApplied' | 'availableLocales' | 'localizations'>;
 /**
- * Entry with locale metadata
+ * Entry with locale metadata: an entry read — single, listed, a child or an expanded reference.
+ *
+ * Not a search or similar hit: a hit's `_metadata` is the document's `SearchHitMetadata`, which
+ * carries no `defaultLocale` or `availableLocales`, so passing one here is a compile error rather
+ * than an empty answer. That is what let the helpers below read `availableLocales` without an
+ * optional chain (REL-1413); the one on `_metadata` stays because a schema-defined query's row
+ * carries `_metadata` only when the query selects it.
  */
 interface LocalizedEntry {
     _metadata?: LocaleMetadata;
@@ -541,7 +651,7 @@ interface LocalizedEntry {
 interface LanguageSwitcherOption {
     code: string;
     label: string;
-    status: 'published' | 'draft' | 'archived';
+    status: LocaleStatus['status'];
     isCurrent: boolean;
     isDefault: boolean;
     hasContent: boolean;
@@ -895,4 +1005,4 @@ declare function snapToLadder(value: number): number;
 
 declare const VERSION = "__VERSION__";
 
-export { AuthenticationError, AuthorizationError, BaseContent, Change, type ChangeSource, type ChangeSourceOptions, ChangesExpiredError, ChangesExpiredReason, ConnectionError, ErrorMapper, FOLLOW_RETRY_BASE_MS, FOLLOW_RETRY_MAX_MS, type FollowEnd, type FollowOptions, type FollowResync, type FollowState, type FollowVerdict, IMAGE_LADDER, InvalidApiKeyError, type LanguageSwitcherOption, type LanguageSwitcherOptions, type LocaleMetadata, type LocaleStatus, type LocalizedEntry, MethodNotAllowedError, MissingApiKeyError, NetworkError, PUBLISHABLE_KEY_PREFIX, PayloadTooLargeError, PlanFeatureUnavailableError, RELYIO_CHANGE_EVENT, RELYIO_RESYNC_EVENT, RateLimitError, ReadOnlyKeyError, type RelyIOChangeDetail, type RelyIOFieldAttributes, type RelyIOFieldName, type RelyIOResyncDetail, SDKError, ServerError, ServiceIndeterminateError, TimeoutError, TransactionRolledBackError, type TranslationCompleteness, UnknownContractError, UsageQuotaExceededError, VERSION, buildLanguageSwitcher, classifyFollowFailure, estimateTranslationCompleteness, followChanges, getAllLocalizedValues, getAvailableLocaleCodes, getDefaultLocale, getFallbackFields, getFieldFallbackLocale, getLocalizedField, getPublishedLocaleCodes, getRequestedLocale, hasLocale, isFieldFallback, isPublishableKey, isPublishedInLocale, localeHelpers, needsTranslation, relyioField, snapToLadder };
+export { AuthorizationError, BaseContent, Change, type ChangeSource, type ChangeSourceOptions, ChangesExpiredError, ChangesExpiredReason, ConnectionError, EntryMetadata, ErrorMapper, FOLLOW_BACK_OFF_MAX_MS, FOLLOW_RETRY_BASE_MS, FOLLOW_RETRY_MAX_MS, type FollowEnd, type FollowOptions, type FollowResync, type FollowState, type FollowVerdict, IMAGE_LADDER, InvalidApiKeyError, type LanguageSwitcherOption, type LanguageSwitcherOptions, type LiveEdgeEnd, LiveEdgeError, type LocaleMetadata, type LocaleStatus, type LocalizedEntry, MethodNotAllowedError, MissingApiKeyError, NetworkError, PUBLISHABLE_KEY_PREFIX, PayloadTooLargeError, PlanFeatureUnavailableError, RELYIO_CHANGE_EVENT, RELYIO_RESYNC_EVENT, RateLimitError, ReadOnlyKeyError, type RelyIOChangeDetail, type RelyIOFieldAttributes, type RelyIOFieldName, type RelyIOResyncDetail, SDKError, ServerError, ServiceIndeterminateError, TimeoutError, TransactionRolledBackError, type TranslationCompleteness, UnknownContractError, UsageQuotaExceededError, VERSION, buildLanguageSwitcher, classifyFollowFailure, estimateTranslationCompleteness, followChanges, getAllLocalizedValues, getAvailableLocaleCodes, getDefaultLocale, getFallbackFields, getFieldFallbackLocale, getLocalizedField, getPublishedLocaleCodes, getRequestedLocale, hasLocale, isFieldFallback, isPublishableKey, isPublishedInLocale, localeHelpers, needsTranslation, relyioField, snapToLadder };