@pouchy_ai/companion-sdk 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -12,6 +12,46 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.18.1] - 2026-07-08
+
+### Changed
+
+- `confirmAction()` return type widened: `status` may now be `'exec_failed'` and
+  the response carries an optional `retryable` flag. When an approved **idempotent**
+  action (a wallet payment) fails on a transient error, the server no longer burns
+  the confirmation — it returns `{ status: 'exec_failed', retryable: true }`, and
+  you MAY re-call `confirmAction(sameConfirmId, true)` to re-run it (the server
+  dedupes a partial first attempt on the confirmId). Non-idempotent actions (a
+  friend message, a skill POST) stay strictly single-use and are never retryable.
+  Additive + backwards-compatible: existing `'approved' | 'denied'` handling is
+  unaffected. No wire-protocol change.
+
+## [0.18.0] - 2026-07-08
+
+### Added
+
+- **`close()`** — one-call teardown for a non-voice (text) session: stops the
+  event stream and calls `endSession()` once (idempotent). The text-path mirror
+  of what a `connectCall()` handle's `close()` already does for voice.
+- **`EndSessionResult`** type — exported. `endSession()` now RETURNS the server's
+  consolidation diagnostic `{ ok, facts?, skipped? }` (or `null`) instead of
+  discarding it, so an integrator whose memory write silently does nothing (wrong
+  id → `skipped: 'no_session'`, empty transcript → `'no_content'`) gets the
+  signal the server already provides. Backwards-compatible: callers ignoring the
+  return value are unaffected (`connectCall`'s internal `void endSession()` too).
+- **`CompanionError.code`** — an optional stable, machine-readable tag on the
+  thrown error. Local precondition mistakes now throw a `CompanionError`
+  (`status: 0`) instead of a bare `Error`, with codes `not_connected` (a method
+  called before `connect()`), `missing_option` (no `baseUrl`/`token`), and
+  `not_representative` (`pairVisitor` off a non-representative session); HTTP
+  failures carry the server's error `code` when present. `catch (e) { if (e
+  instanceof CompanionError) … }` — the natural one-error-type pattern — now
+  catches the common first-run mistakes too.
+
+### Changed
+
+- `endSession(opts?)` return type: `Promise<void>` → `Promise<EndSessionResult | null>`.
+
 ## [0.17.0] - 2026-07-08
 
 ### Added

package/README.md

@@ -18,6 +18,10 @@ No bundler? Pull it from a CDN via an import map instead — see
 [`docs/companion-integration-faq.md`](../../docs/companion-integration-faq.md).
 Changes per release are tracked in [`CHANGELOG.md`](./CHANGELOG.md).
 
+**React?** [`@pouchy_ai/react`](../react-sdk/README.md) wraps this SDK in a
+`<CompanionProvider>` + `useCompanion` / `useMessages` / `useTyping` / `useCall`
+hooks so you don't wire the handshake, stream, or teardown yourself.
+
 ## Quickstart
 
 Two steps. **1)** Your backend exchanges the project **Secret Key** (create one

package/dist/client.d.ts

@@ -129,9 +129,25 @@ export type BrandIconSize = 256 | 512 | 1024;
  *  deployment origin. Standalone (no client/token needed) so a surface can show
  *  the Pouchy mark before/without connecting. */
 export declare function pouchyBrandIconUrl(baseUrl: string, size?: BrandIconSize): string;
+/** The single error type the SDK throws — for HTTP failures (`status` is the
+ *  response code) AND for local precondition mistakes (`status: 0`, e.g. calling
+ *  a method before `connect()`). `code` is a stable machine-readable tag you can
+ *  switch on, shared with the `control.error` stream event vocabulary:
+ *  `'not_connected'`, `'missing_option'`, `'not_representative'`, or the server's
+ *  own error code for an HTTP failure (when it sends one). */
 export declare class CompanionError extends Error {
     status: number;
-    constructor(message: string, status: number);
+    code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+/** The server's memory-consolidation diagnostic from `endSession()` / `close()`.
+ *  `ok` is whether consolidation ran; `facts` is how many memories it wrote;
+ *  `skipped` (when present) says why nothing was written
+ *  (`'no_session'` | `'no_content'` | `'throttled'`). */
+export interface EndSessionResult {
+    ok: boolean;
+    facts?: number;
+    skipped?: string;
 }
 type Handler = (envelope: CompanionEnvelope) => void;
 /** Token-streaming subscriber (P1-2). `chunk` is a raw text delta of the reply
@@ -242,13 +258,27 @@ export declare class CompanionClient {
      *  Called automatically when a connectCall() handle is closed; call it directly
      *  when a non-voice session ends. Best-effort + idempotent (safe to call twice;
      *  uses keepalive so it survives a page unload). Pass the voice transcript when
-     *  you have it (connectCall does this for you). */
+     *  you have it (connectCall does this for you).
+     *
+     *  Returns the server's consolidation diagnostic — `{ ok, facts?, skipped? }`
+     *  — or `null` if there was no session or the (swallowed) keepalive request
+     *  failed. `skipped` tells you WHY nothing was written: `'no_session'` (you
+     *  passed the instance id, not the session id), `'no_content'` (empty turn log
+     *  / a voice transcript that never arrived), `'throttled'` (a duplicate end
+     *  beacon — harmless). `facts` is how many memories were consolidated. */
     endSession(opts?: {
         transcript?: {
             role: string;
             text: string;
         }[];
-    }): Promise<void>;
+    }): Promise<EndSessionResult | null>;
+    /** Tear the session down in one call: stop the event stream and consolidate
+     *  memory (endSession) exactly once. The single teardown entry point for a
+     *  NON-voice (text) session — mirror of what a connectCall() handle's close()
+     *  does for voice. Idempotent. Returns endSession's diagnostic (or null).
+     *  NOTE: if you drive `ping()` on your own timer for a background tab, clear
+     *  that timer yourself — the client doesn't own it. */
+    close(): Promise<EndSessionResult | null>;
     /** Report the result of a companion.tool_call this surface performed. When all
      *  of the turn's calls are reported, the companion resumes and the continuation
      *  (a companion.message or more tool calls) arrives on the event stream. */
@@ -408,12 +438,19 @@ export declare class CompanionClient {
      *  approval the recorded action runs server-side; its result comes back as
      *  `outcome` in this response (render it where the user tapped) AND as a
      *  normal companion.message on the stream (so the conversation shows it).
-     *  A denial returns/emits a brief decline the same way. One-time:
-     *  re-resolving a settled confirmId fails with 409. */
+     *  A denial returns/emits a brief decline the same way. Single-use:
+     *  re-resolving a settled confirmId fails with 409.
+     *
+     *  RETRY: if an approved IDEMPOTENT action (a wallet payment) flakes on a
+     *  transient error, `status` is `'exec_failed'` and `retryable` is true — you
+     *  MAY call `confirmAction(sameConfirmId, true)` again to re-run it (the server
+     *  dedupes a partial first attempt). A non-idempotent action (a message / skill)
+     *  stays terminal and is never retryable. */
     confirmAction(confirmId: string, approve: boolean): Promise<{
         ok: boolean;
-        status: 'approved' | 'denied';
+        status: 'approved' | 'denied' | 'exec_failed';
         outcome?: string;
+        retryable?: boolean;
     }>;
     /** The session's still-pending confirmations (display-safe: id, summary,
      *  scope, timestamps — never raw args). Use it to rebuild your confirm card

package/dist/client.js

@@ -19,12 +19,21 @@ import { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_
 export function pouchyBrandIconUrl(baseUrl, size = 512) {
     return baseUrl.replace(/\/+$/, '') + `/brand-assets/icon/pouchy-icon-${size}.png`;
 }
+/** The single error type the SDK throws — for HTTP failures (`status` is the
+ *  response code) AND for local precondition mistakes (`status: 0`, e.g. calling
+ *  a method before `connect()`). `code` is a stable machine-readable tag you can
+ *  switch on, shared with the `control.error` stream event vocabulary:
+ *  `'not_connected'`, `'missing_option'`, `'not_representative'`, or the server's
+ *  own error code for an HTTP failure (when it sends one). */
 export class CompanionError extends Error {
     status;
-    constructor(message, status) {
+    code;
+    constructor(message, status, code) {
         super(message);
         this.name = 'CompanionError';
         this.status = status;
+        if (code)
+            this.code = code;
     }
 }
 const SEEN_CAP = 512;
@@ -44,9 +53,9 @@ export class CompanionClient {
     pendingVoiceTools = new Map();
     constructor(opts) {
         if (!opts.baseUrl)
-            throw new Error('CompanionClient: baseUrl is required');
+            throw new CompanionError('CompanionClient: baseUrl is required', 0, 'missing_option');
         if (!opts.token)
-            throw new Error('CompanionClient: token is required');
+            throw new CompanionError('CompanionClient: token is required', 0, 'missing_option');
         this.opts = opts;
         this.doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
     }
@@ -62,7 +71,7 @@ export class CompanionClient {
     }
     requireSession() {
         if (!this._session)
-            throw new Error('CompanionClient: call connect() first');
+            throw new CompanionError('CompanionClient: call connect() first', 0, 'not_connected');
         return this._session;
     }
     async postJson(path, body) {
@@ -73,7 +82,7 @@ export class CompanionClient {
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
-            throw new CompanionError(json?.error || `request failed (${res.status})`, res.status);
+            throw new CompanionError(json?.error || `request failed (${res.status})`, res.status, json?.code);
         }
         return json;
     }
@@ -106,10 +115,10 @@ export class CompanionClient {
      *  — as proof + consent. The visitor must therefore also be a Pouchy user. */
     async pairVisitor(visitorToken) {
         if (!this.opts.visitor) {
-            throw new Error('pairVisitor() requires a representative session (createCompanion({ visitor }))');
+            throw new CompanionError('pairVisitor() requires a representative session (createCompanion({ visitor }))', 0, 'not_representative');
         }
         if (!visitorToken)
-            throw new Error('pairVisitor: visitorToken is required');
+            throw new CompanionError('pairVisitor: visitorToken is required', 0, 'missing_option');
         const json = await this.postJson('/api/companion/pair', {
             visitorToken,
             visitorId: this.opts.visitor.id
@@ -320,28 +329,47 @@ export class CompanionClient {
      *  Called automatically when a connectCall() handle is closed; call it directly
      *  when a non-voice session ends. Best-effort + idempotent (safe to call twice;
      *  uses keepalive so it survives a page unload). Pass the voice transcript when
-     *  you have it (connectCall does this for you). */
+     *  you have it (connectCall does this for you).
+     *
+     *  Returns the server's consolidation diagnostic — `{ ok, facts?, skipped? }`
+     *  — or `null` if there was no session or the (swallowed) keepalive request
+     *  failed. `skipped` tells you WHY nothing was written: `'no_session'` (you
+     *  passed the instance id, not the session id), `'no_content'` (empty turn log
+     *  / a voice transcript that never arrived), `'throttled'` (a duplicate end
+     *  beacon — harmless). `facts` is how many memories were consolidated. */
     async endSession(opts) {
         const id = this._session;
         if (!id)
-            return;
+            return null;
         // Cap the payload (fetch keepalive bodies are size-limited): last 60 lines.
         const transcript = (opts?.transcript ?? [])
             .filter((t) => t && typeof t.text === 'string' && t.text.trim())
             .slice(-60)
             .map((t) => ({ role: t.role, text: t.text.slice(0, 500) }));
         try {
-            await this.doFetch(this.url(`/api/companion/session/${id}/end`), {
+            const res = await this.doFetch(this.url(`/api/companion/session/${id}/end`), {
                 method: 'POST',
                 headers: this.jsonHeaders(),
                 body: JSON.stringify({ transcript }),
                 keepalive: true
             });
+            return (await res.json().catch(() => null));
         }
         catch {
             /* best-effort — memory consolidation is not on the user's critical path */
+            return null;
         }
     }
+    /** Tear the session down in one call: stop the event stream and consolidate
+     *  memory (endSession) exactly once. The single teardown entry point for a
+     *  NON-voice (text) session — mirror of what a connectCall() handle's close()
+     *  does for voice. Idempotent. Returns endSession's diagnostic (or null).
+     *  NOTE: if you drive `ping()` on your own timer for a background tab, clear
+     *  that timer yourself — the client doesn't own it. */
+    async close() {
+        this.stop();
+        return this.endSession();
+    }
     /** Report the result of a companion.tool_call this surface performed. When all
      *  of the turn's calls are reported, the companion resumes and the continuation
      *  (a companion.message or more tool calls) arrives on the event stream. */
@@ -650,8 +678,14 @@ export class CompanionClient {
      *  approval the recorded action runs server-side; its result comes back as
      *  `outcome` in this response (render it where the user tapped) AND as a
      *  normal companion.message on the stream (so the conversation shows it).
-     *  A denial returns/emits a brief decline the same way. One-time:
-     *  re-resolving a settled confirmId fails with 409. */
+     *  A denial returns/emits a brief decline the same way. Single-use:
+     *  re-resolving a settled confirmId fails with 409.
+     *
+     *  RETRY: if an approved IDEMPOTENT action (a wallet payment) flakes on a
+     *  transient error, `status` is `'exec_failed'` and `retryable` is true — you
+     *  MAY call `confirmAction(sameConfirmId, true)` again to re-run it (the server
+     *  dedupes a partial first attempt). A non-idempotent action (a message / skill)
+     *  stays terminal and is never retryable. */
     async confirmAction(confirmId, approve) {
         const sessionId = this.requireSession();
         return this.postJson(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`, { confirmId, approve });

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { CompanionClient, type CompanionClientOptions } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
-export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, BrandIconSize } from './client.js';
+export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, BrandIconSize, EndSessionResult } from './client.js';
 export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
 export type { CompanionCall, CompanionCallOptions, VoiceToolBridge } from './call.js';
 export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload } from './protocol.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Embed the Pouchy companion — chat, voice, tools, memory, live world-state, instant UI, and agent-to-agent messaging — in any app, game, or site.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",