@pouchy_ai/companion-sdk 0.10.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { CompanionClient, type CompanionClientOptions } from './client.js';
+export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
+export type { CompanionClientOptions, HelloAck, RecalledMemory, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, BrandIconSize } from './client.js';
+export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES } from './call.js';
+export type { CompanionCall, CompanionCallOptions, VoiceToolBridge } from './call.js';
+export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, AudioClipPayload, ExpressionPayload, UsagePayload } from './protocol.js';
+/** Create a companion client. */
+export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/index.js

@@ -0,0 +1,17 @@
+// Companion SDK — public entry. Embed the Pouchy companion in a third-party
+// surface (web / app / game / hardware) over the REST/SSE plane.
+//
+//   import { createCompanion } from '$lib/companion-sdk';
+//   const c = createCompanion({ baseUrl: 'https://www.pouchy.ai', token: PAT });
+//   await c.connect();
+//   c.onMessage((text) => console.log(text));
+//   c.start();
+//   c.sendWorldState({ type: 'game.scene', data: 'tavern', retained: true });
+//   await c.sendText('what should I do?');
+import { CompanionClient } from './client.js';
+export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
+export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES } from './call.js';
+/** Create a companion client. */
+export function createCompanion(opts) {
+    return new CompanionClient(opts);
+}

package/dist/protocol.d.ts

@@ -0,0 +1,124 @@
+export declare const PROTOCOL_VERSION: 1;
+/** App → Pouchy (control/data plane). */
+export declare const INBOUND_TYPES: readonly ["hello", "input.text", "context.event", "context.snapshot", "tool.result", "control.start_call", "control.end_call", "control.set_modalities", "control.ping"];
+export type InboundType = (typeof INBOUND_TYPES)[number];
+/** Pouchy → app (control/data plane). */
+export declare const OUTBOUND_TYPES: readonly ["hello.ack", "companion.message", "companion.audio", "companion.tool_call", "companion.ui_action", "companion.ui_update", "companion.expression", "companion.voice_inject", "companion.confirm_request", "companion.social_message", "control.call_ready", "control.error", "control.usage"];
+export type OutboundType = (typeof OUTBOUND_TYPES)[number];
+export type MessageType = InboundType | OutboundType;
+/** The single envelope every control/data-plane message shares. */
+export interface CompanionEnvelope<T = unknown> {
+    v: typeof PROTOCOL_VERSION;
+    id: string;
+    session?: string;
+    ts: number;
+    type: MessageType;
+    payload: T;
+}
+/** Payload of a `companion.ui_action` event — an Instant UI surface for the host
+ *  to render. `interface` is the platform-neutral genui schema: a tree of UI
+ *  `nodes` (Text/Slider/Button/Chart/…), an optional `state` bag input atoms
+ *  read+write, and optional `computed` derived values. The SAME shape is drawn by
+ *  a web embed, a native iOS/Android renderer, or a CLI/TUI — only the renderer
+ *  differs per platform, never the contract. Kept structurally loose here (the
+ *  SDK package carries no $lib import); the authoritative schema lives in
+ *  src/lib/genui/schema.ts and the renderer-contract doc. When the panel sets
+ *  `reportChanges`, the user's edits stream back as a normal text turn. */
+export interface RenderInterfacePayload {
+    interface: {
+        title?: string;
+        nodes: Array<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+        state?: Record<string, string | number | boolean>;
+        computed?: Record<string, unknown>;
+        reportChanges?: boolean;
+    };
+}
+/** Payload of a `companion.confirm_request` event — the companion is asking the
+ *  user to approve a sensitive op (a payment, a skill run, a friend message).
+ *  An embed may OBSERVE this to surface the pending approval in its own UI, but
+ *  it CANNOT approve: approval is authed as the first-party Pouchy user (their
+ *  app / a hosted confirm page), so a third-party DOM can never confirm a spend.
+ *  A first-party native host can gate that approval behind a biometric (Face ID
+ *  / passkey) — see docs/companion-wallet-noncustodial.md. */
+export interface ConfirmRequestPayload {
+    /** Opaque id the first-party surface passes to the confirm endpoint. */
+    confirmId: string;
+    /** The scope of the op needing approval (e.g. `wallet.spend`). */
+    scope: string;
+    /** A human, user-facing summary of what approving will do. */
+    summary: string;
+    /** Advisory: when true, the first-party approval surface should require a
+     *  stronger user gesture — a biometric / passkey (Face ID, Touch ID) — before
+     *  approving, not just a tap. Set for irreversible money ops (wallet.spend).
+     *  Cryptographic enforcement is server-side follow-up; this is the host's cue. */
+    stepUp?: boolean;
+}
+/** Payload of a `companion.ui_update` event — a live change to an
+ *  already-rendered Instant UI panel: write each `{ key, value }` into the
+ *  panel's state bag (re-evaluating templates / progress / `when`), without
+ *  rebuilding. `panelId` targets one of several on-screen panels when present. */
+export interface InterfaceUpdatePayload {
+    update: {
+        panelId?: string;
+        updates: Array<{
+            key: string;
+            value: string | number | boolean;
+        }>;
+    };
+}
+/** Payload of a `companion.audio` event — a TTS clip for the assistant's reply on
+ *  a non-call modality. Either a playable `url` or an opaque `ref` the host
+ *  resolves. */
+export interface AudioClipPayload {
+    url?: string;
+    ref?: string;
+}
+/** Payload of a `companion.expression` event — avatar cues for an embed rendering
+ *  the companion's body (e.g. a VRM): a lip-sync `viseme`, an `expression`, or a
+ *  `gesture`. A pure-text/audio host can ignore it. */
+export interface ExpressionPayload {
+    viseme?: string;
+    expression?: string;
+    gesture?: string;
+}
+/** Payload of a `control.usage` event — a per-token metering echo the host can
+ *  surface in a usage/billing view. */
+export interface UsagePayload {
+    chatTurns?: number;
+    voiceSeconds?: number;
+    memoryOps?: number;
+}
+/** Payload of a `companion.social_message` event — an inbound A2A message from
+ *  one of the user's paired friends, delivered cross-app to any live embed whose
+ *  token holds `social.message`. Lets a native/web host surface friend messages
+ *  in real time without the first-party Pouchy app. Only plain human messages are
+ *  delivered (Pouchy-internal structured envelopes are not). */
+export interface SocialMessagePayload {
+    /** The sender's Pouchy uid. */
+    fromUid: string;
+    /** The sender's display name. */
+    fromName: string;
+    /** The message text. */
+    content: string;
+    /** ISO timestamp of delivery. */
+    createdAt: string;
+}
+/** A live world-state event the app streams in. `retained:true` = latest-value
+ *  state (coalesced); `retained:false` = a transient moment carrying `salience`
+ *  and optional `voiceRelevant`. */
+export interface WorldStateEvent<D = unknown> {
+    specversion: '1.0';
+    id: string;
+    source: string;
+    /** Namespaced dotted kind, e.g. `game.player.hp`, `game.event.boss_spawned`. */
+    type: string;
+    time?: string;
+    data: D;
+    retained?: boolean;
+    ttl?: number;
+    salience?: number;
+    voiceRelevant?: boolean;
+}

package/dist/protocol.js

@@ -0,0 +1,35 @@
+// The wire contract, as the SDK sees it — a self-contained copy so the package
+// has ZERO repo-internal ($lib) imports and publishes / builds with plain tsc.
+//
+// This mirrors the server's source of truth (src/lib/types/companion-protocol.ts);
+// a drift test (protocol.drift.test.ts) keeps PROTOCOL_VERSION + the type unions
+// in sync. Adding an outbound type is non-breaking (receivers ignore unknowns).
+export const PROTOCOL_VERSION = 1;
+/** App → Pouchy (control/data plane). */
+export const INBOUND_TYPES = [
+    'hello',
+    'input.text',
+    'context.event',
+    'context.snapshot',
+    'tool.result',
+    'control.start_call',
+    'control.end_call',
+    'control.set_modalities',
+    'control.ping'
+];
+/** Pouchy → app (control/data plane). */
+export const OUTBOUND_TYPES = [
+    'hello.ack',
+    'companion.message',
+    'companion.audio',
+    'companion.tool_call',
+    'companion.ui_action',
+    'companion.ui_update',
+    'companion.expression',
+    'companion.voice_inject',
+    'companion.confirm_request',
+    'companion.social_message',
+    'control.call_ready',
+    'control.error',
+    'control.usage'
+];

package/dist/sse.d.ts

@@ -0,0 +1,12 @@
+export interface SseEvent {
+    /** The `event:` field; defaults to "message" per the SSE spec. */
+    event: string;
+    /** The joined `data:` field(s). */
+    data: string;
+}
+/** Parse all COMPLETE frames out of an accumulated buffer. Returns the parsed
+ *  events plus the unparsed remainder (an incomplete trailing frame). */
+export declare function parseSse(buffer: string): {
+    events: SseEvent[];
+    rest: string;
+};

package/dist/sse.js

@@ -0,0 +1,38 @@
+// Minimal, dependency-free SSE frame parser for the companion SDK. The browser's
+// EventSource can't set an Authorization header, so the SDK consumes the stream
+// over fetch() instead and parses frames itself — this is that parser, kept pure
+// so it unit-tests in isolation.
+//
+// An SSE frame is a block of `field: value` lines terminated by a blank line.
+// Comment lines (starting ":") are keep-alives and ignored. A chunk off the wire
+// may end mid-frame, so the parser returns the leftover for the next call.
+/** Parse all COMPLETE frames out of an accumulated buffer. Returns the parsed
+ *  events plus the unparsed remainder (an incomplete trailing frame). */
+export function parseSse(buffer) {
+    const events = [];
+    let working = buffer.replace(/\r\n/g, '\n');
+    let sep = working.indexOf('\n\n');
+    while (sep !== -1) {
+        const block = working.slice(0, sep);
+        working = working.slice(sep + 2);
+        let event = 'message';
+        const dataLines = [];
+        for (const line of block.split('\n')) {
+            if (!line || line.startsWith(':'))
+                continue; // blank or comment (keep-alive)
+            const ci = line.indexOf(':');
+            const field = ci === -1 ? line : line.slice(0, ci);
+            let value = ci === -1 ? '' : line.slice(ci + 1);
+            if (value.startsWith(' '))
+                value = value.slice(1); // single leading space stripped
+            if (field === 'event')
+                event = value;
+            else if (field === 'data')
+                dataLines.push(value);
+        }
+        if (dataLines.length)
+            events.push({ event, data: dataLines.join('\n') });
+        sep = working.indexOf('\n\n');
+    }
+    return { events, rest: working };
+}

package/dist/ws-transport.d.ts

@@ -0,0 +1,21 @@
+/** Build the WebSocket stream URL from the HTTP base. http→ws, https→wss. The
+ *  token rides the query string because browsers can't set an Authorization
+ *  header on a WebSocket handshake; the server authenticates it the same way it
+ *  authenticates the SSE `?cursor=` stream. `cursor` resumes after a reconnect,
+ *  mirroring the SSE plane. */
+export declare function deriveWsStreamUrl(baseUrl: string, sessionId: string, token: string, cursor?: number): string;
+/** Normalize an incoming WS message into the `{ event, data }` shape the SSE
+ *  frame handler already consumes, so both transports converge on one code
+ *  path. Accepts two wire forms:
+ *    1. a framed message: { "event": "...", "data": "<json string>" }
+ *    2. a bare envelope:  { "type": "...", ... }  → event defaults to "message"
+ *  Returns null for anything unparseable (the caller drops it). */
+export declare function decodeWsMessage(raw: string): {
+    event: string;
+    data: string;
+} | null;
+/** Frame an outbound user-input message for the WS plane (for hosts that also
+ *  accept input over the socket). Mirrors the REST `/input` body. */
+export declare function encodeWsInput(text: string, opts?: {
+    image?: string;
+}): string;

package/dist/ws-transport.js

@@ -0,0 +1,62 @@
+// Companion SDK — WebSocket transport helpers (pure core).
+//
+// The SDK streams replies over Server-Sent Events today; the client comment
+// always anticipated "when the WebSocket plane lands it slots in behind this
+// same interface". This module is that slot: pure, dependency-free helpers for
+// deriving the ws(s) URL and framing/parsing messages, so the live WS loop in
+// client.ts stays a thin wrapper and the framing logic is unit-testable.
+//
+// IMPORTANT — server support: a persistent WebSocket endpoint needs a
+// WS-capable host (adapter-node, or a standalone WS gateway). The default
+// serverless deploy (adapter-auto → Vercel/Netlify functions) can't hold an
+// open socket, so the client keeps SSE as the default and FALLS BACK to it if
+// the socket can't open. Self-hosters who run a WS gateway can opt in with
+// `stream: 'websocket'`. This file ships the deployment-agnostic client side.
+/** Build the WebSocket stream URL from the HTTP base. http→ws, https→wss. The
+ *  token rides the query string because browsers can't set an Authorization
+ *  header on a WebSocket handshake; the server authenticates it the same way it
+ *  authenticates the SSE `?cursor=` stream. `cursor` resumes after a reconnect,
+ *  mirroring the SSE plane. */
+export function deriveWsStreamUrl(baseUrl, sessionId, token, cursor = 0) {
+    const origin = baseUrl.replace(/\/+$/, '').replace(/^http(s?):\/\//i, (_m, s) => `ws${s}://`);
+    const id = encodeURIComponent(sessionId);
+    const q = new URLSearchParams({ cursor: String(cursor), token });
+    return `${origin}/api/companion/session/${id}/ws?${q.toString()}`;
+}
+/** Normalize an incoming WS message into the `{ event, data }` shape the SSE
+ *  frame handler already consumes, so both transports converge on one code
+ *  path. Accepts two wire forms:
+ *    1. a framed message: { "event": "...", "data": "<json string>" }
+ *    2. a bare envelope:  { "type": "...", ... }  → event defaults to "message"
+ *  Returns null for anything unparseable (the caller drops it). */
+export function decodeWsMessage(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    // Form 1 — explicit frame.
+    if (typeof obj.event === 'string') {
+        const data = typeof obj.data === 'string' ? obj.data : JSON.stringify(obj.data ?? {});
+        return { event: obj.event, data };
+    }
+    // Form 2 — bare envelope. Re-serialize so handleFrame can JSON.parse it back
+    // into a CompanionEnvelope exactly as the SSE path does.
+    if (typeof obj.type === 'string') {
+        return { event: 'message', data: raw };
+    }
+    return null;
+}
+/** Frame an outbound user-input message for the WS plane (for hosts that also
+ *  accept input over the socket). Mirrors the REST `/input` body. */
+export function encodeWsInput(text, opts) {
+    const payload = { type: 'input', text };
+    if (opts?.image)
+        payload.image = opts.image;
+    return JSON.stringify(payload);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pouchy_ai/companion-sdk",
+  "version": "0.10.0",
+  "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",
+  "homepage": "https://www.pouchy.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oviswang/Pouchy.git",
+    "directory": "packages/companion-sdk"
+  },
+  "bugs": {
+    "email": "support@pouchy.ai"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/fix-esm-extensions.mjs",
+    "build:cdn": "esbuild ../../src/lib/companion-sdk/index.ts --bundle --format=esm --platform=browser --external:@elevenlabs/client --legal-comments=none --outfile=cdn/companion-sdk.js && node scripts/cdn-banner.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@elevenlabs/client": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@elevenlabs/client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "typescript": "^5.5.0"
+  },
+  "keywords": ["pouchy", "ai-companion", "voice", "agent", "sdk"],
+  "publishConfig": {
+    "access": "public"
+  }
+}