@collective-intelligence/external-apps-client-sdk 0.1.18 → 0.1.21

package/README.md

@@ -271,6 +271,59 @@ not presign, with `invalid_request` (`details.reason` `not_a_file_field` or
 `invalid_request` with `details.field` and `details.reason`; a File field a
 connector writes answers `conflict` with `details.field`.
 
+## Realtime topics
+
+`createRealtimeClient` keeps one realtime connection per tab for every
+subscribed Realtime Topic. A topic is the records of one entity schema,
+optionally filtered by one data path: `{ schema, filter?: { field, eq } }`.
+Events carry ids only; refetch the records through your own data routes.
+
+```ts
+import { createRealtimeClient } from "@collective-intelligence/external-apps-client-sdk"
+
+const realtime = createRealtimeClient({
+  ticketUrl: "/api/realtime/ticket",
+  document,
+  window,
+  onReset: () => queryClient.invalidateQueries(),
+  onAccessChanged: () => session.refresh()
+})
+
+const unsubscribe = realtime.subscribe(
+  { schema: "crm.lead", filter: { field: "ownerId", eq: userId } },
+  (changes) => invalidateLeads(changes.map((change) => change.id))
+)
+```
+
+- Subscriptions to equal topics share one registration; the connection carries
+  the union of the registered topics and routes each `change` by its topic.
+- Listeners receive changes in batches. The first change after a delivery
+  schedules the next delivery 250 ms plus a random 0 to 750 ms later; later
+  changes join it without delaying it. A batch holds the latest change of each
+  record, in order of last arrival, and goes to the topic's listeners at
+  delivery time. A topic that loses its last listener drops its pending
+  changes; `close()` drops every pending change.
+- Pass the page `document` and `window` in a browser. Without `document` the
+  client treats the page as always visible; without `window` it ignores
+  `pagehide`.
+- The connection opens only while the page is visible and a topic has a
+  listener. It closes on `visibilitychange: hidden` and `pagehide`, and when the
+  last listener unsubscribes. A topic set change reconnects after 300 ms.
+- Each connection uses a new ticket from `ticketUrl` (the server SDK BFF route)
+  and resumes after the last received event id, so missed changes replay.
+  `reset` means the gap was too old to replay: refetch every subscribed topic.
+  `onReset` runs at the next delivery instead of its pending changes, so the
+  tabs that reset together refetch apart. `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
+  its lifetime; the client reconnects with a new ticket.
+- The default stream reader uses `fetch`, because `EventSource` does not expose
+  the server's ping comments or a refused stream's status. Inject
+  `eventSourceFactory`, `document`, `window`, `timers` and `random` to test.
+- `getState()` reports `status`, `connections` (0 or 1), `topics` and
+  `lastEventId`; `close()` ends the connection and the page listeners.
+
 ## Workspace development
 
 The repository's [Effect demo](../../../demo/external-app-effect/README.md)

package/dist/index.d.ts

@@ -937,4 +937,114 @@ type DirectTransportOptions = Readonly<{
   tenantUrl: string;
 }>;
 declare const createDirectTransport: <Operations extends ClientOperationMap>(options: DirectTransportOptions) => TypedOperationExecutor<Operations>;
-export { type CiError, type CiErrorCode, type CiResult, type CiRunCancellation, type CiStreamEvent, type CiStreamPage, type ClientDomains, type ClientFetch, type ClientOperationDefinition, type ClientOperationId, type ClientOperationInput, type ClientOperationMap, type ClientOperationOutput, type ClientSdkClient, type ClientSdkEntrypoint, DEFAULT_FOLLOW_RUN_DEADLINE_MS, type DelegatedApplicationRuntime, type DelegatedApplicationRuntimeOptions, type DelegatedRuntimeState, type DirectTransportOptions, type EntityClient, type EntityCreateInput, type EntityDeleteInput, type EntityFileFieldWrite, type EntityFileValue, type EntityFileWrite, type EntityHttpDestination, type EntityHttpTransportOptions, type EntityListQuery, type EntityMemberValue, type EntityOperation, type EntityOperationResult, type EntityPage, type EntityProtocol, type EntityReadLimitDetails, type EntityRequest, type EntityTransport, type EntityUpdateInput, type EntityUploadInput, type EntityUploadSlot, type FederatedAuth, FederatedAuthError, type FederatedAuthErrorCode, type FederatedAuthOptions, type FederatedAuthState, type FederatedSessionIdentity, type FixedWorkflowClient, type FixedWorkflowClientOptions, type FollowRunOptions, type FollowRunSource, type IdempotencyKey, type JsonObject, type JsonValue, type KnowledgeQuery, type OperationExecutionOptions, type OperationRequest, type OperationSuccess, type OrganizationClient, type PortableResourceSchema, type ProxyAuthentication, type ProxyTransportOptions, type QueryFilter, type ResourceCapabilities, type ResourceClient, type ResourceCreateInput, type ResourceCreateRequest, type ResourceCursor, type ResourceDefinition, type ResourceError, type ResourceErrorCode, type ResourceFilter, type ResourceGetRequest, type ResourceId, type ResourceIdentityField, type ResourceJsonValue, type ResourceLifecycleInput, type ResourceLifecycleRequest, type ResourceListQuery, type ResourceListRequest, type ResourceListResult, type ResourceMutationInput, type ResourcePagination, type ResourcePaginationMode, type ResourceRecord, type ResourceRecordId, type ResourceRequestOptions, type ResourceResult, type ResourceRevision, type ResourceSort, type ResourceTransport, type ResourceTransportRequest, type ResourceUpdateRequest, type SearchQuery, type ServerSessionAuthOptions, type TypedOperationExecutor, type WorkflowInvokeTarget, clientOperationIds, clientSdkProtocolVersion, createClient, createDelegatedApplicationRuntime, createDirectTransport, createEntityHttpTransport, createEntityProtocol, createFederatedAuth, createFixedWorkflowClient, createProxyTransport, createResourceClient, createServerSessionAuth, followRun, isClientOperationId, isEntityReadLimitError, nextStreamCursor };
+/** One dispatched Server-Sent Event. */
+type RealtimeStreamEvent = Readonly<{
+  type: string;
+  data: string;
+  /** The `id:` of this event, when it carried one. */
+  id: string | undefined;
+}>;
+/**
+ * How a stream ended: `status` when the server refused it, and the
+ * reconnect delay the server asked for with `retry:` or `Retry-After`.
+ */
+type RealtimeStreamEnd = Readonly<{
+  status: number | undefined;
+  retryMilliseconds: number | undefined;
+}>;
+type RealtimeStreamHandlers = Readonly<{
+  onOpen: () => void;
+  onEvent: (event: RealtimeStreamEvent) => void;
+  /** A comment or an `id:`-only frame: the server is alive. */
+  onPing: (id?: string) => void;
+  /** Called once, unless the stream was closed by the client. */
+  onEnd: (end: RealtimeStreamEnd) => void;
+}>;
+type RealtimeEventSource = Readonly<{
+  close: () => void;
+}>;
+/** Opens one event stream; `close` stops it without calling `onEnd`. */
+type RealtimeEventSourceFactory = (url: string, handlers: RealtimeStreamHandlers) => RealtimeEventSource;
+/** Reads `text/event-stream` with `fetch`, so pings and refusals are visible. */
+declare const createFetchEventSourceFactory: (fetch: ClientFetch) => RealtimeEventSourceFactory;
+/** One equality filter on a dotted data path of a topic's records. */
+type RealtimeTopicFilter = Readonly<{
+  field: string;
+  eq: string | number | boolean | null;
+}>;
+/** The records of one entity schema, named by FQN or id, optionally filtered. */
+type RealtimeTopic = Readonly<{
+  schema: string;
+  filter?: RealtimeTopicFilter;
+}>;
+/** A record of a subscribed topic changed; refetch it, the event carries ids only. */
+type RealtimeChange = Readonly<{
+  id: string;
+  op: "create" | "update" | "delete";
+  revision: string;
+  topic: RealtimeTopic;
+}>;
+/** One stable key per topic, whatever the key order of the object. */
+declare const realtimeTopicKey: ({ filter, schema }: RealtimeTopic) => string;
+/** Schedules `callback` after `milliseconds`; the result cancels it. */
+type RealtimeTimers = Readonly<{
+  schedule: (callback: () => void, milliseconds: number) => () => void;
+}>;
+type PageEvents = Readonly<{
+  addEventListener: (type: string, listener: () => void) => void;
+  removeEventListener: (type: string, listener: () => void) => void;
+}>;
+type RealtimeDocument = PageEvents & Readonly<{
+  visibilityState: DocumentVisibilityState;
+}>;
+type RealtimeWindow = PageEvents;
+type RealtimeClientOptions = Readonly<{
+  /** The application's ticket route, e.g. `/api/realtime/ticket`. */
+  ticketUrl: string;
+  fetch?: ClientFetch;
+  eventSourceFactory?: RealtimeEventSourceFactory;
+  /** The page document; without it the page counts as always visible. */
+  document?: RealtimeDocument;
+  /** The page window; without it `pagehide`/`pageshow` are ignored. */
+  window?: RealtimeWindow;
+  timers?: RealtimeTimers;
+  /** 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.
+   */
+  onReset?: () => void;
+  /** The user's access changed: re-check the session and its capabilities. */
+  onAccessChanged?: () => void;
+}>;
+type RealtimeClientStatus = "idle" | "connecting" | "open" | "backoff";
+type RealtimeClientState = Readonly<{
+  status: RealtimeClientStatus;
+  /** Open or opening connections of this client: 0 or 1. */
+  connections: number;
+  topics: readonly RealtimeTopic[];
+  lastEventId: string | undefined;
+}>;
+type RealtimeClient = Readonly<{
+  /**
+   * Listens to one topic; the result stops listening. Changes arrive in
+   * batches, one change per record: the latest, in order of arrival.
+   */
+  subscribe: (topic: RealtimeTopic, onChanges: (changes: readonly RealtimeChange[]) => void) => () => void;
+  getState: () => RealtimeClientState;
+  /** Closes the connection and stops reacting to the page. */
+  close: () => void;
+}>;
+/**
+ * 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.
+ * Connection decisions live in the pure state machine (`./machine`); this
+ * client only runs its commands.
+ */
+declare const createRealtimeClient: (options: RealtimeClientOptions) => RealtimeClient;
+export { type CiError, type CiErrorCode, type CiResult, type CiRunCancellation, type CiStreamEvent, type CiStreamPage, type ClientDomains, type ClientFetch, type ClientOperationDefinition, type ClientOperationId, type ClientOperationInput, type ClientOperationMap, type ClientOperationOutput, type ClientSdkClient, type ClientSdkEntrypoint, DEFAULT_FOLLOW_RUN_DEADLINE_MS, type DelegatedApplicationRuntime, type DelegatedApplicationRuntimeOptions, type DelegatedRuntimeState, type DirectTransportOptions, type EntityClient, type EntityCreateInput, type EntityDeleteInput, type EntityFileFieldWrite, type EntityFileValue, type EntityFileWrite, type EntityHttpDestination, type EntityHttpTransportOptions, type EntityListQuery, type EntityMemberValue, type EntityOperation, type EntityOperationResult, type EntityPage, type EntityProtocol, type EntityReadLimitDetails, type EntityRequest, type EntityTransport, type EntityUpdateInput, type EntityUploadInput, type EntityUploadSlot, type FederatedAuth, FederatedAuthError, type FederatedAuthErrorCode, type FederatedAuthOptions, type FederatedAuthState, type FederatedSessionIdentity, type FixedWorkflowClient, type FixedWorkflowClientOptions, type FollowRunOptions, type FollowRunSource, type IdempotencyKey, type JsonObject, type JsonValue, type KnowledgeQuery, type OperationExecutionOptions, type OperationRequest, type OperationSuccess, type OrganizationClient, type PortableResourceSchema, type ProxyAuthentication, type ProxyTransportOptions, type QueryFilter, type RealtimeChange, type RealtimeClient, type RealtimeClientOptions, type RealtimeClientState, type RealtimeClientStatus, type RealtimeDocument, type RealtimeEventSource, type RealtimeEventSourceFactory, type RealtimeStreamEnd, type RealtimeStreamEvent, type RealtimeStreamHandlers, type RealtimeTimers, type RealtimeTopic, type RealtimeTopicFilter, type RealtimeWindow, type ResourceCapabilities, type ResourceClient, type ResourceCreateInput, type ResourceCreateRequest, type ResourceCursor, type ResourceDefinition, type ResourceError, type ResourceErrorCode, type ResourceFilter, type ResourceGetRequest, type ResourceId, type ResourceIdentityField, type ResourceJsonValue, type ResourceLifecycleInput, type ResourceLifecycleRequest, type ResourceListQuery, type ResourceListRequest, type ResourceListResult, type ResourceMutationInput, type ResourcePagination, type ResourcePaginationMode, type ResourceRecord, type ResourceRecordId, type ResourceRequestOptions, type ResourceResult, type ResourceRevision, type ResourceSort, type ResourceTransport, type ResourceTransportRequest, type ResourceUpdateRequest, type SearchQuery, type ServerSessionAuthOptions, type TypedOperationExecutor, type WorkflowInvokeTarget, clientOperationIds, clientSdkProtocolVersion, createClient, createDelegatedApplicationRuntime, createDirectTransport, createEntityHttpTransport, createEntityProtocol, createFederatedAuth, createFetchEventSourceFactory, createFixedWorkflowClient, createProxyTransport, createRealtimeClient, createResourceClient, createServerSessionAuth, followRun, isClientOperationId, isEntityReadLimitError, nextStreamCursor, realtimeTopicKey };

package/dist/index.js

@@ -44,10 +44,10 @@ const normalizedReturnTarget = (value, applicationOrigin) => {
 	if (target.origin !== applicationOrigin) throw new FederatedAuthError("invalid_return_target", "The return target must share the callback origin");
 	return target.href;
 };
-const isRecord = (value) => value !== null && Object(value) === value && !Array.isArray(value);
+const isRecord$1 = (value) => value !== null && Object(value) === value && !Array.isArray(value);
 const parseTransaction = (serialized) => {
 	const value = JSON.parse(serialized);
-	if (!isRecord(value) || typeof value.expiresAt !== "number" || typeof value.returnTo !== "string" || typeof value.state !== "string" || typeof value.verifier !== "string") throw new FederatedAuthError("invalid_state", "Invalid login transaction");
+	if (!isRecord$1(value) || typeof value.expiresAt !== "number" || typeof value.returnTo !== "string" || typeof value.state !== "string" || typeof value.verifier !== "string") throw new FederatedAuthError("invalid_state", "Invalid login transaction");
 	return {
 		expiresAt: value.expiresAt,
 		returnTo: value.returnTo,
@@ -432,7 +432,7 @@ const eventKind = (event) => {
 	const record = asRecord$1(event);
 	return record === null ? null : readString(record, "kind");
 };
-const idle = async (ms, sleep, signal) => {
+const idle$1 = async (ms, sleep, signal) => {
 	if (ms <= 0 || signal?.aborted === true) return;
 	if (sleep !== void 0) {
 		await sleep(ms);
@@ -502,7 +502,7 @@ const followRun = async (runs, options) => {
 		if (status !== null && terminalSnapshotStatuses.has(status)) return await readRemainingPages(runs, options, page.value);
 		if (page.value.nextCursor !== null) afterCursor = page.value.nextCursor;
 		emptyPolls = page.value.events.length === 0 ? emptyPolls + 1 : 0;
-		await idle(Math.min(idleMs * 2 ** emptyPolls, maxIdleMs), options.sleep, options.signal);
+		await idle$1(Math.min(idleMs * 2 ** emptyPolls, maxIdleMs), options.sleep, options.signal);
 	}
 	throw new Error("Run did not finish");
 };
@@ -739,4 +739,637 @@ const createDirectTransport = (options) => {
 		origin: tenantUrl
 	});
 };
-export { DEFAULT_FOLLOW_RUN_DEADLINE_MS, FederatedAuthError, clientOperationIds, clientSdkProtocolVersion, createClient, createDelegatedApplicationRuntime, createDirectTransport, createEntityHttpTransport, createEntityProtocol, createFederatedAuth, createFixedWorkflowClient, createProxyTransport, createResourceClient, createServerSessionAuth, followRun, isClientOperationId, isEntityReadLimitError, nextStreamCursor };
+const emptyBlock = () => ({
+	comment: false,
+	data: [],
+	id: void 0,
+	type: ""
+});
+/**
+* A Server-Sent Events parser that, unlike `EventSource`, reports comments:
+* the server's pings are comments, and the client's watchdog needs them.
+*/
+const createEventStreamParser = (handlers) => {
+	let buffer = "";
+	let block = emptyBlock();
+	let retry;
+	const dispatch = () => {
+		const ended = block;
+		block = emptyBlock();
+		if (ended.data.length > 0) handlers.onEvent({
+			data: ended.data.join("\n"),
+			id: ended.id,
+			type: ended.type === "" ? "message" : ended.type
+		});
+		else if (ended.comment || ended.id !== void 0) handlers.onPing(ended.id);
+	};
+	const line = (text) => {
+		if (text === "") {
+			dispatch();
+			return;
+		}
+		if (text.startsWith(":")) {
+			block.comment = true;
+			return;
+		}
+		const colon = text.indexOf(":");
+		const field = colon === -1 ? text : text.slice(0, colon);
+		const raw = colon === -1 ? "" : text.slice(colon + 1);
+		const value = raw.startsWith(" ") ? raw.slice(1) : raw;
+		if (field === "data") block.data.push(value);
+		else if (field === "event") block.type = value;
+		else if (field === "id" && !value.includes("\0")) block.id = value;
+		else if (field === "retry" && /^\d+$/u.test(value)) retry = Number(value);
+	};
+	return {
+		push: (chunk) => {
+			buffer += chunk;
+			const lines = buffer.split("\n");
+			buffer = lines.pop() ?? "";
+			for (const text of lines) line(text.endsWith("\r") ? text.slice(0, -1) : text);
+		},
+		/** The last `retry:` the stream sent, in milliseconds. */
+		retry: () => retry
+	};
+};
+/** `Retry-After` in milliseconds, seconds form only. */
+const retryAfterMilliseconds = (response) => {
+	const value = response.headers.get("retry-after");
+	return value !== null && /^\d+$/u.test(value) ? Number(value) * 1e3 : void 0;
+};
+/** Reads `text/event-stream` with `fetch`, so pings and refusals are visible. */
+const createFetchEventSourceFactory = (fetch) => (url, handlers) => {
+	const abort = new AbortController();
+	const live = () => !abort.signal.aborted;
+	const parser = createEventStreamParser({
+		onEvent: (event) => {
+			if (live()) handlers.onEvent(event);
+		},
+		onPing: (id) => {
+			if (live()) handlers.onPing(id);
+		}
+	});
+	const read = async () => {
+		try {
+			const response = await fetch(url, {
+				cache: "no-store",
+				headers: { accept: "text/event-stream" },
+				signal: abort.signal
+			});
+			if (!response.ok || response.body === null) {
+				parser.push(`${await response.text()}\n\n`);
+				if (live()) handlers.onEnd({
+					retryMilliseconds: retryAfterMilliseconds(response) ?? parser.retry(),
+					status: response.status
+				});
+				return;
+			}
+			if (live()) handlers.onOpen();
+			const decoder = new TextDecoder();
+			const reader = response.body.getReader();
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				parser.push(decoder.decode(value, { stream: true }));
+			}
+		} catch {}
+		if (live()) handlers.onEnd({
+			retryMilliseconds: parser.retry(),
+			status: void 0
+		});
+	};
+	read();
+	return { close: () => abort.abort() };
+};
+const topicSetDebounceMilliseconds = 300;
+const pingTimeoutMilliseconds = 45e3;
+const backoffBaseMilliseconds = 1e3;
+const backoffCapMilliseconds = 3e4;
+const initialMachineState = (documentVisible) => ({
+	attempt: 0,
+	documentVisible,
+	lastEventId: void 0,
+	nextLinkId: 1,
+	pageShown: true,
+	phase: "idle",
+	topics: []
+});
+/** Full jitter over an exponential cap; a server hint is a lower bound. */
+const backoffDelay = (attempt, retryMilliseconds, jitter) => {
+	const cap = Math.min(backoffCapMilliseconds, backoffBaseMilliseconds * 2 ** attempt);
+	return Math.max(retryMilliseconds ?? 0, Math.floor(jitter * cap));
+};
+const currentLink = (state) => "link" in state ? state.link : void 0;
+const shared = (state) => ({
+	attempt: state.attempt,
+	documentVisible: state.documentVisible,
+	lastEventId: state.lastEventId,
+	nextLinkId: state.nextLinkId,
+	pageShown: state.pageShown,
+	topics: state.topics
+});
+const visible = (state) => state.documentVisible && state.pageShown;
+const wanted = (state) => state.phase !== "closed" && visible(state) && state.topics.length > 0;
+const sameTopics = (left, right) => left.length === right.length && left.every((key) => right.includes(key));
+const unchanged = (state) => ({
+	commands: [],
+	state
+});
+/** Commands that end the current link, if any. */
+const unlink = (state) => {
+	const link = currentLink(state);
+	return link === void 0 ? [] : [{
+		linkId: link.id,
+		type: "disconnect"
+	}, {
+		timer: "watchdog",
+		type: "cancel"
+	}];
+};
+const watchdog = (linkId) => ({
+	event: {
+		linkId,
+		type: "watchdogElapsed"
+	},
+	milliseconds: pingTimeoutMilliseconds,
+	timer: "watchdog",
+	type: "schedule"
+});
+const idle = (state) => ({
+	...shared(state),
+	phase: state.phase === "closed" ? "closed" : "idle"
+});
+const stop = (state) => ({
+	commands: [
+		{
+			timer: "debounce",
+			type: "cancel"
+		},
+		{
+			timer: "backoff",
+			type: "cancel"
+		},
+		...unlink(state)
+	],
+	state: idle(state)
+});
+const connect = (state) => {
+	if (!wanted(state)) return {
+		commands: unlink(state),
+		state: idle(state)
+	};
+	const link = {
+		id: state.nextLinkId,
+		topics: state.topics
+	};
+	return {
+		commands: [
+			...unlink(state),
+			watchdog(link.id),
+			{
+				link,
+				type: "mint"
+			}
+		],
+		state: {
+			...shared(state),
+			link,
+			nextLinkId: state.nextLinkId + 1,
+			phase: "connecting"
+		}
+	};
+};
+const retry = (state, retryMilliseconds) => {
+	if (!wanted(state)) return {
+		commands: unlink(state),
+		state: idle(state)
+	};
+	return {
+		commands: [...unlink(state), {
+			attempt: state.attempt,
+			retryMilliseconds,
+			type: "backoff"
+		}],
+		state: {
+			...shared(state),
+			attempt: state.attempt + 1,
+			phase: "backoff"
+		}
+	};
+};
+/** Brings the connection in line with the page and the topic set. */
+const sync = (state) => {
+	if (!wanted(state)) return stop(state);
+	const link = currentLink(state);
+	if (state.phase === "backoff" || link !== void 0 && sameTopics(link.topics, state.topics)) return {
+		commands: [{
+			timer: "debounce",
+			type: "cancel"
+		}],
+		state
+	};
+	return connect(state);
+};
+const reactToPage = (state) => {
+	if (!visible(state)) return stop(state);
+	return currentLink(state) === void 0 && state.phase !== "backoff" ? sync(state) : unchanged(state);
+};
+const streamUrlAfter = (streamUrl, lastEventId) => {
+	const url = new URL(streamUrl);
+	if (lastEventId !== void 0) url.searchParams.set("lastEventId", lastEventId);
+	return url.href;
+};
+/** Events of the client, the page and its timers. */
+const clientTransition = (state, event) => {
+	switch (event.type) {
+		case "topicsChanged": {
+			const next = {
+				...state,
+				topics: event.topics
+			};
+			return next.phase === "closed" ? unchanged(next) : {
+				commands: [{
+					event: { type: "debounceElapsed" },
+					milliseconds: topicSetDebounceMilliseconds,
+					timer: "debounce",
+					type: "schedule"
+				}],
+				state: next
+			};
+		}
+		case "debounceElapsed": return sync(state);
+		case "visibilityChanged": return reactToPage({
+			...state,
+			documentVisible: event.visible
+		});
+		case "pageHidden": return stop({
+			...state,
+			pageShown: false
+		});
+		case "pageShown": return reactToPage({
+			...state,
+			documentVisible: event.visible,
+			pageShown: true
+		});
+		case "backoffElapsed": return state.phase === "backoff" ? connect(state) : unchanged(state);
+		case "close": return {
+			...stop(state),
+			state: {
+				...shared(state),
+				phase: "closed"
+			}
+		};
+		default: return unchanged(state);
+	}
+};
+/** Events of one link; an event of an earlier link changes nothing. */
+const linkTransition = (state, event) => {
+	const link = currentLink(state);
+	if (link?.id !== event.linkId) return unchanged(state);
+	switch (event.type) {
+		case "ticketMinted": return {
+			commands: [{
+				linkId: link.id,
+				type: "openStream",
+				url: streamUrlAfter(event.streamUrl, state.lastEventId)
+			}],
+			state
+		};
+		case "ticketFailed":
+		case "streamEnded": return retry(state, event.retryMilliseconds);
+		case "streamOpened": return {
+			commands: [watchdog(link.id)],
+			state: {
+				...shared(state),
+				link,
+				phase: "open"
+			}
+		};
+		case "received": {
+			const { eventId } = event;
+			return {
+				commands: [watchdog(link.id)],
+				state: {
+					...state,
+					attempt: 0,
+					lastEventId: eventId === void 0 || eventId === "" ? state.lastEventId : eventId
+				}
+			};
+		}
+		case "watchdogElapsed": return retry(state);
+		default: return unchanged(state);
+	}
+};
+const transition = (state, event) => "linkId" in event ? linkTransition(state, event) : clientTransition(state, event);
+/** One stable key per topic, whatever the key order of the object. */
+const realtimeTopicKey = ({ filter, schema }) => JSON.stringify(filter === void 0 ? [schema] : [
+	schema,
+	filter.field,
+	filter.eq
+]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isFilterValue = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+const isTopic = (value) => isRecord(value) && typeof value.schema === "string" && (value.filter === void 0 || isRecord(value.filter) && typeof value.filter.field === "string" && isFilterValue(value.filter.eq));
+const isOp = (value) => value === "create" || value === "update" || value === "delete";
+/** The `data` of a `change` event, or undefined when it is malformed. */
+const parseRealtimeChange = (data) => {
+	let value;
+	try {
+		value = JSON.parse(data);
+	} catch {
+		return;
+	}
+	return isRecord(value) && typeof value.id === "string" && isOp(value.op) && typeof value.revision === "string" && isTopic(value.topic) ? {
+		id: value.id,
+		op: value.op,
+		revision: value.revision,
+		topic: value.topic
+	} : void 0;
+};
+/** The stream URL of a ticket route answer, or undefined when it is malformed. */
+const readStreamUrl = (value) => isRecord(value) && typeof value.streamUrl === "string" ? value.streamUrl : void 0;
+/** Surfaces a listener's error without stopping the other listeners. */
+const report = (error) => {
+	if ("reportError" in globalThis) {
+		globalThis.reportError(error);
+		return;
+	}
+	queueMicrotask(() => {
+		throw error;
+	});
+};
+const notify = (listener) => {
+	try {
+		listener();
+	} catch (error) {
+		report(error);
+	}
+};
+/** The least wait before a delivery: a burst of changes joins one delivery. */
+const changeWindowMilliseconds = 250;
+/** The random extra wait, so that the tabs of many users refetch apart. */
+const changeJitterMilliseconds = 750;
+const defaultTimers = { schedule: (callback, milliseconds) => {
+	const handle = globalThis.setTimeout(callback, milliseconds);
+	return () => globalThis.clearTimeout(handle);
+} };
+/**
+* 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.
+* Connection decisions live in the pure state machine (`./machine`); this
+* client only runs its commands.
+*/
+const createRealtimeClient = (options) => {
+	const fetch = options.fetch ?? globalThis.fetch;
+	const openStream = options.eventSourceFactory ?? createFetchEventSourceFactory(fetch);
+	const timers = options.timers ?? defaultTimers;
+	const random = options.random ?? Math.random;
+	const page = options.document;
+	const view = options.window;
+	const documentVisible = () => page === void 0 || page.visibilityState !== "hidden";
+	const registrations = /* @__PURE__ */ new Map();
+	const pendingTimers = /* @__PURE__ */ new Map();
+	const links = /* @__PURE__ */ new Map();
+	const queue = [];
+	/** Per topic key, the latest change of each record, by last arrival. */
+	const pending = /* @__PURE__ */ new Map();
+	let resetPending = false;
+	let cancelDelivery;
+	let state = initialMachineState(documentVisible());
+	/** Runs events one at a time; events sent by a command wait in the queue. */
+	const dispatch = (event) => {
+		queue.push(event);
+		if (queue.length > 1) return;
+		for (let next = queue.at(0); next !== void 0; next = queue.at(0)) try {
+			const { commands, state: nextState } = transition(state, next);
+			state = nextState;
+			for (const command of commands) run(command);
+		} finally {
+			queue.shift();
+		}
+	};
+	/** Delivers the pending changes, or the pending reset, to the current listeners. */
+	const deliver = () => {
+		cancelDelivery = void 0;
+		const batches = [...pending];
+		pending.clear();
+		if (resetPending) {
+			resetPending = false;
+			notify(() => options.onReset?.());
+			return;
+		}
+		for (const [key, changes] of batches) {
+			const batch = [...changes.values()];
+			for (const listener of registrations.get(key)?.listeners ?? []) notify(() => listener(batch));
+		}
+	};
+	/**
+	* The first change or reset after a delivery schedules the next one; later
+	* ones join it without delaying it.
+	*/
+	const scheduleDelivery = () => {
+		cancelDelivery ??= timers.schedule(deliver, changeWindowMilliseconds + Math.floor(random() * changeJitterMilliseconds));
+	};
+	const route = (change) => {
+		const key = realtimeTopicKey(change.topic);
+		if (!registrations.has(key)) return;
+		const changes = pending.get(key) ?? /* @__PURE__ */ new Map();
+		changes.delete(change.id);
+		changes.set(change.id, change);
+		pending.set(key, changes);
+		scheduleDelivery();
+	};
+	const ticketEvent = async (link, signal) => {
+		const topics = link.topics.flatMap((key) => {
+			const registration = registrations.get(key);
+			return registration === void 0 ? [] : [registration.topic];
+		});
+		try {
+			const response = await fetch(options.ticketUrl, {
+				body: JSON.stringify({ topics }),
+				credentials: "same-origin",
+				headers: { "content-type": "application/json" },
+				method: "POST",
+				signal
+			});
+			if (!response.ok) return {
+				linkId: link.id,
+				retryMilliseconds: retryAfterMilliseconds(response),
+				type: "ticketFailed"
+			};
+			const streamUrl = readStreamUrl(await response.json());
+			return streamUrl === void 0 ? {
+				linkId: link.id,
+				retryMilliseconds: void 0,
+				type: "ticketFailed"
+			} : {
+				linkId: link.id,
+				streamUrl,
+				type: "ticketMinted"
+			};
+		} catch {
+			return {
+				linkId: link.id,
+				retryMilliseconds: void 0,
+				type: "ticketFailed"
+			};
+		}
+	};
+	const mint = async (link, signal) => {
+		dispatch(await ticketEvent(link, signal));
+	};
+	const openEvents = (linkId, url) => openStream(url, {
+		onEnd: (end) => {
+			dispatch({
+				linkId,
+				retryMilliseconds: end.retryMilliseconds,
+				type: "streamEnded"
+			});
+		},
+		onEvent: (event) => {
+			if (currentLink(state)?.id !== linkId) return;
+			dispatch({
+				eventId: event.id,
+				linkId,
+				type: "received"
+			});
+			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?.();
+		},
+		onOpen: () => {
+			dispatch({
+				linkId,
+				type: "streamOpened"
+			});
+		},
+		onPing: (id) => {
+			dispatch({
+				eventId: id,
+				linkId,
+				type: "received"
+			});
+		}
+	}).close;
+	const cancelTimer = (timer) => {
+		pendingTimers.get(timer)?.();
+		pendingTimers.delete(timer);
+	};
+	const scheduleTimer = (timer, milliseconds, event) => {
+		cancelTimer(timer);
+		pendingTimers.set(timer, timers.schedule(() => {
+			pendingTimers.delete(timer);
+			dispatch(event);
+		}, milliseconds));
+	};
+	const run = (command) => {
+		switch (command.type) {
+			case "schedule":
+				scheduleTimer(command.timer, command.milliseconds, command.event);
+				return;
+			case "cancel":
+				cancelTimer(command.timer);
+				return;
+			case "backoff":
+				scheduleTimer("backoff", backoffDelay(command.attempt, command.retryMilliseconds, random()), { type: "backoffElapsed" });
+				return;
+			case "mint": {
+				const abort = new AbortController();
+				links.set(command.link.id, {
+					abort,
+					close: void 0
+				});
+				mint(command.link, abort.signal);
+				return;
+			}
+			case "openStream": {
+				const resources = links.get(command.linkId);
+				if (resources !== void 0) links.set(command.linkId, {
+					...resources,
+					close: openEvents(command.linkId, command.url)
+				});
+				return;
+			}
+			case "disconnect": {
+				const resources = links.get(command.linkId);
+				links.delete(command.linkId);
+				resources?.abort.abort();
+				resources?.close?.();
+				return;
+			}
+		}
+	};
+	const topicsChanged = () => {
+		dispatch({
+			topics: [...registrations.keys()],
+			type: "topicsChanged"
+		});
+	};
+	const onVisibility = () => {
+		dispatch({
+			type: "visibilityChanged",
+			visible: documentVisible()
+		});
+	};
+	const onPageHide = () => {
+		dispatch({ type: "pageHidden" });
+	};
+	const onPageShow = () => {
+		dispatch({
+			type: "pageShown",
+			visible: documentVisible()
+		});
+	};
+	page?.addEventListener("visibilitychange", onVisibility);
+	view?.addEventListener("pagehide", onPageHide);
+	view?.addEventListener("pageshow", onPageShow);
+	return {
+		close: () => {
+			dispatch({ type: "close" });
+			cancelDelivery?.();
+			cancelDelivery = void 0;
+			pending.clear();
+			resetPending = false;
+			page?.removeEventListener("visibilitychange", onVisibility);
+			view?.removeEventListener("pagehide", onPageHide);
+			view?.removeEventListener("pageshow", onPageShow);
+		},
+		getState: () => ({
+			connections: currentLink(state) === void 0 ? 0 : 1,
+			lastEventId: state.lastEventId,
+			status: state.phase === "closed" ? "idle" : state.phase,
+			topics: [...registrations.values()].map(({ topic }) => topic)
+		}),
+		subscribe: (topic, onChanges) => {
+			const key = realtimeTopicKey(topic);
+			const registration = registrations.get(key) ?? {
+				listeners: /* @__PURE__ */ new Set(),
+				topic
+			};
+			const listener = (changes) => onChanges(changes);
+			registration.listeners.add(listener);
+			if (!registrations.has(key)) {
+				registrations.set(key, registration);
+				topicsChanged();
+			}
+			const unsubscribe = () => {
+				if (!registration.listeners.delete(listener)) return;
+				if (registration.listeners.size === 0) {
+					registrations.delete(key);
+					pending.delete(key);
+					topicsChanged();
+				}
+			};
+			return unsubscribe;
+		}
+	};
+};
+export { DEFAULT_FOLLOW_RUN_DEADLINE_MS, FederatedAuthError, clientOperationIds, clientSdkProtocolVersion, createClient, createDelegatedApplicationRuntime, createDirectTransport, createEntityHttpTransport, createEntityProtocol, createFederatedAuth, createFetchEventSourceFactory, createFixedWorkflowClient, createProxyTransport, createRealtimeClient, createResourceClient, createServerSessionAuth, followRun, isClientOperationId, isEntityReadLimitError, nextStreamCursor, realtimeTopicKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collective-intelligence/external-apps-client-sdk",
-  "version": "0.1.18",
+  "version": "0.1.21",
   "description": "Framework-neutral client for Collective Intelligence external applications.",
   "type": "module",
   "sideEffects": false,