@pouchy_ai/companion-sdk 0.37.1 → 0.38.0

package/CHANGELOG.md

@@ -12,6 +12,17 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.38.0] - 2026-07-19
+
+Additive: new `grantsScope(granted, required)` helper. Like `hasScope`, but it
+honours the server's scope subsumption — a key granted only `wallet.spend` now
+`grantsScope(g, 'wallet.read')`, because the wallet API (`GET
+/api/companion/wallet`, `getWallet()`) serves the balance to a spender. Gate a
+read-only affordance on `grantsScope`, not `hasScope`, or the UI hides a feature
+the server would allow. `hasScope` is unchanged (exact-match), for
+"was-this-scope-explicitly-granted" checks. No wire/protocol change
+(`PROTOCOL_VERSION` stays `1`); no scope vocabulary change.
+
 ## [0.37.1] - 2026-07-18
 
 Documentation-only patch — no code, no surface, no protocol change
@@ -213,7 +224,7 @@ Backwards-compatible fixes to the adapter view controller (`createCompanionView`
   now removes the dead card from `pendingConfirms` (other rejections keep the
   card for retry). The error still propagates.
 
-
+## [0.32.0] - 2026-07-14
 
 No breaking changes — additive surface + docs infrastructure. No protocol
 change (`PROTOCOL_VERSION` stays `1`).
@@ -961,7 +972,9 @@ self-hosted/CDN build; this entry captures the surface that ships publicly.
 - **Versioned wire protocol.** `PROTOCOL_VERSION = 1`, kept in lockstep with the
   server by `protocol.drift.test.ts` (fails CI on divergence).
 
-[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.36.0...HEAD
+[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.37.1...HEAD
+[0.37.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.37.0...companion-sdk-v0.37.1
+[0.37.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.36.0...companion-sdk-v0.37.0
 [0.36.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.35.0...companion-sdk-v0.36.0
 [0.35.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.34.0...companion-sdk-v0.35.0
 [0.34.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.33.0...companion-sdk-v0.34.0

package/README.md

@@ -264,18 +264,27 @@ copying scope strings from prose:
 ```ts
 import {
   COMPANION_SCOPES, SENSITIVE_SCOPES, DEFAULT_SCOPES,
-  hasScope, isSensitiveScope, type CompanionScope
+  hasScope, grantsScope, 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
 }
+// Gate a READ-ONLY affordance with grantsScope, not hasScope: a key granted
+// only `wallet.spend` can still read the balance, so hasScope(g,'wallet.read')
+// would wrongly hide it. grantsScope honours that subsumption.
+if (grantsScope(ack.grantedScopes, 'wallet.read')) {
+  // safe to show the wallet balance (getWallet() will succeed)
+}
 ```
 
 `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
+the representative plane); `DEFAULT_SCOPES` is what a fresh key gets.
+`hasScope(granted, required)` is an exact-grant check; **`grantsScope(granted,
+required)`** additionally honours scope subsumption (`wallet.spend` ⊇
+`wallet.read`) — use it to gate whether an API call will succeed. Also
 exported: `COMPANION_MODALITIES`, `REPRESENT_SCOPES`, `DEFAULT_MODALITIES`,
 `isRepresentScope()`. The list mirrors the server vocabulary and is guarded by
 the SDK's drift test.

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export type { CompanionErrorCodeValue, ControlErrorCodeValue } from './errors.js
 export type { CompanionClientOptions, CompanionStreamState, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, ToolCallEvent, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult, SendTextReply, QueuedSend, OutboxStore } 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 { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope, grantsScope } from './scopes.js';
 export type { CompanionScope, CompanionModality } from './scopes.js';
 export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, PendingToolCall, ToolCallPayload, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload, MessagePayload, ControlErrorPayload, HelloAckPayload, CallReadyPayload, OutboundPayloadMap } from './protocol.js';
 export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES, COMPANION_ERROR_CODES, CONTROL_ERROR_CODES } from './protocol.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC/E,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC/E,YAAY,EACX,sBAAsB,EACtB,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,WAAW,EACX,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACnF,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EACX,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EACX,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,MAAM,gBAAgB,CAAC;AAExB,iCAAiC;AACjC,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CAE7E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC/E,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC/E,YAAY,EACX,sBAAsB,EACtB,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,WAAW,EACX,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACnF,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EACX,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EACX,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,MAAM,gBAAgB,CAAC;AAExB,iCAAiC;AACjC,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CAE7E"}

package/dist/index.js

@@ -12,7 +12,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';
+export { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope, grantsScope } from './scopes.js';
 // Runtime protocol constants — so a host can assert PROTOCOL_VERSION or
 // enumerate/validate the event vocabulary without hard-coding the strings.
 // CONTROL_ERROR_CODES (0.30.0) is the stream-plane control.error vocabulary —

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yEAAyE;AACzE,sDAAsD;AACtD,EAAE;AACF,0DAA0D;AAC1D,6EAA6E;AAC7E,uBAAuB;AACvB,8CAA8C;AAC9C,eAAe;AACf,8EAA8E;AAC9E,2CAA2C;AAE3C,OAAO,EAAE,eAAe,EAA+B,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAsB/E,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,QAAQ,CAAC;AAEhB,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,MAAM,UAAU,CAAC;AAyBlB,wEAAwE;AACxE,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AAGpB,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAQrD,iCAAiC;AACjC,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC3D,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yEAAyE;AACzE,sDAAsD;AACtD,EAAE;AACF,0DAA0D;AAC1D,6EAA6E;AAC7E,uBAAuB;AACvB,8CAA8C;AAC9C,eAAe;AACf,8EAA8E;AAC9E,2CAA2C;AAE3C,OAAO,EAAE,eAAe,EAA+B,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAsB/E,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,QAAQ,CAAC;AAEhB,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,MAAM,UAAU,CAAC;AAyBlB,wEAAwE;AACxE,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AAGpB,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAQrD,iCAAiC;AACjC,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC3D,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/scopes.d.ts

@@ -20,6 +20,16 @@ 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). */
+ *  required scope? Exact-match for v1 (no hierarchical wildcards). Use this for
+ *  an EXACT-grant check ("was this scope explicitly granted?"). To gate a
+ *  feature on whether an API CALL will succeed, prefer `grantsScope`, which
+ *  also honours scope subsumption. */
 export declare function hasScope(granted: readonly string[], required: CompanionScope): boolean;
+/** Like {@link hasScope}, but honours the server's scope subsumptions — so a key
+ *  granted only `wallet.spend` still `grantsScope(g, 'wallet.read')` (the API
+ *  would serve the balance). Gate a read-only affordance (e.g. showing the
+ *  wallet balance via `getWallet()`) on THIS, not `hasScope`, or the UI hides a
+ *  feature the server would allow. For non-subsumed scopes it is identical to
+ *  `hasScope`. */
+export declare function grantsScope(granted: readonly string[], required: CompanionScope): boolean;
 //# sourceMappingURL=scopes.d.ts.map

package/dist/scopes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"AAUA,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,8UAsBnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,6CAA8C,CAAC;AAChF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;iDAEiD;AACjD,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,cAAc,CAWvD,CAAC;AAEH;;;6EAG6E;AAC7E,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,cAAc,CAMvD,CAAC;AAEH;oEACoE;AACpE,eAAO,MAAM,cAAc,EAAE,SAAS,cAAc,EASnD,CAAC;AACF,eAAO,MAAM,kBAAkB,EAAE,SAAS,iBAAiB,EAAsB,CAAC;AAElF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAE3D;AACD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED;sEACsE;AACtE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAEtF"}
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"AAUA,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,8UAsBnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,6CAA8C,CAAC;AAChF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;iDAEiD;AACjD,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,cAAc,CAWvD,CAAC;AAEH;;;6EAG6E;AAC7E,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,cAAc,CAMvD,CAAC;AAEH;oEACoE;AACpE,eAAO,MAAM,cAAc,EAAE,SAAS,cAAc,EASnD,CAAC;AACF,eAAO,MAAM,kBAAkB,EAAE,SAAS,iBAAiB,EAAsB,CAAC;AAElF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAE3D;AACD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED;;;;sCAIsC;AACtC,wBAAgB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAEtF;AAWD;;;;;kBAKkB;AAClB,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAIzF"}

package/dist/scopes.js

@@ -79,8 +79,31 @@ 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). */
+ *  required scope? Exact-match for v1 (no hierarchical wildcards). Use this for
+ *  an EXACT-grant check ("was this scope explicitly granted?"). To gate a
+ *  feature on whether an API CALL will succeed, prefer `grantsScope`, which
+ *  also honours scope subsumption. */
 export function hasScope(granted, required) {
     return granted.includes(required);
 }
+/** Scope subsumption: for a required scope, the OTHER granted scopes that also
+ *  satisfy it on the server. v1 has exactly one — `wallet.spend` can already see
+ *  the balance, so it also satisfies a `wallet.read` (mirrors the server gate at
+ *  `GET /api/companion/wallet`). Keep in lockstep with the server if more are
+ *  added. */
+const SCOPE_SUBSUMED_BY = {
+    'wallet.read': ['wallet.spend']
+};
+/** Like {@link hasScope}, but honours the server's scope subsumptions — so a key
+ *  granted only `wallet.spend` still `grantsScope(g, 'wallet.read')` (the API
+ *  would serve the balance). Gate a read-only affordance (e.g. showing the
+ *  wallet balance via `getWallet()`) on THIS, not `hasScope`, or the UI hides a
+ *  feature the server would allow. For non-subsumed scopes it is identical to
+ *  `hasScope`. */
+export function grantsScope(granted, required) {
+    if (granted.includes(required))
+        return true;
+    const implied = SCOPE_SUBSUMED_BY[required];
+    return implied ? implied.some((s) => granted.includes(s)) : false;
+}
 //# sourceMappingURL=scopes.js.map

package/dist/scopes.js.map

@@ -1 +1 @@
-{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,0EAA0E;AAC1E,6EAA6E;AAC7E,kCAAkC;AAClC,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,8EAA8E;AAC9E,0CAA0C;AAE1C,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC/B,MAAM,EAAE,aAAa;IACrB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,gCAAgC;IACxC,OAAO,EAAE,0CAA0C;IACnD,kBAAkB,EAAE,8CAA8C;IAClE,kBAAkB,EAAE,iDAAiD;IACrE,WAAW,EAAE,4FAA4F;IACzG,iBAAiB,EAAE,uCAAuC;IAC1D,kBAAkB,EAAE,6CAA6C;IACjE,kBAAkB,EAAE,2CAA2C;IAC/D,mBAAmB,EAAE,iDAAiD;IACtE,gBAAgB,EAAE,8CAA8C;IAChE,aAAa,EAAE,4KAA4K;IAC3L,cAAc,EAAE,yCAAyC;IACzD,gBAAgB,EAAE,sCAAsC;IACxD,yEAAyE;IACzE,WAAW,EAAE,0DAA0D;IACvE,kBAAkB,EAAE,wEAAwE;IAC5F,cAAc,EAAE,qEAAqE;IACrF,gBAAgB,EAAE,mFAAmF;IACrG,oBAAoB,CAAC,gFAAgF;CAC5F,CAAC;AAGX,2DAA2D;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAGhF;;iDAEiD;AACjD,MAAM,CAAC,MAAM,gBAAgB,GAAgC,IAAI,GAAG,CAAiB;IACpF,kBAAkB;IAClB,mBAAmB;IACnB,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,WAAW;IACX,kBAAkB;IAClB,cAAc;IACd,gBAAgB;IAChB,oBAAoB;CACpB,CAAC,CAAC;AAEH;;;6EAG6E;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAAgC,IAAI,GAAG,CAAiB;IACpF,WAAW;IACX,kBAAkB;IAClB,cAAc;IACd,gBAAgB;IAChB,oBAAoB;CACpB,CAAC,CAAC;AAEH;oEACoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAA8B;IACxD,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;IACP,kBAAkB;IAClB,kBAAkB;IAClB,iBAAiB;IACjB,kBAAkB;CAClB,CAAC;AACF,MAAM,CAAC,MAAM,kBAAkB,GAAiC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElF,MAAM,UAAU,gBAAgB,CAAC,CAAiB;IACjD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AACD,MAAM,UAAU,gBAAgB,CAAC,CAAiB;IACjD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AAED;sEACsE;AACtE,MAAM,UAAU,QAAQ,CAAC,OAA0B,EAAE,QAAwB;IAC5E,OAAO,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,0EAA0E;AAC1E,6EAA6E;AAC7E,kCAAkC;AAClC,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,8EAA8E;AAC9E,0CAA0C;AAE1C,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC/B,MAAM,EAAE,aAAa;IACrB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,gCAAgC;IACxC,OAAO,EAAE,0CAA0C;IACnD,kBAAkB,EAAE,8CAA8C;IAClE,kBAAkB,EAAE,iDAAiD;IACrE,WAAW,EAAE,4FAA4F;IACzG,iBAAiB,EAAE,uCAAuC;IAC1D,kBAAkB,EAAE,6CAA6C;IACjE,kBAAkB,EAAE,2CAA2C;IAC/D,mBAAmB,EAAE,iDAAiD;IACtE,gBAAgB,EAAE,8CAA8C;IAChE,aAAa,EAAE,4KAA4K;IAC3L,cAAc,EAAE,yCAAyC;IACzD,gBAAgB,EAAE,sCAAsC;IACxD,yEAAyE;IACzE,WAAW,EAAE,0DAA0D;IACvE,kBAAkB,EAAE,wEAAwE;IAC5F,cAAc,EAAE,qEAAqE;IACrF,gBAAgB,EAAE,mFAAmF;IACrG,oBAAoB,CAAC,gFAAgF;CAC5F,CAAC;AAGX,2DAA2D;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAGhF;;iDAEiD;AACjD,MAAM,CAAC,MAAM,gBAAgB,GAAgC,IAAI,GAAG,CAAiB;IACpF,kBAAkB;IAClB,mBAAmB;IACnB,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,WAAW;IACX,kBAAkB;IAClB,cAAc;IACd,gBAAgB;IAChB,oBAAoB;CACpB,CAAC,CAAC;AAEH;;;6EAG6E;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAAgC,IAAI,GAAG,CAAiB;IACpF,WAAW;IACX,kBAAkB;IAClB,cAAc;IACd,gBAAgB;IAChB,oBAAoB;CACpB,CAAC,CAAC;AAEH;oEACoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAA8B;IACxD,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;IACP,kBAAkB;IAClB,kBAAkB;IAClB,iBAAiB;IACjB,kBAAkB;CAClB,CAAC;AACF,MAAM,CAAC,MAAM,kBAAkB,GAAiC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElF,MAAM,UAAU,gBAAgB,CAAC,CAAiB;IACjD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AACD,MAAM,UAAU,gBAAgB,CAAC,CAAiB;IACjD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AAED;;;;sCAIsC;AACtC,MAAM,UAAU,QAAQ,CAAC,OAA0B,EAAE,QAAwB;IAC5E,OAAO,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED;;;;aAIa;AACb,MAAM,iBAAiB,GAA+D;IACrF,aAAa,EAAE,CAAC,cAAc,CAAC;CAC/B,CAAC;AAEF;;;;;kBAKkB;AAClB,MAAM,UAAU,WAAW,CAAC,OAA0B,EAAE,QAAwB;IAC/E,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,OAAO,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACnE,CAAC"}

package/package.json

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

package/src/index.ts

@@ -51,7 +51,8 @@ export {
 	DEFAULT_MODALITIES,
 	isSensitiveScope,
 	isRepresentScope,
-	hasScope
+	hasScope,
+	grantsScope
 } from './scopes';
 export type { CompanionScope, CompanionModality } from './scopes';
 export type {

package/src/scopes.ts

@@ -88,7 +88,31 @@ export 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). */
+ *  required scope? Exact-match for v1 (no hierarchical wildcards). Use this for
+ *  an EXACT-grant check ("was this scope explicitly granted?"). To gate a
+ *  feature on whether an API CALL will succeed, prefer `grantsScope`, which
+ *  also honours scope subsumption. */
 export function hasScope(granted: readonly string[], required: CompanionScope): boolean {
 	return granted.includes(required);
 }
+
+/** Scope subsumption: for a required scope, the OTHER granted scopes that also
+ *  satisfy it on the server. v1 has exactly one — `wallet.spend` can already see
+ *  the balance, so it also satisfies a `wallet.read` (mirrors the server gate at
+ *  `GET /api/companion/wallet`). Keep in lockstep with the server if more are
+ *  added. */
+const SCOPE_SUBSUMED_BY: Partial<Record<CompanionScope, readonly CompanionScope[]>> = {
+	'wallet.read': ['wallet.spend']
+};
+
+/** Like {@link hasScope}, but honours the server's scope subsumptions — so a key
+ *  granted only `wallet.spend` still `grantsScope(g, 'wallet.read')` (the API
+ *  would serve the balance). Gate a read-only affordance (e.g. showing the
+ *  wallet balance via `getWallet()`) on THIS, not `hasScope`, or the UI hides a
+ *  feature the server would allow. For non-subsumed scopes it is identical to
+ *  `hasScope`. */
+export function grantsScope(granted: readonly string[], required: CompanionScope): boolean {
+	if (granted.includes(required)) return true;
+	const implied = SCOPE_SUBSUMED_BY[required];
+	return implied ? implied.some((s) => granted.includes(s)) : false;
+}