@relyio/sdk 0.6.0 → 0.8.0

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

@@ -1,6 +1,7 @@
 'use strict';
 
 var chunkLSRPMNPT_cjs = require('./chunk-LSRPMNPT.cjs');
+var chunkTZL374LS_cjs = require('./chunk-TZL374LS.cjs');
 var chunkMWMSFIWN_cjs = require('./chunk-MWMSFIWN.cjs');
 
 /* RelyIO SDK - Built with ❤️ by the RelyIO Team */
@@ -232,18 +233,6 @@ chunkMWMSFIWN_cjs.__name(_UnknownContractError, "UnknownContractError");
 var UnknownContractError = _UnknownContractError;
 
 // src/errors/auth-errors.ts
-var _AuthenticationError = class _AuthenticationError extends SDKError {
-  constructor(message = "Authentication failed", statusCode = 401, cause, context) {
-    super(message, statusCode, cause, context);
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "AUTHENTICATION_ERROR");
-    chunkMWMSFIWN_cjs.__publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "Authentication failed. Please check your API key and try again.";
-  }
-};
-chunkMWMSFIWN_cjs.__name(_AuthenticationError, "AuthenticationError");
-var AuthenticationError = _AuthenticationError;
 var _AuthorizationError = class _AuthorizationError extends SDKError {
   constructor(message = "Authorization failed", statusCode = 403, cause, context) {
     super(message, statusCode, cause, context);
@@ -422,58 +411,45 @@ var _InvalidPayloadError = class _InvalidPayloadError extends BaseValidationErro
 };
 chunkMWMSFIWN_cjs.__name(_InvalidPayloadError, "InvalidPayloadError");
 var InvalidPayloadError = _InvalidPayloadError;
-var _SchemaValidationError = class _SchemaValidationError extends BaseValidationError {
-  constructor(message = "Schema validation failed", violations = [], cause) {
-    super(message, violations, 400, cause);
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "SCHEMA_VALIDATION_ERROR");
+
+// ../../platform/api-contract/dist/chunk-PYZCLRXR.js
+function defineRoute(route) {
+  if (route.kind === "raw" && route.standardShape === void 0) {
+    throw new Error("kind 'raw' requires a named StandardShape");
   }
-  getUserMessage() {
-    return "The data does not match the expected schema. Please check your content structure.";
+  if (route.kind === "raw" && route.success === 302 && !route.headers.some((header) => header.name === "Location")) {
+    throw new Error("a raw route declaring success 302 must declare its 'Location' header");
   }
-};
-chunkMWMSFIWN_cjs.__name(_SchemaValidationError, "SchemaValidationError");
-var SchemaValidationError = _SchemaValidationError;
-var _RequiredFieldError = class _RequiredFieldError extends BaseValidationError {
-  constructor(fieldName, message, cause) {
-    const violation = {
-      field: fieldName,
-      message: message ?? `Field "${fieldName}" is required`,
-      code: "REQUIRED"
-    };
-    super(`Required field "${fieldName}" is missing`, [violation], 400, cause);
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "REQUIRED_FIELD_ERROR");
+  if (route.kind === "stream" && route.stream === void 0) {
+    throw new Error("kind 'stream' requires a StreamDeclaration");
   }
-  getUserMessage() {
-    const violation = this.violations[0];
-    const fieldName = violation?.field;
-    return `The field "${fieldName}" is required and cannot be empty.`;
+  if (route.kind === "collection" && route.page === void 0) {
+    throw new Error("kind 'collection' requires a page dialect");
   }
-};
-chunkMWMSFIWN_cjs.__name(_RequiredFieldError, "RequiredFieldError");
-var RequiredFieldError = _RequiredFieldError;
-var _InvalidFieldTypeError = class _InvalidFieldTypeError extends BaseValidationError {
-  constructor(fieldName, expectedType, actualType, value, cause) {
-    const violation = {
-      field: fieldName,
-      message: `Expected ${expectedType}, got ${actualType}`,
-      code: "INVALID_TYPE",
-      value
-    };
-    super(
-      `Invalid type for field "${fieldName}": expected ${expectedType}, got ${actualType}`,
-      [violation],
-      400,
-      cause
+  if ((route.kind === "object" || route.kind === "collection") && route.negotiated !== void 0) {
+    refuseMismatchedAlternate(route, route.negotiated["text/event-stream"]);
+  }
+  return route;
+}
+chunkMWMSFIWN_cjs.__name(defineRoute, "defineRoute");
+function refuseMismatchedAlternate(route, stream) {
+  if (stream.kind !== "stream") {
+    throw new Error("a negotiated 'text/event-stream' alternate must be kind 'stream'");
+  }
+  if (stream.stream.mediaType !== "text/event-stream") {
+    throw new Error(
+      `a negotiated 'text/event-stream' alternate declares media type "${stream.stream.mediaType}"`
     );
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "INVALID_FIELD_TYPE");
   }
-  getUserMessage() {
-    const violation = this.violations[0];
-    return `The field "${violation?.field}" has an invalid type. ${violation?.message}.`;
+  const own = [...new Set(route.codes)].sort();
+  const alternate = [...new Set(stream.codes)].sort();
+  if (own.length !== alternate.length || own.some((code, index) => code !== alternate[index])) {
+    throw new Error(
+      `a negotiated alternate refuses with [${alternate.join(", ")}] while its route refuses with [${own.join(", ")}]; one route refuses with one set of codes on every transport`
+    );
   }
-};
-chunkMWMSFIWN_cjs.__name(_InvalidFieldTypeError, "InvalidFieldTypeError");
-var InvalidFieldTypeError = _InvalidFieldTypeError;
+}
+chunkMWMSFIWN_cjs.__name(refuseMismatchedAlternate, "refuseMismatchedAlternate");
 
 // ../../platform/api-contract/dist/index.js
 var HEADER_RETRY_AFTER = { name: "Retry-After" };
@@ -482,6 +458,169 @@ var HEADER_IF_MATCH = {
   name: "If-Match"};
 var HEADER_IDEMPOTENCY_KEY = {
   name: "Idempotency-Key"};
+var FRESH_PARAMETER = "_fresh";
+var VISITOR_LIVE_PATH = "/visitor/changes";
+var VISITOR_QUERY = {
+  /** The publishable key. */
+  key: "key",
+  /** A dataset id or name the key reaches; absent, the key's default dataset. */
+  dataset: "dataset",
+  /** The cursor to continue from; absent, the socket starts now. */
+  since: "since",
+  /** Comma-separated content types to keep; absent keeps every type. */
+  types: "types",
+  /** Comma-separated entry ids to keep; absent keeps every entry. */
+  ids: "ids",
+  /** The poll's client id. Required on a poll, and not read on a socket. */
+  client: "client"
+};
+var VISITOR_CURSOR = /^[\w.~-]{1,256}$/;
+var VISITOR_POLL_INTERVAL_MS = 15e3;
+var VISITOR_KEEPALIVE = { request: "ping", response: "pong" };
+var VISITOR_FRAMES = {
+  opened: "feed.opened",
+  changes: "feed.changes",
+  resync: "feed.resync"
+};
+defineRoute({
+  kind: "object",
+  headers: [HEADER_RETRY_AFTER],
+  codes: [
+    "REQUEST_INVALID",
+    "MISSING_API_KEY",
+    "INVALID_API_KEY",
+    "ACCESS_DENIED",
+    "METHOD_NOT_ALLOWED",
+    "SERVICE_INDETERMINATE",
+    "USAGE_QUOTA_EXCEEDED",
+    "RATE_LIMIT_EXCEEDED"
+  ]
+});
+var VISITOR_CLOSE_CODES = {
+  /** A query the door cannot read: a malformed `since`, filter, `dataset` or `client`. */
+  requestInvalid: 4400,
+  /** No publishable key, or one that is unknown, revoked, expired, a secret key or a preview key. */
+  keyRefused: 4401,
+  /** The page's `Origin` is absent, or not on the key's allowed origins. */
+  originRefused: 4403,
+  /** `dataset` names nothing the key reaches. */
+  datasetRefused: 4404,
+  /** The key's scope, the project's counter or the feed could not be reached just now. */
+  unavailable: 1013,
+  /**
+   * The project holds as many visitor connections as its plan allows — Starter's 100 — or its
+   * Organization is suspended. As HTTP's 402: more needs a bigger plan, or visitors leaving.
+   */
+  allowanceReached: 4402,
+  /** This client's address holds as many connections to the project as one address may. */
+  addressLimitReached: 4429,
+  /** The project is at its per-project safety ceiling — Pro's 50,000 — whatever it would pay for. */
+  ceilingReached: 4503
+};
+var VISITOR_CLOSE_RETRY = {
+  4400: "stop",
+  4401: "stop",
+  4403: "stop",
+  4404: "stop",
+  1013: "retry",
+  4402: "back-off",
+  4429: "back-off",
+  4503: "back-off"
+};
+var VISITOR_POLL_RETRY = {
+  REQUEST_INVALID: "stop",
+  MISSING_API_KEY: "stop",
+  INVALID_API_KEY: "stop",
+  ACCESS_DENIED: "stop",
+  METHOD_NOT_ALLOWED: "stop",
+  SERVICE_INDETERMINATE: "retry",
+  USAGE_QUOTA_EXCEEDED: "back-off",
+  RATE_LIMIT_EXCEEDED: "back-off"
+};
+var VISITOR_ADMISSION_RETRY_AFTER_SECONDS = 60;
+function parseVisitorFrame(text) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord2(value) || !isCursor(value.cursor)) return null;
+  switch (value.type) {
+    case VISITOR_FRAMES.opened: {
+      return hasOnly(value, ["type", "cursor"]) ? { type: VISITOR_FRAMES.opened, cursor: value.cursor } : null;
+    }
+    case VISITOR_FRAMES.changes: {
+      const changes = hasOnly(value, ["type", "changes", "cursor"]) ? readVisitorChanges(value.changes) : null;
+      return changes === null ? null : { type: VISITOR_FRAMES.changes, changes, cursor: value.cursor };
+    }
+    case VISITOR_FRAMES.resync: {
+      return hasOnly(value, ["type", "reason", "cursor"]) && isResyncReason(value.reason) ? { type: VISITOR_FRAMES.resync, reason: value.reason, cursor: value.cursor } : null;
+    }
+    default: {
+      return null;
+    }
+  }
+}
+chunkMWMSFIWN_cjs.__name(parseVisitorFrame, "parseVisitorFrame");
+function readVisitorPollAnswer(value) {
+  if (!isRecord2(value) || !isCursor(value.cursor)) return null;
+  if (value.kind === "resync") {
+    return hasOnly(value, ["kind", "reason", "cursor"]) && isResyncReason(value.reason) ? { kind: "resync", reason: value.reason, cursor: value.cursor } : null;
+  }
+  if (value.kind !== "changes" || !hasOnly(value, ["kind", "changes", "cursor"])) return null;
+  const changes = readVisitorChanges(value.changes);
+  return changes === null ? null : { kind: "changes", changes, cursor: value.cursor };
+}
+chunkMWMSFIWN_cjs.__name(readVisitorPollAnswer, "readVisitorPollAnswer");
+var CHANGE_KINDS = /* @__PURE__ */ new Set([
+  "published",
+  "updated",
+  "unpublished",
+  "deleted"
+]);
+var RESYNC_REASONS = /* @__PURE__ */ new Set([
+  "retention",
+  "dataset-replaced",
+  "ahead-of-head",
+  "foreign-cursor",
+  "too-far-behind"
+]);
+function isResyncReason(value) {
+  return typeof value === "string" && RESYNC_REASONS.has(value);
+}
+chunkMWMSFIWN_cjs.__name(isResyncReason, "isResyncReason");
+function readVisitorChanges(value) {
+  if (!Array.isArray(value)) return null;
+  const changes = [];
+  for (const item of value) {
+    if (!isRecord2(item) || !hasOnly(item, ["entryId", "contentType", "locale", "kind"])) return null;
+    const { entryId, contentType, locale, kind } = item;
+    if (!isNonEmptyString2(entryId) || !isNonEmptyString2(contentType)) return null;
+    if (locale !== null && typeof locale !== "string") return null;
+    if (typeof kind !== "string" || !CHANGE_KINDS.has(kind)) return null;
+    changes.push({ entryId, contentType, locale, kind });
+  }
+  return changes;
+}
+chunkMWMSFIWN_cjs.__name(readVisitorChanges, "readVisitorChanges");
+function isCursor(value) {
+  return typeof value === "string" && VISITOR_CURSOR.test(value);
+}
+chunkMWMSFIWN_cjs.__name(isCursor, "isCursor");
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+chunkMWMSFIWN_cjs.__name(isRecord2, "isRecord2");
+function isNonEmptyString2(value) {
+  return typeof value === "string" && value.length > 0;
+}
+chunkMWMSFIWN_cjs.__name(isNonEmptyString2, "isNonEmptyString2");
+function hasOnly(value, keys) {
+  const present = Object.keys(value);
+  return present.length === keys.length && present.every((key) => keys.includes(key));
+}
+chunkMWMSFIWN_cjs.__name(hasOnly, "hasOnly");
 
 // ../../platform/api-contract/dist/client/index.js
 var _a;
@@ -750,6 +889,8 @@ var DECLARED_PATHS = {
   "/health/cache": true,
   "/health/live": true,
   "/health/ready": true,
+  "/internal/live/visitor-feed/{projectId}/{datasetId}/changes": true,
+  "/internal/live/visitor-key": true,
   "/internal/media/claim": true,
   "/internal/media/file-complete": true,
   "/internal/media/progress": true,
@@ -873,6 +1014,20 @@ function isAborted(signal) {
 }
 chunkMWMSFIWN_cjs.__name(isAborted, "isAborted");
 
+// src/http/request-timeout.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+function isTimerDelay(value) {
+  return typeof value === "number" && value >= 1 && value <= MAX_TIMER_DELAY_MS;
+}
+chunkMWMSFIWN_cjs.__name(isTimerDelay, "isTimerDelay");
+function assertRequestTimeout(timeout) {
+  if (isTimerDelay(timeout)) return;
+  throw new Error(
+    `timeout must be a number of milliseconds from 1 to ${MAX_TIMER_DELAY_MS} \u2014 a timer given 0, NaN, Infinity or more fires at once and ends every request \u2014 and got ${String(timeout)}`
+  );
+}
+chunkMWMSFIWN_cjs.__name(assertRequestTimeout, "assertRequestTimeout");
+
 // src/errors/instructed-delay.ts
 function serviceInstructedDelayMs(error, nowMs) {
   if (error instanceof ServiceIndeterminateError) {
@@ -926,43 +1081,31 @@ var DefaultRetryPolicy = _DefaultRetryPolicy;
 // src/http/http-client.ts
 var _HttpClient = class _HttpClient {
   constructor(config) {
-    chunkMWMSFIWN_cjs.__publicField(this, "baseUrl");
-    chunkMWMSFIWN_cjs.__publicField(this, "defaultHeaders");
-    chunkMWMSFIWN_cjs.__publicField(this, "timeout");
-    chunkMWMSFIWN_cjs.__publicField(this, "retryPolicy");
-    chunkMWMSFIWN_cjs.__publicField(this, "debug");
-    chunkMWMSFIWN_cjs.__publicField(this, "logger");
-    chunkMWMSFIWN_cjs.__publicField(this, "config");
-    this.config = config;
-    this.baseUrl = config.baseUrl;
-    this.timeout = config.timeout;
-    this.debug = config.debug.enabled ?? false;
-    this.logger = config.debug.logger;
-    const apiKey = presentKey(config.apiKey);
-    this.defaultHeaders = {
-      "Content-Type": "application/json",
-      ...apiKey === void 0 ? {} : { [API_KEY_HEADER]: apiKey },
-      ...config.headers
-    };
-    if (config.dataset != null) {
-      this.defaultHeaders["X-RelyIO-Dataset"] = config.dataset;
-    }
-    if (typeof window === "undefined") {
-      const globalWithVersion = globalThis;
-      this.defaultHeaders["User-Agent"] = `RelyIO-SDK/${globalWithVersion.__VERSION__ ?? "0.0.0"}`;
-    }
-    this.retryPolicy = new DefaultRetryPolicy({
-      maxAttempts: config.retryAttempts,
-      baseDelay: 1e3,
-      maxDelay: 1e4,
-      backoffFactor: 2,
-      jitter: true
-    });
+    /** What every request reads off the configuration, derived by {@link configure} and nowhere else. */
+    chunkMWMSFIWN_cjs.__publicField(this, "connection");
+    this.connection = connectionFor(config);
+    this.announce();
+  }
+  /**
+   * Run on `config` from now on: every later request — whoever holds this client — is sent to its
+   * `baseUrl`, with its headers, key and dataset, its timeout and retries, through its `fetch`, and
+   * logged by its `debug` options.
+   *
+   * The client's own `updateConfig()` calls this rather than building a second client, so a
+   * `content()` or other sub-client taken before the update sends through the update too. Anything
+   * set on this client since it was last configured — `setDefaultHeaders()`, `setBaseUrl()` — is
+   * replaced by what `config` says.
+   */
+  configure(config) {
+    this.connection = connectionFor(config);
+    this.announce();
+  }
+  announce() {
     this.log("debug", "HttpClient initialized", {
-      baseUrl: this.baseUrl,
-      timeout: this.timeout,
-      retryAttempts: config.retryAttempts,
-      environment: typeof window === "undefined" ? "node" : "browser"
+      baseUrl: this.connection.baseUrl,
+      timeout: this.connection.timeout,
+      retryAttempts: this.connection.config.retryAttempts,
+      environment: chunkTZL374LS_cjs.isBrowser() ? "browser" : "node"
     });
   }
   /**
@@ -999,19 +1142,24 @@ var _HttpClient = class _HttpClient {
    *
    * The loop always makes one attempt. The incumbent's `while (attempt <
    * maxAttempts)` made none at `retryAttempts: 0` — a value the config validator
-   * accepts — and then dereferenced an unassigned `lastError`.
+   * then accepted, and now refuses — and then dereferenced an unassigned
+   * `lastError`. `retryAttempts` is the most attempts, the first included; an
+   * `HttpClient` constructed directly is not validated, so the first attempt
+   * stays unconditional.
    *
    * A request that would carry no `X-API-Key` makes none: it rejects with
    * `MissingApiKeyError` before `fetch` is called, is not retried, and names
    * `apiKey`. This is where a client built without a key learns it — the
    * constructor accepts one so that a module-scope client can be evaluated by a
-   * build that holds no key (REL-1120).
+   * build that holds no key (REL-1120) — and so does one whose `setApiKey` was
+   * given none.
    */
   async request(config) {
+    if (config.timeout !== void 0) assertRequestTimeout(config.timeout);
     const mergedConfig = this.mergeRequestConfig(config);
     if (presentKey(headerValue(mergedConfig.headers, API_KEY_HEADER)) === void 0) {
       throw new MissingApiKeyError(
-        "`apiKey` is missing: this client was created without an API key, so the request was not sent. Pass `apiKey` to createClient \u2014 the documented setup reads it from RELYIO_API_KEY.",
+        "`apiKey` is missing: this client holds no API key, so the request was not sent. Pass `apiKey` to createClient \u2014 the documented setup reads it from RELYIO_API_KEY.",
         { url: mergedConfig.url, method: mergedConfig.method, sent: false }
       );
     }
@@ -1021,7 +1169,7 @@ var _HttpClient = class _HttpClient {
       // Show the final URL with query params
     });
     if (config.method === "DELETE" && mergedConfig.headers) {
-      delete mergedConfig.headers["Content-Type"];
+      mergedConfig.headers = layerHeaders(mergedConfig.headers, { "Content-Type": null });
     }
     for (let attempt = 1; ; attempt++) {
       try {
@@ -1040,8 +1188,8 @@ var _HttpClient = class _HttpClient {
           attempt,
           url: mergedConfig.url
         });
-        if (this.retryPolicy.shouldRetry(attempt, failure, mergedConfig)) {
-          const delay = this.retryPolicy.delayFor(attempt, failure);
+        if (this.connection.retryPolicy.shouldRetry(attempt, failure, mergedConfig)) {
+          const delay = this.connection.retryPolicy.delayFor(attempt, failure);
           this.log("debug", "Retrying request", { attempt, delay });
           await sleep(delay, config.signal);
           continue;
@@ -1113,34 +1261,60 @@ var _HttpClient = class _HttpClient {
     });
   }
   /**
-   * Set default headers for all requests
+   * Add headers to every later request, each replacing any header of the same name — the name
+   * matched without regard to case — until the client is next configured.
    */
   setDefaultHeaders(headers) {
-    this.defaultHeaders = { ...this.defaultHeaders, ...headers };
+    this.connection = {
+      ...this.connection,
+      defaultHeaders: layerHeaders(this.connection.defaultHeaders, headers)
+    };
   }
   /**
-   * Set authentication token
+   * Replace the key every later request sends as `X-API-Key`, and the `apiKey` the configuration
+   * reports.
+   *
+   * The key is read the way construction reads it (`presentKey`): an absent, empty or blank key is
+   * no key, so the header is dropped and the next request is refused with `MissingApiKeyError`
+   * before anything is sent. A key header of any other spelling — one given in `headers` — goes
+   * too, from the headers sent and from the headers the configuration reports, so the old key is
+   * never sent beside the new one.
+   *
+   * The configuration is the one the owning `TypedRelyIOClient` holds (it hands its own to the
+   * constructor), so its `getConfig().apiKey` — what a surface reads to decide a key's kind — is the
+   * key sent from here on.
+   *
+   * This replaced `setAuthToken`, which added `Authorization: Bearer` beside an `X-API-Key` it
+   * never touched: the API reads `X-API-Key` first, so the old key was the one used (REL-1385).
    */
-  setAuthToken(token) {
-    this.defaultHeaders.Authorization = `Bearer ${token}`;
+  setApiKey(apiKey) {
+    const { config } = this.connection;
+    config.apiKey = apiKey;
+    config.headers = layerHeaders(config.headers, { [API_KEY_HEADER]: null });
+    this.connection = {
+      ...this.connection,
+      defaultHeaders: layerHeaders(this.connection.defaultHeaders, {
+        [API_KEY_HEADER]: presentKey(apiKey) ?? null
+      })
+    };
   }
   /**
    * Get current default headers
    */
   getDefaultHeaders() {
-    return { ...this.defaultHeaders };
+    return { ...this.connection.defaultHeaders };
   }
   /**
    * Update base URL
    */
   setBaseUrl(baseUrl) {
-    this.baseUrl = baseUrl;
+    this.connection = { ...this.connection, baseUrl };
   }
   /**
    * Get current base URL
    */
   getBaseUrl() {
-    return this.baseUrl;
+    return this.connection.baseUrl;
   }
   /**
    * One attempt.
@@ -1162,7 +1336,7 @@ var _HttpClient = class _HttpClient {
     const timeoutId = setTimeout(() => {
       timedOut = true;
       controller.abort();
-    }, config.timeout ?? this.timeout);
+    }, config.timeout ?? this.connection.timeout);
     const onCallerAbort = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => controller.abort(), "onCallerAbort");
     caller?.addEventListener("abort", onCallerAbort, { once: true });
     try {
@@ -1172,14 +1346,15 @@ var _HttpClient = class _HttpClient {
         headers: filteredHeaders,
         body: this.prepareRequestBody(config),
         signal: controller.signal,
-        // Only where `window` exists. A server or edge runtime has no cookie jar for the mode to
-        // govern, so the field is left off and the runtime's default stands. A Web Worker gets
-        // that default too: it has cookies but no `window`.
-        ...typeof window !== "undefined" && {
-          credentials: credentialsModeFor(this.config.browser.includeCredentials)
+        // Only in a browser — a `window` with a `document` (`isBrowser()`). A server or edge
+        // runtime has no cookie jar for the mode to govern, so the field is left off and the
+        // runtime's default stands; that includes Deno 1.x, whose global is a `window` with no
+        // `document`. A Web Worker gets that default too: it has cookies but no `window`.
+        ...chunkTZL374LS_cjs.isBrowser() && {
+          credentials: credentialsModeFor(this.connection.config.browser.includeCredentials)
         }
       };
-      const send = this.config.fetch ?? globalThis.fetch;
+      const send = this.connection.config.fetch ?? globalThis.fetch;
       const response = await send(url, requestInit);
       clearTimeout(timeoutId);
       const responseBody = await this.parseResponse(response);
@@ -1212,10 +1387,8 @@ var _HttpClient = class _HttpClient {
       }
       if (error instanceof DOMException && error.name === "AbortError") {
         if (!timedOut && isAborted(caller)) throw error;
-        throw new TimeoutError(
-          `Request timed out after ${config.timeout ?? this.timeout}ms`,
-          config.timeout ?? this.timeout
-        );
+        const timeout = config.timeout ?? this.connection.timeout;
+        throw new TimeoutError(`Request timed out after ${timeout}ms`, timeout);
       }
       if (error instanceof TypeError && error.message.includes("CORS")) {
         const corsError = new NetworkError(
@@ -1229,9 +1402,10 @@ var _HttpClient = class _HttpClient {
             suggestion: "Check if the API server allows requests from your domain and has proper CORS headers configured."
           }
         );
-        if (typeof window !== "undefined" && this.config.browser.onCorsError) {
+        const { onCorsError } = this.connection.config.browser;
+        if (chunkTZL374LS_cjs.isBrowser() && onCorsError) {
           try {
-            this.config.browser.onCorsError(corsError, {
+            onCorsError(corsError, {
               url: config.url,
               method: config.method,
               originalError: error
@@ -1248,20 +1422,20 @@ var _HttpClient = class _HttpClient {
     }
   }
   /**
-   * Filter headers that browsers don't allow to be set manually
+   * The headers without those a browser controls itself, when this is a browser; unchanged when it
+   * is not.
+   *
+   * A name is matched without regard to case (RFC 9110 §5.1), because a browser refuses `Origin`
+   * whatever case a page spells it in. This matched only the all-lowercase and all-uppercase
+   * spellings, so `Origin` and `User-Agent` — how people write them — reached `fetch` (REL-1409).
    */
   filterHeadersForBrowser(headers) {
-    if (typeof window !== "undefined") {
-      const filteredHeaders = { ...headers };
-      const forbiddenHeaders = ["user-agent", "referer", "origin", "host", "connection", "upgrade"];
-      forbiddenHeaders.forEach((header) => {
-        delete filteredHeaders[header];
-        delete filteredHeaders[header.toLowerCase()];
-        delete filteredHeaders[header.toUpperCase()];
-      });
-      return filteredHeaders;
-    }
-    return headers;
+    if (!chunkTZL374LS_cjs.isBrowser()) return headers;
+    return Object.fromEntries(
+      Object.entries(headers).filter(
+        ([name]) => !BROWSER_CONTROLLED_HEADERS.has(name.toLowerCase())
+      )
+    );
   }
   /**
    * Prepare request body based on content type and environment
@@ -1297,7 +1471,7 @@ var _HttpClient = class _HttpClient {
     if (url.startsWith("http://") || url.startsWith("https://")) {
       return url;
     }
-    return `${this.baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
+    return `${this.connection.baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
   }
   mergeRequestConfig(config) {
     const url = this.resolveUrl(config.url);
@@ -1306,11 +1480,11 @@ var _HttpClient = class _HttpClient {
     return {
       ...config,
       url: finalUrl,
-      headers: {
-        ...this.defaultHeaders,
-        ...config.headers
-      },
-      timeout: config.timeout ?? this.timeout
+      // The request's own headers replace the client's of the same name, whatever the case: a
+      // per-request `x-relyio-dataset` sent beside the client's `X-RelyIO-Dataset` is one header
+      // `Headers` joins into `main, staging`.
+      headers: layerHeaders(this.connection.defaultHeaders, config.headers),
+      timeout: config.timeout ?? this.connection.timeout
     };
   }
   buildQueryString(params) {
@@ -1334,9 +1508,10 @@ var _HttpClient = class _HttpClient {
     return obj;
   }
   log(level, message, data) {
-    if (!this.debug) return;
-    if (this.logger != null) {
-      this.logger(level, message, data);
+    const { debug } = this.connection.config;
+    if (!debug.enabled) return;
+    if (debug.logger != null) {
+      debug.logger(level, message, data);
     } else {
       console.log(`[RelyIO SDK ${level.toUpperCase()}] ${message}`, data ?? "");
     }
@@ -1345,29 +1520,104 @@ var _HttpClient = class _HttpClient {
 chunkMWMSFIWN_cjs.__name(_HttpClient, "HttpClient");
 var HttpClient = _HttpClient;
 var API_KEY_HEADER = "X-API-Key";
+var DATASET_HEADER = "X-RelyIO-Dataset";
+var BROWSER_CONTROLLED_HEADERS = /* @__PURE__ */ new Set([
+  "user-agent",
+  "referer",
+  "origin",
+  "host",
+  "connection",
+  "upgrade"
+]);
+function connectionFor(config) {
+  const globalWithVersion = globalThis;
+  const defaultHeaders = layerHeaders(
+    layerHeaders({ "Content-Type": "application/json" }, config.headers),
+    {
+      [API_KEY_HEADER]: presentKey(config.apiKey),
+      [DATASET_HEADER]: config.dataset,
+      // Only outside a browser, which controls this header. "A browser" is the core's one
+      // definition, `isBrowser()` — every environment question in this file asks it.
+      "User-Agent": chunkTZL374LS_cjs.isBrowser() ? void 0 : `RelyIO-SDK/${globalWithVersion.__VERSION__ ?? "0.0.0"}`
+    }
+  );
+  return {
+    config,
+    baseUrl: config.baseUrl,
+    defaultHeaders,
+    timeout: config.timeout,
+    // The policy, not a predicate over `(error, attempt)`: whether a request may be sent again is a
+    // property of the **route** as much as of the refusal, and a callback that never sees the
+    // request cannot express that.
+    retryPolicy: new DefaultRetryPolicy({
+      maxAttempts: config.retryAttempts,
+      baseDelay: 1e3,
+      maxDelay: 1e4,
+      backoffFactor: 2,
+      jitter: true
+    })
+  };
+}
+chunkMWMSFIWN_cjs.__name(connectionFor, "connectionFor");
+function layerHeaders(base, over) {
+  const layered = { ...base };
+  for (const [name, value] of Object.entries(over ?? {})) {
+    if (value === void 0) continue;
+    const lower = name.toLowerCase();
+    for (const existing of Object.keys(layered)) {
+      if (existing.toLowerCase() === lower) delete layered[existing];
+    }
+    if (value !== null) layered[name] = value;
+  }
+  return layered;
+}
+chunkMWMSFIWN_cjs.__name(layerHeaders, "layerHeaders");
 function presentKey(value) {
   return typeof value === "string" && value.trim() !== "" ? value : void 0;
 }
 chunkMWMSFIWN_cjs.__name(presentKey, "presentKey");
 function credentialsModeFor(includeCredentials) {
-  switch (includeCredentials) {
-    case false: {
-      return "same-origin";
-    }
-    case true:
-    case void 0: {
-      return "include";
-    }
-  }
+  return includeCredentials ? "include" : "same-origin";
 }
 chunkMWMSFIWN_cjs.__name(credentialsModeFor, "credentialsModeFor");
 
+// src/content/client-locale.ts
+function callLocale(named, clientLocale) {
+  if (named !== void 0) return named;
+  return clientLocale === void 0 || clientLocale === "" ? void 0 : clientLocale;
+}
+chunkMWMSFIWN_cjs.__name(callLocale, "callLocale");
+function readClientLocale(locale) {
+  return typeof locale === "function" ? locale : () => locale;
+}
+chunkMWMSFIWN_cjs.__name(readClientLocale, "readClientLocale");
+
 // src/content/query-builder.ts
+function namesMetadata(key) {
+  return key === "_metadata" || key.startsWith("_metadata.");
+}
+chunkMWMSFIWN_cjs.__name(namesMetadata, "namesMetadata");
+function refuseMetadataConditions(conditions) {
+  const named = Object.keys(conditions).filter(namesMetadata);
+  if (named.length === 0) return;
+  throw new ValidationError(
+    `A condition cannot name ${named.join(", ")}: the API filters on the fields the content type declares, and reports _metadata beside them. Filter on a field, and read _metadata from the result.`,
+    named.map((field) => ({
+      field,
+      code: "METADATA_CONDITION",
+      message: `${field} is not a field the API can filter on`
+    }))
+  );
+}
+chunkMWMSFIWN_cjs.__name(refuseMetadataConditions, "refuseMetadataConditions");
 var _ContentQueryBuilder = class _ContentQueryBuilder {
-  constructor(httpClient, contentType, defaultLocale) {
+  /**
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when the
+   *   query names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
+   */
+  constructor(httpClient, contentType, locale) {
     this.httpClient = httpClient;
     this.contentType = contentType;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "queryOptions", {});
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
     chunkMWMSFIWN_cjs.__publicField(this, "localesArray");
@@ -1377,6 +1627,21 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     chunkMWMSFIWN_cjs.__publicField(this, "pageNumber");
     chunkMWMSFIWN_cjs.__publicField(this, "pageSizeValue");
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    chunkMWMSFIWN_cjs.__publicField(this, "freshValue");
+    this.clientLocale = readClientLocale(locale);
+  }
+  /**
+   * The feed position this read follows — a change's `fresh` (`FeedChange`), or a resync's. Sent as
+   * `?_fresh`, the one term the API declares for it: no cache — the Content API's edge or the
+   * browser's own — holds an answer for that position from before it, so the read is answered after
+   * the change, and every read naming the same position shares that answer. The answer is the
+   * read's own; omit it for a read no change prompted.
+   */
+  fresh(position) {
+    this.freshValue = position;
+    return this;
   }
   /**
    * Headers this query adds to the client's own, e.g. `X-RelyIO-Dataset` to list another dataset
@@ -1388,9 +1653,11 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     return this;
   }
   /**
-   * Add where conditions to the query
+   * Add where conditions to the query: conditions on the fields the content type declares. A
+   * condition on `_metadata` is refused here, before anything is sent (`refuseMetadataConditions`).
    */
   where(conditions) {
+    refuseMetadataConditions(conditions);
     this.queryOptions.where = {
       ...this.queryOptions.where,
       ...conditions
@@ -1647,7 +1914,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;
@@ -1656,6 +1927,7 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     cloned.pageNumber = this.pageNumber;
     cloned.pageSizeValue = this.pageSizeValue;
     cloned.requestHeaders = this.requestHeaders ? { ...this.requestHeaders } : void 0;
+    cloned.freshValue = this.freshValue;
     return cloned;
   }
   /**
@@ -1722,14 +1994,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;
@@ -1747,23 +2020,44 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
         params.childrenLimit = this.childrenOptions.limit;
       }
     }
+    if (this.freshValue !== void 0) {
+      params[FRESH_PARAMETER] = this.freshValue;
+    }
     return params;
   }
 };
 chunkMWMSFIWN_cjs.__name(_ContentQueryBuilder, "ContentQueryBuilder");
 var ContentQueryBuilder = _ContentQueryBuilder;
 var _ContentByIdBuilder = class _ContentByIdBuilder {
-  constructor(httpClient, contentType, id, defaultLocale) {
+  /**
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when the
+   *   read names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
+   */
+  constructor(httpClient, contentType, id, locale) {
     this.httpClient = httpClient;
     this.contentType = contentType;
     this.id = id;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "includeRelations");
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
     chunkMWMSFIWN_cjs.__publicField(this, "localesArray");
     chunkMWMSFIWN_cjs.__publicField(this, "fetchAllLocales", false);
     chunkMWMSFIWN_cjs.__publicField(this, "childrenOptions");
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked when the read is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    chunkMWMSFIWN_cjs.__publicField(this, "freshValue");
+    this.clientLocale = readClientLocale(locale);
+  }
+  /**
+   * The feed position this read follows — a change's `fresh` (`FeedChange`), or a resync's. Sent as
+   * `?_fresh`, the one term the API declares for it: no cache — the Content API's edge or the
+   * browser's own — holds an answer for that position from before it, so the read is answered after
+   * the change, and every read naming the same position shares that answer. The answer is the
+   * read's own; omit it for a read no change prompted.
+   */
+  fresh(position) {
+    this.freshValue = position;
+    return this;
   }
   /**
    * Include related content in the response
@@ -1833,14 +2127,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) {
@@ -1852,6 +2147,9 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
         params.childrenLimit = this.childrenOptions.limit;
       }
     }
+    if (this.freshValue !== void 0) {
+      params[FRESH_PARAMETER] = this.freshValue;
+    }
     try {
       return await this.httpClient.fetchPayload(
         "/v1/{contentType}/{id}",
@@ -1905,22 +2203,28 @@ chunkMWMSFIWN_cjs.__name(entityTagOf, "entityTagOf");
 
 // src/content/content-client.ts
 var _ContentClient = class _ContentClient {
-  constructor(httpClient, contentType, defaultLocale) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+   *   every call, or a locale fixed for this client
+   */
+  constructor(httpClient, contentType, locale) {
     this.httpClient = httpClient;
     this.contentType = contentType;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Create a new query builder for this content type
    */
   query() {
-    return new ContentQueryBuilder(this.httpClient, this.contentType, this.defaultLocale);
+    return new ContentQueryBuilder(this.httpClient, this.contentType, this.clientLocale);
   }
   /**
    * Find content by ID with fluent options
    */
   findById(id) {
-    return new ContentByIdBuilder(this.httpClient, this.contentType, id, this.defaultLocale);
+    return new ContentByIdBuilder(this.httpClient, this.contentType, id, this.clientLocale);
   }
   /**
    * Fetch all content items
@@ -2004,7 +2308,7 @@ var _ContentClient = class _ContentClient {
   async fetchOneWithTag(id, options) {
     const query = {};
     if (options?.include != null) query.include = options.include.join(",");
-    const locale = options?.locale ?? this.defaultLocale;
+    const locale = options?.locale ?? this.clientLocale();
     if (locale != null && locale !== "") query.locale = locale;
     const response = await this.httpClient.send(
       "/v1/{contentType}/{id}",
@@ -2034,16 +2338,17 @@ var _ContentClient = class _ContentClient {
    * @param options - Create options (slug, locale, parentId, sortOrder), and `headers` this one
    *   request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset other than the
    *   client's. They are sent, never put in the body; `idempotencyKey` still wins over an
-   *   `Idempotency-Key` among them.
+   *   `Idempotency-Key` among them. `locale` defaults to the client's own (`withLocale()`).
    */
   async create(data, options) {
-    const { idempotencyKey, headers, ...body } = options ?? {};
+    const { idempotencyKey, headers, locale, ...body } = options ?? {};
+    const sent = callLocale(locale, this.clientLocale());
     return this.httpClient.fetchPayload(
       "/v1/{contentType}",
       "post",
       {
         path: { contentType: this.contentType },
-        body: { content: data, ...body },
+        body: { content: data, ...body, ...sent === void 0 ? {} : { locale: sent } },
         headers: requestHeaders(headers, writeHeaders({ idempotencyKey }))
       }
     );
@@ -2054,16 +2359,18 @@ var _ContentClient = class _ContentClient {
    * @param data - Fields to update
    * @param options - Update options (slug, locale, parentId, sortOrder), and `headers` this one
    *   request adds, as for {@link create}. `ifMatch` and `idempotencyKey` win over the same
-   *   header among them.
+   *   header among them. `locale` defaults to the client's own, the locale whose entity tag
+   *   {@link fetchOneWithTag} reads, so the tag it hands back is checked against the same locale.
    */
   async update(id, data, options) {
-    const { idempotencyKey, ifMatch, headers, ...body } = options ?? {};
+    const { idempotencyKey, ifMatch, headers, locale, ...body } = options ?? {};
+    const sent = callLocale(locale, this.clientLocale());
     return this.httpClient.fetchPayload(
       "/v1/{contentType}/{id}",
       "patch",
       {
         path: { contentType: this.contentType, id },
-        body: { content: data, ...body },
+        body: { content: data, ...body, ...sent === void 0 ? {} : { locale: sent } },
         headers: requestHeaders(headers, writeHeaders({ idempotencyKey, ifMatch }))
       }
     );
@@ -2095,32 +2402,35 @@ var _ContentClient = class _ContentClient {
    * Get version history for one locale of an entry.
    *
    * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
-   * schema default, no fallback is applied, and a locale with no history returns an empty array
-   * rather than another locale's rows. Every row names the locale it belongs to.
+   * client's own (`withLocale()`), else the schema default; no fallback is applied, and a locale
+   * with no history returns an empty array rather than another locale's rows. Every row names the
+   * locale it belongs to.
    */
   async versions(id, options) {
+    const locale = callLocale(options?.locale, this.clientLocale());
     return this.httpClient.fetchPayload("/v1/{contentType}/{id}/versions", "get", {
       path: { contentType: this.contentType, id },
       query: {
         limit: options?.limit ?? 10,
-        ...options?.locale === void 0 ? {} : { locale: options.locale }
+        ...locale === void 0 ? {} : { locale }
       }
     });
   }
   /**
    * Get a specific version of an entry.
    *
-   * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
-   * different content in each one.
+   * `locale` defaults to the client's own (`withLocale()`), else the schema default. Version
+   * numbers are per locale, so version 2 is different content in each one.
    */
   async version(id, versionNumber, options) {
+    const locale = callLocale(options?.locale, this.clientLocale());
     return this.httpClient.fetchPayload("/v1/{contentType}/{id}/versions/{versionNumber}", "get", {
       path: {
         contentType: this.contentType,
         id,
         versionNumber: String(versionNumber)
       },
-      query: options?.locale === void 0 ? void 0 : { locale: options.locale }
+      query: locale === void 0 ? void 0 : { locale }
     });
   }
   /**
@@ -2159,7 +2469,7 @@ var _ContentClient = class _ContentClient {
     if (options?.include != null) {
       params.include = options.include.join(",");
     }
-    const locale = options?.locale ?? this.defaultLocale;
+    const locale = options?.locale ?? this.clientLocale();
     if (locale != null && locale !== "") {
       params.locale = locale;
     }
@@ -2179,19 +2489,20 @@ var _ContentClient = class _ContentClient {
    * Create a new ContentClient for a different content type
    */
   ofType(contentType) {
-    return new _ContentClient(this.httpClient, contentType, this.defaultLocale);
+    return new _ContentClient(this.httpClient, contentType, this.clientLocale);
   }
   /**
-   * Create a new ContentClient with a different default locale
+   * Create a new ContentClient with a different default locale, fixed: an update of the client's
+   * locale (`updateConfig({ locale })`) does not reach it
    */
   withLocale(locale) {
     return new _ContentClient(this.httpClient, this.contentType, locale);
   }
   /**
-   * Get the current default locale
+   * Get the default locale as it is now: the client's, or the one `withLocale()` fixed
    */
   getDefaultLocale() {
-    return this.defaultLocale;
+    return this.clientLocale();
   }
 };
 chunkMWMSFIWN_cjs.__name(_ContentClient, "ContentClient");
@@ -2200,7 +2511,7 @@ var ContentClient = _ContentClient;
 // src/errors/file-errors.ts
 var _FileUploadError = class _FileUploadError extends SDKError {
   constructor(code, message, options = {}) {
-    super(message, options.statusCode, options.cause, { fileErrorCode: code });
+    super(message, options.statusCode, options.cause, { ...options.context, fileErrorCode: code });
     chunkMWMSFIWN_cjs.__publicField(this, "code");
     chunkMWMSFIWN_cjs.__publicField(this, "retryable");
     this.code = code;
@@ -2247,11 +2558,52 @@ function validateFile(file, constraints = {}) {
 }
 chunkMWMSFIWN_cjs.__name(validateFile, "validateFile");
 
+// src/errors/file-error-codes.ts
+var FILE_ERROR_CODES = [
+  "UPLOAD_TOO_LARGE",
+  "UNSUPPORTED_MIME",
+  "DIMENSION_OUT_OF_RANGE",
+  "ASPECT_RATIO",
+  "CORRUPT_FILE",
+  "UNSUPPORTED_CODEC",
+  "IMAGES_LIMIT_EXCEEDED",
+  "STREAM_ENCODE_FAILED",
+  "SCAN_INFECTED",
+  "INTERNAL"
+];
+
 // src/content/asset-client.ts
+function assertWaitOptions(options) {
+  const { timeoutMs, pollIntervalMs } = options;
+  if (timeoutMs !== void 0 && !(typeof timeoutMs === "number" && timeoutMs >= 0 && timeoutMs <= MAX_TIMER_DELAY_MS)) {
+    throw new Error(
+      `timeoutMs must be a number of milliseconds from 0 to ${MAX_TIMER_DELAY_MS}, and got ${String(timeoutMs)}`
+    );
+  }
+  if (pollIntervalMs !== void 0 && !isTimerDelay(pollIntervalMs)) {
+    throw new Error(
+      `pollIntervalMs must be a number of milliseconds from 1 to ${MAX_TIMER_DELAY_MS} \u2014 a timer given 0, NaN, Infinity or more fires at once \u2014 and got ${String(pollIntervalMs)}`
+    );
+  }
+}
+chunkMWMSFIWN_cjs.__name(assertWaitOptions, "assertWaitOptions");
 function hasText(value) {
   return value != null && value !== "";
 }
 chunkMWMSFIWN_cjs.__name(hasText, "hasText");
+function processingFailure(subject, stored) {
+  const storedCode = stored?.code;
+  const code = FILE_ERROR_CODES.find((known) => known === storedCode) ?? "PROCESSING_FAILED";
+  return new FileUploadError(
+    code,
+    `Asset ${subject}: ${stored?.message ?? "File processing failed"}`,
+    {
+      retriable: stored?.retriable === true,
+      context: { processingError: stored }
+    }
+  );
+}
+chunkMWMSFIWN_cjs.__name(processingFailure, "processingFailure");
 async function computeSha256Hex(blob) {
   try {
     const subtle = globalThis.crypto?.subtle;
@@ -2267,11 +2619,17 @@ async function computeSha256Hex(blob) {
 }
 chunkMWMSFIWN_cjs.__name(computeSha256Hex, "computeSha256Hex");
 var _AssetFileBuilder = class _AssetFileBuilder {
-  constructor(httpClient, assetType, entryUid, defaultLocale) {
+  /**
+   * @param locale - The client's locale, sent when a call names none: the function
+   *   `TypedRelyIOClient` hands over, or a locale fixed for this builder
+   */
+  constructor(httpClient, assetType, entryUid, locale) {
     this.httpClient = httpClient;
     this.assetType = assetType;
     this.entryUid = entryUid;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, asked on every call rather than copied when this builder was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * The path parameters every `/file/*` route on this builder takes.
@@ -2284,7 +2642,16 @@ var _AssetFileBuilder = class _AssetFileBuilder {
     return { contentType: this.assetType, id: this.entryUid };
   }
   withLocale(locale) {
-    return locale ?? this.defaultLocale;
+    return locale ?? this.clientLocale();
+  }
+  /**
+   * The `locale` body field of a multipart call: the session's, else the client's. The API finds
+   * the binding by it, so a session a `withLocale()` client opened must name the same locale on
+   * every later call or its `objectKey` is refused as another binding's.
+   */
+  localeField(locale) {
+    const sent = this.withLocale(locale);
+    return hasText(sent) ? { locale: sent } : {};
   }
   /**
    * Issue a single upload target — an R2 presigned PUT (image/file) or a
@@ -2343,7 +2710,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
         partNumber: target.partNumber,
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
   }
@@ -2354,7 +2721,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       body: {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
     return payload.parts;
@@ -2367,7 +2734,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
         parts: target.parts.map((p) => ({ partNumber: p.partNumber, etag: p.etag })),
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
   }
@@ -2378,7 +2745,7 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       body: {
         uploadId: target.uploadId,
         objectKey: target.objectKey,
-        ...hasText(target.locale) ? { locale: target.locale } : {}
+        ...this.localeField(target.locale)
       }
     });
   }
@@ -2398,6 +2765,25 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       { path: this.target, query: params }
     );
   }
+  /**
+   * Read where this file's upload got to — `status`, and the processing stage, progress and error
+   * the pipeline recorded — whatever the asset entry is published in.
+   *
+   * An asset is a draft until its file is ready, and stays one when its file fails, so a key that
+   * reads published content finds no entry for an upload in flight or one that failed. This read
+   * answers for the binding itself. It takes the capability the upload calls take, so a read-only
+   * key is refused with `ReadOnlyKeyError`, and it never returns the entry's fields.
+   */
+  async status(options = {}) {
+    const params = {};
+    const locale = this.withLocale(options.locale);
+    if (hasText(locale)) params.locale = locale;
+    return this.httpClient.fetchPayload(
+      "/v1/{contentType}/{id}/file",
+      "get",
+      { path: this.target, query: params }
+    );
+  }
   /**
    * Update the binding's delivery visibility (token-based; no byte relocation —
    * a downgrade purges the gateway cache). Returns the refreshed asset entry.
@@ -2436,14 +2822,31 @@ var _AssetFileBuilder = class _AssetFileBuilder {
     });
   }
   /**
-   * Poll the asset entry until its file binding reaches `ready` (resolves with
-   * the ready entry) or `failed` (throws). Times out after `timeoutMs`.
+   * Poll the asset entry until its file binding reaches `ready`, and resolve with the ready entry.
+   *
+   * Each poll reads the entry through the key's lens. When that finds nothing — a key that reads
+   * published content, and an asset that is a draft until its file is ready and stays one when it
+   * fails — the poll reads the binding itself ({@link status}), so a failed upload rejects as one
+   * rather than running out the limit (REL-1481).
+   *
+   * @throws {FileUploadError} When processing failed. `code` is the processing code the service
+   *   stored — `UNSUPPORTED_CODEC`, `CORRUPT_FILE` and so on — or `PROCESSING_FAILED` where it
+   *   stored none this SDK knows; `context.processingError` holds what it stored, and `retryable`
+   *   is its `retriable` hint.
+   * @throws {TimeoutError} When `timeoutMs` passes first. The file may still become ready; the
+   *   error's `context.timeout` is the limit and `context.fileStatus` the status last seen. A file
+   *   that is `ready` in an asset the key's lens never shows — created with `publish: false`, or
+   *   awaiting a workflow — ends here too, and the message says so.
+   * @throws {ReadOnlyKeyError} When the key's lens does not show the asset and the key may not read
+   *   its binding either: nothing it can read would ever report the file.
    */
   async waitUntilReady(options = {}) {
+    assertWaitOptions(options);
     const timeoutMs = options.timeoutMs ?? 6e4;
     const pollIntervalMs = options.pollIntervalMs ?? 1500;
     const locale = this.withLocale(options.locale);
     const deadline = Date.now() + timeoutMs;
+    const subject = `${this.assetType}/${this.entryUid}`;
     for (; ; ) {
       const builder = new ContentByIdBuilder(
         this.httpClient,
@@ -2453,15 +2856,24 @@ var _AssetFileBuilder = class _AssetFileBuilder {
       );
       if (hasText(locale)) builder.locale(locale);
       const entry = await builder.execute();
-      const status = entry?.file?.status;
-      if (entry && status === "ready") return entry;
-      if (status === "failed") {
-        const message = entry?.file?.processing?.error?.message ?? "File processing failed";
-        throw new Error(`Asset ${this.assetType}/${this.entryUid}: ${message}`);
+      let status;
+      if (entry === null) {
+        const binding = await this.status({ ...hasText(locale) ? { locale } : {} });
+        status = binding.status;
+        if (status === "failed") throw processingFailure(subject, binding.processing?.error);
+      } else {
+        status = entry.file?.status;
+        if (status === "ready") return entry;
+        if (status === "failed") throw processingFailure(subject, entry.file?.processing?.error);
       }
       if (Date.now() >= deadline) {
-        throw new Error(
-          `Timed out after ${timeoutMs}ms waiting for ${this.assetType}/${this.entryUid} (status: ${status ?? "unknown"})`
+        const unseen = entry === null && status === "ready" ? "; the file is ready and this key's lens does not show the asset \u2014 it is not published" : "";
+        throw new TimeoutError(
+          `Timed out after ${timeoutMs}ms waiting for ${subject} (status: ${status ?? "unknown"})${unseen}`,
+          timeoutMs,
+          void 0,
+          void 0,
+          { fileStatus: status }
         );
       }
       await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
@@ -2471,11 +2883,14 @@ var _AssetFileBuilder = class _AssetFileBuilder {
 chunkMWMSFIWN_cjs.__name(_AssetFileBuilder, "AssetFileBuilder");
 var AssetFileBuilder = _AssetFileBuilder;
 var _AssetUploadBuilder = class _AssetUploadBuilder {
-  constructor(httpClient, assetType, file, defaultLocale) {
+  /**
+   * @param locale - The client's locale, the upload's when `.locale()` names none: the function
+   *   `TypedRelyIOClient` hands over, or a locale fixed for this upload
+   */
+  constructor(httpClient, assetType, file, locale) {
     this.httpClient = httpClient;
     this.assetType = assetType;
     this.file = file;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "_fileName");
     chunkMWMSFIWN_cjs.__publicField(this, "_visibility");
     chunkMWMSFIWN_cjs.__publicField(this, "_locale");
@@ -2487,6 +2902,9 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     chunkMWMSFIWN_cjs.__publicField(this, "_onProgress");
     chunkMWMSFIWN_cjs.__publicField(this, "_validate");
     chunkMWMSFIWN_cjs.__publicField(this, "_maxPartRetries", 3);
+    /** The client's locale, read once when the upload starts. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /** Subscribe to client → storage upload progress (single PUT + multipart). */
   onProgress(callback) {
@@ -2536,8 +2954,14 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     this._slug = slug;
     return this;
   }
-  /** Wait until the file binding becomes `ready` before resolving. */
+  /**
+   * Wait until the file binding becomes `ready` before resolving.
+   *
+   * @throws {Error} When `timeoutMs` or `pollIntervalMs` is one the wait cannot honour — refused
+   *   here, before anything is uploaded, rather than after the bytes are in.
+   */
   waitForReady(options = true) {
+    if (typeof options === "object") assertWaitOptions(options);
     if (options === false) {
       this._waitForReady = false;
     } else {
@@ -2552,7 +2976,8 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     if (!fileName) {
       throw new Error('A file name is required: pass a File, or call .filename("name.ext")');
     }
-    const locale = this._locale ?? this.defaultLocale;
+    const clientLocale = this.clientLocale();
+    const locale = this._locale ?? clientLocale;
     if (this._validate) {
       const violations = validateFile(this.file, this._validate);
       if (violations.length > 0) {
@@ -2563,7 +2988,7 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
       }
     }
     const hash = await computeSha256Hex(this.file);
-    const client = new AssetClient(this.httpClient, this.assetType, this.defaultLocale);
+    const client = new AssetClient(this.httpClient, this.assetType, clientLocale);
     const created = await client.create(this._content, {
       ...hasText(this._slug) ? { slug: this._slug } : {},
       ...hasText(locale) ? { locale } : {},
@@ -2714,17 +3139,26 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
 chunkMWMSFIWN_cjs.__name(_AssetUploadBuilder, "AssetUploadBuilder");
 var AssetUploadBuilder = _AssetUploadBuilder;
 var _AssetClient = class _AssetClient {
-  constructor(httpClient, assetType, defaultLocale) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+   *   every call, or a locale fixed for this client
+   */
+  constructor(httpClient, assetType, locale) {
     this.httpClient = httpClient;
     this.assetType = assetType;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
-  /** Create a query builder for this asset type. */
+  /**
+   * Create a query builder for this asset type. It resolves asset reads; its conditions name the
+   * asset type's fields, which the `file` and `urls` blocks are not.
+   */
   query() {
     return new ContentQueryBuilder(
       this.httpClient,
       this.assetType,
-      this.defaultLocale
+      this.clientLocale
     );
   }
   /** Find an asset entry by id (or slug) with fluent options. */
@@ -2733,7 +3167,7 @@ var _AssetClient = class _AssetClient {
       this.httpClient,
       this.assetType,
       id,
-      this.defaultLocale
+      this.clientLocale
     );
   }
   /** Fetch a single asset entry by id (or slug), or `null` if not found. */
@@ -2754,28 +3188,34 @@ var _AssetClient = class _AssetClient {
    * Create a new asset entry as a draft. The binary is uploaded separately via
    * `file(uid)` (or use the high-level `upload()` helper), and the entry
    * auto-publishes when its file becomes ready (unless `publish: false`).
+   * `locale` defaults to the client's own (`withLocale()`).
    */
   async create(data, options) {
-    const { idempotencyKey, ...rest } = options ?? {};
+    const { idempotencyKey, locale, ...rest } = options ?? {};
+    const sent = callLocale(locale, this.clientLocale());
     return this.httpClient.fetchPayload(
       "/v1/{contentType}",
       "post",
       {
         path: { contentType: this.assetType },
-        body: { content: data, ...rest },
+        body: { content: data, ...rest, ...sent === void 0 ? {} : { locale: sent } },
         headers: writeHeaders({ idempotencyKey })
       }
     );
   }
-  /** Update an asset entry's metadata fields (and/or slug). */
+  /**
+   * Update an asset entry's metadata fields (and/or slug). `locale` defaults to the client's own
+   * (`withLocale()`).
+   */
   async update(id, data, options) {
-    const { idempotencyKey, ifMatch, ...rest } = options ?? {};
+    const { idempotencyKey, ifMatch, locale, ...rest } = options ?? {};
+    const sent = callLocale(locale, this.clientLocale());
     return this.httpClient.fetchPayload(
       "/v1/{contentType}/{id}",
       "patch",
       {
         path: { contentType: this.assetType, id },
-        body: { content: data, ...rest },
+        body: { content: data, ...rest, ...sent === void 0 ? {} : { locale: sent } },
         headers: writeHeaders({ idempotencyKey, ifMatch })
       }
     );
@@ -2789,21 +3229,24 @@ var _AssetClient = class _AssetClient {
   }
   /** Get the file sub-resource builder for a specific asset entry. */
   file(entryUid) {
-    return new AssetFileBuilder(this.httpClient, this.assetType, entryUid, this.defaultLocale);
+    return new AssetFileBuilder(this.httpClient, this.assetType, entryUid, this.clientLocale);
   }
   /** Start a high-level upload (create → presign → PUT → confirm). */
   upload(file) {
-    return new AssetUploadBuilder(this.httpClient, this.assetType, file, this.defaultLocale);
+    return new AssetUploadBuilder(this.httpClient, this.assetType, file, this.clientLocale);
   }
   /** Get the asset type id. */
   getAssetType() {
     return this.assetType;
   }
-  /** Get the current default locale. */
+  /** Get the default locale as it is now: the client's, or the one `withLocale()` fixed. */
   getDefaultLocale() {
-    return this.defaultLocale;
+    return this.clientLocale();
   }
-  /** Create a new AssetClient for this type with a different default locale. */
+  /**
+   * Create a new AssetClient for this type with a different default locale, fixed: an update of the
+   * client's locale (`updateConfig({ locale })`) does not reach it.
+   */
   withLocale(locale) {
     return new _AssetClient(this.httpClient, this.assetType, locale);
   }
@@ -2819,12 +3262,18 @@ chunkMWMSFIWN_cjs.__name(isAssetEntry, "isAssetEntry");
 
 // src/content/singleton-client.ts
 var _SingletonClient = class _SingletonClient {
-  constructor(httpClient, singletonKey, defaultLocale) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+   *   every call, or a locale fixed for this client
+   */
+  constructor(httpClient, singletonKey, locale) {
     this.httpClient = httpClient;
     this.singletonKey = singletonKey;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "includeFields");
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Include reference fields in the response
@@ -2864,9 +3313,10 @@ var _SingletonClient = class _SingletonClient {
   async fetchWithTag(options) {
     const query = {};
     const includeValue = options?.include ?? this.includeFields;
-    const localeValueFinal = options?.locale ?? this.localeValue ?? this.defaultLocale;
+    const localeValueFinal = options?.locale ?? this.localeValue ?? this.clientLocale();
     if (includeValue) query.include = includeValue.join(",");
     if (localeValueFinal != null && localeValueFinal !== "") query.locale = localeValueFinal;
+    if (options?.fresh !== void 0) query[FRESH_PARAMETER] = options.fresh;
     const response = await this.httpClient.send(
       "/v1/singletons/{key}",
       "get",
@@ -2878,11 +3328,12 @@ var _SingletonClient = class _SingletonClient {
    * Update singleton content. The API auto-publishes on PATCH — there is no
    * separate publish route; calling `update()` writes and publishes.
    * @param data - The content fields to update
-   * @param locale - Optional locale for localized content (overrides fluent locale)
+   * @param locale - Optional locale for localized content (overrides the fluent locale, which
+   *   overrides the client's own)
    * @param options - `If-Match` / `Idempotency-Key`, both declared on this route
    */
   async update(data, locale, options) {
-    const finalLocale = locale ?? this.localeValue;
+    const finalLocale = this.localeOf(locale);
     return this.httpClient.fetchPayload(
       "/v1/singletons/{key}",
       "patch",
@@ -2911,15 +3362,17 @@ var _SingletonClient = class _SingletonClient {
    * Get version history for one locale of the singleton.
    *
    * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
-   * schema default, no fallback is applied, and a locale with no history returns an empty array
-   * rather than another locale's rows. Every row names the locale it belongs to.
+   * fluent `.locale()`, then the client's own (`withLocale()`), then the schema default; no
+   * fallback is applied, and a locale with no history returns an empty array rather than another
+   * locale's rows. Every row names the locale it belongs to.
    */
   async versions(options) {
+    const locale = this.localeOf(options?.locale);
     const payload = await this.httpClient.fetchPayload("/v1/singletons/{key}/versions", "get", {
       path: { key: this.singletonKey },
       query: {
         limit: options?.limit ?? 10,
-        ...options?.locale === void 0 ? {} : { locale: options.locale }
+        ...locale === void 0 ? {} : { locale }
       }
     });
     return payload.versions;
@@ -2927,20 +3380,25 @@ var _SingletonClient = class _SingletonClient {
   /**
    * Get a specific version of the singleton.
    *
-   * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
-   * different content in each one.
+   * `locale` defaults to the fluent `.locale()`, then the client's own (`withLocale()`), then the
+   * schema default. Version numbers are per locale, so version 2 is different content in each one.
    */
   async version(versionNumber, options) {
+    const locale = this.localeOf(options?.locale);
     try {
       return await this.httpClient.fetchPayload("/v1/singletons/{key}/versions/{versionNumber}", "get", {
         path: { key: this.singletonKey, versionNumber: String(versionNumber) },
-        query: options?.locale === void 0 ? void 0 : { locale: options.locale }
+        query: locale === void 0 ? void 0 : { locale }
       });
     } catch (error) {
       if (isResourceNotFound(error)) return null;
       throw error;
     }
   }
+  /** The locale a write or history read sends: the call's, the fluent one, else the client's. */
+  localeOf(named) {
+    return callLocale(named ?? this.localeValue, this.clientLocale());
+  }
   /**
    * Get the singleton key
    */
@@ -2961,12 +3419,18 @@ var SingletonClient = _SingletonClient;
 
 // src/content/settings-client.ts
 var _SettingsClient = class _SettingsClient {
-  constructor(httpClient, groupId, defaultLocale) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, asked on
+   *   every call, or a locale fixed for this client
+   */
+  constructor(httpClient, groupId, locale) {
     this.httpClient = httpClient;
     this.groupId = groupId;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "includeFields");
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
+    /** The client's locale, asked on every call rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Include reference fields in the response
@@ -2998,12 +3462,20 @@ var _SettingsClient = class _SettingsClient {
   }
   /**
    * Update settings group
+   *
+   * The fields travel as `content` beside an optional `locale`, the body the route validates
+   * (`UpdateSettingsDto`); any other top-level key is refused `REQUEST_INVALID`.
+   *
    * @param settings - The settings fields to update
-   * @param locale - Optional locale for localized settings (overrides fluent locale)
+   * @param locale - Optional locale for localized settings (overrides the fluent locale, which
+   *   overrides the client's own)
    */
   async update(settings, locale, options) {
-    const finalLocale = locale ?? this.localeValue;
-    const body = finalLocale != null && finalLocale !== "" ? { ...settings, locale: finalLocale } : settings;
+    const finalLocale = this.localeOf(locale);
+    const body = {
+      content: settings,
+      ...finalLocale != null && finalLocale !== "" ? { locale: finalLocale } : {}
+    };
     return this.httpClient.fetchPayload(
       "/v1/settings/{groupId}",
       "patch",
@@ -3018,7 +3490,7 @@ var _SettingsClient = class _SettingsClient {
   async fetchWithTag(options) {
     const query = {};
     const includeValue = options?.include ?? this.includeFields;
-    const localeValueFinal = options?.locale ?? this.localeValue ?? this.defaultLocale;
+    const localeValueFinal = options?.locale ?? this.localeValue ?? this.clientLocale();
     if (includeValue) query.include = includeValue.join(",");
     if (localeValueFinal != null && localeValueFinal !== "") query.locale = localeValueFinal;
     const response = await this.httpClient.send(
@@ -3030,16 +3502,20 @@ var _SettingsClient = class _SettingsClient {
   }
   /**
    * Reset settings to default values
-   * @param locale - Optional locale for localized settings
+   *
+   * The route reads its locale from `?locale=` and takes no body, so that is where it is sent.
+   *
+   * @param locale - Optional locale for localized settings (overrides the fluent locale, which
+   *   overrides the client's own)
    */
   async reset(locale, options) {
-    const finalLocale = locale ?? this.localeValue;
+    const finalLocale = this.localeOf(locale);
     return this.httpClient.fetchPayload(
       "/v1/settings/{groupId}/reset",
       "post",
       {
         path: { groupId: this.groupId },
-        body: finalLocale != null && finalLocale !== "" ? { locale: finalLocale } : void 0,
+        query: finalLocale != null && finalLocale !== "" ? { locale: finalLocale } : void 0,
         headers: writeHeaders(options)
       }
     );
@@ -3070,15 +3546,17 @@ var _SettingsClient = class _SettingsClient {
    * Get version history for one locale of the settings group.
    *
    * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
-   * schema default, no fallback is applied, and a locale with no history returns an empty array
-   * rather than another locale's rows. Every row names the locale it belongs to.
+   * fluent `.locale()`, then the client's own (`withLocale()`), then the schema default; no
+   * fallback is applied, and a locale with no history returns an empty array rather than another
+   * locale's rows. Every row names the locale it belongs to.
    */
   async versions(options) {
+    const locale = this.localeOf(options?.locale);
     const payload = await this.httpClient.fetchPayload("/v1/settings/{groupId}/versions", "get", {
       path: { groupId: this.groupId },
       query: {
         limit: options?.limit ?? 10,
-        ...options?.locale === void 0 ? {} : { locale: options.locale }
+        ...locale === void 0 ? {} : { locale }
       }
     });
     return payload.versions;
@@ -3086,20 +3564,25 @@ var _SettingsClient = class _SettingsClient {
   /**
    * Get a specific version of the settings.
    *
-   * `locale` defaults to the schema default. Version numbers are per locale, so version 2 is
-   * different content in each one.
+   * `locale` defaults to the fluent `.locale()`, then the client's own (`withLocale()`), then the
+   * schema default. Version numbers are per locale, so version 2 is different content in each one.
    */
   async version(versionNumber, options) {
+    const locale = this.localeOf(options?.locale);
     try {
       return await this.httpClient.fetchPayload("/v1/settings/{groupId}/versions/{versionNumber}", "get", {
         path: { groupId: this.groupId, versionNumber: String(versionNumber) },
-        query: options?.locale === void 0 ? void 0 : { locale: options.locale }
+        query: locale === void 0 ? void 0 : { locale }
       });
     } catch (error) {
       if (isResourceNotFound(error)) return null;
       throw error;
     }
   }
+  /** The locale a write or history read sends: the call's, the fluent one, else the client's. */
+  localeOf(named) {
+    return callLocale(named ?? this.localeValue, this.clientLocale());
+  }
   /**
    * Get the settings group ID
    */
@@ -3121,15 +3604,19 @@ var SettingsClient = _SettingsClient;
 // src/search/search-client.ts
 var _SearchBuilder = class _SearchBuilder {
   /**
-   * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when
+   *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
    */
-  constructor(httpClient, query, defaultLocale) {
+  constructor(httpClient, query, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "query");
     chunkMWMSFIWN_cjs.__publicField(this, "searchOptions", {});
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    chunkMWMSFIWN_cjs.__publicField(this, "freshValue");
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
     this.query = query;
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Headers this search adds to the client's own, e.g. `X-RelyIO-Dataset` to search another
@@ -3139,6 +3626,15 @@ var _SearchBuilder = class _SearchBuilder {
     this.requestHeaders = headers;
     return this;
   }
+  /**
+   * The feed position this search follows — a change's `fresh` (`FeedChange`), or a resync's. Sent
+   * as `?_fresh` on the query string beside the body: the edge keys a search on both, so no answer
+   * it holds from before that position can answer it. The answer is the search's own.
+   */
+  fresh(position) {
+    this.freshValue = position;
+    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.
@@ -3160,10 +3656,12 @@ var _SearchBuilder = class _SearchBuilder {
     return this;
   }
   /**
-   * Add filter conditions
+   * Add filter conditions, on the fields the content types declare. A condition on `_metadata` is
+   * refused here, before anything is sent.
    * @param conditions - Filter conditions
    */
   where(conditions) {
+    refuseMetadataConditions(conditions);
     this.searchOptions.where = {
       ...this.searchOptions.where,
       ...conditions
@@ -3271,14 +3769,18 @@ var _SearchBuilder = class _SearchBuilder {
     if (this.searchOptions.explain === true) {
       body.explain = true;
     }
-    const locale = this.searchOptions.locale ?? this.defaultLocale;
+    const locale = this.searchOptions.locale ?? this.clientLocale();
     if (locale != null && locale !== "") {
       body.locale = locale;
     }
     const response = await this.httpClient.send(
       "/v1/search",
       "post",
-      { body, headers: this.requestHeaders }
+      {
+        body,
+        headers: this.requestHeaders,
+        ...this.freshValue === void 0 ? {} : { query: { [FRESH_PARAMETER]: this.freshValue } }
+      }
     );
     return response.body;
   }
@@ -3299,14 +3801,17 @@ chunkMWMSFIWN_cjs.__name(_SearchBuilder, "SearchBuilder");
 var SearchBuilder = _SearchBuilder;
 var _AutocompleteBuilder = class _AutocompleteBuilder {
   /**
-   * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when
+   *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
    */
-  constructor(httpClient, query, defaultLocale) {
+  constructor(httpClient, query, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "query");
     chunkMWMSFIWN_cjs.__publicField(this, "autocompleteOptions", {});
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
     this.query = query;
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Autocomplete within a content type
@@ -3332,10 +3837,12 @@ var _AutocompleteBuilder = class _AutocompleteBuilder {
     return this;
   }
   /**
-   * Add filter conditions
+   * Add filter conditions, on the fields the content types declare. A condition on `_metadata` is
+   * refused here, before anything is sent.
    * @param conditions - Filter conditions
    */
   where(conditions) {
+    refuseMetadataConditions(conditions);
     this.autocompleteOptions.where = {
       ...this.autocompleteOptions.where,
       ...conditions
@@ -3382,7 +3889,7 @@ var _AutocompleteBuilder = class _AutocompleteBuilder {
     if (this.autocompleteOptions.limit !== void 0) {
       body.limit = this.autocompleteOptions.limit;
     }
-    const locale = this.autocompleteOptions.locale ?? this.defaultLocale;
+    const locale = this.autocompleteOptions.locale ?? this.clientLocale();
     if (locale != null && locale !== "") {
       body.locale = locale;
     }
@@ -3400,15 +3907,18 @@ chunkMWMSFIWN_cjs.__name(_AutocompleteBuilder, "AutocompleteBuilder");
 var AutocompleteBuilder = _AutocompleteBuilder;
 var _SimilarBuilder = class _SimilarBuilder {
   /**
-   * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent when
+   *   `.locale()` names none: the function `TypedRelyIOClient` hands over, or a locale fixed for it
    */
-  constructor(httpClient, sourceId, defaultLocale) {
+  constructor(httpClient, sourceId, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "sourceId");
     chunkMWMSFIWN_cjs.__publicField(this, "similarOptions", {});
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked when the read is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
     this.sourceId = sourceId;
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Headers this read adds to the client's own, e.g. `X-RelyIO-Dataset` to read another dataset
@@ -3436,17 +3946,12 @@ var _SimilarBuilder = class _SimilarBuilder {
     this.similarOptions.contentType = void 0;
     return this;
   }
-  /**
-   * Add filter conditions
-   * @param conditions - Filter conditions
+  /*
+   * No `where()` (REL-1452). Similar ranks from the source entry's stored vector, and the vector
+   * index can pre-filter by content type and locale only — never by an entry field. The API used to
+   * accept `where` here and apply nothing; it now refuses the property, so the builder does not
+   * offer a filter that cannot be honoured. Narrow with `.in()`, `.across()` and `.locale()`.
    */
-  where(conditions) {
-    this.similarOptions.where = {
-      ...this.similarOptions.where,
-      ...conditions
-    };
-    return this;
-  }
   /**
    * Limit number of results
    * @param count - Maximum results
@@ -3480,13 +3985,10 @@ var _SimilarBuilder = class _SimilarBuilder {
     if (contentTypes != null) {
       body.contentTypes = contentTypes;
     }
-    if (this.similarOptions.where && Object.keys(this.similarOptions.where).length > 0) {
-      body.where = this.similarOptions.where;
-    }
     if (this.similarOptions.limit !== void 0) {
       body.limit = this.similarOptions.limit;
     }
-    const locale = this.similarOptions.locale ?? this.defaultLocale;
+    const locale = this.similarOptions.locale ?? this.clientLocale();
     if (locale != null && locale !== "") {
       body.locale = locale;
     }
@@ -3514,41 +4016,36 @@ chunkMWMSFIWN_cjs.__name(_SimilarBuilder, "SimilarBuilder");
 var SimilarBuilder = _SimilarBuilder;
 var _SearchClient = class _SearchClient {
   /**
-   * @param defaultLocale - The client's locale (`withLocale()`): every builder here sends it when
-   *   the query names none, as `content()`'s reads do
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`): every builder
+   *   here sends it when the query names none, as `content()`'s reads do — the function
+   *   `TypedRelyIOClient` hands over, or a locale fixed for this client
    */
-  constructor(httpClient, defaultLocale) {
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, handed to every builder here to ask when it sends. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Start a search query
    * @param query - Search query string
    */
   search(query) {
-    return new SearchBuilder(this.httpClient, query, this.defaultLocale);
+    return new SearchBuilder(this.httpClient, query, this.clientLocale);
   }
   /**
    * Start an autocomplete query
    * @param query - Partial query to autocomplete
    */
   autocomplete(query) {
-    return new AutocompleteBuilder(this.httpClient, query, this.defaultLocale);
+    return new AutocompleteBuilder(this.httpClient, query, this.clientLocale);
   }
   /**
    * Find content similar to a given entry
    * @param sourceId - Entry ID to find similar content for
    */
   similar(sourceId) {
-    return new SimilarBuilder(this.httpClient, sourceId, this.defaultLocale);
-  }
-  /**
-   * Quick search helper - searches all content types
-   * @param query - Search query
-   * @param limit - Max results (default 20)
-   */
-  async global(query, limit = 20) {
-    return this.search(query).across("*").limit(limit).execute();
+    return new SimilarBuilder(this.httpClient, sourceId, this.clientLocale);
   }
 };
 chunkMWMSFIWN_cjs.__name(_SearchClient, "SearchClient");
@@ -3556,7 +4053,12 @@ var SearchClient = _SearchClient;
 
 // src/batch/batch-client.ts
 var _BatchBuilder = class _BatchBuilder {
-  constructor(httpClient) {
+  /**
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), each
+   *   operation's when it names none: the function `TypedRelyIOClient` hands over, or a locale fixed
+   *   for this batch
+   */
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
     chunkMWMSFIWN_cjs.__publicField(this, "operations", []);
     chunkMWMSFIWN_cjs.__publicField(this, "defaultOptions", {
@@ -3566,6 +4068,17 @@ var _BatchBuilder = class _BatchBuilder {
       continueOnError: true
     });
     chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+    /** The client's locale, asked as each operation is added rather than copied when this was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
+  }
+  /**
+   * An operation's body with its locale: the one it names, else the client's as it is when the
+   * operation is added.
+   */
+  localized(data) {
+    const locale = callLocale(data.locale, this.clientLocale());
+    return locale === void 0 ? data : { ...data, locale };
   }
   // ==========================================================================
   // ENTRY OPERATIONS
@@ -3581,7 +4094,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "POST",
       path: `/${contentType}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3601,7 +4114,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PATCH",
       path: `/${contentType}/${entryId}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3621,7 +4134,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PUT",
       path: `/${contentType}/${entryId}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3653,7 +4166,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "PATCH",
       path: `/_singletons/${singletonKey}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3668,7 +4181,7 @@ var _BatchBuilder = class _BatchBuilder {
       id,
       method: "POST",
       path: `/_singletons/${singletonKey}`,
-      body: data
+      body: this.localized(data)
     });
     return this;
   }
@@ -3676,7 +4189,8 @@ var _BatchBuilder = class _BatchBuilder {
   // RAW OPERATIONS
   // ==========================================================================
   /**
-   * Add a raw operation (for advanced use cases)
+   * Add a raw operation (for advanced use cases). It is sent exactly as written: the client's
+   * locale is not added to it.
    * @param operation - The operation to add
    */
   raw(operation) {
@@ -3802,7 +4316,7 @@ var _BatchBuilder = class _BatchBuilder {
    * Clone the builder
    */
   clone() {
-    const cloned = new _BatchBuilder(this.httpClient);
+    const cloned = new _BatchBuilder(this.httpClient, this.clientLocale);
     cloned.operations = [...this.operations];
     cloned.defaultOptions = { ...this.defaultOptions };
     cloned.requestHeaders = this.requestHeaders === void 0 ? void 0 : { ...this.requestHeaders };
@@ -3855,14 +4369,21 @@ var _BatchBuilder = class _BatchBuilder {
 chunkMWMSFIWN_cjs.__name(_BatchBuilder, "BatchBuilder");
 var BatchBuilder = _BatchBuilder;
 var _BatchClient = class _BatchClient {
-  constructor(httpClient) {
+  /**
+   * @param locale - The client's locale: the function `TypedRelyIOClient` hands over, or a locale
+   *   fixed for this client
+   */
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
+    /** The client's locale, handed to every batch this builds to ask as operations are added. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
-   * Create a new batch builder
+   * Create a new batch builder, whose operations default to this client's locale
    */
   create() {
-    return new BatchBuilder(this.httpClient);
+    return new BatchBuilder(this.httpClient, this.clientLocale);
   }
   /**
    * Quick bulk create entries
@@ -3913,15 +4434,18 @@ function withClientLocale(parameters, clientLocale) {
 chunkMWMSFIWN_cjs.__name(withClientLocale, "withClientLocale");
 var _AdhocQueryBuilder = class _AdhocQueryBuilder {
   /**
-   * @param defaultLocale - The client's locale (`withLocale()`), sent as the `locale` parameter
-   *   when `.param('locale', …)` binds none
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent as the
+   *   `locale` parameter when `.param('locale', …)` binds none: the function `TypedRelyIOClient`
+   *   hands over, or a locale fixed for this builder
    */
-  constructor(httpClient, defaultLocale) {
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "queryDef", {});
     chunkMWMSFIWN_cjs.__publicField(this, "parameters", {});
     chunkMWMSFIWN_cjs.__publicField(this, "options", {});
+    /** The client's locale, asked when the query is sent rather than copied when it was built. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   // ==========================================================================
   // QUERY BLOCKS
@@ -3966,14 +4490,6 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
     this.queryDef.search = config;
     return this;
   }
-  /**
-   * Add similar block
-   * @param config - Similar configuration
-   */
-  similar(config) {
-    this.queryDef.similar = config;
-    return this;
-  }
   // ==========================================================================
   // FETCH MODIFIERS
   // ==========================================================================
@@ -4150,15 +4666,15 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
    * Execute the query
    */
   async execute() {
-    if (!this.queryDef.fetch && !this.queryDef.aggregate && !this.queryDef.search && !this.queryDef.similar) {
+    if (!this.queryDef.fetch && !this.queryDef.aggregate && !this.queryDef.search) {
       throw new Error(
-        "Query must have at least one of: fetch, aggregate, search, or similar. Use .from(), .aggregate(), .search(), or .similar()"
+        "Query must have at least one of: fetch, aggregate or search. Use .from(), .aggregate() or .search()"
       );
     }
     const body = {
       query: this.queryDef
     };
-    const parameters = withClientLocale(this.parameters, this.defaultLocale);
+    const parameters = withClientLocale(this.parameters, this.clientLocale());
     if (parameters !== void 0 && Object.keys(parameters).length > 0) {
       body.parameters = parameters;
     }
@@ -4191,7 +4707,7 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
    * Clone the builder
    */
   clone() {
-    const cloned = new _AdhocQueryBuilder(this.httpClient, this.defaultLocale);
+    const cloned = new _AdhocQueryBuilder(this.httpClient, this.clientLocale);
     cloned.queryDef = JSON.parse(JSON.stringify(this.queryDef));
     cloned.parameters = { ...this.parameters };
     cloned.options = { ...this.options };
@@ -4202,18 +4718,21 @@ chunkMWMSFIWN_cjs.__name(_AdhocQueryBuilder, "AdhocQueryBuilder");
 var AdhocQueryBuilder = _AdhocQueryBuilder;
 var _AdhocQueryClient = class _AdhocQueryClient {
   /**
-   * @param defaultLocale - The client's locale (`withLocale()`), sent as the `locale` parameter of
-   *   every query that binds none
+   * @param locale - The client's locale (`withLocale()`, `updateConfig({ locale })`), sent as the
+   *   `locale` parameter of every query that binds none: the function `TypedRelyIOClient` hands
+   *   over, or a locale fixed for this client
    */
-  constructor(httpClient, defaultLocale) {
+  constructor(httpClient, locale) {
     this.httpClient = httpClient;
-    this.defaultLocale = defaultLocale;
+    /** The client's locale, asked on every query rather than copied when this client was taken. */
+    chunkMWMSFIWN_cjs.__publicField(this, "clientLocale");
+    this.clientLocale = readClientLocale(locale);
   }
   /**
    * Create a new query builder
    */
   build() {
-    return new AdhocQueryBuilder(this.httpClient, this.defaultLocale);
+    return new AdhocQueryBuilder(this.httpClient, this.clientLocale);
   }
   /**
    * Execute a query definition directly
@@ -4228,7 +4747,7 @@ var _AdhocQueryClient = class _AdhocQueryClient {
     const body = {
       query: definition
     };
-    const sent = withClientLocale(parameters, this.defaultLocale);
+    const sent = withClientLocale(parameters, this.clientLocale());
     if (sent !== void 0 && Object.keys(sent).length > 0) {
       body.parameters = sent;
     }
@@ -4277,23 +4796,67 @@ var AdhocQueryClient = _AdhocQueryClient;
 
 // src/changes/changes.ts
 var CHANGES_POLL_TIMEOUT_MS = 25e3 + 5e3;
+var EXPIRED_REASONS = {
+  retention: "retention",
+  "dataset-replaced": "dataset-replaced",
+  "ahead-of-head": "ahead-of-head",
+  "foreign-cursor": "foreign-cursor",
+  "too-far-behind": "too-far-behind"
+};
 var _ChangesExpiredError = class _ChangesExpiredError extends ResourceExpiredError {
-  /** The base class's signature, so `withContext` can rebuild one. */
-  constructor(message, statusCode = 410, cause, context) {
+  /** The base class's signature, so `withContext` can rebuild one; then the position resynced to. */
+  constructor(message, statusCode = 410, cause, context, fresh) {
     super(message, statusCode, cause, context);
     chunkMWMSFIWN_cjs.__publicField(this, "reason");
+    /**
+     * The position the feed resynced to, which a refetch of everything names as `?_fresh`, as a
+     * change's {@link FeedChange.fresh} is named: the head a `/v1/changes` resync took, or the cursor
+     * the edge's `feed.resync` sent. `undefined` when there was no resync to take one — the error was
+     * thrown (`onExpired: 'throw'`) — and on an error a caller built itself.
+     */
+    chunkMWMSFIWN_cjs.__publicField(this, "fresh");
     this.name = "ChangesExpiredError";
     this.reason = expiredReasonOf(message);
+    this.fresh = fresh;
+  }
+  /** The base class rebuilds from its four arguments, which would drop the position resynced to. */
+  withContext(context) {
+    const Constructor = this.constructor;
+    return new Constructor(
+      this.message,
+      this.statusCode,
+      this.cause,
+      { ...this.context, ...context },
+      this.fresh
+    );
+  }
+  /** `/v1/changes`' refusal, with the head the feed resynced to when it did. */
+  static of(expired, fresh) {
+    return new _ChangesExpiredError(
+      expired.message,
+      expired.statusCode,
+      expired,
+      expired.context,
+      fresh
+    );
   }
-  static of(expired) {
-    return new _ChangesExpiredError(expired.message, expired.statusCode, expired, expired.context);
+  /** The live edge's `feed.resync`: refetch everything, then continue from the cursor it sent. */
+  static resync(reason, cursor) {
+    return new _ChangesExpiredError(
+      `The live edge cannot list the changes since this cursor (${reason}). Refetch everything derived from the feed; it continues from the position it sent.`,
+      410,
+      void 0,
+      { transport: "live-edge" },
+      cursor
+    );
   }
 };
 chunkMWMSFIWN_cjs.__name(_ChangesExpiredError, "ChangesExpiredError");
 var ChangesExpiredError = _ChangesExpiredError;
 function expiredReasonOf(message) {
-  if (message.includes("(retention)")) return "retention";
-  if (message.includes("(dataset-replaced)")) return "dataset-replaced";
+  for (const reason of Object.values(EXPIRED_REASONS)) {
+    if (message.includes(`(${reason})`)) return reason;
+  }
   return "unknown";
 }
 chunkMWMSFIWN_cjs.__name(expiredReasonOf, "expiredReasonOf");
@@ -4313,7 +4876,7 @@ async function* pollChanges(http, options = {}) {
       const onExpired = options.onExpired ?? "throw";
       if (onExpired === "throw") throw expired;
       since = void 0;
-      resynced = typeof onExpired === "function" ? expired : void 0;
+      resynced = typeof onExpired === "function" ? error : void 0;
       continue;
     }
     const { data, page } = response.body;
@@ -4322,13 +4885,13 @@ async function* pollChanges(http, options = {}) {
     }
     since = page.nextCursor;
     if (resynced !== void 0 && typeof options.onExpired === "function") {
-      const expired = resynced;
+      const expired = ChangesExpiredError.of(resynced, page.nextCursor);
       resynced = void 0;
       await options.onExpired(expired);
       if (isAborted(signal)) return;
     }
     for (const change of data) {
-      yield change;
+      yield { ...change, fresh: change.cursor };
       if (isAborted(signal)) return;
     }
     if (data.length === 0) {
@@ -4367,6 +4930,477 @@ async function pollOnce(http, since, options) {
 }
 chunkMWMSFIWN_cjs.__name(pollOnce, "pollOnce");
 
+// src/config/key-kind.ts
+var PUBLISHABLE_KEY_PREFIX = "rly_pub_";
+var isPublishableKey = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name((apiKey) => apiKey?.startsWith(PUBLISHABLE_KEY_PREFIX) === true, "isPublishableKey");
+
+// src/errors/live-errors.ts
+var _LiveEdgeError = class _LiveEdgeError extends SDKError {
+  constructor(message, end, retry, options = {}) {
+    super(message, options.statusCode, options.cause, options.context);
+    chunkMWMSFIWN_cjs.__publicField(this, "code", "LIVE_EDGE_ENDED");
+    chunkMWMSFIWN_cjs.__publicField(this, "retryable");
+    chunkMWMSFIWN_cjs.__publicField(this, "end");
+    chunkMWMSFIWN_cjs.__publicField(this, "retry");
+    /** A refused poll's `Retry-After`, in milliseconds, where it carried a readable one. */
+    chunkMWMSFIWN_cjs.__publicField(this, "retryAfterMs");
+    this.end = end;
+    this.retry = retry;
+    this.retryable = retry !== "stop";
+    this.retryAfterMs = options.retryAfterMs;
+  }
+  /**
+   * The base class rebuilds an error through its own four-argument constructor, which this class
+   * does not have; rebuilt that way, `end` would be a string and `retry` a number.
+   */
+  withContext(context) {
+    const rebuilt = new _LiveEdgeError(this.message, this.end, this.retry, {
+      ...this.statusCode === void 0 ? {} : { statusCode: this.statusCode },
+      ...this.cause === void 0 ? {} : { cause: this.cause },
+      ...this.retryAfterMs === void 0 ? {} : { retryAfterMs: this.retryAfterMs },
+      context: { ...this.context, ...context }
+    });
+    return rebuilt;
+  }
+  getUserMessage() {
+    return this.message;
+  }
+};
+chunkMWMSFIWN_cjs.__name(_LiveEdgeError, "LiveEdgeError");
+var LiveEdgeError = _LiveEdgeError;
+
+// src/config/live-url.ts
+var LIVE_EDGE_OF_API = {
+  "https://api.relyio.com": "https://live.relyio.com"
+};
+var HTTP_SCHEME_OF = {
+  "http:": "http:",
+  "https:": "https:",
+  "ws:": "http:",
+  "wss:": "https:"
+};
+function liveEdgeAddress(config) {
+  if (config.liveUrl !== void 0) return readLiveUrl(config.liveUrl);
+  const derived = originOf(config.baseUrl);
+  const edge = derived === void 0 ? void 0 : LIVE_EDGE_OF_API[derived];
+  if (edge !== void 0) return { ok: true, url: new URL(edge) };
+  return {
+    ok: false,
+    message: `Live updates need the address of RelyIO\u2019s live edge, and this client cannot derive it: \`baseUrl\` is not RelyIO\u2019s API (${Object.keys(LIVE_EDGE_OF_API).join(", ")}). Set \`liveUrl\` in createClient() to the live edge this API belongs with. Nothing was sent.`
+  };
+}
+chunkMWMSFIWN_cjs.__name(liveEdgeAddress, "liveEdgeAddress");
+function readLiveUrl(liveUrl) {
+  let url;
+  try {
+    url = new URL(liveUrl);
+  } catch {
+    return { ok: false, message: `\`liveUrl\` is not a URL: "${liveUrl}". Nothing was sent.` };
+  }
+  const scheme = HTTP_SCHEME_OF[url.protocol];
+  if (scheme === void 0) {
+    return {
+      ok: false,
+      message: `\`liveUrl\` must be an https:, wss:, http: or ws: URL, not ${url.protocol}. Nothing was sent.`
+    };
+  }
+  url.protocol = scheme;
+  url.search = "";
+  url.hash = "";
+  return { ok: true, url };
+}
+chunkMWMSFIWN_cjs.__name(readLiveUrl, "readLiveUrl");
+function originOf(baseUrl) {
+  try {
+    return new URL(baseUrl).origin;
+  } catch {
+    return void 0;
+  }
+}
+chunkMWMSFIWN_cjs.__name(originOf, "originOf");
+
+// src/changes/live-edge.ts
+var LIVE_KEEPALIVE_INTERVAL_MS = 3e4;
+var LIVE_POLLS_BEFORE_SOCKET = 4;
+async function* subscribeLiveEdge(client, options = {}) {
+  const { signal } = options;
+  if (isAborted(signal)) return;
+  const key = client.apiKey;
+  if (key === void 0 || !isPublishableKey(key)) {
+    throw new LiveEdgeError(NEEDS_PUBLISHABLE_KEY, { kind: "needs-publishable-key" }, "stop");
+  }
+  const address = liveEdgeAddress(client);
+  if (!address.ok) throw new LiveEdgeError(address.message, { kind: "needs-live-url" }, "stop");
+  const request = {
+    base: address.url,
+    key,
+    dataset: client.dataset,
+    types: options.types,
+    ids: options.ids
+  };
+  const reach = { position: options.since };
+  for (; ; ) {
+    const socket = openSocket(client, edgeUrl(request, reach.position, "socket"));
+    if (socket !== void 0) {
+      const ended = yield* followSocket(socket, reach, options);
+      if (ended === "aborted") return;
+    }
+    const polled = yield* followPolls(client, request, reach, options);
+    if (polled === "aborted") return;
+  }
+}
+chunkMWMSFIWN_cjs.__name(subscribeLiveEdge, "subscribeLiveEdge");
+var SOCKET_CONNECTING = 0;
+var SOCKET_OPEN = 1;
+function runtimeWebSocket() {
+  const candidate = globalThis.WebSocket;
+  return typeof candidate === "function" ? candidate : void 0;
+}
+chunkMWMSFIWN_cjs.__name(runtimeWebSocket, "runtimeWebSocket");
+function openSocket(client, url) {
+  const Socket = client.webSocket ?? runtimeWebSocket();
+  if (Socket === void 0) return void 0;
+  try {
+    return new Socket(url);
+  } catch {
+    return void 0;
+  }
+}
+chunkMWMSFIWN_cjs.__name(openSocket, "openSocket");
+async function* followSocket(socket, reach, options) {
+  const { signal } = options;
+  const inbox = socketInbox(socket, signal);
+  let open = false;
+  try {
+    for (; ; ) {
+      const event = await inbox.next();
+      if (event === void 0) return "aborted";
+      switch (event.kind) {
+        case "open": {
+          open = true;
+          inbox.keepAlive();
+          continue;
+        }
+        case "error": {
+          if (!open) return "unopened";
+          continue;
+        }
+        case "close": {
+          if (!open) return "unopened";
+          throw closedBy(event.code, event.reason);
+        }
+        case "silent": {
+          throw new LiveEdgeError(
+            "The live edge\u2019s socket stopped answering its keepalive, so the connection is presumed dead; reconnecting from the last cursor.",
+            { kind: "lost" },
+            "retry"
+          );
+        }
+        case "message": {
+          if (event.data === VISITOR_KEEPALIVE.response) continue;
+          const frame = typeof event.data === "string" ? parseVisitorFrame(event.data) : null;
+          if (frame === null)
+            throw unreadable(`a frame the wire does not declare: ${sample(event.data)}`);
+          switch (frame.type) {
+            case VISITOR_FRAMES.opened: {
+              reach.position = frame.cursor;
+              options.opened?.();
+              options.reached?.(frame.cursor);
+              continue;
+            }
+            case VISITOR_FRAMES.changes: {
+              const prior = reach.position;
+              if (prior === void 0) throw unreadable("changes before the socket had a position");
+              for (const change of changesOf(frame.changes, frame.cursor, prior)) {
+                yield change;
+                if (isAborted(signal)) return "aborted";
+              }
+              reach.position = frame.cursor;
+              if (frame.changes.length === 0) options.reached?.(frame.cursor);
+              continue;
+            }
+            case VISITOR_FRAMES.resync: {
+              await expire(frame.reason, frame.cursor, options);
+              if (isAborted(signal)) return "aborted";
+              reach.position = frame.cursor;
+              options.reached?.(frame.cursor);
+              continue;
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    inbox.dispose();
+  }
+}
+chunkMWMSFIWN_cjs.__name(followSocket, "followSocket");
+function socketInbox(socket, signal) {
+  const events = [];
+  let wake;
+  let disposed = false;
+  let heard = true;
+  let keepalive;
+  const rouse = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => {
+    const waking = wake;
+    wake = void 0;
+    waking?.();
+  }, "rouse");
+  const push = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name((event) => {
+    if (disposed) return;
+    events.push(event);
+    rouse();
+  }, "push");
+  socket.addEventListener("open", () => push({ kind: "open" }));
+  socket.addEventListener("message", (event) => {
+    heard = true;
+    push({ kind: "message", data: isRecord(event) ? event["data"] : void 0 });
+  });
+  socket.addEventListener("close", (event) => {
+    const code = isRecord(event) ? event["code"] : void 0;
+    const reason = isRecord(event) ? event["reason"] : void 0;
+    push({
+      kind: "close",
+      // A close event always carries both; a socket that somehow raised one without them closed
+      // abnormally, which is what 1006 says.
+      code: typeof code === "number" ? code : 1006,
+      reason: typeof reason === "string" ? reason : ""
+    });
+  });
+  socket.addEventListener("error", () => push({ kind: "error" }));
+  signal?.addEventListener("abort", rouse, { once: true });
+  return {
+    async next() {
+      for (; ; ) {
+        if (isAborted(signal)) return void 0;
+        const event = events.shift();
+        if (event !== void 0) return event;
+        await new Promise((resolve) => {
+          wake = resolve;
+        });
+      }
+    },
+    keepAlive() {
+      keepalive = setInterval(() => {
+        if (!heard) {
+          push({ kind: "silent" });
+          return;
+        }
+        heard = false;
+        if (socket.readyState === SOCKET_OPEN) socket.send(VISITOR_KEEPALIVE.request);
+      }, LIVE_KEEPALIVE_INTERVAL_MS);
+    },
+    dispose() {
+      disposed = true;
+      if (keepalive !== void 0) clearInterval(keepalive);
+      signal?.removeEventListener("abort", rouse);
+      if (socket.readyState === SOCKET_CONNECTING || socket.readyState === SOCKET_OPEN) {
+        socket.close(1e3);
+      }
+    }
+  };
+}
+chunkMWMSFIWN_cjs.__name(socketInbox, "socketInbox");
+function closedBy(code, reason) {
+  const retry = closeRetryOf(code);
+  const meaning = hasOwn(CLOSE_MEANING, code) ? CLOSE_MEANING[code] : code < 4e3 ? "the connection dropped" : "a refusal this version of the SDK does not know";
+  const said = `close ${code}${reason === "" ? "" : ` ${reason}`}`;
+  return new LiveEdgeError(
+    `The live edge ended this subscription (${said}): ${meaning}. ${AFTER_A_CLOSE[retry]}`,
+    { kind: "closed", code, reason },
+    retry
+  );
+}
+chunkMWMSFIWN_cjs.__name(closedBy, "closedBy");
+var AFTER_A_CLOSE = {
+  stop: "The same request would be refused again, so it was not retried.",
+  retry: "Reconnecting from the last cursor after a short back-off.",
+  "back-off": "Retrying after a back-off of at least a minute, without polling, which the same admission refuses."
+};
+function closeRetryOf(code) {
+  if (hasOwn(VISITOR_CLOSE_RETRY, code)) return VISITOR_CLOSE_RETRY[code];
+  return code < 4e3 ? "retry" : "stop";
+}
+chunkMWMSFIWN_cjs.__name(closeRetryOf, "closeRetryOf");
+var CLOSE_MEANING = {
+  [VISITOR_CLOSE_CODES.requestInvalid]: "the edge could not read the request \u2014 a malformed cursor or filter",
+  [VISITOR_CLOSE_CODES.keyRefused]: "the key is not a publishable key the edge accepts \u2014 unknown, revoked or expired",
+  [VISITOR_CLOSE_CODES.originRefused]: "this page\u2019s origin is not on the publishable key\u2019s allowed origins",
+  [VISITOR_CLOSE_CODES.datasetRefused]: "`dataset` names no dataset the key reaches",
+  [VISITOR_CLOSE_CODES.unavailable]: "the edge could not reach what it needed to decide just now",
+  [VISITOR_CLOSE_CODES.allowanceReached]: "the project holds as many live connections as its plan allows",
+  [VISITOR_CLOSE_CODES.addressLimitReached]: "this address holds as many live connections to the project as one address may",
+  [VISITOR_CLOSE_CODES.ceilingReached]: "the project is at its safety ceiling of live connections"
+};
+async function* followPolls(client, request, reach, options) {
+  const { signal } = options;
+  for (let poll = 0; poll < LIVE_POLLS_BEFORE_SOCKET; poll += 1) {
+    if (isAborted(signal)) return "aborted";
+    const answer = await pollOnce2(client, request, reach.position, signal);
+    if (answer === void 0) return "aborted";
+    options.opened?.();
+    if (answer.kind === "resync") {
+      await expire(answer.reason, answer.cursor, options);
+      if (isAborted(signal)) return "aborted";
+      reach.position = answer.cursor;
+      options.reached?.(answer.cursor);
+    } else {
+      const prior = reach.position;
+      if (answer.changes.length > 0 && prior === void 0) {
+        throw unreadable("a poll without a cursor answered changes");
+      }
+      for (const change of changesOf(answer.changes, answer.cursor, prior ?? answer.cursor)) {
+        yield change;
+        if (isAborted(signal)) return "aborted";
+      }
+      reach.position = answer.cursor;
+      if (answer.changes.length === 0) options.reached?.(answer.cursor);
+    }
+    await sleep(VISITOR_POLL_INTERVAL_MS, signal);
+  }
+  return isAborted(signal) ? "aborted" : "socket";
+}
+chunkMWMSFIWN_cjs.__name(followPolls, "followPolls");
+async function pollOnce2(client, request, since, signal) {
+  if (isAborted(signal)) return void 0;
+  const url = edgeUrl(request, since, "poll", client.clientId);
+  const context = { url: edgeUrl({ ...request, key: void 0 }, since, "poll", client.clientId) };
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, client.timeout);
+  const onAbort = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => controller.abort(), "onAbort");
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    let response;
+    let text;
+    try {
+      const send = client.fetch ?? globalThis.fetch;
+      response = await send(url, { method: "GET", signal: controller.signal });
+      text = await response.text();
+    } catch (error) {
+      if (isAborted(signal)) return void 0;
+      if (timedOut) {
+        throw new TimeoutError(
+          `The live edge did not answer a poll within ${client.timeout}ms`,
+          client.timeout,
+          void 0,
+          void 0,
+          context
+        );
+      }
+      throw ErrorMapper.mapGenericError(
+        error instanceof Error ? error : new Error(String(error)),
+        context
+      );
+    }
+    const body = parseJson(text);
+    if (!response.ok) throw refusedPoll(response, body, context);
+    const answer = readVisitorPollAnswer(isRecord(body) ? body["data"] : void 0);
+    if (answer === null)
+      throw unreadable(`a poll answer the wire does not declare: ${sample(text)}`);
+    return answer;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+}
+chunkMWMSFIWN_cjs.__name(pollOnce2, "pollOnce");
+function refusedPoll(response, body, context) {
+  const headers = {};
+  response.headers.forEach((value, name) => {
+    headers[name] = value;
+  });
+  const mapped = ErrorMapper.mapHttpError(
+    { status: response.status, statusText: response.statusText, body, headers },
+    { ...context, method: "GET" }
+  );
+  const refusal = readError(body);
+  if (refusal === void 0 || !hasOwn(VISITOR_POLL_RETRY, refusal.code)) return mapped;
+  const code = refusal.code;
+  const retryAfterMs = parseRetryAfterMs(headerValue(headers, "Retry-After"), Date.now());
+  return new LiveEdgeError(
+    `The live edge refused a poll (${code}): ${refusal.messages[0] ?? mapped.message}`,
+    { kind: "refused", code },
+    VISITOR_POLL_RETRY[code],
+    {
+      statusCode: response.status,
+      cause: mapped,
+      ...retryAfterMs === void 0 ? {} : { retryAfterMs },
+      context
+    }
+  );
+}
+chunkMWMSFIWN_cjs.__name(refusedPoll, "refusedPoll");
+function edgeUrl(request, since, transport, clientId) {
+  const url = new URL(request.base.href);
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}${VISITOR_LIVE_PATH}`;
+  if (transport === "socket") url.protocol = url.protocol === "http:" ? "ws:" : "wss:";
+  const query = new URLSearchParams();
+  if (request.key !== void 0) query.set(VISITOR_QUERY.key, request.key);
+  if (request.dataset !== void 0 && request.dataset !== "") {
+    query.set(VISITOR_QUERY.dataset, request.dataset);
+  }
+  if (since !== void 0) query.set(VISITOR_QUERY.since, since);
+  if (request.types !== void 0) query.set(VISITOR_QUERY.types, request.types.join(","));
+  if (request.ids !== void 0) query.set(VISITOR_QUERY.ids, request.ids.join(","));
+  if (transport === "poll" && clientId !== void 0) query.set(VISITOR_QUERY.client, clientId);
+  url.search = query.toString();
+  return url.href;
+}
+chunkMWMSFIWN_cjs.__name(edgeUrl, "edgeUrl");
+function changesOf(changes, cursor, prior) {
+  const last = changes.length - 1;
+  return changes.map((change, index) => ({
+    entryId: change.entryId,
+    contentType: change.contentType,
+    locale: change.locale,
+    kind: change.kind,
+    cursor: index === last ? cursor : prior,
+    fresh: cursor
+  }));
+}
+chunkMWMSFIWN_cjs.__name(changesOf, "changesOf");
+async function expire(reason, cursor, options) {
+  const expired = ChangesExpiredError.resync(reason, cursor);
+  const onExpired = options.onExpired ?? "throw";
+  if (onExpired === "throw") throw expired;
+  if (typeof onExpired === "function") await onExpired(expired);
+}
+chunkMWMSFIWN_cjs.__name(expire, "expire");
+function unreadable(what) {
+  return new LiveEdgeError(
+    `The live edge sent ${what}. This version of the SDK cannot follow it, so it stopped.`,
+    { kind: "unreadable", what },
+    "stop"
+  );
+}
+chunkMWMSFIWN_cjs.__name(unreadable, "unreadable");
+var NEEDS_PUBLISHABLE_KEY = `Live updates at RelyIO\u2019s edge need a publishable key (\`${PUBLISHABLE_KEY_PREFIX}\u2026\`), and this client holds none. A secret or preview key is never sent to the edge; on a server, follow \`changes()\` with it instead. Nothing was sent.`;
+function sample(value) {
+  const text = typeof value === "string" ? value : `(${typeof value})`;
+  return text.length > 200 ? `${text.slice(0, 200)}\u2026` : text;
+}
+chunkMWMSFIWN_cjs.__name(sample, "sample");
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+chunkMWMSFIWN_cjs.__name(parseJson, "parseJson");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+chunkMWMSFIWN_cjs.__name(isRecord, "isRecord");
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+chunkMWMSFIWN_cjs.__name(hasOwn, "hasOwn");
+
 // src/config/dev-detection.ts
 function sandboxStateOf(resolution) {
   return resolution.state === "active" ? resolution.sandbox : resolution;
@@ -4477,7 +5511,7 @@ var DEFAULT_CONFIG = {
   environment: "production",
   headers: {},
   browser: {
-    includeCredentials: true,
+    includeCredentials: false,
     useRelativeUrls: false
   },
   cache: {
@@ -4509,45 +5543,48 @@ function validateConfig(config) {
   if (config.baseUrl != null && typeof config.baseUrl !== "string") {
     throw new Error("Base URL must be a string");
   }
-  if (config.timeout != null && (typeof config.timeout !== "number" || config.timeout < 0)) {
-    throw new Error("Timeout must be a positive number");
+  if (config.liveUrl != null && typeof config.liveUrl !== "string") {
+    throw new Error("liveUrl must be a string");
+  }
+  if (config.webSocket != null && typeof config.webSocket !== "function") {
+    throw new Error("webSocket must be a WebSocket class");
   }
-  if (config.retryAttempts != null && (typeof config.retryAttempts !== "number" || config.retryAttempts < 0)) {
-    throw new Error("Retry attempts must be a positive number");
+  if (config.timeout != null) assertRequestTimeout(config.timeout);
+  if (config.retryAttempts != null && !(Number.isInteger(config.retryAttempts) && config.retryAttempts >= 1)) {
+    throw new Error(
+      `retryAttempts must be a whole number of at least 1 \u2014 the most attempts one request makes, the first included, so 1 turns retrying off \u2014 and got ${String(config.retryAttempts)}`
+    );
   }
 }
 chunkMWMSFIWN_cjs.__name(validateConfig, "validateConfig");
 var devOverrideNotified = false;
 function resolveConfig(userConfig) {
   validateConfig(userConfig);
-  const merged = {
-    ...DEFAULT_CONFIG,
-    ...userConfig,
-    headers: {
-      ...DEFAULT_CONFIG.headers,
-      ...userConfig.headers
-    },
-    browser: {
-      ...DEFAULT_CONFIG.browser,
-      ...userConfig.browser
-    },
-    cache: {
-      ...DEFAULT_CONFIG.cache,
-      ...userConfig.cache
-    },
-    realtime: {
-      ...DEFAULT_CONFIG.realtime,
-      ...userConfig.realtime
-    },
-    debug: {
-      ...DEFAULT_CONFIG.debug,
-      ...userConfig.debug
-    }
-  };
-  const dev = resolveDevOverride(userConfig.dev);
+  return withHandshake(withDefaults(DEFAULT_CONFIG, userConfig, DEFAULT_CONFIG));
+}
+chunkMWMSFIWN_cjs.__name(resolveConfig, "resolveConfig");
+function resolveConfigUpdate(configured, update) {
+  validateConfig(update);
+  const base = update.apiKey === void 0 ? configured : withoutKeyHeader(configured);
+  return withHandshake(withDefaults(base, update, DEFAULT_CONFIG));
+}
+chunkMWMSFIWN_cjs.__name(resolveConfigUpdate, "resolveConfigUpdate");
+function withConfiguredKey(configured, apiKey) {
+  return { ...withoutKeyHeader(configured), apiKey };
+}
+chunkMWMSFIWN_cjs.__name(withConfiguredKey, "withConfiguredKey");
+function withoutKeyHeader(configured) {
+  return { ...configured, headers: layerHeaders(configured.headers, { [API_KEY_HEADER]: null }) };
+}
+chunkMWMSFIWN_cjs.__name(withoutKeyHeader, "withoutKeyHeader");
+function withHandshake(configured) {
+  const dev = resolveDevOverride(configured.dev);
+  const merged = withDefaults(
+    configured,
+    dev.state === "active" ? { apiKey: dev.apiKey, dataset: dev.sandbox.datasetId } : {},
+    DEFAULT_CONFIG
+  );
   if (dev.state === "active") {
-    merged.apiKey = dev.apiKey;
-    merged.dataset = dev.sandbox.datasetId;
     if (!devOverrideNotified) {
       devOverrideNotified = true;
       console.info(
@@ -4565,30 +5602,69 @@ function resolveConfig(userConfig) {
       `[RelyIO] Your .relyio/dev.json could not be read (${dev.reason}) \u2014 ignoring it and using the configured dataset "${merged.dataset}". Run \`relyio dev\` to rewrite it.`
     );
   }
-  return { config: merged, sandbox: sandboxStateOf(dev) };
+  return { config: merged, sandbox: sandboxStateOf(dev), configured };
 }
-chunkMWMSFIWN_cjs.__name(resolveConfig, "resolveConfig");
+chunkMWMSFIWN_cjs.__name(withHandshake, "withHandshake");
+function withDefaults(base, given, defaults) {
+  const merged = new Map(Object.entries(base));
+  const givenValues = new Map(Object.entries(given ?? {}));
+  const defaultValues = new Map(Object.entries(defaults));
+  for (const key of /* @__PURE__ */ new Set([...merged.keys(), ...givenValues.keys()])) {
+    const fallback = merged.get(key);
+    const value = givenValues.get(key);
+    const givenBag = isOptionBag(value) ? value : void 0;
+    if (isOptionBag(fallback) && key === "headers") {
+      merged.set(key, layerHeaders(fallback, givenBag));
+    } else if (isOptionBag(fallback)) {
+      const defaultBag = defaultValues.get(key);
+      merged.set(key, withDefaults(fallback, givenBag, isOptionBag(defaultBag) ? defaultBag : {}));
+    } else if (value === null) {
+      if (defaultValues.has(key)) merged.set(key, defaultValues.get(key));
+      else merged.delete(key);
+    } else if (value !== void 0) {
+      merged.set(key, value);
+    }
+  }
+  return Object.fromEntries(merged);
+}
+chunkMWMSFIWN_cjs.__name(withDefaults, "withDefaults");
+function isOptionBag(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+chunkMWMSFIWN_cjs.__name(isOptionBag, "isOptionBag");
 
 // src/client/create-client.ts
 var API_VERSION_SEGMENT = "v1";
 var _TypedRelyIOClient = class _TypedRelyIOClient {
   constructor(config) {
+    /**
+     * The one HTTP client every sub-client sends through. `updateConfig()` and `setApiKey()` change it
+     * in place rather than replacing it, so a sub-client taken before either sends through the change.
+     */
     chunkMWMSFIWN_cjs.__publicField(this, "httpClient");
     chunkMWMSFIWN_cjs.__publicField(this, "config");
+    /**
+     * The configuration as `createClient()`, `setApiKey()` and `updateConfig()` gave it, before the
+     * `relyio dev` handshake: what the next update is laid over, and what `withLocale()` starts from.
+     */
+    chunkMWMSFIWN_cjs.__publicField(this, "configured");
     chunkMWMSFIWN_cjs.__publicField(this, "_sandbox");
-    chunkMWMSFIWN_cjs.__publicField(this, "_search");
-    chunkMWMSFIWN_cjs.__publicField(this, "_batch");
-    chunkMWMSFIWN_cjs.__publicField(this, "_adhocQuery");
     chunkMWMSFIWN_cjs.__publicField(this, "_schema");
+    /**
+     * The client's locale as it is when a call is made. Every sub-client and builder is handed this
+     * rather than a copy of the locale, so one taken before `updateConfig({ locale })` sends the new
+     * locale, or none after `locale: null` (REL-1453).
+     */
+    chunkMWMSFIWN_cjs.__publicField(this, "currentLocale", /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => this.config.locale, "currentLocale"));
+    /** The live edge's poll client id: chosen once, when first needed, and kept for this client's life. */
+    chunkMWMSFIWN_cjs.__publicField(this, "_liveClientId");
     const { schema, ...clientConfig } = config;
     this._schema = schema;
     const resolved = resolveConfig(clientConfig);
     this.config = resolved.config;
+    this.configured = resolved.configured;
     this._sandbox = resolved.sandbox;
     this.httpClient = new HttpClient(this.config);
-    this._search = new SearchClient(this.httpClient, this.config.locale);
-    this._batch = new BatchClient(this.httpClient);
-    this._adhocQuery = new AdhocQueryClient(this.httpClient, this.config.locale);
   }
   // ============================================================================
   // CORE CLIENTS
@@ -4617,10 +5693,10 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     return this._sandbox;
   }
   /**
-   * Get the ad-hoc query client
+   * Get the ad-hoc query client. Every query it sends is in the client's locale as it is then.
    */
   get query() {
-    return this._adhocQuery;
+    return new AdhocQueryClient(this.httpClient, this.currentLocale);
   }
   // ============================================================================
   // CONTENT OPERATIONS
@@ -4640,7 +5716,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   content(contentType) {
-    return new ContentClient(this.httpClient, contentType, this.config.locale);
+    return new ContentClient(this.httpClient, contentType, this.currentLocale);
   }
   /**
    * Get an asset client for a specific asset type.
@@ -4661,7 +5737,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   asset(assetType) {
-    return new AssetClient(this.httpClient, assetType, this.config.locale);
+    return new AssetClient(this.httpClient, assetType, this.currentLocale);
   }
   /**
    * Get a singleton client for a specific singleton key
@@ -4676,7 +5752,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   singleton(key) {
-    return new SingletonClient(this.httpClient, key, this.config.locale);
+    return new SingletonClient(this.httpClient, key, this.currentLocale);
   }
   /**
    * Get a settings client for a specific settings group
@@ -4690,7 +5766,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   settings(groupId) {
-    return new SettingsClient(this.httpClient, groupId, this.config.locale);
+    return new SettingsClient(this.httpClient, groupId, this.currentLocale);
   }
   // ============================================================================
   // SEARCH OPERATIONS
@@ -4712,7 +5788,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   search(query) {
-    return this._search.search(query);
+    return this.searchClient().search(query);
   }
   /**
    * Start an autocomplete query for search suggestions
@@ -4728,7 +5804,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   autocomplete(query) {
-    return this._search.autocomplete(query);
+    return this.searchClient().autocomplete(query);
   }
   /**
    * Find content similar to a given entry using vector search
@@ -4743,13 +5819,17 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   similar(sourceId) {
-    return this._search.similar(sourceId);
+    return this.searchClient().similar(sourceId);
   }
   // ============================================================================
   // BATCH OPERATIONS
   // ============================================================================
   /**
-   * Start a batch operation for bulk create/update/delete
+   * Start a batch operation for bulk create/update/delete.
+   *
+   * By default each operation lands or fails on its own. `atomic: true` makes the batch one
+   * transaction, which the API accepts only when every operation is the same kind of write and none
+   * writes a singleton that does not exist yet.
    *
    * @example
    * ```typescript
@@ -4758,13 +5838,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
@@ -4776,13 +5866,15 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * Lazy — nothing is requested until the first `next()`. It runs until
    * `signal` aborts, which ends the `for await` cleanly rather than throwing.
    * A change names what changed; refetch it through the ordinary read path
-   * (`INV-SS-CHANGE-IS-IDS`).
+   * (`INV-SS-CHANGE-IS-IDS`), naming its `fresh` so no cache answers with the
+   * body from before it (`FeedChange`).
    *
    * @example
    * ```typescript
    * const controller = new AbortController()
    * for await (const change of relyio.changes({ since: cursor, types: ['post'], signal: controller.signal })) {
-   *   // { entryId, contentType, locale, kind, cursor }
+   *   // { entryId, contentType, locale, kind, cursor, fresh }
+   *   await relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute()
    * }
    * ```
    *
@@ -4790,13 +5882,60 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```typescript
    * for await (const change of relyio.changes({
    *   since: cursor,
-   *   onExpired: async () => invalidateEverything(),
+   *   onExpired: async expired => refetchEverything(expired.fresh),
    * })) { … }
    * ```
    */
   changes(options = {}) {
     return pollChanges(this.httpClient, options);
   }
+  /**
+   * Follow the dataset's **published** changes at RelyIO's live edge, with a publishable key
+   * (`rly_pub_…`): each change as ids, in order — the transport a browser follows changes with.
+   *
+   * A WebSocket to the edge, from `since` or the dataset's current position; where a socket cannot
+   * open — the runtime has none, or the network refuses it — it polls the edge instead, about every
+   * fifteen seconds, from the same cursor. The edge is `liveUrl`, or derived from the default
+   * `baseUrl` (see `RelyIOConfig.liveUrl`).
+   *
+   * One subscription ends only when `signal` aborts, which ends the `for await` cleanly; every other
+   * end — a socket a deploy dropped, a refusal, a refused poll — is thrown as a `LiveEdgeError`
+   * that says whether to stop, retry or back off. Hand it to `followChanges()`, the one loop that
+   * reconnects from the last cursor with jittered back-off and honours those answers:
+   *
+   * @example
+   * ```typescript
+   * const relyio = createClient({ apiKey: 'rly_pub_…' })
+   * const controller = new AbortController()
+   * await followChanges(from => relyio.liveChanges({ ...from, types: ['post'] }), {
+   *   signal: controller.signal,
+   *   // `fresh` names a position no cache holds a body for from before the change.
+   *   onChange: change =>
+   *     relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute(),
+   *   onResync: resync => refetchEverything(resync.cause === 'expired' ? resync.expired.fresh : undefined),
+   * })
+   * ```
+   *
+   * A client without a publishable key sends nothing: a secret or preview key is never put in the
+   * edge's URL. On a server, follow `changes()` with it instead.
+   */
+  liveChanges(options = {}) {
+    const { apiKey, dataset, baseUrl, liveUrl, fetch: fetch2, webSocket, timeout } = this.config;
+    this._liveClientId ?? (this._liveClientId = randomClientId());
+    return subscribeLiveEdge(
+      {
+        apiKey,
+        dataset,
+        baseUrl,
+        liveUrl,
+        fetch: fetch2,
+        webSocket,
+        timeout,
+        clientId: this._liveClientId
+      },
+      options
+    );
+  }
   /**
    * The dataset's current position in the changes feed, as a cursor to start
    * `changes({ since })` or `followChanges(…, { since })` from. One
@@ -4838,7 +5977,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   adhoc() {
-    return this._adhocQuery.build();
+    return this.query.build();
   }
   /**
    * Execute a predefined query by name (from schema)
@@ -4923,16 +6062,53 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     }
   }
   /**
-   * Update the configuration and reinitialize all clients
+   * Change some of the client's options and keep the rest.
+   *
+   * What you pass is laid over the configuration the client holds, field by field:
+   *
+   * - an option you name replaces the value the client holds;
+   * - an option left out, or given as `undefined`, keeps the value the client holds;
+   * - an option with no default given as `null` is cleared — `locale`, `dataset`, `apiKey`, `dev`,
+   *   `fetch`, `browser.onCorsError`, `realtime.wsUrl`, `debug.logger` — so the client runs as though
+   *   it had never been given one. An option with a default takes no `null`;
+   * - a bag of options you name — `browser`, `cache`, `realtime`, `debug` — keeps every field of it
+   *   you do not name, so `updateConfig({ browser: { includeCredentials: true } })` keeps a
+   *   configured `onCorsError`;
+   * - `headers` is laid over the headers the client sends, a name matched without regard to case: a
+   *   header you name is added or replaces every spelling of it, every other one is still sent, and a
+   *   header given as `null` is no longer sent;
+   * - naming `apiKey` — a key, or `null` — replaces every key the client holds, one given in
+   *   `headers` included.
+   *
+   * The configuration it is laid over is what `createClient()`, `setApiKey()` and earlier updates
+   * gave the client. The `relyio dev` handshake is read again, as `createClient()` reads it: while a
+   * sandbox is active its key and dataset are sent over the configured ones, and once it has gone
+   * the configured ones are.
+   *
+   * The client's one HTTP client is changed in place, so every request from now on is sent as the
+   * update says — including one from a `content()`, `asset()`, `singleton()` or `settings()`
+   * sub-client, a `query` client, or a builder such as `search()` or `batch()`, taken before the
+   * call. The locale reaches them too: each reads the client's locale when it sends, so a new
+   * `locale` is the default of its next request and `locale: null` leaves that request with none. A
+   * locale the call names, and a sub-client's own `withLocale()`, still win over it. A client made
+   * by `withLocale()` is a client of its own: an update of this one does not reach it.
+   *
+   * @example
+   * ```typescript
+   * const relyio = createClient({ apiKey, headers: { 'X-Tenant': 'acme' }, browser: { onCorsError } })
+   *
+   * relyio.updateConfig({ headers: { 'X-Trace': traceId } }) // X-Tenant is still sent
+   * relyio.updateConfig({ browser: { includeCredentials: true } }) // onCorsError is kept
+   * relyio.updateConfig({ headers: { 'X-Tenant': null } }) // X-Tenant is no longer sent
+   * relyio.updateConfig({ locale: null }) // reads name no locale of the client's
+   * ```
    */
-  updateConfig(newConfig) {
-    const resolved = resolveConfig({ ...this.config, ...newConfig });
+  updateConfig(update) {
+    const resolved = resolveConfigUpdate(this.configured, update);
     this.config = resolved.config;
+    this.configured = resolved.configured;
     this._sandbox = resolved.sandbox;
-    this.httpClient = new HttpClient(this.config);
-    this._search = new SearchClient(this.httpClient, this.config.locale);
-    this._batch = new BatchClient(this.httpClient);
-    this._adhocQuery = new AdhocQueryClient(this.httpClient, this.config.locale);
+    this.httpClient.configure(this.config);
   }
   /**
    * Get the current configuration
@@ -4941,11 +6117,31 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     return { ...this.config };
   }
   /**
-   * Set the API key
+   * Replace the API key every later request sends as `X-API-Key`.
+   *
+   * It reaches every request this client makes from now on, including those of a `content()`,
+   * `asset()` or other sub-client taken before the call, and `getConfig().apiKey` reports it. A key
+   * given in `headers`, under any spelling, is replaced with it and does not come back on a later
+   * `updateConfig()`. A client already derived with `withLocale()` is a client of its own and keeps
+   * its key.
+   *
+   * An empty or blank key is no key, as it is when passed to `createClient`: the next request
+   * rejects with `MissingApiKeyError` and nothing is sent.
+   *
+   * Under an active `relyio dev` sandbox the sandbox's scoped key stands, as it does over the key
+   * passed to `createClient` — replacing the configured key does not retarget the client at the
+   * sandbox's dataset with a key the sandbox did not issue.
+   *
+   * @example
+   * ```typescript
+   * const relyio = createClient({ apiKey: process.env.RELYIO_API_KEY! })
+   * relyio.setApiKey(rotatedKey) // the next read sends `X-API-Key: <rotatedKey>`
+   * ```
    */
   setApiKey(apiKey) {
-    this.config.apiKey = apiKey;
-    this.httpClient.setAuthToken(apiKey);
+    this.configured = withConfiguredKey(this.configured, apiKey);
+    if (this._sandbox.state === "active") return;
+    this.httpClient.setApiKey(apiKey);
   }
   /**
    * Get the HTTP client instance (for advanced usage)
@@ -4959,9 +6155,12 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   /**
    * Create a locale-scoped client
    *
-   * Every read the returned client builds — `content()`, `asset()`, `singleton()`, `settings()`,
-   * `search()`, `similar()`, `autocomplete()`, `executeQuery()` and the ad-hoc queries — is in this
-   * locale unless the call names one of its own, which wins.
+   * Every call the returned client builds is in this locale unless the call names one of its own,
+   * which wins: every read — `content()`, `asset()`, `singleton()`, `settings()`, `search()`,
+   * `similar()`, `autocomplete()`, `executeQuery()` and the ad-hoc queries — and every write and
+   * version-history read — `create()` and `update()`, the singleton and settings writes, the asset
+   * file writes, `versions()` and `version()`, and each operation `batch()` builds. `restore()`
+   * always names its locale; a delete, and a `batch().raw()` operation, carry none of the client's.
    *
    * Type-safe when schema is provided: autocompletes valid locale codes!
    *
@@ -4969,10 +6168,11 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```typescript
    * const spanish = relyio.withLocale('es-ES')  // ← Autocompletes with schema!
    *
-   * // Reads use Spanish
+   * // Reads and writes use Spanish
    * const products = await spanish.content('product').query().execute()
    * const homepage = await spanish.singleton('homepage').fetch()
    * const results = await spanish.search('zapatos').execute()
+   * await spanish.content('product').update(id, { title: 'Zapatos' })
    *
    * // Original client unchanged
    * const englishProducts = await relyio.content('product').query().execute()
@@ -4980,7 +6180,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    */
   withLocale(locale) {
     const newConfig = {
-      ...this.getConfig(),
+      ...this.configured,
       locale,
       schema: this._schema
     };
@@ -5028,13 +6228,25 @@ function createClient(config) {
   return new TypedRelyIOClient(config);
 }
 chunkMWMSFIWN_cjs.__name(createClient, "createClient");
+function randomClientId() {
+  const bytes = new Uint8Array(16);
+  const random = globalThis.crypto;
+  if (typeof random?.getRandomValues === "function") {
+    random.getRandomValues.call(random, bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+chunkMWMSFIWN_cjs.__name(randomClientId, "randomClientId");
 
 exports.AdhocQueryBuilder = AdhocQueryBuilder;
 exports.AdhocQueryClient = AdhocQueryClient;
 exports.AssetClient = AssetClient;
 exports.AssetFileBuilder = AssetFileBuilder;
 exports.AssetUploadBuilder = AssetUploadBuilder;
-exports.AuthenticationError = AuthenticationError;
 exports.AuthorizationError = AuthorizationError;
 exports.AutocompleteBuilder = AutocompleteBuilder;
 exports.BaseValidationError = BaseValidationError;
@@ -5050,21 +6262,21 @@ exports.FileUploadError = FileUploadError;
 exports.FileValidationError = FileValidationError;
 exports.HttpClient = HttpClient;
 exports.InvalidApiKeyError = InvalidApiKeyError;
-exports.InvalidFieldTypeError = InvalidFieldTypeError;
 exports.InvalidPayloadError = InvalidPayloadError;
+exports.LIVE_KEEPALIVE_INTERVAL_MS = LIVE_KEEPALIVE_INTERVAL_MS;
+exports.LiveEdgeError = LiveEdgeError;
 exports.MethodNotAllowedError = MethodNotAllowedError;
 exports.MissingApiKeyError = MissingApiKeyError;
 exports.NetworkError = NetworkError;
+exports.PUBLISHABLE_KEY_PREFIX = PUBLISHABLE_KEY_PREFIX;
 exports.PayloadTooLargeError = PayloadTooLargeError;
 exports.PlanFeatureUnavailableError = PlanFeatureUnavailableError;
 exports.RateLimitError = RateLimitError;
 exports.ReadOnlyKeyError = ReadOnlyKeyError;
-exports.RequiredFieldError = RequiredFieldError;
 exports.ResourceConflictError = ResourceConflictError;
 exports.ResourceExpiredError = ResourceExpiredError;
 exports.ResourceNotFoundError = ResourceNotFoundError;
 exports.SDKError = SDKError;
-exports.SchemaValidationError = SchemaValidationError;
 exports.SearchBuilder = SearchBuilder;
 exports.SearchClient = SearchClient;
 exports.ServerError = ServerError;
@@ -5077,15 +6289,17 @@ exports.TransactionRolledBackError = TransactionRolledBackError;
 exports.TypedRelyIOClient = TypedRelyIOClient;
 exports.UnknownContractError = UnknownContractError;
 exports.UsageQuotaExceededError = UsageQuotaExceededError;
+exports.VISITOR_ADMISSION_RETRY_AFTER_SECONDS = VISITOR_ADMISSION_RETRY_AFTER_SECONDS;
 exports.ValidationError = ValidationError;
 exports.createClient = createClient;
 exports.entityTagOf = entityTagOf;
 exports.isAborted = isAborted;
 exports.isAssetEntry = isAssetEntry;
+exports.isPublishableKey = isPublishableKey;
 exports.isResourceNotFound = isResourceNotFound;
 exports.matchRoute = matchRoute;
 exports.serviceInstructedDelayMs = serviceInstructedDelayMs;
 exports.sleep = sleep;
 exports.validateFile = validateFile;
-//# sourceMappingURL=chunk-GCMQUM6N.cjs.map
-//# sourceMappingURL=chunk-GCMQUM6N.cjs.map
+//# sourceMappingURL=chunk-XIE7WJV3.cjs.map
+//# sourceMappingURL=chunk-XIE7WJV3.cjs.map