@relyio/sdk 0.8.0 → 0.9.0

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

@@ -4862,6 +4862,7 @@ async function* pollChanges(http, options = {}) {
   const { signal } = options;
   let since = options.since;
   let resynced;
+  let starting = since === void 0;
   for (; ; ) {
     if (isAborted(signal)) return;
     let response;
@@ -4892,6 +4893,10 @@ async function* pollChanges(http, options = {}) {
       yield { ...change, fresh: change.cursor };
       if (isAborted(signal)) return;
     }
+    if (starting) {
+      starting = false;
+      options.reached?.(page.nextCursor);
+    }
     if (data.length === 0) {
       const wait = parseRetryAfterMs(headerValue(response.headers, "Retry-After"), Date.now());
       if (wait !== void 0 && wait > 0) await sleep(wait, signal);
@@ -5019,23 +5024,12 @@ __name(originOf, "originOf");
 
 // src/changes/live-edge.ts
 var LIVE_KEEPALIVE_INTERVAL_MS = 3e4;
+var LIVE_SOCKET_OPEN_TIMEOUT_MS = VISITOR_POLL_INTERVAL_MS;
 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 request = edgeRequest(client, options);
   const reach = { position: options.since };
   for (; ; ) {
     const socket = openSocket(client, edgeUrl(request, reach.position, "socket"));
@@ -5069,6 +5063,7 @@ async function* followSocket(socket, reach, options) {
   const { signal } = options;
   const inbox = socketInbox(socket, signal);
   let open = false;
+  let caughtUp = false;
   try {
     for (; ; ) {
       const event = await inbox.next();
@@ -5094,6 +5089,10 @@ async function* followSocket(socket, reach, options) {
             "retry"
           );
         }
+        case "late": {
+          if (caughtUp) continue;
+          return "unopened";
+        }
         case "message": {
           if (event.data === VISITOR_KEEPALIVE.response) continue;
           const frame = typeof event.data === "string" ? parseVisitorFrame(event.data) : null;
@@ -5101,6 +5100,8 @@ async function* followSocket(socket, reach, options) {
             throw unreadable(`a frame the wire does not declare: ${sample(event.data)}`);
           switch (frame.type) {
             case VISITOR_FRAMES.opened: {
+              caughtUp = true;
+              inbox.caughtUp();
               reach.position = frame.cursor;
               options.opened?.();
               options.reached?.(frame.cursor);
@@ -5167,6 +5168,10 @@ function socketInbox(socket, signal) {
   });
   socket.addEventListener("error", () => push({ kind: "error" }));
   signal?.addEventListener("abort", rouse, { once: true });
+  let connecting = setTimeout(() => {
+    connecting = void 0;
+    push({ kind: "late" });
+  }, LIVE_SOCKET_OPEN_TIMEOUT_MS);
   return {
     async next() {
       for (; ; ) {
@@ -5188,8 +5193,13 @@ function socketInbox(socket, signal) {
         if (socket.readyState === SOCKET_OPEN) socket.send(VISITOR_KEEPALIVE.request);
       }, LIVE_KEEPALIVE_INTERVAL_MS);
     },
+    caughtUp() {
+      if (connecting !== void 0) clearTimeout(connecting);
+      connecting = void 0;
+    },
     dispose() {
       disposed = true;
+      if (connecting !== void 0) clearTimeout(connecting);
       if (keepalive !== void 0) clearInterval(keepalive);
       signal?.removeEventListener("abort", rouse);
       if (socket.readyState === SOCKET_CONNECTING || socket.readyState === SOCKET_OPEN) {
@@ -5225,7 +5235,9 @@ 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",
-  [VISITOR_CLOSE_CODES.unavailable]: "the edge could not reach what it needed to decide just now",
+  // 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.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"
@@ -5332,6 +5344,22 @@ function refusedPoll(response, body, context) {
   );
 }
 __name(refusedPoll, "refusedPoll");
+function edgeRequest(client, filter) {
+  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");
+  return {
+    base: address.url,
+    key,
+    dataset: client.dataset,
+    types: filter.types,
+    ids: filter.ids
+  };
+}
+__name(edgeRequest, "edgeRequest");
 function edgeUrl(request, since, transport, clientId) {
   const url = new URL(request.base.href);
   url.pathname = `${url.pathname.replace(/\/+$/, "")}${VISITOR_LIVE_PATH}`;
@@ -5892,9 +5920,14 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * (`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`).
+   * open — the runtime has none, the network refuses it, or it has not opened and been told its
+   * position within `LIVE_SOCKET_OPEN_TIMEOUT_MS` — 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`).
+   *
+   * Without `since` it starts at the dataset's current position, which it hands `reached` before
+   * anything after it: read what you show after that call, and a publish your read did not see is
+   * one this subscription announces (see `LiveChangesOptions.since`).
    *
    * 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`
@@ -6240,6 +6273,6 @@ function randomClientId() {
 }
 __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, 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
+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, LIVE_SOCKET_OPEN_TIMEOUT_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-LGNJIGHL.js.map
+//# sourceMappingURL=chunk-LGNJIGHL.js.map

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

@@ -4864,6 +4864,7 @@ async function* pollChanges(http, options = {}) {
   const { signal } = options;
   let since = options.since;
   let resynced;
+  let starting = since === void 0;
   for (; ; ) {
     if (isAborted(signal)) return;
     let response;
@@ -4894,6 +4895,10 @@ async function* pollChanges(http, options = {}) {
       yield { ...change, fresh: change.cursor };
       if (isAborted(signal)) return;
     }
+    if (starting) {
+      starting = false;
+      options.reached?.(page.nextCursor);
+    }
     if (data.length === 0) {
       const wait = parseRetryAfterMs(headerValue(response.headers, "Retry-After"), Date.now());
       if (wait !== void 0 && wait > 0) await sleep(wait, signal);
@@ -5021,23 +5026,12 @@ chunkMWMSFIWN_cjs.__name(originOf, "originOf");
 
 // src/changes/live-edge.ts
 var LIVE_KEEPALIVE_INTERVAL_MS = 3e4;
+var LIVE_SOCKET_OPEN_TIMEOUT_MS = VISITOR_POLL_INTERVAL_MS;
 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 request = edgeRequest(client, options);
   const reach = { position: options.since };
   for (; ; ) {
     const socket = openSocket(client, edgeUrl(request, reach.position, "socket"));
@@ -5071,6 +5065,7 @@ async function* followSocket(socket, reach, options) {
   const { signal } = options;
   const inbox = socketInbox(socket, signal);
   let open = false;
+  let caughtUp = false;
   try {
     for (; ; ) {
       const event = await inbox.next();
@@ -5096,6 +5091,10 @@ async function* followSocket(socket, reach, options) {
             "retry"
           );
         }
+        case "late": {
+          if (caughtUp) continue;
+          return "unopened";
+        }
         case "message": {
           if (event.data === VISITOR_KEEPALIVE.response) continue;
           const frame = typeof event.data === "string" ? parseVisitorFrame(event.data) : null;
@@ -5103,6 +5102,8 @@ async function* followSocket(socket, reach, options) {
             throw unreadable(`a frame the wire does not declare: ${sample(event.data)}`);
           switch (frame.type) {
             case VISITOR_FRAMES.opened: {
+              caughtUp = true;
+              inbox.caughtUp();
               reach.position = frame.cursor;
               options.opened?.();
               options.reached?.(frame.cursor);
@@ -5169,6 +5170,10 @@ function socketInbox(socket, signal) {
   });
   socket.addEventListener("error", () => push({ kind: "error" }));
   signal?.addEventListener("abort", rouse, { once: true });
+  let connecting = setTimeout(() => {
+    connecting = void 0;
+    push({ kind: "late" });
+  }, LIVE_SOCKET_OPEN_TIMEOUT_MS);
   return {
     async next() {
       for (; ; ) {
@@ -5190,8 +5195,13 @@ function socketInbox(socket, signal) {
         if (socket.readyState === SOCKET_OPEN) socket.send(VISITOR_KEEPALIVE.request);
       }, LIVE_KEEPALIVE_INTERVAL_MS);
     },
+    caughtUp() {
+      if (connecting !== void 0) clearTimeout(connecting);
+      connecting = void 0;
+    },
     dispose() {
       disposed = true;
+      if (connecting !== void 0) clearTimeout(connecting);
       if (keepalive !== void 0) clearInterval(keepalive);
       signal?.removeEventListener("abort", rouse);
       if (socket.readyState === SOCKET_CONNECTING || socket.readyState === SOCKET_OPEN) {
@@ -5227,7 +5237,9 @@ 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",
-  [VISITOR_CLOSE_CODES.unavailable]: "the edge could not reach what it needed to decide just now",
+  // 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.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"
@@ -5334,6 +5346,22 @@ function refusedPoll(response, body, context) {
   );
 }
 chunkMWMSFIWN_cjs.__name(refusedPoll, "refusedPoll");
+function edgeRequest(client, filter) {
+  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");
+  return {
+    base: address.url,
+    key,
+    dataset: client.dataset,
+    types: filter.types,
+    ids: filter.ids
+  };
+}
+chunkMWMSFIWN_cjs.__name(edgeRequest, "edgeRequest");
 function edgeUrl(request, since, transport, clientId) {
   const url = new URL(request.base.href);
   url.pathname = `${url.pathname.replace(/\/+$/, "")}${VISITOR_LIVE_PATH}`;
@@ -5894,9 +5922,14 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * (`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`).
+   * open — the runtime has none, the network refuses it, or it has not opened and been told its
+   * position within `LIVE_SOCKET_OPEN_TIMEOUT_MS` — 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`).
+   *
+   * Without `since` it starts at the dataset's current position, which it hands `reached` before
+   * anything after it: read what you show after that call, and a publish your read did not see is
+   * one this subscription announces (see `LiveChangesOptions.since`).
    *
    * 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`
@@ -6264,6 +6297,7 @@ exports.HttpClient = HttpClient;
 exports.InvalidApiKeyError = InvalidApiKeyError;
 exports.InvalidPayloadError = InvalidPayloadError;
 exports.LIVE_KEEPALIVE_INTERVAL_MS = LIVE_KEEPALIVE_INTERVAL_MS;
+exports.LIVE_SOCKET_OPEN_TIMEOUT_MS = LIVE_SOCKET_OPEN_TIMEOUT_MS;
 exports.LiveEdgeError = LiveEdgeError;
 exports.MethodNotAllowedError = MethodNotAllowedError;
 exports.MissingApiKeyError = MissingApiKeyError;
@@ -6301,5 +6335,5 @@ exports.matchRoute = matchRoute;
 exports.serviceInstructedDelayMs = serviceInstructedDelayMs;
 exports.sleep = sleep;
 exports.validateFile = validateFile;
-//# sourceMappingURL=chunk-XIE7WJV3.cjs.map
-//# sourceMappingURL=chunk-XIE7WJV3.cjs.map
+//# sourceMappingURL=chunk-SPFRDXAF.cjs.map
+//# sourceMappingURL=chunk-SPFRDXAF.cjs.map

package/dist/client/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkXIE7WJV3_cjs = require('../chunk-XIE7WJV3.cjs');
+var chunkSPFRDXAF_cjs = require('../chunk-SPFRDXAF.cjs');
 require('../chunk-LSRPMNPT.cjs');
 require('../chunk-TZL374LS.cjs');
 require('../chunk-MWMSFIWN.cjs');
@@ -9,11 +9,11 @@ require('../chunk-MWMSFIWN.cjs');
 
 Object.defineProperty(exports, "TypedRelyIOClient", {
   enumerable: true,
-  get: function () { return chunkXIE7WJV3_cjs.TypedRelyIOClient; }
+  get: function () { return chunkSPFRDXAF_cjs.TypedRelyIOClient; }
 });
 Object.defineProperty(exports, "createClient", {
   enumerable: true,
-  get: function () { return chunkXIE7WJV3_cjs.createClient; }
+  get: function () { return chunkSPFRDXAF_cjs.createClient; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/client/index.d.cts

@@ -1,4 +1,4 @@
-export { e as ClientSchema, R as Register, f as RegisteredSchema, d as TypedClientConfig, T as TypedRelyIOClient, c as createClient } from '../index-DBoPPlT1.cjs';
+export { e as ClientSchema, R as Register, f as RegisteredSchema, d as TypedClientConfig, T as TypedRelyIOClient, c as createClient } from '../index-B9axQW8s.cjs';
 import '../index-B_rIWO_l.cjs';
 import '../define-content-type-cEGjIwT5.cjs';
 import '../define-schema-DgbJ5Kwn.cjs';

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-export { e as ClientSchema, R as Register, f as RegisteredSchema, d as TypedClientConfig, T as TypedRelyIOClient, c as createClient } from '../index-yRJ2IqM_.js';
+export { e as ClientSchema, R as Register, f as RegisteredSchema, d as TypedClientConfig, T as TypedRelyIOClient, c as createClient } from '../index-GIfaMlQ7.js';
 import '../index-Cv4tmcrw.js';
 import '../define-content-type-cEGjIwT5.js';
 import '../define-schema-BPj2srgh.js';

package/dist/client/index.js

@@ -1,4 +1,4 @@
-export { TypedRelyIOClient, createClient } from '../chunk-QFHVF3YF.js';
+export { TypedRelyIOClient, createClient } from '../chunk-LGNJIGHL.js';
 import '../chunk-BBUB7C2Z.js';
 import '../chunk-H6IBQSMM.js';
 import '../chunk-XQ4QHWZE.js';

package/dist/{index-DBoPPlT1.d.cts → index-B9axQW8s.d.cts}

@@ -2960,6 +2960,18 @@ interface ChangesOptions {
      *   the new position, on every refetch. The iterator waits for it.
      */
     onExpired?: 'throw' | 'resync' | ((expired: ChangesExpiredError) => void | Promise<void>);
+    /**
+     * Called once, when the feed was opened without `since`, with the position it starts from: the
+     * first poll's answer, the dataset's head — before the next poll is sent. Read what you show
+     * **after** it and a write your read did not see is after the position, so this feed delivers it,
+     * with no second request to take the position first (`changesHead()` is that request) (REL-1513).
+     *
+     * `followChanges()` passes it (`ChangeSourceOptions.reached`), so a feed that drops before its first
+     * change reopens from there rather than re-reading everything. Never called with a later empty
+     * page's cursor: filtered, that cursor is past rows the filter hid, and a caller that widens the
+     * filter must not reopen from it.
+     */
+    reached?: (cursor: string) => void;
 }
 interface ChangesHeadOptions {
     /** Cancels the request; the promise then rejects. */
@@ -2975,10 +2987,18 @@ interface ChangesHeadOptions {
  * the poll interval, and what each close code and each refused poll means a client does next.
  *
  * **One open, two ways in.** A subscription opens a WebSocket to the edge. Where it cannot — the
- * runtime has no `WebSocket` (Node 18 and 20), constructing one throws, or the socket fails before it
- * opens (a network that blocks sockets) — it polls the edge instead, from the same cursor, about
- * every {@link VISITOR_POLL_INTERVAL_MS}, and tries a socket again about once a minute. Both carry
- * one cursor space, so a switch either way loses nothing.
+ * runtime has no `WebSocket` (Node 18 and 20), constructing one throws, the socket fails before it
+ * opens (a network that blocks sockets), or it has not opened and been caught up within
+ * {@link LIVE_SOCKET_OPEN_TIMEOUT_MS} (a network that holds it) — it polls the edge instead, from the
+ * same cursor, about every {@link VISITOR_POLL_INTERVAL_MS}, and tries a socket again about once a
+ * minute. Both carry one cursor space, so a switch either way loses nothing.
+ *
+ * **Where it starts.** Without `since`, the edge answers the dataset's current position before
+ * anything else — the socket's `feed.opened`, or the first poll's answer — and the subscription hands
+ * it to `reached`. That call is the position, with no request of its own for it: a read sent after it
+ * is answered at or after the position, and every change after it is delivered here, so a publish the
+ * read did not see is announced (REL-1513). The edge counts the subscription as one live connection,
+ * whichever way in it took (`INV-LV-LIVE-IS-METERED`).
  *
  * **It ends only when its signal aborts, and throws every other end** — a socket closed by a refusal
  * or a deploy, a refused poll, a keepalive nobody answered — as a `LiveEdgeError` saying what to do
@@ -3005,11 +3025,51 @@ interface ChangesHeadOptions {
  * receives never learns otherwise that a network change dropped its connection.
  */
 declare const LIVE_KEEPALIVE_INTERVAL_MS = 30000;
+/**
+ * How long a socket has to open and be caught up — the feed's `feed.opened` — before the subscription
+ * stops waiting on it, closes it and polls instead, as it does for a socket that fails before it opens
+ * (REL-1513).
+ *
+ * The poll interval, because that is what a socket is for: telling the page sooner than a poll would.
+ * A poll is answered at once and polled again within this interval, so a socket that has not caught
+ * up by then has already served the page worse than polling would have. It is well past a healthy
+ * open — the door's checks and one ledger read at the edge — and half the keepalive's verdict on an
+ * open socket that has gone quiet ({@link LIVE_KEEPALIVE_INTERVAL_MS}, twice). It bounds how long
+ * `<RelyIOProvider live>`'s first reads wait for a position on a network that neither opens a socket
+ * nor refuses one — a proxy that holds the upgrade — which without it they would wait on for as long
+ * as the page is open.
+ */
+declare const LIVE_SOCKET_OPEN_TIMEOUT_MS = 15000;
 interface LiveChangesOptions {
     /**
      * A change's cursor from an earlier subscription. Omitted, the edge answers the dataset's current
-     * position first and replays nothing; fetch what you show **after** that position arrives — with
-     * `followChanges()`, after `onState` reports `following` — so nothing lands in between unseen.
+     * position first and replays nothing, and the subscription hands that position to `reached` before
+     * anything after it. Read what you show **after** that first call — a read sent before it, from a
+     * subscription opened afterwards without `since`, leaves a publish between the two that neither
+     * sees (REL-1513). With `followChanges()`, which hands the source its own `reached`, call both —
+     * and let the read go if the loop fails first, so content never waits on a feed that is down:
+     *
+     * ```ts
+     * let positioned!: () => void
+     * const position = new Promise<void>(resolve => (positioned = resolve))
+     * const following = followChanges(
+     *   from =>
+     *     relyio.liveChanges({
+     *       ...from,
+     *       ids: [id],
+     *       reached: cursor => {
+     *         from.reached(cursor)
+     *         positioned()
+     *       },
+     *     }),
+     *   { signal, onChange, onResync, onState: state => state.kind !== 'following' && positioned() },
+     * )
+     * await position
+     * const post = await relyio.content('post').findById(id).execute()
+     * ```
+     *
+     * The wait is bounded: a socket that has not opened and been told its position within
+     * {@link LIVE_SOCKET_OPEN_TIMEOUT_MS} is given up for a poll, answered at once.
      */
     since?: string;
     /** Content types to keep. Omitted keeps every type; an empty list is refused. At most 50. */
@@ -3036,7 +3096,8 @@ interface LiveChangesOptions {
     /**
      * Called with a position reached without a change to carry it. `followChanges()` passes it so a
      * connection dropped before its first change reconnects from there; see
-     * `ChangeSourceOptions.reached`.
+     * `ChangeSourceOptions.reached`. Without `since`, its first call is the position the subscription
+     * starts from (see `since`).
      */
     reached?: (cursor: string) => void;
 }
@@ -3292,9 +3353,14 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * (`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`).
+     * open — the runtime has none, the network refuses it, or it has not opened and been told its
+     * position within `LIVE_SOCKET_OPEN_TIMEOUT_MS` — 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`).
+     *
+     * Without `since` it starts at the dataset's current position, which it hands `reached` before
+     * anything after it: read what you show after that call, and a publish your read did not see is
+     * one this subscription announces (see `LiveChangesOptions.since`).
      *
      * 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`
@@ -3599,4 +3665,4 @@ declare function createClient<TSchema extends AnySchemaDefinition>(config: Typed
  */
 type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
 
-export { type BatchOperationResult as $, type ActiveSandbox as A, type SearchResultItem as B, type Change as C, type SearchHitMetadata as D, type ExtendedQueryResult as E, type FeedChange as F, type SearchResponse as G, HttpClient as H, type AutocompleteSuggestion as I, type AutocompleteResponse as J, type SimilarResult as K, LIVE_KEEPALIVE_INTERVAL_MS as L, type SimilarResponse as M, type SearchFilter as N, type SearchFields as O, type Project as P, type SearchSort as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type SearchTypeName as U, type SearchEntry as V, BatchClient as W, BatchBuilder as X, type BatchMethod as Y, type BatchOperation as Z, type BatchOptions as _, ChangesExpiredError as a, type BatchSummary as a0, type BatchResponse as a1, AdhocQueryClient as a2, AdhocQueryBuilder as a3, type FetchBlock as a4, type AggregateBlock as a5, type AggregateMetric as a6, type SearchBlock as a7, type FilterValue as a8, type FullTextConfig as a9, type MultipartPart as aA, type MultipartTarget as aB, type UploadProgress as aC, ResourceNotFoundError as aD, ResourceConflictError as aE, ResourceExpiredError as aF, isResourceNotFound as aG, type FileErrorCode as aH, type FileUploadErrorCode as aI, FileUploadError as aJ, FileValidationError as aK, type FileValidationConstraints as aL, validateFile as aM, type AdhocQueryDefinition as aa, type AdhocQueryOptions as ab, type QueryMetadata as ac, type AdhocQueryResult as ad, AssetClient as ae, AssetFileBuilder as af, AssetUploadBuilder as ag, isAssetEntry as ah, type AssetVisibility as ai, type FileStatus as aj, type FileBackend as ak, type AssetFileBlock as al, type AssetFileExtracted as am, type FileStatusResult as an, type AssetUrls as ao, type AssetEntryResponse as ap, type PopulatedAssetReference as aq, type PresignInput as ar, type PresignResult as as, type ConfirmInput as at, type ConfirmResult as au, type ResolveUrlInput as av, type ResolveUrlResult as aw, type CreateAssetOptions as ax, type WaitUntilReadyOptions as ay, type MultipartCreateResult as az, type ChangesExpiredReason as b, createClient as c, type TypedClientConfig as d, type ClientSchema as e, type RegisteredSchema as f, type SendOptions as g, entityTagOf as h, type ConditionalWriteOptions as i, type RetryableWriteOptions as j, type ChangesHeadOptions as k, type ChangesOptions as l, type LiveChangesOptions as m, ContentClient as n, SingletonClient as o, SettingsClient as p, ContentQueryBuilder as q, ContentByIdBuilder as r, type ChildrenOptions as s, type SingletonFetchOptions as t, type SettingsFetchOptions as u, SearchClient as v, SearchBuilder as w, AutocompleteBuilder as x, SimilarBuilder as y, type SearchMode as z };
+export { type BatchOptions as $, type ActiveSandbox as A, type SearchMode as B, type Change as C, type SearchResultItem as D, type ExtendedQueryResult as E, type FeedChange as F, type SearchHitMetadata as G, HttpClient as H, type SearchResponse as I, type AutocompleteSuggestion as J, type AutocompleteResponse as K, LIVE_KEEPALIVE_INTERVAL_MS as L, type SimilarResult as M, type SimilarResponse as N, type SearchFilter as O, type Project as P, type SearchFields as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type SearchSort as U, type SearchTypeName as V, type SearchEntry as W, BatchClient as X, BatchBuilder as Y, type BatchMethod as Z, type BatchOperation as _, ChangesExpiredError as a, type BatchOperationResult as a0, type BatchSummary as a1, type BatchResponse as a2, AdhocQueryClient as a3, AdhocQueryBuilder as a4, type FetchBlock as a5, type AggregateBlock as a6, type AggregateMetric as a7, type SearchBlock as a8, type FilterValue as a9, type MultipartCreateResult as aA, type MultipartPart as aB, type MultipartTarget as aC, type UploadProgress as aD, ResourceNotFoundError as aE, ResourceConflictError as aF, ResourceExpiredError as aG, isResourceNotFound as aH, type FileErrorCode as aI, type FileUploadErrorCode as aJ, FileUploadError as aK, FileValidationError as aL, type FileValidationConstraints as aM, validateFile as aN, type FullTextConfig as aa, type AdhocQueryDefinition as ab, type AdhocQueryOptions as ac, type QueryMetadata as ad, type AdhocQueryResult as ae, AssetClient as af, AssetFileBuilder as ag, AssetUploadBuilder as ah, isAssetEntry as ai, type AssetVisibility as aj, type FileStatus as ak, type FileBackend as al, type AssetFileBlock as am, type AssetFileExtracted as an, type FileStatusResult as ao, type AssetUrls as ap, type AssetEntryResponse as aq, type PopulatedAssetReference as ar, type PresignInput as as, type PresignResult as at, type ConfirmInput as au, type ConfirmResult as av, type ResolveUrlInput as aw, type ResolveUrlResult as ax, type CreateAssetOptions as ay, type WaitUntilReadyOptions as az, type ChangesExpiredReason as b, createClient as c, type TypedClientConfig as d, type ClientSchema as e, type RegisteredSchema as f, type SendOptions as g, entityTagOf as h, type ConditionalWriteOptions as i, type RetryableWriteOptions as j, type ChangesHeadOptions as k, type ChangesOptions as l, LIVE_SOCKET_OPEN_TIMEOUT_MS as m, type LiveChangesOptions as n, ContentClient as o, SingletonClient as p, SettingsClient as q, ContentQueryBuilder as r, ContentByIdBuilder as s, type ChildrenOptions as t, type SingletonFetchOptions as u, type SettingsFetchOptions as v, SearchClient as w, SearchBuilder as x, AutocompleteBuilder as y, SimilarBuilder as z };