@collective-intelligence/external-apps-client-sdk 0.1.24 → 0.1.26

package/README.md

@@ -315,8 +315,16 @@ const unsubscribe = realtime.subscribe(
   the user who received them: store and resend them unchanged, never parse or
   order them. An id the server cannot read answers `reset`.
   `reset` means the gap was too old to replay: refetch every subscribed topic.
+  A connection that opens without an event id, the first one included, starts
+  at the present: a change between your initial queries and the open would not
+  arrive. So the client resyncs: it calls `onReset` once that connection
+  opens, at the next delivery. Expect one extra refetch per page load.
   `onReset` runs at the next delivery instead of its pending changes, so the
-  tabs that reset together refetch apart. `onAccessChanged` runs at once.
+  tabs that reset together refetch apart; a server `reset` and a resync in one
+  delivery call it once. Pass `onReset` for gap-free delivery: without it the
+  client cannot recover from a reset or a cursorless open, so it delivers the
+  pending changes as they are and a change can be lost. `onAccessChanged` runs
+  at once.
 - A connection without a ping for 45 seconds is reopened. Failures, 429 and 503
   back off with full jitter between 1 and 30 seconds; `Retry-After` and the
   server's `retry:` set the lower bound. The server ends each connection after

package/dist/index.d.ts

@@ -1011,8 +1011,11 @@ type RealtimeClientOptions = Readonly<{
   /** A number in `[0, 1)` for the backoff jitter. */
   random?: () => number;
   /**
-   * The server could not replay the missed changes: refetch every subscribed
-   * topic. It arrives at the next delivery and replaces its pending changes.
+   * Refetch every subscribed topic: the server could not replay the missed
+   * changes, or a stream opened without a last event id, so changes before it
+   * opened did not arrive. It arrives at the next delivery and replaces its
+   * pending changes. Without it, the client cannot recover from such a gap and
+   * delivers the pending changes instead.
    */
   onReset?: () => void;
   /** The user's access changed: re-check the session and its capabilities. */
@@ -1040,9 +1043,10 @@ type RealtimeClient = Readonly<{
  * One realtime connection per tab for every subscribed topic. The connection
  * opens while the page is visible and a topic has a listener; a topic set
  * change reconnects after a short debounce, and every reconnect resumes after
- * the last received event. Changes and resets reach the listeners in one
- * delivery per tab, 250 to 1000 ms after the first of them: a burst of
- * changes refetches once, and tabs that reset together refetch apart.
+ * the last received event; a stream that opens without one resets instead.
+ * Changes and resets reach the listeners in one delivery per tab, 250 to
+ * 1000 ms after the first of them: a burst of changes refetches once, and
+ * tabs that reset together refetch apart.
  * Connection decisions live in the pure state machine (`./machine`); this
  * client only runs its commands.
  */

package/dist/index.js

@@ -1038,7 +1038,7 @@ const linkTransition = (state, event) => {
 		case "ticketFailed":
 		case "streamEnded": return retry(state, event.retryMilliseconds);
 		case "streamOpened": return {
-			commands: [watchdog(link.id)],
+			commands: state.lastEventId === void 0 ? [watchdog(link.id), { type: "resync" }] : [watchdog(link.id)],
 			state: {
 				...shared(state),
 				link,
@@ -1117,9 +1117,10 @@ const defaultTimers = { schedule: (callback, milliseconds) => {
 * One realtime connection per tab for every subscribed topic. The connection
 * opens while the page is visible and a topic has a listener; a topic set
 * change reconnects after a short debounce, and every reconnect resumes after
-* the last received event. Changes and resets reach the listeners in one
-* delivery per tab, 250 to 1000 ms after the first of them: a burst of
-* changes refetches once, and tabs that reset together refetch apart.
+* the last received event; a stream that opens without one resets instead.
+* Changes and resets reach the listeners in one delivery per tab, 250 to
+* 1000 ms after the first of them: a burst of changes refetches once, and
+* tabs that reset together refetch apart.
 * Connection decisions live in the pure state machine (`./machine`); this
 * client only runs its commands.
 */
@@ -1174,6 +1175,15 @@ const createRealtimeClient = (options) => {
 	const scheduleDelivery = () => {
 		cancelDelivery ??= timers.schedule(deliver, changeWindowMilliseconds + Math.floor(random() * changeJitterMilliseconds));
 	};
+	/**
+	* Replaces the pending changes with one `onReset` at the next delivery.
+	* Without `onReset` no refetch covers them, so they stay.
+	*/
+	const resync = () => {
+		if (options.onReset === void 0) return;
+		resetPending = true;
+		scheduleDelivery();
+	};
 	const route = (change) => {
 		const key = realtimeTopicKey(change.topic);
 		if (!registrations.has(key)) return;
@@ -1240,10 +1250,8 @@ const createRealtimeClient = (options) => {
 			if (event.type === "change") {
 				const change = parseRealtimeChange(event.data);
 				if (change !== void 0) route(change);
-			} else if (event.type === "reset") {
-				resetPending = true;
-				scheduleDelivery();
-			} else if (event.type === "access-changed") options.onAccessChanged?.();
+			} else if (event.type === "reset") resync();
+			else if (event.type === "access-changed") options.onAccessChanged?.();
 		},
 		onOpen: () => {
 			dispatch({
@@ -1305,6 +1313,9 @@ const createRealtimeClient = (options) => {
 				resources?.close?.();
 				return;
 			}
+			case "resync":
+				resync();
+				return;
 		}
 	};
 	const topicsChanged = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collective-intelligence/external-apps-client-sdk",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Framework-neutral client for Collective Intelligence external applications.",
   "type": "module",
   "sideEffects": false,
@@ -52,5 +52,5 @@
     "typescript": "5.9.3",
     "ultracite": "7.10.7"
   },
-  "gitHead": "5d48a1654c4bd7728d61f97818033d2685d99210"
+  "gitHead": "8200af5951cee11bdd23c59aba0709412aa8ea62"
 }