@pouchy_ai/companion-sdk 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -12,6 +12,34 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-07-10
+
+### Added
+
+- **Typed scope vocabulary exported from the package.** `COMPANION_SCOPES` /
+  `CompanionScope`, `COMPANION_MODALITIES` / `CompanionModality`,
+  `SENSITIVE_SCOPES`, `REPRESENT_SCOPES`, `DEFAULT_SCOPES`,
+  `DEFAULT_MODALITIES`, and the helpers `isSensitiveScope()`,
+  `isRepresentScope()`, `hasScope(granted, required)`. Configure keys, gate
+  features on `hello.ack.grantedScopes`, and explain 403s with compile-checked
+  scope strings instead of prose-copied literals. Mirrors the server vocabulary
+  and is guarded by the same drift test as the wire protocol. Additive — no
+  wire-protocol change.
+
+## [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

package/README.md

@@ -92,6 +92,30 @@ Reference renderers ship in [`examples/`](../../examples): `web-instant-ui` (van
 `native-instant-ui` (SwiftUI + Jetpack Compose), and `cli-skills` (terminal +
 local/device skills).
 
+## Scopes (typed)
+
+The full capability-scope vocabulary ships as typed constants — no more
+copying scope strings from prose:
+
+```ts
+import {
+  COMPANION_SCOPES, SENSITIVE_SCOPES, DEFAULT_SCOPES,
+  hasScope, isSensitiveScope, type CompanionScope
+} from '@pouchy_ai/companion-sdk';
+
+const ack = await c.connect();
+if (!hasScope(ack.grantedScopes, 'skills.execute')) {
+  // hide the "run a skill" affordance instead of eating a 403
+}
+```
+
+`COMPANION_SCOPES` lists every scope a key can carry; `SENSITIVE_SCOPES` are
+the ones that are never on by default (money / skills / social / core memory /
+the representative plane); `DEFAULT_SCOPES` is what a fresh key gets. Also
+exported: `COMPANION_MODALITIES`, `REPRESENT_SCOPES`, `DEFAULT_MODALITIES`,
+`isRepresentScope()`. The list mirrors the server vocabulary and is guarded by
+the SDK's drift test.
+
 ## Representative mode (代聊)
 
 Pass a `visitor` and the session flips from **owner-facing** to **representative**:

package/dist/client.d.ts

@@ -438,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

@@ -678,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

@@ -3,6 +3,8 @@ export { CompanionClient, CompanionError, pouchyBrandIconUrl } 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 { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope } from './scopes.js';
+export type { CompanionScope, CompanionModality } from './scopes.js';
 export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload } from './protocol.js';
 /** Create a companion client. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/index.js

@@ -11,6 +11,7 @@
 import { CompanionClient } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
 export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
+export { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope } from './scopes.js';
 /** Create a companion client. */
 export function createCompanion(opts) {
     return new CompanionClient(opts);

package/dist/scopes.d.ts

@@ -0,0 +1,24 @@
+/** Every capability scope a Personal Access Token / OAuth grant can carry. */
+export declare const COMPANION_SCOPES: readonly ["chat", "voice", "call", "files", "events.subscribe", "worldstate.write", "ui.render", "memory.read:app", "memory.write:app", "memory.read:core", "memory.write:core", "skills.execute", "wallet.read", "wallet.spend", "social.message", "represent", "expose:knowledge", "expose:facts", "represent:pair", "represent:remember"];
+export type CompanionScope = (typeof COMPANION_SCOPES)[number];
+/** I/O modalities a key can carry alongside its scopes. */
+export declare const COMPANION_MODALITIES: readonly ["text", "voice", "call", "files"];
+export type CompanionModality = (typeof COMPANION_MODALITIES)[number];
+/** Sensitive scopes — never granted by default; the user opts in at key
+ *  creation, and execution still passes a confirm on a Pouchy-controlled
+ *  surface (see `companion.confirm_request`). */
+export declare const SENSITIVE_SCOPES: ReadonlySet<CompanionScope>;
+/** The representative ("on-behalf-of") plane — a distinct axis from the
+ *  execution scopes: one lets the companion ACT for the owner, the other lets
+ *  it REPRESENT the owner to an outside visitor. `represent` is the umbrella;
+ *  the `expose:*` / `represent:*` scopes only mean anything alongside it. */
+export declare const REPRESENT_SCOPES: ReadonlySet<CompanionScope>;
+/** What a freshly-generated key carries unless the user opts into more: a
+ *  chat/play companion confined to its own app memory namespace. */
+export declare const DEFAULT_SCOPES: readonly CompanionScope[];
+export declare const DEFAULT_MODALITIES: readonly CompanionModality[];
+export declare function isSensitiveScope(s: CompanionScope): boolean;
+export declare function isRepresentScope(s: CompanionScope): boolean;
+/** Does a granted scope set (e.g. `hello.ack.grantedScopes`) satisfy a
+ *  required scope? Exact-match for v1 (no hierarchical wildcards). */
+export declare function hasScope(granted: readonly string[], required: CompanionScope): boolean;

package/dist/scopes.js

@@ -0,0 +1,85 @@
+// Companion capability scopes — the SDK's self-contained copy (no $lib
+// imports; same doctrine as protocol.ts). The server's source of truth is
+// src/lib/types/companion-scopes.ts; protocol.drift.test.ts fails if the two
+// diverge — extend both together.
+//
+// Why the SDK exports these: a host app configuring a key, gating a feature
+// on `hello.ack.grantedScopes`, or explaining a `403 missing scope` needs the
+// vocabulary as types and constants, not prose. Typos in scope strings become
+// compile errors instead of runtime 403s.
+/** Every capability scope a Personal Access Token / OAuth grant can carry. */
+export const COMPANION_SCOPES = [
+    'chat', // text turns
+    'voice', // TTS / STT
+    'call', // realtime WebRTC voice session
+    'files', // multimodal file in/out (vision / image)
+    'events.subscribe', // receive the outbound companion event stream
+    'worldstate.write', // push inbound live world-state / context events
+    'ui.render', // let the companion render Instant UI surfaces on the host (display + forms; not sensitive)
+    'memory.read:app', // read this app's own memory namespace
+    'memory.write:app', // write into this app's own memory namespace
+    '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.spend', // spend from the Care Wallet (SENSITIVE)
+    'social.message', // message friends via A2A (SENSITIVE)
+    // ── Representative ("on-behalf-of") plane ─────────────────────────────
+    'represent', // open visitor-facing representative sessions (SENSITIVE)
+    'expose:knowledge', // let the representative draw on the owner's knowledge base (SENSITIVE)
+    'expose:facts', // widen exposed facts past the identity/preference floor (SENSITIVE)
+    'represent:pair', // let a representative pair a visitor (also a Pouchy user) as a friend (SENSITIVE)
+    'represent:remember' // let a representative keep durable per-visitor notes across visits (SENSITIVE)
+];
+/** I/O modalities a key can carry alongside its scopes. */
+export const COMPANION_MODALITIES = ['text', 'voice', 'call', 'files'];
+/** Sensitive scopes — never granted by default; the user opts in at key
+ *  creation, and execution still passes a confirm on a Pouchy-controlled
+ *  surface (see `companion.confirm_request`). */
+export const SENSITIVE_SCOPES = new Set([
+    'memory.read:core',
+    'memory.write:core',
+    'skills.execute',
+    'wallet.spend',
+    'social.message',
+    'represent',
+    'expose:knowledge',
+    'expose:facts',
+    'represent:pair',
+    'represent:remember'
+]);
+/** The representative ("on-behalf-of") plane — a distinct axis from the
+ *  execution scopes: one lets the companion ACT for the owner, the other lets
+ *  it REPRESENT the owner to an outside visitor. `represent` is the umbrella;
+ *  the `expose:*` / `represent:*` scopes only mean anything alongside it. */
+export const REPRESENT_SCOPES = new Set([
+    'represent',
+    'expose:knowledge',
+    'expose:facts',
+    'represent:pair',
+    'represent:remember'
+]);
+/** What a freshly-generated key carries unless the user opts into more: a
+ *  chat/play companion confined to its own app memory namespace. */
+export const DEFAULT_SCOPES = [
+    'chat',
+    'voice',
+    'call',
+    'files',
+    'events.subscribe',
+    'worldstate.write',
+    'memory.read:app',
+    'memory.write:app'
+];
+export const DEFAULT_MODALITIES = ['text', 'voice'];
+export function isSensitiveScope(s) {
+    return SENSITIVE_SCOPES.has(s);
+}
+export function isRepresentScope(s) {
+    return REPRESENT_SCOPES.has(s);
+}
+/** Does a granted scope set (e.g. `hello.ack.grantedScopes`) satisfy a
+ *  required scope? Exact-match for v1 (no hierarchical wildcards). */
+export function hasScope(granted, required) {
+    return granted.includes(required);
+}

package/package.json

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