@relyio/sdk 0.4.0 → 0.6.0

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

@@ -71,44 +71,6 @@ var _SDKError = class _SDKError extends Error {
 chunkMWMSFIWN_cjs.__name(_SDKError, "SDKError");
 var SDKError = _SDKError;
 
-// src/errors/auth-errors.ts
-var _AuthenticationError = class _AuthenticationError extends SDKError {
-  constructor(message = "Authentication failed", statusCode = 401, cause, context) {
-    super(message, statusCode, cause, context);
-    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);
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "AUTHORIZATION_ERROR");
-    chunkMWMSFIWN_cjs.__publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "You do not have permission to access this resource.";
-  }
-};
-chunkMWMSFIWN_cjs.__name(_AuthorizationError, "AuthorizationError");
-var AuthorizationError = _AuthorizationError;
-var _InvalidApiKeyError = class _InvalidApiKeyError extends SDKError {
-  constructor(message = "Invalid API key", cause, context) {
-    super(message, 401, cause, context);
-    chunkMWMSFIWN_cjs.__publicField(this, "code", "INVALID_API_KEY");
-    chunkMWMSFIWN_cjs.__publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "Invalid API key. Please check your API key and try again.";
-  }
-};
-chunkMWMSFIWN_cjs.__name(_InvalidApiKeyError, "InvalidApiKeyError");
-var InvalidApiKeyError = _InvalidApiKeyError;
-
 // src/errors/contract-errors.ts
 var _MissingApiKeyError = class _MissingApiKeyError extends SDKError {
   constructor(message = "No API key was sent", context) {
@@ -269,6 +231,44 @@ var _UnknownContractError = class _UnknownContractError extends SDKError {
 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);
+    chunkMWMSFIWN_cjs.__publicField(this, "code", "AUTHORIZATION_ERROR");
+    chunkMWMSFIWN_cjs.__publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    return "You do not have permission to access this resource.";
+  }
+};
+chunkMWMSFIWN_cjs.__name(_AuthorizationError, "AuthorizationError");
+var AuthorizationError = _AuthorizationError;
+var _InvalidApiKeyError = class _InvalidApiKeyError extends SDKError {
+  constructor(message = "Invalid API key", cause, context) {
+    super(message, 401, cause, context);
+    chunkMWMSFIWN_cjs.__publicField(this, "code", "INVALID_API_KEY");
+    chunkMWMSFIWN_cjs.__publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    return "Invalid API key. Please check your API key and try again.";
+  }
+};
+chunkMWMSFIWN_cjs.__name(_InvalidApiKeyError, "InvalidApiKeyError");
+var InvalidApiKeyError = _InvalidApiKeyError;
+
 // src/errors/content-errors.ts
 var _ResourceNotFoundError = class _ResourceNotFoundError extends SDKError {
   constructor(message = "Resource not found", statusCode = 404, cause, context) {
@@ -330,8 +330,12 @@ var _NetworkError = class _NetworkError extends SDKError {
 chunkMWMSFIWN_cjs.__name(_NetworkError, "NetworkError");
 var NetworkError = _NetworkError;
 var _TimeoutError = class _TimeoutError extends SDKError {
-  constructor(message = "Request timed out", timeout, statusCode, cause) {
-    super(message, statusCode, cause, { timeout });
+  /**
+   * @param context - Carried beside `timeout`. The mapper passes a `REQUEST_TIMEOUT` refusal's body
+   *   as `context.response`, as it does for every other contract code.
+   */
+  constructor(message = "Request timed out", timeout, statusCode, cause, context) {
+    super(message, statusCode, cause, { ...context, timeout });
     chunkMWMSFIWN_cjs.__publicField(this, "code", "TIMEOUT_ERROR");
     chunkMWMSFIWN_cjs.__publicField(this, "retryable", true);
   }
@@ -357,8 +361,13 @@ var ConnectionError = _ConnectionError;
 
 // src/errors/validation-errors.ts
 var _BaseValidationError = class _BaseValidationError extends SDKError {
-  constructor(message = "Validation failed", violations = [], statusCode = 400, cause) {
-    super(message, statusCode, cause, { violations });
+  /**
+   * @param context - Carried beside `violations`. The mapper passes the refusal body as
+   *   `context.response`, as it does for every other contract code, so a consumer that hands the
+   *   service's own words on can read them here too.
+   */
+  constructor(message = "Validation failed", violations = [], statusCode = 400, cause, context) {
+    super(message, statusCode, cause, { ...context, violations });
     chunkMWMSFIWN_cjs.__publicField(this, "retryable", false);
     chunkMWMSFIWN_cjs.__publicField(this, "violations");
     this.violations = violations;
@@ -403,8 +412,8 @@ var _ValidationError = class _ValidationError extends BaseValidationError {
 chunkMWMSFIWN_cjs.__name(_ValidationError, "ValidationError");
 var ValidationError = _ValidationError;
 var _InvalidPayloadError = class _InvalidPayloadError extends BaseValidationError {
-  constructor(message = "Invalid payload", violations = [], cause) {
-    super(message, violations, 400, cause);
+  constructor(message = "Invalid payload", violations = [], cause, context) {
+    super(message, violations, 400, cause, context);
     chunkMWMSFIWN_cjs.__publicField(this, "code", "INVALID_PAYLOAD");
   }
   getUserMessage() {
@@ -593,10 +602,10 @@ var _ErrorMapper = class _ErrorMapper {
         );
       }
       case "REQUEST_INVALID": {
-        return new InvalidPayloadError(message, violationsOf(refusal));
+        return new InvalidPayloadError(message, violationsOf(refusal), void 0, context);
       }
       case "CONTENT_INVALID": {
-        return new ValidationError(message, violationsOf(refusal), 400);
+        return new ValidationError(message, violationsOf(refusal), 400, void 0, context);
       }
       case "METHOD_NOT_ALLOWED": {
         return new MethodNotAllowedError(message, context);
@@ -619,7 +628,7 @@ var _ErrorMapper = class _ErrorMapper {
         return new ResourceExpiredError(message, 410, void 0, context);
       }
       case "REQUEST_TIMEOUT": {
-        return new TimeoutError(message, void 0, void 0, void 0);
+        return new TimeoutError(message, void 0, status, void 0, context);
       }
       case "PAYLOAD_TOO_LARGE": {
         return new PayloadTooLargeError(message, detailNumber(refusal, "limitBytes"), context);
@@ -770,6 +779,7 @@ var DECLARED_PATHS = {
   "/v1/meta/schema": true,
   "/v1/meta/schema/{contentType}": true,
   "/v1/meta/schema/{contentType}/fields": true,
+  "/v1/project": true,
   "/v1/query": true,
   "/v1/search": true,
   "/v1/search/autocomplete": true,
@@ -841,20 +851,29 @@ function readQuery(searchParams) {
 }
 chunkMWMSFIWN_cjs.__name(readQuery, "readQuery");
 
-// src/http/retry-policy.ts
-var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
-  "GET",
-  "HEAD",
-  "OPTIONS",
-  "PUT",
-  "DELETE",
-  "TRACE"
-]);
-function isReplaySafe(request) {
-  if (IDEMPOTENT_METHODS.has(request.method.toUpperCase())) return true;
-  return headerValue(request.headers, HEADER_IDEMPOTENCY_KEY.name) !== void 0;
+// src/http/abortable-sleep.ts
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (isAborted(signal)) {
+      resolve();
+      return;
+    }
+    const done = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }, "done");
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
 }
-chunkMWMSFIWN_cjs.__name(isReplaySafe, "isReplaySafe");
+chunkMWMSFIWN_cjs.__name(sleep, "sleep");
+function isAborted(signal) {
+  return signal?.aborted === true;
+}
+chunkMWMSFIWN_cjs.__name(isAborted, "isAborted");
+
+// src/errors/instructed-delay.ts
 function serviceInstructedDelayMs(error, nowMs) {
   if (error instanceof ServiceIndeterminateError) {
     return error.retryAfterMs;
@@ -868,6 +887,21 @@ function serviceInstructedDelayMs(error, nowMs) {
   return wait > 0 ? wait : void 0;
 }
 chunkMWMSFIWN_cjs.__name(serviceInstructedDelayMs, "serviceInstructedDelayMs");
+
+// src/http/retry-policy.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "HEAD",
+  "OPTIONS",
+  "PUT",
+  "DELETE",
+  "TRACE"
+]);
+function isReplaySafe(request) {
+  if (IDEMPOTENT_METHODS.has(request.method.toUpperCase())) return true;
+  return headerValue(request.headers, HEADER_IDEMPOTENCY_KEY.name) !== void 0;
+}
+chunkMWMSFIWN_cjs.__name(isReplaySafe, "isReplaySafe");
 var _DefaultRetryPolicy = class _DefaultRetryPolicy {
   constructor(config) {
     chunkMWMSFIWN_cjs.__publicField(this, "config");
@@ -904,9 +938,10 @@ var _HttpClient = class _HttpClient {
     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",
-      "X-API-Key": config.apiKey,
+      ...apiKey === void 0 ? {} : { [API_KEY_HEADER]: apiKey },
       ...config.headers
     };
     if (config.dataset != null) {
@@ -965,9 +1000,21 @@ 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`.
+   *
+   * 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).
    */
   async request(config) {
     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.",
+        { url: mergedConfig.url, method: mergedConfig.method, sent: false }
+      );
+    }
     this.log("debug", "Making request", {
       method: mergedConfig.method,
       url: mergedConfig.url
@@ -996,7 +1043,7 @@ var _HttpClient = class _HttpClient {
         if (this.retryPolicy.shouldRetry(attempt, failure, mergedConfig)) {
           const delay = this.retryPolicy.delayFor(attempt, failure);
           this.log("debug", "Retrying request", { attempt, delay });
-          await this.sleep(delay, config.signal);
+          await sleep(delay, config.signal);
           continue;
         }
         const sdkError = ErrorMapper.mapGenericError(failure, {
@@ -1125,8 +1172,12 @@ var _HttpClient = class _HttpClient {
         headers: filteredHeaders,
         body: this.prepareRequestBody(config),
         signal: controller.signal,
-        // Include credentials for CORS requests if in browser and configured
-        ...typeof window !== "undefined" && this.config.browser.includeCredentials != null && { credentials: "include" }
+        // Only 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)
+        }
       };
       const send = this.config.fetch ?? globalThis.fetch;
       const response = await send(url, requestInit);
@@ -1282,22 +1333,6 @@ var _HttpClient = class _HttpClient {
     });
     return obj;
   }
-  /** A backoff the caller's abort cuts short; the next attempt then refuses to send. */
-  sleep(ms, signal) {
-    return new Promise((resolve) => {
-      if (isAborted(signal)) {
-        resolve();
-        return;
-      }
-      const done = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => {
-        clearTimeout(timer);
-        signal?.removeEventListener("abort", done);
-        resolve();
-      }, "done");
-      const timer = setTimeout(done, ms);
-      signal?.addEventListener("abort", done, { once: true });
-    });
-  }
   log(level, message, data) {
     if (!this.debug) return;
     if (this.logger != null) {
@@ -1309,10 +1344,23 @@ var _HttpClient = class _HttpClient {
 };
 chunkMWMSFIWN_cjs.__name(_HttpClient, "HttpClient");
 var HttpClient = _HttpClient;
-function isAborted(signal) {
-  return signal?.aborted === true;
+var API_KEY_HEADER = "X-API-Key";
+function presentKey(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
 }
-chunkMWMSFIWN_cjs.__name(isAborted, "isAborted");
+chunkMWMSFIWN_cjs.__name(presentKey, "presentKey");
+function credentialsModeFor(includeCredentials) {
+  switch (includeCredentials) {
+    case false: {
+      return "same-origin";
+    }
+    case true:
+    case void 0: {
+      return "include";
+    }
+  }
+}
+chunkMWMSFIWN_cjs.__name(credentialsModeFor, "credentialsModeFor");
 
 // src/content/query-builder.ts
 var _ContentQueryBuilder = class _ContentQueryBuilder {
@@ -1328,6 +1376,16 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     chunkMWMSFIWN_cjs.__publicField(this, "childrenOptions");
     chunkMWMSFIWN_cjs.__publicField(this, "pageNumber");
     chunkMWMSFIWN_cjs.__publicField(this, "pageSizeValue");
+    chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
+  }
+  /**
+   * Headers this query adds to the client's own, e.g. `X-RelyIO-Dataset` to list another dataset
+   * the key can see. A name the client already sends is replaced for this query only; the client
+   * is not changed.
+   */
+  headers(headers) {
+    this.requestHeaders = headers;
+    return this;
   }
   /**
    * Add where conditions to the query
@@ -1525,7 +1583,11 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     const response = await this.httpClient.send(
       "/v1/{contentType}",
       "get",
-      { path: { contentType: this.contentType }, query: this.buildQueryParams() }
+      {
+        path: { contentType: this.contentType },
+        query: this.buildQueryParams(),
+        headers: this.requestHeaders
+      }
     );
     return response.body;
   }
@@ -1593,6 +1655,7 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     cloned.fieldsProjection = this.fieldsProjection ? [...this.fieldsProjection] : void 0;
     cloned.pageNumber = this.pageNumber;
     cloned.pageSizeValue = this.pageSizeValue;
+    cloned.requestHeaders = this.requestHeaders ? { ...this.requestHeaders } : void 0;
     return cloned;
   }
   /**
@@ -1700,6 +1763,7 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
     chunkMWMSFIWN_cjs.__publicField(this, "localesArray");
     chunkMWMSFIWN_cjs.__publicField(this, "fetchAllLocales", false);
     chunkMWMSFIWN_cjs.__publicField(this, "childrenOptions");
+    chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
   }
   /**
    * Include related content in the response
@@ -1730,6 +1794,15 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
     this.fetchAllLocales = false;
     return this;
   }
+  /**
+   * Headers this one read adds to the client's own, e.g. `X-RelyIO-Dataset` to read another dataset
+   * the key can see. A name the client already sends is replaced for this request only; the client
+   * is not changed.
+   */
+  headers(headers) {
+    this.requestHeaders = headers;
+    return this;
+  }
   /**
    * Fetch content in all available locales
    * Returns default locale at top level, others in _metadata.localizations
@@ -1783,7 +1856,11 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
       return await this.httpClient.fetchPayload(
         "/v1/{contentType}/{id}",
         "get",
-        { path: { contentType: this.contentType, id: this.id }, query: params }
+        {
+          path: { contentType: this.contentType, id: this.id },
+          query: params,
+          headers: this.requestHeaders
+        }
       );
     } catch (error) {
       if (isResourceNotFound(error)) return null;
@@ -1813,6 +1890,14 @@ function writeHeaders(options) {
   return Object.keys(headers).length > 0 ? headers : void 0;
 }
 chunkMWMSFIWN_cjs.__name(writeHeaders, "writeHeaders");
+function requestHeaders(headers, typed) {
+  if (headers === void 0) return typed;
+  if (typed === void 0) return headers;
+  const typedNames = new Set(Object.keys(typed).map((name) => name.toLowerCase()));
+  const own = Object.entries(headers).filter(([name]) => !typedNames.has(name.toLowerCase()));
+  return { ...Object.fromEntries(own), ...typed };
+}
+chunkMWMSFIWN_cjs.__name(requestHeaders, "requestHeaders");
 function entityTagOf(response) {
   return headerValue(response.headers, HEADER_ENTITY_TAG.name);
 }
@@ -1882,7 +1967,8 @@ var _ContentClient = class _ContentClient {
   /**
    * Fetch a single content item by ID
    * @param id - Entry ID or slug
-   * @param options - Fetch options (include, locale)
+   * @param options - Fetch options (include, locale, and `headers` this one request adds — e.g.
+   *   `{ 'X-RelyIO-Dataset': 'staging' }` to read a dataset other than the client's)
    */
   async fetchOne(id, options) {
     const builder = this.findById(id);
@@ -1892,6 +1978,9 @@ var _ContentClient = class _ContentClient {
     if (options?.locale != null && options.locale !== "") {
       builder.locale(options.locale);
     }
+    if (options?.headers != null) {
+      builder.headers(options.headers);
+    }
     return builder.execute();
   }
   /**
@@ -1906,6 +1995,11 @@ var _ContentClient = class _ContentClient {
    * `entityTag` is `undefined` when the response came from the cache: a cached
    * body cannot know the current version, and an absent tag beats a stale one
    * that would refuse the next write.
+   *
+   * Unlike {@link fetchOne}, a missing entry is not `null`: the service's
+   * `RESOURCE_NOT_FOUND` is thrown as it arrived, with the `kind` that says
+   * whether the entry, the content type or the schema was missing. `headers`
+   * are the ones this read adds, as for `fetchOne`.
    */
   async fetchOneWithTag(id, options) {
     const query = {};
@@ -1915,7 +2009,7 @@ var _ContentClient = class _ContentClient {
     const response = await this.httpClient.send(
       "/v1/{contentType}/{id}",
       "get",
-      { path: { contentType: this.contentType, id }, query }
+      { path: { contentType: this.contentType, id }, query, headers: options?.headers }
     );
     return { entry: readPayload(response.body), entityTag: entityTagOf(response) };
   }
@@ -1937,17 +2031,20 @@ var _ContentClient = class _ContentClient {
   /**
    * Create a new content item
    * @param data - Content data
-   * @param options - Create options (slug, locale, parentId, sortOrder)
+   * @param options - Create options (slug, locale, parentId, sortOrder), and `headers` this one
+   *   request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset other than the
+   *   client's. They are sent, never put in the body; `idempotencyKey` still wins over an
+   *   `Idempotency-Key` among them.
    */
   async create(data, options) {
-    const { idempotencyKey, ...body } = options ?? {};
+    const { idempotencyKey, headers, ...body } = options ?? {};
     return this.httpClient.fetchPayload(
       "/v1/{contentType}",
       "post",
       {
         path: { contentType: this.contentType },
         body: { content: data, ...body },
-        headers: writeHeaders({ idempotencyKey })
+        headers: requestHeaders(headers, writeHeaders({ idempotencyKey }))
       }
     );
   }
@@ -1955,17 +2052,19 @@ var _ContentClient = class _ContentClient {
    * Update a content item by ID (partial update)
    * @param id - Entry ID
    * @param data - Fields to update
-   * @param options - Update options (slug, locale, parentId, sortOrder)
+   * @param options - Update options (slug, locale, parentId, sortOrder), and `headers` this one
+   *   request adds, as for {@link create}. `ifMatch` and `idempotencyKey` win over the same
+   *   header among them.
    */
   async update(id, data, options) {
-    const { idempotencyKey, ifMatch, ...body } = options ?? {};
+    const { idempotencyKey, ifMatch, headers, ...body } = options ?? {};
     return this.httpClient.fetchPayload(
       "/v1/{contentType}/{id}",
       "patch",
       {
         path: { contentType: this.contentType, id },
         body: { content: data, ...body },
-        headers: writeHeaders({ idempotencyKey, ifMatch })
+        headers: requestHeaders(headers, writeHeaders({ idempotencyKey, ifMatch }))
       }
     );
   }
@@ -2060,8 +2159,9 @@ var _ContentClient = class _ContentClient {
     if (options?.include != null) {
       params.include = options.include.join(",");
     }
-    if (options?.locale != null && options.locale !== "") {
-      params.locale = options.locale;
+    const locale = options?.locale ?? this.defaultLocale;
+    if (locale != null && locale !== "") {
+      params.locale = locale;
     }
     return this.httpClient.fetchPayload(
       "/v1/{contentType}/{id}/children",
@@ -2719,9 +2819,10 @@ chunkMWMSFIWN_cjs.__name(isAssetEntry, "isAssetEntry");
 
 // src/content/singleton-client.ts
 var _SingletonClient = class _SingletonClient {
-  constructor(httpClient, singletonKey) {
+  constructor(httpClient, singletonKey, defaultLocale) {
     this.httpClient = httpClient;
     this.singletonKey = singletonKey;
+    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "includeFields");
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
   }
@@ -2746,11 +2847,6 @@ var _SingletonClient = class _SingletonClient {
    * @param options - Optional fetch options (alternative to fluent methods)
    */
   async fetch(options) {
-    const includeValue = options?.include ?? this.includeFields;
-    options?.locale ?? this.localeValue;
-    if (includeValue) {
-      includeValue.join(",");
-    }
     try {
       return (await this.fetchWithTag(options)).content;
     } catch (error) {
@@ -2768,7 +2864,7 @@ var _SingletonClient = class _SingletonClient {
   async fetchWithTag(options) {
     const query = {};
     const includeValue = options?.include ?? this.includeFields;
-    const localeValueFinal = options?.locale ?? this.localeValue;
+    const localeValueFinal = options?.locale ?? this.localeValue ?? this.defaultLocale;
     if (includeValue) query.include = includeValue.join(",");
     if (localeValueFinal != null && localeValueFinal !== "") query.locale = localeValueFinal;
     const response = await this.httpClient.send(
@@ -2865,9 +2961,10 @@ var SingletonClient = _SingletonClient;
 
 // src/content/settings-client.ts
 var _SettingsClient = class _SettingsClient {
-  constructor(httpClient, groupId) {
+  constructor(httpClient, groupId, defaultLocale) {
     this.httpClient = httpClient;
     this.groupId = groupId;
+    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "includeFields");
     chunkMWMSFIWN_cjs.__publicField(this, "localeValue");
   }
@@ -2892,11 +2989,6 @@ var _SettingsClient = class _SettingsClient {
    * @param options - Optional fetch options (alternative to fluent methods)
    */
   async fetch(options) {
-    const includeValue = options?.include ?? this.includeFields;
-    options?.locale ?? this.localeValue;
-    if (includeValue) {
-      includeValue.join(",");
-    }
     try {
       return (await this.fetchWithTag(options)).settings;
     } catch (error) {
@@ -2926,7 +3018,7 @@ var _SettingsClient = class _SettingsClient {
   async fetchWithTag(options) {
     const query = {};
     const includeValue = options?.include ?? this.includeFields;
-    const localeValueFinal = options?.locale ?? this.localeValue;
+    const localeValueFinal = options?.locale ?? this.localeValue ?? this.defaultLocale;
     if (includeValue) query.include = includeValue.join(",");
     if (localeValueFinal != null && localeValueFinal !== "") query.locale = localeValueFinal;
     const response = await this.httpClient.send(
@@ -3028,14 +3120,28 @@ var SettingsClient = _SettingsClient;
 
 // src/search/search-client.ts
 var _SearchBuilder = class _SearchBuilder {
-  constructor(httpClient, query) {
+  /**
+   * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+   */
+  constructor(httpClient, query, defaultLocale) {
     this.httpClient = httpClient;
+    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "query");
     chunkMWMSFIWN_cjs.__publicField(this, "searchOptions", {});
+    chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
     this.query = query;
   }
   /**
-   * Search within a single content type
+   * Headers this search adds to the client's own, e.g. `X-RelyIO-Dataset` to search another
+   * dataset the key can see. A name the client already sends is replaced for this search only.
+   */
+  headers(headers) {
+    this.requestHeaders = headers;
+    return this;
+  }
+  /**
+   * Search within a single content type. Where a schema types the client, the name is one of its
+   * content types and the results are that type's entries.
    * @param contentType - Content type to search in
    */
   in(contentType) {
@@ -3044,7 +3150,8 @@ var _SearchBuilder = class _SearchBuilder {
     return this;
   }
   /**
-   * Search across multiple content types
+   * Search across multiple content types. Where a schema types the client, the names are its content
+   * types and the results are a union of their entries — every type's, for `'*'`.
    * @param contentTypes - Array of content types or '*' for all
    */
   across(contentTypes) {
@@ -3079,6 +3186,16 @@ var _SearchBuilder = class _SearchBuilder {
     this.searchOptions.fields = projection;
     return this;
   }
+  /**
+   * Order the results by a field instead of by relevance. Called again, it adds a tie-breaker.
+   * `_score` names relevance itself.
+   * @param field - Field path to sort by (e.g. `updatedAt`, `pricing.basePrice`)
+   * @param direction - `asc` or `desc` (the route's default is `desc`)
+   */
+  sort(field, direction = "desc") {
+    this.searchOptions.sort = [...this.searchOptions.sort ?? [], { field, direction }];
+    return this;
+  }
   /**
    * Limit number of results
    * @param count - Maximum results
@@ -3139,6 +3256,9 @@ var _SearchBuilder = class _SearchBuilder {
     if (this.searchOptions.fields) {
       body.fields = this.searchOptions.fields;
     }
+    if (this.searchOptions.sort) {
+      body.sort = this.searchOptions.sort;
+    }
     if (this.searchOptions.limit !== void 0) {
       body.limit = this.searchOptions.limit;
     }
@@ -3151,13 +3271,14 @@ var _SearchBuilder = class _SearchBuilder {
     if (this.searchOptions.explain === true) {
       body.explain = true;
     }
-    if (this.searchOptions.locale != null && this.searchOptions.locale !== "") {
-      body.locale = this.searchOptions.locale;
+    const locale = this.searchOptions.locale ?? this.defaultLocale;
+    if (locale != null && locale !== "") {
+      body.locale = locale;
     }
     const response = await this.httpClient.send(
       "/v1/search",
       "post",
-      { body }
+      { body, headers: this.requestHeaders }
     );
     return response.body;
   }
@@ -3177,8 +3298,12 @@ var _SearchBuilder = class _SearchBuilder {
 chunkMWMSFIWN_cjs.__name(_SearchBuilder, "SearchBuilder");
 var SearchBuilder = _SearchBuilder;
 var _AutocompleteBuilder = class _AutocompleteBuilder {
-  constructor(httpClient, query) {
+  /**
+   * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+   */
+  constructor(httpClient, query, defaultLocale) {
     this.httpClient = httpClient;
+    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "query");
     chunkMWMSFIWN_cjs.__publicField(this, "autocompleteOptions", {});
     this.query = query;
@@ -3257,8 +3382,9 @@ var _AutocompleteBuilder = class _AutocompleteBuilder {
     if (this.autocompleteOptions.limit !== void 0) {
       body.limit = this.autocompleteOptions.limit;
     }
-    if (this.autocompleteOptions.locale != null && this.autocompleteOptions.locale !== "") {
-      body.locale = this.autocompleteOptions.locale;
+    const locale = this.autocompleteOptions.locale ?? this.defaultLocale;
+    if (locale != null && locale !== "") {
+      body.locale = locale;
     }
     const response = await this.httpClient.send("/v1/search/autocomplete", "post", { body });
     return response.body;
@@ -3273,18 +3399,41 @@ var _AutocompleteBuilder = class _AutocompleteBuilder {
 chunkMWMSFIWN_cjs.__name(_AutocompleteBuilder, "AutocompleteBuilder");
 var AutocompleteBuilder = _AutocompleteBuilder;
 var _SimilarBuilder = class _SimilarBuilder {
-  constructor(httpClient, sourceId) {
+  /**
+   * @param defaultLocale - The client's locale (`withLocale()`), sent when `.locale()` names none
+   */
+  constructor(httpClient, sourceId, defaultLocale) {
     this.httpClient = httpClient;
+    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "sourceId");
     chunkMWMSFIWN_cjs.__publicField(this, "similarOptions", {});
+    chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
     this.sourceId = sourceId;
   }
+  /**
+   * Headers this read adds to the client's own, e.g. `X-RelyIO-Dataset` to read another dataset
+   * the key can see. A name the client already sends is replaced for this read only.
+   */
+  headers(headers) {
+    this.requestHeaders = headers;
+    return this;
+  }
   /**
    * Find similar content within a content type
    * @param contentType - Content type to search
    */
   in(contentType) {
     this.similarOptions.contentType = contentType;
+    this.similarOptions.contentTypes = void 0;
+    return this;
+  }
+  /**
+   * Find similar content across several content types, or `'*'` for every type
+   * @param contentTypes - Array of content types or '*' for all
+   */
+  across(contentTypes) {
+    this.similarOptions.contentTypes = contentTypes;
+    this.similarOptions.contentType = void 0;
     return this;
   }
   /**
@@ -3318,26 +3467,33 @@ var _SimilarBuilder = class _SimilarBuilder {
    * Execute the similar query
    */
   async execute() {
-    if (this.similarOptions.contentType == null || this.similarOptions.contentType === "") {
-      throw new Error('Content type is required for similar search. Use .in("contentType")');
+    const { contentType, contentTypes } = this.similarOptions;
+    if ((contentType == null || contentType === "") && contentTypes == null) {
+      throw new Error(
+        'Content type is required for similar search. Use .in("contentType") or .across("*")'
+      );
+    }
+    const body = { source: this.sourceId };
+    if (contentType != null && contentType !== "") {
+      body.contentType = contentType;
+    }
+    if (contentTypes != null) {
+      body.contentTypes = contentTypes;
     }
-    const body = {
-      source: this.sourceId,
-      contentType: this.similarOptions.contentType
-    };
     if (this.similarOptions.where && Object.keys(this.similarOptions.where).length > 0) {
       body.where = this.similarOptions.where;
     }
     if (this.similarOptions.limit !== void 0) {
       body.limit = this.similarOptions.limit;
     }
-    if (this.similarOptions.locale != null && this.similarOptions.locale !== "") {
-      body.locale = this.similarOptions.locale;
+    const locale = this.similarOptions.locale ?? this.defaultLocale;
+    if (locale != null && locale !== "") {
+      body.locale = locale;
     }
     const response = await this.httpClient.send(
       "/v1/search/similar",
       "post",
-      { body }
+      { body, headers: this.requestHeaders }
     );
     return response.body;
   }
@@ -3357,29 +3513,34 @@ var _SimilarBuilder = class _SimilarBuilder {
 chunkMWMSFIWN_cjs.__name(_SimilarBuilder, "SimilarBuilder");
 var SimilarBuilder = _SimilarBuilder;
 var _SearchClient = class _SearchClient {
-  constructor(httpClient) {
+  /**
+   * @param defaultLocale - The client's locale (`withLocale()`): every builder here sends it when
+   *   the query names none, as `content()`'s reads do
+   */
+  constructor(httpClient, defaultLocale) {
     this.httpClient = httpClient;
+    this.defaultLocale = defaultLocale;
   }
   /**
    * Start a search query
    * @param query - Search query string
    */
   search(query) {
-    return new SearchBuilder(this.httpClient, query);
+    return new SearchBuilder(this.httpClient, query, this.defaultLocale);
   }
   /**
    * Start an autocomplete query
    * @param query - Partial query to autocomplete
    */
   autocomplete(query) {
-    return new AutocompleteBuilder(this.httpClient, query);
+    return new AutocompleteBuilder(this.httpClient, query, this.defaultLocale);
   }
   /**
    * Find content similar to a given entry
    * @param sourceId - Entry ID to find similar content for
    */
   similar(sourceId) {
-    return new SimilarBuilder(this.httpClient, sourceId);
+    return new SimilarBuilder(this.httpClient, sourceId, this.defaultLocale);
   }
   /**
    * Quick search helper - searches all content types
@@ -3404,6 +3565,7 @@ var _BatchBuilder = class _BatchBuilder {
       returnData: true,
       continueOnError: true
     });
+    chunkMWMSFIWN_cjs.__publicField(this, "requestHeaders");
   }
   // ==========================================================================
   // ENTRY OPERATIONS
@@ -3605,6 +3767,15 @@ var _BatchBuilder = class _BatchBuilder {
     this.defaultOptions.continueOnError = false;
     return this;
   }
+  /**
+   * Headers the batch request adds — e.g. `{ 'X-RelyIO-Dataset': 'staging' }` to write a dataset
+   * other than the client's. They replace the client's own header of the same name for this
+   * request alone, and apply to every operation in it: a batch is one request.
+   */
+  headers(headers) {
+    this.requestHeaders = { ...this.requestHeaders, ...headers };
+    return this;
+  }
   // ==========================================================================
   // EXECUTION
   // ==========================================================================
@@ -3634,6 +3805,7 @@ var _BatchBuilder = class _BatchBuilder {
     const cloned = new _BatchBuilder(this.httpClient);
     cloned.operations = [...this.operations];
     cloned.defaultOptions = { ...this.defaultOptions };
+    cloned.requestHeaders = this.requestHeaders === void 0 ? void 0 : { ...this.requestHeaders };
     return cloned;
   }
   /**
@@ -3651,7 +3823,8 @@ var _BatchBuilder = class _BatchBuilder {
     }
     const finalOptions = { ...this.defaultOptions, ...options };
     return this.httpClient.fetchPayload("/v1/batch", "post", {
-      body: { operations: this.operations, options: finalOptions }
+      body: { operations: this.operations, options: finalOptions },
+      headers: this.requestHeaders
     });
   }
   /**
@@ -3731,9 +3904,21 @@ chunkMWMSFIWN_cjs.__name(_BatchClient, "BatchClient");
 var BatchClient = _BatchClient;
 
 // src/queries/adhoc-query-client.ts
+function withClientLocale(parameters, clientLocale) {
+  if (clientLocale === void 0 || clientLocale === "" || parameters?.locale != null) {
+    return parameters;
+  }
+  return { ...parameters, locale: clientLocale };
+}
+chunkMWMSFIWN_cjs.__name(withClientLocale, "withClientLocale");
 var _AdhocQueryBuilder = class _AdhocQueryBuilder {
-  constructor(httpClient) {
+  /**
+   * @param defaultLocale - The client's locale (`withLocale()`), sent as the `locale` parameter
+   *   when `.param('locale', …)` binds none
+   */
+  constructor(httpClient, defaultLocale) {
     this.httpClient = httpClient;
+    this.defaultLocale = defaultLocale;
     chunkMWMSFIWN_cjs.__publicField(this, "queryDef", {});
     chunkMWMSFIWN_cjs.__publicField(this, "parameters", {});
     chunkMWMSFIWN_cjs.__publicField(this, "options", {});
@@ -3973,8 +4158,9 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
     const body = {
       query: this.queryDef
     };
-    if (Object.keys(this.parameters).length > 0) {
-      body.parameters = this.parameters;
+    const parameters = withClientLocale(this.parameters, this.defaultLocale);
+    if (parameters !== void 0 && Object.keys(parameters).length > 0) {
+      body.parameters = parameters;
     }
     if (Object.keys(this.options).length > 0) {
       body.options = this.options;
@@ -4005,7 +4191,7 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
    * Clone the builder
    */
   clone() {
-    const cloned = new _AdhocQueryBuilder(this.httpClient);
+    const cloned = new _AdhocQueryBuilder(this.httpClient, this.defaultLocale);
     cloned.queryDef = JSON.parse(JSON.stringify(this.queryDef));
     cloned.parameters = { ...this.parameters };
     cloned.options = { ...this.options };
@@ -4015,27 +4201,36 @@ var _AdhocQueryBuilder = class _AdhocQueryBuilder {
 chunkMWMSFIWN_cjs.__name(_AdhocQueryBuilder, "AdhocQueryBuilder");
 var AdhocQueryBuilder = _AdhocQueryBuilder;
 var _AdhocQueryClient = class _AdhocQueryClient {
-  constructor(httpClient) {
+  /**
+   * @param defaultLocale - The client's locale (`withLocale()`), sent as the `locale` parameter of
+   *   every query that binds none
+   */
+  constructor(httpClient, defaultLocale) {
     this.httpClient = httpClient;
+    this.defaultLocale = defaultLocale;
   }
   /**
    * Create a new query builder
    */
   build() {
-    return new AdhocQueryBuilder(this.httpClient);
+    return new AdhocQueryBuilder(this.httpClient, this.defaultLocale);
   }
   /**
    * Execute a query definition directly
    * @param definition - Query definition
    * @param parameters - Parameter values
    * @param options - Execution options
+   * @param request - `headers` this one request adds to the client's own, e.g. `X-RelyIO-Dataset`
+   *   to query another dataset the key can see. A name the client already sends is replaced for
+   *   this request only.
    */
-  async execute(definition, parameters, options) {
+  async execute(definition, parameters, options, request) {
     const body = {
       query: definition
     };
-    if (parameters && Object.keys(parameters).length > 0) {
-      body.parameters = parameters;
+    const sent = withClientLocale(parameters, this.defaultLocale);
+    if (sent !== void 0 && Object.keys(sent).length > 0) {
+      body.parameters = sent;
     }
     if (options && Object.keys(options).length > 0) {
       body.options = options;
@@ -4043,7 +4238,7 @@ var _AdhocQueryClient = class _AdhocQueryClient {
     return this.httpClient.fetchPayload(
       "/v1/query",
       "post",
-      { body }
+      { body, headers: request?.headers }
     );
   }
   /**
@@ -4107,12 +4302,12 @@ async function* pollChanges(http, options = {}) {
   let since = options.since;
   let resynced;
   for (; ; ) {
-    if (aborted(signal)) return;
+    if (isAborted(signal)) return;
     let response;
     try {
       response = await pollOnce(http, since, options);
     } catch (error) {
-      if (aborted(signal)) return;
+      if (isAborted(signal)) return;
       if (!(error instanceof ResourceExpiredError) || since === void 0) throw error;
       const expired = ChangesExpiredError.of(error);
       const onExpired = options.onExpired ?? "throw";
@@ -4130,11 +4325,11 @@ async function* pollChanges(http, options = {}) {
       const expired = resynced;
       resynced = void 0;
       await options.onExpired(expired);
-      if (aborted(signal)) return;
+      if (isAborted(signal)) return;
     }
     for (const change of data) {
       yield change;
-      if (aborted(signal)) return;
+      if (isAborted(signal)) return;
     }
     if (data.length === 0) {
       const wait = parseRetryAfterMs(headerValue(response.headers, "Retry-After"), Date.now());
@@ -4143,6 +4338,21 @@ async function* pollChanges(http, options = {}) {
   }
 }
 chunkMWMSFIWN_cjs.__name(pollChanges, "pollChanges");
+async function readChangesHead(http, options = {}) {
+  const response = await http.send("/v1/changes", "get", {
+    query: {},
+    ...options.signal === void 0 ? {} : { signal: options.signal }
+  });
+  const { data, page } = response.body;
+  if (page.nextCursor === null) {
+    throw new Error("GET /v1/changes answered without page.nextCursor");
+  }
+  if (data.length > 0) {
+    throw new Error("GET /v1/changes without since answered changes; a head carries none");
+  }
+  return page.nextCursor;
+}
+chunkMWMSFIWN_cjs.__name(readChangesHead, "readChangesHead");
 async function pollOnce(http, since, options) {
   const query = {};
   if (since !== void 0) query.since = since;
@@ -4156,28 +4366,12 @@ async function pollOnce(http, since, options) {
   });
 }
 chunkMWMSFIWN_cjs.__name(pollOnce, "pollOnce");
-function sleep(ms, signal) {
-  return new Promise((resolve) => {
-    if (aborted(signal)) {
-      resolve();
-      return;
-    }
-    const done = /* @__PURE__ */ chunkMWMSFIWN_cjs.__name(() => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", done);
-      resolve();
-    }, "done");
-    const timer = setTimeout(done, ms);
-    signal?.addEventListener("abort", done, { once: true });
-  });
-}
-chunkMWMSFIWN_cjs.__name(sleep, "sleep");
-function aborted(signal) {
-  return signal?.aborted === true;
-}
-chunkMWMSFIWN_cjs.__name(aborted, "aborted");
 
 // src/config/dev-detection.ts
+function sandboxStateOf(resolution) {
+  return resolution.state === "active" ? resolution.sandbox : resolution;
+}
+chunkMWMSFIWN_cjs.__name(sandboxStateOf, "sandboxStateOf");
 function getProcess() {
   return typeof process !== "undefined" ? process : void 0;
 }
@@ -4201,11 +4395,14 @@ function resolveFromEnv(proc, now) {
     case "active":
       return {
         state: "active",
-        override: {
-          dataset: verdict.credentials.dataset,
-          apiKey: verdict.credentials.apiKey,
+        sandbox: {
+          state: "active",
+          datasetId: verdict.credentials.dataset,
+          branchId: null,
+          expiresAt: verdict.expiresAt,
           source: "env"
-        }
+        },
+        apiKey: verdict.credentials.apiKey
       };
     case "expired":
       return { state: "expired", expiredAt: verdict.expiredAt };
@@ -4236,11 +4433,14 @@ function resolveFromFile(proc, now) {
         case "active":
           return {
             state: "active",
-            override: {
-              dataset: verdict.context.datasetId,
-              apiKey: verdict.context.previewApiKey,
+            sandbox: {
+              state: "active",
+              datasetId: verdict.context.datasetId,
+              branchId: verdict.context.branchId,
+              expiresAt: verdict.context.expiresAt,
               source: "file"
-            }
+            },
+            apiKey: verdict.context.previewApiKey
           };
         case "expired":
           return { state: "expired", expiredAt: verdict.expiredAt };
@@ -4303,10 +4503,7 @@ var DEFAULT_CONFIG = {
   }
 };
 function validateConfig(config) {
-  if (!config.apiKey || config.apiKey.length === 0) {
-    throw new Error("API key is required");
-  }
-  if (typeof config.apiKey !== "string") {
+  if (config.apiKey != null && typeof config.apiKey !== "string") {
     throw new Error("API key must be a string");
   }
   if (config.baseUrl != null && typeof config.baseUrl !== "string") {
@@ -4321,7 +4518,7 @@ function validateConfig(config) {
 }
 chunkMWMSFIWN_cjs.__name(validateConfig, "validateConfig");
 var devOverrideNotified = false;
-function mergeConfig(userConfig) {
+function resolveConfig(userConfig) {
   validateConfig(userConfig);
   const merged = {
     ...DEFAULT_CONFIG,
@@ -4349,12 +4546,12 @@ function mergeConfig(userConfig) {
   };
   const dev = resolveDevOverride(userConfig.dev);
   if (dev.state === "active") {
-    merged.apiKey = dev.override.apiKey;
-    merged.dataset = dev.override.dataset;
+    merged.apiKey = dev.apiKey;
+    merged.dataset = dev.sandbox.datasetId;
     if (!devOverrideNotified) {
       devOverrideNotified = true;
       console.info(
-        `[RelyIO] Sandbox dev mode active (${dev.override.source}) \u2014 targeting dataset "${dev.override.dataset}" with a scoped preview key.`
+        `[RelyIO] Sandbox dev mode active (${dev.sandbox.source}) \u2014 targeting dataset "${dev.sandbox.datasetId}" with a scoped preview key.`
       );
     }
   } else if (dev.state === "expired" && !devOverrideNotified) {
@@ -4368,9 +4565,9 @@ function mergeConfig(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 merged;
+  return { config: merged, sandbox: sandboxStateOf(dev) };
 }
-chunkMWMSFIWN_cjs.__name(mergeConfig, "mergeConfig");
+chunkMWMSFIWN_cjs.__name(resolveConfig, "resolveConfig");
 
 // src/client/create-client.ts
 var API_VERSION_SEGMENT = "v1";
@@ -4378,17 +4575,20 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   constructor(config) {
     chunkMWMSFIWN_cjs.__publicField(this, "httpClient");
     chunkMWMSFIWN_cjs.__publicField(this, "config");
+    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");
     const { schema, ...clientConfig } = config;
     this._schema = schema;
-    this.config = mergeConfig(clientConfig);
+    const resolved = resolveConfig(clientConfig);
+    this.config = resolved.config;
+    this._sandbox = resolved.sandbox;
     this.httpClient = new HttpClient(this.config);
-    this._search = new SearchClient(this.httpClient);
+    this._search = new SearchClient(this.httpClient, this.config.locale);
     this._batch = new BatchClient(this.httpClient);
-    this._adhocQuery = new AdhocQueryClient(this.httpClient);
+    this._adhocQuery = new AdhocQueryClient(this.httpClient, this.config.locale);
   }
   // ============================================================================
   // CORE CLIENTS
@@ -4399,6 +4599,23 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   get schema() {
     return this._schema;
   }
+  /**
+   * The `relyio dev` sandbox this client resolved at construction, as the preview toolbar displays
+   * it (`sdk-surfaces-spec.md` decision 22).
+   *
+   * Plain, JSON-serializable data and no key, so a server component can hand it to a client
+   * component as a prop — the browser cannot read the handshake itself, so a client created there
+   * reports `absent`. See {@link SandboxState} for what each state means.
+   *
+   * @example
+   * ```tsx
+   * // app/layout.tsx — a server component handing the state to a client component
+   * <SandboxBadge sandbox={relyio.sandbox} />
+   * ```
+   */
+  get sandbox() {
+    return this._sandbox;
+  }
   /**
    * Get the ad-hoc query client
    */
@@ -4459,7 +4676,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   singleton(key) {
-    return new SingletonClient(this.httpClient, key);
+    return new SingletonClient(this.httpClient, key, this.config.locale);
   }
   /**
    * Get a settings client for a specific settings group
@@ -4473,13 +4690,16 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   settings(groupId) {
-    return new SettingsClient(this.httpClient, groupId);
+    return new SettingsClient(this.httpClient, groupId, this.config.locale);
   }
   // ============================================================================
   // SEARCH OPERATIONS
   // ============================================================================
   /**
-   * Start a search query with full-text, semantic, or hybrid search
+   * Start a search query with full-text, semantic, or hybrid search.
+   *
+   * Where a schema types the client, the results are its entries — every content type's until
+   * `in()` or `across()` narrows them (`INV-SS-TYPES-INFERRED`).
    *
    * @example
    * ```typescript
@@ -4577,6 +4797,25 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   changes(options = {}) {
     return pollChanges(this.httpClient, options);
   }
+  /**
+   * The dataset's current position in the changes feed, as a cursor to start
+   * `changes({ since })` or `followChanges(…, { since })` from. One
+   * `GET /v1/changes` without a cursor: answered at once, holding nothing.
+   *
+   * Take it **before** you read what you will follow. A write your read did not
+   * see is then after the position and replayed; opening the feed afterwards
+   * without a `since` starts after it and misses it.
+   *
+   * @example
+   * ```typescript
+   * const since = await relyio.changesHead()
+   * const post = await relyio.content('post').findById(id).execute()
+   * for await (const change of relyio.changes({ since, ids: [id] })) { … }
+   * ```
+   */
+  changesHead(options = {}) {
+    return readChangesHead(this.httpClient, options);
+  }
   // ============================================================================
   // QUERY OPERATIONS
   // ============================================================================
@@ -4614,14 +4853,33 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```
    */
   async executeQuery(queryName, params) {
+    const clientLocale = this.config.locale;
+    const namesLocale = params?.locale != null || params?.locales != null;
     const response = await this.httpClient.request({
       method: "GET",
       url: `/${API_VERSION_SEGMENT}/${String(queryName)}`,
-      params: params ?? {}
+      params: namesLocale || clientLocale === void 0 || clientLocale === "" ? params ?? {} : { ...params, locale: clientLocale }
     });
     const payload = readPayload(response.body);
     return Array.isArray(payload) ? payload : [payload];
   }
+  /**
+   * Describe the project this key resolves to — `GET /v1/project`.
+   *
+   * `dataset` is the one this client's requests select (`dataset`, a sandbox from the `relyio dev`
+   * handshake, or the key's default), which is not always the project's default, so a Studio link
+   * built from `studioUrl` should carry it as `?dataset=`. `studioUrl` is `null` — a value, not an
+   * error — when the service has no Dashboard address configured.
+   *
+   * @example
+   * ```typescript
+   * const { studioUrl, dataset } = await relyio.project()
+   * if (studioUrl !== null) window.open(`${studioUrl}?dataset=${dataset.id}`)
+   * ```
+   */
+  async project() {
+    return this.httpClient.fetchPayload("/v1/project", "get", {});
+  }
   /**
    * Get schema information from the API
    */
@@ -4668,11 +4926,13 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * Update the configuration and reinitialize all clients
    */
   updateConfig(newConfig) {
-    this.config = mergeConfig({ ...this.config, ...newConfig });
+    const resolved = resolveConfig({ ...this.config, ...newConfig });
+    this.config = resolved.config;
+    this._sandbox = resolved.sandbox;
     this.httpClient = new HttpClient(this.config);
-    this._search = new SearchClient(this.httpClient);
+    this._search = new SearchClient(this.httpClient, this.config.locale);
     this._batch = new BatchClient(this.httpClient);
-    this._adhocQuery = new AdhocQueryClient(this.httpClient);
+    this._adhocQuery = new AdhocQueryClient(this.httpClient, this.config.locale);
   }
   /**
    * Get the current configuration
@@ -4698,7 +4958,10 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   // ============================================================================
   /**
    * Create a locale-scoped client
-   * All content operations on the returned client will use the specified locale
+   *
+   * 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.
    *
    * Type-safe when schema is provided: autocompletes valid locale codes!
    *
@@ -4706,9 +4969,10 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```typescript
    * const spanish = relyio.withLocale('es-ES')  // ← Autocompletes with schema!
    *
-   * // All operations use Spanish
+   * // Reads use Spanish
    * const products = await spanish.content('product').query().execute()
    * const homepage = await spanish.singleton('homepage').fetch()
+   * const results = await spanish.search('zapatos').execute()
    *
    * // Original client unchanged
    * const englishProducts = await relyio.content('product').query().execute()
@@ -4816,9 +5080,12 @@ exports.UsageQuotaExceededError = UsageQuotaExceededError;
 exports.ValidationError = ValidationError;
 exports.createClient = createClient;
 exports.entityTagOf = entityTagOf;
+exports.isAborted = isAborted;
 exports.isAssetEntry = isAssetEntry;
 exports.isResourceNotFound = isResourceNotFound;
 exports.matchRoute = matchRoute;
+exports.serviceInstructedDelayMs = serviceInstructedDelayMs;
+exports.sleep = sleep;
 exports.validateFile = validateFile;
-//# sourceMappingURL=chunk-XS32U2UP.cjs.map
-//# sourceMappingURL=chunk-XS32U2UP.cjs.map
+//# sourceMappingURL=chunk-GCMQUM6N.cjs.map
+//# sourceMappingURL=chunk-GCMQUM6N.cjs.map