@relyio/sdk 0.6.0 → 0.8.0

package/dist/{index-XqoGUaAY.d.ts → index-yRJ2IqM_.d.ts}

@@ -1,6 +1,7 @@
-import { N as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, O as PathParamsOf, v as ApiResponse, W as Wire, u as RequestConfig, B as BaseContent, f as WhereClause, h as SortOptions, i as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, z as BaseValidationError, y as ValidationViolation, T as components, X as paths, R as RelyIOConfig } from './index-yPbhZc6q.js';
-import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, h as SchemaAssetTypeNames, c as SchemaSingletonNames, g as SchemaSettingsGroupNames, I as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-ChvAzY8H.js';
-import { Q as InferContentType, a6 as InferAssetType, a0 as InferSingleton } from './define-content-type-CDB3kyeA.js';
+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-Cv4tmcrw.js';
+import { aK as components, aJ as paths, W as InferContentType, aa as InferAssetType, a3 as InferSingleton } from './define-content-type-cEGjIwT5.js';
+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-BPj2srgh.js';
+import { VisitorResyncReason } from './live-visitor.js';
 import { DevUnreadableReason } from './dev-handshake/index.js';
 
 /**
@@ -99,14 +100,21 @@ type SendOptions<P extends ApiPath, M extends ApiMethod<P>> = {
  * nothing inside the SDK uses them.
  */
 declare class HttpClient {
-    private baseUrl;
-    private defaultHeaders;
-    private timeout;
-    private retryPolicy;
-    private debug;
-    private logger?;
-    private config;
+    /** What every request reads off the configuration, derived by {@link configure} and nowhere else. */
+    private connection;
     constructor(config: MergedRelyIOConfig);
+    /**
+     * Run on `config` from now on: every later request — whoever holds this client — is sent to its
+     * `baseUrl`, with its headers, key and dataset, its timeout and retries, through its `fetch`, and
+     * logged by its `debug` options.
+     *
+     * The client's own `updateConfig()` calls this rather than building a second client, so a
+     * `content()` or other sub-client taken before the update sends through the update too. Anything
+     * set on this client since it was last configured — `setDefaultHeaders()`, `setBaseUrl()` — is
+     * replaced by what `config` says.
+     */
+    configure(config: MergedRelyIOConfig): void;
+    private announce;
     /**
      * Call a route the committed document declares, and get back the body that
      * document says it serves.
@@ -129,13 +137,17 @@ declare class HttpClient {
      *
      * The loop always makes one attempt. The incumbent's `while (attempt <
      * maxAttempts)` made none at `retryAttempts: 0` — a value the config validator
-     * accepts — and then dereferenced an unassigned `lastError`.
+     * then accepted, and now refuses — and then dereferenced an unassigned
+     * `lastError`. `retryAttempts` is the most attempts, the first included; an
+     * `HttpClient` constructed directly is not validated, so the first attempt
+     * stays unconditional.
      *
      * A request that would carry no `X-API-Key` makes none: it rejects with
      * `MissingApiKeyError` before `fetch` is called, is not retried, and names
      * `apiKey`. This is where a client built without a key learns it — the
      * constructor accepts one so that a module-scope client can be evaluated by a
-     * build that holds no key (REL-1120).
+     * build that holds no key (REL-1120) — and so does one whose `setApiKey` was
+     * given none.
      */
     request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
     /**
@@ -159,13 +171,28 @@ declare class HttpClient {
      */
     patch<T = unknown>(url: string, data?: unknown, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
     /**
-     * Set default headers for all requests
+     * Add headers to every later request, each replacing any header of the same name — the name
+     * matched without regard to case — until the client is next configured.
      */
     setDefaultHeaders(headers: Record<string, string>): void;
     /**
-     * Set authentication token
+     * Replace the key every later request sends as `X-API-Key`, and the `apiKey` the configuration
+     * reports.
+     *
+     * The key is read the way construction reads it (`presentKey`): an absent, empty or blank key is
+     * no key, so the header is dropped and the next request is refused with `MissingApiKeyError`
+     * before anything is sent. A key header of any other spelling — one given in `headers` — goes
+     * too, from the headers sent and from the headers the configuration reports, so the old key is
+     * never sent beside the new one.
+     *
+     * The configuration is the one the owning `TypedRelyIOClient` holds (it hands its own to the
+     * constructor), so its `getConfig().apiKey` — what a surface reads to decide a key's kind — is the
+     * key sent from here on.
+     *
+     * This replaced `setAuthToken`, which added `Authorization: Bearer` beside an `X-API-Key` it
+     * never touched: the API reads `X-API-Key` first, so the old key was the one used (REL-1385).
      */
-    setAuthToken(token: string): void;
+    setApiKey(apiKey: string): void;
     /**
      * Get current default headers
      */
@@ -190,7 +217,12 @@ declare class HttpClient {
      */
     private makeRequest;
     /**
-     * Filter headers that browsers don't allow to be set manually
+     * The headers without those a browser controls itself, when this is a browser; unchanged when it
+     * is not.
+     *
+     * A name is matched without regard to case (RFC 9110 §5.1), because a browser refuses `Origin`
+     * whatever case a page spells it in. This matched only the all-lowercase and all-uppercase
+     * spellings, so `Origin` and `User-Agent` — how people write them — reached `fetch` (REL-1409).
      */
     private filterHeadersForBrowser;
     /**
@@ -205,6 +237,18 @@ declare class HttpClient {
     private log;
 }
 
+/**
+ * The client's locale as a sub-client holds it: a function it asks on every call, or a locale fixed
+ * when it was built.
+ *
+ * `TypedRelyIOClient` hands every sub-client and builder a function over the configuration it holds,
+ * so one taken before `updateConfig({ locale })` sends the locale the client holds when the call is
+ * made, and none once `updateConfig({ locale: null })` has cleared it (REL-1453). A string is a locale
+ * fixed at construction — a sub-client's own `withLocale()`, or one built directly — and stays what it
+ * was.
+ */
+type ClientLocale = string | (() => string | undefined);
+
 /**
  * Children population options
  */
@@ -244,10 +288,9 @@ type ExtendedQueryResult<T extends BaseContent = BaseContent> = ContentQueryResu
  *   .execute()
  * ```
  */
-declare class ContentQueryBuilder<T extends BaseContent = BaseContent> {
+declare class ContentQueryBuilder<T extends BaseContent = BaseContent, F extends BaseContent = T> {
     private readonly httpClient;
     private readonly contentType;
-    private readonly defaultLocale?;
     private queryOptions;
     private localeValue?;
     private localesArray?;
@@ -257,7 +300,22 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent> {
     private pageNumber?;
     private pageSizeValue?;
     private requestHeaders?;
-    constructor(httpClient: HttpClient, contentType: string, defaultLocale?: string | undefined);
+    /** 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
@@ -265,13 +323,14 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent> {
      */
     headers(headers: Record<string, string>): this;
     /**
-     * Add where conditions to the query
+     * Add where conditions to the query: conditions on the fields the content type declares. A
+     * condition on `_metadata` is refused here, before anything is sent (`refuseMetadataConditions`).
      */
-    where(conditions: WhereClause<T>): this;
+    where(conditions: WhereClause<F>): this;
     /**
      * Select specific fields to return
      */
-    select(fields: (keyof T)[]): this;
+    select(fields: NonNullable<QueryOptions<T, F>['select']>): this;
     /**
      * Include related content in the response
      */
@@ -289,7 +348,7 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent> {
      * ```
      */
     sort(field: string, direction: 'asc' | 'desc'): this;
-    sort(sortOptions: SortOptions<T>): this;
+    sort(sortOptions: SortOptions<F>): this;
     /**
      * Sort by a specific field in ascending order
      */
@@ -418,11 +477,11 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent> {
     /**
      * Clone the query builder
      */
-    clone(): ContentQueryBuilder<T>;
+    clone(): ContentQueryBuilder<T, F>;
     /**
      * Get the current query options
      */
-    getQueryOptions(): QueryOptions<T>;
+    getQueryOptions(): QueryOptions<T, F>;
     /**
      * Execute the query and return the whole body.
      *
@@ -459,14 +518,28 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
     private readonly httpClient;
     private readonly contentType;
     private readonly id;
-    private readonly defaultLocale?;
     private includeRelations?;
     private localeValue?;
     private localesArray?;
     private fetchAllLocales;
     private childrenOptions?;
     private requestHeaders?;
-    constructor(httpClient: HttpClient, contentType: string, id: string, defaultLocale?: string | undefined);
+    /** 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
      */
@@ -615,8 +688,13 @@ interface ContentFetchOptions<T extends BaseContent = BaseContent> {
 declare class ContentClient<T extends BaseContent = BaseContent> {
     private readonly httpClient;
     private readonly contentType;
-    private readonly defaultLocale?;
-    constructor(httpClient: HttpClient, contentType: string, defaultLocale?: string | undefined);
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    private readonly clientLocale;
+    /**
+     * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+     *   every call, or a locale fixed for this client
+     */
+    constructor(httpClient: HttpClient, contentType: string, locale?: ClientLocale);
     /**
      * Create a new query builder for this content type
      */
@@ -683,7 +761,7 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
      * @param options - Create options (slug, locale, parentId, sortOrder), and `headers` this one
      *   request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset other than the
      *   client's. They are sent, never put in the body; `idempotencyKey` still wins over an
-     *   `Idempotency-Key` among them.
+     *   `Idempotency-Key` among them. `locale` defaults to the client's own (`withLocale()`).
      */
     create(data: CreateInput<T>, options?: {
         slug?: string;
@@ -698,7 +776,8 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
      * @param data - Fields to update
      * @param options - Update options (slug, locale, parentId, sortOrder), and `headers` this one
      *   request adds, as for {@link create}. `ifMatch` and `idempotencyKey` win over the same
-     *   header among them.
+     *   header among them. `locale` defaults to the client's own, the locale whose entity tag
+     *   {@link fetchOneWithTag} reads, so the tag it hands back is checked against the same locale.
      */
     update(id: string, data: UpdateInput<T>, options?: {
         slug?: string;
@@ -719,8 +798,9 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
      * Get version history for one locale of an entry.
      *
      * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
-     * schema default, no fallback is applied, and a locale with no history returns an empty array
-     * rather than another locale's rows. Every row names the locale it belongs to.
+     * client's own (`withLocale()`), else the schema default; no fallback is applied, and a locale
+     * with no history returns an empty array rather than another locale's rows. Every row names the
+     * locale it belongs to.
      */
     versions(id: string, options?: {
         limit?: number;
@@ -732,8 +812,8 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
     /**
      * Get a specific version of an entry.
      *
-     * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
-     * different content in each one.
+     * `locale` defaults to the client's own (`withLocale()`), else the schema default. Version
+     * numbers are per locale, so version 2 is different content in each one.
      */
     version(id: string, versionNumber: number, options?: {
         locale?: string;
@@ -770,11 +850,12 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
      */
     ofType<U extends BaseContent = BaseContent>(contentType: string): ContentClient<U>;
     /**
-     * Create a new ContentClient with a different default locale
+     * Create a new ContentClient with a different default locale, fixed: an update of the client's
+     * locale (`updateConfig({ locale })`) does not reach it
      */
     withLocale(locale: string): ContentClient<T>;
     /**
-     * Get the current default locale
+     * Get the default locale as it is now: the client's, or the one `withLocale()` fixed
      */
     getDefaultLocale(): string | undefined;
 }
@@ -785,21 +866,40 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
  * A **thin customer-side mirror** of the realtime-contracts `FileErrorCode`
  * (correction C6 — the SDK must not import the server/Studio contracts package).
  * Keep the members in sync with `@relyio/realtime-contracts`.
+ *
+ * Written once, as values, because a processing failure's code arrives as a string the service
+ * stored and has to be recognised at runtime; `FileErrorCode` is read off this list. The module is
+ * internal — `errors/index.ts` does not re-export it — so the list is not a second public name for
+ * the type.
  */
-type FileErrorCode = 'UPLOAD_TOO_LARGE' | 'UNSUPPORTED_MIME' | 'DIMENSION_OUT_OF_RANGE' | 'ASPECT_RATIO' | 'CORRUPT_FILE' | 'UNSUPPORTED_CODEC' | 'IMAGES_LIMIT_EXCEEDED' | 'STREAM_ENCODE_FAILED' | 'SCAN_INFECTED' | 'INTERNAL';
+declare const FILE_ERROR_CODES: readonly ["UPLOAD_TOO_LARGE", "UNSUPPORTED_MIME", "DIMENSION_OUT_OF_RANGE", "ASPECT_RATIO", "CORRUPT_FILE", "UNSUPPORTED_CODEC", "IMAGES_LIMIT_EXCEEDED", "STREAM_ENCODE_FAILED", "SCAN_INFECTED", "INTERNAL"];
+
+/**
+ * Upload/processing error taxonomy (plan 17, 00b Step 4): a customer-side mirror of the
+ * realtime-contracts `FileErrorCode`, read off the list in `./file-error-codes`.
+ */
+type FileErrorCode = (typeof FILE_ERROR_CODES)[number];
+/**
+ * The code a {@link FileUploadError} carries: a {@link FileErrorCode}, or `PROCESSING_FAILED` for a
+ * processing failure this SDK cannot name — the service stored no code, as an image or file
+ * processing failure is stored today, or one this version of the SDK predates. What the service
+ * stored is in the error's `context.processingError` either way.
+ */
+type FileUploadErrorCode = FileErrorCode | 'PROCESSING_FAILED';
 /**
  * A failure during the upload protocol (presign / PUT / multipart / confirm) or
- * surfaced by the server's processing pipeline. Carries a typed {@link FileErrorCode}
+ * surfaced by the server's processing pipeline. Carries a typed {@link FileUploadErrorCode}
  * and a `retriable` hint so callers (and `upload()`'s bounded auto-retry) can
  * decide whether to retry on the same entry.
  */
 declare class FileUploadError extends SDKError {
-    readonly code: FileErrorCode;
+    readonly code: FileUploadErrorCode;
     readonly retryable: boolean;
-    constructor(code: FileErrorCode, message: string, options?: {
+    constructor(code: FileUploadErrorCode, message: string, options?: {
         retriable?: boolean;
         statusCode?: number;
         cause?: Error;
+        context?: Record<string, unknown>;
     });
     getUserMessage(): string;
 }
@@ -837,73 +937,20 @@ type AssetVisibility = 'public' | 'protected' | 'private';
 type FileStatus = 'pending_upload' | 'uploading' | 'processing' | 'ready' | 'failed';
 /** Storage backend: `r2` = image + file kinds, `stream` = video kind. */
 type FileBackend = 'r2' | 'stream';
-/** Extracted media metadata (Phase 1 basics + Phase 2 enrichment, plans 15–19). */
-interface AssetFileExtracted {
-    width?: number;
-    height?: number;
-    format?: string;
-    duration?: number;
-    hasAlpha?: boolean;
-    isAnimated?: boolean;
-    orientation?: number;
-    placeholder?: string;
-    dominantColor?: string;
-    palette?: string[];
-    exif?: Record<string, unknown>;
-    video?: {
-        codec?: string;
-        bitrate?: number;
-        framerate?: number;
-        audioTracks?: unknown[];
-    };
-    pageCount?: number;
-    text?: string;
-    safety?: {
-        nsfwScore?: number;
-        flagged?: boolean;
-        categories?: string[];
-    };
-    [key: string]: unknown;
-}
-/** Customer-facing file binding block on an asset entry. */
-interface AssetFileBlock {
-    status: FileStatus;
-    backend: FileBackend;
-    fileName: string;
-    mimeType?: string | null;
-    size?: number | null;
-    /** Advisory client-computed SHA-256 (duplicate detection only). */
-    hash?: string | null;
-    visibility: AssetVisibility;
-    extracted?: AssetFileExtracted;
-    /** 0..1 normalized smart-crop anchor (written by plan 18). */
-    focalPoint?: {
-        x: number;
-        y: number;
-    };
-    /** Phase-2 enrichment status — independent of `status` (plan 15). */
-    enrichment?: {
-        status: 'pending' | 'running' | 'complete' | 'partial' | 'failed';
-    };
-    /** File-kind malware scan status (plan 19). */
-    scan?: {
-        status: 'pending' | 'clean' | 'infected' | 'error' | 'skipped';
-    };
-    /** Processing progress (e.g. video encoding %) + terminal error. */
-    processing?: {
-        stage?: string;
-        progress?: number;
-        error?: {
-            code?: string;
-            message?: string;
-            retriable?: boolean;
-        };
-    };
-    /** Video playback readiness. */
-    playback?: {
-        ready?: boolean;
-    };
-}
+/**
+ * Customer-facing file binding block on an asset entry: the document's `AssetFile` — status,
+ * backend, file name, MIME type, size, advisory hash, visibility, extracted metadata, focal point,
+ * enrichment and scan status, processing stage/progress/error, and video playback readiness.
+ */
+type AssetFileBlock = components['schemas']['AssetFile'];
+/** Extracted media metadata (Phase 1 basics + Phase 2 enrichment, plans 15–19); open-ended. */
+type AssetFileExtracted = NonNullable<AssetFileBlock['extracted']>;
+/**
+ * Where one file binding's upload got to, as {@link AssetFileBuilder.status} reads it
+ * (`GET /v1/{assetType}/{id}/file`): the document's `FileStatus` — the binding's lifecycle and
+ * nothing of the entry's content. `processing.error` is present exactly while `status` is `failed`.
+ */
+type FileStatusResult = components['schemas']['FileStatus'];
 /**
  * Computed gateway delivery URLs (the reserved `urls` key). Always served from
  * `cdn.relyio.net`. Image bindings expose `original` + `variants`; video bindings
@@ -1036,9 +1083,12 @@ type UpdateAssetOptions = {
 interface WaitUntilReadyOptions {
     /** Locale of the binding to watch. */
     locale?: string;
-    /** Total time to wait before giving up (ms). Default 60000. */
+    /**
+     * Total time to wait before giving up (ms), from 0 to 2147483647. Default 60000. `0` reads the
+     * file once and rejects with a `TimeoutError` if it is not ready.
+     */
     timeoutMs?: number;
-    /** Delay between polls (ms). Default 1500. */
+    /** Delay between polls (ms), from 1 to 2147483647. Default 1500. */
     pollIntervalMs?: number;
 }
 /**
@@ -1049,8 +1099,13 @@ declare class AssetFileBuilder<T extends BaseContent = BaseContent> {
     private readonly httpClient;
     private readonly assetType;
     private readonly entryUid;
-    private readonly defaultLocale?;
-    constructor(httpClient: HttpClient, assetType: string, entryUid: string, defaultLocale?: string | undefined);
+    /** The client's locale, asked on every call rather than copied when this builder was taken. */
+    private readonly clientLocale;
+    /**
+     * @param locale - The client's locale, sent when a call names none: the function
+     *   `TypedRelyIOClient` hands over, or a locale fixed for this builder
+     */
+    constructor(httpClient: HttpClient, assetType: string, entryUid: string, locale?: ClientLocale);
     /**
      * The path parameters every `/file/*` route on this builder takes.
      *
@@ -1060,6 +1115,12 @@ declare class AssetFileBuilder<T extends BaseContent = BaseContent> {
      */
     private get target();
     private withLocale;
+    /**
+     * The `locale` body field of a multipart call: the session's, else the client's. The API finds
+     * the binding by it, so a session a `withLocale()` client opened must name the same locale on
+     * every later call or its `objectKey` is refused as another binding's.
+     */
+    private localeField;
     /**
      * Issue a single upload target — an R2 presigned PUT (image/file) or a
      * Cloudflare Stream direct-creator URL (video). Resumable multipart is plan 17.
@@ -1096,6 +1157,18 @@ declare class AssetFileBuilder<T extends BaseContent = BaseContent> {
      * Throws if the binding is not `ready`.
      */
     url(input?: ResolveUrlInput): Promise<ResolveUrlResult>;
+    /**
+     * Read where this file's upload got to — `status`, and the processing stage, progress and error
+     * the pipeline recorded — whatever the asset entry is published in.
+     *
+     * An asset is a draft until its file is ready, and stays one when its file fails, so a key that
+     * reads published content finds no entry for an upload in flight or one that failed. This read
+     * answers for the binding itself. It takes the capability the upload calls take, so a read-only
+     * key is refused with `ReadOnlyKeyError`, and it never returns the entry's fields.
+     */
+    status(options?: {
+        locale?: string;
+    }): Promise<FileStatusResult>;
     /**
      * Update the binding's delivery visibility (token-based; no byte relocation —
      * a downgrade purges the gateway cache). Returns the refreshed asset entry.
@@ -1123,8 +1196,23 @@ declare class AssetFileBuilder<T extends BaseContent = BaseContent> {
         locale?: string;
     }): Promise<void>;
     /**
-     * Poll the asset entry until its file binding reaches `ready` (resolves with
-     * the ready entry) or `failed` (throws). Times out after `timeoutMs`.
+     * Poll the asset entry until its file binding reaches `ready`, and resolve with the ready entry.
+     *
+     * Each poll reads the entry through the key's lens. When that finds nothing — a key that reads
+     * published content, and an asset that is a draft until its file is ready and stays one when it
+     * fails — the poll reads the binding itself ({@link status}), so a failed upload rejects as one
+     * rather than running out the limit (REL-1481).
+     *
+     * @throws {FileUploadError} When processing failed. `code` is the processing code the service
+     *   stored — `UNSUPPORTED_CODEC`, `CORRUPT_FILE` and so on — or `PROCESSING_FAILED` where it
+     *   stored none this SDK knows; `context.processingError` holds what it stored, and `retryable`
+     *   is its `retriable` hint.
+     * @throws {TimeoutError} When `timeoutMs` passes first. The file may still become ready; the
+     *   error's `context.timeout` is the limit and `context.fileStatus` the status last seen. A file
+     *   that is `ready` in an asset the key's lens never shows — created with `publish: false`, or
+     *   awaiting a workflow — ends here too, and the message says so.
+     * @throws {ReadOnlyKeyError} When the key's lens does not show the asset and the key may not read
+     *   its binding either: nothing it can read would ever report the file.
      */
     waitUntilReady(options?: WaitUntilReadyOptions): Promise<AssetEntryResponse<T>>;
 }
@@ -1139,7 +1227,6 @@ declare class AssetUploadBuilder<T extends BaseContent = BaseContent> {
     private readonly httpClient;
     private readonly assetType;
     private readonly file;
-    private readonly defaultLocale?;
     private _fileName?;
     private _visibility?;
     private _locale?;
@@ -1151,7 +1238,13 @@ declare class AssetUploadBuilder<T extends BaseContent = BaseContent> {
     private _onProgress?;
     private _validate?;
     private _maxPartRetries;
-    constructor(httpClient: HttpClient, assetType: string, file: Blob, defaultLocale?: string | undefined);
+    /** The client's locale, read once when the upload starts. */
+    private readonly clientLocale;
+    /**
+     * @param locale - The client's locale, the upload's when `.locale()` names none: the function
+     *   `TypedRelyIOClient` hands over, or a locale fixed for this upload
+     */
+    constructor(httpClient: HttpClient, assetType: string, file: Blob, locale?: ClientLocale);
     /** Subscribe to client → storage upload progress (single PUT + multipart). */
     onProgress(callback: (_progress: UploadProgress) => void): this;
     /**
@@ -1173,7 +1266,12 @@ declare class AssetUploadBuilder<T extends BaseContent = BaseContent> {
     content(content: Record<string, unknown>): this;
     /** Set an explicit slug for the new entry. */
     slug(slug: string): this;
-    /** Wait until the file binding becomes `ready` before resolving. */
+    /**
+     * Wait until the file binding becomes `ready` before resolving.
+     *
+     * @throws {Error} When `timeoutMs` or `pollIntervalMs` is one the wait cannot honour — refused
+     *   here, before anything is uploaded, rather than after the bytes are in.
+     */
     waitForReady(options?: boolean | Omit<WaitUntilReadyOptions, 'locale'>): this;
     /** Execute the full upload flow and resolve with the asset entry. */
     execute(): Promise<AssetEntryResponse<T>>;
@@ -1197,10 +1295,18 @@ declare class AssetUploadBuilder<T extends BaseContent = BaseContent> {
 declare class AssetClient<T extends BaseContent = BaseContent> {
     private readonly httpClient;
     private readonly assetType;
-    private readonly defaultLocale?;
-    constructor(httpClient: HttpClient, assetType: string, defaultLocale?: string | undefined);
-    /** Create a query builder for this asset type. */
-    query(): ContentQueryBuilder<AssetEntryResponse<T>>;
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    private readonly clientLocale;
+    /**
+     * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+     *   every call, or a locale fixed for this client
+     */
+    constructor(httpClient: HttpClient, assetType: string, locale?: ClientLocale);
+    /**
+     * Create a query builder for this asset type. It resolves asset reads; its conditions name the
+     * asset type's fields, which the `file` and `urls` blocks are not.
+     */
+    query(): ContentQueryBuilder<AssetEntryResponse<T>, T>;
     /** Find an asset entry by id (or slug) with fluent options. */
     findById(id: string): ContentByIdBuilder<AssetEntryResponse<T>>;
     /** Fetch a single asset entry by id (or slug), or `null` if not found. */
@@ -1209,14 +1315,18 @@ declare class AssetClient<T extends BaseContent = BaseContent> {
         locale?: string;
     }): Promise<AssetEntryResponse<T> | null>;
     /** Fetch the first asset entry matching the conditions, or `null`. */
-    fetchFirst(where?: WhereClause<AssetEntryResponse<T>>, locale?: string): Promise<AssetEntryResponse<T> | null>;
+    fetchFirst(where?: WhereClause<T>, locale?: string): Promise<AssetEntryResponse<T> | null>;
     /**
      * Create a new asset entry as a draft. The binary is uploaded separately via
      * `file(uid)` (or use the high-level `upload()` helper), and the entry
      * auto-publishes when its file becomes ready (unless `publish: false`).
+     * `locale` defaults to the client's own (`withLocale()`).
      */
     create(data: CreateInput<T>, options?: CreateAssetOptions & RetryableWriteOptions): Promise<AssetEntryResponse<T>>;
-    /** Update an asset entry's metadata fields (and/or slug). */
+    /**
+     * Update an asset entry's metadata fields (and/or slug). `locale` defaults to the client's own
+     * (`withLocale()`).
+     */
     update(id: string, data: UpdateInput<T>, options?: UpdateAssetOptions): Promise<AssetEntryResponse<T>>;
     /** Delete an asset entry (cascades file-byte cleanup + gateway purge). */
     delete(id: string, options?: ConditionalWriteOptions): Promise<void>;
@@ -1226,9 +1336,12 @@ declare class AssetClient<T extends BaseContent = BaseContent> {
     upload(file: Blob): AssetUploadBuilder<T>;
     /** Get the asset type id. */
     getAssetType(): string;
-    /** Get the current default locale. */
+    /** Get the default locale as it is now: the client's, or the one `withLocale()` fixed. */
     getDefaultLocale(): string | undefined;
-    /** Create a new AssetClient for this type with a different default locale. */
+    /**
+     * Create a new AssetClient for this type with a different default locale, fixed: an update of the
+     * client's locale (`updateConfig({ locale })`) does not reach it.
+     */
     withLocale(locale: string): AssetClient<T>;
 }
 /**
@@ -1258,13 +1371,21 @@ 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
  * Provides a fluent API for singleton operations following the same pattern as ContentClient
  *
- * A read is in the locale it names — `fetch({ locale })`, then `.locale()` — and otherwise in
- * `defaultLocale`, the client's own (`withLocale()`), as `content()`'s reads are.
+ * Every call is in the locale it names — the argument (`fetch({ locale })`, `update(data, locale)`,
+ * `versions({ locale })`), then `.locale()` — and otherwise in the client's own (`withLocale()`,
+ * `updateConfig({ locale })`) as it is when the call is made, as `content()`'s are: reads, the write,
+ * and version history alike.
  *
  * @example
  * ```typescript
@@ -1277,10 +1398,15 @@ interface SingletonFetchOptions {
 declare class SingletonClient<T = unknown> {
     private httpClient;
     private singletonKey;
-    private readonly defaultLocale?;
     private includeFields?;
     private localeValue?;
-    constructor(httpClient: HttpClient, singletonKey: string, defaultLocale?: string | undefined);
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    private readonly clientLocale;
+    /**
+     * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+     *   every call, or a locale fixed for this client
+     */
+    constructor(httpClient: HttpClient, singletonKey: string, locale?: ClientLocale);
     /**
      * Include reference fields in the response
      * @param fields - Reference field names to populate
@@ -1311,7 +1437,8 @@ declare class SingletonClient<T = unknown> {
      * Update singleton content. The API auto-publishes on PATCH — there is no
      * separate publish route; calling `update()` writes and publishes.
      * @param data - The content fields to update
-     * @param locale - Optional locale for localized content (overrides fluent locale)
+     * @param locale - Optional locale for localized content (overrides the fluent locale, which
+     *   overrides the client's own)
      * @param options - `If-Match` / `Idempotency-Key`, both declared on this route
      */
     update(data: Partial<T>, locale?: string, options?: ConditionalWriteOptions): Promise<T>;
@@ -1323,8 +1450,9 @@ declare class SingletonClient<T = unknown> {
      * Get version history for one locale of the singleton.
      *
      * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
-     * schema default, no fallback is applied, and a locale with no history returns an empty array
-     * rather than another locale's rows. Every row names the locale it belongs to.
+     * fluent `.locale()`, then the client's own (`withLocale()`), then the schema default; no
+     * fallback is applied, and a locale with no history returns an empty array rather than another
+     * locale's rows. Every row names the locale it belongs to.
      */
     versions(options?: {
         limit?: number;
@@ -1336,12 +1464,14 @@ declare class SingletonClient<T = unknown> {
     /**
      * Get a specific version of the singleton.
      *
-     * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
-     * different content in each one.
+     * `locale` defaults to the fluent `.locale()`, then the client's own (`withLocale()`), then the
+     * schema default. Version numbers are per locale, so version 2 is different content in each one.
      */
     version(versionNumber: number, options?: {
         locale?: string;
     }): Promise<T | null>;
+    /** The locale a write or history read sends: the call's, the fluent one, else the client's. */
+    private localeOf;
     /**
      * Get the singleton key
      */
@@ -1365,8 +1495,10 @@ interface SettingsFetchOptions {
  * Settings client for managing settings group operations
  * Provides a fluent API for settings operations following the same pattern as ContentClient
  *
- * A read is in the locale it names — `fetch({ locale })`, then `.locale()` — and otherwise in
- * `defaultLocale`, the client's own (`withLocale()`), as `content()`'s reads are.
+ * Every call is in the locale it names — the argument (`fetch({ locale })`, `update(settings,
+ * locale)`, `reset(locale)`, `versions({ locale })`), then `.locale()` — and otherwise in the
+ * client's own (`withLocale()`, `updateConfig({ locale })`) as it is when the call is made, as
+ * `content()`'s are: reads, writes and version history alike.
  *
  * @example
  * ```typescript
@@ -1379,10 +1511,15 @@ interface SettingsFetchOptions {
 declare class SettingsClient<T = unknown> {
     private readonly httpClient;
     private readonly groupId;
-    private readonly defaultLocale?;
     private includeFields?;
     private localeValue?;
-    constructor(httpClient: HttpClient, groupId: string, defaultLocale?: string | undefined);
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    private readonly clientLocale;
+    /**
+     * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+     *   every call, or a locale fixed for this client
+     */
+    constructor(httpClient: HttpClient, groupId: string, locale?: ClientLocale);
     /**
      * Include reference fields in the response
      * @param fields - Reference field names to populate
@@ -1400,8 +1537,13 @@ declare class SettingsClient<T = unknown> {
     fetch(options?: SettingsFetchOptions): Promise<T | null>;
     /**
      * Update settings group
+     *
+     * The fields travel as `content` beside an optional `locale`, the body the route validates
+     * (`UpdateSettingsDto`); any other top-level key is refused `REQUEST_INVALID`.
+     *
      * @param settings - The settings fields to update
-     * @param locale - Optional locale for localized settings (overrides fluent locale)
+     * @param locale - Optional locale for localized settings (overrides the fluent locale, which
+     *   overrides the client's own)
      */
     update(settings: Partial<T>, locale?: string, options?: ConditionalWriteOptions): Promise<T>;
     /**
@@ -1415,7 +1557,11 @@ declare class SettingsClient<T = unknown> {
     }>;
     /**
      * Reset settings to default values
-     * @param locale - Optional locale for localized settings
+     *
+     * The route reads its locale from `?locale=` and takes no body, so that is where it is sent.
+     *
+     * @param locale - Optional locale for localized settings (overrides the fluent locale, which
+     *   overrides the client's own)
      */
     reset(locale?: string, options?: ConditionalWriteOptions): Promise<T>;
     /**
@@ -1430,8 +1576,9 @@ declare class SettingsClient<T = unknown> {
      * Get version history for one locale of the settings group.
      *
      * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
-     * schema default, no fallback is applied, and a locale with no history returns an empty array
-     * rather than another locale's rows. Every row names the locale it belongs to.
+     * fluent `.locale()`, then the client's own (`withLocale()`), then the schema default; no
+     * fallback is applied, and a locale with no history returns an empty array rather than another
+     * locale's rows. Every row names the locale it belongs to.
      */
     versions(options?: {
         limit?: number;
@@ -1443,12 +1590,14 @@ declare class SettingsClient<T = unknown> {
     /**
      * Get a specific version of the settings.
      *
-     * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
-     * different content in each one.
+     * `locale` defaults to the fluent `.locale()`, then the client's own (`withLocale()`), then the
+     * schema default. Version numbers are per locale, so version 2 is different content in each one.
      */
     version(versionNumber: number, options?: {
         locale?: string;
     }): Promise<T | null>;
+    /** The locale a write or history read sends: the call's, the fluent one, else the client's. */
+    private localeOf;
     /**
      * Get the settings group ID
      */
@@ -1499,17 +1648,27 @@ type RegisteredSchema = Register extends {
  */
 type SearchMode = 'keyword' | 'semantic' | 'hybrid';
 /**
- * One search hit as the route emits it: the entry fields at the top level,
- * plus optional score annotations. There is no per-item `data` wrapper.
+ * What a search or similar hit reports beside its fields: the committed document's
+ * `SearchHitMetadata`, read through `http/api-schema.ts`.
+ *
+ * Narrower than an entry read's `EntryMetadata`, because a hit is not built by the entry read: it
+ * carries no `entryType`, `defaultLocale`, `availableLocales`, `refs`, `firstPublishedAt` or
+ * version history. Until REL-1413 a hit was typed as an entry and so promised all five — the
+ * locale helpers kept an optional chain after `availableLocales` for the hits that lacked it. Read
+ * the entry (`content(type).findById(hit._metadata.id)`) for those.
+ */
+type SearchHitMetadata = components['schemas']['SearchHitMetadata'];
+/** What a hit carries beside the entry's fields, as the document declares it. */
+type SearchHitSystemFields = Pick<components['schemas']['SearchHit'], '_metadata' | '_score' | '_scoreBreakdown' | '_highlights'>;
+/**
+ * One search hit as the route emits it — the document's `SearchHit`: the fields `T` declares at the
+ * top level (at `_metadata.locale`, or only the aliases a `fields` projection names), the hit's own
+ * `_metadata`, and the score annotations the request asked for. There is no per-item `data` wrapper.
+ *
+ * `T`'s `_metadata` is replaced, not kept: `T` is an entry type, and a hit is not an entry read.
+ * Distributes over a union of entry types, so a search across two types keeps each one's fields.
  */
-type SearchResultItem<T = unknown> = T & {
-    _score?: number;
-    _scoreBreakdown?: {
-        keyword?: number;
-        semantic?: number;
-    };
-    _highlights?: Record<string, string[]>;
-};
+type SearchResultItem<T = unknown> = T extends unknown ? Omit<T, '_metadata'> & SearchHitSystemFields : never;
 /**
  * Search response from API
  */
@@ -1529,20 +1688,12 @@ type SearchResultItem<T = unknown> = T & {
  */
 type SearchResponse<T = unknown> = Wire<'/v1/search', 'post', SearchResultItem<T>>;
 /**
- * Autocomplete suggestion
- */
-interface AutocompleteSuggestion {
-    /** Suggested text */
-    text: string;
-    /** Highlighted version */
-    highlighted?: string;
-    /** Score */
-    score?: number;
-    /** Source entry ID */
-    entryId?: string;
-    /** Content type */
-    contentType?: string;
-}
+ * One autocomplete suggestion — the document's `AutocompleteSuggestion`: the value, its best score,
+ * an entry holding it (`id`), and the value with its match wrapped in `<em>` when Atlas highlighted
+ * it. The hand-written type this replaces named `highlighted`, `entryId` and `contentType`, none of
+ * which the route sends, and made `score` optional where it is always sent.
+ */
+type AutocompleteSuggestion = components['schemas']['AutocompleteSuggestion'];
 /**
  * Autocomplete response
  */
@@ -1555,11 +1706,10 @@ interface AutocompleteSuggestion {
  */
 type AutocompleteResponse = Wire<'/v1/search/autocomplete', 'post', AutocompleteSuggestion>;
 /**
- * One similar-content hit as the route emits it — a flat entry, no `data` wrapper.
+ * One similar-content hit as the route emits it: the same `SearchHit` a search serves, built by
+ * the same transform, with `_score` on every hit.
  */
-type SimilarResult<T = unknown> = T & {
-    _score?: number;
-};
+type SimilarResult<T = unknown> = SearchResultItem<T>;
 /**
  * Similar response
  */
@@ -1610,19 +1760,28 @@ interface SearchSort {
  */
 declare class SearchBuilder<T extends BaseContent = BaseContent, S extends AnySchemaDefinition | undefined = undefined> {
     private readonly httpClient;
-    private readonly defaultLocale?;
     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;
     /**
-     * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+     * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when
+     *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
      */
-    constructor(httpClient: HttpClient, query: string, defaultLocale?: string | undefined);
+    constructor(httpClient: HttpClient, query: string, locale?: ClientLocale);
     /**
      * Headers this search adds to the client's own, e.g. `X-RelyIO-Dataset` to search another
      * 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.
@@ -1636,7 +1795,8 @@ declare class SearchBuilder<T extends BaseContent = BaseContent, S extends AnySc
      */
     across<K extends SearchTypeName<S>>(contentTypes: K[] | '*'): SearchBuilder<SearchEntry<S, K, T>, S>;
     /**
-     * Add filter conditions
+     * Add filter conditions, on the fields the content types declare. A condition on `_metadata` is
+     * refused here, before anything is sent.
      * @param conditions - Filter conditions
      */
     where(conditions: SearchFilter): this;
@@ -1708,13 +1868,15 @@ declare class SearchBuilder<T extends BaseContent = BaseContent, S extends AnySc
  */
 declare class AutocompleteBuilder {
     private readonly httpClient;
-    private readonly defaultLocale?;
     private query;
     private autocompleteOptions;
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    private readonly clientLocale;
     /**
-     * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+     * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when
+     *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
      */
-    constructor(httpClient: HttpClient, query: string, defaultLocale?: string | undefined);
+    constructor(httpClient: HttpClient, query: string, locale?: ClientLocale);
     /**
      * Autocomplete within a content type
      * @param contentType - Content type to search
@@ -1730,7 +1892,8 @@ declare class AutocompleteBuilder {
      */
     fuzzy(): this;
     /**
-     * Add filter conditions
+     * Add filter conditions, on the fields the content types declare. A condition on `_metadata` is
+     * refused here, before anything is sent.
      * @param conditions - Filter conditions
      */
     where(conditions: SearchFilter): this;
@@ -1767,14 +1930,16 @@ declare class AutocompleteBuilder {
  */
 declare class SimilarBuilder<T extends BaseContent = BaseContent> {
     private readonly httpClient;
-    private readonly defaultLocale?;
     private sourceId;
     private similarOptions;
     private requestHeaders?;
+    /** The client's locale, asked when the read is sent rather than copied when it was built. */
+    private readonly clientLocale;
     /**
-     * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+     * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when
+     *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
      */
-    constructor(httpClient: HttpClient, sourceId: string, defaultLocale?: string | undefined);
+    constructor(httpClient: HttpClient, sourceId: string, locale?: ClientLocale);
     /**
      * Headers this read adds to the client's own, e.g. `X-RelyIO-Dataset` to read another dataset
      * the key can see. A name the client already sends is replaced for this read only.
@@ -1790,11 +1955,6 @@ declare class SimilarBuilder<T extends BaseContent = BaseContent> {
      * @param contentTypes - Array of content types or '*' for all
      */
     across(contentTypes: string[] | '*'): this;
-    /**
-     * Add filter conditions
-     * @param conditions - Filter conditions
-     */
-    where(conditions: SearchFilter): this;
     /**
      * Limit number of results
      * @param count - Maximum results
@@ -1845,12 +2005,14 @@ declare class SimilarBuilder<T extends BaseContent = BaseContent> {
  */
 declare class SearchClient {
     private readonly httpClient;
-    private readonly defaultLocale?;
+    /** The client's locale, handed to every builder here to ask when it sends. */
+    private readonly clientLocale;
     /**
-     * @param defaultLocale - The client's locale (`withLocale()`): every builder here sends it when
-     *   the query names none, as `content()`'s reads do
+     * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`): every builder
+     *   here sends it when the query names none, as `content()`'s reads do — the function
+     *   `TypedRelyIOClient` hands over, or a locale fixed for this client
      */
-    constructor(httpClient: HttpClient, defaultLocale?: string | undefined);
+    constructor(httpClient: HttpClient, locale?: ClientLocale);
     /**
      * Start a search query
      * @param query - Search query string
@@ -1866,12 +2028,6 @@ declare class SearchClient {
      * @param sourceId - Entry ID to find similar content for
      */
     similar<T extends BaseContent = BaseContent>(sourceId: string): SimilarBuilder<T>;
-    /**
-     * Quick search helper - searches all content types
-     * @param query - Search query
-     * @param limit - Max results (default 20)
-     */
-    global<T extends BaseContent = BaseContent>(query: string, limit?: number): Promise<SearchResponse<T>>;
 }
 
 /**
@@ -1900,7 +2056,10 @@ interface BatchOptions {
      *
      * Requires that all operations be the same kind of write — one transaction cannot span two
      * calls — so a batch mixing creates and deletes, or `update` and `replace`, is rejected with
-     * a 400 before anything is attempted.
+     * a 400 before anything is attempted: `execute()` rejects with `InvalidPayloadError`. A
+     * singleton write is a create when the dataset has never written that singleton and an update
+     * after, and an atomic batch cannot create one — that operation reports `REQUEST_INVALID` and
+     * every other `TRANSACTION_ROLLED_BACK` — so create it in a request of its own first.
      *
      * @default false
      */
@@ -1958,16 +2117,33 @@ type BatchResponse = components['schemas']['MultiPayload'];
 /**
  * Fluent builder for batch operations
  *
+ * Every create, update, replace and singleton operation it builds is in the locale that operation
+ * names, and otherwise in the client's own (`withLocale()`), sent as that operation's
+ * `body.locale` — a batch is one request, but the API reads a locale per operation. A delete names
+ * none (it removes the whole entry), and a `raw()` operation is sent exactly as written.
+ *
+ * An atomic batch — `.atomic()` or `execute({ atomic: true })` — is one transaction: every
+ * operation lands or none does. The API accepts one only when every operation is the same kind of
+ * write and none writes a singleton that does not exist yet (see {@link BatchOptions.atomic}).
+ *
  * @example
  * ```typescript
+ * // Each operation lands or fails on its own
  * const result = await relyio.batch()
  *   .create('product', { content: { title: 'iPhone', price: 999 } })
  *   .update('product', 'entry_abc', { content: { price: 899 } })
  *   .delete('product', 'entry_xyz')
  *   .upsertSingleton('homepage', { content: { hero: 'Welcome!' } })
- *   .execute({ atomic: true })
+ *   .execute()
+ *
+ * console.log(result.summary.succeeded)
  *
- * console.log(result.summary.succeeded) // 4
+ * // All or nothing: one kind of write
+ * await relyio.batch()
+ *   .create('product', { content: { title: 'iPhone', price: 999 } })
+ *   .create('product', { content: { title: 'iPad', price: 799 } })
+ *   .atomic()
+ *   .execute()
  * ```
  */
 declare class BatchBuilder<TSchema = unknown> {
@@ -1975,7 +2151,19 @@ declare class BatchBuilder<TSchema = unknown> {
     private operations;
     private defaultOptions;
     private requestHeaders;
-    constructor(httpClient: HttpClient);
+    /** The client's locale, asked as each operation is added rather than copied when this was built. */
+    private readonly clientLocale;
+    /**
+     * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), each
+     *   operation's when it names none: the function `TypedRelyIOClient` hands over, or a locale fixed
+     *   for this batch
+     */
+    constructor(httpClient: HttpClient, locale?: ClientLocale);
+    /**
+     * An operation's body with its locale: the one it names, else the client's as it is when the
+     * operation is added.
+     */
+    private localized;
     /**
      * Add a create operation
      * @param contentType - Content type to create
@@ -2053,7 +2241,8 @@ declare class BatchBuilder<TSchema = unknown> {
         locale?: string;
     }, id?: string): this;
     /**
-     * Add a raw operation (for advanced use cases)
+     * Add a raw operation (for advanced use cases). It is sent exactly as written: the client's
+     * locale is not added to it.
      * @param operation - The operation to add
      */
     raw(operation: BatchOperation): this;
@@ -2170,9 +2359,15 @@ declare class BatchBuilder<TSchema = unknown> {
  */
 declare class BatchClient<TSchema = unknown> {
     private readonly httpClient;
-    constructor(httpClient: HttpClient);
+    /** The client's locale, handed to every batch this builds to ask as operations are added. */
+    private readonly clientLocale;
+    /**
+     * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, or a locale
+     *   fixed for this client
+     */
+    constructor(httpClient: HttpClient, locale?: ClientLocale);
     /**
-     * Create a new batch builder
+     * Create a new batch builder, whose operations default to this client's locale
      */
     create(): BatchBuilder<TSchema>;
     /**
@@ -2251,13 +2446,14 @@ interface AggregateBlock {
 }
 /**
  * One metric, as the Query DSL writes it: `<field>.<fn>`, where `fn` is `count`, `sum`, `avg`,
- * `min` or `max` — `'id.count'`, `'pricing.basePrice.avg'`. The service validates every metric
- * against that form (`INVALID_AGGREGATION_EXPRESSION`); `count` ignores the field it names.
+ * `min`, `max`, `first` or `last` — `'id.count'`, `'pricing.basePrice.avg'`. The service
+ * validates every metric against that form (`INVALID_AGGREGATION_EXPRESSION`); `count` ignores the
+ * field it names. `first` and `last` were missing here while the service ran them (REL-1470).
  *
  * It used to be `{ fn, field? }`, a shape the service refuses on every request: the validator
  * tests the metric as a string, so an object arrives as `[object Object]`.
  */
-type AggregateMetric = `${string}.${'count' | 'sum' | 'avg' | 'min' | 'max'}`;
+type AggregateMetric = `${string}.${'count' | 'sum' | 'avg' | 'min' | 'max' | 'first' | 'last'}`;
 /**
  * Search block for full-text/semantic search
  */
@@ -2276,36 +2472,11 @@ interface SearchBlock {
     limit?: number;
 }
 /**
- * Similar block for vector similarity search
+ * One post-fetch filter: a parameter expression, or the operators every query clause compares with
+ * (`FilterOperator`, REL-1479). This kept a copy of eleven, without `exists` or `notExists`; and a
+ * bare number or boolean, which it took, the service does not read as a filter.
  */
-interface SimilarBlock {
-    /** Content type */
-    contentType: string;
-    /** Source entry ID */
-    source: string;
-    /** Minimum similarity threshold */
-    threshold?: number;
-    /** Additional filters */
-    where?: Record<string, unknown>;
-    /** Maximum results */
-    limit?: number;
-}
-/**
- * Post-fetch filters with parameter support
- */
-type FilterValue = string | number | boolean | {
-    eq?: unknown;
-    ne?: unknown;
-    gt?: unknown;
-    gte?: unknown;
-    lt?: unknown;
-    lte?: unknown;
-    in?: unknown[];
-    nin?: unknown[];
-    contains?: unknown;
-    startsWith?: string;
-    endsWith?: string;
-};
+type FilterValue = string | FilterOperator;
 /**
  * Full-text search configuration
  */
@@ -2327,8 +2498,6 @@ interface AdhocQueryDefinition {
     aggregate?: AggregateBlock;
     /** Search block - full-text/semantic search */
     search?: SearchBlock;
-    /** Similar block - vector similarity */
-    similar?: SimilarBlock;
     /** Field selection/transformation */
     select?: Record<string, string>;
     /** Post-fetch filters with parameter support */
@@ -2416,15 +2585,17 @@ interface AdhocQueryResult<T = unknown> {
  */
 declare class AdhocQueryBuilder<T = unknown> {
     private readonly httpClient;
-    private readonly defaultLocale?;
     private queryDef;
     private parameters;
     private options;
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    private readonly clientLocale;
     /**
-     * @param defaultLocale - The client's locale (`withLocale()`), sent as the `locale` parameter
-     *   when `.param('locale', …)` binds none
+     * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent as the
+     *   `locale` parameter when `.param('locale', …)` binds none: the function `TypedRelyIOClient`
+     *   hands over, or a locale fixed for this builder
      */
-    constructor(httpClient: HttpClient, defaultLocale?: string | undefined);
+    constructor(httpClient: HttpClient, locale?: ClientLocale);
     /**
      * Add a fetch block to retrieve content
      * @param config - Fetch configuration
@@ -2450,11 +2621,6 @@ declare class AdhocQueryBuilder<T = unknown> {
      * @param config - Search configuration
      */
     search(config: SearchBlock): this;
-    /**
-     * Add similar block
-     * @param config - Similar configuration
-     */
-    similar(config: SimilarBlock): this;
     /**
      * Add where conditions to fetch
      * @param conditions - Filter conditions
@@ -2583,12 +2749,14 @@ declare class AdhocQueryBuilder<T = unknown> {
  */
 declare class AdhocQueryClient {
     private readonly httpClient;
-    private readonly defaultLocale?;
+    /** The client's locale, asked on every query rather than copied when this client was taken. */
+    private readonly clientLocale;
     /**
-     * @param defaultLocale - The client's locale (`withLocale()`), sent as the `locale` parameter of
-     *   every query that binds none
+     * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent as the
+     *   `locale` parameter of every query that binds none: the function `TypedRelyIOClient` hands
+     *   over, or a locale fixed for this client
      */
-    constructor(httpClient: HttpClient, defaultLocale?: string | undefined);
+    constructor(httpClient: HttpClient, locale?: ClientLocale);
     /**
      * Create a new query builder
      */
@@ -2697,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
@@ -2707,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 {
     /**
@@ -2746,7 +2956,8 @@ interface ChangesOptions {
      * - a function — resync, and call it with the error once the new position is
      *   taken and before any change after it is yielded. This is the observable
      *   form: whatever the consumer derived from the feed may be stale, so the
-     *   function is where it invalidates everything. The iterator waits for it.
+     *   function is where it invalidates everything — naming the error's `fresh`,
+     *   the new position, on every refetch. The iterator waits for it.
      */
     onExpired?: 'throw' | 'resync' | ((expired: ChangesExpiredError) => void | Promise<void>);
 }
@@ -2755,6 +2966,81 @@ interface ChangesHeadOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * `relyio.liveChanges()` — a dataset's published changes at RelyIO's live edge, for a publishable key
+ * (`live-layer-spec.md` decision 20; LV5.2, REL-1158).
+ *
+ * The wire is `@relyio/api-contract`'s `live-visitor.ts`, read from there and never restated: the
+ * path and query names, the frames and their reader, the keepalive, the poll's answer and its reader,
+ * the poll interval, and what each close code and each refused poll means a client does next.
+ *
+ * **One open, two ways in.** A subscription opens a WebSocket to the edge. Where it cannot — the
+ * runtime has no `WebSocket` (Node 18 and 20), constructing one throws, or the socket fails before it
+ * opens (a network that blocks sockets) — it polls the edge instead, from the same cursor, about
+ * every {@link VISITOR_POLL_INTERVAL_MS}, and tries a socket again about once a minute. Both carry
+ * one cursor space, so a switch either way loses nothing.
+ *
+ * **It ends only when its signal aborts, and throws every other end** — a socket closed by a refusal
+ * or a deploy, a refused poll, a keepalive nobody answered — as a `LiveEdgeError` saying what to do
+ * next, so `followChanges()` reconnects, backs off or stops by the edge's own tables. That loop is
+ * the one reconnect policy (`INV-SS-ONE-CORE`, REL-1215); this module keeps no back-off of its own.
+ *
+ * **Cursors.** The edge sends one cursor after a batch of changes. The last change of a batch carries
+ * it; each earlier one carries the position before the batch, so a failure part-way through a batch
+ * replays the whole batch rather than skipping its rest. Delivery is at-least-once: a replay and the
+ * live frames after it may name one change twice, and a refetch makes a repeat cost a read, never a
+ * wrong view (`INV-SS-CHANGE-IS-IDS`).
+ *
+ * **What a refetch names.** Every change of a batch carries the batch's own cursor as `fresh`
+ * (`FeedChange`), the position its refetch names as `?_fresh` — not `cursor`, which for an earlier
+ * change is the position before the batch: the previous batch's refetches were answered under that
+ * one, before this batch, and a cache would hand the same answer back. A `feed.resync`'s error
+ * carries the cursor it sent the same way.
+ */
+
+/**
+ * How often an open socket sends the keepalive, which the edge's runtime answers without waking the
+ * feed — the Studio's dataset room sends its own on the same interval. A socket that has heard
+ * nothing by the next one, not even the answer, is presumed dead and reconnected: a client that only
+ * receives never learns otherwise that a network change dropped its connection.
+ */
+declare const LIVE_KEEPALIVE_INTERVAL_MS = 30000;
+interface LiveChangesOptions {
+    /**
+     * A change's cursor from an earlier subscription. Omitted, the edge answers the dataset's current
+     * position first and replays nothing; fetch what you show **after** that position arrives — with
+     * `followChanges()`, after `onState` reports `following` — so nothing lands in between unseen.
+     */
+    since?: string;
+    /** Content types to keep. Omitted keeps every type; an empty list is refused. At most 50. */
+    types?: readonly string[];
+    /** Entry ids to keep. Omitted keeps every entry; an empty list is refused. At most 100. */
+    ids?: readonly string[];
+    /**
+     * Ends the subscription. An abort — while connected, while polling, or between polls — makes the
+     * `for await` **complete**, with the socket closed, no further request and nothing thrown.
+     */
+    signal?: AbortSignal;
+    /**
+     * What to do when the edge says to refetch everything (`feed.resync`: the cursor is too old, was
+     * never this dataset's, or the dataset was replaced) — as `relyio.changes()` takes it: `'throw'`
+     * (default) throws a `ChangesExpiredError`, `'resync'` carries on from the edge's position, and a
+     * function is awaited with the error before any change after that position is yielded.
+     */
+    onExpired?: ChangesOptions['onExpired'];
+    /**
+     * Called when the edge has the subscription in hand — its `feed.opened` frame, or an answered
+     * poll. `followChanges()` passes it to reset its back-off; see `ChangeSourceOptions.opened`.
+     */
+    opened?: () => void;
+    /**
+     * Called with a position reached without a change to carry it. `followChanges()` passes it so a
+     * connection dropped before its first change reconnects from there; see
+     * `ChangeSourceOptions.reached`.
+     */
+    reached?: (cursor: string) => void;
+}
+
 /**
  * The key's project, as `GET /v1/project` describes it: organization, project, dataset and branch,
  * each by id and name, and `studioUrl` — the Studio root the preview toolbar deep-links from
@@ -2797,13 +3083,27 @@ interface TypedClientConfig<TSchema extends AnySchemaDefinition | undefined = un
  * ```
  */
 declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined = undefined> {
-    private httpClient;
+    /**
+     * The one HTTP client every sub-client sends through. `updateConfig()` and `setApiKey()` change it
+     * in place rather than replacing it, so a sub-client taken before either sends through the change.
+     */
+    private readonly httpClient;
     private config;
+    /**
+     * The configuration as `createClient()`, `setApiKey()` and `updateConfig()` gave it, before the
+     * `relyio dev` handshake: what the next update is laid over, and what `withLocale()` starts from.
+     */
+    private configured;
     private _sandbox;
-    private _search;
-    private _batch;
-    private _adhocQuery;
     private _schema;
+    /**
+     * The client's locale as it is when a call is made. Every sub-client and builder is handed this
+     * rather than a copy of the locale, so one taken before `updateConfig({ locale })` sends the new
+     * 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
@@ -2825,7 +3125,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      */
     get sandbox(): SandboxState;
     /**
-     * Get the ad-hoc query client
+     * Get the ad-hoc query client. Every query it sends is in the client's locale as it is then.
      */
     get query(): AdhocQueryClient;
     /**
@@ -2932,7 +3232,11 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      */
     similar<T extends BaseContent = BaseContent>(sourceId: string): SimilarBuilder<T>;
     /**
-     * Start a batch operation for bulk create/update/delete
+     * Start a batch operation for bulk create/update/delete.
+     *
+     * By default each operation lands or fails on its own. `atomic: true` makes the batch one
+     * transaction, which the API accepts only when every operation is the same kind of write and none
+     * writes a singleton that does not exist yet.
      *
      * @example
      * ```typescript
@@ -2941,12 +3245,20 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .update('product', 'entry_abc', { content: { price: 899 } })
      *   .delete('product', 'entry_xyz')
      *   .upsertSingleton('homepage', { content: { hero: 'Welcome!' } })
-     *   .execute({ atomic: true })
+     *   .execute()
      *
      * console.log(result.summary.succeeded)
+     *
+     * // All or nothing: one kind of write
+     * await relyio.batch()
+     *   .update('product', 'entry_abc', { content: { price: 899 } })
+     *   .update('product', 'entry_def', { content: { price: 799 } })
+     *   .execute({ atomic: true })
      * ```
      */
     batch(): BatchBuilder<NonNullable<TSchema>>;
+    /** The search client, whose builders send the client's locale as it is when each one is sent. */
+    private searchClient;
     /**
      * Follow the dataset's changes feed: each write this key can see, as ids, in
      * order, long-polled from `GET /v1/changes`.
@@ -2954,13 +3266,15 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * Lazy — nothing is requested until the first `next()`. It runs until
      * `signal` aborts, which ends the `for await` cleanly rather than throwing.
      * A change names what changed; refetch it through the ordinary read path
-     * (`INV-SS-CHANGE-IS-IDS`).
+     * (`INV-SS-CHANGE-IS-IDS`), naming its `fresh` so no cache answers with the
+     * body from before it (`FeedChange`).
      *
      * @example
      * ```typescript
      * const controller = new AbortController()
      * for await (const change of relyio.changes({ since: cursor, types: ['post'], signal: controller.signal })) {
-     *   // { entryId, contentType, locale, kind, cursor }
+     *   // { entryId, contentType, locale, kind, cursor, fresh }
+     *   await relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute()
      * }
      * ```
      *
@@ -2968,11 +3282,42 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```typescript
      * for await (const change of relyio.changes({
      *   since: cursor,
-     *   onExpired: async () => invalidateEverything(),
+     *   onExpired: async expired => refetchEverything(expired.fresh),
      * })) { … }
      * ```
      */
-    changes(options?: ChangesOptions): AsyncIterable<Change>;
+    changes(options?: ChangesOptions): AsyncIterable<FeedChange>;
+    /**
+     * Follow the dataset's **published** changes at RelyIO's live edge, with a publishable key
+     * (`rly_pub_…`): each change as ids, in order — the transport a browser follows changes with.
+     *
+     * A WebSocket to the edge, from `since` or the dataset's current position; where a socket cannot
+     * open — the runtime has none, or the network refuses it — it polls the edge instead, about every
+     * fifteen seconds, from the same cursor. The edge is `liveUrl`, or derived from the default
+     * `baseUrl` (see `RelyIOConfig.liveUrl`).
+     *
+     * One subscription ends only when `signal` aborts, which ends the `for await` cleanly; every other
+     * end — a socket a deploy dropped, a refusal, a refused poll — is thrown as a `LiveEdgeError`
+     * that says whether to stop, retry or back off. Hand it to `followChanges()`, the one loop that
+     * reconnects from the last cursor with jittered back-off and honours those answers:
+     *
+     * @example
+     * ```typescript
+     * const relyio = createClient({ apiKey: 'rly_pub_…' })
+     * const controller = new AbortController()
+     * await followChanges(from => relyio.liveChanges({ ...from, types: ['post'] }), {
+     *   signal: controller.signal,
+     *   // `fresh` names a position no cache holds a body for from before the change.
+     *   onChange: change =>
+     *     relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute(),
+     *   onResync: resync => refetchEverything(resync.cause === 'expired' ? resync.expired.fresh : undefined),
+     * })
+     * ```
+     *
+     * A client without a publishable key sends nothing: a secret or preview key is never put in the
+     * edge's URL. On a server, follow `changes()` with it instead.
+     */
+    liveChanges(options?: LiveChangesOptions): AsyncIterable<FeedChange>;
     /**
      * The dataset's current position in the changes feed, as a cursor to start
      * `changes({ since })` or `followChanges(…, { since })` from. One
@@ -3065,15 +3410,73 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      */
     testConnection(): Promise<boolean>;
     /**
-     * Update the configuration and reinitialize all clients
+     * Change some of the client's options and keep the rest.
+     *
+     * What you pass is laid over the configuration the client holds, field by field:
+     *
+     * - an option you name replaces the value the client holds;
+     * - an option left out, or given as `undefined`, keeps the value the client holds;
+     * - an option with no default given as `null` is cleared — `locale`, `dataset`, `apiKey`, `dev`,
+     *   `fetch`, `browser.onCorsError`, `realtime.wsUrl`, `debug.logger` — so the client runs as though
+     *   it had never been given one. An option with a default takes no `null`;
+     * - a bag of options you name — `browser`, `cache`, `realtime`, `debug` — keeps every field of it
+     *   you do not name, so `updateConfig({ browser: { includeCredentials: true } })` keeps a
+     *   configured `onCorsError`;
+     * - `headers` is laid over the headers the client sends, a name matched without regard to case: a
+     *   header you name is added or replaces every spelling of it, every other one is still sent, and a
+     *   header given as `null` is no longer sent;
+     * - naming `apiKey` — a key, or `null` — replaces every key the client holds, one given in
+     *   `headers` included.
+     *
+     * The configuration it is laid over is what `createClient()`, `setApiKey()` and earlier updates
+     * gave the client. The `relyio dev` handshake is read again, as `createClient()` reads it: while a
+     * sandbox is active its key and dataset are sent over the configured ones, and once it has gone
+     * the configured ones are.
+     *
+     * The client's one HTTP client is changed in place, so every request from now on is sent as the
+     * update says — including one from a `content()`, `asset()`, `singleton()` or `settings()`
+     * sub-client, a `query` client, or a builder such as `search()` or `batch()`, taken before the
+     * call. The locale reaches them too: each reads the client's locale when it sends, so a new
+     * `locale` is the default of its next request and `locale: null` leaves that request with none. A
+     * locale the call names, and a sub-client's own `withLocale()`, still win over it. A client made
+     * by `withLocale()` is a client of its own: an update of this one does not reach it.
+     *
+     * @example
+     * ```typescript
+     * const relyio = createClient({ apiKey, headers: { 'X-Tenant': 'acme' }, browser: { onCorsError } })
+     *
+     * relyio.updateConfig({ headers: { 'X-Trace': traceId } }) // X-Tenant is still sent
+     * relyio.updateConfig({ browser: { includeCredentials: true } }) // onCorsError is kept
+     * relyio.updateConfig({ headers: { 'X-Tenant': null } }) // X-Tenant is no longer sent
+     * relyio.updateConfig({ locale: null }) // reads name no locale of the client's
+     * ```
      */
-    updateConfig(newConfig: Partial<RelyIOConfig>): void;
+    updateConfig(update: RelyIOConfigUpdate): void;
     /**
      * Get the current configuration
      */
     getConfig(): Readonly<MergedRelyIOConfig>;
     /**
-     * Set the API key
+     * Replace the API key every later request sends as `X-API-Key`.
+     *
+     * It reaches every request this client makes from now on, including those of a `content()`,
+     * `asset()` or other sub-client taken before the call, and `getConfig().apiKey` reports it. A key
+     * given in `headers`, under any spelling, is replaced with it and does not come back on a later
+     * `updateConfig()`. A client already derived with `withLocale()` is a client of its own and keeps
+     * its key.
+     *
+     * An empty or blank key is no key, as it is when passed to `createClient`: the next request
+     * rejects with `MissingApiKeyError` and nothing is sent.
+     *
+     * Under an active `relyio dev` sandbox the sandbox's scoped key stands, as it does over the key
+     * passed to `createClient` — replacing the configured key does not retarget the client at the
+     * sandbox's dataset with a key the sandbox did not issue.
+     *
+     * @example
+     * ```typescript
+     * const relyio = createClient({ apiKey: process.env.RELYIO_API_KEY! })
+     * relyio.setApiKey(rotatedKey) // the next read sends `X-API-Key: <rotatedKey>`
+     * ```
      */
     setApiKey(apiKey: string): void;
     /**
@@ -3083,9 +3486,12 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
     /**
      * Create a locale-scoped client
      *
-     * Every read the returned client builds — `content()`, `asset()`, `singleton()`, `settings()`,
-     * `search()`, `similar()`, `autocomplete()`, `executeQuery()` and the ad-hoc queries — is in this
-     * locale unless the call names one of its own, which wins.
+     * Every call the returned client builds is in this locale unless the call names one of its own,
+     * which wins: every read — `content()`, `asset()`, `singleton()`, `settings()`, `search()`,
+     * `similar()`, `autocomplete()`, `executeQuery()` and the ad-hoc queries — and every write and
+     * version-history read — `create()` and `update()`, the singleton and settings writes, the asset
+     * file writes, `versions()` and `version()`, and each operation `batch()` builds. `restore()`
+     * always names its locale; a delete, and a `batch().raw()` operation, carry none of the client's.
      *
      * Type-safe when schema is provided: autocompletes valid locale codes!
      *
@@ -3093,10 +3499,11 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```typescript
      * const spanish = relyio.withLocale('es-ES')  // ← Autocompletes with schema!
      *
-     * // Reads use Spanish
+     * // Reads and writes use Spanish
      * const products = await spanish.content('product').query().execute()
      * const homepage = await spanish.singleton('homepage').fetch()
      * const results = await spanish.search('zapatos').execute()
+     * await spanish.content('product').update(id, { title: 'Zapatos' })
      *
      * // Original client unchanged
      * const englishProducts = await relyio.content('product').query().execute()
@@ -3192,4 +3599,4 @@ declare function createClient<TSchema extends AnySchemaDefinition>(config: Typed
  */
 type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
 
-export { AdhocQueryBuilder as $, type ActiveSandbox as A, type SearchResponse as B, ChangesExpiredError as C, type AutocompleteSuggestion as D, type ExtendedQueryResult as E, type AutocompleteResponse as F, type SimilarResult as G, HttpClient as H, type SimilarResponse as I, type SearchFilter as J, type SearchFields as K, type SearchSort as L, type SearchTypeName as M, type SearchEntry as N, BatchClient as O, type Project as P, BatchBuilder as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type BatchMethod as U, type BatchOperation as V, type BatchOptions as W, type BatchOperationResult as X, type BatchSummary as Y, type BatchResponse as Z, AdhocQueryClient as _, type Change as a, type FetchBlock as a0, type AggregateBlock as a1, type AggregateMetric as a2, type SearchBlock as a3, type SimilarBlock as a4, type FilterValue as a5, type FullTextConfig as a6, type AdhocQueryDefinition as a7, type AdhocQueryOptions as a8, type QueryMetadata as a9, ResourceConflictError as aA, ResourceExpiredError as aB, isResourceNotFound as aC, type FileErrorCode as aD, FileUploadError as aE, FileValidationError as aF, type FileValidationConstraints as aG, validateFile as aH, 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 AssetUrls as ak, type AssetEntryResponse as al, type PopulatedAssetReference as am, type PresignInput as an, type PresignResult as ao, type ConfirmInput as ap, type ConfirmResult as aq, type ResolveUrlInput as ar, type ResolveUrlResult as as, type CreateAssetOptions as at, type WaitUntilReadyOptions as au, type MultipartCreateResult as av, type MultipartPart as aw, type MultipartTarget as ax, type UploadProgress as ay, ResourceNotFoundError as az, type ChangesExpiredReason as b, createClient as c, type TypedClientConfig as d, type ClientSchema as e, type RegisteredSchema as f, type SendOptions as g, entityTagOf as h, type ConditionalWriteOptions as i, type RetryableWriteOptions as j, type ChangesHeadOptions as k, type ChangesOptions as l, ContentClient as m, SingletonClient as n, SettingsClient as o, ContentQueryBuilder as p, ContentByIdBuilder as q, type ChildrenOptions as r, type SingletonFetchOptions as s, type SettingsFetchOptions as t, SearchClient as u, SearchBuilder as v, AutocompleteBuilder as w, SimilarBuilder as x, type SearchMode as y, type SearchResultItem as z };
+export { type BatchOperationResult as $, type ActiveSandbox as A, type SearchResultItem as B, type Change as C, type SearchHitMetadata as D, type ExtendedQueryResult as E, type FeedChange as F, type SearchResponse as G, HttpClient as H, type AutocompleteSuggestion as I, type AutocompleteResponse as J, type SimilarResult as K, LIVE_KEEPALIVE_INTERVAL_MS as L, type SimilarResponse as M, type SearchFilter as N, type SearchFields as O, type Project as P, type SearchSort as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type SearchTypeName as U, type SearchEntry as V, BatchClient as W, BatchBuilder as X, type BatchMethod as Y, type BatchOperation as Z, type BatchOptions as _, ChangesExpiredError as a, type BatchSummary as a0, type BatchResponse as a1, AdhocQueryClient as a2, AdhocQueryBuilder as a3, type FetchBlock as a4, type AggregateBlock as a5, type AggregateMetric as a6, type SearchBlock as a7, type FilterValue as a8, type FullTextConfig as a9, type MultipartPart as aA, type MultipartTarget as aB, type UploadProgress as aC, ResourceNotFoundError as aD, ResourceConflictError as aE, ResourceExpiredError as aF, isResourceNotFound as aG, type FileErrorCode as aH, type FileUploadErrorCode as aI, FileUploadError as aJ, FileValidationError as aK, type FileValidationConstraints as aL, validateFile as aM, type AdhocQueryDefinition as aa, type AdhocQueryOptions as ab, type QueryMetadata as ac, type AdhocQueryResult as ad, AssetClient as ae, AssetFileBuilder as af, AssetUploadBuilder as ag, isAssetEntry as ah, type AssetVisibility as ai, type FileStatus as aj, type FileBackend as ak, type AssetFileBlock as al, type AssetFileExtracted as am, type FileStatusResult as an, type AssetUrls as ao, type AssetEntryResponse as ap, type PopulatedAssetReference as aq, type PresignInput as ar, type PresignResult as as, type ConfirmInput as at, type ConfirmResult as au, type ResolveUrlInput as av, type ResolveUrlResult as aw, type CreateAssetOptions as ax, type WaitUntilReadyOptions as ay, type MultipartCreateResult as az, type ChangesExpiredReason as b, createClient as c, type TypedClientConfig as d, type ClientSchema as e, type RegisteredSchema as f, type SendOptions as g, entityTagOf as h, type ConditionalWriteOptions as i, type RetryableWriteOptions as j, type ChangesHeadOptions as k, type ChangesOptions as l, type LiveChangesOptions as m, ContentClient as n, SingletonClient as o, SettingsClient as p, ContentQueryBuilder as q, ContentByIdBuilder as r, type ChildrenOptions as s, type SingletonFetchOptions as t, type SettingsFetchOptions as u, SearchClient as v, SearchBuilder as w, AutocompleteBuilder as x, SimilarBuilder as y, type SearchMode as z };