@soulcraft/sdk 1.0.0 → 1.2.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,16 +18,17 @@ 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';
 export { AI_MODELS } from './modules/ai/types.js';
 export type { EventsModule, SoulcraftEventMap, SoulcraftEventName, VfsWriteEvent, VfsDeleteEvent, VfsRenameEvent, } from './modules/events/types.js';
 export type { SkillsModule, Skill, SkillListOptions, SkillInstallOptions, } from './modules/skills/types.js';
-export type * from './modules/license/types.js';
-export type * from './modules/kits/types.js';
-export type * from './modules/formats/types.js';
-export type * from './modules/billing/types.js';
-export type * from './modules/notifications/types.js';
+export type { LicenseResult, LicenseModule, LicensePlanTier, LicenseFeatures, AICreditCheckResult, AIUsageRecord, AIProviderConfig, } from './modules/license/types.js';
+export type { KitsModule, SoulcraftKitConfig, } from './modules/kits/types.js';
+export type { WvizDocument, WvizEntity, WvizEdge, WvizSnapshot, WvizViewType, WdocDocument, WdocMeta, WdocBlock, WdocInlineContent, WdocTextNode, WdocMark, WdocParagraphBlock, WdocHeadingBlock, WdocBlockquoteBlock, WdocCodeBlock, WdocBulletListBlock, WdocOrderedListBlock, WdocListItemBlock, WdocTaskListBlock, WdocTaskItemBlock, WdocImageBlock, WdocVideoBlock, WdocIconBlock, WdocSvgEmbedBlock, WdocEmbedBlock, WdocTableBlock, WdocTableRowBlock, WdocTableCellBlock, WdocTableHeaderBlock, WdocHorizontalRuleBlock, WdocCalloutBlock, WslideDocument, WslideSlide, WslideBackground, WslideLayout, WslideTransition, WslideConfig, WquizDocument, WquizQuestion, WquizQuestionType, WquizAnswer, WquizScoringRules, SoulcraftFormat, SoulcraftFormatDocument, } from './modules/formats/types.js';
+export { SOULCRAFT_FORMATS } from './modules/formats/types.js';
+export type { BillingModule, BillingPlanType, SubscriptionStatus, ModelUsage, UsageData, UsageStatus, SubscriptionData, LimitCheckResult, BatchIncrementData, CreateCheckoutSessionOptions, CreatePortalSessionOptions, } from './modules/billing/types.js';
+export type { NotificationsModule, Notification, NotificationResult, NotificationSender, EmailNotification, SmsNotification, } from './modules/notifications/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAG9F,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,YAAY,EACV,MAAM,EACN,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,0BAA0B,CAAA;AACjC,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;AAGnC,YAAY,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAGvD,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAGjE,YAAY,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,YAAY,GACb,MAAM,yBAAyB,CAAA;AAGhC,YAAY,EACV,UAAU,EACV,YAAY,EACZ,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,GACT,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,MAAM,0BAA0B,CAAA;AAGjC,YAAY,EACV,QAAQ,EACR,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,UAAU,EACV,SAAS,EACT,cAAc,EACd,MAAM,EACN,OAAO,GACR,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAGjD,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,2BAA2B,CAAA;AAGlC,YAAY,EACV,YAAY,EACZ,KAAK,EACL,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAGlC,mBAAmB,4BAA4B,CAAA;AAC/C,mBAAmB,yBAAyB,CAAA;AAC5C,mBAAmB,4BAA4B,CAAA;AAC/C,mBAAmB,4BAA4B,CAAA;AAC/C,mBAAmB,kCAAkC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -14,4 +14,5 @@ export { createCapabilityToken, verifyCapabilityToken, } from './modules/brainy/
 export { SDKError, SDKDisconnectedError, SDKTimeoutError, SDKAuthError, SDKForbiddenError, SDKRpcError, SDKMethodNotFoundError, } from './modules/brainy/errors.js';
 export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, computeEmailHash, getAuthMode, getOIDCClientConfig, } from './modules/auth/config.js';
 export { AI_MODELS } from './modules/ai/types.js';
+export { SOULCRAFT_FORMATS } from './modules/formats/types.js';
 //# sourceMappingURL=index.js.map

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"}
+{"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/firestore-provider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module billing/firestore-provider
+ * @description Firestore-backed billing provider for production deployments.
+ *
+ * Reads subscription and license data from the `licenses` Firestore collection
+ * managed by Portal (`soulcraft.com`). Workshop, Venue, and Academy all write
+ * usage counters to the same document so Portal's Admin can see cross-product usage.
+ *
+ * This provider is activated when `FIREBASE_SERVICE_ACCOUNT_KEY` is set in the
+ * environment. `firebase-admin` is loaded lazily via dynamic import so that the
+ * SDK does not require the package when using the local provider.
+ *
+ * **Firestore document structure:**
+ * ```
+ * licenses/{docId}
+ *   email: string                  (user email — used to look up the doc)
+ *   product: 'workshop' | 'venue' | 'academy'
+ *   status: 'active' | 'past_due' | 'canceled' | 'trialing'
+ *   plan: 'standard' | 'byok'
+ *   credits: {
+ *     monthlyIncluded: number
+ *     monthlyUsed: number          (SDK increments this)
+ *     topUpBalance: number         (SDK decrements this)
+ *     inputTokens: number
+ *     outputTokens: number
+ *     byModel: Record<model, { input, output }>
+ *     periodStart: Timestamp
+ *     periodEnd: Timestamp
+ *     lastUpdated: Timestamp
+ *   }
+ *   stripeCustomerId: string
+ *   stripeSubscriptionId: string
+ *   cancelAtPeriodEnd: boolean
+ * ```
+ *
+ * Note: The `userId` passed to provider methods is the user's email address when
+ * using Firestore, since the `licenses` collection is keyed by email. Products
+ * must pass `user.email` (not `user.id`) when constructing the SDK in Firestore mode.
+ */
+import type { BillingProvider, UsageData, SubscriptionData, LimitCheckResult, UsageStatus, BatchIncrementData } from './types.js';
+/**
+ * Firestore-backed billing provider for production deployments.
+ *
+ * The `userId` parameter on all methods must be the user's **email address**,
+ * since the Firestore `licenses` collection is indexed by email.
+ */
+export declare class FirestoreBillingProvider implements BillingProvider {
+    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>;
+    private _toSubscription;
+    private _resetPeriod;
+}
+//# sourceMappingURL=firestore-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-provider.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/firestore-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAkJnB;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IACxD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8B9E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAiB5C,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAgC7E,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1H,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB7E,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAMtE,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOvD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOhD,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAM5D,OAAO,CAAC,eAAe;YA2BT,YAAY;CAe3B"}

package/dist/modules/billing/firestore-provider.js

@@ -0,0 +1,314 @@
+/**
+ * @module billing/firestore-provider
+ * @description Firestore-backed billing provider for production deployments.
+ *
+ * Reads subscription and license data from the `licenses` Firestore collection
+ * managed by Portal (`soulcraft.com`). Workshop, Venue, and Academy all write
+ * usage counters to the same document so Portal's Admin can see cross-product usage.
+ *
+ * This provider is activated when `FIREBASE_SERVICE_ACCOUNT_KEY` is set in the
+ * environment. `firebase-admin` is loaded lazily via dynamic import so that the
+ * SDK does not require the package when using the local provider.
+ *
+ * **Firestore document structure:**
+ * ```
+ * licenses/{docId}
+ *   email: string                  (user email — used to look up the doc)
+ *   product: 'workshop' | 'venue' | 'academy'
+ *   status: 'active' | 'past_due' | 'canceled' | 'trialing'
+ *   plan: 'standard' | 'byok'
+ *   credits: {
+ *     monthlyIncluded: number
+ *     monthlyUsed: number          (SDK increments this)
+ *     topUpBalance: number         (SDK decrements this)
+ *     inputTokens: number
+ *     outputTokens: number
+ *     byModel: Record<model, { input, output }>
+ *     periodStart: Timestamp
+ *     periodEnd: Timestamp
+ *     lastUpdated: Timestamp
+ *   }
+ *   stripeCustomerId: string
+ *   stripeSubscriptionId: string
+ *   cancelAtPeriodEnd: boolean
+ * ```
+ *
+ * Note: The `userId` passed to provider methods is the user's email address when
+ * using Firestore, since the `licenses` collection is keyed by email. Products
+ * must pass `user.email` (not `user.id`) when constructing the SDK in Firestore mode.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Lazy loader
+// ─────────────────────────────────────────────────────────────────────────────
+let _db;
+let _FieldValue;
+async function _getFirestore() {
+    if (_db && _FieldValue)
+        return { db: _db, FieldValue: _FieldValue };
+    const key = process.env['FIREBASE_SERVICE_ACCOUNT_KEY'];
+    if (!key)
+        throw new Error('FIREBASE_SERVICE_ACCOUNT_KEY is not set — cannot use Firestore billing provider');
+    // firebase-admin is an optional peer dependency — loaded at runtime only when configured.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const admin = await Function('return import("firebase-admin")')();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const { getFirestore, FieldValue } = await Function('return import("firebase-admin/firestore")')();
+    if (!admin.apps?.length) {
+        admin.initializeApp({
+            credential: admin.credential.cert(JSON.parse(Buffer.from(key, 'base64').toString('utf-8'))),
+            preferRest: true, // Use REST transport — required for Bun compatibility (avoids gRPC).
+        });
+    }
+    _db = getFirestore();
+    _FieldValue = FieldValue;
+    return { db: _db, FieldValue: _FieldValue };
+}
+const _docCache = new Map();
+const DOC_CACHE_TTL_MS = 5 * 60 * 1000;
+async function _getLicenseDoc(email) {
+    const cached = _docCache.get(email);
+    if (cached && Date.now() < cached.expiresAt)
+        return cached;
+    const { db } = await _getFirestore();
+    const snap = await db.collection('licenses')
+        .where('email', '==', email.toLowerCase())
+        .where('status', 'in', ['active', 'trialing', 'past_due'])
+        .get();
+    if (!snap.docs.length)
+        return null;
+    const doc = snap.docs[0];
+    const data = doc.data() ?? {};
+    const result = { data, docId: doc.id, ref: doc.ref, expiresAt: Date.now() + DOC_CACHE_TTL_MS };
+    _docCache.set(email, result);
+    return result;
+}
+function _invalidateCache(email) {
+    _docCache.delete(email);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Period helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function _toISO(ts) {
+    if (!ts)
+        return undefined;
+    if (typeof ts === 'string')
+        return ts;
+    // Firestore Timestamp object
+    if (typeof ts === 'object' && ts !== null && 'toDate' in ts) {
+        return ts.toDate().toISOString();
+    }
+    return undefined;
+}
+function _currentPeriod() {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+function _shouldReset(periodEnd) {
+    const iso = _toISO(periodEnd);
+    if (!iso)
+        return true;
+    return new Date() >= new Date(iso);
+}
+const FREE_TIER_LIMIT = 100;
+const MODEL_PRICING = {
+    'claude-haiku-4-5-20251001': { input: 0.80, output: 4.00 },
+    'claude-sonnet-4-6': { input: 3.00, output: 15.00 },
+    'claude-opus-4-6': { input: 15.00, output: 75.00 },
+};
+function _estimateCostUSD(byModel) {
+    let total = 0;
+    for (const [model, counts] of Object.entries(byModel)) {
+        const pricing = MODEL_PRICING[model];
+        if (!pricing)
+            continue;
+        total += (counts.input / 1_000_000) * pricing.input;
+        total += (counts.output / 1_000_000) * pricing.output;
+    }
+    return Math.round(total * 10_000) / 10_000;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider implementation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Firestore-backed billing provider for production deployments.
+ *
+ * The `userId` parameter on all methods must be the user's **email address**,
+ * since the Firestore `licenses` collection is indexed by email.
+ */
+export class FirestoreBillingProvider {
+    async checkLimit(userId, hasPersonalKey) {
+        if (hasPersonalKey) {
+            return { ok: true, remaining: Infinity, topUpBalance: 0, totalAvailable: Infinity, useTopUp: false };
+        }
+        const doc = await _getLicenseDoc(userId);
+        if (!doc) {
+            // No license — free tier.
+            return { ok: false, remaining: 0, topUpBalance: 0, totalAvailable: 0, useTopUp: false, reason: 'no_subscription' };
+        }
+        const credits = doc.data['credits'] ?? {};
+        const monthlyIncluded = credits['monthlyIncluded'] ?? FREE_TIER_LIMIT;
+        const monthlyUsed = credits['monthlyUsed'] ?? 0;
+        const topUpBalance = credits['topUpBalance'] ?? 0;
+        const periodEnd = credits['periodEnd'];
+        if (_shouldReset(periodEnd)) {
+            await this._resetPeriod(doc);
+            return { ok: true, remaining: monthlyIncluded, topUpBalance, totalAvailable: monthlyIncluded + topUpBalance, useTopUp: false };
+        }
+        const remaining = Math.max(0, monthlyIncluded - monthlyUsed);
+        const totalAvailable = remaining + topUpBalance;
+        if (remaining > 0)
+            return { ok: true, remaining, topUpBalance, totalAvailable, useTopUp: false };
+        if (topUpBalance > 0)
+            return { ok: true, remaining: 0, topUpBalance, totalAvailable, useTopUp: true };
+        return { ok: false, remaining: 0, topUpBalance: 0, totalAvailable: 0, useTopUp: false, reason: 'limit_reached' };
+    }
+    async getUsage(userId) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc) {
+            return { currentPeriod: _currentPeriod(), periodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(), messagesUsed: 0, inputTokens: 0, outputTokens: 0, byModel: {}, lastUpdated: new Date().toISOString() };
+        }
+        const credits = doc.data['credits'] ?? {};
+        return {
+            currentPeriod: _currentPeriod(),
+            periodEnd: _toISO(credits['periodEnd']) ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+            messagesUsed: credits['monthlyUsed'] ?? 0,
+            inputTokens: credits['inputTokens'] ?? 0,
+            outputTokens: credits['outputTokens'] ?? 0,
+            byModel: credits['byModel'] ?? {},
+            lastUpdated: _toISO(credits['lastUpdated']) ?? new Date().toISOString(),
+        };
+    }
+    async getUsageStatus(userId, hasPersonalKey) {
+        const usage = await this.getUsage(userId);
+        const doc = await _getLicenseDoc(userId);
+        const credits = doc?.data['credits'] ?? {};
+        const topUpBalance = credits['topUpBalance'] ?? 0;
+        const monthlyIncluded = credits['monthlyIncluded'] ?? FREE_TIER_LIMIT;
+        const subscription = doc ? this._toSubscription(doc.data) : undefined;
+        if (hasPersonalKey) {
+            return { mode: 'byok', usage, limit: null, remaining: null, topUpBalance, totalAvailable: null, percentUsed: null, resetsAt: usage.periodEnd, estimatedCostUSD: _estimateCostUSD(usage.byModel), ...(subscription ? { subscription } : {}) };
+        }
+        const isSubscriber = subscription?.status === 'active' || subscription?.status === 'trialing';
+        const remaining = Math.max(0, monthlyIncluded - usage.messagesUsed);
+        const totalAvailable = remaining + topUpBalance;
+        const percentUsed = Math.round((usage.messagesUsed / monthlyIncluded) * 100);
+        return {
+            mode: isSubscriber ? 'included' : 'free',
+            usage,
+            limit: monthlyIncluded,
+            remaining,
+            topUpBalance,
+            totalAvailable,
+            percentUsed,
+            resetsAt: usage.periodEnd,
+            estimatedCostUSD: _estimateCostUSD(usage.byModel),
+            ...(subscription ? { subscription } : {}),
+            isFreeUser: !isSubscriber,
+        };
+    }
+    async incrementUsage(userId, inputTokens, outputTokens, model, useTopUp) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return; // No license doc — free tier, usage not tracked in Firestore.
+        const { FieldValue } = await _getFirestore();
+        const updates = {
+            'credits.monthlyUsed': FieldValue.increment(1),
+            'credits.inputTokens': FieldValue.increment(inputTokens),
+            'credits.outputTokens': FieldValue.increment(outputTokens),
+            [`credits.byModel.${model}.input`]: FieldValue.increment(inputTokens),
+            [`credits.byModel.${model}.output`]: FieldValue.increment(outputTokens),
+            'credits.lastUpdated': FieldValue.serverTimestamp(),
+            'updatedAt': FieldValue.serverTimestamp(),
+        };
+        if (useTopUp)
+            updates['credits.topUpBalance'] = FieldValue.increment(-1);
+        await doc.ref.update(updates);
+        _invalidateCache(userId);
+    }
+    async batchIncrementUsage(userId, batch) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return;
+        const { FieldValue } = await _getFirestore();
+        const updates = {
+            'credits.monthlyUsed': FieldValue.increment(batch.messageCount),
+            'credits.inputTokens': FieldValue.increment(batch.inputTokens),
+            'credits.outputTokens': FieldValue.increment(batch.outputTokens),
+            'credits.lastUpdated': FieldValue.serverTimestamp(),
+            'updatedAt': FieldValue.serverTimestamp(),
+        };
+        if (batch.topUpUsed > 0)
+            updates['credits.topUpBalance'] = FieldValue.increment(-batch.topUpUsed);
+        for (const [model, counts] of Object.entries(batch.byModel)) {
+            updates[`credits.byModel.${model}.input`] = FieldValue.increment(counts.input);
+            updates[`credits.byModel.${model}.output`] = FieldValue.increment(counts.output);
+        }
+        await doc.ref.update(updates);
+        _invalidateCache(userId);
+    }
+    async getSubscription(userId) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return undefined;
+        return this._toSubscription(doc.data);
+    }
+    async hasActiveSubscription(userId) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return false;
+        const status = doc.data['status'];
+        return status === 'active' || status === 'trialing';
+    }
+    async getTopUpBalance(userId) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return 0;
+        const credits = doc.data['credits'] ?? {};
+        return credits['topUpBalance'] ?? 0;
+    }
+    async canAccessPaidFeature(userId) {
+        return this.hasActiveSubscription(userId);
+    }
+    // ── Internal helpers ────────────────────────────────────────────────────
+    _toSubscription(data) {
+        const status = data['status'];
+        if (!status)
+            return undefined;
+        const stripeCustomerId = data['stripeCustomerId'];
+        const stripeSubscriptionId = data['stripeSubscriptionId'];
+        const cancelAtPeriodEnd = data['cancelAtPeriodEnd'];
+        const giftedBy = data['giftedBy'];
+        const currentPeriodEnd = _toISO(data['credits']?.['periodEnd']);
+        const giftedAt = _toISO(data['giftedAt']);
+        const expiresAt = _toISO(data['expiresAt']);
+        const note = data['note'];
+        return {
+            plan: data['plan'] ?? 'standard',
+            status: status,
+            ...(stripeCustomerId ? { stripeCustomerId } : {}),
+            ...(stripeSubscriptionId ? { stripeSubscriptionId } : {}),
+            ...(currentPeriodEnd ? { currentPeriodEnd } : {}),
+            ...(cancelAtPeriodEnd !== undefined ? { cancelAtPeriodEnd } : {}),
+            ...(giftedBy ? { giftedBy } : {}),
+            ...(giftedAt ? { giftedAt } : {}),
+            ...(expiresAt ? { expiresAt } : {}),
+            ...(note ? { note } : {}),
+        };
+    }
+    async _resetPeriod(doc) {
+        const { FieldValue } = await _getFirestore();
+        const newPeriodEnd = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+        await doc.ref.update({
+            'credits.monthlyUsed': 0,
+            'credits.inputTokens': 0,
+            'credits.outputTokens': 0,
+            'credits.byModel': {},
+            'credits.periodStart': FieldValue.serverTimestamp(),
+            'credits.periodEnd': newPeriodEnd,
+            'credits.lastUpdated': FieldValue.serverTimestamp(),
+            'updatedAt': FieldValue.serverTimestamp(),
+        });
+        _invalidateCache(doc.docId);
+    }
+}
+//# sourceMappingURL=firestore-provider.js.map