@relyio/sdk 0.6.0 → 0.7.0

package/dist/{chunk-GCMQUM6N.cjs → chunk-VH2DE7HZ.cjs}

@@ -1,6 +1,7 @@
 'use strict';
 
 var chunkLSRPMNPT_cjs = require('./chunk-LSRPMNPT.cjs');
+var chunkTZL374LS_cjs = require('./chunk-TZL374LS.cjs');
 var chunkMWMSFIWN_cjs = require('./chunk-MWMSFIWN.cjs');
 
 /* RelyIO SDK - Built with ❤️ by the RelyIO Team */
@@ -232,18 +233,6 @@ chunkMWMSFIWN_cjs.__name(_UnknownContractError, "UnknownContractError");
 var UnknownContractError = _UnknownContractError;
 
 // src/errors/auth-errors.ts
-var _AuthenticationError = class _AuthenticationError extends SDKError {
-  constructor(message = "Authentication failed", statusCode = 401, cause, context) {
-    super(message, statusCode, cause, context);
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "AUTHENTICATION_ERROR");
-    chunkMWMSFIWN_cjs.__publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "Authentication failed. Please check your API key and try again.";
-  }
-};
-chunkMWMSFIWN_cjs.__name(_AuthenticationError, "AuthenticationError");
-var AuthenticationError = _AuthenticationError;
 var _AuthorizationError = class _AuthorizationError extends SDKError {
   constructor(message = "Authorization failed", statusCode = 403, cause, context) {
     super(message, statusCode, cause, context);
@@ -422,58 +411,6 @@ var _InvalidPayloadError = class _InvalidPayloadError extends BaseValidationErro
 };
 chunkMWMSFIWN_cjs.__name(_InvalidPayloadError, "InvalidPayloadError");
 var InvalidPayloadError = _InvalidPayloadError;
-var _SchemaValidationError = class _SchemaValidationError extends BaseValidationError {
-  constructor(message = "Schema validation failed", violations = [], cause) {
-    super(message, violations, 400, cause);
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "SCHEMA_VALIDATION_ERROR");
-  }
-  getUserMessage() {
-    return "The data does not match the expected schema. Please check your content structure.";
-  }
-};
-chunkMWMSFIWN_cjs.__name(_SchemaValidationError, "SchemaValidationError");
-var SchemaValidationError = _SchemaValidationError;
-var _RequiredFieldError = class _RequiredFieldError extends BaseValidationError {
-  constructor(fieldName, message, cause) {
-    const violation = {
-      field: fieldName,
-      message: message ?? `Field "${fieldName}" is required`,
-      code: "REQUIRED"
-    };
-    super(`Required field "${fieldName}" is missing`, [violation], 400, cause);
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "REQUIRED_FIELD_ERROR");
-  }
-  getUserMessage() {
-    const violation = this.violations[0];
-    const fieldName = violation?.field;
-    return `The field "${fieldName}" is required and cannot be empty.`;
-  }
-};
-chunkMWMSFIWN_cjs.__name(_RequiredFieldError, "RequiredFieldError");
-var RequiredFieldError = _RequiredFieldError;
-var _InvalidFieldTypeError = class _InvalidFieldTypeError extends BaseValidationError {
-  constructor(fieldName, expectedType, actualType, value, cause) {
-    const violation = {
-      field: fieldName,
-      message: `Expected ${expectedType}, got ${actualType}`,
-      code: "INVALID_TYPE",
-      value
-    };
-    super(
-      `Invalid type for field "${fieldName}": expected ${expectedType}, got ${actualType}`,
-      [violation],
-      400,
-      cause
-    );
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "INVALID_FIELD_TYPE");
-  }
-  getUserMessage() {
-    const violation = this.violations[0];
-    return `The field "${violation?.field}" has an invalid type. ${violation?.message}.`;
-  }
-};
-chunkMWMSFIWN_cjs.__name(_InvalidFieldTypeError, "InvalidFieldTypeError");
-var InvalidFieldTypeError = _InvalidFieldTypeError;
 
 // ../../platform/api-contract/dist/index.js
 var HEADER_RETRY_AFTER = { name: "Retry-After" };
@@ -873,6 +810,20 @@ function isAborted(signal) {
 }
 chunkMWMSFIWN_cjs.__name(isAborted, "isAborted");
 
+// src/http/request-timeout.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+function isTimerDelay(value) {
+  return typeof value === "number" && value >= 1 && value <= MAX_TIMER_DELAY_MS;
+}
+chunkMWMSFIWN_cjs.__name(isTimerDelay, "isTimerDelay");
+function assertRequestTimeout(timeout) {
+  if (isTimerDelay(timeout)) return;
+  throw new Error(
+    `timeout must be a number of milliseconds from 1 to ${MAX_TIMER_DELAY_MS} \u2014 a timer given 0, NaN, Infinity or more fires at once and ends every request \u2014 and got ${String(timeout)}`
+  );
+}
+chunkMWMSFIWN_cjs.__name(assertRequestTimeout, "assertRequestTimeout");
+
 // src/errors/instructed-delay.ts
 function serviceInstructedDelayMs(error, nowMs) {
   if (error instanceof ServiceIndeterminateError) {
@@ -926,43 +877,31 @@ var DefaultRetryPolicy = _DefaultRetryPolicy;
 // src/http/http-client.ts
 var _HttpClient = class _HttpClient {
   constructor(config) {
-    chunkMWMSFIWN_cjs.__publicField(this, "baseUrl");
-    chunkMWMSFIWN_cjs.__publicField(this, "defaultHeaders");
-    chunkMWMSFIWN_cjs.__publicField(this, "timeout");
-    chunkMWMSFIWN_cjs.__publicField(this, "retryPolicy");
-    chunkMWMSFIWN_cjs.__publicField(this, "debug");
-    chunkMWMSFIWN_cjs.__publicField(this, "logger");
-    chunkMWMSFIWN_cjs.__publicField(this, "config");
-    this.config = config;
-    this.baseUrl = config.baseUrl;
-    this.timeout = config.timeout;
-    this.debug = config.debug.enabled ?? false;
-    this.logger = config.debug.logger;
-    const apiKey = presentKey(config.apiKey);
-    this.defaultHeaders = {
-      "Content-Type": "application/json",
-      ...apiKey === void 0 ? {} : { [API_KEY_HEADER]: apiKey },
-      ...config.headers
-    };
-    if (config.dataset != null) {
-      this.defaultHeaders["X-RelyIO-Dataset"] = config.dataset;
-    }
-    if (typeof window === "undefined") {
-      const globalWithVersion = globalThis;
-      this.defaultHeaders["User-Agent"] = `RelyIO-SDK/${globalWithVersion.__VERSION__ ?? "0.0.0"}`;
-    }
-    this.retryPolicy = new DefaultRetryPolicy({
-      maxAttempts: config.retryAttempts,
-      baseDelay: 1e3,
-      maxDelay: 1e4,
-      backoffFactor: 2,
-      jitter: true
-    });
+    /** What every request reads off the configuration, derived by {@link configure} and nowhere else. */
+    chunkMWMSFIWN_cjs.__publicField(this, "connection");
+    this.connection = connectionFor(config);
+    this.announce();
+  }
+  /**
+   * 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) {
+    this.connection = connectionFor(config);
+    this.announce();
+  }
+  announce() {
     this.log("debug", "HttpClient initialized", {
-      baseUrl: this.baseUrl,
-      timeout: this.timeout,
-      retryAttempts: config.retryAttempts,
-      environment: typeof window === "undefined" ? "node" : "browser"
+      baseUrl: this.connection.baseUrl,
+      timeout: this.connection.timeout,
+      retryAttempts: this.connection.config.retryAttempts,
+      environment: chunkTZL374LS_cjs.isBrowser() ? "browser" : "node"
     });
   }
   /**
@@ -999,19 +938,24 @@ var _HttpClient = 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.
    */
   async request(config) {
+    if (config.timeout !== void 0) assertRequestTimeout(config.timeout);
     const mergedConfig = this.mergeRequestConfig(config);
     if (presentKey(headerValue(mergedConfig.headers, API_KEY_HEADER)) === void 0) {
       throw new MissingApiKeyError(
-        "`apiKey` is missing: this client was created without an API key, so the request was not sent. Pass `apiKey` to createClient \u2014 the documented setup reads it from RELYIO_API_KEY.",
+        "`apiKey` is missing: this client holds no API key, so the request was not sent. Pass `apiKey` to createClient \u2014 the documented setup reads it from RELYIO_API_KEY.",
         { url: mergedConfig.url, method: mergedConfig.method, sent: false }
       );
     }
@@ -1021,7 +965,7 @@ var _HttpClient = class _HttpClient {
       // Show the final URL with query params
     });
     if (config.method === "DELETE" && mergedConfig.headers) {
-      delete mergedConfig.headers["Content-Type"];
+      mergedConfig.headers = layerHeaders(mergedConfig.headers, { "Content-Type": null });
     }
     for (let attempt = 1; ; attempt++) {
       try {
@@ -1040,8 +984,8 @@ var _HttpClient = class _HttpClient {
           attempt,
           url: mergedConfig.url
         });
-        if (this.retryPolicy.shouldRetry(attempt, failure, mergedConfig)) {
-          const delay = this.retryPolicy.delayFor(attempt, failure);
+        if (this.connection.retryPolicy.shouldRetry(attempt, failure, mergedConfig)) {
+          const delay = this.connection.retryPolicy.delayFor(attempt, failure);
           this.log("debug", "Retrying request", { attempt, delay });
           await sleep(delay, config.signal);
           continue;
@@ -1113,34 +1057,60 @@ var _HttpClient = class _HttpClient {
     });
   }
   /**
-   * 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) {
-    this.defaultHeaders = { ...this.defaultHeaders, ...headers };
+    this.connection = {
+      ...this.connection,
+      defaultHeaders: layerHeaders(this.connection.defaultHeaders, headers)
+    };
   }
   /**
-   * 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) {
-    this.defaultHeaders.Authorization = `Bearer ${token}`;
+  setApiKey(apiKey) {
+    const { config } = this.connection;
+    config.apiKey = apiKey;
+    config.headers = layerHeaders(config.headers, { [API_KEY_HEADER]: null });
+    this.connection = {
+      ...this.connection,
+      defaultHeaders: layerHeaders(this.connection.defaultHeaders, {
+        [API_KEY_HEADER]: presentKey(apiKey) ?? null
+      })
+    };
   }
   /**
    * Get current default headers
    */
   getDefaultHeaders() {
-    return { ...this.defaultHeaders };
+    return { ...this.connection.defaultHeaders };
   }
   /**
    * Update base URL
    */
   setBaseUrl(baseUrl) {
-    this.baseUrl = baseUrl;
+    this.connection = { ...this.connection, baseUrl };
   }
   /**
    * Get current base URL
    */
   getBaseUrl() {
-    return this.baseUrl;
+    return this.connection.baseUrl;
   }
   /**
    * One attempt.
@@ -1162,7 +1132,7 @@ var _HttpClient = class _HttpClient {
     const timeoutId = setTimeout(() => {
       timedOut = true;
       controller.abort();
-    }, config.timeout ?? this.timeout);
+    }, config.timeout ?? this.connection.timeout);
     const onCallerAbort = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => controller.abort(), "onCallerAbort");
     caller?.addEventListener("abort", onCallerAbort, { once: true });
     try {
@@ -1172,14 +1142,15 @@ var _HttpClient = class _HttpClient {
         headers: filteredHeaders,
         body: this.prepareRequestBody(config),
         signal: controller.signal,
-        // Only where `window` exists. A server or edge runtime has no cookie jar for the mode to
-        // govern, so the field is left off and the runtime's default stands. A Web Worker gets
-        // that default too: it has cookies but no `window`.
-        ...typeof window !== "undefined" && {
-          credentials: credentialsModeFor(this.config.browser.includeCredentials)
+        // Only in a browser — a `window` with a `document` (`isBrowser()`). A server or edge
+        // runtime has no cookie jar for the mode to govern, so the field is left off and the
+        // runtime's default stands; that includes Deno 1.x, whose global is a `window` with no
+        // `document`. A Web Worker gets that default too: it has cookies but no `window`.
+        ...chunkTZL374LS_cjs.isBrowser() && {
+          credentials: credentialsModeFor(this.connection.config.browser.includeCredentials)
         }
       };
-      const send = this.config.fetch ?? globalThis.fetch;
+      const send = this.connection.config.fetch ?? globalThis.fetch;
       const response = await send(url, requestInit);
       clearTimeout(timeoutId);
       const responseBody = await this.parseResponse(response);
@@ -1212,10 +1183,8 @@ var _HttpClient = class _HttpClient {
       }
       if (error instanceof DOMException && error.name === "AbortError") {
         if (!timedOut && isAborted(caller)) throw error;
-        throw new TimeoutError(
-          `Request timed out after ${config.timeout ?? this.timeout}ms`,
-          config.timeout ?? this.timeout
-        );
+        const timeout = config.timeout ?? this.connection.timeout;
+        throw new TimeoutError(`Request timed out after ${timeout}ms`, timeout);
       }
       if (error instanceof TypeError && error.message.includes("CORS")) {
         const corsError = new NetworkError(
@@ -1229,9 +1198,10 @@ var _HttpClient = class _HttpClient {
             suggestion: "Check if the API server allows requests from your domain and has proper CORS headers configured."
           }
         );
-        if (typeof window !== "undefined" && this.config.browser.onCorsError) {
+        const { onCorsError } = this.connection.config.browser;
+        if (chunkTZL374LS_cjs.isBrowser() && onCorsError) {
           try {
-            this.config.browser.onCorsError(corsError, {
+            onCorsError(corsError, {
               url: config.url,
               method: config.method,
               originalError: error
@@ -1248,20 +1218,20 @@ var _HttpClient = class _HttpClient {
     }
   }
   /**
-   * 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).
    */
   filterHeadersForBrowser(headers) {
-    if (typeof window !== "undefined") {
-      const filteredHeaders = { ...headers };
-      const forbiddenHeaders = ["user-agent", "referer", "origin", "host", "connection", "upgrade"];
-      forbiddenHeaders.forEach((header) => {
-        delete filteredHeaders[header];
-        delete filteredHeaders[header.toLowerCase()];
-        delete filteredHeaders[header.toUpperCase()];
-      });
-      return filteredHeaders;
-    }
-    return headers;
+    if (!chunkTZL374LS_cjs.isBrowser()) return headers;
+    return Object.fromEntries(
+      Object.entries(headers).filter(
+        ([name]) => !BROWSER_CONTROLLED_HEADERS.has(name.toLowerCase())
+      )
+    );
   }
   /**
    * Prepare request body based on content type and environment
@@ -1297,7 +1267,7 @@ var _HttpClient = class _HttpClient {
     if (url.startsWith("http://") || url.startsWith("https://")) {
       return url;
     }
-    return `${this.baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
+    return `${this.connection.baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
   }
   mergeRequestConfig(config) {
     const url = this.resolveUrl(config.url);
@@ -1306,11 +1276,11 @@ var _HttpClient = class _HttpClient {
     return {
       ...config,
       url: finalUrl,
-      headers: {
-        ...this.defaultHeaders,
-        ...config.headers
-      },
-      timeout: config.timeout ?? this.timeout
+      // The request's own headers replace the client's of the same name, whatever the case: a
+      // per-request `x-relyio-dataset` sent beside the client's `X-RelyIO-Dataset` is one header
+      // `Headers` joins into `main, staging`.
+      headers: layerHeaders(this.connection.defaultHeaders, config.headers),
+      timeout: config.timeout ?? this.connection.timeout
     };
   }
   buildQueryString(params) {
@@ -1334,9 +1304,10 @@ var _HttpClient = class _HttpClient {
     return obj;
   }
   log(level, message, data) {
-    if (!this.debug) return;
-    if (this.logger != null) {
-      this.logger(level, message, data);
+    const { debug } = this.connection.config;
+    if (!debug.enabled) return;
+    if (debug.logger != null) {
+      debug.logger(level, message, data);
     } else {
       console.log(`[RelyIO SDK ${level.toUpperCase()}] ${message}`, data ?? "");
     }
@@ -1345,29 +1316,104 @@ var _HttpClient = class _HttpClient {
 chunkMWMSFIWN_cjs.__name(_HttpClient, "HttpClient");
 var HttpClient = _HttpClient;
 var API_KEY_HEADER = "X-API-Key";
+var DATASET_HEADER = "X-RelyIO-Dataset";
+var BROWSER_CONTROLLED_HEADERS = /* @__PURE__ */ new Set([
+  "user-agent",
+  "referer",
+  "origin",
+  "host",
+  "connection",
+  "upgrade"
+]);
+function connectionFor(config) {
+  const globalWithVersion = globalThis;
+  const defaultHeaders = layerHeaders(
+    layerHeaders({ "Content-Type": "application/json" }, config.headers),
+    {
+      [API_KEY_HEADER]: presentKey(config.apiKey),
+      [DATASET_HEADER]: config.dataset,
+      // Only outside a browser, which controls this header. "A browser" is the core's one
+      // definition, `isBrowser()` — every environment question in this file asks it.
+      "User-Agent": chunkTZL374LS_cjs.isBrowser() ? void 0 : `RelyIO-SDK/${globalWithVersion.__VERSION__ ?? "0.0.0"}`
+    }
+  );
+  return {
+    config,
+    baseUrl: config.baseUrl,
+    defaultHeaders,
+    timeout: config.timeout,
+    // The policy, not a predicate over `(error, attempt)`: whether a request may be sent again is a
+    // property of the **route** as much as of the refusal, and a callback that never sees the
+    // request cannot express that.
+    retryPolicy: new DefaultRetryPolicy({
+      maxAttempts: config.retryAttempts,
+      baseDelay: 1e3,
+      maxDelay: 1e4,
+      backoffFactor: 2,
+      jitter: true
+    })
+  };
+}
+chunkMWMSFIWN_cjs.__name(connectionFor, "connectionFor");
+function layerHeaders(base, over) {
+  const layered = { ...base };
+  for (const [name, value] of Object.entries(over ?? {})) {
+    if (value === void 0) continue;
+    const lower = name.toLowerCase();
+    for (const existing of Object.keys(layered)) {
+      if (existing.toLowerCase() === lower) delete layered[existing];
+    }
+    if (value !== null) layered[name] = value;
+  }
+  return layered;
+}
+chunkMWMSFIWN_cjs.__name(layerHeaders, "layerHeaders");
 function presentKey(value) {
   return typeof value === "string" && value.trim() !== "" ? value : void 0;
 }
 chunkMWMSFIWN_cjs.__name(presentKey, "presentKey");
 function credentialsModeFor(includeCredentials) {
-  switch (includeCredentials) {
-    case false: {
-      return "same-origin";
-    }
-    case true:
-    case void 0: {
-      return "include";
-    }
-  }
+  return includeCredentials ? "include" : "same-origin";
 }
 chunkMWMSFIWN_cjs.__name(credentialsModeFor, "credentialsModeFor");
 
+// src/content/client-locale.ts
+function callLocale(named, clientLocale) {
+  if (named !== void 0) return named;
+  return clientLocale === void 0 || clientLocale === "" ? void 0 : clientLocale;
+}
+chunkMWMSFIWN_cjs.__name(callLocale, "callLocale");
+function readClientLocale(locale) {
+  return typeof locale === "function" ? locale : () => locale;
+}
+chunkMWMSFIWN_cjs.__name(readClientLocale, "readClientLocale");
+
 // src/content/query-builder.ts
+function namesMetadata(key) {
+  return key === "_metadata" || key.startsWith("_metadata.");
+}
+chunkMWMSFIWN_cjs.__name(namesMetadata, "namesMetadata");
+function refuseMetadataConditions(conditions) {
+  const named = Object.keys(conditions).filter(namesMetadata);
+  if (named.length === 0) return;
+  throw new ValidationError(
+    `A condition cannot name ${named.join(", ")}: the API filters on the fields the content type declares, and reports _metadata beside them. Filter on a field, and read _metadata from the result.`,
+    named.map((field) => ({
+      field,
+      code: "METADATA_CONDITION",
+      message: `${field} is not a field the API can filter on`
+    }))
+  );
+}
+chunkMWMSFIWN_cjs.__name(refuseMetadataConditions, "refuseMetadataConditions");
 var _ContentQueryBuilder = class _ContentQueryBuilder {
-  constructor(httpClient, contentType, defaultLocale) {
+  /**
+   * @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, contentType, locale) {
     this.httpClient = httpClient;
     this.contentType = contentType;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "queryOptions", {});
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
     chunkMWMSFIWN_cjs.__publicField(this, "localesArray");
@@ -1377,6 +1423,9 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     chunkMWMSFIWN_cjs.__publicField(this, "pageNumber");
     chunkMWMSFIWN_cjs.__publicField(this, "pageSizeValue");
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Headers this query adds to the client's own, e.g. `X-RelyIO-Dataset` to list another dataset
@@ -1388,9 +1437,11 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     return 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) {
+    refuseMetadataConditions(conditions);
     this.queryOptions.where = {
       ...this.queryOptions.where,
       ...conditions
@@ -1647,7 +1698,11 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
    * Clone the query builder
    */
   clone() {
-    const cloned = new _ContentQueryBuilder(this.httpClient, this.contentType, this.defaultLocale);
+    const cloned = new _ContentQueryBuilder(
+      this.httpClient,
+      this.contentType,
+      this.clientLocale
+    );
     cloned.queryOptions = JSON.parse(JSON.stringify(this.queryOptions));
     cloned.localeValue = this.localeValue;
     cloned.localesArray = this.localesArray ? [...this.localesArray] : void 0;
@@ -1722,14 +1777,15 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     if (this.queryOptions.cursor !== void 0) {
       params.cursor = this.queryOptions.cursor;
     }
+    const clientLocale = this.clientLocale();
     if (this.localeValue != null && this.localeValue !== "") {
       params.locale = this.localeValue;
     } else if (this.fetchAllLocales) {
       params.locale = "*";
     } else if (this.localesArray && this.localesArray.length > 0) {
       params.locales = this.localesArray.join(",");
-    } else if (this.defaultLocale != null && this.defaultLocale !== "") {
-      params.locale = this.defaultLocale;
+    } else if (clientLocale != null && clientLocale !== "") {
+      params.locale = clientLocale;
     }
     if (this.pageNumber !== void 0) {
       params.page = this.pageNumber;
@@ -1753,17 +1809,23 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
 chunkMWMSFIWN_cjs.__name(_ContentQueryBuilder, "ContentQueryBuilder");
 var ContentQueryBuilder = _ContentQueryBuilder;
 var _ContentByIdBuilder = class _ContentByIdBuilder {
-  constructor(httpClient, contentType, id, defaultLocale) {
+  /**
+   * @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, contentType, id, locale) {
     this.httpClient = httpClient;
     this.contentType = contentType;
     this.id = id;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "includeRelations");
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
     chunkMWMSFIWN_cjs.__publicField(this, "localesArray");
     chunkMWMSFIWN_cjs.__publicField(this, "fetchAllLocales", false);
     chunkMWMSFIWN_cjs.__publicField(this, "childrenOptions");
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked when the read is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Include related content in the response
@@ -1833,14 +1895,15 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
     if (this.includeRelations != null) {
       params.include = this.includeRelations.join(",");
     }
+    const clientLocale = this.clientLocale();
     if (this.localeValue != null && this.localeValue !== "") {
       params.locale = this.localeValue;
     } else if (this.fetchAllLocales) {
       params.locale = "*";
     } else if (this.localesArray && this.localesArray.length > 0) {
       params.locales = this.localesArray.join(",");
-    } else if (this.defaultLocale != null && this.defaultLocale !== "") {
-      params.locale = this.defaultLocale;
+    } else if (clientLocale != null && clientLocale !== "") {
+      params.locale = clientLocale;
     }
     if (this.childrenOptions != null) {
       if (this.childrenOptions.contentTypes) {
@@ -1905,22 +1968,28 @@ chunkMWMSFIWN_cjs.__name(entityTagOf, "entityTagOf");
 
 // src/content/content-client.ts
 var _ContentClient = class _ContentClient {
-  constructor(httpClient, contentType, defaultLocale) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+   *   every call, or a locale fixed for this client
+   */
+  constructor(httpClient, contentType, locale) {
     this.httpClient = httpClient;
     this.contentType = contentType;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Create a new query builder for this content type
    */
   query() {
-    return new ContentQueryBuilder(this.httpClient, this.contentType, this.defaultLocale);
+    return new ContentQueryBuilder(this.httpClient, this.contentType, this.clientLocale);
   }
   /**
    * Find content by ID with fluent options
    */
   findById(id) {
-    return new ContentByIdBuilder(this.httpClient, this.contentType, id, this.defaultLocale);
+    return new ContentByIdBuilder(this.httpClient, this.contentType, id, this.clientLocale);
   }
   /**
    * Fetch all content items
@@ -2004,7 +2073,7 @@ var _ContentClient = class _ContentClient {
   async fetchOneWithTag(id, options) {
     const query = {};
     if (options?.include != null) query.include = options.include.join(",");
-    const locale = options?.locale ?? this.defaultLocale;
+    const locale = options?.locale ?? this.clientLocale();
     if (locale != null && locale !== "") query.locale = locale;
     const response = await this.httpClient.send(
       "/v1/{contentType}/{id}",
@@ -2034,16 +2103,17 @@ var _ContentClient = class _ContentClient {
    * @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()`).
    */
   async create(data, options) {
-    const { idempotencyKey, headers, ...body } = options ?? {};
+    const { idempotencyKey, headers, locale, ...body } = options ?? {};
+    const sent = callLocale(locale, this.clientLocale());
     return this.httpClient.fetchPayload(
       "/v1/{contentType}",
       "post",
       {
         path: { contentType: this.contentType },
-        body: { content: data, ...body },
+        body: { content: data, ...body, ...sent === void 0 ? {} : { locale: sent } },
         headers: requestHeaders(headers, writeHeaders({ idempotencyKey }))
       }
     );
@@ -2054,16 +2124,18 @@ var _ContentClient = class _ContentClient {
    * @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.
    */
   async update(id, data, options) {
-    const { idempotencyKey, ifMatch, headers, ...body } = options ?? {};
+    const { idempotencyKey, ifMatch, headers, locale, ...body } = options ?? {};
+    const sent = callLocale(locale, this.clientLocale());
     return this.httpClient.fetchPayload(
       "/v1/{contentType}/{id}",
       "patch",
       {
         path: { contentType: this.contentType, id },
-        body: { content: data, ...body },
+        body: { content: data, ...body, ...sent === void 0 ? {} : { locale: sent } },
         headers: requestHeaders(headers, writeHeaders({ idempotencyKey, ifMatch }))
       }
     );
@@ -2095,32 +2167,35 @@ var _ContentClient = class _ContentClient {
    * 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.
    */
   async versions(id, options) {
+    const locale = callLocale(options?.locale, this.clientLocale());
     return this.httpClient.fetchPayload("/v1/{contentType}/{id}/versions", "get", {
       path: { contentType: this.contentType, id },
       query: {
         limit: options?.limit ?? 10,
-        ...options?.locale === void 0 ? {} : { locale: options.locale }
+        ...locale === void 0 ? {} : { locale }
       }
     });
   }
   /**
    * 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.
    */
   async version(id, versionNumber, options) {
+    const locale = callLocale(options?.locale, this.clientLocale());
     return this.httpClient.fetchPayload("/v1/{contentType}/{id}/versions/{versionNumber}", "get", {
       path: {
         contentType: this.contentType,
         id,
         versionNumber: String(versionNumber)
       },
-      query: options?.locale === void 0 ? void 0 : { locale: options.locale }
+      query: locale === void 0 ? void 0 : { locale }
     });
   }
   /**
@@ -2159,7 +2234,7 @@ var _ContentClient = class _ContentClient {
     if (options?.include != null) {
       params.include = options.include.join(",");
     }
-    const locale = options?.locale ?? this.defaultLocale;
+    const locale = options?.locale ?? this.clientLocale();
     if (locale != null && locale !== "") {
       params.locale = locale;
     }
@@ -2179,19 +2254,20 @@ var _ContentClient = class _ContentClient {
    * Create a new ContentClient for a different content type
    */
   ofType(contentType) {
-    return new _ContentClient(this.httpClient, contentType, this.defaultLocale);
+    return new _ContentClient(this.httpClient, contentType, this.clientLocale);
   }
   /**
-   * 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) {
     return new _ContentClient(this.httpClient, this.contentType, locale);
   }
   /**
-   * Get the current default locale
+   * Get the default locale as it is now: the client's, or the one `withLocale()` fixed
    */
   getDefaultLocale() {
-    return this.defaultLocale;
+    return this.clientLocale();
   }
 };
 chunkMWMSFIWN_cjs.__name(_ContentClient, "ContentClient");
@@ -2200,7 +2276,7 @@ var ContentClient = _ContentClient;
 // src/errors/file-errors.ts
 var _FileUploadError = class _FileUploadError extends SDKError {
   constructor(code, message, options = {}) {
-    super(message, options.statusCode, options.cause, { fileErrorCode: code });
+    super(message, options.statusCode, options.cause, { ...options.context, fileErrorCode: code });
     chunkMWMSFIWN_cjs.__publicField(this, "code");
     chunkMWMSFIWN_cjs.__publicField(this, "retryable");
     this.code = code;
@@ -2247,11 +2323,52 @@ function validateFile(file, constraints = {}) {
 }
 chunkMWMSFIWN_cjs.__name(validateFile, "validateFile");
 
+// src/errors/file-error-codes.ts
+var FILE_ERROR_CODES = [
+  "UPLOAD_TOO_LARGE",
+  "UNSUPPORTED_MIME",
+  "DIMENSION_OUT_OF_RANGE",
+  "ASPECT_RATIO",
+  "CORRUPT_FILE",
+  "UNSUPPORTED_CODEC",
+  "IMAGES_LIMIT_EXCEEDED",
+  "STREAM_ENCODE_FAILED",
+  "SCAN_INFECTED",
+  "INTERNAL"
+];
+
 // src/content/asset-client.ts
+function assertWaitOptions(options) {
+  const { timeoutMs, pollIntervalMs } = options;
+  if (timeoutMs !== void 0 && !(typeof timeoutMs === "number" && timeoutMs >= 0 && timeoutMs <= MAX_TIMER_DELAY_MS)) {
+    throw new Error(
+      `timeoutMs must be a number of milliseconds from 0 to ${MAX_TIMER_DELAY_MS}, and got ${String(timeoutMs)}`
+    );
+  }
+  if (pollIntervalMs !== void 0 && !isTimerDelay(pollIntervalMs)) {
+    throw new Error(
+      `pollIntervalMs must be a number of milliseconds from 1 to ${MAX_TIMER_DELAY_MS} \u2014 a timer given 0, NaN, Infinity or more fires at once \u2014 and got ${String(pollIntervalMs)}`
+    );
+  }
+}
+chunkMWMSFIWN_cjs.__name(assertWaitOptions, "assertWaitOptions");
 function hasText(value) {
   return value != null && value !== "";
 }
 chunkMWMSFIWN_cjs.__name(hasText, "hasText");
+function processingFailure(subject, stored) {
+  const storedCode = stored?.code;
+  const code = FILE_ERROR_CODES.find((known) => known === storedCode) ?? "PROCESSING_FAILED";
+  return new FileUploadError(
+    code,
+    `Asset ${subject}: ${stored?.message ?? "File processing failed"}`,
+    {
+      retriable: stored?.retriable === true,
+      context: { processingError: stored }
+    }
+  );
+}
+chunkMWMSFIWN_cjs.__name(processingFailure, "processingFailure");
 async function computeSha256Hex(blob) {
   try {
     const subtle = globalThis.crypto?.subtle;
@@ -2267,11 +2384,17 @@ async function computeSha256Hex(blob) {
 }
 chunkMWMSFIWN_cjs.__name(computeSha256Hex, "computeSha256Hex");
 var _AssetFileBuilder = class _AssetFileBuilder {
-  constructor(httpClient, assetType, entryUid, defaultLocale) {
+  /**
+   * @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, assetType, entryUid, locale) {
     this.httpClient = httpClient;
     this.assetType = assetType;
     this.entryUid = entryUid;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, asked on every call rather than copied when this builder was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * The path parameters every `/file/*` route on this builder takes.
@@ -2284,7 +2407,16 @@ var _AssetFileBuilder = class _AssetFileBuilder {
     return { contentType: this.assetType, id: this.entryUid };
   }
   withLocale(locale) {
-    return locale ?? this.defaultLocale;
+    return locale ?? this.clientLocale();
+  }
+  /**
+   * 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.
+   */
+  localeField(locale) {
+    const sent = this.withLocale(locale);
+    return hasText(sent) ? { locale: sent } : {};
   }
   /**
    * Issue a single upload target — an R2 presigned PUT (image/file) or a
@@ -2343,7 +2475,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
         partNumber: target.partNumber,
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
   }
@@ -2354,7 +2486,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       body: {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
     return payload.parts;
@@ -2367,7 +2499,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
         parts: target.parts.map((p) => ({ partNumber: p.partNumber, etag: p.etag })),
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
   }
@@ -2378,7 +2510,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       body: {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
   }
@@ -2398,6 +2530,25 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       { path: this.target, query: params }
     );
   }
+  /**
+   * 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.
+   */
+  async status(options = {}) {
+    const params = {};
+    const locale = this.withLocale(options.locale);
+    if (hasText(locale)) params.locale = locale;
+    return this.httpClient.fetchPayload(
+      "/v1/{contentType}/{id}/file",
+      "get",
+      { path: this.target, query: params }
+    );
+  }
   /**
    * Update the binding's delivery visibility (token-based; no byte relocation —
    * a downgrade purges the gateway cache). Returns the refreshed asset entry.
@@ -2436,14 +2587,31 @@ var _AssetFileBuilder = class _AssetFileBuilder {
     });
   }
   /**
-   * 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.
    */
   async waitUntilReady(options = {}) {
+    assertWaitOptions(options);
     const timeoutMs = options.timeoutMs ?? 6e4;
     const pollIntervalMs = options.pollIntervalMs ?? 1500;
     const locale = this.withLocale(options.locale);
     const deadline = Date.now() + timeoutMs;
+    const subject = `${this.assetType}/${this.entryUid}`;
     for (; ; ) {
       const builder = new ContentByIdBuilder(
         this.httpClient,
@@ -2453,15 +2621,24 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       );
       if (hasText(locale)) builder.locale(locale);
       const entry = await builder.execute();
-      const status = entry?.file?.status;
-      if (entry && status === "ready") return entry;
-      if (status === "failed") {
-        const message = entry?.file?.processing?.error?.message ?? "File processing failed";
-        throw new Error(`Asset ${this.assetType}/${this.entryUid}: ${message}`);
+      let status;
+      if (entry === null) {
+        const binding = await this.status({ ...hasText(locale) ? { locale } : {} });
+        status = binding.status;
+        if (status === "failed") throw processingFailure(subject, binding.processing?.error);
+      } else {
+        status = entry.file?.status;
+        if (status === "ready") return entry;
+        if (status === "failed") throw processingFailure(subject, entry.file?.processing?.error);
       }
       if (Date.now() >= deadline) {
-        throw new Error(
-          `Timed out after ${timeoutMs}ms waiting for ${this.assetType}/${this.entryUid} (status: ${status ?? "unknown"})`
+        const unseen = entry === null && status === "ready" ? "; the file is ready and this key's lens does not show the asset \u2014 it is not published" : "";
+        throw new TimeoutError(
+          `Timed out after ${timeoutMs}ms waiting for ${subject} (status: ${status ?? "unknown"})${unseen}`,
+          timeoutMs,
+          void 0,
+          void 0,
+          { fileStatus: status }
         );
       }
       await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
@@ -2471,11 +2648,14 @@ var _AssetFileBuilder = class _AssetFileBuilder {
 chunkMWMSFIWN_cjs.__name(_AssetFileBuilder, "AssetFileBuilder");
 var AssetFileBuilder = _AssetFileBuilder;
 var _AssetUploadBuilder = class _AssetUploadBuilder {
-  constructor(httpClient, assetType, file, defaultLocale) {
+  /**
+   * @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, assetType, file, locale) {
     this.httpClient = httpClient;
     this.assetType = assetType;
     this.file = file;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "_fileName");
     chunkMWMSFIWN_cjs.__publicField(this, "_visibility");
     chunkMWMSFIWN_cjs.__publicField(this, "_locale");
@@ -2487,6 +2667,9 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     chunkMWMSFIWN_cjs.__publicField(this, "_onProgress");
     chunkMWMSFIWN_cjs.__publicField(this, "_validate");
     chunkMWMSFIWN_cjs.__publicField(this, "_maxPartRetries", 3);
+    /** The client's locale, read once when the upload starts. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /** Subscribe to client → storage upload progress (single PUT + multipart). */
   onProgress(callback) {
@@ -2536,8 +2719,14 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     this._slug = slug;
     return 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 = true) {
+    if (typeof options === "object") assertWaitOptions(options);
     if (options === false) {
       this._waitForReady = false;
     } else {
@@ -2552,7 +2741,8 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     if (!fileName) {
       throw new Error('A file name is required: pass a File, or call .filename("name.ext")');
     }
-    const locale = this._locale ?? this.defaultLocale;
+    const clientLocale = this.clientLocale();
+    const locale = this._locale ?? clientLocale;
     if (this._validate) {
       const violations = validateFile(this.file, this._validate);
       if (violations.length > 0) {
@@ -2563,7 +2753,7 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
       }
     }
     const hash = await computeSha256Hex(this.file);
-    const client = new AssetClient(this.httpClient, this.assetType, this.defaultLocale);
+    const client = new AssetClient(this.httpClient, this.assetType, clientLocale);
     const created = await client.create(this._content, {
       ...hasText(this._slug) ? { slug: this._slug } : {},
       ...hasText(locale) ? { locale } : {},
@@ -2714,17 +2904,26 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
 chunkMWMSFIWN_cjs.__name(_AssetUploadBuilder, "AssetUploadBuilder");
 var AssetUploadBuilder = _AssetUploadBuilder;
 var _AssetClient = class _AssetClient {
-  constructor(httpClient, assetType, defaultLocale) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+   *   every call, or a locale fixed for this client
+   */
+  constructor(httpClient, assetType, locale) {
     this.httpClient = httpClient;
     this.assetType = assetType;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
-  /** Create a query builder for this asset type. */
+  /**
+   * 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() {
     return new ContentQueryBuilder(
       this.httpClient,
       this.assetType,
-      this.defaultLocale
+      this.clientLocale
     );
   }
   /** Find an asset entry by id (or slug) with fluent options. */
@@ -2733,7 +2932,7 @@ var _AssetClient = class _AssetClient {
       this.httpClient,
       this.assetType,
       id,
-      this.defaultLocale
+      this.clientLocale
     );
   }
   /** Fetch a single asset entry by id (or slug), or `null` if not found. */
@@ -2754,28 +2953,34 @@ var _AssetClient = class _AssetClient {
    * 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()`).
    */
   async create(data, options) {
-    const { idempotencyKey, ...rest } = options ?? {};
+    const { idempotencyKey, locale, ...rest } = options ?? {};
+    const sent = callLocale(locale, this.clientLocale());
     return this.httpClient.fetchPayload(
       "/v1/{contentType}",
       "post",
       {
         path: { contentType: this.assetType },
-        body: { content: data, ...rest },
+        body: { content: data, ...rest, ...sent === void 0 ? {} : { locale: sent } },
         headers: writeHeaders({ idempotencyKey })
       }
     );
   }
-  /** 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()`).
+   */
   async update(id, data, options) {
-    const { idempotencyKey, ifMatch, ...rest } = options ?? {};
+    const { idempotencyKey, ifMatch, locale, ...rest } = options ?? {};
+    const sent = callLocale(locale, this.clientLocale());
     return this.httpClient.fetchPayload(
       "/v1/{contentType}/{id}",
       "patch",
       {
         path: { contentType: this.assetType, id },
-        body: { content: data, ...rest },
+        body: { content: data, ...rest, ...sent === void 0 ? {} : { locale: sent } },
         headers: writeHeaders({ idempotencyKey, ifMatch })
       }
     );
@@ -2789,21 +2994,24 @@ var _AssetClient = class _AssetClient {
   }
   /** Get the file sub-resource builder for a specific asset entry. */
   file(entryUid) {
-    return new AssetFileBuilder(this.httpClient, this.assetType, entryUid, this.defaultLocale);
+    return new AssetFileBuilder(this.httpClient, this.assetType, entryUid, this.clientLocale);
   }
   /** Start a high-level upload (create → presign → PUT → confirm). */
   upload(file) {
-    return new AssetUploadBuilder(this.httpClient, this.assetType, file, this.defaultLocale);
+    return new AssetUploadBuilder(this.httpClient, this.assetType, file, this.clientLocale);
   }
   /** Get the asset type id. */
   getAssetType() {
     return this.assetType;
   }
-  /** Get the current default locale. */
+  /** Get the default locale as it is now: the client's, or the one `withLocale()` fixed. */
   getDefaultLocale() {
-    return this.defaultLocale;
+    return this.clientLocale();
   }
-  /** 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) {
     return new _AssetClient(this.httpClient, this.assetType, locale);
   }
@@ -2819,12 +3027,18 @@ chunkMWMSFIWN_cjs.__name(isAssetEntry, "isAssetEntry");
 
 // src/content/singleton-client.ts
 var _SingletonClient = class _SingletonClient {
-  constructor(httpClient, singletonKey, defaultLocale) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+   *   every call, or a locale fixed for this client
+   */
+  constructor(httpClient, singletonKey, locale) {
     this.httpClient = httpClient;
     this.singletonKey = singletonKey;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "includeFields");
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Include reference fields in the response
@@ -2864,7 +3078,7 @@ var _SingletonClient = class _SingletonClient {
   async fetchWithTag(options) {
     const query = {};
     const includeValue = options?.include ?? this.includeFields;
-    const localeValueFinal = options?.locale ?? this.localeValue ?? this.defaultLocale;
+    const localeValueFinal = options?.locale ?? this.localeValue ?? this.clientLocale();
     if (includeValue) query.include = includeValue.join(",");
     if (localeValueFinal != null && localeValueFinal !== "") query.locale = localeValueFinal;
     const response = await this.httpClient.send(
@@ -2878,11 +3092,12 @@ var _SingletonClient = class _SingletonClient {
    * 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
    */
   async update(data, locale, options) {
-    const finalLocale = locale ?? this.localeValue;
+    const finalLocale = this.localeOf(locale);
     return this.httpClient.fetchPayload(
       "/v1/singletons/{key}",
       "patch",
@@ -2911,15 +3126,17 @@ var _SingletonClient = class _SingletonClient {
    * 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.
    */
   async versions(options) {
+    const locale = this.localeOf(options?.locale);
     const payload = await this.httpClient.fetchPayload("/v1/singletons/{key}/versions", "get", {
       path: { key: this.singletonKey },
       query: {
         limit: options?.limit ?? 10,
-        ...options?.locale === void 0 ? {} : { locale: options.locale }
+        ...locale === void 0 ? {} : { locale }
       }
     });
     return payload.versions;
@@ -2927,20 +3144,25 @@ var _SingletonClient = class _SingletonClient {
   /**
    * 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.
    */
   async version(versionNumber, options) {
+    const locale = this.localeOf(options?.locale);
     try {
       return await this.httpClient.fetchPayload("/v1/singletons/{key}/versions/{versionNumber}", "get", {
         path: { key: this.singletonKey, versionNumber: String(versionNumber) },
-        query: options?.locale === void 0 ? void 0 : { locale: options.locale }
+        query: locale === void 0 ? void 0 : { locale }
       });
     } catch (error) {
       if (isResourceNotFound(error)) return null;
       throw error;
     }
   }
+  /** The locale a write or history read sends: the call's, the fluent one, else the client's. */
+  localeOf(named) {
+    return callLocale(named ?? this.localeValue, this.clientLocale());
+  }
   /**
    * Get the singleton key
    */
@@ -2961,12 +3183,18 @@ var SingletonClient = _SingletonClient;
 
 // src/content/settings-client.ts
 var _SettingsClient = class _SettingsClient {
-  constructor(httpClient, groupId, defaultLocale) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+   *   every call, or a locale fixed for this client
+   */
+  constructor(httpClient, groupId, locale) {
     this.httpClient = httpClient;
     this.groupId = groupId;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "includeFields");
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Include reference fields in the response
@@ -2998,12 +3226,20 @@ var _SettingsClient = class _SettingsClient {
   }
   /**
    * 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)
    */
   async update(settings, locale, options) {
-    const finalLocale = locale ?? this.localeValue;
-    const body = finalLocale != null && finalLocale !== "" ? { ...settings, locale: finalLocale } : settings;
+    const finalLocale = this.localeOf(locale);
+    const body = {
+      content: settings,
+      ...finalLocale != null && finalLocale !== "" ? { locale: finalLocale } : {}
+    };
     return this.httpClient.fetchPayload(
       "/v1/settings/{groupId}",
       "patch",
@@ -3018,7 +3254,7 @@ var _SettingsClient = class _SettingsClient {
   async fetchWithTag(options) {
     const query = {};
     const includeValue = options?.include ?? this.includeFields;
-    const localeValueFinal = options?.locale ?? this.localeValue ?? this.defaultLocale;
+    const localeValueFinal = options?.locale ?? this.localeValue ?? this.clientLocale();
     if (includeValue) query.include = includeValue.join(",");
     if (localeValueFinal != null && localeValueFinal !== "") query.locale = localeValueFinal;
     const response = await this.httpClient.send(
@@ -3030,16 +3266,20 @@ var _SettingsClient = class _SettingsClient {
   }
   /**
    * 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)
    */
   async reset(locale, options) {
-    const finalLocale = locale ?? this.localeValue;
+    const finalLocale = this.localeOf(locale);
     return this.httpClient.fetchPayload(
       "/v1/settings/{groupId}/reset",
       "post",
       {
         path: { groupId: this.groupId },
-        body: finalLocale != null && finalLocale !== "" ? { locale: finalLocale } : void 0,
+        query: finalLocale != null && finalLocale !== "" ? { locale: finalLocale } : void 0,
         headers: writeHeaders(options)
       }
     );
@@ -3070,15 +3310,17 @@ var _SettingsClient = class _SettingsClient {
    * 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.
    */
   async versions(options) {
+    const locale = this.localeOf(options?.locale);
     const payload = await this.httpClient.fetchPayload("/v1/settings/{groupId}/versions", "get", {
       path: { groupId: this.groupId },
       query: {
         limit: options?.limit ?? 10,
-        ...options?.locale === void 0 ? {} : { locale: options.locale }
+        ...locale === void 0 ? {} : { locale }
       }
     });
     return payload.versions;
@@ -3086,20 +3328,25 @@ var _SettingsClient = class _SettingsClient {
   /**
    * 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.
    */
   async version(versionNumber, options) {
+    const locale = this.localeOf(options?.locale);
     try {
       return await this.httpClient.fetchPayload("/v1/settings/{groupId}/versions/{versionNumber}", "get", {
         path: { groupId: this.groupId, versionNumber: String(versionNumber) },
-        query: options?.locale === void 0 ? void 0 : { locale: options.locale }
+        query: locale === void 0 ? void 0 : { locale }
       });
     } catch (error) {
       if (isResourceNotFound(error)) return null;
       throw error;
     }
   }
+  /** The locale a write or history read sends: the call's, the fluent one, else the client's. */
+  localeOf(named) {
+    return callLocale(named ?? this.localeValue, this.clientLocale());
+  }
   /**
    * Get the settings group ID
    */
@@ -3121,15 +3368,18 @@ var SettingsClient = _SettingsClient;
 // src/search/search-client.ts
 var _SearchBuilder = class _SearchBuilder {
   /**
-   * @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, query, defaultLocale) {
+  constructor(httpClient, query, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "query");
     chunkMWMSFIWN_cjs.__publicField(this, "searchOptions", {});
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
     this.query = query;
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Headers this search adds to the client's own, e.g. `X-RelyIO-Dataset` to search another
@@ -3160,10 +3410,12 @@ var _SearchBuilder = class _SearchBuilder {
     return 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) {
+    refuseMetadataConditions(conditions);
     this.searchOptions.where = {
       ...this.searchOptions.where,
       ...conditions
@@ -3271,7 +3523,7 @@ var _SearchBuilder = class _SearchBuilder {
     if (this.searchOptions.explain === true) {
       body.explain = true;
     }
-    const locale = this.searchOptions.locale ?? this.defaultLocale;
+    const locale = this.searchOptions.locale ?? this.clientLocale();
     if (locale != null && locale !== "") {
       body.locale = locale;
     }
@@ -3299,14 +3551,17 @@ chunkMWMSFIWN_cjs.__name(_SearchBuilder, "SearchBuilder");
 var SearchBuilder = _SearchBuilder;
 var _AutocompleteBuilder = class _AutocompleteBuilder {
   /**
-   * @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, query, defaultLocale) {
+  constructor(httpClient, query, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "query");
     chunkMWMSFIWN_cjs.__publicField(this, "autocompleteOptions", {});
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
     this.query = query;
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Autocomplete within a content type
@@ -3332,10 +3587,12 @@ var _AutocompleteBuilder = class _AutocompleteBuilder {
     return 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) {
+    refuseMetadataConditions(conditions);
     this.autocompleteOptions.where = {
       ...this.autocompleteOptions.where,
       ...conditions
@@ -3382,7 +3639,7 @@ var _AutocompleteBuilder = class _AutocompleteBuilder {
     if (this.autocompleteOptions.limit !== void 0) {
       body.limit = this.autocompleteOptions.limit;
     }
-    const locale = this.autocompleteOptions.locale ?? this.defaultLocale;
+    const locale = this.autocompleteOptions.locale ?? this.clientLocale();
     if (locale != null && locale !== "") {
       body.locale = locale;
     }
@@ -3400,15 +3657,18 @@ chunkMWMSFIWN_cjs.__name(_AutocompleteBuilder, "AutocompleteBuilder");
 var AutocompleteBuilder = _AutocompleteBuilder;
 var _SimilarBuilder = class _SimilarBuilder {
   /**
-   * @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, sourceId, defaultLocale) {
+  constructor(httpClient, sourceId, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "sourceId");
     chunkMWMSFIWN_cjs.__publicField(this, "similarOptions", {});
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked when the read is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
     this.sourceId = sourceId;
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Headers this read adds to the client's own, e.g. `X-RelyIO-Dataset` to read another dataset
@@ -3436,17 +3696,12 @@ var _SimilarBuilder = class _SimilarBuilder {
     this.similarOptions.contentType = void 0;
     return this;
   }
-  /**
-   * Add filter conditions
-   * @param conditions - Filter conditions
+  /*
+   * No `where()` (REL-1452). Similar ranks from the source entry's stored vector, and the vector
+   * index can pre-filter by content type and locale only — never by an entry field. The API used to
+   * accept `where` here and apply nothing; it now refuses the property, so the builder does not
+   * offer a filter that cannot be honoured. Narrow with `.in()`, `.across()` and `.locale()`.
    */
-  where(conditions) {
-    this.similarOptions.where = {
-      ...this.similarOptions.where,
-      ...conditions
-    };
-    return this;
-  }
   /**
    * Limit number of results
    * @param count - Maximum results
@@ -3480,13 +3735,10 @@ var _SimilarBuilder = class _SimilarBuilder {
     if (contentTypes != null) {
       body.contentTypes = contentTypes;
     }
-    if (this.similarOptions.where && Object.keys(this.similarOptions.where).length > 0) {
-      body.where = this.similarOptions.where;
-    }
     if (this.similarOptions.limit !== void 0) {
       body.limit = this.similarOptions.limit;
     }
-    const locale = this.similarOptions.locale ?? this.defaultLocale;
+    const locale = this.similarOptions.locale ?? this.clientLocale();
     if (locale != null && locale !== "") {
       body.locale = locale;
     }
@@ -3514,41 +3766,36 @@ chunkMWMSFIWN_cjs.__name(_SimilarBuilder, "SimilarBuilder");
 var SimilarBuilder = _SimilarBuilder;
 var _SearchClient = class _SearchClient {
   /**
-   * @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, defaultLocale) {
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, handed to every builder here to ask when it sends. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Start a search query
    * @param query - Search query string
    */
   search(query) {
-    return new SearchBuilder(this.httpClient, query, this.defaultLocale);
+    return new SearchBuilder(this.httpClient, query, this.clientLocale);
   }
   /**
    * Start an autocomplete query
    * @param query - Partial query to autocomplete
    */
   autocomplete(query) {
-    return new AutocompleteBuilder(this.httpClient, query, this.defaultLocale);
+    return new AutocompleteBuilder(this.httpClient, query, this.clientLocale);
   }
   /**
    * Find content similar to a given entry
    * @param sourceId - Entry ID to find similar content for
    */
   similar(sourceId) {
-    return new SimilarBuilder(this.httpClient, sourceId, this.defaultLocale);
-  }
-  /**
-   * Quick search helper - searches all content types
-   * @param query - Search query
-   * @param limit - Max results (default 20)
-   */
-  async global(query, limit = 20) {
-    return this.search(query).across("*").limit(limit).execute();
+    return new SimilarBuilder(this.httpClient, sourceId, this.clientLocale);
   }
 };
 chunkMWMSFIWN_cjs.__name(_SearchClient, "SearchClient");
@@ -3556,7 +3803,12 @@ var SearchClient = _SearchClient;
 
 // src/batch/batch-client.ts
 var _BatchBuilder = class _BatchBuilder {
-  constructor(httpClient) {
+  /**
+   * @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, locale) {
     this.httpClient = httpClient;
     chunkMWMSFIWN_cjs.__publicField(this, "operations", []);
     chunkMWMSFIWN_cjs.__publicField(this, "defaultOptions", {
@@ -3566,6 +3818,17 @@ var _BatchBuilder = class _BatchBuilder {
       continueOnError: true
     });
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked as each operation is added rather than copied when this was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
+  }
+  /**
+   * An operation's body with its locale: the one it names, else the client's as it is when the
+   * operation is added.
+   */
+  localized(data) {
+    const locale = callLocale(data.locale, this.clientLocale());
+    return locale === void 0 ? data : { ...data, locale };
   }
   // ==========================================================================
   // ENTRY OPERATIONS
@@ -3581,7 +3844,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "POST",
       path: `/${contentType}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3601,7 +3864,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PATCH",
       path: `/${contentType}/${entryId}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3621,7 +3884,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PUT",
       path: `/${contentType}/${entryId}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3653,7 +3916,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PATCH",
       path: `/_singletons/${singletonKey}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3668,7 +3931,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "POST",
       path: `/_singletons/${singletonKey}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3676,7 +3939,8 @@ var _BatchBuilder = class _BatchBuilder {
   // RAW OPERATIONS
   // ==========================================================================
   /**
-   * 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) {
@@ -3802,7 +4066,7 @@ var _BatchBuilder = class _BatchBuilder {
    * Clone the builder
    */
   clone() {
-    const cloned = new _BatchBuilder(this.httpClient);
+    const cloned = new _BatchBuilder(this.httpClient, this.clientLocale);
     cloned.operations = [...this.operations];
     cloned.defaultOptions = { ...this.defaultOptions };
     cloned.requestHeaders = this.requestHeaders === void 0 ? void 0 : { ...this.requestHeaders };
@@ -3855,14 +4119,21 @@ var _BatchBuilder = class _BatchBuilder {
 chunkMWMSFIWN_cjs.__name(_BatchBuilder, "BatchBuilder");
 var BatchBuilder = _BatchBuilder;
 var _BatchClient = class _BatchClient {
-  constructor(httpClient) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, or a locale
+   *   fixed for this client
+   */
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
+    /** The client's locale, handed to every batch this builds to ask as operations are added. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
-   * Create a new batch builder
+   * Create a new batch builder, whose operations default to this client's locale
    */
   create() {
-    return new BatchBuilder(this.httpClient);
+    return new BatchBuilder(this.httpClient, this.clientLocale);
   }
   /**
    * Quick bulk create entries
@@ -3913,15 +4184,18 @@ function withClientLocale(parameters, clientLocale) {
 chunkMWMSFIWN_cjs.__name(withClientLocale, "withClientLocale");
 var _AdhocQueryBuilder = class _AdhocQueryBuilder {
   /**
-   * @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, defaultLocale) {
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "queryDef", {});
     chunkMWMSFIWN_cjs.__publicField(this, "parameters", {});
     chunkMWMSFIWN_cjs.__publicField(this, "options", {});
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   // ==========================================================================
   // QUERY BLOCKS
@@ -3966,14 +4240,6 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
     this.queryDef.search = config;
     return this;
   }
-  /**
-   * Add similar block
-   * @param config - Similar configuration
-   */
-  similar(config) {
-    this.queryDef.similar = config;
-    return this;
-  }
   // ==========================================================================
   // FETCH MODIFIERS
   // ==========================================================================
@@ -4150,15 +4416,15 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
    * Execute the query
    */
   async execute() {
-    if (!this.queryDef.fetch && !this.queryDef.aggregate && !this.queryDef.search && !this.queryDef.similar) {
+    if (!this.queryDef.fetch && !this.queryDef.aggregate && !this.queryDef.search) {
       throw new Error(
-        "Query must have at least one of: fetch, aggregate, search, or similar. Use .from(), .aggregate(), .search(), or .similar()"
+        "Query must have at least one of: fetch, aggregate or search. Use .from(), .aggregate() or .search()"
       );
     }
     const body = {
       query: this.queryDef
     };
-    const parameters = withClientLocale(this.parameters, this.defaultLocale);
+    const parameters = withClientLocale(this.parameters, this.clientLocale());
     if (parameters !== void 0 && Object.keys(parameters).length > 0) {
       body.parameters = parameters;
     }
@@ -4191,7 +4457,7 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
    * Clone the builder
    */
   clone() {
-    const cloned = new _AdhocQueryBuilder(this.httpClient, this.defaultLocale);
+    const cloned = new _AdhocQueryBuilder(this.httpClient, this.clientLocale);
     cloned.queryDef = JSON.parse(JSON.stringify(this.queryDef));
     cloned.parameters = { ...this.parameters };
     cloned.options = { ...this.options };
@@ -4202,18 +4468,21 @@ chunkMWMSFIWN_cjs.__name(_AdhocQueryBuilder, "AdhocQueryBuilder");
 var AdhocQueryBuilder = _AdhocQueryBuilder;
 var _AdhocQueryClient = class _AdhocQueryClient {
   /**
-   * @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, defaultLocale) {
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, asked on every query rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Create a new query builder
    */
   build() {
-    return new AdhocQueryBuilder(this.httpClient, this.defaultLocale);
+    return new AdhocQueryBuilder(this.httpClient, this.clientLocale);
   }
   /**
    * Execute a query definition directly
@@ -4228,7 +4497,7 @@ var _AdhocQueryClient = class _AdhocQueryClient {
     const body = {
       query: definition
     };
-    const sent = withClientLocale(parameters, this.defaultLocale);
+    const sent = withClientLocale(parameters, this.clientLocale());
     if (sent !== void 0 && Object.keys(sent).length > 0) {
       body.parameters = sent;
     }
@@ -4477,7 +4746,7 @@ var DEFAULT_CONFIG = {
   environment: "production",
   headers: {},
   browser: {
-    includeCredentials: true,
+    includeCredentials: false,
     useRelativeUrls: false
   },
   cache: {
@@ -4509,45 +4778,42 @@ function validateConfig(config) {
   if (config.baseUrl != null && typeof config.baseUrl !== "string") {
     throw new Error("Base URL must be a string");
   }
-  if (config.timeout != null && (typeof config.timeout !== "number" || config.timeout < 0)) {
-    throw new Error("Timeout must be a positive number");
-  }
-  if (config.retryAttempts != null && (typeof config.retryAttempts !== "number" || config.retryAttempts < 0)) {
-    throw new Error("Retry attempts must be a positive number");
+  if (config.timeout != null) assertRequestTimeout(config.timeout);
+  if (config.retryAttempts != null && !(Number.isInteger(config.retryAttempts) && config.retryAttempts >= 1)) {
+    throw new Error(
+      `retryAttempts must be a whole number of at least 1 \u2014 the most attempts one request makes, the first included, so 1 turns retrying off \u2014 and got ${String(config.retryAttempts)}`
+    );
   }
 }
 chunkMWMSFIWN_cjs.__name(validateConfig, "validateConfig");
 var devOverrideNotified = false;
 function resolveConfig(userConfig) {
   validateConfig(userConfig);
-  const merged = {
-    ...DEFAULT_CONFIG,
-    ...userConfig,
-    headers: {
-      ...DEFAULT_CONFIG.headers,
-      ...userConfig.headers
-    },
-    browser: {
-      ...DEFAULT_CONFIG.browser,
-      ...userConfig.browser
-    },
-    cache: {
-      ...DEFAULT_CONFIG.cache,
-      ...userConfig.cache
-    },
-    realtime: {
-      ...DEFAULT_CONFIG.realtime,
-      ...userConfig.realtime
-    },
-    debug: {
-      ...DEFAULT_CONFIG.debug,
-      ...userConfig.debug
-    }
-  };
-  const dev = resolveDevOverride(userConfig.dev);
+  return withHandshake(withDefaults(DEFAULT_CONFIG, userConfig, DEFAULT_CONFIG));
+}
+chunkMWMSFIWN_cjs.__name(resolveConfig, "resolveConfig");
+function resolveConfigUpdate(configured, update) {
+  validateConfig(update);
+  const base = update.apiKey === void 0 ? configured : withoutKeyHeader(configured);
+  return withHandshake(withDefaults(base, update, DEFAULT_CONFIG));
+}
+chunkMWMSFIWN_cjs.__name(resolveConfigUpdate, "resolveConfigUpdate");
+function withConfiguredKey(configured, apiKey) {
+  return { ...withoutKeyHeader(configured), apiKey };
+}
+chunkMWMSFIWN_cjs.__name(withConfiguredKey, "withConfiguredKey");
+function withoutKeyHeader(configured) {
+  return { ...configured, headers: layerHeaders(configured.headers, { [API_KEY_HEADER]: null }) };
+}
+chunkMWMSFIWN_cjs.__name(withoutKeyHeader, "withoutKeyHeader");
+function withHandshake(configured) {
+  const dev = resolveDevOverride(configured.dev);
+  const merged = withDefaults(
+    configured,
+    dev.state === "active" ? { apiKey: dev.apiKey, dataset: dev.sandbox.datasetId } : {},
+    DEFAULT_CONFIG
+  );
   if (dev.state === "active") {
-    merged.apiKey = dev.apiKey;
-    merged.dataset = dev.sandbox.datasetId;
     if (!devOverrideNotified) {
       devOverrideNotified = true;
       console.info(
@@ -4565,30 +4831,67 @@ function resolveConfig(userConfig) {
       `[RelyIO] Your .relyio/dev.json could not be read (${dev.reason}) \u2014 ignoring it and using the configured dataset "${merged.dataset}". Run \`relyio dev\` to rewrite it.`
     );
   }
-  return { config: merged, sandbox: sandboxStateOf(dev) };
+  return { config: merged, sandbox: sandboxStateOf(dev), configured };
 }
-chunkMWMSFIWN_cjs.__name(resolveConfig, "resolveConfig");
+chunkMWMSFIWN_cjs.__name(withHandshake, "withHandshake");
+function withDefaults(base, given, defaults) {
+  const merged = new Map(Object.entries(base));
+  const givenValues = new Map(Object.entries(given ?? {}));
+  const defaultValues = new Map(Object.entries(defaults));
+  for (const key of /* @__PURE__ */ new Set([...merged.keys(), ...givenValues.keys()])) {
+    const fallback = merged.get(key);
+    const value = givenValues.get(key);
+    const givenBag = isOptionBag(value) ? value : void 0;
+    if (isOptionBag(fallback) && key === "headers") {
+      merged.set(key, layerHeaders(fallback, givenBag));
+    } else if (isOptionBag(fallback)) {
+      const defaultBag = defaultValues.get(key);
+      merged.set(key, withDefaults(fallback, givenBag, isOptionBag(defaultBag) ? defaultBag : {}));
+    } else if (value === null) {
+      if (defaultValues.has(key)) merged.set(key, defaultValues.get(key));
+      else merged.delete(key);
+    } else if (value !== void 0) {
+      merged.set(key, value);
+    }
+  }
+  return Object.fromEntries(merged);
+}
+chunkMWMSFIWN_cjs.__name(withDefaults, "withDefaults");
+function isOptionBag(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+chunkMWMSFIWN_cjs.__name(isOptionBag, "isOptionBag");
 
 // src/client/create-client.ts
 var API_VERSION_SEGMENT = "v1";
 var _TypedRelyIOClient = class _TypedRelyIOClient {
   constructor(config) {
+    /**
+     * 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.
+     */
     chunkMWMSFIWN_cjs.__publicField(this, "httpClient");
     chunkMWMSFIWN_cjs.__publicField(this, "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.
+     */
+    chunkMWMSFIWN_cjs.__publicField(this, "configured");
     chunkMWMSFIWN_cjs.__publicField(this, "_sandbox");
-    chunkMWMSFIWN_cjs.__publicField(this, "_search");
-    chunkMWMSFIWN_cjs.__publicField(this, "_batch");
-    chunkMWMSFIWN_cjs.__publicField(this, "_adhocQuery");
     chunkMWMSFIWN_cjs.__publicField(this, "_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).
+     */
+    chunkMWMSFIWN_cjs.__publicField(this, "currentLocale", /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => this.config.locale, "currentLocale"));
     const { schema, ...clientConfig } = config;
     this._schema = schema;
     const resolved = resolveConfig(clientConfig);
     this.config = resolved.config;
+    this.configured = resolved.configured;
     this._sandbox = resolved.sandbox;
     this.httpClient = new HttpClient(this.config);
-    this._search = new SearchClient(this.httpClient, this.config.locale);
-    this._batch = new BatchClient(this.httpClient);
-    this._adhocQuery = new AdhocQueryClient(this.httpClient, this.config.locale);
   }
   // ============================================================================
   // CORE CLIENTS
@@ -4617,10 +4920,10 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     return this._sandbox;
   }
   /**
-   * 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() {
-    return this._adhocQuery;
+    return new AdhocQueryClient(this.httpClient, this.currentLocale);
   }
   // ============================================================================
   // CONTENT OPERATIONS
@@ -4640,7 +4943,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   content(contentType) {
-    return new ContentClient(this.httpClient, contentType, this.config.locale);
+    return new ContentClient(this.httpClient, contentType, this.currentLocale);
   }
   /**
    * Get an asset client for a specific asset type.
@@ -4661,7 +4964,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   asset(assetType) {
-    return new AssetClient(this.httpClient, assetType, this.config.locale);
+    return new AssetClient(this.httpClient, assetType, this.currentLocale);
   }
   /**
    * Get a singleton client for a specific singleton key
@@ -4676,7 +4979,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   singleton(key) {
-    return new SingletonClient(this.httpClient, key, this.config.locale);
+    return new SingletonClient(this.httpClient, key, this.currentLocale);
   }
   /**
    * Get a settings client for a specific settings group
@@ -4690,7 +4993,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   settings(groupId) {
-    return new SettingsClient(this.httpClient, groupId, this.config.locale);
+    return new SettingsClient(this.httpClient, groupId, this.currentLocale);
   }
   // ============================================================================
   // SEARCH OPERATIONS
@@ -4712,7 +5015,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   search(query) {
-    return this._search.search(query);
+    return this.searchClient().search(query);
   }
   /**
    * Start an autocomplete query for search suggestions
@@ -4728,7 +5031,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   autocomplete(query) {
-    return this._search.autocomplete(query);
+    return this.searchClient().autocomplete(query);
   }
   /**
    * Find content similar to a given entry using vector search
@@ -4743,13 +5046,17 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   similar(sourceId) {
-    return this._search.similar(sourceId);
+    return this.searchClient().similar(sourceId);
   }
   // ============================================================================
   // BATCH OPERATIONS
   // ============================================================================
   /**
-   * 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
@@ -4758,13 +5065,23 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    *   .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() {
-    return this._batch.create();
+    return new BatchClient(this.httpClient, this.currentLocale).create();
+  }
+  /** The search client, whose builders send the client's locale as it is when each one is sent. */
+  searchClient() {
+    return new SearchClient(this.httpClient, this.currentLocale);
   }
   // ============================================================================
   // CHANGES FEED
@@ -4838,7 +5155,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   adhoc() {
-    return this._adhocQuery.build();
+    return this.query.build();
   }
   /**
    * Execute a predefined query by name (from schema)
@@ -4923,16 +5240,53 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     }
   }
   /**
-   * 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) {
-    const resolved = resolveConfig({ ...this.config, ...newConfig });
+  updateConfig(update) {
+    const resolved = resolveConfigUpdate(this.configured, update);
     this.config = resolved.config;
+    this.configured = resolved.configured;
     this._sandbox = resolved.sandbox;
-    this.httpClient = new HttpClient(this.config);
-    this._search = new SearchClient(this.httpClient, this.config.locale);
-    this._batch = new BatchClient(this.httpClient);
-    this._adhocQuery = new AdhocQueryClient(this.httpClient, this.config.locale);
+    this.httpClient.configure(this.config);
   }
   /**
    * Get the current configuration
@@ -4941,11 +5295,31 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     return { ...this.config };
   }
   /**
-   * 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) {
-    this.config.apiKey = apiKey;
-    this.httpClient.setAuthToken(apiKey);
+    this.configured = withConfiguredKey(this.configured, apiKey);
+    if (this._sandbox.state === "active") return;
+    this.httpClient.setApiKey(apiKey);
   }
   /**
    * Get the HTTP client instance (for advanced usage)
@@ -4959,9 +5333,12 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   /**
    * 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!
    *
@@ -4969,10 +5346,11 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```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()
@@ -4980,7 +5358,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    */
   withLocale(locale) {
     const newConfig = {
-      ...this.getConfig(),
+      ...this.configured,
       locale,
       schema: this._schema
     };
@@ -5034,7 +5412,6 @@ exports.AdhocQueryClient = AdhocQueryClient;
 exports.AssetClient = AssetClient;
 exports.AssetFileBuilder = AssetFileBuilder;
 exports.AssetUploadBuilder = AssetUploadBuilder;
-exports.AuthenticationError = AuthenticationError;
 exports.AuthorizationError = AuthorizationError;
 exports.AutocompleteBuilder = AutocompleteBuilder;
 exports.BaseValidationError = BaseValidationError;
@@ -5050,7 +5427,6 @@ exports.FileUploadError = FileUploadError;
 exports.FileValidationError = FileValidationError;
 exports.HttpClient = HttpClient;
 exports.InvalidApiKeyError = InvalidApiKeyError;
-exports.InvalidFieldTypeError = InvalidFieldTypeError;
 exports.InvalidPayloadError = InvalidPayloadError;
 exports.MethodNotAllowedError = MethodNotAllowedError;
 exports.MissingApiKeyError = MissingApiKeyError;
@@ -5059,12 +5435,10 @@ exports.PayloadTooLargeError = PayloadTooLargeError;
 exports.PlanFeatureUnavailableError = PlanFeatureUnavailableError;
 exports.RateLimitError = RateLimitError;
 exports.ReadOnlyKeyError = ReadOnlyKeyError;
-exports.RequiredFieldError = RequiredFieldError;
 exports.ResourceConflictError = ResourceConflictError;
 exports.ResourceExpiredError = ResourceExpiredError;
 exports.ResourceNotFoundError = ResourceNotFoundError;
 exports.SDKError = SDKError;
-exports.SchemaValidationError = SchemaValidationError;
 exports.SearchBuilder = SearchBuilder;
 exports.SearchClient = SearchClient;
 exports.ServerError = ServerError;
@@ -5087,5 +5461,5 @@ exports.matchRoute = matchRoute;
 exports.serviceInstructedDelayMs = serviceInstructedDelayMs;
 exports.sleep = sleep;
 exports.validateFile = validateFile;
-//# sourceMappingURL=chunk-GCMQUM6N.cjs.map
-//# sourceMappingURL=chunk-GCMQUM6N.cjs.map
+//# sourceMappingURL=chunk-VH2DE7HZ.cjs.map
+//# sourceMappingURL=chunk-VH2DE7HZ.cjs.map