@soulcraft/sdk 1.6.2 → 1.7.0

package/dist/transports/workshop.js

@@ -0,0 +1,307 @@
+/**
+ * @module transports/workshop
+ * @description PostMessage transport for non-brainy API calls from kit iframes to
+ * the Workshop parent frame.
+ *
+ * While {@link PostMessageTransport} handles Brainy RPC (`brainy:request` /
+ * `brainy:response`), this transport handles generic HTTP-style API calls —
+ * AI chat streaming, Hall room joins, Pulse analytics, file operations, and
+ * notifications — using the `workshop:request` / `workshop:response` /
+ * `workshop:stream` wire protocol.
+ *
+ * The parent frame (PreviewFrame.svelte) receives `workshop:request` messages,
+ * forwards them as real HTTP requests to Workshop's backend, and relays the
+ * response back via `workshop:response` (JSON) or `workshop:stream` (SSE chunks).
+ *
+ * ## Wire protocol
+ *
+ * **Request** (kit iframe → parent):
+ * ```json
+ * { "type": "workshop:request", "id": "<uuid>", "path": "/api/ai/chat",
+ *   "method": "POST", "body": "{...}", "stream": true, "headers": {} }
+ * ```
+ *
+ * **Response** (parent → kit iframe, non-streaming):
+ * ```json
+ * { "type": "workshop:response", "id": "<uuid>", "result": {...} }
+ * { "type": "workshop:response", "id": "<uuid>", "error": { "code": "...", "message": "..." } }
+ * ```
+ *
+ * **Stream chunk** (parent → kit iframe, streaming):
+ * ```json
+ * { "type": "workshop:stream", "id": "<uuid>", "chunk": "..." }
+ * { "type": "workshop:stream", "id": "<uuid>", "done": true }
+ * { "type": "workshop:stream", "id": "<uuid>", "error": "..." }
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { WorkshopTransport } from '@soulcraft/sdk/client'
+ *
+ * const transport = new WorkshopTransport('https://workshop.soulcraft.com')
+ *
+ * // JSON call
+ * const result = await transport.call('/api/hall/rooms/my-room/join', 'POST', '{"audio":true}')
+ *
+ * // Streaming call (AI chat)
+ * for await (const chunk of transport.stream('/api/ai/chat', 'POST', body)) {
+ *   process.stdout.write(chunk)
+ * }
+ * ```
+ *
+ * @see {@link PostMessageTransport} for Brainy-specific RPC transport.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Transport
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * PostMessage transport for generic (non-brainy) API calls from kit iframes.
+ *
+ * Each `call()` posts a `workshop:request` message to `window.parent` and awaits
+ * a matching `workshop:response`. For streaming endpoints, `stream()` collects
+ * `workshop:stream` chunks and yields them as an `AsyncIterable<string>`.
+ *
+ * @example
+ * ```typescript
+ * const t = new WorkshopTransport(workshopOrigin)
+ *
+ * // Fire-and-forget analytics
+ * t.call('/api/pulse/track', 'POST', JSON.stringify({ event: 'page_view' }))
+ *
+ * // Stream AI tokens
+ * for await (const token of t.stream('/api/ai/chat', 'POST', body)) {
+ *   output += token
+ * }
+ * ```
+ */
+export class WorkshopTransport {
+    _targetOrigin;
+    _timeoutMs;
+    _pendingCalls = new Map();
+    _pendingStreams = new Map();
+    _closed = false;
+    _messageListener;
+    _listenerWindow;
+    _parentWindow;
+    /**
+     * @param targetOrigin - The Workshop parent frame's origin for postMessage security.
+     *   Must be an explicit origin in production; `'*'` is acceptable only in dev.
+     * @param timeoutMs - Per-call timeout in milliseconds. Default: 60 000 (longer than
+     *   brainy RPC because AI chat streams can take a while to start).
+     * @param listenerWindow - Window for message events. Defaults to `window`.
+     * @param parentWindow - Window to post messages to. Defaults to `window.parent`.
+     */
+    constructor(targetOrigin, timeoutMs = 60_000, listenerWindow, parentWindow) {
+        this._targetOrigin = targetOrigin;
+        this._timeoutMs = timeoutMs;
+        this._listenerWindow = listenerWindow ?? window;
+        this._parentWindow = parentWindow ?? window.parent;
+        this._messageListener = (event) => this._handleMessage(event);
+        this._listenerWindow.addEventListener('message', this._messageListener);
+    }
+    // ── Internal ──────────────────────────────────────────────────────────────
+    _handleMessage(event) {
+        const data = event.data;
+        if (!data || typeof data.type !== 'string')
+            return;
+        // ── JSON response ─────────────────────────────────────────────────────
+        if (data.type === 'workshop:response') {
+            const pending = this._pendingCalls.get(data.id);
+            if (!pending)
+                return;
+            clearTimeout(pending.timer);
+            this._pendingCalls.delete(data.id);
+            if (data.error) {
+                pending.reject(new Error(`${data.error.code}: ${data.error.message}`));
+            }
+            else {
+                pending.resolve(data.result);
+            }
+            return;
+        }
+        // ── Stream chunk ──────────────────────────────────────────────────────
+        if (data.type === 'workshop:stream') {
+            const stream = this._pendingStreams.get(data.id);
+            if (!stream)
+                return;
+            if (data.error) {
+                stream.ended = true;
+                stream.error = data.error;
+                clearTimeout(stream.timer);
+                this._pendingStreams.delete(data.id);
+                if (stream.waiter) {
+                    const w = stream.waiter;
+                    stream.waiter = null;
+                    w({ value: undefined, done: true });
+                }
+                return;
+            }
+            if (data.done) {
+                stream.ended = true;
+                clearTimeout(stream.timer);
+                this._pendingStreams.delete(data.id);
+                if (stream.waiter) {
+                    const w = stream.waiter;
+                    stream.waiter = null;
+                    w({ value: undefined, done: true });
+                }
+                return;
+            }
+            if (data.chunk !== undefined) {
+                // Reset timeout on each chunk — the stream is alive.
+                clearTimeout(stream.timer);
+                stream.timer = setTimeout(() => this._streamTimeout(data.id), this._timeoutMs);
+                if (stream.waiter) {
+                    // Consumer is waiting — deliver directly.
+                    const w = stream.waiter;
+                    stream.waiter = null;
+                    w({ value: data.chunk, done: false });
+                }
+                else {
+                    // Consumer hasn't called next() yet — buffer.
+                    stream.buffer.push(data.chunk);
+                }
+            }
+        }
+    }
+    _streamTimeout(id) {
+        const stream = this._pendingStreams.get(id);
+        if (!stream)
+            return;
+        stream.ended = true;
+        stream.error = 'Stream timed out';
+        this._pendingStreams.delete(id);
+        if (stream.waiter) {
+            const w = stream.waiter;
+            stream.waiter = null;
+            w({ value: undefined, done: true });
+        }
+    }
+    _generateId() {
+        if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+            return crypto.randomUUID();
+        }
+        return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    /**
+     * Send a JSON API call through the PostMessage relay.
+     *
+     * @param path - API endpoint path (e.g. '/api/hall/rooms/my-room/join').
+     * @param method - HTTP method.
+     * @param body - JSON-serialized request body.
+     * @param headers - Extra headers to forward.
+     * @returns The parsed JSON response body.
+     * @throws {Error} If the transport is closed, the request times out, or the
+     *   parent responds with an error.
+     */
+    async call(path, method = 'POST', body, headers) {
+        if (this._closed)
+            throw new Error('WorkshopTransport is closed');
+        const id = this._generateId();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this._pendingCalls.delete(id);
+                reject(new Error(`WorkshopTransport: call to ${path} timed out after ${this._timeoutMs}ms`));
+            }, this._timeoutMs);
+            this._pendingCalls.set(id, { resolve, reject, timer });
+            const message = {
+                type: 'workshop:request',
+                id,
+                path,
+                method,
+                body,
+                headers,
+            };
+            this._parentWindow.postMessage(message, this._targetOrigin);
+        });
+    }
+    /**
+     * Send a streaming API call through the PostMessage relay.
+     *
+     * The parent frame reads the HTTP response as SSE chunks and forwards each as
+     * a `workshop:stream` message. This method yields each chunk as it arrives.
+     *
+     * @param path - API endpoint path (e.g. '/api/ai/chat').
+     * @param method - HTTP method (typically 'POST').
+     * @param body - JSON-serialized request body.
+     * @param headers - Extra headers to forward.
+     * @returns An async iterable of string chunks.
+     */
+    stream(path, method = 'POST', body, headers) {
+        if (this._closed)
+            throw new Error('WorkshopTransport is closed');
+        const id = this._generateId();
+        const pending = {
+            buffer: [],
+            ended: false,
+            waiter: null,
+            timer: setTimeout(() => this._streamTimeout(id), this._timeoutMs),
+        };
+        this._pendingStreams.set(id, pending);
+        const message = {
+            type: 'workshop:request',
+            id,
+            path,
+            method,
+            body,
+            stream: true,
+            headers,
+        };
+        this._parentWindow.postMessage(message, this._targetOrigin);
+        // Return an AsyncIterable that pulls from the pending stream state.
+        return {
+            [Symbol.asyncIterator]: () => ({
+                next: () => {
+                    // Check for buffered data first.
+                    if (pending.buffer.length > 0) {
+                        return Promise.resolve({ value: pending.buffer.shift(), done: false });
+                    }
+                    // Stream ended — check for error.
+                    if (pending.ended) {
+                        if (pending.error) {
+                            return Promise.reject(new Error(`WorkshopTransport stream error: ${pending.error}`));
+                        }
+                        return Promise.resolve({ value: undefined, done: true });
+                    }
+                    // Wait for the next chunk.
+                    return new Promise((resolve) => {
+                        pending.waiter = resolve;
+                    });
+                },
+            }),
+        };
+    }
+    /**
+     * Returns `true` if the transport is open and usable.
+     */
+    isAlive() {
+        return !this._closed;
+    }
+    /**
+     * Close the transport, removing the message listener and rejecting all pending calls.
+     */
+    close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        this._listenerWindow.removeEventListener('message', this._messageListener);
+        const callError = new Error('WorkshopTransport closed');
+        for (const [id, pending] of this._pendingCalls) {
+            clearTimeout(pending.timer);
+            pending.reject(callError);
+            this._pendingCalls.delete(id);
+        }
+        for (const [id, stream] of this._pendingStreams) {
+            clearTimeout(stream.timer);
+            stream.ended = true;
+            stream.error = 'Transport closed';
+            this._pendingStreams.delete(id);
+            if (stream.waiter) {
+                stream.waiter({ value: undefined, done: true });
+            }
+        }
+    }
+}
+//# sourceMappingURL=workshop.js.map

package/dist/transports/workshop.js.map

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

package/dist/types.d.ts

@@ -4,8 +4,12 @@
  * interface and configuration options for both server and client modes. All module
  * namespaces (brainy, vfs, auth, etc.) hang off of SoulcraftSDK.
  */
-/** Products that can register as OIDC clients of auth.soulcraft.com. */
-export type SoulcraftProduct = 'workshop' | 'venue' | 'academy' | 'portal';
+import type { SoulcraftProduct } from './modules/auth/products.js';
+/**
+ * Products that can register as OIDC clients of auth.soulcraft.com.
+ * Derived from `SOULCRAFT_PRODUCTS` registry — see `modules/auth/products.ts`.
+ */
+export type { SoulcraftProduct };
 /** Brainy instance pooling strategies. */
 export type InstanceStrategy = 'per-user' | 'per-tenant' | 'per-scope';
 /** Transport protocols supported by the client SDK. */

package/dist/types.d.ts.map

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

package/docs/ADR-004-product-registry.md

@@ -0,0 +1,108 @@
+# ADR-004: Centralized Product Registry
+
+**Status:** Accepted
+**Date:** 2026-03-10
+**Location:** `sdk/src/modules/auth/products.ts`
+
+---
+
+## Context
+
+Before this change, adding a new Soulcraft product (e.g. Pulse) required editing
+**five separate hardcoded arrays** in `auth/apps/server/server.ts`:
+
+1. `trustedOrigins` — callback URL allowlist for better-auth
+2. `cors({ origin: [...] })` — Hono CORS origin list
+3. `BACKCHANNEL_CLIENTS` — products that receive OIDC Logout Tokens on sign-out
+4. `trustedClients` — OIDC client registrations (clientId, secret, redirectUrls)
+5. Status page HTML — product badges displayed on the auth home page
+
+Missing any one caused a cryptic 403 on sign-in. Each array had a different shape,
+different ordering, and no compile-time enforcement that they were in sync.
+
+---
+
+## Decision
+
+Create a **single typed registry** (`SOULCRAFT_PRODUCTS`) in the SDK. The auth server
+derives all five arrays from it at startup — no hardcoded product lists in server.ts.
+
+### Registry location
+
+`@soulcraft/sdk/src/modules/auth/products.ts` — exported from `@soulcraft/sdk/server`.
+
+### Why the SDK (not the auth package)?
+
+- The SDK is the cross-project dependency that all products already import.
+- `SoulcraftProduct` was already a type in `sdk/src/types.ts` — the registry
+  simply replaces the manual union with a derived one.
+- The auth server already imports from the SDK for session config and user fields.
+
+### Key design choices
+
+**`as const satisfies Record<string, ProductRegistration>`**
+Preserves literal types (so `keyof typeof SOULCRAFT_PRODUCTS` gives the exact union)
+while enforcing all required fields at the definition site. Adding a partial entry
+fails immediately with a specific error, not a downstream 403.
+
+**`SoulcraftProduct` derived from registry keys**
+Before: `type SoulcraftProduct = 'workshop' | 'venue' | 'academy' | 'portal'`
+After: `type SoulcraftProduct = keyof typeof SOULCRAFT_PRODUCTS`
+Adding a product to the registry extends the type automatically.
+
+**Startup validation**
+Products with `backchannelRequired: true` must have their secret env var set.
+The server throws at startup (not at sign-in) with a clear list of missing vars.
+
+**Optional products**
+Cookie-proxy products (Pulse) have `backchannelRequired: false`. Their secret is
+best-effort — the server starts without it, logs a notice, and the product is
+excluded from backchannel logout. This matches Pulse's current status (analytics
+dashboard; session termination is not critical path).
+
+---
+
+## Adding a new product
+
+1. Add an entry to `SOULCRAFT_PRODUCTS` in `sdk/src/modules/auth/products.ts`.
+   TypeScript will error if any required field is missing.
+
+2. Add the product's secret env var to `.env.production` on `auth-vm`:
+   ```bash
+   MYPRODUCT_OIDC_CLIENT_SECRET=$(openssl rand -hex 32)
+   ```
+
+3. Publish `@soulcraft/sdk` (version bump handled by release script).
+
+4. Deploy the auth server — it reads the new registry and configures all arrays.
+
+5. Set `SOULCRAFT_IDP_URL=https://auth.soulcraft.com` in the product's own
+   `.env.production` to activate OIDC client mode.
+
+---
+
+## Consequences
+
+**Positive:**
+- One place to add a product; TypeScript enforces completeness.
+- Auth server startup fails fast with a clear error if secrets are missing.
+- Status page and CORS list update automatically.
+- No risk of a product being present in origins but missing from OIDC clients (or vice versa).
+
+**Trade-off:**
+- Auth server now depends on `@soulcraft/sdk`. Managed via `file:../../../sdk`
+  in `package.json` (local dev) — bundled into `dist/server.js` at build time,
+  so no runtime dependency on the symlink in production.
+
+---
+
+## Files changed
+
+| File | Change |
+|------|--------|
+| `sdk/src/modules/auth/products.ts` | New — registry + derivation helpers |
+| `sdk/src/types.ts` | `SoulcraftProduct` now re-exported from `products.ts` |
+| `sdk/src/server/index.ts` | Added `SOULCRAFT_PRODUCTS`, `deriveOrigins`, `deriveRedirectUrls` exports |
+| `sdk/src/index.ts` | Added `SoulcraftProduct` export |
+| `auth/apps/server/package.json` | Added `@soulcraft/sdk` dependency |
+| `auth/apps/server/server.ts` | All product arrays derived from registry |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/sdk",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "The unified Soulcraft platform SDK — data, auth, AI, billing, and notifications",
   "type": "module",
   "publishConfig": {