@pouchy_ai/companion-sdk 0.10.0

package/dist/client.d.ts

@@ -0,0 +1,366 @@
+import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, RenderInterfacePayload, SocialMessagePayload, UsagePayload, WorldStateEvent } from './protocol.js';
+/** Ergonomic world-state input: a WorldStateEvent with the CloudEvents plumbing
+ *  (specversion / id / source) optional — sendWorldState fills them. */
+export type WorldStateInput<D = unknown> = Omit<WorldStateEvent<D>, 'specversion' | 'id' | 'source'> & Partial<Pick<WorldStateEvent<D>, 'specversion' | 'id' | 'source'>>;
+import { type CompanionCall, type CompanionCallOptions } from './call.js';
+export interface CompanionClientOptions {
+    /** Origin of the Pouchy deployment, e.g. "https://www.pouchy.ai". */
+    baseUrl: string;
+    /** A Pouchy access token (PAT). */
+    token: string;
+    /** Logical surface (one resumable session per surface), default "default". */
+    surface?: string;
+    /** Requested I/O modalities (intersected with the token's grant server-side). */
+    modalities?: string[];
+    /** Action types this surface can perform (declared at handshake). */
+    handles?: string[];
+    /** World-state kinds this surface emits (declared at handshake). */
+    contextKinds?: string[];
+    /** Tools the companion may ask this surface to perform (companion.tool_call). */
+    tools?: CompanionToolDecl[];
+    /** Static description of THIS app/game so the companion is grounded in where it
+     *  is (drives reasoning + the call opener). Live state still flows via
+     *  sendWorldState. */
+    appContext?: {
+        name?: string;
+        description?: string;
+    };
+    /** Open a REPRESENTATIVE ("on-behalf-of" / 代聊) session: the companion fields
+     *  this VISITOR's messages on the owner's behalf — customer-service style —
+     *  drawing only on screened owner context (persona + share-screened facts, plus
+     *  the knowledge base when the owner's token grants `expose:knowledge`). Each
+     *  visitor (stable opaque `id`, 8-64 url-safe chars that YOU keep stable per
+     *  end-user) gets their own continuous thread. Requires the token's `represent`
+     *  scope — without it the handshake is rejected (never silently downgraded to an
+     *  owner-facing session). */
+    visitor?: {
+        id: string;
+        displayName?: string;
+    };
+    /** Injectable fetch (for Node < 18 / tests). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Receive transport for the reply stream. 'sse' (default) works on every
+     *  deploy; 'websocket' opts into the lower-latency WS plane when the host
+     *  supports it (adapter-node / a WS gateway) and falls back to SSE if the
+     *  socket can't open — so enabling it can never stop reply delivery. */
+    stream?: 'sse' | 'websocket';
+    /** Injectable WebSocket constructor (Node without a global WebSocket, or
+     *  tests). Defaults to globalThis.WebSocket when present. */
+    webSocketImpl?: typeof WebSocket;
+}
+export interface HelloAck {
+    session: string;
+    grantedScopes: string[];
+    modalities: string[];
+    resumeCursor: number;
+    /** True when this is a representative (visitor-facing) session — i.e. a
+     *  `visitor` was supplied and the token holds `represent`. */
+    representative: boolean;
+    /** Representative sessions only: whether this visitor is already paired with
+     *  the owner (their two companions are friends). Lets you skip offering a
+     *  "pair" affordance to an already-connected visitor. */
+    visitorPaired: boolean;
+}
+/** A tool the embedding declares the companion may ask it to perform. */
+export interface CompanionToolDecl {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+/** Voice-plane credentials, discriminated by provider (see startCall). */
+export type CallCredentials = {
+    provider: 'elevenlabs-convai';
+    /** EL conversation token (open WebRTC with @elevenlabs/client). */
+    token: string;
+    agentId: string;
+    /** Pass as overrides.agent.prompt.prompt when starting the EL session. */
+    instructions: string;
+    /** Server-resolved EL voice id (the user's cloned/localized voice). Pass
+     *  as overrides.tts.voiceId so the call isn't a stock default voice. */
+    voice?: string;
+    /** Server-resolved agent language (ISO 639-1, e.g. 'zh'). Pass as
+     *  overrides.agent.language so the call opens in the user's language. */
+    language?: string;
+    /** First-message override ('' = suppress the canned greeting so the call
+     *  opens in-character / context-aware). Pass as overrides.agent.firstMessage. */
+    firstMessage?: string;
+} | {
+    provider: 'openai-realtime';
+    /** Ephemeral client secret (ek_…); open WebRTC directly to OpenAI. */
+    clientSecret: string;
+    model: string;
+    voice: string;
+    expiresAt: number | null;
+};
+export interface RecalledMemory {
+    content: string;
+    category?: string;
+    kind?: string;
+    importance: number;
+    namespace: string;
+    createdAt?: string;
+}
+/** The user's current companion avatar (see getAvatar). */
+export interface CompanionAvatar {
+    /** Companion display name (the user's chosen name), or null. */
+    name: string | null;
+    /** Persona archetype driving the default look/voice. */
+    archetype: 'girlfriend' | 'boyfriend' | 'pet';
+    /** The active model id (e.g. "default-gf-luna", or a custom id), or null. */
+    modelId: string | null;
+    /** Absolute URL to the VRM 3D model — the avatar itself. CORS-enabled so a
+     *  cross-origin renderer can fetch it. Null only if resolution failed. */
+    vrmUrl: string | null;
+    /** Absolute URL to a flat 2D portrait when available; null for VRM-only
+     *  built-ins today (reserved for custom previews / server-rendered thumbs). */
+    imageUrl: string | null;
+}
+/** Available sizes for the Pouchy brand icon (px). */
+export type BrandIconSize = 256 | 512 | 1024;
+/** Canonical URL of the official Pouchy brand icon at `size` px, derived from a
+ *  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;
+export declare class CompanionError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+type Handler = (envelope: CompanionEnvelope) => void;
+export declare class CompanionClient {
+    private readonly opts;
+    private readonly doFetch;
+    private _session;
+    private cursor;
+    private streaming;
+    private abort;
+    private readonly handlers;
+    private readonly seen;
+    private readonly pendingVoiceTools;
+    constructor(opts: CompanionClientOptions);
+    /** The active session id, or null before connect(). */
+    get sessionId(): string | null;
+    private url;
+    private jsonHeaders;
+    private requireSession;
+    private postJson;
+    /** Handshake: start or resume the session for this surface. */
+    connect(): Promise<HelloAck>;
+    /** Pair this representative session's VISITOR with the owner so their two
+     *  companions become friends — unlocking the A2A plane (messaging, gifts,
+     *  visiting) between them. Only valid in a representative session (the client
+     *  was created with a `visitor`).
+     *
+     *  Two-token consent: this client's PAT (the owner's) must hold `represent:pair`,
+     *  and you pass the VISITOR's own Pouchy PAT — which must hold `social.message`
+     *  — as proof + consent. The visitor must therefore also be a Pouchy user. */
+    pairVisitor(visitorToken: string): Promise<{
+        pairId: string | null;
+    }>;
+    /** Send a user text turn, optionally with images (data URLs) for a multimodal
+     *  turn — images need the `files` scope. The reply arrives on the event stream
+     *  as a `companion.message` — subscribe via onMessage()/start() to receive it. */
+    sendText(text: string, opts?: {
+        images?: string[];
+    }): Promise<{
+        seq: number | null;
+    }>;
+    /** Push live world-state — a single event or a batch. Retained events
+     *  (retained:true) coalesce per kind; transient ones carry a salience.
+     *
+     *  Ergonomic input: `specversion` / `id` / `source` are filled automatically
+     *  (id → a fresh handle, source → this surface), so callers only supply the
+     *  meaningful fields: `{ type, data, retained?, salience?, voiceRelevant? }`.
+     *  A full CloudEvents envelope is still accepted (its fields win). */
+    sendWorldState(event: WorldStateInput | WorldStateInput[]): Promise<{
+        accepted: number;
+        dropped: number;
+    }>;
+    private randomId;
+    /** Open the voice plane. Returns realtime credentials to connect DIRECTLY to
+     *  the voice provider (the Pouchy server is out of the audio path). Provider
+     *  precedence is server-side: ElevenLabs Convai (primary) → OpenAI Realtime
+     *  (fallback). Requires the `call` scope.
+     *
+     *  - `elevenlabs-convai`: open the EL session with the returned `token` and
+     *    pass `instructions` as `overrides.agent.prompt.prompt` (the EL agent runs
+     *    EL's LLM, so the persona/memory snapshot rides in client-side).
+     *  - `openai-realtime`: open WebRTC with the short-lived `clientSecret`
+     *    (instructions are baked into the session server-side).
+     */
+    startCall(opts?: {
+        voice?: string;
+        locale?: string;
+    }): Promise<CallCredentials>;
+    /** Open a live voice call end-to-end: mints credentials (startCall) and opens a
+     *  WebRTC session directly to the provider — no first-party app code needed.
+     *  Browser-only. Returns a handle to hang up + inject live context. EL Convai
+     *  needs the optional '@elevenlabs/client' peer dependency; OpenAI Realtime has
+     *  no extra deps. */
+    connectCall(opts?: CompanionCallOptions & {
+        voice?: string;
+        locale?: string;
+    }): Promise<CompanionCall>;
+    /** End the session: consolidate what happened into the companion's long-term
+     *  memory, so it remembers this experience in future first-party conversations.
+     *  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). */
+    endSession(opts?: {
+        transcript?: {
+            role: string;
+            text: string;
+        }[];
+    }): Promise<void>;
+    /** 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. */
+    sendToolResult(callId: string, result: {
+        ok?: boolean;
+        result?: unknown;
+    }): Promise<{
+        allDone: boolean;
+    }>;
+    /** A tool the live voice call asked the app to run. Fires the SAME
+     *  companion.tool_call event the text flow uses (so the app's onToolCall +
+     *  sendToolResult handle voice identically), and resolves with the result
+     *  string fed back to the voice model. Times out so a missing result can't
+     *  hang the call. */
+    private invokeVoiceTool;
+    /** Convenience: subscribe to tool-call requests from the companion. */
+    onToolCall(handler: (call: {
+        id: string;
+        name: string;
+        args: string;
+    }, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to errors the companion surfaces — server-side agent
+     *  errors and stream failures (e.g. a permanent `stream_unauthorized`) both
+     *  arrive as `control.error`. Returns an unsubscribe fn. */
+    onError(handler: (err: {
+        code: string;
+        message: string;
+    }, envelope: CompanionEnvelope) => void): () => void;
+    /** Recall the memory this token is authorized to see (ranked). */
+    recall(opts?: {
+        limit?: number;
+    }): Promise<RecalledMemory[]>;
+    /** Remember a fact (into this app's namespace unless `namespace` is given and
+     *  the token has the core scope). Intimate-tier writes are rejected server-side. */
+    remember(fact: {
+        content: string;
+        importance?: number;
+        confidence?: number;
+        category?: string;
+        kind?: string;
+        namespace?: string;
+        sensitivity?: 'public' | 'personal';
+    }): Promise<{
+        cloudId: string;
+        namespace: string;
+    }>;
+    /** Ingest a DOCUMENT into the user's knowledge base. Unlike `remember` (one
+     *  short fact), this distils already-extracted text — a PDF body, a meeting
+     *  transcript, notes — into a headline summary PLUS full-text chunks, each
+     *  embedded and semantically recallable, and surfaces it in the user's "My
+     *  materials" list with source attribution, exactly like a first-party upload.
+     *  So the materials entry point can live in YOUR app, not just Pouchy's.
+     *
+     *  Extract the text yourself (your own parser, or Pouchy's /api/stt for audio)
+     *  and pass it here. Writes the user's SHARED knowledge, so the token must
+     *  hold `memory.write:core` (the user's consent) — otherwise 403. Embeddings
+     *  are computed on the user's next first-party open (eventually-consistent
+     *  semantic recall). `kind` is a free label for the source type (pdf / audio /
+     *  note / …) used only for display + the materials icon. */
+    ingestKnowledge(doc: {
+        text: string;
+        name: string;
+        kind?: string;
+        locale?: string;
+    }): Promise<{
+        ok: boolean;
+        summary: string;
+        chunks: number;
+    }>;
+    /** Convenience over `ingestKnowledge`: hand over a RAW file and Pouchy
+     *  understands it server-side before ingesting — no parser/transcriber/vision on
+     *  your side. Pass a `data:<mime>;base64,…` URL. Supported today: **PDF**
+     *  (server-side text extraction), **audio/video** (Whisper transcript), and
+     *  **image** (server-side vision caption — an objective description becomes the
+     *  material). For other types, extract the text yourself and call
+     *  `ingestKnowledge`. Same `memory.write:core` requirement and "My materials"
+     *  integration as `ingestKnowledge`. */
+    ingestFile(file: {
+        dataUrl: string;
+        name: string;
+        kind?: string;
+        locale?: string;
+    }): Promise<{
+        ok: boolean;
+        summary: string;
+        chunks: number;
+    }>;
+    /** Fetch the user's CURRENT companion avatar so the embedding can render the
+     *  same virtual human Pouchy shows. The avatar is a VRM 3D model (`vrmUrl`,
+     *  load it with a VRM/glTF renderer e.g. three-vrm); `imageUrl` is a flat 2D
+     *  portrait when one exists (null today for built-in models). URLs are absolute
+     *  and the /models asset is CORS-enabled, so a cross-origin renderer can fetch
+     *  the VRM directly. Reflects the user's live choice (built-in or custom). */
+    getAvatar(): Promise<CompanionAvatar>;
+    /** Canonical URL of the official Pouchy brand icon (square PNG, transparent
+     *  background) at the given size. Static + public — needs no token — so it's
+     *  safe to drop straight into an `<img src>` for "powered by Pouchy" badges,
+     *  the companion's app tile, etc. Sizes: 256 | 512 | 1024 (default 512). */
+    brandIconUrl(size?: BrandIconSize): string;
+    /** Subscribe to outbound events of a given type, or "*" for all. Returns an
+     *  unsubscribe function. */
+    on(type: OutboundType | '*', handler: Handler): () => void;
+    /** Convenience: subscribe to assistant text replies. */
+    onMessage(handler: (text: string, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to Instant UI render surfaces (companion.ui_action).
+     *  The host draws `payload.interface` with its OWN renderer — a web component, a
+     *  native iOS/Android view tree, a CLI/TUI — all consuming the same
+     *  platform-neutral genui schema. If the panel set `reportChanges`, feed the
+     *  user's edits back via `sendText`/`sendWorldState` to continue the turn. */
+    onRender(handler: (payload: RenderInterfacePayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to TTS audio clips for the reply (companion.audio,
+     *  non-call modality) — play `url`, or resolve `ref` your way. */
+    onAudio(handler: (payload: AudioClipPayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to avatar cues (companion.expression) — viseme /
+     *  expression / gesture for an embed rendering the companion's body. */
+    onExpression(handler: (payload: ExpressionPayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to the per-token metering echo (control.usage) for a
+     *  usage / billing view. */
+    onUsage(handler: (payload: UsagePayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: OBSERVE sensitive-op confirmation requests
+     *  (companion.confirm_request) — a payment, skill run, or friend message the
+     *  companion wants the user to approve. Use it to surface the pending approval
+     *  in your UI (e.g. "open Pouchy to approve"). NOTE: an embed cannot approve —
+     *  approval is authed as the first-party Pouchy user (their app / a hosted
+     *  confirm page), which is also where a biometric (Face ID / passkey) gate
+     *  lives. This handler is observe-only. */
+    onConfirmRequest(handler: (payload: ConfirmRequestPayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to live updates of an already-rendered Instant UI
+     *  panel (companion.ui_update). Apply each `{ key, value }` to the panel's state
+     *  bag and re-evaluate bound displays — no rebuild. */
+    onInterfaceUpdate(handler: (payload: InterfaceUpdatePayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to inbound A2A messages from the user's paired
+     *  friends (companion.social_message), delivered cross-app to any embed whose
+     *  token holds `social.message`. Surface them in your own UI / notify the user. */
+    onSocialMessage(handler: (payload: SocialMessagePayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Open the event stream (auto-reconnecting with the resume cursor). Uses the
+     *  WebSocket plane when opted in + available, else SSE. */
+    start(): void;
+    /** WebSocket receive loop. Resolves when the socket closes; on any failure
+     *  while still streaming it falls back to the SSE loop, so opting into WS can
+     *  only ever DEGRADE to SSE, never drop replies. Input is still sent over
+     *  REST (sendInput) — receiving is the latency-sensitive half. */
+    private wsLoop;
+    /** Stop the event stream. */
+    stop(): void;
+    private emit;
+    private handleFrame;
+    private loop;
+    private consume;
+    private sleep;
+}
+export {};