@pouchy_ai/companion-sdk 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -12,6 +12,48 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-07-12
+
+### Added
+
+- **`rate_limited` error code + `CompanionError.retryAfter`.** The runtime's
+  two cost gates (per-user turn burst ceiling, demo daily budget) answer 429;
+  those responses now carry `code: "rate_limited"`, so the typed-error contract
+  finally covers the most common failure a busy integration hits. On any 429
+  the thrown `CompanionError` also exposes `retryAfter` (seconds, from the
+  body's `retryAfterSec` or the standard `Retry-After` header) so consumers can
+  back off precisely:
+  `if (e.code === 'rate_limited') await sleep(e.retryAfter * 1000)`.
+- **OpenAPI now documents the 429s** (shared `RateLimited` response on every
+  model-running path) and the `input` text cap below.
+
+### Changed
+
+- **`input` text is capped at 32,000 chars** (parity with `tool-result`); an
+  over-limit turn returns 413 `payload_too_large` instead of riding a multi-MB
+  string into the model context.
+- Malformed streaming frames no longer throw raw `SyntaxError` out of
+  `sendText`: a bad `delta` frame is skipped (the durable reply still lands),
+  and a bad `done` frame fails the turn with a clean `CompanionError` (502).
+
+### Fixed
+
+- OpenAPI: `/api/companion/pair` no longer claims to deliver paired-friend
+  messages (pairing only; sends happen inside companion turns).
+
+## [0.26.1] - 2026-07-12
+
+### Changed
+
+- **Docs: `/api/stt` now requires auth.** The audio-transcription relay the
+  `ingestKnowledge` guidance points at is no longer an open endpoint — send
+  your `pchy_…` access token as the bearer (any valid token works; the call
+  is metered like other companion ops). No SDK code paths changed; this
+  release updates the inline JSDoc guidance only.
+- Server-side hardening (no client change needed): concurrent `input` posts
+  on one session now lose cleanly with the existing 409 `turn_pending` code
+  instead of double-running a turn — retry after the in-flight reply lands.
+
 ## [0.26.0] - 2026-07-11
 
 ### Fixed

package/README.md

@@ -147,7 +147,11 @@ HTTP `code` vocabulary behind `CompanionError.code`, e.g. `missing_scope` /
 `session_not_found` / `turn_pending`) — so you can assert the version, validate
 the event vocabulary, or switch on error codes without hard-coding strings.
 Every helper populates `CompanionError.code` when the server names a cause
-(0.24.0 — previously only the POST-backed calls did). The SDK also synthesizes
+(0.24.0 — previously only the POST-backed calls did). 0.27.0 adds
+`rate_limited` for the runtime's 429 cost gates (turn burst ceiling, demo
+daily budget); on those failures `CompanionError.retryAfter` carries the
+server's Retry-After in seconds, so back off with
+`if (e.code === 'rate_limited') await sleep(e.retryAfter * 1000)`. The SDK also synthesizes
 a few client-side codes outside that HTTP vocabulary: `reply_timeout`
 (awaitReply fallback gave up), `stream_unauthorized` (event-stream 401
 exhausted reconnects), and — 0.26.0 — the voice connect-step codes

package/dist/client.d.ts

@@ -228,6 +228,10 @@ export declare class CompanionClient {
     private url;
     private jsonHeaders;
     private requireSession;
+    /** Retry-After in seconds for a throttled response: the JSON body's
+     *  `retryAfterSec` (companion rate-limit shape) wins, else the standard
+     *  Retry-After header. Undefined when the server named neither. */
+    private retryAfterFrom;
     private postJson;
     /** Handshake: start or resume the session for this surface. */
     connect(): Promise<HelloAck>;
@@ -432,7 +436,8 @@ export declare class CompanionClient {
      *  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)
+     *  Extract the text yourself (your own parser, or Pouchy's /api/stt for audio —
+     *  send your pchy_ token as the bearer; the relay is auth-gated and metered)
      *  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

package/dist/client.js

@@ -119,6 +119,16 @@ export class CompanionClient {
             throw new CompanionError('CompanionClient: call connect() first', 0, 'not_connected');
         return this._session;
     }
+    /** Retry-After in seconds for a throttled response: the JSON body's
+     *  `retryAfterSec` (companion rate-limit shape) wins, else the standard
+     *  Retry-After header. Undefined when the server named neither. */
+    retryAfterFrom(res, json) {
+        const fromBody = json?.retryAfterSec;
+        if (typeof fromBody === 'number' && Number.isFinite(fromBody) && fromBody >= 0)
+            return fromBody;
+        const header = Number(res.headers.get('Retry-After'));
+        return Number.isFinite(header) && header >= 0 ? header : undefined;
+    }
     async postJson(path, body) {
         const res = await this.fetchAuthed(this.url(path), {
             method: 'POST',
@@ -127,7 +137,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, json?.code);
+            throw new CompanionError(json?.error || `request failed (${res.status})`, res.status, json?.code, this.retryAfterFrom(res, json));
         }
         return json;
     }
@@ -238,7 +248,7 @@ export class CompanionClient {
             // Old server / error before the stream opened — behave like postJson.
             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, json?.code);
+                throw new CompanionError(json?.error || `request failed (${res.status})`, res.status, json?.code, this.retryAfterFrom(res, json));
             }
             return { seq: json.seq ?? null };
         }
@@ -259,7 +269,16 @@ export class CompanionClient {
             buf = rest;
             for (const ev of events) {
                 if (ev.event === 'delta') {
-                    const d = JSON.parse(ev.data);
+                    // A malformed delta frame is dropped, not fatal — losing one text
+                    // chunk beats throwing away the whole turn (the final message
+                    // arrives intact in the done frame / event stream regardless).
+                    let d;
+                    try {
+                        d = JSON.parse(ev.data);
+                    }
+                    catch {
+                        continue;
+                    }
                     if (typeof d.text === 'string' && d.text)
                         fireDelta(d.text, {});
                 }
@@ -267,7 +286,22 @@ export class CompanionClient {
                     fireDelta('', { reset: true });
                 }
                 else if (ev.event === 'done') {
-                    const d = JSON.parse(ev.data);
+                    // The done frame carries the turn's resolution — unparseable means
+                    // the turn's outcome is unknowable, so fail it explicitly instead
+                    // of letting a raw SyntaxError escape the SDK.
+                    let d;
+                    try {
+                        d = JSON.parse(ev.data);
+                    }
+                    catch {
+                        try {
+                            await reader.cancel();
+                        }
+                        catch {
+                            /* stream already finished */
+                        }
+                        throw new CompanionError('malformed done frame', 502);
+                    }
                     try {
                         await reader.cancel();
                     }
@@ -642,7 +676,8 @@ export class CompanionClient {
      *  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)
+     *  Extract the text yourself (your own parser, or Pouchy's /api/stt for audio —
+     *  send your pchy_ token as the bearer; the relay is auth-gated and metered)
      *  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

package/dist/errors.d.ts

@@ -1,9 +1,12 @@
 /** Thrown by every helper on an HTTP or client-side failure. `status` is the
  *  HTTP status (0 for client-synthesized failures — timeouts, unsupported
  *  environments, missing optional deps); `code` is machine-switchable when
- *  the server (or the SDK itself) names a cause. */
+ *  the server (or the SDK itself) names a cause. On a `rate_limited` (429)
+ *  failure, `retryAfter` carries the server's Retry-After in SECONDS so a
+ *  consumer can back off precisely instead of guessing. */
 export declare class CompanionError extends Error {
     status: number;
     code?: string;
-    constructor(message: string, status: number, code?: string);
+    retryAfter?: number;
+    constructor(message: string, status: number, code?: string, retryAfter?: number);
 }

package/dist/errors.js

@@ -6,15 +6,20 @@
 /** Thrown by every helper on an HTTP or client-side failure. `status` is the
  *  HTTP status (0 for client-synthesized failures — timeouts, unsupported
  *  environments, missing optional deps); `code` is machine-switchable when
- *  the server (or the SDK itself) names a cause. */
+ *  the server (or the SDK itself) names a cause. On a `rate_limited` (429)
+ *  failure, `retryAfter` carries the server's Retry-After in SECONDS so a
+ *  consumer can back off precisely instead of guessing. */
 export class CompanionError extends Error {
     status;
     code;
-    constructor(message, status, code) {
+    retryAfter;
+    constructor(message, status, code, retryAfter) {
         super(message);
         this.name = 'CompanionError';
         this.status = status;
         if (code)
             this.code = code;
+        if (typeof retryAfter === 'number' && Number.isFinite(retryAfter))
+            this.retryAfter = retryAfter;
     }
 }

package/dist/protocol.d.ts

@@ -16,7 +16,7 @@ export type MessageType = InboundType | OutboundType;
  *  self-contained mirror of the server's api-error.ts list (drift-tested);
  *  APPEND-ONLY: renaming or removing a code is a breaking SDK change.
  *  Consumers can switch on these instead of string-matching error prose. */
-export declare const COMPANION_ERROR_CODES: readonly ["missing_token", "invalid_token", "missing_scope", "invalid_request", "session_not_found", "turn_pending", "no_pending_tools", "unknown_call", "payload_too_large", "forbidden", "unavailable"];
+export declare const COMPANION_ERROR_CODES: readonly ["missing_token", "invalid_token", "missing_scope", "invalid_request", "session_not_found", "turn_pending", "no_pending_tools", "unknown_call", "payload_too_large", "rate_limited", "forbidden", "unavailable"];
 export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
 /** The single envelope every control/data-plane message shares. */
 export interface CompanionEnvelope<T = unknown> {

package/dist/protocol.js

@@ -54,6 +54,7 @@ export const COMPANION_ERROR_CODES = [
     'no_pending_tools', // 409 — tool result posted but nothing is pending
     'unknown_call', // 404 — tool result for a callId the turn didn't issue
     'payload_too_large', // 413 — body/image over the documented cap
+    'rate_limited', // 429 — turn burst / demo daily budget spent; Retry-After + retryAfterSec say when
     'forbidden', // 403 — authorization denial other than a missing scope
     'unavailable' // 503 — backing store/provider not configured or down
 ];

package/package.json

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