@relyio/sdk 0.5.0 → 0.7.0

package/dist/{index-BozPz4n1.d.cts → index-M0X45k7J.d.cts}

@@ -1,6 +1,6 @@
-import { J as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, K as PathParamsOf, t as ApiResponse, W as Wire, s as RequestConfig, B as BaseContent, d as WhereClause, f as SortOptions, g as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, x as BaseValidationError, w as ValidationViolation, N as components, O as paths, R as RelyIOConfig } from './index-C5mRBb6t.cjs';
-import { a as SchemaDefinition, b as SchemaContentTypeNames, h as SchemaAssetTypeNames, M as InferAssetType, c as SchemaSingletonNames, t as InferSingleton, g as SchemaSettingsGroupNames, E as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-2xbHgtK-.cjs';
-import { J as InferContentType } from './define-content-type-CBfnTWSS.cjs';
+import { H as MergedRelyIOConfig, A as ApiPath, b as ApiMethod, J as PathParamsOf, v as ApiResponse, W as Wire, u as RequestConfig, B as BaseContent, g as WhereClause, Q as QueryOptions, i as SortOptions, j as ContentQueryResult, C as CreateInput, U as UpdateInput, S as SDKError, z as BaseValidationError, y as ValidationViolation, R as RelyIOConfig, a as RelyIOConfigUpdate } from './index-DbsTUw3Q.cjs';
+import { aK as components, aJ as paths, W as InferContentType, aa as InferAssetType, a3 as InferSingleton } from './define-content-type-DiVpbwNs.cjs';
+import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, ay as FilterOperator, h as SchemaAssetTypeNames, c as SchemaSingletonNames, g as SchemaSettingsGroupNames, I as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-D7MButVt.cjs';
 import { DevUnreadableReason } from './dev-handshake/index.cjs';
 
 /**
@@ -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,7 +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) — and so does one whose `setApiKey` was
+     * given none.
      */
     request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
     /**
@@ -153,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
      */
@@ -184,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;
     /**
@@ -196,11 +233,21 @@ declare class HttpClient {
     private mergeRequestConfig;
     private buildQueryString;
     private headersToObject;
-    /** A backoff the caller's abort cuts short; the next attempt then refuses to send. */
-    private sleep;
     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
  */
@@ -240,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?;
@@ -252,15 +298,29 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent> {
     private childrenOptions?;
     private pageNumber?;
     private pageSizeValue?;
-    constructor(httpClient: HttpClient, contentType: string, defaultLocale?: string | undefined);
+    private requestHeaders?;
+    /** 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
+     * is not changed.
+     */
+    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
      */
@@ -278,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
      */
@@ -407,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.
      *
@@ -448,13 +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?;
-    constructor(httpClient: HttpClient, contentType: string, id: string, defaultLocale?: string | undefined);
+    private requestHeaders?;
+    /** 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
      */
@@ -471,6 +537,12 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
      * @param localeCodes - Array of locale codes to fetch
      */
     locales(localeCodes: string[]): this;
+    /**
+     * Headers this one 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 request only; the client
+     * is not changed.
+     */
+    headers(headers: Record<string, string>): this;
     /**
      * Fetch content in all available locales
      * Returns default locale at top level, others in _metadata.localizations
@@ -597,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
      */
@@ -619,11 +696,13 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
     /**
      * Fetch a single content item by ID
      * @param id - Entry ID or slug
-     * @param options - Fetch options (include, locale)
+     * @param options - Fetch options (include, locale, and `headers` this one request adds — e.g.
+     *   `{ 'X-RelyIO-Dataset': 'staging' }` to read a dataset other than the client's)
      */
     fetchOne(id: string, options?: {
         include?: string[];
         locale?: string;
+        headers?: Record<string, string>;
     }): Promise<T | null>;
     /**
      * Fetch one entry **and the entity tag that read served**.
@@ -637,10 +716,16 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
      * `entityTag` is `undefined` when the response came from the cache: a cached
      * body cannot know the current version, and an absent tag beats a stale one
      * that would refuse the next write.
+     *
+     * Unlike {@link fetchOne}, a missing entry is not `null`: the service's
+     * `RESOURCE_NOT_FOUND` is thrown as it arrived, with the `kind` that says
+     * whether the entry, the content type or the schema was missing. `headers`
+     * are the ones this read adds, as for `fetchOne`.
      */
     fetchOneWithTag(id: string, options?: {
         include?: string[];
         locale?: string;
+        headers?: Record<string, string>;
     }): Promise<{
         entry: T;
         entityTag?: string;
@@ -654,25 +739,33 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
     /**
      * Create a new content item
      * @param data - Content data
-     * @param options - Create options (slug, locale, parentId, sortOrder)
+     * @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. `locale` defaults to the client's own (`withLocale()`).
      */
     create(data: CreateInput<T>, options?: {
         slug?: string;
         locale?: string;
         parentId?: string;
         sortOrder?: number;
+        headers?: Record<string, string>;
     } & RetryableWriteOptions): Promise<T>;
     /**
      * Update a content item by ID (partial update)
      * @param id - Entry ID
      * @param data - Fields to update
-     * @param options - Update options (slug, locale, parentId, sortOrder)
+     * @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. `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;
         locale?: string;
         parentId?: string;
         sortOrder?: number;
+        headers?: Record<string, string>;
     } & ConditionalWriteOptions): Promise<T>;
     /**
      * Delete a content item by ID
@@ -686,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;
@@ -699,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;
@@ -737,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;
 }
@@ -752,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.
+ */
+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 = 'UPLOAD_TOO_LARGE' | 'UNSUPPORTED_MIME' | 'DIMENSION_OUT_OF_RANGE' | 'ASPECT_RATIO' | 'CORRUPT_FILE' | 'UNSUPPORTED_CODEC' | 'IMAGES_LIMIT_EXCEEDED' | 'STREAM_ENCODE_FAILED' | 'SCAN_INFECTED' | 'INTERNAL';
+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;
 }
@@ -804,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
@@ -1003,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;
 }
 /**
@@ -1016,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.
      *
@@ -1027,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.
@@ -1063,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.
@@ -1090,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>>;
 }
@@ -1106,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?;
@@ -1118,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;
     /**
@@ -1140,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>>;
@@ -1164,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. */
@@ -1176,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>;
@@ -1193,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>;
 }
 /**
@@ -1230,6 +1357,11 @@ interface SingletonFetchOptions {
  * Singleton client for managing singleton content operations
  * Provides a fluent API for singleton operations following the same pattern as ContentClient
  *
+ * 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
  * const homepage = await client.singleton('homepage')
@@ -1243,7 +1375,13 @@ declare class SingletonClient<T = unknown> {
     private singletonKey;
     private includeFields?;
     private localeValue?;
-    constructor(httpClient: HttpClient, singletonKey: string);
+    /** 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
@@ -1274,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>;
@@ -1286,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;
@@ -1299,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
      */
@@ -1328,6 +1470,11 @@ interface SettingsFetchOptions {
  * Settings client for managing settings group operations
  * Provides a fluent API for settings operations following the same pattern as ContentClient
  *
+ * 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
  * const emailConfig = await client.settings('email-config')
@@ -1341,7 +1488,13 @@ declare class SettingsClient<T = unknown> {
     private readonly groupId;
     private includeFields?;
     private localeValue?;
-    constructor(httpClient: HttpClient, groupId: string);
+    /** 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
@@ -1359,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>;
     /**
@@ -1374,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>;
     /**
@@ -1389,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;
@@ -1402,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
      */
@@ -1418,22 +1583,67 @@ declare class SettingsClient<T = unknown> {
     resetOptions(): this;
 }
 
+/**
+ * Any schema the client can be typed by. `any` is deliberate: the client accepts whatever content
+ * types, components, singletons, queries and settings groups a customer declares.
+ *
+ * This is the constraint `TypedRelyIOClient`'s `TSchema` carries, so `RegisteredSchema` is inferred
+ * against the same one — `createClient` returns `TypedRelyIOClient<RegisteredSchema>`, and a schema
+ * inferred against any wider alias would not be provably inside the client's bound.
+ */
+type AnySchemaDefinition = SchemaDefinition<any, any, any, any, any>;
+/**
+ * The seam `relyio generate-types` fills (`INV-SS-TYPES-INFERRED`).
+ *
+ * Empty here on purpose. The generated `schema.ts` augments it —
+ *
+ * ```ts
+ * declare module '@relyio/sdk' {
+ *   interface Register {
+ *     schema: typeof schema
+ *   }
+ * }
+ * ```
+ *
+ * — and from then on `createClient({ apiKey })`, with no generic and no `schema:`, is typed by that
+ * schema. The pattern is TanStack Router's. It is type-level only: nothing at runtime reads it.
+ */
+interface Register {
+}
+/**
+ * The schema the project registered through `Register`, or `undefined` when nothing did — which is
+ * the untyped client, exactly as before the generator ran.
+ */
+type RegisteredSchema = Register extends {
+    schema: infer S extends AnySchemaDefinition;
+} ? S : undefined;
+
 /**
  * Search mode for content queries
  */
 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
  */
@@ -1453,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
  */
@@ -1479,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
  */
@@ -1493,12 +1694,31 @@ type SimilarResponse<T = unknown> = Wire<'/v1/search/similar', 'post', SimilarRe
  * Filter conditions for search
  */
 type SearchFilter = Record<string, unknown>;
+/**
+ * The content type names a search may be scoped to: the schema's where one types the client, any
+ * name where none does.
+ */
+type SearchTypeName<S extends AnySchemaDefinition | undefined> = S extends AnySchemaDefinition ? SchemaContentTypeNames<S> : string;
+/**
+ * What a search over the content types `K` returns: their entries, typed by the schema
+ * (`INV-SS-TYPES-INFERRED`) — or `T` unchanged where no schema types the client.
+ */
+type SearchEntry<S extends AnySchemaDefinition | undefined, K extends SearchTypeName<S> = SearchTypeName<S>, T extends BaseContent = BaseContent> = S extends AnySchemaDefinition ? SchemaEntryOf<S, K & SchemaContentTypeNames<S>> : T;
 /**
  * Field projection for search results
  */
 type SearchFields<T> = {
     [K: string]: keyof T | string;
 };
+/**
+ * One ordering of `POST /v1/search`'s results, as the route's `sort` array takes it.
+ */
+interface SearchSort {
+    /** Field path, or `_score` for relevance */
+    field: string;
+    /** Direction; the route's default is `desc` */
+    direction: 'asc' | 'desc';
+}
 /**
  * Fluent builder for search queries
  *
@@ -1513,23 +1733,38 @@ type SearchFields<T> = {
  *   .execute()
  * ```
  */
-declare class SearchBuilder<T extends BaseContent = BaseContent> {
+declare class SearchBuilder<T extends BaseContent = BaseContent, S extends AnySchemaDefinition | undefined = undefined> {
     private readonly httpClient;
     private query;
     private searchOptions;
-    constructor(httpClient: HttpClient, query: string);
+    private requestHeaders?;
+    /** 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
+     *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
+     */
+    constructor(httpClient: HttpClient, query: string, locale?: ClientLocale);
     /**
-     * Search within a single content type
+     * 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;
+    /**
+     * 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.
      * @param contentType - Content type to search in
      */
-    in<K extends string>(contentType: K): SearchBuilder<T>;
+    in<K extends SearchTypeName<S>>(contentType: K): SearchBuilder<SearchEntry<S, K, T>, S>;
     /**
-     * Search across multiple content types
+     * Search across multiple content types. Where a schema types the client, the names are its content
+     * types and the results are a union of their entries — every type's, for `'*'`.
      * @param contentTypes - Array of content types or '*' for all
      */
-    across(contentTypes: string[] | '*'): SearchBuilder<T>;
+    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;
@@ -1543,6 +1778,13 @@ declare class SearchBuilder<T extends BaseContent = BaseContent> {
      * @param projection - Field mapping
      */
     fields(projection: Record<string, string>): this;
+    /**
+     * Order the results by a field instead of by relevance. Called again, it adds a tie-breaker.
+     * `_score` names relevance itself.
+     * @param field - Field path to sort by (e.g. `updatedAt`, `pricing.basePrice`)
+     * @param direction - `asc` or `desc` (the route's default is `desc`)
+     */
+    sort(field: string, direction?: 'asc' | 'desc'): this;
     /**
      * Limit number of results
      * @param count - Maximum results
@@ -1596,7 +1838,13 @@ declare class AutocompleteBuilder {
     private readonly httpClient;
     private query;
     private autocompleteOptions;
-    constructor(httpClient: HttpClient, query: string);
+    /** 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
+     *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
+     */
+    constructor(httpClient: HttpClient, query: string, locale?: ClientLocale);
     /**
      * Autocomplete within a content type
      * @param contentType - Content type to search
@@ -1612,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;
@@ -1651,17 +1900,29 @@ declare class SimilarBuilder<T extends BaseContent = BaseContent> {
     private readonly httpClient;
     private sourceId;
     private similarOptions;
-    constructor(httpClient: HttpClient, sourceId: string);
+    private requestHeaders?;
+    /** 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
+     *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
+     */
+    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.
+     */
+    headers(headers: Record<string, string>): this;
     /**
      * Find similar content within a content type
      * @param contentType - Content type to search
      */
     in(contentType: string): this;
     /**
-     * Add filter conditions
-     * @param conditions - Filter conditions
+     * Find similar content across several content types, or `'*'` for every type
+     * @param contentTypes - Array of content types or '*' for all
      */
-    where(conditions: SearchFilter): this;
+    across(contentTypes: string[] | '*'): this;
     /**
      * Limit number of results
      * @param count - Maximum results
@@ -1712,12 +1973,19 @@ declare class SimilarBuilder<T extends BaseContent = BaseContent> {
  */
 declare class SearchClient {
     private readonly httpClient;
-    constructor(httpClient: HttpClient);
+    /** The client's locale, handed to every builder here to ask when it sends. */
+    private readonly clientLocale;
+    /**
+     * @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, locale?: ClientLocale);
     /**
      * Start a search query
      * @param query - Search query string
      */
-    search<T extends BaseContent = BaseContent>(query: string): SearchBuilder<T>;
+    search<T extends BaseContent = BaseContent, S extends AnySchemaDefinition | undefined = undefined>(query: string): SearchBuilder<T, S>;
     /**
      * Start an autocomplete query
      * @param query - Partial query to autocomplete
@@ -1728,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>>;
 }
 
 /**
@@ -1762,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
      */
@@ -1820,23 +2085,53 @@ 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> {
     private readonly httpClient;
     private operations;
     private defaultOptions;
-    constructor(httpClient: HttpClient);
+    private requestHeaders;
+    /** 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
@@ -1914,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;
@@ -1973,6 +2269,12 @@ declare class BatchBuilder<TSchema = unknown> {
      * Stop on first error (non-atomic mode)
      */
     stopOnError(): this;
+    /**
+     * Headers the batch request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset
+     * other than the client's. They replace the client's own header of the same name for this
+     * request alone, and apply to every operation in it: a batch is one request.
+     */
+    headers(headers: Record<string, string>): this;
     /**
      * Get the current list of operations
      */
@@ -2025,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;
+    /**
+     * @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>;
     /**
@@ -2093,20 +2401,27 @@ interface FetchBlock {
 interface AggregateBlock {
     /** Source content type or query reference */
     source: string;
+    /**
+     * Filter conditions applied before grouping, in the Query DSL's spelling — bare operator names
+     * (`{ price: { gte: 10 } }`), not the list route's `$gte`. A `$`-prefixed key is not an operator
+     * in this dialect: the service reads the object as a nested field and drops it.
+     */
+    where?: Record<string, unknown>;
     /** Field to group by */
     by?: string | string[];
-    /** Metrics to compute */
+    /** Metrics to compute, keyed by the name each one answers under */
     metrics: Record<string, AggregateMetric>;
 }
 /**
- * Aggregate metric definition
+ * One metric, as the Query DSL writes it: `<field>.<fn>`, where `fn` is `count`, `sum`, `avg`,
+ * `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]`.
  */
-interface AggregateMetric {
-    /** Aggregation function */
-    fn: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'first' | 'last';
-    /** Field to aggregate (optional for count) */
-    field?: string;
-}
+type AggregateMetric = `${string}.${'count' | 'sum' | 'avg' | 'min' | 'max' | 'first' | 'last'}`;
 /**
  * Search block for full-text/semantic search
  */
@@ -2125,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
  */
@@ -2176,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 */
@@ -2268,7 +2556,14 @@ declare class AdhocQueryBuilder<T = unknown> {
     private queryDef;
     private parameters;
     private options;
-    constructor(httpClient: HttpClient);
+    /** 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 as the
+     *   `locale` parameter when `.param('locale', …)` binds none: the function `TypedRelyIOClient`
+     *   hands over, or a locale fixed for this builder
+     */
+    constructor(httpClient: HttpClient, locale?: ClientLocale);
     /**
      * Add a fetch block to retrieve content
      * @param config - Fetch configuration
@@ -2294,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
@@ -2427,7 +2717,14 @@ declare class AdhocQueryBuilder<T = unknown> {
  */
 declare class AdhocQueryClient {
     private readonly httpClient;
-    constructor(httpClient: HttpClient);
+    /** The client's locale, asked on every query rather than copied when this client was taken. */
+    private readonly clientLocale;
+    /**
+     * @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, locale?: ClientLocale);
     /**
      * Create a new query builder
      */
@@ -2437,8 +2734,13 @@ declare class AdhocQueryClient {
      * @param definition - Query definition
      * @param parameters - Parameter values
      * @param options - Execution options
+     * @param request - `headers` this one request adds to the client's own, e.g. `X-RelyIO-Dataset`
+     *   to query another dataset the key can see. A name the client already sends is replaced for
+     *   this request only.
      */
-    execute<T = unknown>(definition: AdhocQueryDefinition, parameters?: Record<string, unknown>, options?: AdhocQueryOptions): Promise<AdhocQueryResult<T>>;
+    execute<T = unknown>(definition: AdhocQueryDefinition, parameters?: Record<string, unknown>, options?: AdhocQueryOptions, request?: {
+        headers?: Record<string, string>;
+    }): Promise<AdhocQueryResult<T>>;
     /**
      * Quick fetch helper
      * @param contentType - Content type
@@ -2584,41 +2886,10 @@ interface ChangesOptions {
      */
     onExpired?: 'throw' | 'resync' | ((expired: ChangesExpiredError) => void | Promise<void>);
 }
-
-/**
- * Any schema the client can be typed by. `any` is deliberate: the client accepts whatever content
- * types, components, singletons, queries and settings groups a customer declares.
- *
- * This is the constraint `TypedRelyIOClient`'s `TSchema` carries, so `RegisteredSchema` is inferred
- * against the same one — `createClient` returns `TypedRelyIOClient<RegisteredSchema>`, and a schema
- * inferred against any wider alias would not be provably inside the client's bound.
- */
-type AnySchemaDefinition = SchemaDefinition<any, any, any, any, any>;
-/**
- * The seam `relyio generate-types` fills (`INV-SS-TYPES-INFERRED`).
- *
- * Empty here on purpose. The generated `schema.ts` augments it —
- *
- * ```ts
- * declare module '@relyio/sdk' {
- *   interface Register {
- *     schema: typeof schema
- *   }
- * }
- * ```
- *
- * — and from then on `createClient({ apiKey })`, with no generic and no `schema:`, is typed by that
- * schema. The pattern is TanStack Router's. It is type-level only: nothing at runtime reads it.
- */
-interface Register {
+interface ChangesHeadOptions {
+    /** Cancels the request; the promise then rejects. */
+    signal?: AbortSignal;
 }
-/**
- * The schema the project registered through `Register`, or `undefined` when nothing did — which is
- * the untyped client, exactly as before the generator ran.
- */
-type RegisteredSchema = Register extends {
-    schema: infer S extends AnySchemaDefinition;
-} ? S : undefined;
 
 /**
  * The key's project, as `GET /v1/project` describes it: organization, project, dataset and branch,
@@ -2662,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
@@ -2690,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;
     /**
@@ -2707,7 +2990,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .execute()
      * ```
      */
-    content<K extends TSchema extends AnySchemaDefinition ? SchemaContentTypeNames<TSchema> : string>(contentType: K): TSchema extends AnySchemaDefinition ? ContentClient<InferContentType<TSchema['contentTypes'][K & keyof TSchema['contentTypes']]>> : ContentClient<BaseContent>;
+    content<K extends TSchema extends AnySchemaDefinition ? SchemaContentTypeNames<TSchema> : string>(contentType: K): TSchema extends AnySchemaDefinition ? ContentClient<InferContentType<TSchema['contentTypes'][K & keyof TSchema['contentTypes']], TSchema>> : ContentClient<BaseContent>;
     /**
      * Get an asset client for a specific asset type.
      *
@@ -2726,7 +3009,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * const heroUrl = await relyio.asset('productPhoto').file(photo._metadata.id).url({ variantId: 'hero' })
      * ```
      */
-    asset<K extends TSchema extends AnySchemaDefinition ? SchemaAssetTypeNames<TSchema> : string>(assetType: K): TSchema extends AnySchemaDefinition ? AssetClient<InferAssetType<NonNullable<TSchema['assetTypes']>[K & keyof NonNullable<TSchema['assetTypes']>]>> : AssetClient<BaseContent>;
+    asset<K extends TSchema extends AnySchemaDefinition ? SchemaAssetTypeNames<TSchema> : string>(assetType: K): TSchema extends AnySchemaDefinition ? AssetClient<InferAssetType<NonNullable<TSchema['assetTypes']>[K & keyof NonNullable<TSchema['assetTypes']>], TSchema>> : AssetClient<BaseContent>;
     /**
      * Get a singleton client for a specific singleton key
      * Type-safe when schema is provided: autocompletes singleton names AND field names
@@ -2739,7 +3022,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .fetch()
      * ```
      */
-    singleton<K extends TSchema extends AnySchemaDefinition ? SchemaSingletonNames<TSchema> : string>(key: K): TSchema extends AnySchemaDefinition ? SingletonClient<InferSingleton<TSchema['singletonContentTypes'][K & keyof TSchema['singletonContentTypes']]>> : SingletonClient<unknown>;
+    singleton<K extends TSchema extends AnySchemaDefinition ? SchemaSingletonNames<TSchema> : string>(key: K): TSchema extends AnySchemaDefinition ? SingletonClient<InferSingleton<TSchema['singletonContentTypes'][K & keyof TSchema['singletonContentTypes']], TSchema>> : SingletonClient<unknown>;
     /**
      * Get a settings client for a specific settings group
      * Type-safe when schema is provided: autocompletes settings group names AND field names
@@ -2751,9 +3034,12 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .fetch()
      * ```
      */
-    settings<K extends TSchema extends AnySchemaDefinition ? SchemaSettingsGroupNames<TSchema> : string>(groupId: K): TSchema extends AnySchemaDefinition ? SettingsClient<InferSettingsGroup<NonNullable<TSchema['settingsGroups']>[K & keyof NonNullable<TSchema['settingsGroups']>]>> : SettingsClient<unknown>;
+    settings<K extends TSchema extends AnySchemaDefinition ? SchemaSettingsGroupNames<TSchema> : string>(groupId: K): TSchema extends AnySchemaDefinition ? SettingsClient<InferSettingsGroup<NonNullable<TSchema['settingsGroups']>[K & keyof NonNullable<TSchema['settingsGroups']>], TSchema>> : SettingsClient<unknown>;
     /**
-     * Start a search query with full-text, semantic, or hybrid search
+     * Start a search query with full-text, semantic, or hybrid search.
+     *
+     * Where a schema types the client, the results are its entries — every content type's until
+     * `in()` or `across()` narrows them (`INV-SS-TYPES-INFERRED`).
      *
      * @example
      * ```typescript
@@ -2765,7 +3051,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .execute()
      * ```
      */
-    search<T extends BaseContent = BaseContent>(query: string): SearchBuilder<T>;
+    search<T extends BaseContent = SearchEntry<TSchema>>(query: string): SearchBuilder<T, TSchema>;
     /**
      * Start an autocomplete query for search suggestions
      *
@@ -2794,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
@@ -2803,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`.
@@ -2835,6 +3133,23 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```
      */
     changes(options?: ChangesOptions): AsyncIterable<Change>;
+    /**
+     * The dataset's current position in the changes feed, as a cursor to start
+     * `changes({ since })` or `followChanges(…, { since })` from. One
+     * `GET /v1/changes` without a cursor: answered at once, holding nothing.
+     *
+     * Take it **before** you read what you will follow. A write your read did not
+     * see is then after the position and replayed; opening the feed afterwards
+     * without a `since` starts after it and misses it.
+     *
+     * @example
+     * ```typescript
+     * const since = await relyio.changesHead()
+     * const post = await relyio.content('post').findById(id).execute()
+     * for await (const change of relyio.changes({ since, ids: [id] })) { … }
+     * ```
+     */
+    changesHead(options?: ChangesHeadOptions): Promise<string>;
     /**
      * Build and execute an ad-hoc query dynamically
      *
@@ -2910,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;
     /**
@@ -2927,7 +3300,13 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
     getHttpClient(): HttpClient;
     /**
      * Create a locale-scoped client
-     * All content operations on the returned client will use the specified locale
+     *
+     * 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!
      *
@@ -2935,9 +3314,11 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```typescript
      * const spanish = relyio.withLocale('es-ES')  // ← Autocompletes with schema!
      *
-     * // All operations 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()
@@ -3033,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 { type SearchBlock as $, type ActiveSandbox as A, type AutocompleteSuggestion as B, type Change as C, type AutocompleteResponse as D, type ExtendedQueryResult as E, type SimilarResult as F, type SimilarResponse as G, HttpClient as H, type SearchFilter as I, type SearchFields as J, BatchClient as K, BatchBuilder as L, type BatchMethod as M, type BatchOperation as N, type BatchOptions as O, type Project as P, type BatchOperationResult as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type BatchSummary as U, type BatchResponse as V, AdhocQueryClient as W, AdhocQueryBuilder as X, type FetchBlock as Y, type AggregateBlock as Z, type AggregateMetric as _, type TypedClientConfig as a, type SimilarBlock as a0, type FilterValue as a1, type FullTextConfig as a2, type AdhocQueryDefinition as a3, type AdhocQueryOptions as a4, type QueryMetadata as a5, type AdhocQueryResult as a6, AssetClient as a7, AssetFileBuilder as a8, AssetUploadBuilder as a9, FileUploadError as aA, FileValidationError as aB, type FileValidationConstraints as aC, validateFile as aD, isAssetEntry as aa, type AssetVisibility as ab, type FileStatus as ac, type FileBackend as ad, type AssetFileBlock as ae, type AssetFileExtracted as af, type AssetUrls as ag, type AssetEntryResponse as ah, type PopulatedAssetReference as ai, type PresignInput as aj, type PresignResult as ak, type ConfirmInput as al, type ConfirmResult as am, type ResolveUrlInput as an, type ResolveUrlResult as ao, type CreateAssetOptions as ap, type WaitUntilReadyOptions as aq, type MultipartCreateResult as ar, type MultipartPart as as, type MultipartTarget as at, type UploadProgress as au, ResourceNotFoundError as av, ResourceConflictError as aw, ResourceExpiredError as ax, isResourceNotFound as ay, type FileErrorCode as az, type ClientSchema as b, createClient as c, type RegisteredSchema as d, type SendOptions as e, entityTagOf as f, type ConditionalWriteOptions as g, type RetryableWriteOptions as h, ChangesExpiredError as i, type ChangesOptions as j, type ChangesExpiredReason as k, ContentClient as l, SingletonClient as m, SettingsClient as n, ContentQueryBuilder as o, ContentByIdBuilder as p, type ChildrenOptions as q, type SingletonFetchOptions as r, type SettingsFetchOptions as s, SearchClient as t, SearchBuilder as u, AutocompleteBuilder as v, SimilarBuilder as w, type SearchMode as x, type SearchResultItem as y, type SearchResponse 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 };