@relyio/sdk 0.7.0 → 0.8.0

package/dist/{chunk-GYHAVYND.js → chunk-QFHVF3YF.js}

@@ -410,6 +410,45 @@ var _InvalidPayloadError = class _InvalidPayloadError extends BaseValidationErro
 __name(_InvalidPayloadError, "InvalidPayloadError");
 var InvalidPayloadError = _InvalidPayloadError;
 
+// ../../platform/api-contract/dist/chunk-PYZCLRXR.js
+function defineRoute(route) {
+  if (route.kind === "raw" && route.standardShape === void 0) {
+    throw new Error("kind 'raw' requires a named StandardShape");
+  }
+  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.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_ENTITY_TAG = { name: "X-Entity-Tag" };
@@ -417,6 +456,169 @@ var HEADER_IF_MATCH = {
   name: "If-Match"};
 var HEADER_IDEMPOTENCY_KEY = {
   name: "Idempotency-Key"};
+var FRESH_PARAMETER = "_fresh";
+var VISITOR_LIVE_PATH = "/visitor/changes";
+var VISITOR_QUERY = {
+  /** The publishable key. */
+  key: "key",
+  /** A dataset id or name the key reaches; absent, the key's default dataset. */
+  dataset: "dataset",
+  /** The cursor to continue from; absent, the socket starts now. */
+  since: "since",
+  /** Comma-separated content types to keep; absent keeps every type. */
+  types: "types",
+  /** Comma-separated entry ids to keep; absent keeps every entry. */
+  ids: "ids",
+  /** The poll's client id. Required on a poll, and not read on a socket. */
+  client: "client"
+};
+var VISITOR_CURSOR = /^[\w.~-]{1,256}$/;
+var VISITOR_POLL_INTERVAL_MS = 15e3;
+var VISITOR_KEEPALIVE = { request: "ping", response: "pong" };
+var VISITOR_FRAMES = {
+  opened: "feed.opened",
+  changes: "feed.changes",
+  resync: "feed.resync"
+};
+defineRoute({
+  kind: "object",
+  headers: [HEADER_RETRY_AFTER],
+  codes: [
+    "REQUEST_INVALID",
+    "MISSING_API_KEY",
+    "INVALID_API_KEY",
+    "ACCESS_DENIED",
+    "METHOD_NOT_ALLOWED",
+    "SERVICE_INDETERMINATE",
+    "USAGE_QUOTA_EXCEEDED",
+    "RATE_LIMIT_EXCEEDED"
+  ]
+});
+var VISITOR_CLOSE_CODES = {
+  /** A query the door cannot read: a malformed `since`, filter, `dataset` or `client`. */
+  requestInvalid: 4400,
+  /** No publishable key, or one that is unknown, revoked, expired, a secret key or a preview key. */
+  keyRefused: 4401,
+  /** The page's `Origin` is absent, or not on the key's allowed origins. */
+  originRefused: 4403,
+  /** `dataset` names nothing the key reaches. */
+  datasetRefused: 4404,
+  /** The key's scope, the project's counter or the feed could not be reached just now. */
+  unavailable: 1013,
+  /**
+   * The project holds as many visitor connections as its plan allows — Starter's 100 — or its
+   * Organization is suspended. As HTTP's 402: more needs a bigger plan, or visitors leaving.
+   */
+  allowanceReached: 4402,
+  /** This client's address holds as many connections to the project as one address may. */
+  addressLimitReached: 4429,
+  /** The project is at its per-project safety ceiling — Pro's 50,000 — whatever it would pay for. */
+  ceilingReached: 4503
+};
+var VISITOR_CLOSE_RETRY = {
+  4400: "stop",
+  4401: "stop",
+  4403: "stop",
+  4404: "stop",
+  1013: "retry",
+  4402: "back-off",
+  4429: "back-off",
+  4503: "back-off"
+};
+var VISITOR_POLL_RETRY = {
+  REQUEST_INVALID: "stop",
+  MISSING_API_KEY: "stop",
+  INVALID_API_KEY: "stop",
+  ACCESS_DENIED: "stop",
+  METHOD_NOT_ALLOWED: "stop",
+  SERVICE_INDETERMINATE: "retry",
+  USAGE_QUOTA_EXCEEDED: "back-off",
+  RATE_LIMIT_EXCEEDED: "back-off"
+};
+var VISITOR_ADMISSION_RETRY_AFTER_SECONDS = 60;
+function parseVisitorFrame(text) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord2(value) || !isCursor(value.cursor)) return null;
+  switch (value.type) {
+    case VISITOR_FRAMES.opened: {
+      return hasOnly(value, ["type", "cursor"]) ? { type: VISITOR_FRAMES.opened, cursor: value.cursor } : null;
+    }
+    case VISITOR_FRAMES.changes: {
+      const changes = hasOnly(value, ["type", "changes", "cursor"]) ? readVisitorChanges(value.changes) : null;
+      return changes === null ? null : { type: VISITOR_FRAMES.changes, changes, cursor: value.cursor };
+    }
+    case VISITOR_FRAMES.resync: {
+      return hasOnly(value, ["type", "reason", "cursor"]) && isResyncReason(value.reason) ? { type: VISITOR_FRAMES.resync, reason: value.reason, cursor: value.cursor } : null;
+    }
+    default: {
+      return null;
+    }
+  }
+}
+__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;
@@ -685,6 +887,8 @@ var DECLARED_PATHS = {
   "/health/cache": true,
   "/health/live": true,
   "/health/ready": true,
+  "/internal/live/visitor-feed/{projectId}/{datasetId}/changes": true,
+  "/internal/live/visitor-key": true,
   "/internal/media/claim": true,
   "/internal/media/file-complete": true,
   "/internal/media/progress": true,
@@ -1423,8 +1627,20 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     __publicField(this, "requestHeaders");
     /** The client's locale, asked when the query is sent rather than copied when it was built. */
     __publicField(this, "clientLocale");
+    __publicField(this, "freshValue");
     this.clientLocale = readClientLocale(locale);
   }
+  /**
+   * The feed position this read follows — a change's `fresh` (`FeedChange`), or a resync's. Sent as
+   * `?_fresh`, the one term the API declares for it: no cache — the Content API's edge or the
+   * browser's own — holds an answer for that position from before it, so the read is answered after
+   * the change, and every read naming the same position shares that answer. The answer is the
+   * read's own; omit it for a read no change prompted.
+   */
+  fresh(position) {
+    this.freshValue = position;
+    return this;
+  }
   /**
    * Headers this query adds to the client's own, e.g. `X-RelyIO-Dataset` to list another dataset
    * the key can see. A name the client already sends is replaced for this query only; the client
@@ -1709,6 +1925,7 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
     cloned.pageNumber = this.pageNumber;
     cloned.pageSizeValue = this.pageSizeValue;
     cloned.requestHeaders = this.requestHeaders ? { ...this.requestHeaders } : void 0;
+    cloned.freshValue = this.freshValue;
     return cloned;
   }
   /**
@@ -1801,6 +2018,9 @@ var _ContentQueryBuilder = class _ContentQueryBuilder {
         params.childrenLimit = this.childrenOptions.limit;
       }
     }
+    if (this.freshValue !== void 0) {
+      params[FRESH_PARAMETER] = this.freshValue;
+    }
     return params;
   }
 };
@@ -1823,8 +2043,20 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
     __publicField(this, "requestHeaders");
     /** The client's locale, asked when the read is sent rather than copied when it was built. */
     __publicField(this, "clientLocale");
+    __publicField(this, "freshValue");
     this.clientLocale = readClientLocale(locale);
   }
+  /**
+   * The feed position this read follows — a change's `fresh` (`FeedChange`), or a resync's. Sent as
+   * `?_fresh`, the one term the API declares for it: no cache — the Content API's edge or the
+   * browser's own — holds an answer for that position from before it, so the read is answered after
+   * the change, and every read naming the same position shares that answer. The answer is the
+   * read's own; omit it for a read no change prompted.
+   */
+  fresh(position) {
+    this.freshValue = position;
+    return this;
+  }
   /**
    * Include related content in the response
    */
@@ -1913,6 +2145,9 @@ var _ContentByIdBuilder = class _ContentByIdBuilder {
         params.childrenLimit = this.childrenOptions.limit;
       }
     }
+    if (this.freshValue !== void 0) {
+      params[FRESH_PARAMETER] = this.freshValue;
+    }
     try {
       return await this.httpClient.fetchPayload(
         "/v1/{contentType}/{id}",
@@ -3079,6 +3314,7 @@ var _SingletonClient = class _SingletonClient {
     const localeValueFinal = options?.locale ?? this.localeValue ?? this.clientLocale();
     if (includeValue) query.include = includeValue.join(",");
     if (localeValueFinal != null && localeValueFinal !== "") query.locale = localeValueFinal;
+    if (options?.fresh !== void 0) query[FRESH_PARAMETER] = options.fresh;
     const response = await this.httpClient.send(
       "/v1/singletons/{key}",
       "get",
@@ -3374,6 +3610,7 @@ var _SearchBuilder = class _SearchBuilder {
     __publicField(this, "query");
     __publicField(this, "searchOptions", {});
     __publicField(this, "requestHeaders");
+    __publicField(this, "freshValue");
     /** The client's locale, asked when the query is sent rather than copied when it was built. */
     __publicField(this, "clientLocale");
     this.query = query;
@@ -3387,6 +3624,15 @@ var _SearchBuilder = class _SearchBuilder {
     this.requestHeaders = headers;
     return this;
   }
+  /**
+   * The feed position this search follows — a change's `fresh` (`FeedChange`), or a resync's. Sent
+   * as `?_fresh` on the query string beside the body: the edge keys a search on both, so no answer
+   * it holds from before that position can answer it. The answer is the search's own.
+   */
+  fresh(position) {
+    this.freshValue = position;
+    return this;
+  }
   /**
    * Search within a single content type. Where a schema types the client, the name is one of its
    * content types and the results are that type's entries.
@@ -3528,7 +3774,11 @@ var _SearchBuilder = class _SearchBuilder {
     const response = await this.httpClient.send(
       "/v1/search",
       "post",
-      { body, headers: this.requestHeaders }
+      {
+        body,
+        headers: this.requestHeaders,
+        ...this.freshValue === void 0 ? {} : { query: { [FRESH_PARAMETER]: this.freshValue } }
+      }
     );
     return response.body;
   }
@@ -4544,23 +4794,67 @@ var AdhocQueryClient = _AdhocQueryClient;
 
 // src/changes/changes.ts
 var CHANGES_POLL_TIMEOUT_MS = 25e3 + 5e3;
+var EXPIRED_REASONS = {
+  retention: "retention",
+  "dataset-replaced": "dataset-replaced",
+  "ahead-of-head": "ahead-of-head",
+  "foreign-cursor": "foreign-cursor",
+  "too-far-behind": "too-far-behind"
+};
 var _ChangesExpiredError = class _ChangesExpiredError extends ResourceExpiredError {
-  /** The base class's signature, so `withContext` can rebuild one. */
-  constructor(message, statusCode = 410, cause, context) {
+  /** The base class's signature, so `withContext` can rebuild one; then the position resynced to. */
+  constructor(message, statusCode = 410, cause, context, fresh) {
     super(message, statusCode, cause, context);
     __publicField(this, "reason");
+    /**
+     * The position the feed resynced to, which a refetch of everything names as `?_fresh`, as a
+     * change's {@link FeedChange.fresh} is named: the head a `/v1/changes` resync took, or the cursor
+     * the edge's `feed.resync` sent. `undefined` when there was no resync to take one — the error was
+     * thrown (`onExpired: 'throw'`) — and on an error a caller built itself.
+     */
+    __publicField(this, "fresh");
     this.name = "ChangesExpiredError";
     this.reason = expiredReasonOf(message);
+    this.fresh = fresh;
+  }
+  /** The base class rebuilds from its four arguments, which would drop the position resynced to. */
+  withContext(context) {
+    const Constructor = this.constructor;
+    return new Constructor(
+      this.message,
+      this.statusCode,
+      this.cause,
+      { ...this.context, ...context },
+      this.fresh
+    );
+  }
+  /** `/v1/changes`' refusal, with the head the feed resynced to when it did. */
+  static of(expired, fresh) {
+    return new _ChangesExpiredError(
+      expired.message,
+      expired.statusCode,
+      expired,
+      expired.context,
+      fresh
+    );
   }
-  static of(expired) {
-    return new _ChangesExpiredError(expired.message, expired.statusCode, expired, expired.context);
+  /** The live edge's `feed.resync`: refetch everything, then continue from the cursor it sent. */
+  static resync(reason, cursor) {
+    return new _ChangesExpiredError(
+      `The live edge cannot list the changes since this cursor (${reason}). Refetch everything derived from the feed; it continues from the position it sent.`,
+      410,
+      void 0,
+      { transport: "live-edge" },
+      cursor
+    );
   }
 };
 __name(_ChangesExpiredError, "ChangesExpiredError");
 var ChangesExpiredError = _ChangesExpiredError;
 function expiredReasonOf(message) {
-  if (message.includes("(retention)")) return "retention";
-  if (message.includes("(dataset-replaced)")) return "dataset-replaced";
+  for (const reason of Object.values(EXPIRED_REASONS)) {
+    if (message.includes(`(${reason})`)) return reason;
+  }
   return "unknown";
 }
 __name(expiredReasonOf, "expiredReasonOf");
@@ -4580,7 +4874,7 @@ async function* pollChanges(http, options = {}) {
       const onExpired = options.onExpired ?? "throw";
       if (onExpired === "throw") throw expired;
       since = void 0;
-      resynced = typeof onExpired === "function" ? expired : void 0;
+      resynced = typeof onExpired === "function" ? error : void 0;
       continue;
     }
     const { data, page } = response.body;
@@ -4589,13 +4883,13 @@ async function* pollChanges(http, options = {}) {
     }
     since = page.nextCursor;
     if (resynced !== void 0 && typeof options.onExpired === "function") {
-      const expired = resynced;
+      const expired = ChangesExpiredError.of(resynced, page.nextCursor);
       resynced = void 0;
       await options.onExpired(expired);
       if (isAborted(signal)) return;
     }
     for (const change of data) {
-      yield change;
+      yield { ...change, fresh: change.cursor };
       if (isAborted(signal)) return;
     }
     if (data.length === 0) {
@@ -4634,6 +4928,477 @@ 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 = {}) {
+    super(message, options.statusCode, options.cause, options.context);
+    __publicField(this, "code", "LIVE_EDGE_ENDED");
+    __publicField(this, "retryable");
+    __publicField(this, "end");
+    __publicField(this, "retry");
+    /** A refused poll's `Retry-After`, in milliseconds, where it carried a readable one. */
+    __publicField(this, "retryAfterMs");
+    this.end = end;
+    this.retry = retry;
+    this.retryable = retry !== "stop";
+    this.retryAfterMs = options.retryAfterMs;
+  }
+  /**
+   * The base class rebuilds an error through its own four-argument constructor, which this class
+   * does not have; rebuilt that way, `end` would be a string and `retry` a number.
+   */
+  withContext(context) {
+    const rebuilt = new _LiveEdgeError(this.message, this.end, this.retry, {
+      ...this.statusCode === void 0 ? {} : { statusCode: this.statusCode },
+      ...this.cause === void 0 ? {} : { cause: this.cause },
+      ...this.retryAfterMs === void 0 ? {} : { retryAfterMs: this.retryAfterMs },
+      context: { ...this.context, ...context }
+    });
+    return rebuilt;
+  }
+  getUserMessage() {
+    return this.message;
+  }
+};
+__name(_LiveEdgeError, "LiveEdgeError");
+var LiveEdgeError = _LiveEdgeError;
+
+// src/config/live-url.ts
+var LIVE_EDGE_OF_API = {
+  "https://api.relyio.com": "https://live.relyio.com"
+};
+var HTTP_SCHEME_OF = {
+  "http:": "http:",
+  "https:": "https:",
+  "ws:": "http:",
+  "wss:": "https:"
+};
+function liveEdgeAddress(config) {
+  if (config.liveUrl !== void 0) return readLiveUrl(config.liveUrl);
+  const derived = originOf(config.baseUrl);
+  const edge = derived === void 0 ? void 0 : LIVE_EDGE_OF_API[derived];
+  if (edge !== void 0) return { ok: true, url: new URL(edge) };
+  return {
+    ok: false,
+    message: `Live updates need the address of RelyIO\u2019s live edge, and this client cannot derive it: \`baseUrl\` is not RelyIO\u2019s API (${Object.keys(LIVE_EDGE_OF_API).join(", ")}). Set \`liveUrl\` in createClient() to the live edge this API belongs with. Nothing was sent.`
+  };
+}
+__name(liveEdgeAddress, "liveEdgeAddress");
+function readLiveUrl(liveUrl) {
+  let url;
+  try {
+    url = new URL(liveUrl);
+  } catch {
+    return { ok: false, message: `\`liveUrl\` is not a URL: "${liveUrl}". Nothing was sent.` };
+  }
+  const scheme = HTTP_SCHEME_OF[url.protocol];
+  if (scheme === void 0) {
+    return {
+      ok: false,
+      message: `\`liveUrl\` must be an https:, wss:, http: or ws: URL, not ${url.protocol}. Nothing was sent.`
+    };
+  }
+  url.protocol = scheme;
+  url.search = "";
+  url.hash = "";
+  return { ok: true, url };
+}
+__name(readLiveUrl, "readLiveUrl");
+function originOf(baseUrl) {
+  try {
+    return new URL(baseUrl).origin;
+  } catch {
+    return void 0;
+  }
+}
+__name(originOf, "originOf");
+
+// src/changes/live-edge.ts
+var LIVE_KEEPALIVE_INTERVAL_MS = 3e4;
+var LIVE_POLLS_BEFORE_SOCKET = 4;
+async function* subscribeLiveEdge(client, options = {}) {
+  const { signal } = options;
+  if (isAborted(signal)) return;
+  const key = client.apiKey;
+  if (key === void 0 || !isPublishableKey(key)) {
+    throw new LiveEdgeError(NEEDS_PUBLISHABLE_KEY, { kind: "needs-publishable-key" }, "stop");
+  }
+  const address = liveEdgeAddress(client);
+  if (!address.ok) throw new LiveEdgeError(address.message, { kind: "needs-live-url" }, "stop");
+  const request = {
+    base: address.url,
+    key,
+    dataset: client.dataset,
+    types: options.types,
+    ids: options.ids
+  };
+  const reach = { position: options.since };
+  for (; ; ) {
+    const socket = openSocket(client, edgeUrl(request, reach.position, "socket"));
+    if (socket !== void 0) {
+      const ended = yield* followSocket(socket, reach, options);
+      if (ended === "aborted") return;
+    }
+    const polled = yield* followPolls(client, request, reach, options);
+    if (polled === "aborted") return;
+  }
+}
+__name(subscribeLiveEdge, "subscribeLiveEdge");
+var SOCKET_CONNECTING = 0;
+var SOCKET_OPEN = 1;
+function runtimeWebSocket() {
+  const candidate = globalThis.WebSocket;
+  return typeof candidate === "function" ? candidate : void 0;
+}
+__name(runtimeWebSocket, "runtimeWebSocket");
+function openSocket(client, url) {
+  const Socket = client.webSocket ?? runtimeWebSocket();
+  if (Socket === void 0) return void 0;
+  try {
+    return new Socket(url);
+  } catch {
+    return void 0;
+  }
+}
+__name(openSocket, "openSocket");
+async function* followSocket(socket, reach, options) {
+  const { signal } = options;
+  const inbox = socketInbox(socket, signal);
+  let open = false;
+  try {
+    for (; ; ) {
+      const event = await inbox.next();
+      if (event === void 0) return "aborted";
+      switch (event.kind) {
+        case "open": {
+          open = true;
+          inbox.keepAlive();
+          continue;
+        }
+        case "error": {
+          if (!open) return "unopened";
+          continue;
+        }
+        case "close": {
+          if (!open) return "unopened";
+          throw closedBy(event.code, event.reason);
+        }
+        case "silent": {
+          throw new LiveEdgeError(
+            "The live edge\u2019s socket stopped answering its keepalive, so the connection is presumed dead; reconnecting from the last cursor.",
+            { kind: "lost" },
+            "retry"
+          );
+        }
+        case "message": {
+          if (event.data === VISITOR_KEEPALIVE.response) continue;
+          const frame = typeof event.data === "string" ? parseVisitorFrame(event.data) : null;
+          if (frame === null)
+            throw unreadable(`a frame the wire does not declare: ${sample(event.data)}`);
+          switch (frame.type) {
+            case VISITOR_FRAMES.opened: {
+              reach.position = frame.cursor;
+              options.opened?.();
+              options.reached?.(frame.cursor);
+              continue;
+            }
+            case VISITOR_FRAMES.changes: {
+              const prior = reach.position;
+              if (prior === void 0) throw unreadable("changes before the socket had a position");
+              for (const change of changesOf(frame.changes, frame.cursor, prior)) {
+                yield change;
+                if (isAborted(signal)) return "aborted";
+              }
+              reach.position = frame.cursor;
+              if (frame.changes.length === 0) options.reached?.(frame.cursor);
+              continue;
+            }
+            case VISITOR_FRAMES.resync: {
+              await expire(frame.reason, frame.cursor, options);
+              if (isAborted(signal)) return "aborted";
+              reach.position = frame.cursor;
+              options.reached?.(frame.cursor);
+              continue;
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    inbox.dispose();
+  }
+}
+__name(followSocket, "followSocket");
+function socketInbox(socket, signal) {
+  const events = [];
+  let wake;
+  let disposed = false;
+  let heard = true;
+  let keepalive;
+  const rouse = /* @__PURE__ */ __name(() => {
+    const waking = wake;
+    wake = void 0;
+    waking?.();
+  }, "rouse");
+  const push = /* @__PURE__ */ __name((event) => {
+    if (disposed) return;
+    events.push(event);
+    rouse();
+  }, "push");
+  socket.addEventListener("open", () => push({ kind: "open" }));
+  socket.addEventListener("message", (event) => {
+    heard = true;
+    push({ kind: "message", data: isRecord(event) ? event["data"] : void 0 });
+  });
+  socket.addEventListener("close", (event) => {
+    const code = isRecord(event) ? event["code"] : void 0;
+    const reason = isRecord(event) ? event["reason"] : void 0;
+    push({
+      kind: "close",
+      // A close event always carries both; a socket that somehow raised one without them closed
+      // abnormally, which is what 1006 says.
+      code: typeof code === "number" ? code : 1006,
+      reason: typeof reason === "string" ? reason : ""
+    });
+  });
+  socket.addEventListener("error", () => push({ kind: "error" }));
+  signal?.addEventListener("abort", rouse, { once: true });
+  return {
+    async next() {
+      for (; ; ) {
+        if (isAborted(signal)) return void 0;
+        const event = events.shift();
+        if (event !== void 0) return event;
+        await new Promise((resolve) => {
+          wake = resolve;
+        });
+      }
+    },
+    keepAlive() {
+      keepalive = setInterval(() => {
+        if (!heard) {
+          push({ kind: "silent" });
+          return;
+        }
+        heard = false;
+        if (socket.readyState === SOCKET_OPEN) socket.send(VISITOR_KEEPALIVE.request);
+      }, LIVE_KEEPALIVE_INTERVAL_MS);
+    },
+    dispose() {
+      disposed = true;
+      if (keepalive !== void 0) clearInterval(keepalive);
+      signal?.removeEventListener("abort", rouse);
+      if (socket.readyState === SOCKET_CONNECTING || socket.readyState === SOCKET_OPEN) {
+        socket.close(1e3);
+      }
+    }
+  };
+}
+__name(socketInbox, "socketInbox");
+function closedBy(code, reason) {
+  const retry = closeRetryOf(code);
+  const meaning = hasOwn(CLOSE_MEANING, code) ? CLOSE_MEANING[code] : code < 4e3 ? "the connection dropped" : "a refusal this version of the SDK does not know";
+  const said = `close ${code}${reason === "" ? "" : ` ${reason}`}`;
+  return new LiveEdgeError(
+    `The live edge ended this subscription (${said}): ${meaning}. ${AFTER_A_CLOSE[retry]}`,
+    { kind: "closed", code, reason },
+    retry
+  );
+}
+__name(closedBy, "closedBy");
+var AFTER_A_CLOSE = {
+  stop: "The same request would be refused again, so it was not retried.",
+  retry: "Reconnecting from the last cursor after a short back-off.",
+  "back-off": "Retrying after a back-off of at least a minute, without polling, which the same admission refuses."
+};
+function closeRetryOf(code) {
+  if (hasOwn(VISITOR_CLOSE_RETRY, code)) return VISITOR_CLOSE_RETRY[code];
+  return code < 4e3 ? "retry" : "stop";
+}
+__name(closeRetryOf, "closeRetryOf");
+var CLOSE_MEANING = {
+  [VISITOR_CLOSE_CODES.requestInvalid]: "the edge could not read the request \u2014 a malformed cursor or filter",
+  [VISITOR_CLOSE_CODES.keyRefused]: "the key is not a publishable key the edge accepts \u2014 unknown, revoked or expired",
+  [VISITOR_CLOSE_CODES.originRefused]: "this page\u2019s origin is not on the publishable key\u2019s allowed origins",
+  [VISITOR_CLOSE_CODES.datasetRefused]: "`dataset` names no dataset the key reaches",
+  [VISITOR_CLOSE_CODES.unavailable]: "the edge could not reach what it needed to decide just now",
+  [VISITOR_CLOSE_CODES.allowanceReached]: "the project holds as many live connections as its plan allows",
+  [VISITOR_CLOSE_CODES.addressLimitReached]: "this address holds as many live connections to the project as one address may",
+  [VISITOR_CLOSE_CODES.ceilingReached]: "the project is at its safety ceiling of live connections"
+};
+async function* followPolls(client, request, reach, options) {
+  const { signal } = options;
+  for (let poll = 0; poll < LIVE_POLLS_BEFORE_SOCKET; poll += 1) {
+    if (isAborted(signal)) return "aborted";
+    const answer = await pollOnce2(client, request, reach.position, signal);
+    if (answer === void 0) return "aborted";
+    options.opened?.();
+    if (answer.kind === "resync") {
+      await expire(answer.reason, answer.cursor, options);
+      if (isAborted(signal)) return "aborted";
+      reach.position = answer.cursor;
+      options.reached?.(answer.cursor);
+    } else {
+      const prior = reach.position;
+      if (answer.changes.length > 0 && prior === void 0) {
+        throw unreadable("a poll without a cursor answered changes");
+      }
+      for (const change of changesOf(answer.changes, answer.cursor, prior ?? answer.cursor)) {
+        yield change;
+        if (isAborted(signal)) return "aborted";
+      }
+      reach.position = answer.cursor;
+      if (answer.changes.length === 0) options.reached?.(answer.cursor);
+    }
+    await sleep(VISITOR_POLL_INTERVAL_MS, signal);
+  }
+  return isAborted(signal) ? "aborted" : "socket";
+}
+__name(followPolls, "followPolls");
+async function pollOnce2(client, request, since, signal) {
+  if (isAborted(signal)) return void 0;
+  const url = edgeUrl(request, since, "poll", client.clientId);
+  const context = { url: edgeUrl({ ...request, key: void 0 }, since, "poll", client.clientId) };
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, client.timeout);
+  const onAbort = /* @__PURE__ */ __name(() => controller.abort(), "onAbort");
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    let response;
+    let text;
+    try {
+      const send = client.fetch ?? globalThis.fetch;
+      response = await send(url, { method: "GET", signal: controller.signal });
+      text = await response.text();
+    } catch (error) {
+      if (isAborted(signal)) return void 0;
+      if (timedOut) {
+        throw new TimeoutError(
+          `The live edge did not answer a poll within ${client.timeout}ms`,
+          client.timeout,
+          void 0,
+          void 0,
+          context
+        );
+      }
+      throw ErrorMapper.mapGenericError(
+        error instanceof Error ? error : new Error(String(error)),
+        context
+      );
+    }
+    const body = parseJson(text);
+    if (!response.ok) throw refusedPoll(response, body, context);
+    const answer = readVisitorPollAnswer(isRecord(body) ? body["data"] : void 0);
+    if (answer === null)
+      throw unreadable(`a poll answer the wire does not declare: ${sample(text)}`);
+    return answer;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+}
+__name(pollOnce2, "pollOnce");
+function refusedPoll(response, body, context) {
+  const headers = {};
+  response.headers.forEach((value, name) => {
+    headers[name] = value;
+  });
+  const mapped = ErrorMapper.mapHttpError(
+    { status: response.status, statusText: response.statusText, body, headers },
+    { ...context, method: "GET" }
+  );
+  const refusal = readError(body);
+  if (refusal === void 0 || !hasOwn(VISITOR_POLL_RETRY, refusal.code)) return mapped;
+  const code = refusal.code;
+  const retryAfterMs = parseRetryAfterMs(headerValue(headers, "Retry-After"), Date.now());
+  return new LiveEdgeError(
+    `The live edge refused a poll (${code}): ${refusal.messages[0] ?? mapped.message}`,
+    { kind: "refused", code },
+    VISITOR_POLL_RETRY[code],
+    {
+      statusCode: response.status,
+      cause: mapped,
+      ...retryAfterMs === void 0 ? {} : { retryAfterMs },
+      context
+    }
+  );
+}
+__name(refusedPoll, "refusedPoll");
+function edgeUrl(request, since, transport, clientId) {
+  const url = new URL(request.base.href);
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}${VISITOR_LIVE_PATH}`;
+  if (transport === "socket") url.protocol = url.protocol === "http:" ? "ws:" : "wss:";
+  const query = new URLSearchParams();
+  if (request.key !== void 0) query.set(VISITOR_QUERY.key, request.key);
+  if (request.dataset !== void 0 && request.dataset !== "") {
+    query.set(VISITOR_QUERY.dataset, request.dataset);
+  }
+  if (since !== void 0) query.set(VISITOR_QUERY.since, since);
+  if (request.types !== void 0) query.set(VISITOR_QUERY.types, request.types.join(","));
+  if (request.ids !== void 0) query.set(VISITOR_QUERY.ids, request.ids.join(","));
+  if (transport === "poll" && clientId !== void 0) query.set(VISITOR_QUERY.client, clientId);
+  url.search = query.toString();
+  return url.href;
+}
+__name(edgeUrl, "edgeUrl");
+function changesOf(changes, cursor, prior) {
+  const last = changes.length - 1;
+  return changes.map((change, index) => ({
+    entryId: change.entryId,
+    contentType: change.contentType,
+    locale: change.locale,
+    kind: change.kind,
+    cursor: index === last ? cursor : prior,
+    fresh: cursor
+  }));
+}
+__name(changesOf, "changesOf");
+async function expire(reason, cursor, options) {
+  const expired = ChangesExpiredError.resync(reason, cursor);
+  const onExpired = options.onExpired ?? "throw";
+  if (onExpired === "throw") throw expired;
+  if (typeof onExpired === "function") await onExpired(expired);
+}
+__name(expire, "expire");
+function unreadable(what) {
+  return new LiveEdgeError(
+    `The live edge sent ${what}. This version of the SDK cannot follow it, so it stopped.`,
+    { kind: "unreadable", what },
+    "stop"
+  );
+}
+__name(unreadable, "unreadable");
+var NEEDS_PUBLISHABLE_KEY = `Live updates at RelyIO\u2019s edge need a publishable key (\`${PUBLISHABLE_KEY_PREFIX}\u2026\`), and this client holds none. A secret or preview key is never sent to the edge; on a server, follow \`changes()\` with it instead. Nothing was sent.`;
+function sample(value) {
+  const text = typeof value === "string" ? value : `(${typeof value})`;
+  return text.length > 200 ? `${text.slice(0, 200)}\u2026` : text;
+}
+__name(sample, "sample");
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+__name(parseJson, "parseJson");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(isRecord, "isRecord");
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+__name(hasOwn, "hasOwn");
+
 // src/config/dev-detection.ts
 function sandboxStateOf(resolution) {
   return resolution.state === "active" ? resolution.sandbox : resolution;
@@ -4776,6 +5541,12 @@ function validateConfig(config) {
   if (config.baseUrl != null && typeof config.baseUrl !== "string") {
     throw new Error("Base URL must be a string");
   }
+  if (config.liveUrl != null && typeof config.liveUrl !== "string") {
+    throw new Error("liveUrl must be a string");
+  }
+  if (config.webSocket != null && typeof config.webSocket !== "function") {
+    throw new Error("webSocket must be a WebSocket class");
+  }
   if (config.timeout != null) assertRequestTimeout(config.timeout);
   if (config.retryAttempts != null && !(Number.isInteger(config.retryAttempts) && config.retryAttempts >= 1)) {
     throw new Error(
@@ -4883,6 +5654,8 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
      * locale, or none after `locale: null` (REL-1453).
      */
     __publicField(this, "currentLocale", /* @__PURE__ */ __name(() => this.config.locale, "currentLocale"));
+    /** The live edge's poll client id: chosen once, when first needed, and kept for this client's life. */
+    __publicField(this, "_liveClientId");
     const { schema, ...clientConfig } = config;
     this._schema = schema;
     const resolved = resolveConfig(clientConfig);
@@ -5091,13 +5864,15 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * Lazy — nothing is requested until the first `next()`. It runs until
    * `signal` aborts, which ends the `for await` cleanly rather than throwing.
    * A change names what changed; refetch it through the ordinary read path
-   * (`INV-SS-CHANGE-IS-IDS`).
+   * (`INV-SS-CHANGE-IS-IDS`), naming its `fresh` so no cache answers with the
+   * body from before it (`FeedChange`).
    *
    * @example
    * ```typescript
    * const controller = new AbortController()
    * for await (const change of relyio.changes({ since: cursor, types: ['post'], signal: controller.signal })) {
-   *   // { entryId, contentType, locale, kind, cursor }
+   *   // { entryId, contentType, locale, kind, cursor, fresh }
+   *   await relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute()
    * }
    * ```
    *
@@ -5105,13 +5880,60 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * ```typescript
    * for await (const change of relyio.changes({
    *   since: cursor,
-   *   onExpired: async () => invalidateEverything(),
+   *   onExpired: async expired => refetchEverything(expired.fresh),
    * })) { … }
    * ```
    */
   changes(options = {}) {
     return pollChanges(this.httpClient, options);
   }
+  /**
+   * Follow the dataset's **published** changes at RelyIO's live edge, with a publishable key
+   * (`rly_pub_…`): each change as ids, in order — the transport a browser follows changes with.
+   *
+   * A WebSocket to the edge, from `since` or the dataset's current position; where a socket cannot
+   * open — the runtime has none, or the network refuses it — it polls the edge instead, about every
+   * fifteen seconds, from the same cursor. The edge is `liveUrl`, or derived from the default
+   * `baseUrl` (see `RelyIOConfig.liveUrl`).
+   *
+   * One subscription ends only when `signal` aborts, which ends the `for await` cleanly; every other
+   * end — a socket a deploy dropped, a refusal, a refused poll — is thrown as a `LiveEdgeError`
+   * that says whether to stop, retry or back off. Hand it to `followChanges()`, the one loop that
+   * reconnects from the last cursor with jittered back-off and honours those answers:
+   *
+   * @example
+   * ```typescript
+   * const relyio = createClient({ apiKey: 'rly_pub_…' })
+   * const controller = new AbortController()
+   * await followChanges(from => relyio.liveChanges({ ...from, types: ['post'] }), {
+   *   signal: controller.signal,
+   *   // `fresh` names a position no cache holds a body for from before the change.
+   *   onChange: change =>
+   *     relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute(),
+   *   onResync: resync => refetchEverything(resync.cause === 'expired' ? resync.expired.fresh : undefined),
+   * })
+   * ```
+   *
+   * A client without a publishable key sends nothing: a secret or preview key is never put in the
+   * edge's URL. On a server, follow `changes()` with it instead.
+   */
+  liveChanges(options = {}) {
+    const { apiKey, dataset, baseUrl, liveUrl, fetch: fetch2, webSocket, timeout } = this.config;
+    this._liveClientId ?? (this._liveClientId = randomClientId());
+    return subscribeLiveEdge(
+      {
+        apiKey,
+        dataset,
+        baseUrl,
+        liveUrl,
+        fetch: fetch2,
+        webSocket,
+        timeout,
+        clientId: this._liveClientId
+      },
+      options
+    );
+  }
   /**
    * The dataset's current position in the changes feed, as a cursor to start
    * `changes({ since })` or `followChanges(…, { since })` from. One
@@ -5404,7 +6226,20 @@ function createClient(config) {
   return new TypedRelyIOClient(config);
 }
 __name(createClient, "createClient");
+function randomClientId() {
+  const bytes = new Uint8Array(16);
+  const random = globalThis.crypto;
+  if (typeof random?.getRandomValues === "function") {
+    random.getRandomValues.call(random, bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+__name(randomClientId, "randomClientId");
 
-export { AdhocQueryBuilder, AdhocQueryClient, AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthorizationError, AutocompleteBuilder, BaseValidationError, BatchBuilder, BatchClient, ChangesExpiredError, ConnectionError, ContentByIdBuilder, ContentClient, ContentQueryBuilder, ErrorMapper, FileUploadError, FileValidationError, HttpClient, InvalidApiKeyError, InvalidPayloadError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PayloadTooLargeError, PlanFeatureUnavailableError, RateLimitError, ReadOnlyKeyError, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, SearchBuilder, SearchClient, ServerError, ServiceIndeterminateError, SettingsClient, SimilarBuilder, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, ValidationError, createClient, entityTagOf, isAborted, isAssetEntry, isResourceNotFound, matchRoute, serviceInstructedDelayMs, sleep, validateFile };
-//# sourceMappingURL=chunk-GYHAVYND.js.map
-//# sourceMappingURL=chunk-GYHAVYND.js.map
+export { AdhocQueryBuilder, AdhocQueryClient, AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthorizationError, AutocompleteBuilder, BaseValidationError, BatchBuilder, BatchClient, ChangesExpiredError, ConnectionError, ContentByIdBuilder, ContentClient, ContentQueryBuilder, ErrorMapper, FileUploadError, FileValidationError, HttpClient, InvalidApiKeyError, InvalidPayloadError, LIVE_KEEPALIVE_INTERVAL_MS, LiveEdgeError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PUBLISHABLE_KEY_PREFIX, PayloadTooLargeError, PlanFeatureUnavailableError, RateLimitError, ReadOnlyKeyError, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, SearchBuilder, SearchClient, ServerError, ServiceIndeterminateError, SettingsClient, SimilarBuilder, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, VISITOR_ADMISSION_RETRY_AFTER_SECONDS, ValidationError, createClient, entityTagOf, isAborted, isAssetEntry, isPublishableKey, isResourceNotFound, matchRoute, serviceInstructedDelayMs, sleep, validateFile };
+//# sourceMappingURL=chunk-QFHVF3YF.js.map
+//# sourceMappingURL=chunk-QFHVF3YF.js.map