@pouchy_ai/companion-sdk 0.30.0 → 0.32.1

package/src/adapter-core.ts

@@ -0,0 +1,227 @@
+// Framework-agnostic view controller behind the /svelte and /vue adapters
+// (0.31.0). One place owns the subscription wiring + snapshot bookkeeping the
+// adapters share, so each adapter stays a logic-free ~40-line binding to its
+// framework's reactivity primitive — and THIS file is where the behavior gets
+// unit-tested once instead of per-framework. (React hosts use the standalone
+// `@pouchy_ai/react` package instead — it owns the client LIFECYCLE and a
+// voice-call hook, which this controller deliberately doesn't; conversely the
+// render-state here — streamState, streamed draft, pendingConfirms — is richer
+// than the react hooks. Complementary shapes, not a parity pair.)
+//
+// Contract (deliberately useSyncExternalStore-shaped, the strictest of the
+// three): `getSnapshot()` returns the SAME object reference until something
+// changes, and every change produces a new frozen snapshot + one listener
+// sweep. Svelte's store contract and Vue's shallowRef both accept that shape
+// as-is.
+
+import type { CompanionClient } from './client';
+import type { CompanionStreamState } from './client';
+import type { ConfirmRequestPayload, TypingPayload } from './protocol';
+import { CompanionError } from './errors';
+
+/** One rendered line of the conversation, in arrival order. */
+export interface CompanionTranscriptEntry {
+	role: 'user' | 'companion';
+	text: string;
+	/** Client wall-clock ms when the entry was appended. */
+	at: number;
+}
+
+/** Immutable view snapshot. A new object per change — safe to hand to
+ *  useSyncExternalStore / $state / shallowRef without defensive copies. */
+export interface CompanionViewSnapshot {
+	streamState: CompanionStreamState;
+	/** Rolling transcript, oldest first, capped at `transcriptCap`. */
+	transcript: readonly CompanionTranscriptEntry[];
+	/** The in-flight streamed reply (token deltas), '' when none. */
+	draft: string;
+	typing: boolean;
+	/** Confirm requests that arrived on the stream and haven't been resolved
+	 *  through this view yet. Rebuild after a reload via client.pendingConfirms()
+	 *  — confirm_request events are not replayed. */
+	pendingConfirms: readonly ConfirmRequestPayload[];
+}
+
+export interface CompanionViewOptions {
+	/** Max transcript entries kept (oldest dropped). Default 200. */
+	transcriptCap?: number;
+	/** Restore up to this many recent turns from `client.history()` on
+	 *  creation, so a reloaded tab isn't blank (same semantic as
+	 *  `@pouchy_ai/react`'s useMessages). Requires a connected client (a
+	 *  session must exist). Restored turns land ONLY while the live transcript
+	 *  is still empty — they never clobber messages that arrived first.
+	 *  Default 0 (off). */
+	restore?: number;
+}
+
+export interface CompanionView {
+	/** Stable-reference snapshot (useSyncExternalStore contract). */
+	getSnapshot(): CompanionViewSnapshot;
+	/** Subscribe to snapshot changes. Returns unsubscribe. */
+	subscribe(listener: () => void): () => void;
+	/** sendText that also appends the user turn to the transcript. */
+	sendText(
+		text: string,
+		opts?: Parameters<CompanionClient['sendText']>[1]
+	): ReturnType<CompanionClient['sendText']>;
+	/** confirmAction that also removes the confirm from `pendingConfirms`
+	 *  (on approve AND deny — both resolve the card server-side). */
+	confirmAction(
+		confirmId: string,
+		approve: boolean,
+		opts?: { signal?: AbortSignal }
+	): ReturnType<CompanionClient['confirmAction']>;
+	/** Detach every client subscription. The view goes inert (snapshot frozen,
+	 *  listeners dropped); the client itself is NOT closed — it belongs to the
+	 *  host. Idempotent. */
+	dispose(): void;
+	/** The underlying client, for everything the view doesn't wrap. */
+	readonly client: CompanionClient;
+}
+
+const DEFAULT_TRANSCRIPT_CAP = 200;
+
+/** Wire a client into an immutable-snapshot view. Adapters bind this to their
+ *  framework; hosts using none of the adapters can consume it directly. */
+export function createCompanionView(
+	client: CompanionClient,
+	opts?: CompanionViewOptions
+): CompanionView {
+	const cap = Math.max(1, opts?.transcriptCap ?? DEFAULT_TRANSCRIPT_CAP);
+	const listeners = new Set<() => void>();
+	let disposed = false;
+
+	let snapshot: CompanionViewSnapshot = Object.freeze({
+		streamState: client.streamState,
+		transcript: Object.freeze([]) as readonly CompanionTranscriptEntry[],
+		draft: '',
+		typing: false,
+		pendingConfirms: Object.freeze([]) as readonly ConfirmRequestPayload[]
+	});
+
+	function commit(patch: Partial<CompanionViewSnapshot>): void {
+		if (disposed) return;
+		snapshot = Object.freeze({ ...snapshot, ...patch });
+		// Snapshot-first, then notify: a listener that re-reads getSnapshot()
+		// synchronously must see the new value. Handler isolation matches the
+		// client's emit() doctrine — one throwing listener must not starve the rest.
+		for (const l of [...listeners]) {
+			try {
+				l();
+			} catch {
+				/* listener errors are the listener's problem */
+			}
+		}
+	}
+
+	function appendTranscript(entry: CompanionTranscriptEntry): void {
+		const next = [...snapshot.transcript, entry];
+		commit({ transcript: Object.freeze(next.slice(-cap)) });
+	}
+
+	const restore = opts?.restore ?? 0;
+	if (restore > 0) {
+		void client
+			.history({ limit: restore })
+			.then((turns) => {
+				// Only fill a still-empty transcript — live traffic wins.
+				if (disposed || snapshot.transcript.length) return;
+				const restored: CompanionTranscriptEntry[] = [];
+				for (const t of turns) {
+					if (t.user) restored.push({ role: 'user', text: t.user, at: t.ts });
+					if (t.assistant) restored.push({ role: 'companion', text: t.assistant, at: t.ts });
+				}
+				if (restored.length) commit({ transcript: Object.freeze(restored.slice(-cap)) });
+			})
+			.catch(() => {
+				/* a brand-new session has no history — fine */
+			});
+	}
+
+	const unsubs: Array<() => void> = [
+		client.onStreamStateChange((next: CompanionStreamState) => commit({ streamState: next })),
+		client.onMessage((text: string) => {
+			// The authoritative full reply replaces any streamed draft; typing is
+			// definitionally over once the reply lands.
+			const next = [...snapshot.transcript, { role: 'companion' as const, text, at: Date.now() }];
+			commit({
+				transcript: Object.freeze(next.slice(-cap)),
+				draft: '',
+				typing: false
+			});
+		}),
+		client.onDelta((chunk: string, meta: { reset?: boolean }) => {
+			commit({ draft: meta.reset ? chunk : snapshot.draft + chunk });
+		}),
+		client.onTyping((payload: TypingPayload) => commit({ typing: !!payload.active })),
+		client.onConfirmRequest((payload: ConfirmRequestPayload) => {
+			// The stream can redeliver on reconnect replay — dedupe by confirmId.
+			if (snapshot.pendingConfirms.some((c) => c.confirmId === payload.confirmId)) return;
+			commit({ pendingConfirms: Object.freeze([...snapshot.pendingConfirms, payload]) });
+		})
+	];
+
+	return {
+		client,
+		getSnapshot: () => snapshot,
+		subscribe(listener: () => void) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		async sendText(text, sendOpts) {
+			const entry: CompanionTranscriptEntry = { role: 'user', text, at: Date.now() };
+			appendTranscript(entry);
+			try {
+				return await client.sendText(text, sendOpts as never);
+			} catch (err) {
+				// The optimistic line must not survive a send the server never saw
+				// (network drop / 429 turn-claim) — roll it back by identity so the
+				// host's retry re-appends cleanly (0.32.1).
+				commit({
+					transcript: Object.freeze(snapshot.transcript.filter((e) => e !== entry))
+				});
+				throw err;
+			}
+		},
+		async confirmAction(confirmId, approve, confirmOpts) {
+			let res;
+			try {
+				res = await client.confirmAction(confirmId, approve, confirmOpts);
+			} catch (err) {
+				// The same confirm can be resolved OUT FROM UNDER this card — the
+				// hosted confirm page, or (since round 13) a channel keyword reply.
+				// A 409 confirm_resolved / 404 confirm_not_found means the card is
+				// dead either way; keeping it would strand a permanently-stale
+				// approve button (0.32.1). Other rejections (network) keep the card.
+				if (
+					err instanceof CompanionError &&
+					(err.code === 'confirm_resolved' || err.code === 'confirm_not_found')
+				) {
+					commit({
+						pendingConfirms: Object.freeze(
+							snapshot.pendingConfirms.filter((c) => c.confirmId !== confirmId)
+						)
+					});
+				}
+				throw err;
+			}
+			// Remove on any settled resolution; exec_failed with retryable keeps the
+			// card — the host may re-approve the SAME confirmId (documented server
+			// semantic), so dropping it would strand the retry affordance.
+			if (!(res.status === 'exec_failed' && res.retryable)) {
+				commit({
+					pendingConfirms: Object.freeze(
+						snapshot.pendingConfirms.filter((c) => c.confirmId !== confirmId)
+					)
+				});
+			}
+			return res;
+		},
+		dispose() {
+			if (disposed) return;
+			for (const u of unsubs) u();
+			listeners.clear();
+			disposed = true;
+		}
+	};
+}