@soulcraft/sdk 1.0.0 → 1.2.0

package/dist/modules/notifications/types.d.ts

@@ -1,7 +1,156 @@
 /**
  * @module notifications/types
- * @description Type definitions for sdk.notifications.*
- * Implementation: Phase 5 per ADR-001.
+ * @description Type definitions for sdk.notifications.* — the platform notification system.
+ *
+ * The notifications module provides a provider-agnostic interface for sending
+ * transactional email (via Postmark) and SMS (via Twilio). In development
+ * environments where neither API key is configured, a console-logging dev sender
+ * is used automatically.
+ *
+ * The `NotificationSender` interface is the central abstraction: every sender
+ * implementation (Postmark, Twilio, dev console, composite) implements it.
+ *
+ * @example
+ * ```typescript
+ * const sender = sdk.notifications.getSender()
+ * await sender.send({
+ *   type: 'email',
+ *   to: 'customer@example.com',
+ *   subject: 'Booking Confirmed',
+ *   htmlBody: '<h1>Your booking is confirmed!</h1>',
+ *   textBody: 'Your booking is confirmed.',
+ * })
+ * ```
  */
-export type {};
+/**
+ * An email notification to be sent via the configured email provider (Postmark).
+ */
+export interface EmailNotification {
+    /** Channel discriminant. Always `'email'`. */
+    type: 'email';
+    /** Recipient email address. */
+    to: string;
+    /**
+     * Sender email address.
+     * Defaults to `POSTMARK_FROM_EMAIL` when omitted.
+     */
+    from?: string;
+    /** Email subject line. */
+    subject: string;
+    /** HTML email body. */
+    htmlBody: string;
+    /** Plain-text fallback body (required for deliverability). */
+    textBody: string;
+    /** Optional reply-to email address. */
+    replyTo?: string;
+}
+/**
+ * An SMS notification to be sent via the configured SMS provider (Twilio).
+ */
+export interface SmsNotification {
+    /** Channel discriminant. Always `'sms'`. */
+    type: 'sms';
+    /**
+     * Recipient phone number in E.164 format, e.g. `'+17045551234'`.
+     * Must include country code.
+     */
+    to: string;
+    /**
+     * Sender phone number or Twilio messaging service SID.
+     * Defaults to `TWILIO_FROM_NUMBER` when omitted.
+     */
+    from?: string;
+    /** SMS message body. Maximum 1,600 characters for long SMS. */
+    body: string;
+}
+/**
+ * Union of all notification payload types.
+ * Discriminate on the `type` field.
+ */
+export type Notification = EmailNotification | SmsNotification;
+/**
+ * The result of a notification send attempt.
+ */
+export interface NotificationResult {
+    /** Whether the notification was accepted by the provider. */
+    success: boolean;
+    /**
+     * Provider-specific message identifier.
+     * - Postmark: `MessageID` (UUID)
+     * - Twilio: `sid` (e.g. `'SM...'`)
+     * - Dev sender: synthetic `'dev-{timestamp}-{random}'`
+     */
+    messageId?: string;
+    /** Human-readable error message if `success` is `false`. */
+    error?: string;
+}
+/**
+ * Interface implemented by all notification provider classes.
+ *
+ * Consumers of the SDK receive a `NotificationSender` from
+ * `sdk.notifications.getSender()` and call `send()` without needing to
+ * know which provider is configured underneath.
+ */
+export interface NotificationSender {
+    /**
+     * Send a notification via this provider.
+     *
+     * @param notification - The email or SMS notification payload.
+     * @returns A result indicating success/failure and the provider message ID.
+     */
+    send(notification: Notification): Promise<NotificationResult>;
+}
+/**
+ * The `sdk.notifications.*` namespace.
+ */
+export interface NotificationsModule {
+    /**
+     * Returns the configured notification sender for the current environment.
+     *
+     * - When `POSTMARK_SERVER_TOKEN` and/or `TWILIO_ACCOUNT_SID` + `TWILIO_AUTH_TOKEN`
+     *   are set, returns a `CompositeNotificationSender` wiring Postmark (email) and
+     *   Twilio (SMS) to the correct channel.
+     * - When neither is configured, returns a `DevSender` that logs notifications to
+     *   the console — ideal for local development without real API credentials.
+     *
+     * @returns A `NotificationSender` ready to use.
+     *
+     * @example
+     * ```typescript
+     * const sender = sdk.notifications.getSender()
+     * const result = await sender.send({ type: 'sms', to: '+17045551234', body: 'Your code is 123456' })
+     * if (!result.success) console.error(result.error)
+     * ```
+     */
+    getSender(): NotificationSender;
+    /**
+     * Create a Postmark email sender explicitly.
+     *
+     * Use when you need to send from a specific server token rather than the
+     * environment-configured default.
+     *
+     * @param serverToken - Postmark server API token.
+     * @param defaultFrom - Default sender email address.
+     * @returns A `NotificationSender` that only handles email.
+     */
+    createPostmarkSender(serverToken: string, defaultFrom: string): NotificationSender;
+    /**
+     * Create a Twilio SMS sender explicitly.
+     *
+     * @param accountSid - Twilio account SID.
+     * @param authToken - Twilio auth token.
+     * @param defaultFrom - Default sender phone number in E.164 format.
+     * @returns A `NotificationSender` that only handles SMS.
+     */
+    createTwilioSender(accountSid: string, authToken: string, defaultFrom: string): NotificationSender;
+    /**
+     * Create a development console sender.
+     *
+     * Logs all notifications to stdout with ANSI formatting. Returns a synthetic
+     * message ID. Never makes network calls.
+     *
+     * @returns A `NotificationSender` that logs to the console.
+     */
+    createDevSender(): NotificationSender;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/modules/notifications/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/notifications/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/notifications/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,IAAI,EAAE,OAAO,CAAA;IACb,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,IAAI,EAAE,KAAK,CAAA;IACX;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,eAAe,CAAA;AAM9D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAC9D;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,IAAI,kBAAkB,CAAA;IAE/B;;;;;;;;;OASG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAAA;IAElF;;;;;;;OAOG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAAA;IAElG;;;;;;;OAOG;IACH,eAAe,IAAI,kBAAkB,CAAA;CACtC"}

package/dist/modules/notifications/types.js

@@ -1,7 +1,26 @@
 /**
  * @module notifications/types
- * @description Type definitions for sdk.notifications.*
- * Implementation: Phase 5 per ADR-001.
+ * @description Type definitions for sdk.notifications.* — the platform notification system.
+ *
+ * The notifications module provides a provider-agnostic interface for sending
+ * transactional email (via Postmark) and SMS (via Twilio). In development
+ * environments where neither API key is configured, a console-logging dev sender
+ * is used automatically.
+ *
+ * The `NotificationSender` interface is the central abstraction: every sender
+ * implementation (Postmark, Twilio, dev console, composite) implements it.
+ *
+ * @example
+ * ```typescript
+ * const sender = sdk.notifications.getSender()
+ * await sender.send({
+ *   type: 'email',
+ *   to: 'customer@example.com',
+ *   subject: 'Booking Confirmed',
+ *   htmlBody: '<h1>Your booking is confirmed!</h1>',
+ *   textBody: 'Your booking is confirmed.',
+ * })
+ * ```
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/modules/notifications/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/notifications/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/notifications/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/server/create-sdk.d.ts

@@ -52,6 +52,10 @@ export interface CreateSDKOptions {
  * `sdk.ai.*` calls go directly to the Anthropic API (requires `ANTHROPIC_API_KEY`).
  * `sdk.skills.*` reads from the Brainy VFS and falls back to `@soulcraft/kits`.
  * `sdk.events` is a local EventEmitter — events do not cross process boundaries.
+ * `sdk.billing.*` stores usage locally (dev) or in Firestore (prod via `FIREBASE_SERVICE_ACCOUNT_KEY`).
+ * `sdk.license.*` activates via `@soulcraft/cortex` and delegates credit metering to `sdk.billing`.
+ * `sdk.kits.*` reads from the `@soulcraft/kits` registry (optional peer dependency).
+ * `sdk.notifications.*` sends via Postmark/Twilio or logs to the console in dev mode.
  *
  * @param options - SDK creation options.
  * @returns A fully assembled `SoulcraftSDK` instance.

package/dist/server/create-sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-sdk.d.ts","sourceRoot":"","sources":["../../src/server/create-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAO/C,OAAO,KAAK,EAAE,YAAY,EAAyC,MAAM,aAAa,CAAA;AAOtF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;CACd;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAiDjE"}
+{"version":3,"file":"create-sdk.d.ts","sourceRoot":"","sources":["../../src/server/create-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAW/C,OAAO,KAAK,EAAE,YAAY,EAAyC,MAAM,aAAa,CAAA;AAOtF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;CACd;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAqDjE"}

package/dist/server/create-sdk.js

@@ -33,6 +33,10 @@ import { createBrainyProxy } from '../modules/brainy/proxy.js';
 import { createEventsModule } from '../modules/events/index.js';
 import { createAiModule } from '../modules/ai/index.js';
 import { createSkillsModule } from '../modules/skills/index.js';
+import { createLicenseModule } from '../modules/license/index.js';
+import { createKitsModule } from '../modules/kits/index.js';
+import { createBillingModule } from '../modules/billing/index.js';
+import { createNotificationsModule } from '../modules/notifications/index.js';
 import { createCapabilityToken, verifyCapabilityToken } from '../modules/brainy/auth.js';
 // ─────────────────────────────────────────────────────────────────────────────
 // Factory
@@ -46,6 +50,10 @@ import { createCapabilityToken, verifyCapabilityToken } from '../modules/brainy/
  * `sdk.ai.*` calls go directly to the Anthropic API (requires `ANTHROPIC_API_KEY`).
  * `sdk.skills.*` reads from the Brainy VFS and falls back to `@soulcraft/kits`.
  * `sdk.events` is a local EventEmitter — events do not cross process boundaries.
+ * `sdk.billing.*` stores usage locally (dev) or in Firestore (prod via `FIREBASE_SERVICE_ACCOUNT_KEY`).
+ * `sdk.license.*` activates via `@soulcraft/cortex` and delegates credit metering to `sdk.billing`.
+ * `sdk.kits.*` reads from the `@soulcraft/kits` registry (optional peer dependency).
+ * `sdk.notifications.*` sends via Postmark/Twilio or logs to the console in dev mode.
  *
  * @param options - SDK creation options.
  * @returns A fully assembled `SoulcraftSDK` instance.
@@ -73,6 +81,10 @@ export function createSDK(options) {
     const events = createEventsModule();
     const ai = createAiModule();
     const skills = createSkillsModule(brain);
+    const billing = createBillingModule();
+    const license = createLicenseModule({ billing });
+    const kits = createKitsModule();
+    const notifications = createNotificationsModule();
     const auth = {
         verifyToken: (token, secret) => verifyCapabilityToken(token, secret),
         createToken: (opts) => createCapabilityToken(opts),
@@ -85,13 +97,14 @@ export function createSDK(options) {
         events,
         ai,
         skills,
-        // Stubs for unimplemented modules — will throw if called
-        license: _unimplementedModule('license'),
-        kits: _unimplementedModule('kits'),
-        formats: _unimplementedModule('formats'),
-        billing: _unimplementedModule('billing'),
-        notifications: _unimplementedModule('notifications'),
+        license,
+        kits,
+        billing,
+        notifications,
         async shutdown() {
+            billing.stopFlush();
+            await billing.flush();
+            license.stopHeartbeat();
             await brain.flush();
         },
         async flush(scopeKey) {
@@ -102,24 +115,4 @@ export function createSDK(options) {
         },
     };
 }
-// ─────────────────────────────────────────────────────────────────────────────
-// Internal helpers
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Creates a Proxy that throws a descriptive error for any property access
- * on an unimplemented SDK module. This makes missing modules fail fast and
- * informatively rather than silently returning undefined.
- *
- * @param moduleName - The module name shown in the error message.
- * @returns A Proxy that throws on any property access.
- */
-function _unimplementedModule(moduleName) {
-    return new Proxy({}, {
-        get(_target, prop) {
-            throw new Error(`sdk.${moduleName}.${String(prop)} is not yet implemented. ` +
-                `The '${moduleName}' module is planned for a future SDK release. ` +
-                `See docs/ADR-001-sdk-design.md for the implementation roadmap.`);
-        },
-    });
-}
 //# sourceMappingURL=create-sdk.js.map

package/dist/server/create-sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-sdk.js","sourceRoot":"","sources":["../../src/server/create-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAsBxF,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAEzB,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA;IAC3C,MAAM,WAAW,GAAG,iBAAiB,CAAC,SAAS,CAAoB,CAAA;IAEnE,wEAAwE;IACxE,2EAA2E;IAC3E,8DAA8D;IAC9D,MAAM,GAAG,GAAI,WAAmB,CAAC,GAAgB,CAAA;IACjD,8DAA8D;IAC9D,MAAM,QAAQ,GAAI,WAAmB,CAAC,QAA0B,CAAA;IAEhE,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,EAAE,GAAG,cAAc,EAAE,CAAA;IAC3B,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAExC,MAAM,IAAI,GAAe;QACvB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC;QACpE,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC;KACnD,CAAA;IAED,OAAO;QACL,MAAM,EAAE,WAAW;QACnB,GAAG;QACH,QAAQ;QACR,IAAI;QACJ,MAAM;QACN,EAAE;QACF,MAAM;QAEN,yDAAyD;QACzD,OAAO,EAAE,oBAAoB,CAAC,SAAS,CAAC;QACxC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC;QAClC,OAAO,EAAE,oBAAoB,CAAC,SAAS,CAAC;QACxC,OAAO,EAAE,oBAAoB,CAAC,SAAS,CAAC;QACxC,aAAa,EAAE,oBAAoB,CAAC,eAAe,CAAC;QAEpD,KAAK,CAAC,QAAQ;YACZ,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,QAAgB;YAC1B,qEAAqE;YACrE,qEAAqE;YACrE,KAAK,QAAQ,CAAA;YACb,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;KACF,CAAA;AACH,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAAC,UAAkB;IAC9C,OAAO,IAAI,KAAK,CAAC,EAA6B,EAAE;QAC9C,GAAG,CAAC,OAAO,EAAE,IAAqB;YAChC,MAAM,IAAI,KAAK,CACb,OAAO,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,2BAA2B;gBAC5D,QAAQ,UAAU,gDAAgD;gBAClE,gEAAgE,CACjE,CAAA;QACH,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"create-sdk.js","sourceRoot":"","sources":["../../src/server/create-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAC7E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAsBxF,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAEzB,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA;IAC3C,MAAM,WAAW,GAAG,iBAAiB,CAAC,SAAS,CAAoB,CAAA;IAEnE,wEAAwE;IACxE,2EAA2E;IAC3E,8DAA8D;IAC9D,MAAM,GAAG,GAAI,WAAmB,CAAC,GAAgB,CAAA;IACjD,8DAA8D;IAC9D,MAAM,QAAQ,GAAI,WAAmB,CAAC,QAA0B,CAAA;IAEhE,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,EAAE,GAAG,cAAc,EAAE,CAAA;IAC3B,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IACxC,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAA;IACrC,MAAM,OAAO,GAAG,mBAAmB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IAChD,MAAM,IAAI,GAAG,gBAAgB,EAAE,CAAA;IAC/B,MAAM,aAAa,GAAG,yBAAyB,EAAE,CAAA;IAEjD,MAAM,IAAI,GAAe;QACvB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC;QACpE,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC;KACnD,CAAA;IAED,OAAO;QACL,MAAM,EAAE,WAAW;QACnB,GAAG;QACH,QAAQ;QACR,IAAI;QACJ,MAAM;QACN,EAAE;QACF,MAAM;QACN,OAAO;QACP,IAAI;QACJ,OAAO;QACP,aAAa;QAEb,KAAK,CAAC,QAAQ;YACZ,OAAO,CAAC,SAAS,EAAE,CAAA;YACnB,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA;YACrB,OAAO,CAAC,aAAa,EAAE,CAAA;YACvB,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,QAAgB;YAC1B,qEAAqE;YACrE,qEAAqE;YACrE,KAAK,QAAQ,CAAA;YACb,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/server/hall-handlers.d.ts

@@ -1,139 +1,97 @@
 /**
  * @module server/hall-handlers
- * @description Factory functions for mounting Hall WebRTC signaling over WebSocket.
+ * @description Hall module factory and TURN credential utilities for product backends.
  *
- * Hall uses a lightweight JSON signaling protocol over WebSocket:
+ * Hall is a standalone server — products connect to it over WebSocket rather than
+ * running signaling in-process. This module exports:
  *
- *   Client → Server:
- *     { type: 'offer',  sdp: string }              — SDP offer (first message from peer)
- *     { type: 'ice',    candidate: string }         — ICE candidate trickle
- *     { type: 'data',   channel: string, data: number[] }  — data channel message
- *     { type: 'leave' }                             — graceful peer disconnect
+ * - `createHallModule` — creates a server-side Hall control-plane client
+ * - `generateTurnCredentials` — generates time-limited TURN credentials if a product
+ *   needs to expose TURN info independently (e.g. for a custom ICE server list)
  *
- *   Server → Client:
- *     { type: 'answer', sdp: string }               — SDP answer
- *     { type: 'ice',    candidate: string }          — ICE candidate from SFU
- *     { type: 'speaker_changed', speakerId: string }
- *     { type: 'concept_mention', ...ConceptEvent }
- *     { type: 'relation_proposed', ...RelationProposedEvent }
- *     { type: 'transcript', peerId, text, isFinal, sessionMs }
- *     { type: 'attention', ...AttentionEvent }
- *     { type: 'track_added', peerId, trackId, kind }
- *     { type: 'track_removed', peerId, trackId }
- *     { type: 'error', message: string }
+ * The signaling WebSocket (offer/answer/ICE) is handled directly by the Hall server,
+ * not by the product backend. Products only manage the control plane:
+ * room creation, session token minting, and recording control.
  *
- * Products mount a single WebSocket route (e.g. `GET /api/hall/rooms/:roomId/signal`)
- * and delegate to the handler returned by createHallRoomHandler().
- *
- * @example Hono mounting
+ * @example Academy startup
  * ```typescript
- * import { createHallRoomHandler } from '@soulcraft/sdk/server'
+ * import { createHallModule } from '@soulcraft/sdk/server'
  *
- * const hallHandler = createHallRoomHandler({
- *   server: hallServer,
- *   authenticate: async (req) => getSessionUser(req),
- *   resolvePeerId: (req, user) => (user as { id: string }).id,
- *   resolveRoomId: (req) => new URL(req.url).pathname.split('/').at(-2)!,
+ * const hall = createHallModule({
+ *   url: process.env.HALL_URL!,          // wss://hall.soulcraft.com
+ *   productName: 'academy',
+ *   secret: process.env.HALL_ACADEMY_SECRET!,
  * })
+ * await hall.connect()
  *
- * app.get('/api/hall/rooms/:roomId/signal', upgradeWebSocket((c) => {
- *   const session = await hallHandler.handleUpgrade(c.req.raw)
- *   if (!session) return { onClose: () => {} }
- *   return {
- *     onMessage: (event, ws) => hallHandler.handleMessage(session, event.data as string, (m) => ws.send(m)),
- *     onClose: () => hallHandler.handleClose(session),
+ * hall.onDisconnect((reason) => {
+ *   console.error('[Hall] disconnected:', reason)
+ * })
+ * hall.onReconnect(async () => {
+ *   // Re-create any active rooms after reconnect
+ *   for (const session of activeSessions) {
+ *     await hall.createRoom(session.id, session.roomOptions)
  *   }
- * }))
+ * })
+ * ```
+ *
+ * @example Lesson join route
+ * ```typescript
+ * app.post('/api/lessons/:id/join', requireAuth, async (c) => {
+ *   const { id } = c.req.param()
+ *   const user = c.get('user')!
+ *
+ *   // Create room if it doesn't already exist
+ *   if (!hall.getRoom(id)) {
+ *     await hall.createRoom(id, {
+ *       enableTranscription: true,
+ *       concepts: await loadLessonConcepts(id),
+ *     })
+ *   }
+ *
+ *   // Mint a short-lived token for this browser peer
+ *   const { token } = await hall.createSessionToken(id, user.id, 3600)
+ *   return c.json({ token, hallUrl: process.env.HALL_URL })
+ * })
  * ```
  */
-import type { HallServer, Room } from '@soulcraft/hall';
-/**
- * @description An active peer connection managed by the Hall signaling handler.
- * Returned by handleUpgrade() and passed to every subsequent call.
- */
-export interface HallSession {
-    /** The authenticated peer ID (e.g. user ID). */
-    readonly peerId: string;
-    /** The room this peer is joining. */
-    readonly room: Room;
-    /** Whether the peer has completed the SDP offer/answer handshake. */
-    joined: boolean;
-}
-/**
- * @description Configuration for createHallRoomHandler().
- */
-export interface HallRoomHandlerConfig {
-    /**
-     * The running HallServer instance to use for room management.
-     */
-    server: HallServer;
-    /**
-     * Authenticates an incoming WebSocket upgrade request.
-     * Return the authenticated user object (any shape), or null/undefined to reject.
-     * @param request - The HTTP upgrade request.
-     * @returns Authenticated user or null/undefined.
-     */
-    authenticate(request: Request): Promise<unknown> | unknown;
-    /**
-     * Derives the peer ID from the request and the authenticated user.
-     * @param request - The HTTP upgrade request.
-     * @param user - The result of authenticate().
-     * @returns The peer ID string (e.g. user.id, session.userId).
-     */
-    resolvePeerId(request: Request, user: unknown): string;
-    /**
-     * Derives the room ID from the request.
-     * @param request - The HTTP upgrade request.
-     * @returns The room ID string (e.g. from URL path parameter).
-     */
-    resolveRoomId(request: Request): string;
-    /**
-     * Optional room options applied when the room does not already exist.
-     * @param request - The HTTP upgrade request.
-     * @param user - The authenticated user.
-     * @returns RoomOptions or undefined to use defaults.
-     */
-    roomOptions?(request: Request, user: unknown): import('@soulcraft/hall').RoomOptions | undefined;
-}
+import { HallClient } from '../modules/hall/server.js';
+import type { HallConnectionOptions, HallModule } from '../modules/hall/types.js';
+export { HallClient };
+export type { HallConnectionOptions, HallModule };
 /**
- * @description The object returned by createHallRoomHandler(). Products pass incoming
- * WebSocket connections through this handler for complete Hall signaling management.
+ * Create a server-side Hall module connected to the Hall standalone server.
+ *
+ * Returns a `HallModule` backed by a persistent WebSocket connection. Call `connect()`
+ * once at process startup — the client auto-reconnects on unexpected disconnects.
+ *
+ * @param options - Hall server URL, product name, and shared secret.
+ * @returns A `HallModule` instance (not yet connected — call `module.connect()`).
+ *
+ * @example
+ * ```typescript
+ * const hall = createHallModule({
+ *   url: process.env.HALL_URL!,
+ *   productName: 'academy',
+ *   secret: process.env.HALL_ACADEMY_SECRET!,
+ * })
+ * await hall.connect()
+ * ```
  */
-export interface HallRoomHandler {
-    /**
-     * Authenticates the upgrade request and resolves the room/peer. Call this when
-     * the WebSocket connection is established.
-     * @param request - The HTTP upgrade request.
-     * @returns A HallSession if authentication succeeded, or null to reject.
-     */
-    handleUpgrade(request: Request): Promise<HallSession | null>;
-    /**
-     * Processes an incoming signaling message from a peer.
-     * @param session - The HallSession returned by handleUpgrade().
-     * @param data - Raw JSON string from the WebSocket message event.
-     * @param send - Callback to send a JSON string back to this peer's client.
-     */
-    handleMessage(session: HallSession, data: string, send: (message: string) => void): Promise<void>;
-    /**
-     * Cleans up when a peer disconnects. Always call this on WebSocket close/error.
-     * @param session - The HallSession to clean up.
-     */
-    handleClose(session: HallSession): Promise<void>;
-}
+export declare function createHallModule(options: HallConnectionOptions): HallModule;
 /**
- * @description TURN credential options for generateTurnCredentials().
+ * Options for {@link generateTurnCredentials}.
  */
 export interface TurnCredentialOptions {
-    /** The HMAC-SHA1 secret shared between this server and the TURN server. */
+    /** The HMAC-SHA1 secret shared with the TURN server (i.e. `TURN_SECRET` from `hall.toml`). */
     secret: string;
-    /** Peer/user identifier embedded in the credential username. */
+    /** Peer or user identifier embedded in the credential username. */
     peerId: string;
     /** Credential TTL in seconds (default: 86400 — 24 hours). */
     ttlSeconds?: number;
 }
 /**
- * @description Time-limited TURN credentials for a peer, suitable for passing to
- * RTCPeerConnection as iceServers configuration.
+ * Time-limited TURN credentials, ready for use in `RTCPeerConnection.iceServers`.
  */
 export interface TurnCredentials {
     /** Username in the form `{expiryTimestamp}:{peerId}`. */
@@ -144,52 +102,33 @@ export interface TurnCredentials {
     expiresAt: number;
 }
 /**
- * @description Generates time-limited TURN credentials using the TURN REST API
- * authentication mechanism (RFC draft-uberti-behave-turn-rest-00).
+ * Generate time-limited TURN credentials using the TURN REST API authentication
+ * mechanism (RFC draft-uberti-behave-turn-rest-00).
  *
- * The TURN server must be configured with the same shared secret. Credentials
- * expire after ttlSeconds and cannot be reused after that time.
+ * Hall's in-process TURN server uses the same shared `TURN_SECRET` from `hall.toml`.
+ * Call this if you need to expose TURN credentials via a product API endpoint
+ * (e.g. for a custom ICE server list in a legacy client). In most cases the browser
+ * SDK handles TURN automatically via the Hall signaling connection.
  *
- * @param options - Secret, peer ID, and optional TTL.
- * @returns Time-limited TURN credentials ready for RTCPeerConnection.iceServers.
+ * @param options - TURN secret, peer ID, and optional TTL.
+ * @returns Time-limited TURN credentials.
  *
  * @example
  * ```typescript
- * const creds = generateTurnCredentials({
- *   secret: process.env.TURN_SECRET!,
- *   peerId: user.id,
- *   ttlSeconds: 3600,
+ * app.get('/api/turn-credentials', requireAuth, (c) => {
+ *   const user = c.get('user')!
+ *   const creds = generateTurnCredentials({
+ *     secret: process.env.TURN_SECRET!,
+ *     peerId: user.id,
+ *     ttlSeconds: 3600,
+ *   })
+ *   return c.json({
+ *     urls: 'turn:hall.soulcraft.com:3478',
+ *     username: creds.username,
+ *     credential: creds.password,
+ *   })
  * })
- * // Pass to client:
- * return c.json({ turnUsername: creds.username, turnPassword: creds.password })
  * ```
  */
 export declare function generateTurnCredentials(options: TurnCredentialOptions): TurnCredentials;
-/**
- * @description Factory that creates a framework-agnostic Hall WebRTC signaling
- * handler. Products mount the returned handler at a WebSocket route and delegate
- * upgrade, message, and close lifecycle events to it.
- *
- * The handler owns the full signaling lifecycle:
- * - Authenticates the upgrade request
- * - Resolves or creates the Room via HallServer
- * - Forwards SDP offer → gets SDP answer from the NAPI SFU
- * - Forwards ICE candidates in both directions
- * - Wires Room events (transcript, concept_mention, relation_proposed, etc.) to the peer's send callback
- * - Cleans up on disconnect
- *
- * @param config - Handler configuration.
- * @returns A HallRoomHandler with handleUpgrade / handleMessage / handleClose.
- *
- * @example
- * ```typescript
- * const hallHandler = createHallRoomHandler({
- *   server: hallServer,
- *   authenticate: (req) => verifySession(req.headers.get('cookie') ?? ''),
- *   resolvePeerId: (_req, user) => (user as { id: string }).id,
- *   resolveRoomId: (req) => new URL(req.url).pathname.split('/').at(-2)!,
- * })
- * ```
- */
-export declare function createHallRoomHandler(config: HallRoomHandlerConfig): HallRoomHandler;
 //# sourceMappingURL=hall-handlers.d.ts.map

package/dist/server/hall-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hall-handlers.d.ts","sourceRoot":"","sources":["../../src/server/hall-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,IAAI,EAIL,MAAM,iBAAiB,CAAA;AAOxB;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,UAAU,CAAA;IAElB;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAE1D;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAA;IAEtD;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAA;IAEvC;;;;;OAKG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,iBAAiB,EAAE,WAAW,GAAG,SAAS,CAAA;CACjG;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IAE5D;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjG;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAA;IACd,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAA;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CAQvF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAqJpF"}
+{"version":3,"file":"hall-handlers.d.ts","sourceRoot":"","sources":["../../src/server/hall-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAGH,OAAO,EAAE,UAAU,EAAyC,MAAM,2BAA2B,CAAA;AAC7F,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAEjF,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,YAAY,EAAE,qBAAqB,EAAE,UAAU,EAAE,CAAA;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAE3E;AAID;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CAMvF"}