@soulcraft/sdk 1.1.0 → 1.3.0

package/dist/client/index.d.ts

@@ -55,6 +55,9 @@ export { WsTransport } from '../transports/ws.js';
 export { SseTransport } from '../transports/sse.js';
 export type { SDKTransport } from '../transports/transport.js';
 export { createBrainyProxy } from '../modules/brainy/proxy.js';
+export { joinHallRoom } from '../modules/hall/browser.js';
+export type { JoinHallRoomOptions } from '../modules/hall/browser.js';
+export type { HallRoomHandle, HallRoomHandleEvents, TranscriptEvent, ConceptMentionEvent, RelationProposedEvent, SpeakerChangedEvent, PeerJoinedEvent, PeerLeftEvent, RoomOptions, RecordingManifest, ConceptInput, } from '../modules/hall/types.js';
 export type { ClientSDKOptions } from '../types.js';
 export type { SoulcraftBrainy } from '../modules/brainy/types.js';
 export type { BrainyChangeEvent } from '../modules/brainy/events.js';

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAG9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AACjE,YAAY,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,6BAA6B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAG9D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACrE,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,YAAY,GACb,MAAM,0BAA0B,CAAA;AAGjC,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AACjE,YAAY,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,6BAA6B,CAAA"}

package/dist/client/index.js

@@ -56,5 +56,7 @@ export { WsTransport } from '../transports/ws.js';
 export { SseTransport } from '../transports/sse.js';
 // ── Proxy factory ─────────────────────────────────────────────────────────────
 export { createBrainyProxy } from '../modules/brainy/proxy.js';
+// ── Hall room client (browser WebRTC) ─────────────────────────────────────────
+export { joinHallRoom } from '../modules/hall/browser.js';
 export { SDKError, SDKDisconnectedError, SDKTimeoutError, SDKAuthError, SDKForbiddenError, SDKRpcError, SDKMethodNotFoundError, } from '../modules/brainy/errors.js';
 //# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,iFAAiF;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAGnD,iFAAiF;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAM9D,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,6BAA6B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,iFAAiF;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAGnD,iFAAiF;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAE9D,iFAAiF;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAoBzD,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,6BAA6B,CAAA"}

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export { createCapabilityToken, verifyCapabilityToken, } from './modules/brainy/
 export { SDKError, SDKDisconnectedError, SDKTimeoutError, SDKAuthError, SDKForbiddenError, SDKRpcError, SDKMethodNotFoundError, } from './modules/brainy/errors.js';
 export type { VfsModule } from './modules/vfs/types.js';
 export type { VersionsModule } from './modules/versions/types.js';
-export type { HallModule, HallConfig, RoomOptions, RecordingManifest, ConceptEvent, RelationProposedEvent, AttentionEvent, RoomEventMap, } from './modules/hall/types.js';
+export type { HallModule, HallRoom, HallRoomHandle, HallRoomEvents, HallRoomHandleEvents, HallConnectionOptions, RoomOptions, ConceptInput, RecordingManifest, TranscriptEvent, ConceptMentionEvent, RelationProposedEvent, SpeakerChangedEvent, PeerJoinedEvent, PeerLeftEvent, } from './modules/hall/types.js';
 export type { AuthModule, PlatformRole, SoulcraftAuthProvider, SoulcraftOrganization, SoulcraftUserFields, SoulcraftSessionUser, SoulcraftSession, OIDCClientConfig, AuthMode, } from './modules/auth/types.js';
 export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, computeEmailHash, getAuthMode, getOIDCClientConfig, } from './modules/auth/config.js';
 export type { AiModule, AiCompleteOptions, AiCompleteResult, AiStreamOptions, AiStreamEvent, AiToolCall, AiMessage, AiContentBlock, AiTool, AiModel, } from './modules/ai/types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8BH,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,4BAA4B,CAAA;AAgCnC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,MAAM,0BAA0B,CAAA;AAejC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAoFjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8BH,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,4BAA4B,CAAA;AAuCnC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,MAAM,0BAA0B,CAAA;AAejC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAoFjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/modules/auth/service-token.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module modules/auth/service-token
+ * @description Timing-safe bearer token verification for service-to-service requests.
+ *
+ * Some Soulcraft services authenticate inter-service calls with a plain shared secret
+ * rather than HMAC-signed capability tokens. Examples include:
+ * - `WORKSHOP_DEPLOY_SECRET` — CI/CD pipelines triggering workshop deploys
+ * - `ACADEMY_PUBLISH_SECRET` — Academy publishing webhooks
+ *
+ * This module provides `verifyServiceToken()` — a single helper that extracts the
+ * `Authorization: Bearer <token>` header and compares it against the expected secret
+ * using a constant-time comparison to prevent timing-attack leaks.
+ *
+ * For cross-product server-to-server calls that need user identity, use capability
+ * tokens from `@soulcraft/sdk/server` (`createCapabilityToken` / `verifyCapabilityToken`)
+ * instead.
+ *
+ * @example Hono route guarded by a service token
+ * ```typescript
+ * import { verifyServiceToken } from '@soulcraft/sdk/server'
+ *
+ * app.post('/api/deploy', async (c) => {
+ *   if (!verifyServiceToken(c.req.raw, process.env.WORKSHOP_DEPLOY_SECRET!)) {
+ *     return c.json({ error: 'Unauthorized' }, 401)
+ *   }
+ *   await triggerDeploy()
+ *   return c.json({ ok: true })
+ * })
+ * ```
+ */
+/**
+ * Extract the bearer token from an HTTP `Authorization` header.
+ *
+ * Returns `null` if the header is absent or does not follow the
+ * `Bearer <token>` scheme.
+ *
+ * @param request - A Web API `Request` object (Hono / SvelteKit / Bun / Node18+).
+ * @returns The raw token string, or `null` if not present.
+ */
+export declare function extractBearerToken(request: Request): string | null;
+/**
+ * Verify that the `Authorization: Bearer` token in `request` matches `expected`.
+ *
+ * Uses a timing-safe comparison (SHA-256 digest of both sides before comparing)
+ * to prevent timing attacks that could leak the secret.
+ *
+ * Returns `false` immediately if `expected` is empty, preventing accidental
+ * wide-open access when the env var is not configured.
+ *
+ * @param request - A Web API `Request` object.
+ * @param expected - The expected secret (e.g. `process.env.WORKSHOP_DEPLOY_SECRET`).
+ * @returns `true` if the token is present and matches `expected`; `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * if (!verifyServiceToken(c.req.raw, process.env.WORKSHOP_DEPLOY_SECRET!)) {
+ *   return c.json({ error: 'Unauthorized' }, 401)
+ * }
+ * ```
+ */
+export declare function verifyServiceToken(request: Request, expected: string): boolean;
+//# sourceMappingURL=service-token.d.ts.map

package/dist/modules/auth/service-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-token.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/service-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAsBH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKlE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAc9E"}

package/dist/modules/auth/service-token.js

@@ -0,0 +1,99 @@
+/**
+ * @module modules/auth/service-token
+ * @description Timing-safe bearer token verification for service-to-service requests.
+ *
+ * Some Soulcraft services authenticate inter-service calls with a plain shared secret
+ * rather than HMAC-signed capability tokens. Examples include:
+ * - `WORKSHOP_DEPLOY_SECRET` — CI/CD pipelines triggering workshop deploys
+ * - `ACADEMY_PUBLISH_SECRET` — Academy publishing webhooks
+ *
+ * This module provides `verifyServiceToken()` — a single helper that extracts the
+ * `Authorization: Bearer <token>` header and compares it against the expected secret
+ * using a constant-time comparison to prevent timing-attack leaks.
+ *
+ * For cross-product server-to-server calls that need user identity, use capability
+ * tokens from `@soulcraft/sdk/server` (`createCapabilityToken` / `verifyCapabilityToken`)
+ * instead.
+ *
+ * @example Hono route guarded by a service token
+ * ```typescript
+ * import { verifyServiceToken } from '@soulcraft/sdk/server'
+ *
+ * app.post('/api/deploy', async (c) => {
+ *   if (!verifyServiceToken(c.req.raw, process.env.WORKSHOP_DEPLOY_SECRET!)) {
+ *     return c.json({ error: 'Unauthorized' }, 401)
+ *   }
+ *   await triggerDeploy()
+ *   return c.json({ ok: true })
+ * })
+ * ```
+ */
+import { timingSafeEqual, createHash } from 'node:crypto';
+// ─────────────────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Hash a string to a fixed 32-byte SHA-256 digest for `timingSafeEqual`.
+ *
+ * Both sides must be the same byte length for `timingSafeEqual` to work.
+ * Hashing also ensures comparison time is independent of token length.
+ */
+function _toComparableBuffer(value) {
+    return createHash('sha256').update(value, 'utf8').digest();
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract the bearer token from an HTTP `Authorization` header.
+ *
+ * Returns `null` if the header is absent or does not follow the
+ * `Bearer <token>` scheme.
+ *
+ * @param request - A Web API `Request` object (Hono / SvelteKit / Bun / Node18+).
+ * @returns The raw token string, or `null` if not present.
+ */
+export function extractBearerToken(request) {
+    const header = request.headers.get('authorization');
+    if (!header?.startsWith('Bearer '))
+        return null;
+    const token = header.slice(7).trim();
+    return token.length > 0 ? token : null;
+}
+/**
+ * Verify that the `Authorization: Bearer` token in `request` matches `expected`.
+ *
+ * Uses a timing-safe comparison (SHA-256 digest of both sides before comparing)
+ * to prevent timing attacks that could leak the secret.
+ *
+ * Returns `false` immediately if `expected` is empty, preventing accidental
+ * wide-open access when the env var is not configured.
+ *
+ * @param request - A Web API `Request` object.
+ * @param expected - The expected secret (e.g. `process.env.WORKSHOP_DEPLOY_SECRET`).
+ * @returns `true` if the token is present and matches `expected`; `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * if (!verifyServiceToken(c.req.raw, process.env.WORKSHOP_DEPLOY_SECRET!)) {
+ *   return c.json({ error: 'Unauthorized' }, 401)
+ * }
+ * ```
+ */
+export function verifyServiceToken(request, expected) {
+    // Reject immediately if the expected secret is not configured.
+    if (!expected)
+        return false;
+    const actual = extractBearerToken(request);
+    if (!actual)
+        return false;
+    try {
+        const a = _toComparableBuffer(actual);
+        const b = _toComparableBuffer(expected);
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=service-token.js.map

package/dist/modules/auth/service-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-token.js","sourceRoot":"","sources":["../../../src/modules/auth/service-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEzD,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,KAAa;IACxC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAA;AAC5D,CAAC;AAED,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;IACnD,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAA;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACpC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB,EAAE,QAAgB;IACnE,+DAA+D;IAC/D,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAA;IAE3B,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAC1C,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAEzB,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAA;QACrC,MAAM,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAA;QACvC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC"}

package/dist/modules/billing/index.d.ts

@@ -3,9 +3,11 @@
  * @description Factory for sdk.billing.* — usage metering, subscription management,
  * top-up credits, and Stripe integration.
  *
- * **Provider selection:** The billing module automatically chooses the storage backend:
- * - `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (production)
- * - Not set → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
+ * **Provider selection (priority order):**
+ * 1. `options.provider` — explicit override (primarily for testing)
+ * 2. `PORTAL_CREDIT_SECRET` set → `PortalBillingProvider` (cross-product unified credits)
+ * 3. `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (per-product production)
+ * 4. Neither → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
  *
  * **Usage metering:** Fire-and-forget via a 5-second write-behind buffer. Recording
  * usage never blocks the AI response path.
@@ -30,10 +32,20 @@ import type { BillingModule, BillingProvider } from './types.js';
 export interface CreateBillingModuleOptions {
     /**
      * Override the billing provider directly.
-     * When not provided, the provider is selected from the environment:
-     * Firestore when `FIREBASE_SERVICE_ACCOUNT_KEY` is set, local otherwise.
+     * When not provided, the provider is selected from the environment
+     * (Portal → Firestore → Local).
      */
     provider?: BillingProvider;
+    /**
+     * The product name sent to the Portal credit API with every consume/batch call.
+     * Used for per-product usage attribution in Portal analytics.
+     *
+     * Only relevant when `PORTAL_CREDIT_SECRET` is set and no explicit `provider` is given.
+     * Defaults to `'unknown'` if not specified.
+     *
+     * @example `'workshop'` | `'venue'` | `'academy'`
+     */
+    product?: string;
 }
 /**
  * Create the `sdk.billing.*` module.

package/dist/modules/billing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAOhB,MAAM,YAAY,CAAA;AAMnB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B;AAgBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAuH3F;AAGD,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAOhB,MAAM,YAAY,CAAA;AAMnB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;IAE1B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAgBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAwI3F;AAGD,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,YAAY,CAAA"}

package/dist/modules/billing/index.js

@@ -3,9 +3,11 @@
  * @description Factory for sdk.billing.* — usage metering, subscription management,
  * top-up credits, and Stripe integration.
  *
- * **Provider selection:** The billing module automatically chooses the storage backend:
- * - `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (production)
- * - Not set → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
+ * **Provider selection (priority order):**
+ * 1. `options.provider` — explicit override (primarily for testing)
+ * 2. `PORTAL_CREDIT_SECRET` set → `PortalBillingProvider` (cross-product unified credits)
+ * 3. `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (per-product production)
+ * 4. Neither → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
  *
  * **Usage metering:** Fire-and-forget via a 5-second write-behind buffer. Recording
  * usage never blocks the AI response path.
@@ -26,6 +28,7 @@
 import Stripe from 'stripe';
 import { LocalBillingProvider } from './local-provider.js';
 import { FirestoreBillingProvider } from './firestore-provider.js';
+import { PortalBillingProvider } from './portal-provider.js';
 import { UsageBuffer } from './usage-buffer.js';
 // ─────────────────────────────────────────────────────────────────────────────
 // Stripe helper
@@ -46,10 +49,17 @@ function _getStripe() {
  * @returns A fully configured `BillingModule`.
  */
 export function createBillingModule(options = {}) {
-    const provider = options.provider
-        ?? (process.env['FIREBASE_SERVICE_ACCOUNT_KEY']
-            ? new FirestoreBillingProvider()
-            : new LocalBillingProvider());
+    const _selectProvider = () => {
+        const portalSecret = process.env['PORTAL_CREDIT_SECRET'];
+        if (portalSecret) {
+            return new PortalBillingProvider('https://portal.soulcraft.com', portalSecret, options.product ?? 'unknown');
+        }
+        if (process.env['FIREBASE_SERVICE_ACCOUNT_KEY']) {
+            return new FirestoreBillingProvider();
+        }
+        return new LocalBillingProvider();
+    };
+    const provider = options.provider ?? _selectProvider();
     const buffer = new UsageBuffer(provider);
     return {
         // ── Usage metering ──────────────────────────────────────────────────────
@@ -112,15 +122,20 @@ export function createBillingModule(options = {}) {
             return provider.getTopUpBalance(userId);
         },
         async addTopUp(userId, amount) {
+            // Portal manages top-up credits directly — this method is a no-op
+            // when the Portal provider is active. Products should redirect users
+            // to portal.soulcraft.com to purchase top-up credits.
+            if (provider instanceof PortalBillingProvider) {
+                return provider.getTopUpBalance(userId);
+            }
             // For the local provider, directly update the balance.
-            // For Firestore, we use a targeted increment to avoid race conditions.
             if (provider instanceof LocalBillingProvider) {
                 const current = await provider.getTopUpBalance(userId);
                 const newBalance = current + amount;
                 await provider.setTopUpBalance(userId, newBalance);
                 return newBalance;
             }
-            // Firestore: increment and then read the new balance.
+            // Firestore: increment via a targeted negative-topUpUsed write to avoid race conditions.
             if (provider instanceof FirestoreBillingProvider) {
                 await provider.batchIncrementUsage(userId, {
                     messageCount: 0, inputTokens: 0, outputTokens: 0,

package/dist/modules/billing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/billing/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/billing/index.ts"],"names":[],"mappings":"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"}

package/dist/modules/billing/portal-provider.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module billing/portal-provider
+ * @description Portal-backed billing provider for unified cross-product credit tracking.
+ *
+ * Delegates all credit checks and usage recording to the Portal credit API at
+ * `https://portal.soulcraft.com/api/credits/*`. This ensures that a user's
+ * 1,000 monthly credits are shared across Workshop, Venue, and Academy — not siloed
+ * per product.
+ *
+ * Activated when `PORTAL_CREDIT_SECRET` is set in the environment. Takes precedence
+ * over the Firestore provider.
+ *
+ * **Endpoint summary:**
+ * ```
+ * POST /api/credits/check   — pre-flight before an AI call
+ * POST /api/credits/consume — deduct usage after a single AI response
+ * POST /api/credits/batch   — flush buffered usage at end of session
+ * ```
+ *
+ * All requests carry `X-Portal-Credit-Secret: <PORTAL_CREDIT_SECRET>`.
+ *
+ * Subscription data, top-up balances, and usage history are not surfaced via
+ * this API — those are managed by Portal directly. Methods that require them
+ * (`getUsageStatus`, `getSubscription`, `addTopUp`) return safe defaults.
+ * Products that need rich billing UI should call Portal's management API directly.
+ *
+ * @example
+ * ```typescript
+ * // Automatically selected when PORTAL_CREDIT_SECRET is set:
+ * const billing = createBillingModule()
+ *
+ * // Explicit override (e.g. for testing):
+ * const billing = createBillingModule({
+ *   provider: new PortalBillingProvider('https://portal.soulcraft.com', secret, 'workshop'),
+ * })
+ * ```
+ */
+import type { BillingProvider, UsageData, SubscriptionData, LimitCheckResult, UsageStatus, BatchIncrementData } from './types.js';
+/**
+ * Portal-backed billing provider.
+ *
+ * Calls the Portal credit API for all gate checks and usage recording.
+ * All requests are authenticated with the `X-Portal-Credit-Secret` header.
+ *
+ * The `userId` parameter on all methods must be the user's **email address** —
+ * the same identifier Portal uses to look up the license document.
+ */
+export declare class PortalBillingProvider implements BillingProvider {
+    private readonly baseUrl;
+    private readonly secret;
+    private readonly product;
+    /**
+     * @param baseUrl - Portal base URL (e.g. `"https://portal.soulcraft.com"`).
+     * @param secret - The value of `PORTAL_CREDIT_SECRET`.
+     * @param product - The product name sent with consume/batch calls (`'workshop'`, `'venue'`, `'academy'`).
+     */
+    constructor(baseUrl: string, secret: string, product: string);
+    private _headers;
+    private _post;
+    checkLimit(userId: string, hasPersonalKey: boolean): Promise<LimitCheckResult>;
+    getUsage(userId: string): Promise<UsageData>;
+    getUsageStatus(userId: string, hasPersonalKey: boolean): Promise<UsageStatus>;
+    incrementUsage(userId: string, inputTokens: number, outputTokens: number, model: string, _useTopUp: boolean): Promise<void>;
+    batchIncrementUsage(userId: string, batch: BatchIncrementData): Promise<void>;
+    getSubscription(_userId: string): Promise<SubscriptionData | undefined>;
+    hasActiveSubscription(userId: string): Promise<boolean>;
+    getTopUpBalance(userId: string): Promise<number>;
+    canAccessPaidFeature(userId: string): Promise<boolean>;
+}
+//# sourceMappingURL=portal-provider.d.ts.map

package/dist/modules/billing/portal-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal-provider.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/portal-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAmBnB;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAOzD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B;;;;OAIG;gBAEgB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM;IAKlC,OAAO,CAAC,QAAQ;YAOF,KAAK;IAeb,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2B9E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAgB5C,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAgC7E,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,IAAI,CAAC;IAeV,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7E,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAKvE,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKvD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKhD,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAG7D"}