@relyio/sdk 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,13 +1,250 @@
-import { C as Change } from './index-BozPz4n1.cjs';
-export { A as ActiveSandbox, Z as AdhocAggregateBlock, Y as AdhocFetchBlock, X as AdhocQueryBuilder, W as AdhocQueryClient, a3 as AdhocQueryDefinition, a4 as AdhocQueryOptions, a6 as AdhocQueryResult, $ as AdhocSearchBlock, a0 as AdhocSimilarBlock, _ as AggregateMetric, a7 as AssetClient, ah as AssetEntryResponse, ae as AssetFileBlock, a8 as AssetFileBuilder, af as AssetFileExtracted, a9 as AssetUploadBuilder, ag as AssetUrls, ab as AssetVisibility, v as AutocompleteBuilder, D as AutocompleteResponse, B as AutocompleteSuggestion, L as BatchBuilder, K as BatchClient, M as BatchMethod, N as BatchOperation, Q as BatchOperationResult, O as BatchOptions, V as BatchResponse, U as BatchSummary, i as ChangesExpiredError, k as ChangesExpiredReason, j as ChangesOptions, q as ChildrenOptions, b as ClientSchema, g as ConditionalWriteOptions, al as ConfirmInput, am as ConfirmResult, p as ContentByIdBuilder, l as ContentClient, o as ContentQueryBuilder, ap as CreateAssetOptions, E as ExtendedQueryResult, ad as FileBackend, az as FileErrorCode, ac as FileStatus, aA as FileUploadError, aC as FileValidationConstraints, aB as FileValidationError, a1 as FilterValue, a2 as FullTextConfig, H as HttpClient, ar as MultipartCreateResult, as as MultipartPart, at as MultipartTarget, ai as PopulatedAssetReference, aj as PresignInput, ak as PresignResult, P as Project, a5 as QueryMetadata, R as Register, d as RegisteredSchema, an as ResolveUrlInput, ao as ResolveUrlResult, aw as ResourceConflictError, ax as ResourceExpiredError, av as ResourceNotFoundError, h as RetryableWriteOptions, S as SandboxState, u as SearchBuilder, t as SearchClient, J as SearchFields, I as SearchFilter, x as SearchMode, z as SearchResponse, y as SearchResultItem, e as SendOptions, n as SettingsClient, s as SettingsFetchOptions, w as SimilarBuilder, G as SimilarResponse, F as SimilarResult, m as SingletonClient, r as SingletonFetchOptions, a as TypedClientConfig, T as TypedRelyIOClient, au as UploadProgress, aq as WaitUntilReadyOptions, c as createClient, c as default, f as entityTagOf, aa as isAssetEntry, ay as isResourceNotFound, aD as validateFile } from './index-BozPz4n1.cjs';
+import { C as ChangesExpiredError, a as Change, b as ChangesExpiredReason } from './index-M0X45k7J.cjs';
+export { A as ActiveSandbox, a2 as AdhocAggregateBlock, a1 as AdhocFetchBlock, a0 as AdhocQueryBuilder, $ as AdhocQueryClient, a7 as AdhocQueryDefinition, a8 as AdhocQueryOptions, aa as AdhocQueryResult, a4 as AdhocSearchBlock, a3 as AggregateMetric, ab as AssetClient, am as AssetEntryResponse, ai as AssetFileBlock, ac as AssetFileBuilder, aj as AssetFileExtracted, ad as AssetUploadBuilder, al as AssetUrls, af as AssetVisibility, w as AutocompleteBuilder, G as AutocompleteResponse, F as AutocompleteSuggestion, U as BatchBuilder, Q as BatchClient, V as BatchMethod, W as BatchOperation, Y as BatchOperationResult, X as BatchOptions, _ as BatchResponse, Z as BatchSummary, k as ChangesHeadOptions, l as ChangesOptions, r as ChildrenOptions, e as ClientSchema, i as ConditionalWriteOptions, aq as ConfirmInput, ar as ConfirmResult, q as ContentByIdBuilder, m as ContentClient, p as ContentQueryBuilder, au as CreateAssetOptions, E as ExtendedQueryResult, ah as FileBackend, aE as FileErrorCode, ag as FileStatus, ak as FileStatusResult, aG as FileUploadError, aF as FileUploadErrorCode, aI as FileValidationConstraints, aH as FileValidationError, a5 as FilterValue, a6 as FullTextConfig, H as HttpClient, aw as MultipartCreateResult, ax as MultipartPart, ay as MultipartTarget, an as PopulatedAssetReference, ao as PresignInput, ap as PresignResult, P as Project, a9 as QueryMetadata, R as Register, f as RegisteredSchema, as as ResolveUrlInput, at as ResolveUrlResult, aB as ResourceConflictError, aC as ResourceExpiredError, aA as ResourceNotFoundError, j as RetryableWriteOptions, S as SandboxState, v as SearchBuilder, u as SearchClient, O as SearchEntry, L as SearchFields, K as SearchFilter, B as SearchHitMetadata, y as SearchMode, D as SearchResponse, z as SearchResultItem, M as SearchSort, N as SearchTypeName, g as SendOptions, o as SettingsClient, t as SettingsFetchOptions, x as SimilarBuilder, J as SimilarResponse, I as SimilarResult, n as SingletonClient, s as SingletonFetchOptions, d as TypedClientConfig, T as TypedRelyIOClient, az as UploadProgress, av as WaitUntilReadyOptions, c as createClient, c as default, h as entityTagOf, ae as isAssetEntry, aD as isResourceNotFound, aJ as validateFile } from './index-M0X45k7J.cjs';
 export { fields } from './schema/index.cjs';
-import { S as SDKError, B as BaseContent } from './index-C5mRBb6t.cjs';
-export { a as ApiMethod, A as ApiPath, t as ApiResponse, b as ApiSuccessBody, x as BaseValidationError, q as CacheConfig, v as CacheStrategy, g as ContentQueryResult, k as ContentTypeSchema, C as CreateInput, j as CustomQuery, D as DebugConfig, E as Environment, l as FieldOptions, F as FieldTypeName, H as InvalidFieldTypeError, I as InvalidPayloadError, L as LogLevel, M as MatchRouteOptions, P as PerformanceMetrics, Q as QueryOptions, r as RealtimeConfig, o as RealtimeEvent, n as RealtimeEventType, R as RelyIOConfig, s as RequestConfig, G as RequiredFieldError, u as RetryConfig, c as RouteMatch, z as SchemaValidationError, i as SettingsGroup, h as SingletonContent, f as SortOptions, p as SubscriptionOptions, U as UpdateInput, y as ValidationError, V as ValidationRule, w as ValidationViolation, d as WhereClause, e as WhereOperator, W as Wire, m as matchRoute } from './index-C5mRBb6t.cjs';
+import { S as SDKError, B as BaseContent } from './index-DbsTUw3Q.cjs';
+export { b as ApiMethod, A as ApiPath, v as ApiResponse, c as ApiSuccessBody, z as BaseValidationError, s as CacheConfig, x as CacheStrategy, j as ContentQueryResult, n as ContentTypeSchema, C as CreateInput, l as CustomQuery, D as DebugConfig, E as Environment, o as FieldOptions, F as FieldTypeName, 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, a as RelyIOConfigUpdate, u as RequestConfig, w as RetryConfig, d as RouteMatch, k as SingletonContent, i as SortOptions, r as SubscriptionOptions, U as UpdateInput, G as ValidationError, V as ValidationRule, y as ValidationViolation, g as WhereClause, f as WhereFieldCondition, h as WhereOperator, e as WhereScalar, W as Wire, m as matchRoute } from './index-DbsTUw3Q.cjs';
 export { camelToSnake, createDeferred, debounce, deepClone, generateId, isBrowser, isNode, isPlainObject, isValidEmail, isValidUrl, mergeDeep, omit, pick, retry, sleep, snakeToCamel, throttle, toSafeString } from './utils/index.cjs';
-export { ax as AggregateBlock, G as AssetTypeConfig, K as AssetTypeDefinition, C as ComponentConfig, v as ComponentDefinition, w as ComponentMetadata, aw as FetchBlock, O as FileKindConfig, a3 as FileScanConfig, a2 as FileUploadConfig, aH as FilterDefinition, X as ImageExifConfig, N as ImageKindConfig, W as ImageSourceConfig, U as ImageUploadConfig, aF as IncludeDefinition, M as InferAssetType, aR as InferQueryParams, aQ as InferQueryResponse, t as InferSingleton, I as InferSingletonContentType, au as QueryConfig, av as QueryDefinition, h as SchemaAssetTypeNames, S as SchemaConfig, b as SchemaContentTypeNames, a as SchemaDefinition, f as SchemaLocaleCodes, e as SchemaQueryNames, g as SchemaSettingsGroupNames, c as SchemaSingletonNames, ay as SearchBlock, aG as SelectMapping, A as SettingsGroupConfig, B as SettingsGroupDefinition, az as SimilarBlock, r as SingletonContentTypeDefinition, s as SingletonMetadata, aD as SortCondition, Y as VariantDefinition, $ as VideoCaptionsConfig, a0 as VideoDownloadConfig, V as VideoKindConfig, _ as VideoPosterConfig, Z as VideoUploadConfig, a1 as VideoWatermarkConfig, aA as WhereCondition, F as defineAssetType, u as defineComponent, at as defineQuery, d as defineSchema, z as defineSettingsGroup, q as defineSingleton, p as defineSingletonContentType } from './define-schema-2xbHgtK-.cjs';
-export { n as BaseFieldConfig, x as ContentTypeConfig, y as ContentTypeConfigWithFields, z as ContentTypeConfigWithFieldsets, G as ContentTypeDefinition, H as EntryMetadata, c as FieldDefinition, b as FieldRule, o as FieldType, F as FieldUIConfig, w as Fieldset, J as InferContentType, K as LocalePublicationFields, L as LocalizationConfig, u as defineContentType, v as fieldset } from './define-content-type-CBfnTWSS.cjs';
+import { Q as EntryMetadata } from './define-content-type-DiVpbwNs.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-DiVpbwNs.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-D7MButVt.cjs';
 import './dev-handshake/index.cjs';
 
+/**
+ * What a key may do is in its prefix. A RelyIO key is `rly_{scope}_v1_{entropy}_{checksum}`, and a
+ * publishable key — the one project key that may sit in a browser (`sdk-surfaces-spec.md` decision
+ * 29) — is scope `pub`. Its scope is in its prefix so that no stored flag can disagree with it.
+ *
+ * The truth is the service's: `isPublishableApiKey` in
+ * `packages/data/metadata-db/src/utils/api-key-generator.ts`, which decides whether a presented key is
+ * publishable. This package may not import it (`INV-SS-CUSTOMER-FENCE`), so the prefix is restated
+ * here, and `src/__tests__/key-kind.test.ts` reads that file and fails when the two part.
+ */
+declare const PUBLISHABLE_KEY_PREFIX = "rly_pub_";
+/**
+ * Whether `apiKey` is a publishable key (`rly_pub_…`).
+ *
+ * The one reading of a key's kind a surface asks the core for: `@relyio/react`'s `live` refuses to
+ * start in a browser without one, and the edge transport (LV5.2) is chosen by it. It reads the prefix
+ * only — whether the key is valid, active or allowed from this origin is the service's to say.
+ *
+ * `undefined` is a client that holds no key: `createClient({ apiKey: process.env.X! })` with the
+ * variable unset constructs, and refuses at its first request (REL-1120). Such a client holds no
+ * publishable key, so the answer is `false` rather than a `TypeError` in a caller that only asked.
+ */
+declare const isPublishableKey: (apiKey: string | undefined) => boolean;
+
+/**
+ * `followChanges()` — the one loop that follows a changes source until its
+ * signal aborts (`INV-SS-ONE-CORE`, REL-1215).
+ *
+ * `<RelyIOProvider live>` and the preview toolbar both follow the feed, and the
+ * toolbar may not import `@relyio/react` (`INV-SS-LAYER-DIRECTION`), so each
+ * carried its own copy of this policy until the core — the one package both may
+ * import — owned it. Each surface now says only what a change, a resync and a
+ * 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.
+ */
+
+/** 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;
+/** What the loop hands a source each time it opens one. */
+interface ChangeSourceOptions {
+    /**
+     * The cursor of the last change the loop applied — or the `since` it was
+     * started with. Omitted, the source starts from the dataset's current position
+     * and replays nothing.
+     */
+    readonly since?: string;
+    /**
+     * Ends the source. On an abort the iteration **completes**: no rejection, and
+     * no further request or frame.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Call when `since` can no longer be replayed (`INV-SS-CURSOR-REPLAYS`):
+     * resync to the dataset's current position, call this with the error, and
+     * await it before yielding any change after the new position.
+     */
+    readonly onExpired: (expired: ChangesExpiredError) => Promise<void>;
+    /**
+     * Call once the transport is established — a socket's `open`, say. The loop
+     * takes it as the source being healthy and resets its back-off, so a
+     * connection that is later dropped reconnects after the base wait however
+     * often that has happened. Optional to call: a source that never does has its
+     * back-off reset only by a delivered change. A call from an open that has
+     * already failed changes nothing.
+     */
+    readonly opened: () => 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`).
+ *
+ * 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
+ * one as it stands:
+ *
+ * ```ts
+ * const source: ChangeSource = from => relyio.changes({ ...from, types: ['post'] })
+ * ```
+ */
+type ChangeSource = (options: ChangeSourceOptions) => AsyncIterable<Change>;
+/**
+ * Why everything derived from the feed may be stale, so the consumer re-reads
+ * what it holds:
+ *
+ * - `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.
+ */
+type FollowResync = {
+    readonly cause: 'expired';
+    readonly expired: ChangesExpiredError;
+} | {
+    readonly cause: 'no-cursor';
+};
+/**
+ * What the loop is doing, reported on every transition so a surface can name it
+ * rather than keep its own count:
+ *
+ * - `following` — the source is open (reported on every open, reconnects too);
+ * - `resynced` — the consumer's resync handler has settled;
+ * - `reconnecting` — `error` was worth retrying; the source reopens after
+ *   `retryInMs`;
+ * - `stopped` — `error` was not; the loop has ended. Reported once.
+ *
+ * Nothing is reported after the signal aborts.
+ */
+type FollowState = {
+    readonly kind: 'following';
+} | {
+    readonly kind: 'resynced';
+    readonly resync: FollowResync;
+} | {
+    readonly kind: 'reconnecting';
+    readonly error: unknown;
+    readonly retryInMs: number;
+} | {
+    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;
+};
+interface FollowOptions {
+    /** 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. */
+    readonly signal: AbortSignal;
+    /**
+     * Apply one change. Awaited before the next change is taken, and before its
+     * 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.
+     */
+    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;
+    /**
+     * Whether a failure is worth reopening the source for, and any wait the
+     * server asked for. Default {@link classifyFollowFailure}. A transport whose
+     * failures the core's errors do not describe supplies its own, and delegates
+     * the rest to the default.
+     */
+    readonly classify?: (error: unknown) => FollowVerdict;
+    /**
+     * The jitter's source of randomness, `Math.random` by default: a number in
+     * `[0, 1)`. `0` waits the whole ceiling; values towards `1` shorten the wait
+     * to just over half of it. A test fixes it.
+     */
+    readonly random?: () => number;
+}
+/**
+ * How the loop ended — never a rejection. `since` is the cursor of the last
+ * change applied (or the starting `since`), which a caller that stopped the loop
+ * to reopen it with a different filter starts the next one from.
+ */
+type FollowEnd = {
+    readonly kind: 'aborted';
+    readonly since: string | undefined;
+} | {
+    readonly kind: 'stopped';
+    readonly since: string | undefined;
+    readonly error: unknown;
+};
+/**
+ * The default classifier. A failure is worth retrying when the core calls it
+ * retryable — `SDKError.retryable`, **after** the client's own retries, so this
+ * is an outage that outlasted them — and the wait it carries is the one the
+ * 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.
+ */
+declare function classifyFollowFailure(error: unknown): FollowVerdict;
+/**
+ * Follow `source` until `signal` aborts: apply each change in feed order, one at
+ * a time, and carry the cursor.
+ *
+ * - **Expired cursor.** The source resyncs and awaits `onResync({ cause:
+ *   'expired' })` before yielding anything after the new position.
+ * - **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
+ *   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.
+ * - **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 —
+ * resolves it at once with no further open, resync or state; a change whose
+ * handler is running when the abort lands is finished and its cursor kept.
+ *
+ * ```ts
+ * 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(),
+ * })
+ * if (end.kind === 'stopped') console.error(end.error)
+ * ```
+ */
+declare function followChanges(source: ChangeSource, options: FollowOptions): Promise<FollowEnd>;
+
 /**
  * Network-related errors
  */
@@ -20,7 +257,11 @@ declare class NetworkError extends SDKError {
 declare class TimeoutError extends SDKError {
     readonly code = "TIMEOUT_ERROR";
     readonly retryable = true;
-    constructor(message?: string, timeout?: number, statusCode?: number, cause?: Error);
+    /**
+     * @param context - Carried beside `timeout`. The mapper passes a `REQUEST_TIMEOUT` refusal's body
+     *   as `context.response`, as it does for every other contract code.
+     */
+    constructor(message?: string, timeout?: number, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
     getUserMessage(): string;
 }
 declare class ConnectionError extends SDKError {
@@ -39,13 +280,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;
@@ -268,28 +509,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;
@@ -301,7 +541,7 @@ interface LocalizedEntry {
 interface LanguageSwitcherOption {
     code: string;
     label: string;
-    status: 'published' | 'draft' | 'archived';
+    status: LocaleStatus['status'];
     isCurrent: boolean;
     isDefault: boolean;
     hasContent: boolean;
@@ -561,6 +801,41 @@ declare const RELYIO_CHANGE_EVENT = "relyio:change";
  * ```
  */
 type RelyIOChangeDetail = Change;
+/**
+ * The DOM event a preview surface dispatches when **everything** on the page may be stale: the feed
+ * lost its place, so the surface re-read what it holds without a change to name (REL-1214). Same
+ * target and the same wire-contract rule as {@link RELYIO_CHANGE_EVENT}; `<RelyIORefresh />` listens
+ * for both.
+ *
+ * **A second name, not a second shape of the first.** A `relyio:change` listener reads `detail` as
+ * a {@link Change}. A resync dispatched under that name would hand it `undefined` ids at runtime —
+ * and a listener built against an earlier release, or written in JavaScript, gets no type error to
+ * warn it. Under its own name, a listener that knows only `relyio:change` behaves exactly as before:
+ * it does not hear a resync. Nor is a resync one synthetic change per re-read entry: a change carries
+ * a `cursor`, and the feed issued none for it.
+ *
+ * @example
+ * ```ts
+ * window.addEventListener(RELYIO_RESYNC_EVENT, () => refetchEverything())
+ * ```
+ */
+declare const RELYIO_RESYNC_EVENT = "relyio:resync";
+/**
+ * The `detail` of a {@link RELYIO_RESYNC_EVENT} dispatch: why the feed lost its place, one arm per
+ * `FollowResync` cause, as plain data.
+ *
+ * - `expired` — the cursor could no longer be replayed; `reason` is the feed's own
+ *   ({@link ChangesExpiredReason}).
+ * - `no-cursor` — the feed failed before any change arrived, so it had no cursor to resume from.
+ *
+ * A listener that only refreshes reads none of it.
+ */
+type RelyIOResyncDetail = {
+    readonly cause: 'expired';
+    readonly reason: ChangesExpiredReason;
+} | {
+    readonly cause: 'no-cursor';
+};
 
 /**
  * The width ladder the delivery Worker snaps every rendered dimension to
@@ -620,4 +895,4 @@ declare function snapToLadder(value: number): number;
 
 declare const VERSION = "__VERSION__";
 
-export { AuthenticationError, AuthorizationError, BaseContent, Change, ConnectionError, ErrorMapper, IMAGE_LADDER, InvalidApiKeyError, type LanguageSwitcherOption, type LanguageSwitcherOptions, type LocaleMetadata, type LocaleStatus, type LocalizedEntry, MethodNotAllowedError, MissingApiKeyError, NetworkError, PayloadTooLargeError, PlanFeatureUnavailableError, RELYIO_CHANGE_EVENT, RateLimitError, ReadOnlyKeyError, type RelyIOChangeDetail, type RelyIOFieldAttributes, type RelyIOFieldName, SDKError, ServerError, ServiceIndeterminateError, TimeoutError, TransactionRolledBackError, type TranslationCompleteness, UnknownContractError, UsageQuotaExceededError, VERSION, buildLanguageSwitcher, estimateTranslationCompleteness, getAllLocalizedValues, getAvailableLocaleCodes, getDefaultLocale, getFallbackFields, getFieldFallbackLocale, getLocalizedField, getPublishedLocaleCodes, getRequestedLocale, hasLocale, isFieldFallback, isPublishedInLocale, localeHelpers, needsTranslation, relyioField, snapToLadder };
+export { AuthorizationError, BaseContent, Change, type ChangeSource, type ChangeSourceOptions, ChangesExpiredError, ChangesExpiredReason, ConnectionError, EntryMetadata, 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 };