@relyio/sdk 0.15.0 → 0.17.0

package/dist/{chunk-PXA5ONIU.js → chunk-VS2DEUTN.js}

@@ -1,9 +1,16 @@
 import { parseDevEnv, DEV_CONTEXT_DIR, DEV_CONTEXT_FILENAME, parseDevContextFile } from './chunk-BBUB7C2Z.js';
+import { VISITOR_CLOSE_CODES, HEADER_RETRY_AFTER, HEADER_IDEMPOTENCY_KEY, UNKNOWN_PREVIEW_RECHECK_MS, entityTag, HEADER_IF_MATCH, FRESH_PARAMETER, VISITOR_KEEPALIVE, parseVisitorFrame, VISITOR_FRAMES, VISITOR_POLL_INTERVAL_MS, VISITOR_CLOSE_RETRY, readVisitorPollAnswer, VISITOR_POLL_RETRY, VISITOR_LIVE_PATH, VISITOR_QUERY, previewAtRequest, previewDatasetSlug } from './chunk-OVMIHAYK.js';
 import { isBrowser } from './chunk-H6IBQSMM.js';
 import { __name, __publicField } from './chunk-XQ4QHWZE.js';
 
 /* RelyIO SDK - Built with ❤️ by the RelyIO Team */
 
+// src/config/key-kind.ts
+var PUBLISHABLE_KEY_PREFIX = "rly_pub_";
+var isPublishableKey = /* @__PURE__ */ __name((apiKey) => apiKey?.startsWith(PUBLISHABLE_KEY_PREFIX) === true, "isPublishableKey");
+var PREVIEW_KEY_PREFIX = "rly_prev_";
+var isPreviewKey = /* @__PURE__ */ __name((apiKey) => apiKey?.startsWith(PREVIEW_KEY_PREFIX) === true, "isPreviewKey");
+
 // src/errors/sdk-error.ts
 var _SDKError = class _SDKError extends Error {
   constructor(message, statusCode, cause, context) {
@@ -57,19 +64,84 @@ var _SDKError = class _SDKError extends Error {
     return this.code === errorType;
   }
   /**
-   * Create a new error with additional context
+   * Create a copy of this error with additional context.
+   *
+   * The copy is made from this error's own properties, not by calling a constructor: subclasses
+   * declare constructors of their own (violations, a timeout, a feature, a failed index second),
+   * and no single argument order fits them all. Rebuilding through the base order put the status
+   * code in the subclass's second slot. Copying keeps every field, the subclass's own included, and
+   * the original `timestamp` and `stack`, since it is the same failure.
+   *
+   * `Object.create` runs no constructor, so a `#private` field would not survive the copy; none
+   * exist in this directory. `stack` is not an own property on V8 and is copied by hand below.
    */
   withContext(context) {
-    const Constructor = this.constructor;
-    return new Constructor(this.message, this.statusCode, this.cause, {
-      ...this.context,
-      ...context
+    return Object.create(Object.getPrototypeOf(this), {
+      ...Object.getOwnPropertyDescriptors(this),
+      stack: { value: this.stack, writable: true, enumerable: false, configurable: true },
+      context: {
+        value: { ...this.context, ...context },
+        writable: true,
+        enumerable: true,
+        configurable: true
+      }
     });
   }
 };
 __name(_SDKError, "SDKError");
 var SDKError = _SDKError;
 
+// src/errors/content-errors.ts
+var _ResourceNotFoundError = class _ResourceNotFoundError extends SDKError {
+  constructor(message = "Resource not found", statusCode = 404, cause, context) {
+    super(message, statusCode, cause, context);
+    __publicField(this, "code", "RESOURCE_NOT_FOUND");
+    __publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    const resourceType = this.context?.resourceType;
+    const resourceId = this.context?.resourceId;
+    if (resourceType != null && resourceId != null) {
+      return `${resourceType} with ID "${resourceId}" was not found.`;
+    }
+    return "The requested resource was not found.";
+  }
+};
+__name(_ResourceNotFoundError, "ResourceNotFoundError");
+var ResourceNotFoundError = _ResourceNotFoundError;
+var _ResourceConflictError = class _ResourceConflictError extends SDKError {
+  constructor(message = "Resource conflict", statusCode = 409, cause, context) {
+    super(message, statusCode, cause, context);
+    __publicField(this, "code", "RESOURCE_CONFLICT");
+    __publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    return "The resource could not be created or updated due to a conflict.";
+  }
+};
+__name(_ResourceConflictError, "ResourceConflictError");
+var ResourceConflictError = _ResourceConflictError;
+var _ResourceExpiredError = class _ResourceExpiredError extends SDKError {
+  constructor(message = "Resource has expired", statusCode = 410, cause, context) {
+    super(message, statusCode, cause, context);
+    __publicField(this, "code", "RESOURCE_EXPIRED");
+    __publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    return "The resource is no longer available.";
+  }
+};
+__name(_ResourceExpiredError, "ResourceExpiredError");
+var ResourceExpiredError = _ResourceExpiredError;
+function isResourceNotFound(error) {
+  return error instanceof ResourceNotFoundError;
+}
+__name(isResourceNotFound, "isResourceNotFound");
+function isMissingEntry(error) {
+  return error instanceof ResourceNotFoundError && error.context?.resourceType === "entry";
+}
+__name(isMissingEntry, "isMissingEntry");
+
 // src/errors/contract-errors.ts
 var _MissingApiKeyError = class _MissingApiKeyError extends SDKError {
   constructor(message = "No API key was sent", context) {
@@ -182,7 +254,7 @@ var _TransactionRolledBackError = class _TransactionRolledBackError extends SDKE
     this.failedIndex = failedIndex;
   }
   getUserMessage() {
-    return this.failedIndex === void 0 ? "The batch was rolled back; nothing was written." : `The batch was rolled back at operation ${this.failedIndex}; nothing was written.`;
+    return this.failedIndex === void 0 ? "The batch was rolled back; nothing was written." : `The batch was rolled back; nothing was written. This refusal is for operation ${this.failedIndex} of the batch, which is not necessarily the one that failed.`;
   }
 };
 __name(_TransactionRolledBackError, "TransactionRolledBackError");
@@ -256,57 +328,6 @@ var _InvalidApiKeyError = class _InvalidApiKeyError extends SDKError {
 __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) {
-    super(message, statusCode, cause, context);
-    __publicField(this, "code", "RESOURCE_NOT_FOUND");
-    __publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    const resourceType = this.context?.resourceType;
-    const resourceId = this.context?.resourceId;
-    if (resourceType != null && resourceId != null) {
-      return `${resourceType} with ID "${resourceId}" was not found.`;
-    }
-    return "The requested resource was not found.";
-  }
-};
-__name(_ResourceNotFoundError, "ResourceNotFoundError");
-var ResourceNotFoundError = _ResourceNotFoundError;
-var _ResourceConflictError = class _ResourceConflictError extends SDKError {
-  constructor(message = "Resource conflict", statusCode = 409, cause, context) {
-    super(message, statusCode, cause, context);
-    __publicField(this, "code", "RESOURCE_CONFLICT");
-    __publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "The resource could not be created or updated due to a conflict.";
-  }
-};
-__name(_ResourceConflictError, "ResourceConflictError");
-var ResourceConflictError = _ResourceConflictError;
-var _ResourceExpiredError = class _ResourceExpiredError extends SDKError {
-  constructor(message = "Resource has expired", statusCode = 410, cause, context) {
-    super(message, statusCode, cause, context);
-    __publicField(this, "code", "RESOURCE_EXPIRED");
-    __publicField(this, "retryable", false);
-  }
-  getUserMessage() {
-    return "The resource is no longer available.";
-  }
-};
-__name(_ResourceExpiredError, "ResourceExpiredError");
-var ResourceExpiredError = _ResourceExpiredError;
-function isResourceNotFound(error) {
-  return error instanceof ResourceNotFoundError;
-}
-__name(isResourceNotFound, "isResourceNotFound");
-function isMissingEntry(error) {
-  return error instanceof ResourceNotFoundError && error.context?.resourceType === "entry";
-}
-__name(isMissingEntry, "isMissingEntry");
-
 // src/errors/network-errors.ts
 var _NetworkError = class _NetworkError extends SDKError {
   constructor(message = "Network request failed", statusCode, cause, context) {
@@ -414,229 +435,6 @@ var _InvalidPayloadError = class _InvalidPayloadError extends BaseValidationErro
 __name(_InvalidPayloadError, "InvalidPayloadError");
 var InvalidPayloadError = _InvalidPayloadError;
 
-// ../../platform/api-contract/dist/chunk-46347LG2.js
-function defineRoute(route) {
-  if (route.kind === "raw" && route.standardShape === void 0) {
-    throw new Error("kind 'raw' requires a named StandardShape");
-  }
-  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");
-  }
-  if (route.kind === "stream" && route.stream === void 0) {
-    throw new Error("kind 'stream' requires a StreamDeclaration");
-  }
-  if (route.kind === "collection" && route.page === void 0) {
-    throw new Error("kind 'collection' requires a page dialect");
-  }
-  if (route.queues === true) {
-    if (route.kind !== "object" && route.kind !== "empty") {
-      throw new Error(
-        `kind '${route.kind}' cannot declare \`queues\`: only an object or empty route answers 202 beside its own status`
-      );
-    }
-    if (route.kind === "object" && route.success === 202) {
-      throw new Error("a route whose own status is 202 cannot also declare `queues`");
-    }
-  }
-  if ((route.kind === "object" || route.kind === "collection") && route.negotiated !== void 0) {
-    refuseMismatchedAlternate(route, route.negotiated["text/event-stream"]);
-  }
-  return route;
-}
-__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}"`
-    );
-  }
-  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`
-    );
-  }
-}
-__name(refuseMismatchedAlternate, "refuseMismatchedAlternate");
-
-// ../../platform/api-contract/dist/index.js
-var HEADER_RETRY_AFTER = { name: "Retry-After" };
-var HEADER_IF_MATCH = {
-  name: "If-Match"};
-function entityTag(parts) {
-  return `"${parts.entryUid}:${parts.locale}:${parts.version}:${parts.sharedVersion}"`;
-}
-__name(entityTag, "entityTag");
-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;
-    }
-  }
-}
-__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 };
-}
-__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);
-}
-__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;
-}
-__name(readVisitorChanges, "readVisitorChanges");
-function isCursor(value) {
-  return typeof value === "string" && VISITOR_CURSOR.test(value);
-}
-__name(isCursor, "isCursor");
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-__name(isRecord2, "isRecord2");
-function isNonEmptyString2(value) {
-  return typeof value === "string" && value.length > 0;
-}
-__name(isNonEmptyString2, "isNonEmptyString2");
-function hasOnly(value, keys) {
-  const present = Object.keys(value);
-  return present.length === keys.length && present.every((key) => keys.includes(key));
-}
-__name(hasOnly, "hasOnly");
-
 // ../../platform/api-contract/dist/client/index.js
 var _a;
 var ContractBodyError = (_a = class extends Error {
@@ -774,9 +572,13 @@ var _ErrorMapper = class _ErrorMapper {
       }
       case "RESOURCE_CONFLICT": {
         const expectedVersion = detailNumber(refusal, "expectedVersion");
-        const guidance = expectedVersion === void 0 ? message : `${message.endsWith(".") ? message : `${message}.`} ${STALE_VERSION_GUIDANCE}`;
+        const blockage = blockageOf(refusal);
+        const guidance = blockage !== void 0 || expectedVersion === void 0 ? message : `${message.endsWith(".") ? message : `${message}.`} ${STALE_VERSION_GUIDANCE}`;
         return new ResourceConflictError(guidance, 409, void 0, {
           ...context,
+          // What stands in the way, as a declared kind a program switches on: `draft-exists`,
+          // `release-locked` or `slug-taken` from the Content API (REL-2446).
+          blockage,
           expectedVersion,
           actualVersion: detailNumber(refusal, "actualVersion"),
           // The shared fields' counter, which the `If-Match` tag carries beside the locale's and a
@@ -786,7 +588,10 @@ var _ErrorMapper = class _ErrorMapper {
         });
       }
       case "RESOURCE_EXPIRED": {
-        return new ResourceExpiredError(message, 410, void 0, context);
+        return new ResourceExpiredError(message, 410, void 0, {
+          ...context,
+          reason: detailString(refusal, "reason")
+        });
       }
       case "REQUEST_TIMEOUT": {
         return new TimeoutError(message, void 0, status, void 0, context);
@@ -873,6 +678,15 @@ function detailNumber(refusal, key) {
   return typeof value === "number" ? value : void 0;
 }
 __name(detailNumber, "detailNumber");
+function blockageOf(refusal) {
+  const blockage = detailBag(refusal)?.blockage;
+  if (typeof blockage !== "object" || blockage === null) return void 0;
+  const { kind, facts } = blockage;
+  if (typeof kind !== "string") return void 0;
+  const named = typeof facts === "object" && facts !== null && !Array.isArray(facts) ? facts : {};
+  return { kind, facts: named };
+}
+__name(blockageOf, "blockageOf");
 function violationsOf(refusal) {
   const issues = detailBag(refusal)?.issues;
   if (!Array.isArray(issues)) return [];
@@ -932,6 +746,7 @@ var DECLARED_PATHS = {
   "/v1/{contentType}/{id}/file/multipart/sign-part": true,
   "/v1/{contentType}/{id}/file/presign": true,
   "/v1/{contentType}/{id}/file/url": true,
+  "/v1/{contentType}/{id}/shared-versions/{versionNumber}/restore": true,
   "/v1/{contentType}/{id}/versions": true,
   "/v1/{contentType}/{id}/versions/{versionNumber}": true,
   "/v1/{contentType}/{id}/versions/{versionNumber}/restore": true,
@@ -1016,42 +831,6 @@ function readQuery(searchParams) {
 }
 __name(readQuery, "readQuery");
 
-// src/http/abortable-sleep.ts
-function sleep(ms, signal) {
-  return new Promise((resolve) => {
-    if (isAborted(signal)) {
-      resolve();
-      return;
-    }
-    const done = /* @__PURE__ */ __name(() => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", done);
-      resolve();
-    }, "done");
-    const timer = setTimeout(done, ms);
-    signal?.addEventListener("abort", done, { once: true });
-  });
-}
-__name(sleep, "sleep");
-function isAborted(signal) {
-  return signal?.aborted === true;
-}
-__name(isAborted, "isAborted");
-
-// src/http/request-timeout.ts
-var MAX_TIMER_DELAY_MS = 2147483647;
-function isTimerDelay(value) {
-  return typeof value === "number" && value >= 1 && value <= MAX_TIMER_DELAY_MS;
-}
-__name(isTimerDelay, "isTimerDelay");
-function assertRequestTimeout(timeout) {
-  if (isTimerDelay(timeout)) return;
-  throw new Error(
-    `timeout must be a number of milliseconds from 1 to ${MAX_TIMER_DELAY_MS} \u2014 a timer given 0, NaN, Infinity or more fires at once and ends every request \u2014 and got ${String(timeout)}`
-  );
-}
-__name(assertRequestTimeout, "assertRequestTimeout");
-
 // src/errors/instructed-delay.ts
 function serviceInstructedDelayMs(error, nowMs) {
   if (error instanceof ServiceIndeterminateError) {
@@ -1081,6 +860,17 @@ function isReplaySafe(request) {
   return headerValue(request.headers, HEADER_IDEMPOTENCY_KEY.name) !== void 0;
 }
 __name(isReplaySafe, "isReplaySafe");
+var UNREACHABLE_CODES = /* @__PURE__ */ new Set(["ECONNREFUSED", "ENOTFOUND"]);
+function isUnreachableHost(error, depth = 0) {
+  if (depth > 4 || typeof error !== "object" || error === null) return false;
+  const { code, cause, errors } = error;
+  if (typeof code === "string" && UNREACHABLE_CODES.has(code)) return true;
+  if (Array.isArray(errors) && errors.length > 0) {
+    if (errors.every((one) => isUnreachableHost(one, depth + 1))) return true;
+  }
+  return isUnreachableHost(cause, depth + 1);
+}
+__name(isUnreachableHost, "isUnreachableHost");
 var _DefaultRetryPolicy = class _DefaultRetryPolicy {
   constructor(config) {
     __publicField(this, "config");
@@ -1089,6 +879,7 @@ var _DefaultRetryPolicy = class _DefaultRetryPolicy {
   shouldRetry(attempt, error, request) {
     if (attempt >= this.config.maxAttempts) return false;
     if (!ErrorMapper.isRetryable(error)) return false;
+    if (isUnreachableHost(error)) return false;
     return isReplaySafe(request);
   }
   delayFor(attempt, error) {
@@ -1101,6 +892,86 @@ var _DefaultRetryPolicy = class _DefaultRetryPolicy {
 };
 __name(_DefaultRetryPolicy, "DefaultRetryPolicy");
 var DefaultRetryPolicy = _DefaultRetryPolicy;
+function retryPolicyFor(maxAttempts) {
+  return new DefaultRetryPolicy({
+    maxAttempts,
+    baseDelay: 1e3,
+    maxDelay: 1e4,
+    backoffFactor: 2,
+    jitter: true
+  });
+}
+__name(retryPolicyFor, "retryPolicyFor");
+
+// src/config/preview-read.ts
+var derived = /* @__PURE__ */ new Set();
+var unknown = /* @__PURE__ */ new Map();
+var announced = /* @__PURE__ */ new Set();
+function noteDerivedPreview(dataset) {
+  derived.add(dataset);
+}
+__name(noteDerivedPreview, "noteDerivedPreview");
+function isDerivedPreview(dataset) {
+  return derived.has(dataset);
+}
+__name(isDerivedPreview, "isDerivedPreview");
+function isUnknownPreview(dataset) {
+  const since = unknown.get(dataset);
+  if (since === void 0) return false;
+  if (Date.now() - since < UNKNOWN_PREVIEW_RECHECK_MS) return true;
+  unknown.delete(dataset);
+  return false;
+}
+__name(isUnknownPreview, "isUnknownPreview");
+function rememberUnknownPreview(dataset) {
+  unknown.set(dataset, Date.now());
+  if (announced.has(dataset)) return;
+  announced.add(dataset);
+  console.info(
+    `[RelyIO] No preview dataset "${dataset}" exists for this deployment's branch \u2014 reading the key's default dataset instead, and asking again in a minute.`
+  );
+}
+__name(rememberUnknownPreview, "rememberUnknownPreview");
+function answersUnknownDataset(error, dataset) {
+  return error instanceof ResourceNotFoundError && error.context?.resourceType === "dataset" && error.context.resourceId === dataset;
+}
+__name(answersUnknownDataset, "answersUnknownDataset");
+
+// src/http/abortable-sleep.ts
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (isAborted(signal)) {
+      resolve();
+      return;
+    }
+    const done = /* @__PURE__ */ __name(() => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }, "done");
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+__name(sleep, "sleep");
+function isAborted(signal) {
+  return signal?.aborted === true;
+}
+__name(isAborted, "isAborted");
+
+// src/http/request-timeout.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+function isTimerDelay(value) {
+  return typeof value === "number" && value >= 1 && value <= MAX_TIMER_DELAY_MS;
+}
+__name(isTimerDelay, "isTimerDelay");
+function assertRequestTimeout(timeout) {
+  if (isTimerDelay(timeout)) return;
+  throw new Error(
+    `timeout must be a number of milliseconds from 1 to ${MAX_TIMER_DELAY_MS} \u2014 a timer given 0, NaN, Infinity or more fires at once and ends every request \u2014 and got ${String(timeout)}`
+  );
+}
+__name(assertRequestTimeout, "assertRequestTimeout");
 
 // src/http/http-client.ts
 var _HttpClient = class _HttpClient {
@@ -1116,33 +987,6 @@ var _HttpClient = class _HttpClient {
     this.connection = connectionFor(config);
     this.announce();
   }
-  /**
-   * A view of this client that sends every request through it with `headers` added — beneath the
-   * request's own, over this client's — and changes nothing else: its key, base URL, timeout,
-   * retries and `fetch` are this client's as they are when each request is sent, so a later
-   * `configure()` or `setApiKey()` on this client reaches the view, and one on the view reaches
-   * this client. `client.with({ dataset })` is one (REL-2417).
-   */
-  withHeaders(headers) {
-    const view = new _HttpClient(this.connection.config);
-    view.view = { client: this, headers: { ...headers } };
-    return view;
-  }
-  /**
-   * 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) {
-    if (this.view !== void 0) return this.view.client.configure(config);
-    this.connection = connectionFor(config);
-    this.announce();
-  }
   announce() {
     this.log("debug", "HttpClient initialized", {
       baseUrl: this.connection.baseUrl,
@@ -1151,6 +995,20 @@ var _HttpClient = class _HttpClient {
       environment: isBrowser() ? "browser" : "node"
     });
   }
+  /**
+   * Send bytes to an address that is not a RelyIO route — an asset upload's presigned `PUT` and its
+   * multipart parts — through the client's configured `fetch`, so a wrapper that records, proxies or
+   * forbids network access sees every request this client makes (REL-2671). Nothing else is added: no
+   * key, no retry, no timeout, because the address belongs to the storage service, not to RelyIO.
+   *
+   * Static so the instances a customer holds stay `send` and `fetchPayload` (REL-3107). The `fetch`
+   * is read per call, from the client a view sends through, like the requests are.
+   */
+  static transfer(client, url, init) {
+    const owner = client.view?.client ?? client;
+    const send = owner.connection.config.fetch ?? globalThis.fetch;
+    return send(url, init);
+  }
   /**
    * Call a route the committed document declares, and get back the body that
    * document says it serves.
@@ -1220,6 +1078,11 @@ var _HttpClient = class _HttpClient {
     if (config.method === "DELETE" && mergedConfig.headers) {
       mergedConfig.headers = layerHeaders(mergedConfig.headers, { "Content-Type": null });
     }
+    let preview = derivedPreviewIn(mergedConfig.headers);
+    if (preview !== void 0 && (isUnknownPreview(preview) || !isPreviewKey(headerValue(mergedConfig.headers, API_KEY_HEADER)))) {
+      mergedConfig.headers = layerHeaders(mergedConfig.headers ?? {}, { [DATASET_HEADER]: null });
+      preview = void 0;
+    }
     for (let attempt = 1; ; attempt++) {
       try {
         const response = await this.makeRequest(mergedConfig.url, mergedConfig);
@@ -1248,6 +1111,10 @@ var _HttpClient = class _HttpClient {
           method: mergedConfig.method,
           attempt
         });
+        if (preview !== void 0 && answersUnknownDataset(sdkError, preview)) {
+          rememberUnknownPreview(preview);
+          return this.request(config);
+        }
         this.log("error", "Request failed after all retries", {
           error: sdkError.toJSON(),
           url: mergedConfig.url
@@ -1256,122 +1123,6 @@ var _HttpClient = class _HttpClient {
       }
     }
   }
-  /**
-   * Make a GET request
-   */
-  async get(url, params) {
-    return this.request({
-      method: "GET",
-      url,
-      params
-    });
-  }
-  /**
-   * Make a POST request
-   */
-  async post(url, data, params) {
-    return this.request({
-      method: "POST",
-      url,
-      body: data,
-      params
-    });
-  }
-  /**
-   * Make a PUT request
-   */
-  async put(url, data, params) {
-    return this.request({
-      method: "PUT",
-      url,
-      body: data,
-      params
-    });
-  }
-  /**
-   * Make a DELETE request
-   */
-  async delete(url, params) {
-    return this.request({
-      method: "DELETE",
-      url,
-      params
-    });
-  }
-  /**
-   * Make a PATCH request
-   */
-  async patch(url, data, params) {
-    return this.request({
-      method: "PATCH",
-      url,
-      body: data,
-      params
-    });
-  }
-  /**
-   * 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) {
-    if (this.view !== void 0) return this.view.client.setDefaultHeaders(headers);
-    this.connection = {
-      ...this.connection,
-      defaultHeaders: layerHeaders(this.connection.defaultHeaders, headers)
-    };
-  }
-  /**
-   * 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).
-   */
-  setApiKey(apiKey) {
-    if (this.view !== void 0) return this.view.client.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() {
-    if (this.view !== void 0) {
-      return layerHeaders(this.view.client.getDefaultHeaders(), this.view.headers);
-    }
-    return { ...this.connection.defaultHeaders };
-  }
-  /**
-   * Update base URL
-   */
-  setBaseUrl(baseUrl) {
-    if (this.view !== void 0) return this.view.client.setBaseUrl(baseUrl);
-    this.connection = { ...this.connection, baseUrl };
-  }
-  /**
-   * Get current base URL
-   */
-  getBaseUrl() {
-    if (this.view !== void 0) return this.view.client.getBaseUrl();
-    return this.connection.baseUrl;
-  }
   /**
    * One attempt.
    *
@@ -1517,10 +1268,11 @@ var _HttpClient = class _HttpClient {
     if (contentType.includes("text/")) {
       return await response.text();
     }
+    const text = await response.text();
     try {
-      return await response.json();
+      return JSON.parse(text);
     } catch {
-      return await response.text();
+      return text;
     }
   }
   resolveUrl(url) {
@@ -1575,8 +1327,73 @@ var _HttpClient = class _HttpClient {
 };
 __name(_HttpClient, "HttpClient");
 var HttpClient = _HttpClient;
+var _ControlledHttpClient = class _ControlledHttpClient extends HttpClient {
+  /**
+   * A view of this client that sends every request through it with `headers` added — beneath the
+   * request's own, over this client's — and changes nothing else: its key, base URL, timeout,
+   * retries and `fetch` are this client's as they are when each request is sent, so a later
+   * `configure()` or `setApiKey()` on this client reaches the view, and one on the view reaches
+   * this client. `client.with({ dataset })` is one (REL-2417).
+   */
+  withHeaders(headers) {
+    const view = new _ControlledHttpClient(this.connection.config);
+    view.view = { client: this, headers: { ...headers } };
+    return view;
+  }
+  /**
+   * 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 — `setApiKey()` — is replaced by what `config`
+   * says.
+   */
+  configure(config) {
+    if (this.view !== void 0) return this.view.client.configure(config);
+    this.connection = connectionFor(config);
+    this.announce();
+  }
+  /**
+   * 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).
+   */
+  setApiKey(apiKey) {
+    if (this.view !== void 0) return this.view.client.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
+      })
+    };
+  }
+};
+__name(_ControlledHttpClient, "ControlledHttpClient");
+var ControlledHttpClient = _ControlledHttpClient;
 var API_KEY_HEADER = "X-API-Key";
 var DATASET_HEADER = "X-RelyIO-Dataset";
+function derivedPreviewIn(headers) {
+  const dataset = headerValue(headers, DATASET_HEADER);
+  return dataset !== void 0 && isDerivedPreview(dataset) ? dataset : void 0;
+}
+__name(derivedPreviewIn, "derivedPreviewIn");
 var BROWSER_CONTROLLED_HEADERS = /* @__PURE__ */ new Set([
   "user-agent",
   "referer",
@@ -1605,13 +1422,7 @@ function connectionFor(config) {
     // 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
-    })
+    retryPolicy: retryPolicyFor(config.retryAttempts)
   };
 }
 __name(connectionFor, "connectionFor");
@@ -1771,6 +1582,10 @@ function writeLocale(query, locale) {
   query.locales = locale.join(",");
 }
 __name(writeLocale, "writeLocale");
+function signalOf(options) {
+  return options.signal === void 0 ? {} : { signal: options.signal };
+}
+__name(signalOf, "signalOf");
 function readHeaders(options) {
   const headers = {};
   if (options.dataset !== void 0) headers[DATASET_HEADER] = options.dataset;
@@ -1824,7 +1639,8 @@ var _EntryHandle = class _EntryHandle {
       {
         path: { contentType: this.typeName },
         query: listQuery(options, this.clientLocale()),
-        headers: readHeaders(options)
+        headers: readHeaders(options),
+        ...signalOf(options)
       }
     );
     return response.body;
@@ -1879,7 +1695,8 @@ var _EntryHandle = class _EntryHandle {
       return await this.httpClient.fetchPayload("/v1/{contentType}/{id}", "get", {
         path: { contentType: this.typeName, id: idOrSlug },
         query: entryQuery(options, this.clientLocale()),
-        headers: readHeaders(options)
+        headers: readHeaders(options),
+        ...signalOf(options)
       });
     } catch (error) {
       if (isMissingEntry(error)) return null;
@@ -1917,7 +1734,10 @@ var EntryHandle = _EntryHandle;
 // src/content/content-client.ts
 var _ContentClient = class _ContentClient extends EntryHandle {
   /**
-   * Create a new content entry.
+   * Create a new content entry, published. The answer's `_metadata.warnings` lists each reference
+   * the content type declares `weak` that the create made live while the entry it points at is
+   * unpublished (`REFERENCE_NOT_PUBLISHED`) — `[]` when there are none; the create is never refused
+   * for them.
    *
    * `locale` defaults to the client's own, and `dataset` to the client's (`client.with({ dataset })`
    * sets it for every call).
@@ -1946,7 +1766,7 @@ var _ContentClient = class _ContentClient extends EntryHandle {
    * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
    * client's own, 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.
+   * locale it belongs to, and holds that locale's fields under `fields`.
    */
   async versions(id, options) {
     const locale = callLocale(options?.locale, this.clientLocale());
@@ -1967,6 +1787,9 @@ var _ContentClient = class _ContentClient extends EntryHandle {
    * There is no `null`: a version the locale does not have, an entry that is not there, a type the
    * schema does not declare and a dataset with no schema all throw `ResourceNotFoundError`, its
    * `context.resourceType` naming which (REL-2409 Q12).
+   *
+   * It answers the version, not the entry: that locale's own fields as the version stored them, and
+   * `_metadata` with `status: 'version'` ({@link ContentVersion}).
    */
   async version(id, options) {
     const locale = callLocale(options.locale, this.clientLocale());
@@ -2022,7 +1845,8 @@ var _ContentClient = class _ContentClient extends EntryHandle {
     const response = await this.httpClient.send("/v1/{contentType}/{id}/children", "get", {
       path: { contentType: this.typeName, id },
       query: childrenQuery(options, this.clientLocale()),
-      headers: readHeaders(options)
+      headers: readHeaders(options),
+      ...signalOf(options)
     });
     return response.body;
   }
@@ -2556,7 +2380,7 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     }
     const total = this.file.size;
     this.emitProgress(0, total);
-    const uploadResponse = await fetch(presigned.uploadUrl, {
+    const uploadResponse = await HttpClient.transfer(this.httpClient, presigned.uploadUrl, {
       method: presigned.method,
       headers: presigned.headers,
       body: this.file
@@ -2623,7 +2447,10 @@ var _AssetUploadBuilder = class _AssetUploadBuilder {
     for (let attempt = 0; attempt <= this._maxPartRetries; attempt += 1) {
       try {
         const { url } = await fileBuilder.signPart({ ...target, partNumber });
-        const response = await fetch(url, { method: "PUT", body: blob });
+        const response = await HttpClient.transfer(this.httpClient, url, {
+          method: "PUT",
+          body: blob
+        });
         if (!response.ok) {
           const retriable = response.status >= 500 || response.status === 408 || response.status === 429;
           if (!retriable) {
@@ -2808,14 +2635,18 @@ var _SingletonClient = class _SingletonClient extends DocumentHandle {
       return await this.httpClient.fetchPayload("/v1/singletons/{key}", "get", {
         path: { key: this.name },
         query: documentQuery(options, this.clientLocale()),
-        headers: readHeaders(options)
+        headers: readHeaders(options),
+        ...signalOf(options)
       });
     } catch (error) {
       if (isMissingEntry(error)) return null;
       throw error;
     }
   }
-  /** The API publishes on PATCH: there is no separate publish route. */
+  /**
+   * The API publishes on PATCH: there is no separate publish route. The answer's `_metadata` also
+   * lists the links the write left pointing nowhere and its `warnings` (REL-3097).
+   */
   patch(write, options) {
     return this.httpClient.fetchPayload(
       "/v1/singletons/{key}",
@@ -2831,14 +2662,10 @@ var _SingletonClient = class _SingletonClient extends DocumentHandle {
     return this.httpClient.fetchPayload("/v1/singletons/{key}/versions", "get", { path: { key: this.name }, query });
   }
   readVersion(versionNumber, query) {
-    return this.httpClient.fetchPayload(
-      "/v1/singletons/{key}/versions/{versionNumber}",
-      "get",
-      {
-        path: { key: this.name, versionNumber },
-        query
-      }
-    );
+    return this.httpClient.fetchPayload("/v1/singletons/{key}/versions/{versionNumber}", "get", {
+      path: { key: this.name, versionNumber },
+      query
+    });
   }
 };
 __name(_SingletonClient, "SingletonClient");
@@ -2871,22 +2698,19 @@ var _SettingsClient = class _SettingsClient extends DocumentHandle {
       {
         path: { groupId: this.name },
         query: documentQuery(options, this.clientLocale()),
-        headers: readHeaders(options)
+        headers: readHeaders(options),
+        ...signalOf(options)
       }
     );
   }
   async reset(...args) {
     const [first, second] = args;
     const write = first !== void 0 && isRead(first) ? { ...versionCheckOf(first), options: second } : { locale: this.localeOf(first?.locale), ifMatch: void 0, options: first };
-    return this.httpClient.fetchPayload(
-      "/v1/settings/{groupId}/reset",
-      "post",
-      {
-        path: { groupId: this.name },
-        query: write.locale === void 0 ? void 0 : { locale: write.locale },
-        headers: DocumentHandle.headersOf(write, write.options)
-      }
-    );
+    return this.httpClient.fetchPayload("/v1/settings/{groupId}/reset", "post", {
+      path: { groupId: this.name },
+      query: write.locale === void 0 ? void 0 : { locale: write.locale },
+      headers: DocumentHandle.headersOf(write, write.options)
+    });
   }
   /** The group's default values, as the schema declares them. */
   async getDefaults() {
@@ -2922,7 +2746,7 @@ var SettingsClient = _SettingsClient;
 
 // src/changes/changes.ts
 var CHANGES_POLL_TIMEOUT_MS = 25e3 + 5e3;
-var EXPIRED_REASONS = {
+var EXPIRED_REASONS2 = {
   retention: "retention",
   "dataset-replaced": "dataset-replaced",
   "ahead-of-head": "ahead-of-head",
@@ -2942,7 +2766,7 @@ var _ChangesExpiredError = class _ChangesExpiredError extends ResourceExpiredErr
      */
     __publicField(this, "fresh");
     this.name = "ChangesExpiredError";
-    this.reason = expiredReasonOf(message);
+    this.reason = expiredReasonOf(context?.reason);
     this.fresh = fresh;
   }
   /** The base class rebuilds from its four arguments, which would drop the position resynced to. */
@@ -2972,16 +2796,16 @@ var _ChangesExpiredError = class _ChangesExpiredError extends ResourceExpiredErr
       `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" },
+      { transport: "live-edge", reason },
       cursor
     );
   }
 };
 __name(_ChangesExpiredError, "ChangesExpiredError");
 var ChangesExpiredError = _ChangesExpiredError;
-function expiredReasonOf(message) {
-  for (const reason of Object.values(EXPIRED_REASONS)) {
-    if (message.includes(`(${reason})`)) return reason;
+function expiredReasonOf(named) {
+  for (const reason of Object.values(EXPIRED_REASONS2)) {
+    if (named === reason) return reason;
   }
   return "unknown";
 }
@@ -3061,10 +2885,6 @@ async function pollOnce(http, since, options) {
 }
 __name(pollOnce, "pollOnce");
 
-// src/config/key-kind.ts
-var PUBLISHABLE_KEY_PREFIX = "rly_pub_";
-var isPublishableKey = /* @__PURE__ */ __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 = {}) {
@@ -3080,19 +2900,6 @@ var _LiveEdgeError = class _LiveEdgeError extends SDKError {
     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;
   }
@@ -3112,8 +2919,8 @@ var HTTP_SCHEME_OF = {
 };
 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];
+  const derived2 = originOf(config.baseUrl);
+  const edge = derived2 === void 0 ? void 0 : LIVE_EDGE_OF_API[derived2];
   if (edge !== void 0) return { ok: true, url: new URL(edge) };
   return {
     ok: false,
@@ -3363,19 +3170,18 @@ var CLOSE_MEANING = {
   [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",
-  // Also how the edge hands a connection on when the project's live objects move to another
-  // placement (reason `moved`, REL-1514): either way the same request succeeds again shortly.
-  [VISITOR_CLOSE_CODES.unavailable]: "the edge could not serve this connection just now \u2014 it could not reach what it needed, or it moved the project\u2019s live connections elsewhere",
+  [VISITOR_CLOSE_CODES.unavailable]: "the edge could not serve this connection just now \u2014 it could not reach what it needed",
   [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;
+  let starting = reach.position === void 0;
   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";
+    if (answer === void 0 || isAborted(signal)) return "aborted";
     options.opened?.();
     if (answer.kind === "resync") {
       await expire(answer.reason, answer.cursor, options);
@@ -3392,8 +3198,9 @@ async function* followPolls(client, request, reach, options) {
         if (isAborted(signal)) return "aborted";
       }
       reach.position = answer.cursor;
-      if (answer.changes.length === 0) options.reached?.(answer.cursor);
+      if (starting) options.reached?.(answer.cursor);
     }
+    starting = false;
     await sleep(VISITOR_POLL_INTERVAL_MS, signal);
   }
   return isAborted(signal) ? "aborted" : "socket";
@@ -3585,6 +3392,7 @@ __name(given, "given");
 function transportOf(options) {
   const headers = readHeaders(options);
   return {
+    ...signalOf(options),
     ...headers === void 0 ? {} : { headers },
     ...typeof options.fresh === "string" ? { query: { [FRESH_PARAMETER]: options.fresh } } : {}
   };
@@ -3662,7 +3470,7 @@ __name(runSimilar, "runSimilar");
 // src/batch/batch-operations.ts
 var VERBS = ["create", "update", "replace", "delete", "singleton"];
 async function runBatch(http, operations, options, clientLocale) {
-  const { atomic, dryRun, stopOnError, returnData, dataset } = options;
+  const { atomic, dryRun, stopOnError, returnData, dataset, signal } = options;
   const runOptions = {
     ...atomic === void 0 ? {} : { atomic },
     ...dryRun === void 0 ? {} : { dryRun },
@@ -3675,7 +3483,8 @@ async function runBatch(http, operations, options, clientLocale) {
       operations: operations.map((operation, index) => operationOf(operation, index, clientLocale)),
       ...Object.keys(runOptions).length === 0 ? {} : { options: runOptions }
     },
-    ...headers === void 0 ? {} : { headers }
+    ...headers === void 0 ? {} : { headers },
+    ...signalOf({ signal })
   });
   return response.body;
 }
@@ -3755,7 +3564,7 @@ async function runAdhocQuery(http, query, clientLocale) {
   const order = sort === void 0 ? [] : Object.entries(sort).flatMap(
     ([field, direction]) => direction === void 0 ? [] : [{ [field]: direction }]
   );
-  const fetch2 = {
+  const fetch = {
     contentType: query.from,
     ...where === void 0 || Object.keys(where).length === 0 ? {} : { where },
     ...include === void 0 || include.length === 0 ? {} : { include: [...include] },
@@ -3763,14 +3572,14 @@ async function runAdhocQuery(http, query, clientLocale) {
     ...limit === void 0 ? {} : { limit },
     ...page === void 0 ? {} : { offset: offsetOf(page, limit) }
   };
-  const locale = query.locale ?? clientLocale;
-  const parameters = {
-    ...query.params,
-    ...locale === void 0 || locale === "" ? {} : { locale }
-  };
+  const terms = {};
+  if (query.cursor !== void 0) terms.cursor = query.cursor;
+  writeLocale(terms, query.locale ?? clientLocale);
+  if (typeof query.fresh === "string") terms[FRESH_PARAMETER] = query.fresh;
+  const parameters = { ...query.params };
   const body = {
     query: {
-      fetch: fetch2,
+      fetch,
       ...aggregate === void 0 ? {} : { aggregate },
       ...select === void 0 || select.length === 0 ? {} : { select: Object.fromEntries(select.map((field) => [field, field])) },
       ...fullText === void 0 ? {} : { fullText }
@@ -3780,8 +3589,9 @@ async function runAdhocQuery(http, query, clientLocale) {
   const headers = readHeaders(query);
   const response = await http.send("/v1/query", "post", {
     body,
+    ...Object.keys(terms).length === 0 ? {} : { query: terms },
     ...headers === void 0 ? {} : { headers },
-    ...typeof query.fresh === "string" ? { query: { [FRESH_PARAMETER]: query.fresh } } : {}
+    ...signalOf(query)
   });
   return response.body;
 }
@@ -3798,6 +3608,9 @@ function offsetOf(page, limit) {
 __name(offsetOf, "offsetOf");
 async function runNamedQuery(http, name, options, clientLocale) {
   const locale = options.locale ?? clientLocale;
+  const terms = {};
+  if (locale !== void 0 && locale !== "") terms.locale = locale;
+  if (typeof options.fresh === "string") terms[FRESH_PARAMETER] = options.fresh;
   const headers = readHeaders(options);
   const response = await http.send(
     "/v1/queries/{name}",
@@ -3805,8 +3618,9 @@ async function runNamedQuery(http, name, options, clientLocale) {
     {
       path: { name },
       body: options.params === void 0 ? {} : { params: options.params },
-      ...locale === void 0 || locale === "" ? {} : { query: { locale } },
-      ...headers === void 0 ? {} : { headers }
+      ...Object.keys(terms).length === 0 ? {} : { query: terms },
+      ...headers === void 0 ? {} : { headers },
+      ...signalOf(options)
     }
   );
   return response.body;
@@ -3914,6 +3728,17 @@ function resolveDevOverride(dev) {
 }
 __name(resolveDevOverride, "resolveDevOverride");
 
+// src/config/preview-environment.ts
+function readPreviewAtRequest() {
+  const env = typeof process === "undefined" ? void 0 : process.env;
+  return previewAtRequest(isEnvironment(env) ? env : {});
+}
+__name(readPreviewAtRequest, "readPreviewAtRequest");
+function isEnvironment(value) {
+  return typeof value === "object" && value !== null;
+}
+__name(isEnvironment, "isEnvironment");
+
 // src/config/types.ts
 var DEFAULT_CONFIG = {
   baseUrl: "https://api.relyio.com",
@@ -3935,12 +3760,6 @@ var DEFAULT_CONFIG = {
     // 50MB
     strategies: ["memory", "stale-while-revalidate"]
   },
-  realtime: {
-    enabled: true,
-    maxReconnectAttempts: 10,
-    reconnectDelay: 1e3,
-    heartbeatInterval: 3e4
-  },
   debug: {
     enabled: false,
     logRequests: false,
@@ -3992,7 +3811,7 @@ __name(withoutKeyHeader, "withoutKeyHeader");
 function withHandshake(configured) {
   const dev = resolveDevOverride(configured.dev);
   const merged = withDefaults(
-    configured,
+    withPreview(configured),
     dev.state === "active" ? { apiKey: dev.apiKey, dataset: dev.sandbox.datasetId } : {},
     DEFAULT_CONFIG
   );
@@ -4017,6 +3836,22 @@ function withHandshake(configured) {
   return { config: merged, sandbox: sandboxStateOf(dev), configured };
 }
 __name(withHandshake, "withHandshake");
+var previewNotified = false;
+function withPreview(configured) {
+  if (configured.dataset !== void 0 || !isPreviewKey(configured.apiKey)) return configured;
+  const preview = readPreviewAtRequest();
+  if (preview.state !== "preview") return configured;
+  const dataset = previewDatasetSlug(preview.branch);
+  noteDerivedPreview(dataset);
+  if (!previewNotified) {
+    previewNotified = true;
+    console.info(
+      `[RelyIO] ${preview.host} preview deployment of "${preview.branch}" \u2014 reading its preview dataset "${dataset}".`
+    );
+  }
+  return { ...configured, dataset };
+}
+__name(withPreview, "withPreview");
 function withDefaults(base, given2, defaults) {
   const merged = new Map(Object.entries(base));
   const givenValues = new Map(Object.entries(given2 ?? {}));
@@ -4083,7 +3918,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
     this.config = resolved.config;
     this.configured = resolved.configured;
     this._sandbox = resolved.sandbox;
-    this.httpClient = new HttpClient(this.config);
+    this.httpClient = new ControlledHttpClient(this.config);
   }
   // ============================================================================
   // CORE CLIENTS
@@ -4108,14 +3943,16 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   /**
    * Run a query in one call (REL-2421, REL-2409 Q22):
    *
-   * - `query({ from, … })` runs one inline, with `list`'s option names — `where` (the query
-   *   route's dialect), `include`, `select`, `sort`, `limit`, `page`, `locale`, `dataset`, `fresh` —
-   *   plus `aggregate`, `params` and `fullText`;
+   * - `query({ from, … })` runs one inline, with `list`'s options — `where`, `include`, `select`
+   *   (beside `include`), `sort`, `limit`, `cursor`, `page`, `locale` (a code, a list or `'*'`),
+   *   `dataset`, `fresh` — plus `aggregate`, `params` and `fullText`. It answers a list's envelope,
+   *   `{ data, page, meta }` (REL-2460);
    * - `query(name, { params, … })` runs the saved query the schema declares under `name`, its
-   *   `params` typed from that declaration.
+   *   `params` typed from that declaration. It answers the API's body,
+   *   `{ data: { result, metadata } }`.
    *
-   * Both answer the API's body, `{ data: { result, metadata } }`. See {@link QueryCall}. Every query
-   * is sent in the client's locale as it is then, unless it names its own.
+   * See {@link QueryCall}. Every query is sent in the client's locale as it is then, unless it names
+   * its own.
    */
   get query() {
     const call = /* @__PURE__ */ __name((target, options = {}) => typeof target === "string" ? runNamedQuery(this.httpClient, target, options, this.currentLocale()) : runAdhocQuery(this.httpClient, target, this.currentLocale()), "call");
@@ -4300,7 +4137,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * edge's URL. On a server, follow `changes()` with it instead.
    */
   liveChanges(options = {}) {
-    const { apiKey, dataset, baseUrl, liveUrl, fetch: fetch2, webSocket, timeout } = this.getConfig();
+    const { apiKey, dataset, baseUrl, liveUrl, fetch, webSocket, timeout } = this.getConfig();
     this._liveClientId ?? (this._liveClientId = randomClientId());
     return subscribeLiveEdge(
       {
@@ -4308,7 +4145,7 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
         dataset,
         baseUrl,
         liveUrl,
-        fetch: fetch2,
+        fetch,
         webSocket,
         timeout,
         clientId: this._liveClientId
@@ -4417,9 +4254,9 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * - 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
+   *   `fetch`, `browser.onCorsError`, `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
+   * - a bag of options you name — `browser`, `cache`, `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
@@ -4595,6 +4432,6 @@ function randomClientId() {
 }
 __name(randomClientId, "randomClientId");
 
-export { AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthorizationError, BaseValidationError, ChangesExpiredError, ConnectionError, ContentClient, ErrorMapper, FileUploadError, FileValidationError, HttpClient, InvalidApiKeyError, InvalidPayloadError, LIVE_KEEPALIVE_INTERVAL_MS, LIVE_SOCKET_OPEN_TIMEOUT_MS, LiveEdgeError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PUBLISHABLE_KEY_PREFIX, PayloadTooLargeError, PlanFeatureUnavailableError, RateLimitError, ReadOnlyKeyError, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, ServerError, ServiceIndeterminateError, SettingsClient, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, VISITOR_ADMISSION_RETRY_AFTER_SECONDS, ValidationError, createClient, isAborted, isAssetEntry, isMissingEntry, isPublishableKey, isResourceNotFound, matchRoute, serviceInstructedDelayMs, sleep, validateFile, versionCheckOf };
-//# sourceMappingURL=chunk-PXA5ONIU.js.map
-//# sourceMappingURL=chunk-PXA5ONIU.js.map
+export { AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthorizationError, BaseValidationError, ChangesExpiredError, ConnectionError, ContentClient, DefaultRetryPolicy, ErrorMapper, FileUploadError, FileValidationError, HttpClient, InvalidApiKeyError, InvalidPayloadError, LIVE_KEEPALIVE_INTERVAL_MS, LIVE_SOCKET_OPEN_TIMEOUT_MS, LiveEdgeError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PREVIEW_KEY_PREFIX, PUBLISHABLE_KEY_PREFIX, PayloadTooLargeError, PlanFeatureUnavailableError, RateLimitError, ReadOnlyKeyError, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, ServerError, ServiceIndeterminateError, SettingsClient, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, ValidationError, createClient, isAborted, isAssetEntry, isMissingEntry, isPreviewKey, isPublishableKey, isReplaySafe, isResourceNotFound, matchRoute, retryPolicyFor, serviceInstructedDelayMs, sleep, validateFile, versionCheckOf };
+//# sourceMappingURL=chunk-VS2DEUTN.js.map
+//# sourceMappingURL=chunk-VS2DEUTN.js.map