@pouchy_ai/companion-sdk 0.33.0 → 0.34.0

package/src/client.ts

@@ -107,6 +107,21 @@ export interface CompanionClientOptions {
 	 *  configuration errors and never trigger it. Alternative: call `setToken()`
 	 *  proactively on your own refresh schedule. */
 	onAuthError?: () => string | null | Promise<string | null>;
+	/** Opt-in offline send queue (0.34.0). A sendText that fails at the NETWORK
+	 *  level (fetch rejected before any HTTP response, or `navigator.onLine` is
+	 *  false) is queued instead of lost, and replayed FIFO once the server is
+	 *  reachable again — after a successful connect(), on every stream
+	 *  reconnect, or via `flushOutbox()`. Replays reuse the ORIGINAL turnId:
+	 *  the server dedupes completed turnIds (10 min TTL, last 8 per session),
+	 *  so a retry after an ambiguous failure can never double-run a turn. HTTP
+	 *  error responses (4xx/5xx incl. 429) are NEVER queued — the server saw
+	 *  those; they keep the normal throw semantics. Default false. */
+	queueOffline?: boolean;
+	/** Persistence for the offline queue (see `queueOffline`). Defaults to
+	 *  localStorage when available (privacy-mode / quota failures fall back
+	 *  silently), else an in-memory page-lifetime store. The key is
+	 *  `pouchy-outbox:${surface}`, so each surface keeps its own queue. */
+	outboxStore?: OutboxStore;
 }
 
 export interface HelloAck {
@@ -268,6 +283,53 @@ export interface SendTextReply {
 	envelope: CompanionEnvelope;
 }
 
+/** One send queued while offline (see the `queueOffline` option) — replayed
+ *  FIFO by flushOutbox with its ORIGINAL `turnId` (the server's turn-dedup is
+ *  what makes the retry safe). `at` is Date.now() at enqueue. */
+export interface QueuedSend {
+	turnId: string;
+	text: string;
+	images?: string[];
+	at: number;
+}
+
+/** Pluggable persistence for the offline send queue (the `outboxStore`
+ *  option). Both methods receive the storage key
+ *  (`pouchy-outbox:${surface}`); `load` returns the previously-saved value or
+ *  null. */
+export interface OutboxStore {
+	load(key: string): string | null;
+	save(key: string, value: string): void;
+}
+
+// Default outbox persistence: localStorage when the environment has one (and
+// allows it — privacy mode / quota errors fall through), else a module-level
+// Map so the queue at least survives for the page's lifetime.
+const memoryOutbox = new Map<string, string>();
+const defaultOutboxStore: OutboxStore = {
+	load(key) {
+		try {
+			if (typeof window !== 'undefined' && window.localStorage) {
+				return window.localStorage.getItem(key);
+			}
+		} catch {
+			/* storage denied — fall through to the in-memory copy */
+		}
+		return memoryOutbox.get(key) ?? null;
+	},
+	save(key, value) {
+		try {
+			if (typeof window !== 'undefined' && window.localStorage) {
+				window.localStorage.setItem(key, value);
+				return;
+			}
+		} catch {
+			/* quota / privacy mode — keep the in-memory copy below */
+		}
+		memoryOutbox.set(key, value);
+	}
+};
+
 type Handler = (envelope: CompanionEnvelope) => void;
 
 /** Token-streaming subscriber (P1-2). `chunk` is a raw text delta of the reply
@@ -345,6 +407,14 @@ export class CompanionClient {
 	// paths pay one falsy check.
 	private readonly debugSink: ((event: CompanionDebugEvent) => void) | null;
 
+	// Offline send queue (0.34.0) — null until first use, then loaded lazily
+	// from the store so a reloaded tab resumes the queue its predecessor
+	// persisted.
+	private outbox: QueuedSend[] | null = null;
+	private readonly outboxHandlers = new Set<(items: readonly QueuedSend[]) => void>();
+	// In-flight flush, shared so concurrent triggers run ONE flush at a time.
+	private outboxFlush: Promise<{ sent: number; remaining: number }> | null = null;
+
 	constructor(opts: CompanionClientOptions) {
 		if (!opts.baseUrl)
 			throw new CompanionError('CompanionClient: baseUrl is required', 0, 'missing_option');
@@ -409,6 +479,9 @@ export class CompanionClient {
 				console.error('[companion-sdk] stream-state handler threw', e);
 			}
 		}
+		// The stream coming back up is the strongest "server reachable again"
+		// signal there is — drain any sends queued while offline (0.34.0).
+		if (next === 'connected' && this.opts.queueOffline) void this.flushOutbox().catch(() => {});
 	}
 
 	/** Swap the bearer token used by every subsequent request and stream
@@ -616,6 +689,9 @@ export class CompanionClient {
 		}, opts?.signal);
 		this._session = json.session;
 		this.cursor = json.resumeCursor ?? 0;
+		// A successful handshake proves reachability — replay any sends queued
+		// while offline (0.34.0; no-op when the queue is empty).
+		if (this.opts.queueOffline) void this.flushOutbox().catch(() => {});
 		return {
 			...json,
 			representative: json.representative ?? false,
@@ -668,7 +744,15 @@ export class CompanionClient {
 	 *  can't ride the request (`stream: false`, or an old server) does it fall
 	 *  back to the event stream — which then DOES need start() — resolving with
 	 *  the next `companion.message`, or rejecting with code `reply_timeout`
-	 *  after `replyTimeoutMs` (default 60s). */
+	 *  after `replyTimeoutMs` (default 60s).
+	 *
+	 *  OFFLINE QUEUE (0.34.0, opt-in `queueOffline: true`): a send that never
+	 *  REACHED the server — fetch rejected at the network level, or
+	 *  `navigator.onLine` is already false — is queued for replay instead of
+	 *  lost, and resolves `{ seq: null, queued: true, turnId }`. With
+	 *  `awaitReply: true` there is no reply to await this session, so it
+	 *  rejects with code `queued_offline` (the item IS queued first). HTTP
+	 *  error responses keep the throw semantics above — they are never queued. */
 	async sendText(
 		text: string,
 		opts: { awaitReply: true; images?: string[]; stream?: boolean; replyTimeoutMs?: number; signal?: AbortSignal }
@@ -676,11 +760,11 @@ export class CompanionClient {
 	async sendText(
 		text: string,
 		opts?: { images?: string[]; stream?: boolean; awaitReply?: boolean; replyTimeoutMs?: number; signal?: AbortSignal }
-	): Promise<{ seq: number | null }>;
+	): Promise<{ seq: number | null; queued?: boolean; turnId?: string }>;
 	async sendText(
 		text: string,
 		opts?: { images?: string[]; stream?: boolean; awaitReply?: boolean; replyTimeoutMs?: number; signal?: AbortSignal }
-	): Promise<{ seq: number | null } | SendTextReply> {
+	): Promise<{ seq: number | null; queued?: boolean; turnId?: string } | SendTextReply> {
 		const id = this.requireSession();
 		// Client-minted correlation id (0.28.0): the server echoes it back as
 		// `replyTo` on this turn's companion.message — even across an app-tool
@@ -688,6 +772,29 @@ export class CompanionClient {
 		// message that happens by (world-state reactions, confirm outcomes).
 		const turnId = `turn_${this.randomId()}`;
 		const body = { text, turnId, ...(opts?.images?.length ? { images: opts.images } : {}) };
+		if (!this.opts.queueOffline) return this.dispatchText(id, body, opts, turnId);
+		// Offline queue: two triggers only — the browser already knows it's
+		// offline, or fetch itself rejected without an HTTP response. An HTTP
+		// error (4xx/5xx incl. 429) means the server SAW the turn: those keep
+		// the normal throw semantics and are never queued.
+		if (typeof navigator !== 'undefined' && navigator.onLine === false) {
+			return this.queueSend(turnId, text, opts);
+		}
+		try {
+			return await this.dispatchText(id, body, opts, turnId);
+		} catch (e) {
+			if (this.isNetworkSendFailure(e)) return this.queueSend(turnId, text, opts);
+			throw e;
+		}
+	}
+
+	/** The pre-queue dispatch of sendText: awaitReply / streaming / buffered. */
+	private async dispatchText(
+		id: string,
+		body: Record<string, unknown>,
+		opts?: { images?: string[]; stream?: boolean; awaitReply?: boolean; replyTimeoutMs?: number; signal?: AbortSignal },
+		turnId?: string
+	): Promise<{ seq: number | null } | SendTextReply> {
 		if (opts?.awaitReply) return this.sendTextAwaitingReply(id, body, opts, turnId);
 		const wantStream = opts?.stream ?? this.deltaHandlers.size > 0;
 		if (!wantStream) {
@@ -701,6 +808,42 @@ export class CompanionClient {
 		return this.sendTextStreaming(id, body, opts?.signal);
 	}
 
+	/** True only for a send that never reached the server: fetch rejected at
+	 *  the network level, which asCompanionError wraps as status 0 with NO
+	 *  code. Every code-carrying status-0 error is deliberate — `aborted` is
+	 *  the caller cancelling, `reply_timeout`/`needs_event_stream` mean the
+	 *  POST was accepted — and any nonzero status is a response the server
+	 *  produced. None of those may queue. */
+	private isNetworkSendFailure(e: unknown): boolean {
+		return e instanceof CompanionError && e.status === 0 && e.code === undefined;
+	}
+
+	/** Enqueue an offline send. Plain sends resolve `{ seq: null, queued: true,
+	 *  turnId }`; awaitReply can't await a reply that won't arrive this
+	 *  session, so it rejects with `queued_offline` — the item is queued
+	 *  either way. */
+	private queueSend(
+		turnId: string,
+		text: string,
+		opts?: { images?: string[]; awaitReply?: boolean }
+	): { seq: null; queued: true; turnId: string } {
+		this.loadOutbox().push({
+			turnId,
+			text,
+			...(opts?.images?.length ? { images: opts.images } : {}),
+			at: Date.now()
+		});
+		this.commitOutbox();
+		if (opts?.awaitReply) {
+			throw new CompanionError(
+				'offline — the text was queued and will send when the connection returns; no reply to await',
+				0,
+				'queued_offline'
+			);
+		}
+		return { seq: null, queued: true, turnId };
+	}
+
 	/** The awaitReply leg of sendText. Prefers the in-request answer (the
 	 *  streaming `done` frame's envelope); falls back to the next
 	 *  `companion.message` off the event stream, bounded by a timeout. The
@@ -927,6 +1070,120 @@ export class CompanionClient {
 		}
 	}
 
+	/** The live offline queue, loaded from the store on first use so a reloaded
+	 *  tab resumes what its predecessor persisted. Unreadable or foreign store
+	 *  content is discarded — a corrupt store must never break sending. */
+	private loadOutbox(): QueuedSend[] {
+		if (this.outbox) return this.outbox;
+		let items: QueuedSend[] = [];
+		try {
+			const raw = (this.opts.outboxStore ?? defaultOutboxStore).load(this.outboxKey());
+			const parsed = raw ? (JSON.parse(raw) as unknown) : null;
+			if (Array.isArray(parsed)) {
+				items = parsed.filter(
+					(q): q is QueuedSend =>
+						!!q &&
+						typeof (q as QueuedSend).turnId === 'string' &&
+						typeof (q as QueuedSend).text === 'string'
+				);
+			}
+		} catch {
+			/* unreadable store — start empty */
+		}
+		this.outbox = items;
+		return items;
+	}
+
+	private outboxKey(): string {
+		return `pouchy-outbox:${this.opts.surface ?? 'default'}`;
+	}
+
+	/** Persist + notify after EVERY queue mutation (enqueue / flushed / drop),
+	 *  so the stored copy never lags what a reload would need. Handler
+	 *  isolation matches emit(): a throwing consumer must not skip the rest. */
+	private commitOutbox(): void {
+		const items = this.loadOutbox();
+		try {
+			(this.opts.outboxStore ?? defaultOutboxStore).save(this.outboxKey(), JSON.stringify(items));
+		} catch {
+			/* store save failed — the in-memory queue still flushes this page */
+		}
+		const copy = Object.freeze([...items]) as readonly QueuedSend[];
+		for (const h of this.outboxHandlers) {
+			try {
+				h(copy);
+			} catch (e) {
+				console.error('[companion-sdk] outbox handler threw', e);
+			}
+		}
+	}
+
+	/** The sends queued while offline (oldest first), as a defensive copy —
+	 *  see the `queueOffline` option. */
+	pendingOutbox(): readonly QueuedSend[] {
+		return [...this.loadOutbox()];
+	}
+
+	/** Subscribe to offline-queue changes (enqueue / flushed / dropped) — drive
+	 *  a "N pending" badge from `items.length`. Returns an unsubscribe fn. */
+	onOutboxChange(handler: (items: readonly QueuedSend[]) => void): () => void {
+		this.outboxHandlers.add(handler);
+		return () => this.outboxHandlers.delete(handler);
+	}
+
+	/** Replay the offline queue: FIFO, sequential, each item a normal buffered
+	 *  input POST reusing its ORIGINAL `turnId` (the server dedupes completed
+	 *  turnIds — see `queueOffline` — so a retry can never double-run a turn).
+	 *  Runs automatically after connect() and on every stream reconnect; call
+	 *  it yourself for a manual retry affordance. One flush at a time —
+	 *  concurrent calls share the in-flight run. Per item: success (or a
+	 *  server-side duplicate) → removed; network failure / 5xx / 429 → stop,
+	 *  keep this item and the rest for the next flush; any other 4xx → the
+	 *  item itself is invalid (the server deliberately rejected it) — drop it,
+	 *  console.warn, and keep flushing. */
+	async flushOutbox(): Promise<{ sent: number; remaining: number }> {
+		this.requireSession();
+		this.outboxFlush ??= this.runOutboxFlush().finally(() => {
+			this.outboxFlush = null;
+		});
+		return this.outboxFlush;
+	}
+
+	private async runOutboxFlush(): Promise<{ sent: number; remaining: number }> {
+		const id = this.requireSession();
+		const items = this.loadOutbox();
+		let sent = 0;
+		while (items.length) {
+			const item = items[0];
+			try {
+				await this.postJson<{ seq: number | null; duplicate?: boolean }>(
+					`/api/companion/session/${id}/input`,
+					{
+						text: item.text,
+						turnId: item.turnId,
+						...(item.images?.length ? { images: item.images } : {})
+					}
+				);
+			} catch (e) {
+				const status = e instanceof CompanionError ? e.status : 0;
+				if (status >= 400 && status < 500 && status !== 429) {
+					// The server saw it and said no — retrying can't fix the item.
+					console.warn('[companion-sdk] dropping queued send the server rejected', status, e);
+					items.shift();
+					this.commitOutbox();
+					continue;
+				}
+				// Unreachable again (or throttled / a server-side failure): keep
+				// this item and everything behind it for the next flush.
+				break;
+			}
+			items.shift();
+			sent += 1;
+			this.commitOutbox();
+		}
+		return { sent, remaining: items.length };
+	}
+
 	/** Subscribe to token-streaming deltas of the reply (P1-2). Registering a
 	 *  subscriber makes sendText stream automatically. Returns an unsubscribe
 	 *  function. Render chunks as they arrive; on `meta.reset` clear the partial;

package/src/errors.ts

@@ -20,7 +20,8 @@ export const SDK_SYNTHESIZED_ERROR_CODES = [
 	'call_unsupported', // startCall on a server/provider without voice
 	'call_connect_failed', // WebRTC/provider handshake failed
 	'call_dependency_missing', // optional voice dependency not installed
-	'aborted' // a caller-supplied AbortSignal cancelled the request (0.29.0)
+	'aborted', // a caller-supplied AbortSignal cancelled the request (0.29.0)
+	'queued_offline' // queueOffline: the text was queued while offline and will send on reconnect (0.34.0)
 ] as const;
 export type SdkSynthesizedErrorCode = (typeof SDK_SYNTHESIZED_ERROR_CODES)[number];
 

package/src/index.ts

@@ -30,7 +30,9 @@ export type {
 	WalletBalance,
 	BrandIconSize,
 	EndSessionResult,
-	SendTextReply
+	SendTextReply,
+	QueuedSend,
+	OutboxStore
 } from './client';
 export {
 	openCompanionCall,