@relyio/sdk 0.6.0 → 0.7.0

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

@@ -1,6 +1,6 @@
-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 { H as MergedRelyIOConfig, A as ApiPath, b as ApiMethod, J as PathParamsOf, v as ApiResponse, W as Wire, u as RequestConfig, B as BaseContent, g as WhereClause, Q as QueryOptions, i as SortOptions, j as ContentQueryResult, C as CreateInput, U as UpdateInput, S as SDKError, z as BaseValidationError, y as ValidationViolation, R as RelyIOConfig, a as RelyIOConfigUpdate } from './index-BOQIHnsh.js';
+import { aK as components, aJ as paths, W as InferContentType, aa as InferAssetType, a3 as InferSingleton } from './define-content-type-DiVpbwNs.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-C-5an28C.js';
 import { DevUnreadableReason } from './dev-handshake/index.js';
 
 /**
@@ -99,14 +99,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 +136,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 +170,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 +216,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 +236,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 +287,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 +299,13 @@ 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;
+    /**
+     * @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);
     /**
      * 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 +313,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 +338,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 +467,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 +508,19 @@ 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;
+    /**
+     * @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);
     /**
      * Include related content in the response
      */
@@ -615,8 +669,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 +742,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 +757,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 +779,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 +793,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 +831,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 +847,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 +918,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 +1064,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 +1080,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 +1096,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 +1138,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 +1177,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 +1208,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 +1219,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 +1247,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 +1276,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 +1296,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 +1317,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>;
 }
 /**
@@ -1263,8 +1357,10 @@ interface SingletonFetchOptions {
  * 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 +1373,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 +1412,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 +1425,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 +1439,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 +1470,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 +1486,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 +1512,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 +1532,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 +1551,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 +1565,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 +1623,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 SearchResultItem<T = unknown> = T & {
-    _score?: number;
-    _scoreBreakdown?: {
-        keyword?: number;
-        semantic?: number;
-    };
-    _highlights?: Record<string, string[]>;
-};
+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 extends unknown ? Omit<T, '_metadata'> & SearchHitSystemFields : never;
 /**
  * Search response from API
  */
@@ -1529,20 +1663,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 +1681,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,14 +1735,16 @@ 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?;
+    /** 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.
@@ -1636,7 +1763,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 +1836,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 +1860,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 +1898,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 +1923,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 +1973,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 +1996,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 +2024,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 +2085,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) // 4
+ * console.log(result.summary.succeeded)
+ *
+ * // 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 +2119,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 +2209,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 +2327,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;
     /**
-     * Create a new batch builder
+     * @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, whose operations default to this client's locale
      */
     create(): BatchBuilder<TSchema>;
     /**
@@ -2251,13 +2414,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 +2440,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 +2466,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 +2553,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 +2589,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 +2717,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
      */
@@ -2797,13 +2933,25 @@ 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;
     constructor(config: TypedClientConfig<TSchema>);
     /**
      * Get the schema definition
@@ -2825,7 +2973,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 +3080,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 +3093,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`.
@@ -3065,15 +3225,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 +3301,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 +3314,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 +3414,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 { AdhocQueryClient as $, type ActiveSandbox as A, type SearchHitMetadata as B, ChangesExpiredError as C, type SearchResponse as D, type ExtendedQueryResult as E, type AutocompleteSuggestion as F, type AutocompleteResponse as G, HttpClient as H, type SimilarResult as I, type SimilarResponse as J, type SearchFilter as K, type SearchFields as L, type SearchSort as M, type SearchTypeName as N, type SearchEntry as O, type Project as P, BatchClient as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, BatchBuilder as U, type BatchMethod as V, type BatchOperation as W, type BatchOptions as X, type BatchOperationResult as Y, type BatchSummary as Z, type BatchResponse as _, type Change as a, AdhocQueryBuilder as a0, type FetchBlock as a1, type AggregateBlock as a2, type AggregateMetric as a3, type SearchBlock as a4, type FilterValue as a5, type FullTextConfig as a6, type AdhocQueryDefinition as a7, type AdhocQueryOptions as a8, type QueryMetadata as a9, ResourceNotFoundError as aA, ResourceConflictError as aB, ResourceExpiredError as aC, isResourceNotFound as aD, type FileErrorCode as aE, type FileUploadErrorCode as aF, FileUploadError as aG, FileValidationError as aH, type FileValidationConstraints as aI, validateFile as aJ, type AdhocQueryResult as aa, AssetClient as ab, AssetFileBuilder as ac, AssetUploadBuilder as ad, isAssetEntry as ae, type AssetVisibility as af, type FileStatus as ag, type FileBackend as ah, type AssetFileBlock as ai, type AssetFileExtracted as aj, type FileStatusResult as ak, type AssetUrls as al, type AssetEntryResponse as am, type PopulatedAssetReference as an, type PresignInput as ao, type PresignResult as ap, type ConfirmInput as aq, type ConfirmResult as ar, type ResolveUrlInput as as, type ResolveUrlResult as at, type CreateAssetOptions as au, type WaitUntilReadyOptions as av, type MultipartCreateResult as aw, type MultipartPart as ax, type MultipartTarget as ay, type UploadProgress as az, type ChangesExpiredReason as b, createClient as c, type TypedClientConfig as d, type ClientSchema as e, type RegisteredSchema as f, type SendOptions as g, entityTagOf as h, type ConditionalWriteOptions as i, type RetryableWriteOptions as j, type ChangesHeadOptions as k, type ChangesOptions as l, ContentClient as m, SingletonClient as n, SettingsClient as o, ContentQueryBuilder as p, ContentByIdBuilder as q, type ChildrenOptions as r, type SingletonFetchOptions as s, type SettingsFetchOptions as t, SearchClient as u, SearchBuilder as v, AutocompleteBuilder as w, SimilarBuilder as x, type SearchMode as y, type SearchResultItem as z };