@pouchy_ai/companion-sdk 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -12,6 +12,28 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-07-11
+
+### Added
+
+- `client.getWallet(): Promise<CompanionWallet>` and the `GET /api/companion/wallet`
+  endpoint — read the companion instance's OWN wallet (nonzero stablecoin
+  balances + total USD). Read-only and receive-only; requires the `wallet.read`
+  scope (or `wallet.spend`, which subsumes it). Shares its read path with the
+  conversational `get_wallet_balance` tool so the endpoint and the in-chat answer
+  can never diverge. New exported types `CompanionWallet` / `WalletBalance`.
+
+## [0.19.1] - 2026-07-10
+
+### Documentation
+
+- README gains a client-method reference table (memory ingest, history,
+  setModalities, ping, pendingConfirms/confirmAction incl. the
+  exec_failed/retryable retry contract, endSession skipped reasons, close(),
+  startCall/connectCall, getAvatar/brandIconUrl) plus a note on
+  HOST_CONTROL_TOOLS and AVATAR_VISUAL_TOOLS (declare-or-silent-no-op).
+  No code change.
+
 ## [0.19.0] - 2026-07-10
 
 ### Added

package/README.md

@@ -72,11 +72,11 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | `onInterfaceUpdate(fn)` | `companion.ui_update` | live `{key,value}` update to an already-rendered panel (no rebuild) |
 | `onSocialMessage(fn)` | `companion.social_message` | inbound A2A friend message, delivered cross-app. Needs `social.message` |
 | `onConfirmRequest(fn)` | `companion.confirm_request` | a sensitive-op approval request. **Platform session tokens** (your end users): show your own confirm card and resolve it with `confirmAction` — this is how confirm-gated custom skills (POST / credentialed) run. First-party user tokens: observe-only — approval stays first-party (where the `stepUp:true` biometric gate lives) |
-| `onAudio(fn)` | `companion.audio` | TTS clip (non-call modality) |
-| `onExpression(fn)` | `companion.expression` | avatar viseme / expression / gesture |
+| `onAudio(fn)` | `companion.audio` | TTS clip (non-call modality). _(reserved — not emitted yet)_ |
+| `onExpression(fn)` | `companion.expression` | avatar viseme / expression / gesture. _(reserved — not emitted yet)_ |
 | `onVoiceInject(fn)` | `companion.voice_inject` | `fn({text, speak})` — a `voiceRelevant` world-state line to say aloud during a live call; route `text` to your voice session when `speak` |
 | `onTyping(fn)` | `companion.typing` | activity indicator — `fn({active})` fires `true` when a turn starts working and `false` when it finishes / pauses, spanning the tool-loop / thinking phase before the first text delta. Drive a "typing…" state |
-| `onUsage(fn)` | `control.usage` | per-token metering echo |
+| `onUsage(fn)` | `control.usage` | per-token metering echo. _(reserved — not emitted yet)_ |
 | `onError(fn)` | `control.error` | agent / stream errors |
 
 ### Instant UI
@@ -92,6 +92,29 @@ Reference renderers ship in [`examples/`](../../examples): `web-instant-ui` (van
 `native-instant-ui` (SwiftUI + Jetpack Compose), and `cli-skills` (terminal +
 local/device skills).
 
+## Client methods (beyond the quickstart)
+
+| Method | What it does |
+|---|---|
+| `recall(query)` / `remember(text)` | Read / write the token-scoped memory namespace. |
+| `ingestKnowledge(text, opts?)` / `ingestFile(file)` | Push documents into the user's knowledge base ("My materials"); needs `memory.write:core`. |
+| `history(limit?)` | Fetch the session transcript — restore chat on reload. |
+| `setModalities([...])` | Switch active I/O mid-session (within the token's grant). |
+| `ping()` | Keepalive for long-idle embeds. |
+| `pendingConfirms()` / `confirmAction(id, approve)` | List / resolve pending sensitive-action confirms (platform session tokens). On `{ status: 'exec_failed', retryable: true }` you MAY re-call the same confirmId — idempotent actions only. |
+| `endSession()` | Distill the session into durable memory now; returns `{ skipped?: 'no_session' \| 'no_content' \| 'throttled' }`. |
+| `close()` | One-call teardown: `stop()` + `endSession()` — the text-session mirror of the call handle's `close()`. |
+| `startCall(opts)` / `connectCall(opts)` | Voice plane: raw credentials / fully-wired call handle (`call.close()` ends + folds the transcript into memory). |
+| `getAvatar()` / `brandIconUrl(size?)` | The user's avatar (VRM/portrait) and the Pouchy brand icon for your UI. |
+| `getWallet()` | Read the instance's own wallet — `{ balances: [{ currency, amount }], totalUsd, currency }`. Read-only + receive-only; needs the `wallet.read` scope. |
+
+Tool calling beyond your own declared tools: `HOST_CONTROL_TOOLS` (universal
+verbs — `invoke_action`, `set_feature`, `set_value`, `navigate`, `highlight`)
+are offered automatically once you declare `tools`/`handles`, and
+`AVATAR_VISUAL_TOOLS` (`play_gesture` / `play_expression`) let avatar-rendering
+embeds receive expression cues — declare them or they no-op silently. Full
+contract: `docs/companion-host-control.md`.
+
 ## Scopes (typed)
 
 The full capability-scope vocabulary ships as typed constants — no more

package/dist/client.d.ts

@@ -123,6 +123,23 @@ export interface CompanionAvatar {
      *  built-ins today (reserved for custom previews / server-rendered thumbs). */
     imageUrl: string | null;
 }
+/** One nonzero stablecoin balance line. */
+export interface WalletBalance {
+    /** Stablecoin code (USDT / USDC / DAI / USD1). */
+    currency: string;
+    /** Decimal amount as a string (not atomic units), e.g. "5.83". */
+    amount: string;
+}
+/** Read-only snapshot of the companion instance's OWN wallet (receive-only —
+ *  there is no way to move funds via the SDK). Requires the `wallet.read` scope. */
+export interface CompanionWallet {
+    /** Nonzero per-currency balances (empty when the wallet is empty). */
+    balances: WalletBalance[];
+    /** Total across the balances; the allowed stablecoins are USD-pegged 1:1. */
+    totalUsd: number;
+    /** Denomination of `totalUsd` (always "USD" today). */
+    currency: string;
+}
 /** 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
@@ -392,6 +409,12 @@ export declare class CompanionClient {
      *  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>;
+    /** Read the companion instance's OWN wallet — nonzero stablecoin balances +
+     *  total USD. Read-only and receive-only (spends go through the confirm-gated
+     *  pay tools, never here). Requires the `wallet.read` scope (or `wallet.spend`,
+     *  which subsumes it). Same data the companion gives when asked "what's my
+     *  balance?". */
+    getWallet(): Promise<CompanionWallet>;
     /** 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,

package/dist/client.js

@@ -593,6 +593,25 @@ export class CompanionClient {
             imageUrl: json.imageUrl ?? null
         };
     }
+    /** Read the companion instance's OWN wallet — nonzero stablecoin balances +
+     *  total USD. Read-only and receive-only (spends go through the confirm-gated
+     *  pay tools, never here). Requires the `wallet.read` scope (or `wallet.spend`,
+     *  which subsumes it). Same data the companion gives when asked "what's my
+     *  balance?". */
+    async getWallet() {
+        const res = await this.doFetch(this.url('/api/companion/wallet'), {
+            headers: { Authorization: `Bearer ${this.opts.token}` }
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json || json.ok === false) {
+            throw new CompanionError(json?.error || `wallet fetch failed (${res.status})`, res.status);
+        }
+        return {
+            balances: json.balances ?? [],
+            totalUsd: json.totalUsd ?? 0,
+            currency: json.currency ?? 'USD'
+        };
+    }
     /** 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,

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, EndSessionResult } from './client.js';
+export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, 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 { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope } from './scopes.js';

package/dist/protocol.d.ts

@@ -2,7 +2,13 @@ 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). */
+/** Pouchy → app (control/data plane).
+ *  NOTE: three types are RESERVED — part of the vocabulary + typed handlers, but
+ *  the server does NOT emit them yet, so `onAudio` / `onExpression` / `onUsage`
+ *  are safe to register but won't fire until a producer ships. Don't build a UX
+ *  that depends on them today. (companion.audio → non-call reply TTS;
+ *  companion.expression → avatar viseme/expression cues; control.usage →
+ *  per-turn usage-metering echo.) */
 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", "companion.typing", "control.call_ready", "control.error", "control.usage"];
 export type OutboundType = (typeof OUTBOUND_TYPES)[number];
 export type MessageType = InboundType | OutboundType;

package/dist/protocol.js

@@ -17,20 +17,26 @@ export const INBOUND_TYPES = [
     'control.set_modalities',
     'control.ping'
 ];
-/** Pouchy → app (control/data plane). */
+/** Pouchy → app (control/data plane).
+ *  NOTE: three types are RESERVED — part of the vocabulary + typed handlers, but
+ *  the server does NOT emit them yet, so `onAudio` / `onExpression` / `onUsage`
+ *  are safe to register but won't fire until a producer ships. Don't build a UX
+ *  that depends on them today. (companion.audio → non-call reply TTS;
+ *  companion.expression → avatar viseme/expression cues; control.usage →
+ *  per-turn usage-metering echo.) */
 export const OUTBOUND_TYPES = [
     'hello.ack',
     'companion.message',
-    'companion.audio',
+    'companion.audio', // reserved — not emitted yet
     'companion.tool_call',
     'companion.ui_action',
     'companion.ui_update',
-    'companion.expression',
+    'companion.expression', // reserved — not emitted yet
     'companion.voice_inject',
     'companion.confirm_request',
     'companion.social_message',
     'companion.typing',
     'control.call_ready',
     'control.error',
-    'control.usage'
+    'control.usage' // reserved — not emitted yet
 ];

package/dist/scopes.js

@@ -21,7 +21,7 @@ export const COMPANION_SCOPES = [
     'memory.read:core', // read the shared global brain (SENSITIVE)
     'memory.write:core', // write into the shared global brain (SENSITIVE)
     'skills.execute', // run the user's installed skills (SENSITIVE)
-    'wallet.read', // READ-ONLY wallet: balance + own deposit address (receive-only; not sensitive)
+    'wallet.read', // READ-ONLY wallet: balance + own deposit address (receive-only; not sensitive). Surfaced via the companion's wallet tools (ask it) — no standalone REST endpoint.
     'wallet.spend', // spend from the Care Wallet (SENSITIVE)
     'social.message', // message friends via A2A (SENSITIVE)
     // ── Representative ("on-behalf-of") plane ─────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.19.0",
+  "version": "0.20.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",