@relyio/sdk 0.5.0 → 0.7.0

package/dist/{chunk-5AZUUV5B.js → chunk-GYHAVYND.js}

@@ -1,4 +1,5 @@
 import { parseDevEnv, DEV_CONTEXT_DIR, DEV_CONTEXT_FILENAME, parseDevContextFile } from './chunk-BBUB7C2Z.js';
+import { isBrowser } from './chunk-H6IBQSMM.js';
 import { __name, __publicField } from './chunk-XQ4QHWZE.js';
 
 /* RelyIO SDK - Built with ❤️ by the RelyIO Team */
@@ -69,44 +70,6 @@ var _SDKError = class _SDKError extends Error {
 __name(_SDKError, "SDKError");
 var SDKError = _SDKError;
 
-// src/errors/auth-errors.ts
-var _AuthenticationError = class _AuthenticationError extends SDKError {
-  constructor(message = "Authentication failed", statusCode = 401, cause, context) {
-    super(message, statusCode, cause, context);
-    __publicField(this, "code", "AUTHENTICATION_ERROR");
-    __publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "Authentication failed. Please check your API key and try again.";
-  }
-};
-__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);
-    __publicField(this, "code", "AUTHORIZATION_ERROR");
-    __publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "You do not have permission to access this resource.";
-  }
-};
-__name(_AuthorizationError, "AuthorizationError");
-var AuthorizationError = _AuthorizationError;
-var _InvalidApiKeyError = class _InvalidApiKeyError extends SDKError {
-  constructor(message = "Invalid API key", cause, context) {
-    super(message, 401, cause, context);
-    __publicField(this, "code", "INVALID_API_KEY");
-    __publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "Invalid API key. Please check your API key and try again.";
-  }
-};
-__name(_InvalidApiKeyError, "InvalidApiKeyError");
-var InvalidApiKeyError = _InvalidApiKeyError;
-
 // src/errors/contract-errors.ts
 var _MissingApiKeyError = class _MissingApiKeyError extends SDKError {
   constructor(message = "No API key was sent", context) {
@@ -267,6 +230,32 @@ var _UnknownContractError = class _UnknownContractError extends SDKError {
 __name(_UnknownContractError, "UnknownContractError");
 var UnknownContractError = _UnknownContractError;
 
+// src/errors/auth-errors.ts
+var _AuthorizationError = class _AuthorizationError extends SDKError {
+  constructor(message = "Authorization failed", statusCode = 403, cause, context) {
+    super(message, statusCode, cause, context);
+    __publicField(this, "code", "AUTHORIZATION_ERROR");
+    __publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    return "You do not have permission to access this resource.";
+  }
+};
+__name(_AuthorizationError, "AuthorizationError");
+var AuthorizationError = _AuthorizationError;
+var _InvalidApiKeyError = class _InvalidApiKeyError extends SDKError {
+  constructor(message = "Invalid API key", cause, context) {
+    super(message, 401, cause, context);
+    __publicField(this, "code", "INVALID_API_KEY");
+    __publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    return "Invalid API key. Please check your API key and try again.";
+  }
+};
+__name(_InvalidApiKeyError, "InvalidApiKeyError");
+var InvalidApiKeyError = _InvalidApiKeyError;
+
 // src/errors/content-errors.ts
 var _ResourceNotFoundError = class _ResourceNotFoundError extends SDKError {
   constructor(message = "Resource not found", statusCode = 404, cause, context) {
@@ -328,8 +317,12 @@ var _NetworkError = class _NetworkError extends SDKError {
 __name(_NetworkError, "NetworkError");
 var NetworkError = _NetworkError;
 var _TimeoutError = class _TimeoutError extends SDKError {
-  constructor(message = "Request timed out", timeout, statusCode, cause) {
-    super(message, statusCode, cause, { timeout });
+  /**
+   * @param context - Carried beside `timeout`. The mapper passes a `REQUEST_TIMEOUT` refusal's body
+   *   as `context.response`, as it does for every other contract code.
+   */
+  constructor(message = "Request timed out", timeout, statusCode, cause, context) {
+    super(message, statusCode, cause, { ...context, timeout });
     __publicField(this, "code", "TIMEOUT_ERROR");
     __publicField(this, "retryable", true);
   }
@@ -355,8 +348,13 @@ var ConnectionError = _ConnectionError;
 
 // src/errors/validation-errors.ts
 var _BaseValidationError = class _BaseValidationError extends SDKError {
-  constructor(message = "Validation failed", violations = [], statusCode = 400, cause) {
-    super(message, statusCode, cause, { violations });
+  /**
+   * @param context - Carried beside `violations`. The mapper passes the refusal body as
+   *   `context.response`, as it does for every other contract code, so a consumer that hands the
+   *   service's own words on can read them here too.
+   */
+  constructor(message = "Validation failed", violations = [], statusCode = 400, cause, context) {
+    super(message, statusCode, cause, { ...context, violations });
     __publicField(this, "retryable", false);
     __publicField(this, "violations");
     this.violations = violations;
@@ -401,8 +399,8 @@ var _ValidationError = class _ValidationError extends BaseValidationError {
 __name(_ValidationError, "ValidationError");
 var ValidationError = _ValidationError;
 var _InvalidPayloadError = class _InvalidPayloadError extends BaseValidationError {
-  constructor(message = "Invalid payload", violations = [], cause) {
-    super(message, violations, 400, cause);
+  constructor(message = "Invalid payload", violations = [], cause, context) {
+    super(message, violations, 400, cause, context);
     __publicField(this, "code", "INVALID_PAYLOAD");
   }
   getUserMessage() {
@@ -411,58 +409,6 @@ var _InvalidPayloadError = class _InvalidPayloadError extends BaseValidationErro
 };
 __name(_InvalidPayloadError, "InvalidPayloadError");
 var InvalidPayloadError = _InvalidPayloadError;
-var _SchemaValidationError = class _SchemaValidationError extends BaseValidationError {
-  constructor(message = "Schema validation failed", violations = [], cause) {
-    super(message, violations, 400, cause);
-    __publicField(this, "code", "SCHEMA_VALIDATION_ERROR");
-  }
-  getUserMessage() {
-    return "The data does not match the expected schema. Please check your content structure.";
-  }
-};
-__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);
-    __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.`;
-  }
-};
-__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
-    );
-    __publicField(this, "code", "INVALID_FIELD_TYPE");
-  }
-  getUserMessage() {
-    const violation = this.violations[0];
-    return `The field "${violation?.field}" has an invalid type. ${violation?.message}.`;
-  }
-};
-__name(_InvalidFieldTypeError, "InvalidFieldTypeError");
-var InvalidFieldTypeError = _InvalidFieldTypeError;
 
 // ../../platform/api-contract/dist/index.js
 var HEADER_RETRY_AFTER = { name: "Retry-After" };
@@ -591,10 +537,10 @@ var _ErrorMapper = class _ErrorMapper {
         );
       }
       case "REQUEST_INVALID": {
-        return new InvalidPayloadError(message, violationsOf(refusal));
+        return new InvalidPayloadError(message, violationsOf(refusal), void 0, context);
       }
       case "CONTENT_INVALID": {
-        return new ValidationError(message, violationsOf(refusal), 400);
+        return new ValidationError(message, violationsOf(refusal), 400, void 0, context);
       }
       case "METHOD_NOT_ALLOWED": {
         return new MethodNotAllowedError(message, context);
@@ -617,7 +563,7 @@ var _ErrorMapper = class _ErrorMapper {
         return new ResourceExpiredError(message, 410, void 0, context);
       }
       case "REQUEST_TIMEOUT": {
-        return new TimeoutError(message, void 0, void 0, void 0);
+        return new TimeoutError(message, void 0, status, void 0, context);
       }
       case "PAYLOAD_TOO_LARGE": {
         return new PayloadTooLargeError(message, detailNumber(refusal, "limitBytes"), context);
@@ -840,20 +786,43 @@ function readQuery(searchParams) {
 }
 __name(readQuery, "readQuery");
 
-// src/http/retry-policy.ts
-var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
-  "GET",
-  "HEAD",
-  "OPTIONS",
-  "PUT",
-  "DELETE",
-  "TRACE"
-]);
-function isReplaySafe(request) {
-  if (IDEMPOTENT_METHODS.has(request.method.toUpperCase())) return true;
-  return headerValue(request.headers, HEADER_IDEMPOTENCY_KEY.name) !== void 0;
+// src/http/abortable-sleep.ts
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (isAborted(signal)) {
+      resolve();
+      return;
+    }
+    const done = /* @__PURE__ */ __name(() => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }, "done");
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
 }
-__name(isReplaySafe, "isReplaySafe");
+__name(sleep, "sleep");
+function isAborted(signal) {
+  return signal?.aborted === true;
+}
+__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;
+}
+__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)}`
+  );
+}
+__name(assertRequestTimeout, "assertRequestTimeout");
+
+// src/errors/instructed-delay.ts
 function serviceInstructedDelayMs(error, nowMs) {
   if (error instanceof ServiceIndeterminateError) {
     return error.retryAfterMs;
@@ -867,6 +836,21 @@ function serviceInstructedDelayMs(error, nowMs) {
   return wait > 0 ? wait : void 0;
 }
 __name(serviceInstructedDelayMs, "serviceInstructedDelayMs");
+
+// src/http/retry-policy.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "HEAD",
+  "OPTIONS",
+  "PUT",
+  "DELETE",
+  "TRACE"
+]);
+function isReplaySafe(request) {
+  if (IDEMPOTENT_METHODS.has(request.method.toUpperCase())) return true;
+  return headerValue(request.headers, HEADER_IDEMPOTENCY_KEY.name) !== void 0;
+}
+__name(isReplaySafe, "isReplaySafe");
 var _DefaultRetryPolicy = class _DefaultRetryPolicy {
   constructor(config) {
     __publicField(this, "config");
@@ -891,42 +875,31 @@ var DefaultRetryPolicy = _DefaultRetryPolicy;
 // src/http/http-client.ts
 var _HttpClient = class _HttpClient {
   constructor(config) {
-    __publicField(this, "baseUrl");
-    __publicField(this, "defaultHeaders");
-    __publicField(this, "timeout");
-    __publicField(this, "retryPolicy");
-    __publicField(this, "debug");
-    __publicField(this, "logger");
-    __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;
-    this.defaultHeaders = {
-      "Content-Type": "application/json",
-      "X-API-Key": config.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. */
+    __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: isBrowser() ? "browser" : "node"
     });
   }
   /**
@@ -963,17 +936,34 @@ 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) — 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 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 }
+      );
+    }
     this.log("debug", "Making request", {
       method: mergedConfig.method,
       url: mergedConfig.url
       // 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 {
@@ -992,10 +982,10 @@ 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 this.sleep(delay, config.signal);
+          await sleep(delay, config.signal);
           continue;
         }
         const sdkError = ErrorMapper.mapGenericError(failure, {
@@ -1065,34 +1055,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.
@@ -1114,7 +1130,7 @@ var _HttpClient = class _HttpClient {
     const timeoutId = setTimeout(() => {
       timedOut = true;
       controller.abort();
-    }, config.timeout ?? this.timeout);
+    }, config.timeout ?? this.connection.timeout);
     const onCallerAbort = /* @__PURE__ */ __name(() => controller.abort(), "onCallerAbort");
     caller?.addEventListener("abort", onCallerAbort, { once: true });
     try {
@@ -1124,10 +1140,15 @@ var _HttpClient = class _HttpClient {
         headers: filteredHeaders,
         body: this.prepareRequestBody(config),
         signal: controller.signal,
-        // Include credentials for CORS requests if in browser and configured
-        ...typeof window !== "undefined" && this.config.browser.includeCredentials != null && { credentials: "include" }
+        // 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`.
+        ...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);
@@ -1160,10 +1181,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(
@@ -1177,9 +1196,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 (isBrowser() && onCorsError) {
           try {
-            this.config.browser.onCorsError(corsError, {
+            onCorsError(corsError, {
               url: config.url,
               method: config.method,
               originalError: error
@@ -1196,20 +1216,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 (!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
@@ -1245,7 +1265,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);
@@ -1254,11 +1274,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) {
@@ -1281,26 +1301,11 @@ var _HttpClient = class _HttpClient {
     });
     return obj;
   }
-  /** A backoff the caller's abort cuts short; the next attempt then refuses to send. */
-  sleep(ms, signal) {
-    return new Promise((resolve) => {
-      if (isAborted(signal)) {
-        resolve();
-        return;
-      }
-      const done = /* @__PURE__ */ __name(() => {
-        clearTimeout(timer);
-        signal?.removeEventListener("abort", done);
-        resolve();
-      }, "done");
-      const timer = setTimeout(done, ms);
-      signal?.addEventListener("abort", done, { once: true });
-    });
-  }
   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 ?? "");
     }
@@ -1308,17 +1313,105 @@ var _HttpClient = class _HttpClient {
 };
 __name(_HttpClient, "HttpClient");
 var HttpClient = _HttpClient;
-function isAborted(signal) {
-  return signal?.aborted === true;
+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": 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
+    })
+  };
 }
-__name(isAborted, "isAborted");
+__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;
+}
+__name(layerHeaders, "layerHeaders");
+function presentKey(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+__name(presentKey, "presentKey");
+function credentialsModeFor(includeCredentials) {
+  return includeCredentials ? "include" : "same-origin";
+}
+__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;
+}
+__name(callLocale, "callLocale");
+function readClientLocale(locale) {
+  return typeof locale === "function" ? locale : () => locale;
+}
+__name(readClientLocale, "readClientLocale");
 
 // src/content/query-builder.ts
+function namesMetadata(key) {
+  return key === "_metadata" || key.startsWith("_metadata.");
+}
+__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`
+    }))
+  );
+}
+__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;
     __publicField(this, "queryOptions", {});
     __publicField(this, "localeValue");
     __publicField(this, "localesArray");
@@ -1327,11 +1420,26 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     __publicField(this, "childrenOptions");
     __publicField(this, "pageNumber");
     __publicField(this, "pageSizeValue");
+    __publicField(this, "requestHeaders");
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    __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
+   * the key can see. A name the client already sends is replaced for this query only; the client
+   * is not changed.
+   */
+  headers(headers) {
+    this.requestHeaders = headers;
+    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
@@ -1524,7 +1632,11 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     const response = await this.httpClient.send(
       "/v1/{contentType}",
       "get",
-      { path: { contentType: this.contentType }, query: this.buildQueryParams() }
+      {
+        path: { contentType: this.contentType },
+        query: this.buildQueryParams(),
+        headers: this.requestHeaders
+      }
     );
     return response.body;
   }
@@ -1584,7 +1696,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;
@@ -1592,6 +1708,7 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     cloned.fieldsProjection = this.fieldsProjection ? [...this.fieldsProjection] : void 0;
     cloned.pageNumber = this.pageNumber;
     cloned.pageSizeValue = this.pageSizeValue;
+    cloned.requestHeaders = this.requestHeaders ? { ...this.requestHeaders } : void 0;
     return cloned;
   }
   /**
@@ -1658,14 +1775,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;
@@ -1689,16 +1807,23 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
 __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;
     __publicField(this, "includeRelations");
     __publicField(this, "localeValue");
     __publicField(this, "localesArray");
     __publicField(this, "fetchAllLocales", false);
     __publicField(this, "childrenOptions");
+    __publicField(this, "requestHeaders");
+    /** The client's locale, asked when the read is sent rather than copied when it was built. */
+    __publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Include related content in the response
@@ -1729,6 +1854,15 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
     this.fetchAllLocales = false;
     return this;
   }
+  /**
+   * Headers this one read adds to the client's own, e.g. `X-RelyIO-Dataset` to read another dataset
+   * the key can see. A name the client already sends is replaced for this request only; the client
+   * is not changed.
+   */
+  headers(headers) {
+    this.requestHeaders = headers;
+    return this;
+  }
   /**
    * Fetch content in all available locales
    * Returns default locale at top level, others in _metadata.localizations
@@ -1759,14 +1893,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) {
@@ -1782,7 +1917,11 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
       return await this.httpClient.fetchPayload(
         "/v1/{contentType}/{id}",
         "get",
-        { path: { contentType: this.contentType, id: this.id }, query: params }
+        {
+          path: { contentType: this.contentType, id: this.id },
+          query: params,
+          headers: this.requestHeaders
+        }
       );
     } catch (error) {
       if (isResourceNotFound(error)) return null;
@@ -1812,6 +1951,14 @@ function writeHeaders(options) {
   return Object.keys(headers).length > 0 ? headers : void 0;
 }
 __name(writeHeaders, "writeHeaders");
+function requestHeaders(headers, typed) {
+  if (headers === void 0) return typed;
+  if (typed === void 0) return headers;
+  const typedNames = new Set(Object.keys(typed).map((name) => name.toLowerCase()));
+  const own = Object.entries(headers).filter(([name]) => !typedNames.has(name.toLowerCase()));
+  return { ...Object.fromEntries(own), ...typed };
+}
+__name(requestHeaders, "requestHeaders");
 function entityTagOf(response) {
   return headerValue(response.headers, HEADER_ENTITY_TAG.name);
 }
@@ -1819,22 +1966,28 @@ __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. */
+    __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
@@ -1881,7 +2034,8 @@ var _ContentClient = class _ContentClient {
   /**
    * Fetch a single content item by ID
    * @param id - Entry ID or slug
-   * @param options - Fetch options (include, locale)
+   * @param options - Fetch options (include, locale, and `headers` this one request adds — e.g.
+   *   `{ 'X-RelyIO-Dataset': 'staging' }` to read a dataset other than the client's)
    */
   async fetchOne(id, options) {
     const builder = this.findById(id);
@@ -1891,6 +2045,9 @@ var _ContentClient = class _ContentClient {
     if (options?.locale != null && options.locale !== "") {
       builder.locale(options.locale);
     }
+    if (options?.headers != null) {
+      builder.headers(options.headers);
+    }
     return builder.execute();
   }
   /**
@@ -1905,16 +2062,21 @@ var _ContentClient = class _ContentClient {
    * `entityTag` is `undefined` when the response came from the cache: a cached
    * body cannot know the current version, and an absent tag beats a stale one
    * that would refuse the next write.
+   *
+   * Unlike {@link fetchOne}, a missing entry is not `null`: the service's
+   * `RESOURCE_NOT_FOUND` is thrown as it arrived, with the `kind` that says
+   * whether the entry, the content type or the schema was missing. `headers`
+   * are the ones this read adds, as for `fetchOne`.
    */
   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}",
       "get",
-      { path: { contentType: this.contentType, id }, query }
+      { path: { contentType: this.contentType, id }, query, headers: options?.headers }
     );
     return { entry: readPayload(response.body), entityTag: entityTagOf(response) };
   }
@@ -1936,17 +2098,21 @@ var _ContentClient = class _ContentClient {
   /**
    * Create a new content item
    * @param data - Content data
-   * @param options - Create options (slug, locale, parentId, sortOrder)
+   * @param options - Create options (slug, locale, parentId, sortOrder), and `headers` this one
+   *   request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset other than the
+   *   client's. They are sent, never put in the body; `idempotencyKey` still wins over an
+   *   `Idempotency-Key` among them. `locale` defaults to the client's own (`withLocale()`).
    */
   async create(data, options) {
-    const { idempotencyKey, ...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 },
-        headers: writeHeaders({ idempotencyKey })
+        body: { content: data, ...body, ...sent === void 0 ? {} : { locale: sent } },
+        headers: requestHeaders(headers, writeHeaders({ idempotencyKey }))
       }
     );
   }
@@ -1954,17 +2120,21 @@ var _ContentClient = class _ContentClient {
    * Update a content item by ID (partial update)
    * @param id - Entry ID
    * @param data - Fields to update
-   * @param options - Update options (slug, locale, parentId, sortOrder)
+   * @param options - Update options (slug, locale, parentId, sortOrder), and `headers` this one
+   *   request adds, as for {@link create}. `ifMatch` and `idempotencyKey` win over the same
+   *   header among them. `locale` defaults to the client's own, the locale whose entity tag
+   *   {@link fetchOneWithTag} reads, so the tag it hands back is checked against the same locale.
    */
   async update(id, data, options) {
-    const { idempotencyKey, ifMatch, ...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 },
-        headers: writeHeaders({ idempotencyKey, ifMatch })
+        body: { content: data, ...body, ...sent === void 0 ? {} : { locale: sent } },
+        headers: requestHeaders(headers, writeHeaders({ idempotencyKey, ifMatch }))
       }
     );
   }
@@ -1995,32 +2165,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 }
     });
   }
   /**
@@ -2059,8 +2232,9 @@ var _ContentClient = class _ContentClient {
     if (options?.include != null) {
       params.include = options.include.join(",");
     }
-    if (options?.locale != null && options.locale !== "") {
-      params.locale = options.locale;
+    const locale = options?.locale ?? this.clientLocale();
+    if (locale != null && locale !== "") {
+      params.locale = locale;
     }
     return this.httpClient.fetchPayload(
       "/v1/{contentType}/{id}/children",
@@ -2078,19 +2252,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();
   }
 };
 __name(_ContentClient, "ContentClient");
@@ -2099,7 +2274,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 });
     __publicField(this, "code");
     __publicField(this, "retryable");
     this.code = code;
@@ -2146,11 +2321,52 @@ function validateFile(file, constraints = {}) {
 }
 __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)}`
+    );
+  }
+}
+__name(assertWaitOptions, "assertWaitOptions");
 function hasText(value) {
   return value != null && value !== "";
 }
 __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 }
+    }
+  );
+}
+__name(processingFailure, "processingFailure");
 async function computeSha256Hex(blob) {
   try {
     const subtle = globalThis.crypto?.subtle;
@@ -2166,11 +2382,17 @@ async function computeSha256Hex(blob) {
 }
 __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. */
+    __publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * The path parameters every `/file/*` route on this builder takes.
@@ -2183,7 +2405,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
@@ -2242,7 +2473,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
         partNumber: target.partNumber,
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
   }
@@ -2253,7 +2484,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;
@@ -2266,7 +2497,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)
       }
     });
   }
@@ -2277,7 +2508,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       body: {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
   }
@@ -2297,6 +2528,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.
@@ -2335,14 +2585,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,
@@ -2352,15 +2619,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));
@@ -2370,11 +2646,14 @@ var _AssetFileBuilder = class _AssetFileBuilder {
 __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;
     __publicField(this, "_fileName");
     __publicField(this, "_visibility");
     __publicField(this, "_locale");
@@ -2386,6 +2665,9 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     __publicField(this, "_onProgress");
     __publicField(this, "_validate");
     __publicField(this, "_maxPartRetries", 3);
+    /** The client's locale, read once when the upload starts. */
+    __publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /** Subscribe to client → storage upload progress (single PUT + multipart). */
   onProgress(callback) {
@@ -2435,8 +2717,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 {
@@ -2451,7 +2739,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) {
@@ -2462,7 +2751,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 } : {},
@@ -2613,17 +2902,26 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
 __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. */
+    __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. */
@@ -2632,7 +2930,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. */
@@ -2653,28 +2951,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 })
       }
     );
@@ -2688,21 +2992,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);
   }
@@ -2718,11 +3025,18 @@ __name(isAssetEntry, "isAssetEntry");
 
 // src/content/singleton-client.ts
 var _SingletonClient = class _SingletonClient {
-  constructor(httpClient, singletonKey) {
+  /**
+   * @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;
     __publicField(this, "includeFields");
     __publicField(this, "localeValue");
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    __publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Include reference fields in the response
@@ -2745,11 +3059,6 @@ var _SingletonClient = class _SingletonClient {
    * @param options - Optional fetch options (alternative to fluent methods)
    */
   async fetch(options) {
-    const includeValue = options?.include ?? this.includeFields;
-    options?.locale ?? this.localeValue;
-    if (includeValue) {
-      includeValue.join(",");
-    }
     try {
       return (await this.fetchWithTag(options)).content;
     } catch (error) {
@@ -2767,7 +3076,7 @@ var _SingletonClient = class _SingletonClient {
   async fetchWithTag(options) {
     const query = {};
     const includeValue = options?.include ?? this.includeFields;
-    const localeValueFinal = options?.locale ?? this.localeValue;
+    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(
@@ -2781,11 +3090,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",
@@ -2814,15 +3124,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;
@@ -2830,20 +3142,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
    */
@@ -2864,11 +3181,18 @@ var SingletonClient = _SingletonClient;
 
 // src/content/settings-client.ts
 var _SettingsClient = class _SettingsClient {
-  constructor(httpClient, groupId) {
+  /**
+   * @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;
     __publicField(this, "includeFields");
     __publicField(this, "localeValue");
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    __publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Include reference fields in the response
@@ -2891,11 +3215,6 @@ var _SettingsClient = class _SettingsClient {
    * @param options - Optional fetch options (alternative to fluent methods)
    */
   async fetch(options) {
-    const includeValue = options?.include ?? this.includeFields;
-    options?.locale ?? this.localeValue;
-    if (includeValue) {
-      includeValue.join(",");
-    }
     try {
       return (await this.fetchWithTag(options)).settings;
     } catch (error) {
@@ -2905,12 +3224,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",
@@ -2925,7 +3252,7 @@ var _SettingsClient = class _SettingsClient {
   async fetchWithTag(options) {
     const query = {};
     const includeValue = options?.include ?? this.includeFields;
-    const localeValueFinal = options?.locale ?? this.localeValue;
+    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(
@@ -2937,16 +3264,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)
       }
     );
@@ -2977,15 +3308,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;
@@ -2993,20 +3326,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
    */
@@ -3027,14 +3365,31 @@ var SettingsClient = _SettingsClient;
 
 // src/search/search-client.ts
 var _SearchBuilder = class _SearchBuilder {
-  constructor(httpClient, query) {
+  /**
+   * @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, locale) {
     this.httpClient = httpClient;
     __publicField(this, "query");
     __publicField(this, "searchOptions", {});
+    __publicField(this, "requestHeaders");
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    __publicField(this, "clientLocale");
     this.query = query;
+    this.clientLocale = readClientLocale(locale);
   }
   /**
-   * Search within a single content type
+   * Headers this search adds to the client's own, e.g. `X-RelyIO-Dataset` to search another
+   * dataset the key can see. A name the client already sends is replaced for this search only.
+   */
+  headers(headers) {
+    this.requestHeaders = headers;
+    return this;
+  }
+  /**
+   * Search within a single content type. Where a schema types the client, the name is one of its
+   * content types and the results are that type's entries.
    * @param contentType - Content type to search in
    */
   in(contentType) {
@@ -3043,7 +3398,8 @@ var _SearchBuilder = class _SearchBuilder {
     return this;
   }
   /**
-   * Search across multiple content types
+   * Search across multiple content types. Where a schema types the client, the names are its content
+   * types and the results are a union of their entries — every type's, for `'*'`.
    * @param contentTypes - Array of content types or '*' for all
    */
   across(contentTypes) {
@@ -3052,10 +3408,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
@@ -3078,6 +3436,16 @@ var _SearchBuilder = class _SearchBuilder {
     this.searchOptions.fields = projection;
     return this;
   }
+  /**
+   * Order the results by a field instead of by relevance. Called again, it adds a tie-breaker.
+   * `_score` names relevance itself.
+   * @param field - Field path to sort by (e.g. `updatedAt`, `pricing.basePrice`)
+   * @param direction - `asc` or `desc` (the route's default is `desc`)
+   */
+  sort(field, direction = "desc") {
+    this.searchOptions.sort = [...this.searchOptions.sort ?? [], { field, direction }];
+    return this;
+  }
   /**
    * Limit number of results
    * @param count - Maximum results
@@ -3138,6 +3506,9 @@ var _SearchBuilder = class _SearchBuilder {
     if (this.searchOptions.fields) {
       body.fields = this.searchOptions.fields;
     }
+    if (this.searchOptions.sort) {
+      body.sort = this.searchOptions.sort;
+    }
     if (this.searchOptions.limit !== void 0) {
       body.limit = this.searchOptions.limit;
     }
@@ -3150,13 +3521,14 @@ var _SearchBuilder = class _SearchBuilder {
     if (this.searchOptions.explain === true) {
       body.explain = true;
     }
-    if (this.searchOptions.locale != null && this.searchOptions.locale !== "") {
-      body.locale = this.searchOptions.locale;
+    const locale = this.searchOptions.locale ?? this.clientLocale();
+    if (locale != null && locale !== "") {
+      body.locale = locale;
     }
     const response = await this.httpClient.send(
       "/v1/search",
       "post",
-      { body }
+      { body, headers: this.requestHeaders }
     );
     return response.body;
   }
@@ -3176,11 +3548,18 @@ var _SearchBuilder = class _SearchBuilder {
 __name(_SearchBuilder, "SearchBuilder");
 var SearchBuilder = _SearchBuilder;
 var _AutocompleteBuilder = class _AutocompleteBuilder {
-  constructor(httpClient, query) {
+  /**
+   * @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, locale) {
     this.httpClient = httpClient;
     __publicField(this, "query");
     __publicField(this, "autocompleteOptions", {});
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    __publicField(this, "clientLocale");
     this.query = query;
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Autocomplete within a content type
@@ -3206,10 +3585,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
@@ -3256,8 +3637,9 @@ var _AutocompleteBuilder = class _AutocompleteBuilder {
     if (this.autocompleteOptions.limit !== void 0) {
       body.limit = this.autocompleteOptions.limit;
     }
-    if (this.autocompleteOptions.locale != null && this.autocompleteOptions.locale !== "") {
-      body.locale = this.autocompleteOptions.locale;
+    const locale = this.autocompleteOptions.locale ?? this.clientLocale();
+    if (locale != null && locale !== "") {
+      body.locale = locale;
     }
     const response = await this.httpClient.send("/v1/search/autocomplete", "post", { body });
     return response.body;
@@ -3272,11 +3654,27 @@ var _AutocompleteBuilder = class _AutocompleteBuilder {
 __name(_AutocompleteBuilder, "AutocompleteBuilder");
 var AutocompleteBuilder = _AutocompleteBuilder;
 var _SimilarBuilder = class _SimilarBuilder {
-  constructor(httpClient, sourceId) {
+  /**
+   * @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, locale) {
     this.httpClient = httpClient;
     __publicField(this, "sourceId");
     __publicField(this, "similarOptions", {});
+    __publicField(this, "requestHeaders");
+    /** The client's locale, asked when the read is sent rather than copied when it was built. */
+    __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
+   * the key can see. A name the client already sends is replaced for this read only.
+   */
+  headers(headers) {
+    this.requestHeaders = headers;
+    return this;
   }
   /**
    * Find similar content within a content type
@@ -3284,19 +3682,24 @@ var _SimilarBuilder = class _SimilarBuilder {
    */
   in(contentType) {
     this.similarOptions.contentType = contentType;
+    this.similarOptions.contentTypes = void 0;
     return this;
   }
   /**
-   * Add filter conditions
-   * @param conditions - Filter conditions
+   * Find similar content across several content types, or `'*'` for every type
+   * @param contentTypes - Array of content types or '*' for all
    */
-  where(conditions) {
-    this.similarOptions.where = {
-      ...this.similarOptions.where,
-      ...conditions
-    };
+  across(contentTypes) {
+    this.similarOptions.contentTypes = contentTypes;
+    this.similarOptions.contentType = void 0;
     return this;
   }
+  /*
+   * 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()`.
+   */
   /**
    * Limit number of results
    * @param count - Maximum results
@@ -3317,26 +3720,30 @@ var _SimilarBuilder = class _SimilarBuilder {
    * Execute the similar query
    */
   async execute() {
-    if (this.similarOptions.contentType == null || this.similarOptions.contentType === "") {
-      throw new Error('Content type is required for similar search. Use .in("contentType")');
+    const { contentType, contentTypes } = this.similarOptions;
+    if ((contentType == null || contentType === "") && contentTypes == null) {
+      throw new Error(
+        'Content type is required for similar search. Use .in("contentType") or .across("*")'
+      );
     }
-    const body = {
-      source: this.sourceId,
-      contentType: this.similarOptions.contentType
-    };
-    if (this.similarOptions.where && Object.keys(this.similarOptions.where).length > 0) {
-      body.where = this.similarOptions.where;
+    const body = { source: this.sourceId };
+    if (contentType != null && contentType !== "") {
+      body.contentType = contentType;
+    }
+    if (contentTypes != null) {
+      body.contentTypes = contentTypes;
     }
     if (this.similarOptions.limit !== void 0) {
       body.limit = this.similarOptions.limit;
     }
-    if (this.similarOptions.locale != null && this.similarOptions.locale !== "") {
-      body.locale = this.similarOptions.locale;
+    const locale = this.similarOptions.locale ?? this.clientLocale();
+    if (locale != null && locale !== "") {
+      body.locale = locale;
     }
     const response = await this.httpClient.send(
       "/v1/search/similar",
       "post",
-      { body }
+      { body, headers: this.requestHeaders }
     );
     return response.body;
   }
@@ -3356,37 +3763,37 @@ var _SimilarBuilder = class _SimilarBuilder {
 __name(_SimilarBuilder, "SimilarBuilder");
 var SimilarBuilder = _SimilarBuilder;
 var _SearchClient = class _SearchClient {
-  constructor(httpClient) {
+  /**
+   * @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, locale) {
     this.httpClient = httpClient;
+    /** The client's locale, handed to every builder here to ask when it sends. */
+    __publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Start a search query
    * @param query - Search query string
    */
   search(query) {
-    return new SearchBuilder(this.httpClient, query);
+    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);
+    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);
-  }
-  /**
-   * 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);
   }
 };
 __name(_SearchClient, "SearchClient");
@@ -3394,7 +3801,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;
     __publicField(this, "operations", []);
     __publicField(this, "defaultOptions", {
@@ -3403,6 +3815,18 @@ var _BatchBuilder = class _BatchBuilder {
       returnData: true,
       continueOnError: true
     });
+    __publicField(this, "requestHeaders");
+    /** The client's locale, asked as each operation is added rather than copied when this was built. */
+    __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
@@ -3418,7 +3842,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "POST",
       path: `/${contentType}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3438,7 +3862,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PATCH",
       path: `/${contentType}/${entryId}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3458,7 +3882,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PUT",
       path: `/${contentType}/${entryId}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3490,7 +3914,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PATCH",
       path: `/_singletons/${singletonKey}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3505,7 +3929,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "POST",
       path: `/_singletons/${singletonKey}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3513,7 +3937,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) {
@@ -3604,6 +4029,15 @@ var _BatchBuilder = class _BatchBuilder {
     this.defaultOptions.continueOnError = false;
     return this;
   }
+  /**
+   * Headers the batch request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset
+   * other than the client's. They replace the client's own header of the same name for this
+   * request alone, and apply to every operation in it: a batch is one request.
+   */
+  headers(headers) {
+    this.requestHeaders = { ...this.requestHeaders, ...headers };
+    return this;
+  }
   // ==========================================================================
   // EXECUTION
   // ==========================================================================
@@ -3630,9 +4064,10 @@ 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 };
     return cloned;
   }
   /**
@@ -3650,7 +4085,8 @@ var _BatchBuilder = class _BatchBuilder {
     }
     const finalOptions = { ...this.defaultOptions, ...options };
     return this.httpClient.fetchPayload("/v1/batch", "post", {
-      body: { operations: this.operations, options: finalOptions }
+      body: { operations: this.operations, options: finalOptions },
+      headers: this.requestHeaders
     });
   }
   /**
@@ -3681,14 +4117,21 @@ var _BatchBuilder = class _BatchBuilder {
 __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. */
+    __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
@@ -3730,12 +4173,27 @@ __name(_BatchClient, "BatchClient");
 var BatchClient = _BatchClient;
 
 // src/queries/adhoc-query-client.ts
+function withClientLocale(parameters, clientLocale) {
+  if (clientLocale === void 0 || clientLocale === "" || parameters?.locale != null) {
+    return parameters;
+  }
+  return { ...parameters, locale: clientLocale };
+}
+__name(withClientLocale, "withClientLocale");
 var _AdhocQueryBuilder = class _AdhocQueryBuilder {
-  constructor(httpClient) {
+  /**
+   * @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, locale) {
     this.httpClient = httpClient;
     __publicField(this, "queryDef", {});
     __publicField(this, "parameters", {});
     __publicField(this, "options", {});
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    __publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   // ==========================================================================
   // QUERY BLOCKS
@@ -3780,14 +4238,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
   // ==========================================================================
@@ -3964,16 +4414,17 @@ 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
     };
-    if (Object.keys(this.parameters).length > 0) {
-      body.parameters = this.parameters;
+    const parameters = withClientLocale(this.parameters, this.clientLocale());
+    if (parameters !== void 0 && Object.keys(parameters).length > 0) {
+      body.parameters = parameters;
     }
     if (Object.keys(this.options).length > 0) {
       body.options = this.options;
@@ -4004,7 +4455,7 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
    * Clone the builder
    */
   clone() {
-    const cloned = new _AdhocQueryBuilder(this.httpClient);
+    const cloned = new _AdhocQueryBuilder(this.httpClient, this.clientLocale);
     cloned.queryDef = JSON.parse(JSON.stringify(this.queryDef));
     cloned.parameters = { ...this.parameters };
     cloned.options = { ...this.options };
@@ -4014,27 +4465,39 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
 __name(_AdhocQueryBuilder, "AdhocQueryBuilder");
 var AdhocQueryBuilder = _AdhocQueryBuilder;
 var _AdhocQueryClient = class _AdhocQueryClient {
-  constructor(httpClient) {
+  /**
+   * @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, locale) {
     this.httpClient = httpClient;
+    /** The client's locale, asked on every query rather than copied when this client was taken. */
+    __publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Create a new query builder
    */
   build() {
-    return new AdhocQueryBuilder(this.httpClient);
+    return new AdhocQueryBuilder(this.httpClient, this.clientLocale);
   }
   /**
    * Execute a query definition directly
    * @param definition - Query definition
    * @param parameters - Parameter values
    * @param options - Execution options
+   * @param request - `headers` this one request adds to the client's own, e.g. `X-RelyIO-Dataset`
+   *   to query another dataset the key can see. A name the client already sends is replaced for
+   *   this request only.
    */
-  async execute(definition, parameters, options) {
+  async execute(definition, parameters, options, request) {
     const body = {
       query: definition
     };
-    if (parameters && Object.keys(parameters).length > 0) {
-      body.parameters = parameters;
+    const sent = withClientLocale(parameters, this.clientLocale());
+    if (sent !== void 0 && Object.keys(sent).length > 0) {
+      body.parameters = sent;
     }
     if (options && Object.keys(options).length > 0) {
       body.options = options;
@@ -4042,7 +4505,7 @@ var _AdhocQueryClient = class _AdhocQueryClient {
     return this.httpClient.fetchPayload(
       "/v1/query",
       "post",
-      { body }
+      { body, headers: request?.headers }
     );
   }
   /**
@@ -4106,12 +4569,12 @@ async function* pollChanges(http, options = {}) {
   let since = options.since;
   let resynced;
   for (; ; ) {
-    if (aborted(signal)) return;
+    if (isAborted(signal)) return;
     let response;
     try {
       response = await pollOnce(http, since, options);
     } catch (error) {
-      if (aborted(signal)) return;
+      if (isAborted(signal)) return;
       if (!(error instanceof ResourceExpiredError) || since === void 0) throw error;
       const expired = ChangesExpiredError.of(error);
       const onExpired = options.onExpired ?? "throw";
@@ -4129,11 +4592,11 @@ async function* pollChanges(http, options = {}) {
       const expired = resynced;
       resynced = void 0;
       await options.onExpired(expired);
-      if (aborted(signal)) return;
+      if (isAborted(signal)) return;
     }
     for (const change of data) {
       yield change;
-      if (aborted(signal)) return;
+      if (isAborted(signal)) return;
     }
     if (data.length === 0) {
       const wait = parseRetryAfterMs(headerValue(response.headers, "Retry-After"), Date.now());
@@ -4142,6 +4605,21 @@ async function* pollChanges(http, options = {}) {
   }
 }
 __name(pollChanges, "pollChanges");
+async function readChangesHead(http, options = {}) {
+  const response = await http.send("/v1/changes", "get", {
+    query: {},
+    ...options.signal === void 0 ? {} : { signal: options.signal }
+  });
+  const { data, page } = response.body;
+  if (page.nextCursor === null) {
+    throw new Error("GET /v1/changes answered without page.nextCursor");
+  }
+  if (data.length > 0) {
+    throw new Error("GET /v1/changes without since answered changes; a head carries none");
+  }
+  return page.nextCursor;
+}
+__name(readChangesHead, "readChangesHead");
 async function pollOnce(http, since, options) {
   const query = {};
   if (since !== void 0) query.since = since;
@@ -4155,26 +4633,6 @@ async function pollOnce(http, since, options) {
   });
 }
 __name(pollOnce, "pollOnce");
-function sleep(ms, signal) {
-  return new Promise((resolve) => {
-    if (aborted(signal)) {
-      resolve();
-      return;
-    }
-    const done = /* @__PURE__ */ __name(() => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", done);
-      resolve();
-    }, "done");
-    const timer = setTimeout(done, ms);
-    signal?.addEventListener("abort", done, { once: true });
-  });
-}
-__name(sleep, "sleep");
-function aborted(signal) {
-  return signal?.aborted === true;
-}
-__name(aborted, "aborted");
 
 // src/config/dev-detection.ts
 function sandboxStateOf(resolution) {
@@ -4286,7 +4744,7 @@ var DEFAULT_CONFIG = {
   environment: "production",
   headers: {},
   browser: {
-    includeCredentials: true,
+    includeCredentials: false,
     useRelativeUrls: false
   },
   cache: {
@@ -4312,54 +4770,48 @@ var DEFAULT_CONFIG = {
   }
 };
 function validateConfig(config) {
-  if (!config.apiKey || config.apiKey.length === 0) {
-    throw new Error("API key is required");
-  }
-  if (typeof config.apiKey !== "string") {
+  if (config.apiKey != null && typeof config.apiKey !== "string") {
     throw new Error("API key must be a string");
   }
   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)}`
+    );
   }
 }
 __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));
+}
+__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));
+}
+__name(resolveConfigUpdate, "resolveConfigUpdate");
+function withConfiguredKey(configured, apiKey) {
+  return { ...withoutKeyHeader(configured), apiKey };
+}
+__name(withConfiguredKey, "withConfiguredKey");
+function withoutKeyHeader(configured) {
+  return { ...configured, headers: layerHeaders(configured.headers, { [API_KEY_HEADER]: null }) };
+}
+__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(
@@ -4377,30 +4829,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 };
 }
-__name(resolveConfig, "resolveConfig");
+__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);
+}
+__name(withDefaults, "withDefaults");
+function isOptionBag(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__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.
+     */
     __publicField(this, "httpClient");
     __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.
+     */
+    __publicField(this, "configured");
     __publicField(this, "_sandbox");
-    __publicField(this, "_search");
-    __publicField(this, "_batch");
-    __publicField(this, "_adhocQuery");
     __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).
+     */
+    __publicField(this, "currentLocale", /* @__PURE__ */ __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._batch = new BatchClient(this.httpClient);
-    this._adhocQuery = new AdhocQueryClient(this.httpClient);
   }
   // ============================================================================
   // CORE CLIENTS
@@ -4429,10 +4918,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
@@ -4452,7 +4941,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.
@@ -4473,7 +4962,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
@@ -4488,7 +4977,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   singleton(key) {
-    return new SingletonClient(this.httpClient, key);
+    return new SingletonClient(this.httpClient, key, this.currentLocale);
   }
   /**
    * Get a settings client for a specific settings group
@@ -4502,13 +4991,16 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   settings(groupId) {
-    return new SettingsClient(this.httpClient, groupId);
+    return new SettingsClient(this.httpClient, groupId, this.currentLocale);
   }
   // ============================================================================
   // SEARCH OPERATIONS
   // ============================================================================
   /**
-   * Start a search query with full-text, semantic, or hybrid search
+   * Start a search query with full-text, semantic, or hybrid search.
+   *
+   * Where a schema types the client, the results are its entries — every content type's until
+   * `in()` or `across()` narrows them (`INV-SS-TYPES-INFERRED`).
    *
    * @example
    * ```typescript
@@ -4521,7 +5013,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   search(query) {
-    return this._search.search(query);
+    return this.searchClient().search(query);
   }
   /**
    * Start an autocomplete query for search suggestions
@@ -4537,7 +5029,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
@@ -4552,13 +5044,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
@@ -4567,13 +5063,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
@@ -4606,6 +5112,25 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   changes(options = {}) {
     return pollChanges(this.httpClient, options);
   }
+  /**
+   * The dataset's current position in the changes feed, as a cursor to start
+   * `changes({ since })` or `followChanges(…, { since })` from. One
+   * `GET /v1/changes` without a cursor: answered at once, holding nothing.
+   *
+   * Take it **before** you read what you will follow. A write your read did not
+   * see is then after the position and replayed; opening the feed afterwards
+   * without a `since` starts after it and misses it.
+   *
+   * @example
+   * ```typescript
+   * const since = await relyio.changesHead()
+   * const post = await relyio.content('post').findById(id).execute()
+   * for await (const change of relyio.changes({ since, ids: [id] })) { … }
+   * ```
+   */
+  changesHead(options = {}) {
+    return readChangesHead(this.httpClient, options);
+  }
   // ============================================================================
   // QUERY OPERATIONS
   // ============================================================================
@@ -4628,7 +5153,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   adhoc() {
-    return this._adhocQuery.build();
+    return this.query.build();
   }
   /**
    * Execute a predefined query by name (from schema)
@@ -4643,10 +5168,12 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   async executeQuery(queryName, params) {
+    const clientLocale = this.config.locale;
+    const namesLocale = params?.locale != null || params?.locales != null;
     const response = await this.httpClient.request({
       method: "GET",
       url: `/${API_VERSION_SEGMENT}/${String(queryName)}`,
-      params: params ?? {}
+      params: namesLocale || clientLocale === void 0 || clientLocale === "" ? params ?? {} : { ...params, locale: clientLocale }
     });
     const payload = readPayload(response.body);
     return Array.isArray(payload) ? payload : [payload];
@@ -4711,16 +5238,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._batch = new BatchClient(this.httpClient);
-    this._adhocQuery = new AdhocQueryClient(this.httpClient);
+    this.httpClient.configure(this.config);
   }
   /**
    * Get the current configuration
@@ -4729,11 +5293,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)
@@ -4746,7 +5330,13 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   // ============================================================================
   /**
    * Create a locale-scoped client
-   * All content operations on the returned client will use the specified locale
+   *
+   * Every call the returned client builds is in this locale unless the call names one of its own,
+   * which wins: every read — `content()`, `asset()`, `singleton()`, `settings()`, `search()`,
+   * `similar()`, `autocomplete()`, `executeQuery()` and the ad-hoc queries — and every write and
+   * version-history read — `create()` and `update()`, the singleton and settings writes, the asset
+   * file writes, `versions()` and `version()`, and each operation `batch()` builds. `restore()`
+   * always names its locale; a delete, and a `batch().raw()` operation, carry none of the client's.
    *
    * Type-safe when schema is provided: autocompletes valid locale codes!
    *
@@ -4754,9 +5344,11 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```typescript
    * const spanish = relyio.withLocale('es-ES')  // ← Autocompletes with schema!
    *
-   * // All operations use Spanish
+   * // Reads and writes use Spanish
    * const products = await spanish.content('product').query().execute()
    * const homepage = await spanish.singleton('homepage').fetch()
+   * const results = await spanish.search('zapatos').execute()
+   * await spanish.content('product').update(id, { title: 'Zapatos' })
    *
    * // Original client unchanged
    * const englishProducts = await relyio.content('product').query().execute()
@@ -4764,7 +5356,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    */
   withLocale(locale) {
     const newConfig = {
-      ...this.getConfig(),
+      ...this.configured,
       locale,
       schema: this._schema
     };
@@ -4813,6 +5405,6 @@ function createClient(config) {
 }
 __name(createClient, "createClient");
 
-export { AdhocQueryBuilder, AdhocQueryClient, AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthenticationError, AuthorizationError, AutocompleteBuilder, BaseValidationError, BatchBuilder, BatchClient, ChangesExpiredError, ConnectionError, ContentByIdBuilder, ContentClient, ContentQueryBuilder, ErrorMapper, FileUploadError, FileValidationError, HttpClient, InvalidApiKeyError, InvalidFieldTypeError, InvalidPayloadError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PayloadTooLargeError, PlanFeatureUnavailableError, RateLimitError, ReadOnlyKeyError, RequiredFieldError, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, SchemaValidationError, SearchBuilder, SearchClient, ServerError, ServiceIndeterminateError, SettingsClient, SimilarBuilder, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, ValidationError, createClient, entityTagOf, isAssetEntry, isResourceNotFound, matchRoute, validateFile };
-//# sourceMappingURL=chunk-5AZUUV5B.js.map
-//# sourceMappingURL=chunk-5AZUUV5B.js.map
+export { AdhocQueryBuilder, AdhocQueryClient, AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthorizationError, AutocompleteBuilder, BaseValidationError, BatchBuilder, BatchClient, ChangesExpiredError, ConnectionError, ContentByIdBuilder, ContentClient, ContentQueryBuilder, ErrorMapper, FileUploadError, FileValidationError, HttpClient, InvalidApiKeyError, InvalidPayloadError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PayloadTooLargeError, PlanFeatureUnavailableError, RateLimitError, ReadOnlyKeyError, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, SearchBuilder, SearchClient, ServerError, ServiceIndeterminateError, SettingsClient, SimilarBuilder, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, ValidationError, createClient, entityTagOf, isAborted, isAssetEntry, isResourceNotFound, matchRoute, serviceInstructedDelayMs, sleep, validateFile };
+//# sourceMappingURL=chunk-GYHAVYND.js.map
+//# sourceMappingURL=chunk-GYHAVYND.js.map