@soulcraft/sdk 2.0.0 → 2.0.2

package/dist/server/from-license.js

@@ -1,349 +0,0 @@
-/**
- * @module server/from-license
- * @description License-driven server SDK factory.
- *
- * `createServerSDK.fromLicense({ product })` is the recommended production entry point
- * for product backends. It replaces the manual environment-variable wiring required by
- * `createSDK()` with a single boot-time call to Portal:
- *
- * ```
- * SOULCRAFT_LICENSE_KEY=SC-XXXX-XXXX-XXXX   ← only secret needed
- * ```
- *
- * At startup the factory:
- * 1. Reads `SOULCRAFT_LICENSE_KEY` from the environment.
- * 2. POSTs `POST https://soulcraft.com/api/license/activate` with the key and product name.
- * 3. Receives a config bundle (`anthropicApiKey`, `portalCreditSecret`, `hallSecret`, etc.).
- * 4. Injects the bundle values into `process.env` so all SDK module factories pick them
- *    up automatically — no factory API changes required.
- * 5. Writes the bundle to `.soulcraft-config.json` in the working directory for offline
- *    restarts (e.g. if Portal is temporarily unreachable after a product restart).
- * 6. Schedules a background re-validation every 4 hours to pick up rotated secrets.
- *
- * The returned `ServerSDK` object is long-lived (one per process). Its `createSDK(brain)`
- * method returns a per-request `SoulcraftSDK`, identical to calling `createSDK({ brain })`
- * directly, but with all secrets already wired from the bundle.
- *
- * ## Backward compatibility
- *
- * `createSDK()` is unchanged — products that manage their own env vars continue to work
- * exactly as before. `fromLicense()` is additive.
- *
- * ## Offline / degraded start
- *
- * If Portal is unreachable on first boot, the factory falls back to a cached bundle from
- * `.soulcraft-config.json`. If no cache exists either, it throws — a product cannot start
- * in production without a resolved config bundle.
- *
- * @example Academy startup
- * ```typescript
- * import { createServerSDK, BrainyInstancePool } from '@soulcraft/sdk/server'
- *
- * const server = await createServerSDK.fromLicense({ product: 'academy' })
- *
- * const pool = new BrainyInstancePool({
- *   storage: 'mmap-filesystem',
- *   dataPath: '/mnt/brainy-data',
- *   strategy: 'per-user',
- * })
- *
- * // Per-request:
- * app.get('/api/brainy', requireAuth, async (c) => {
- *   const brain = await pool.forUser(user.emailHash, 'main')
- *   const sdk = server.createSDK(brain)
- *   const items = await sdk.brainy.find({ query: 'candle inventory' })
- *   return c.json({ items })
- * })
- *
- * // On shutdown:
- * process.on('SIGTERM', () => server.shutdown())
- * ```
- */
-import { readFileSync, writeFileSync, renameSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { createSDK } from './create-sdk.js';
-import { createHallModule } from './hall-handlers.js';
-import { SDK_VERSION } from '../version.js';
-// ─────────────────────────────────────────────────────────────────────────────
-// Constants
-// ─────────────────────────────────────────────────────────────────────────────
-/** Portal license activation endpoint. */
-const ACTIVATE_URL = 'https://soulcraft.com/api/license/activate';
-/** Re-validation interval: 4 hours. */
-const REVALIDATE_INTERVAL_MS = 4 * 60 * 60 * 1000;
-/**
- * Returns the path to the cached config bundle.
- *
- * Resolved lazily at call-time so the path is always relative to the working
- * directory at the time of the call, not at module load time.
- */
-function getCachePath() {
-    return resolve(process.cwd(), '.soulcraft-config.json');
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Internal helpers
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Call the Portal `licenseActivate` endpoint and return the full response.
- *
- * @throws {Error} If the network call fails or Portal returns a non-200 status.
- */
-async function _activate(key, product) {
-    const response = await fetch(ACTIVATE_URL, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ key, product, sdkVersion: SDK_VERSION }),
-        signal: AbortSignal.timeout(15_000),
-    });
-    if (response.status === 403) {
-        const body = (await response.json().catch(() => ({})));
-        throw new Error(`License key rejected by Portal: ${body.reason ?? 'key_not_found'}. ` +
-            `Check SOULCRAFT_LICENSE_KEY is correct and the license has not expired.`);
-    }
-    if (!response.ok) {
-        throw new Error(`Portal license activation failed (HTTP ${response.status}). ` +
-            `The service may be temporarily unavailable.`);
-    }
-    return response.json();
-}
-/**
- * Read the cached bundle from `.soulcraft-config.json`.
- * Returns `undefined` if the file does not exist or cannot be parsed.
- */
-function _readCache() {
-    try {
-        const raw = readFileSync(getCachePath(), 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Write the activation response to `.soulcraft-config.json`.
- * Failures are non-fatal — if the disk is read-only, the cache is simply not written.
- */
-function _writeCache(product, response) {
-    try {
-        const bundle = {
-            activatedAt: new Date().toISOString(),
-            product,
-            response,
-        };
-        writeFileSync(getCachePath(), JSON.stringify(bundle, null, 2), 'utf8');
-    }
-    catch {
-        // Non-fatal — read-only FS or permission error.
-    }
-}
-/**
- * Inject config bundle values into `process.env`.
- *
- * Only sets variables that are present in the bundle and not already set by the host
- * environment. Host-set values take precedence, allowing per-deployment overrides.
- */
-function _injectEnv(config) {
-    const mappings = [
-        ['anthropicApiKey', 'ANTHROPIC_API_KEY'],
-        ['portalCreditSecret', 'PORTAL_CREDIT_SECRET'],
-        ['hallUrl', 'HALL_URL'],
-        ['stripeSecretKey', 'STRIPE_SECRET_KEY'],
-        ['stripeWebhookSecret', 'STRIPE_WEBHOOK_SECRET'],
-        ['workshopDeploySecret', 'WORKSHOP_DEPLOY_SECRET'],
-        ['academyPublishSecret', 'ACADEMY_PUBLISH_SECRET'],
-        ['venueRpcSecret', 'VENUE_RPC_SECRET'],
-        ['postmarkToken', 'POSTMARK_SERVER_TOKEN'],
-        ['postmarkFromEmail', 'POSTMARK_FROM_EMAIL'],
-        ['twilioSid', 'TWILIO_ACCOUNT_SID'],
-        ['twilioToken', 'TWILIO_AUTH_TOKEN'],
-        ['twilioFromNumber', 'TWILIO_FROM_NUMBER'],
-    ];
-    for (const [configKey, envKey] of mappings) {
-        const value = config[configKey];
-        if (value && !process.env[envKey]) {
-            process.env[envKey] = value;
-        }
-    }
-}
-/**
- * Write a Cortex license key to `.soulcraft.json` in the working directory.
- *
- * Uses an atomic tmp-then-rename write so a concurrent Cortex process never
- * reads a partial file. Must be called BEFORE `createSDK(brain)` — Cortex
- * reads `.soulcraft.json` during Brainy plugin initialization.
- *
- * Failures are non-fatal: if the filesystem is read-only or permissions are
- * missing, Cortex falls back to its own activation code exchange.
- *
- * @param cortexLicenseKey - The Cortex Ed25519 JWT (`sc_cortex_...`) to persist.
- */
-function _writeSoulcraftJson(cortexLicenseKey) {
-    try {
-        const targetPath = resolve(process.cwd(), '.soulcraft.json');
-        const tmpPath = targetPath + '.tmp';
-        writeFileSync(tmpPath, JSON.stringify({ cortex: cortexLicenseKey }, null, 2) + '\n', 'utf8');
-        renameSync(tmpPath, targetPath);
-    }
-    catch {
-        // Non-fatal — Cortex exchanges its own activation code independently.
-    }
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// fromLicense factory
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Activate the SDK from a Soulcraft license key.
- *
- * Calls Portal's `licenseActivate` endpoint, injects the returned config bundle
- * into `process.env`, and returns a `ServerSDK` ready for per-request use.
- *
- * Falls back to a cached bundle (`.soulcraft-config.json`) if Portal is unreachable.
- * Throws if neither Portal nor a valid cache is available.
- *
- * @param options - Product name and optional license key override.
- * @returns A `ServerSDK` instance, fully wired from the license bundle.
- *
- * @throws {Error} If the license key is invalid, expired, or Portal is unreachable with no cache.
- *
- * @example
- * ```typescript
- * const server = await createServerSDK.fromLicense({ product: 'academy' })
- * const pool = new BrainyInstancePool({ storage: 'mmap-filesystem', dataPath: '/mnt/brainy-data', strategy: 'per-user' })
- *
- * app.use(requireAuth)
- * app.get('/api/brainy', async (c) => {
- *   const brain = await pool.forUser(c.get('user').emailHash, 'main')
- *   const sdk = server.createSDK(brain)
- *   return c.json(await sdk.brainy.find({ query: c.req.query('q') ?? '' }))
- * })
- *
- * process.on('SIGTERM', () => server.shutdown())
- * ```
- */
-async function fromLicense(options) {
-    const { product } = options;
-    const key = options.licenseKey ?? process.env['SOULCRAFT_LICENSE_KEY'];
-    if (!key) {
-        throw new Error('SOULCRAFT_LICENSE_KEY is not set. ' +
-            'Set this environment variable to your Soulcraft license key, ' +
-            'or pass licenseKey explicitly to fromLicense().');
-    }
-    // ── Activate ──────────────────────────────────────────────────────────────
-    let activateResponse;
-    try {
-        activateResponse = await _activate(key, product);
-        _writeCache(product, activateResponse);
-    }
-    catch (err) {
-        // Portal unreachable — try the cached bundle.
-        const cached = _readCache();
-        if (cached?.product === product && cached.response.valid) {
-            console.warn(`[SDK] Portal unreachable (${err instanceof Error ? err.message : String(err)}). ` +
-                `Using cached config from ${cached.activatedAt}.`);
-            activateResponse = cached.response;
-        }
-        else {
-            throw new Error(`Failed to activate SDK license and no valid cache found. ` +
-                `Original error: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    if (!activateResponse.valid) {
-        throw new Error(`License key is not valid: ${activateResponse.reason ?? 'unknown reason'}. ` +
-            `Check that your license has not expired.`);
-    }
-    const config = activateResponse.config;
-    const tier = activateResponse.tier ?? 'free';
-    let venueOrgConfig = activateResponse.venueOrgConfig ?? {};
-    // ── Inject env ────────────────────────────────────────────────────────────
-    _injectEnv(config);
-    // ── Write Cortex license to .soulcraft.json ───────────────────────────────
-    // Must run before createSDK(brain) — Cortex reads .soulcraft.json at Brainy
-    // plugin initialization time, not at first use.
-    if (config.cortexLicenseKey) {
-        _writeSoulcraftJson(config.cortexLicenseKey);
-    }
-    // ── Wire Hall ─────────────────────────────────────────────────────────────
-    let hall;
-    if (config.hallSecret && config.hallUrl) {
-        hall = createHallModule({
-            url: config.hallUrl,
-            productName: product,
-            secret: config.hallSecret,
-        });
-        await hall.connect();
-    }
-    // ── Background re-validation ──────────────────────────────────────────────
-    let _revalidateTimer;
-    async function _revalidate() {
-        try {
-            const fresh = await _activate(key, product);
-            _writeCache(product, fresh);
-            _injectEnv(fresh.config);
-            if (fresh.config.cortexLicenseKey) {
-                _writeSoulcraftJson(fresh.config.cortexLicenseKey);
-            }
-            venueOrgConfig = fresh.venueOrgConfig ?? {};
-        }
-        catch {
-            // Non-fatal — the in-memory injected values remain valid until next attempt.
-        }
-    }
-    _revalidateTimer = setInterval(() => { void _revalidate(); }, REVALIDATE_INTERVAL_MS);
-    if (_revalidateTimer.unref)
-        _revalidateTimer.unref();
-    // ── Return ServerSDK ──────────────────────────────────────────────────────
-    return {
-        createSDK(brain) {
-            return createSDK({ brain });
-        },
-        get hall() {
-            return hall;
-        },
-        get config() {
-            return config;
-        },
-        get tier() {
-            return tier;
-        },
-        get venueOrgConfig() {
-            return venueOrgConfig;
-        },
-        shutdown() {
-            if (_revalidateTimer) {
-                clearInterval(_revalidateTimer);
-                _revalidateTimer = undefined;
-            }
-            if (hall) {
-                void hall.close();
-            }
-        },
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// createServerSDK namespace
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Server SDK factory namespace.
- *
- * The primary entry point is `createServerSDK.fromLicense({ product })`.
- * For lower-level control (custom Brainy instance, no license key), use
- * `createSDK({ brain })` directly.
- *
- * @example
- * ```typescript
- * import { createServerSDK, BrainyInstancePool } from '@soulcraft/sdk/server'
- *
- * const server = await createServerSDK.fromLicense({ product: 'workshop' })
- * const pool = new BrainyInstancePool({ storage: 'mmap-filesystem', dataPath: '/mnt/data', strategy: 'per-user' })
- *
- * app.get('/api/brainy', requireAuth, async (c) => {
- *   const brain = await pool.forUser(c.get('user').emailHash, 'main')
- *   const sdk = server.createSDK(brain)
- *   return c.json(await sdk.brainy.find({ query: c.req.query('q') ?? '' }))
- * })
- * ```
- */
-export const createServerSDK = {
-    fromLicense,
-};
-//# sourceMappingURL=from-license.js.map

package/dist/server/from-license.js.map

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

package/dist/server/handlers.d.ts

@@ -1,312 +0,0 @@
-/**
- * @module server/handlers
- * @description HTTP RPC and WebSocket handler factories for mounting Brainy server endpoints.
- *
- * Products mount exactly two routes:
- * - `POST /api/brainy/rpc` — handled by {@link createBrainyHandler}
- * - `GET /api/brainy/ws` — WebSocket upgrade handled by {@link createBrainyWsHandler}
- *
- * Both factories are framework-agnostic — they accept and return `Request` / `Response`
- * objects (Fetch API), making them compatible with SvelteKit, Hono, and raw Bun.serve.
- *
- * ## HTTP RPC handler
- *
- * Accepts `{ method: string, args: unknown[] }` as a JSON body and returns
- * `{ result: unknown }` or `{ error: { code, message } }`. All authentication and
- * authorization is delegated to the caller-supplied callbacks.
- *
- * ## WebSocket handler
- *
- * Accepts binary MessagePack frames. See wire protocol in `transports/ws.ts`.
- * The `broadcastChange()` method on the returned handler pushes `BrainyChangeEvent`
- * objects to connected clients.
- *
- * @example SvelteKit route mounting the HTTP handler
- * ```typescript
- * // src/routes/api/brainy/rpc/+server.ts
- * import { createBrainyHandler } from '@soulcraft/sdk/server'
- * import { pool } from '$lib/server/sdk'
- * import { verifySession } from '$lib/server/auth'
- *
- * const handler = createBrainyHandler({
- *   resolveBrain: async (req) => {
- *     const userId = req.headers.get('x-user-id') ?? ''
- *     const workspaceId = req.headers.get('x-workspace-id') ?? ''
- *     return pool.forUser(userId, workspaceId)
- *   },
- *   authenticate: async (req) => verifySession(req.headers.get('cookie') ?? ''),
- * })
- *
- * export const POST: RequestHandler = ({ request }) => handler(request)
- * ```
- *
- * @example Bun.serve WebSocket upgrade
- * ```typescript
- * import { createBrainyWsHandler } from '@soulcraft/sdk/server'
- * import { pool } from './sdk'
- * import { verifyCapabilityToken } from '@soulcraft/sdk'
- *
- * const wsHandler = createBrainyWsHandler({
- *   resolveBrain: (scope) => pool.forTenant(scope),
- *   authenticate: (token, scope) => verifyCapabilityToken(token, process.env.VENUE_RPC_SECRET!),
- * })
- *
- * Bun.serve({
- *   async fetch(req, server) {
- *     if (req.url.endsWith('/api/brainy/ws')) {
- *       const session = await wsHandler.handleUpgrade(req)
- *       if (!session) return new Response('Unauthorized', { status: 401 })
- *       server.upgrade(req, { data: session })
- *       return undefined
- *     }
- *     return new Response('Not found', { status: 404 })
- *   },
- *   websocket: {
- *     async message(ws, data) {
- *       await wsHandler.handleMessage(ws.data, data as ArrayBuffer, (msg) => ws.send(msg))
- *     },
- *   },
- * })
- * ```
- */
-import type { Brainy } from '@soulcraft/brainy';
-import { LocalTransport } from '../transports/local.js';
-import type { BrainyChangeEvent } from '../modules/brainy/events.js';
-import { YDocManager } from '../modules/brainy/ydoc-manager.js';
-/**
- * Configuration for {@link createBrainyHandler}.
- */
-export interface BrainyHandlerConfig {
-    /**
-     * Resolves the Brainy instance to dispatch this request against.
-     *
-     * Called on every request. Use request headers (org slug, workspace ID, etc.)
-     * to select the correct instance from the pool.
-     *
-     * @param request - The incoming HTTP Request.
-     * @returns The Brainy instance for this request's scope.
-     */
-    resolveBrain: (request: Request) => Promise<Brainy>;
-    /**
-     * Authenticates the incoming request.
-     *
-     * Return any truthy value (claims, session object, etc.) on success.
-     * Return `null` or `undefined` to reject the request with HTTP 401.
-     *
-     * @param request - The incoming HTTP Request.
-     * @returns An auth context on success, or `null` to reject.
-     */
-    authenticate: (request: Request) => Promise<unknown | null>;
-    /**
-     * Optional per-call authorization check.
-     *
-     * Called after `authenticate()` succeeds. Return `false` or `null` to
-     * reject with HTTP 403.
-     *
-     * @param method - Dot-separated Brainy method name.
-     * @param args - Positional arguments from the request body.
-     * @param auth - The auth context returned by `authenticate()`.
-     * @returns `true` to allow, `false` / `null` to deny.
-     */
-    authorize?: (method: string, args: unknown[], auth: unknown) => boolean | null | Promise<boolean | null>;
-    /**
-     * Methods that are blocked for all callers regardless of auth.
-     *
-     * @default []
-     */
-    blockedMethods?: string[];
-}
-/**
- * Creates a Fetch-API-compatible HTTP handler for Brainy RPC calls.
- *
- * Mount at `POST /api/brainy/rpc` in your product's router.
- *
- * @param config - Handler configuration.
- * @returns `(request: Request) => Promise<Response>`
- */
-export declare function createBrainyHandler(config: BrainyHandlerConfig): (request: Request) => Promise<Response>;
-/**
- * Configuration for {@link createBrainyWsHandler}.
- */
-export interface BrainyWsHandlerConfig {
-    /**
-     * Resolves the Brainy instance for the given scope (e.g. tenant slug).
-     *
-     * @param scope - The `?scope=` query param from the WebSocket URL.
-     * @returns The Brainy instance for this scope.
-     */
-    resolveBrain: (scope: string) => Promise<Brainy>;
-    /**
-     * Authenticates the WebSocket upgrade request.
-     *
-     * The `token` is extracted from `Authorization: Bearer <token>` (Bun/Node) or
-     * `?token=` query param (browser). Return `null` to reject with close code 4001.
-     *
-     * @param token - The bearer token from the header or query string.
-     * @param scope - The requested scope from the URL.
-     * @returns An auth context on success, or `null` to reject.
-     */
-    authenticate: (token: string, scope: string) => Promise<unknown | null>;
-    /**
-     * Optional per-call authorization check for Brainy RPC methods.
-     *
-     * @param method - Dot-separated Brainy method name.
-     * @param args - Positional arguments.
-     * @param auth - The auth context from `authenticate()`.
-     * @returns `true` to allow, `false` / `null` to deny.
-     */
-    authorize?: (method: string, args: unknown[], auth: unknown) => boolean | null | Promise<boolean | null>;
-    /** Methods blocked for all callers. @default [] */
-    blockedMethods?: string[];
-    /**
-     * Optional Y.js document manager for real-time collaborative editing.
-     *
-     * When provided, the handler routes `y-sync`, `y-update`, and `y-awareness`
-     * messages through the `YDocManager` instead of the Brainy RPC dispatcher.
-     * Y.js update broadcasts are sent to all other peers via the `broadcast` callback
-     * on the session — the product server must populate this callback when a peer
-     * connects (see {@link WsSession.broadcast}).
-     */
-    ydocManager?: YDocManager;
-}
-/** Per-connection session state stored on the WebSocket data field. */
-export interface WsSession {
-    /** The tenant scope extracted from `?scope=`. */
-    scope: string;
-    /** The auth context returned by `authenticate()`. */
-    auth: unknown;
-    /** The resolved Brainy instance for this scope. */
-    brain: Brainy;
-    /** Local transport wrapping the Brainy instance for this session. */
-    transport: LocalTransport;
-    /**
-     * Unique peer ID for this connection. Used by `YDocManager` to track per-file
-     * peer counts so it knows when the last peer has disconnected.
-     */
-    peerId: string;
-    /**
-     * Broadcast callback set by the product server after upgrade.
-     *
-     * Called by the handler to fan out `y-update` and `y-awareness` messages to all
-     * other peers connected to this scope. The product server owns the connection map
-     * (keyed by scope) and provides this callback so the SDK doesn't need to manage
-     * WebSocket handles directly.
-     *
-     * @param msg - Encoded MessagePack frame to send to all OTHER peers in this scope.
-     * @param excludePeerId - The peer that sent the message — must be excluded from broadcast.
-     */
-    broadcast: (msg: Uint8Array, excludePeerId: string) => void;
-}
-/**
- * The object returned by {@link createBrainyWsHandler}.
- */
-export interface BrainyWsHandler {
-    /**
-     * Handles a WebSocket upgrade request.
-     *
-     * Extracts the token and scope from the request, authenticates, and resolves
-     * the Brainy instance. Returns `null` if authentication fails (caller should
-     * respond with 401 and not proceed with the upgrade).
-     *
-     * After a successful upgrade the product server must set `session.broadcast` to
-     * a function that sends a `Uint8Array` to all other peers in the same scope.
-     *
-     * @param request - The HTTP upgrade Request.
-     * @returns Session state on success, or `null` on auth failure.
-     */
-    handleUpgrade(request: Request): Promise<WsSession | null>;
-    /**
-     * Processes an incoming WebSocket message.
-     *
-     * Decodes the MessagePack frame and routes it to either:
-     * - The Brainy RPC dispatcher (frames with an `id` field), or
-     * - The `YDocManager` (frames with `type: 'y-sync' | 'y-update' | 'y-awareness'`).
-     *
-     * Y.js update and awareness frames are also broadcast to other peers via
-     * `session.broadcast`.
-     *
-     * @param session - The session state from `handleUpgrade()`.
-     * @param data - Raw binary message frame.
-     * @param send - Callback to send a binary response to THIS client only.
-     */
-    handleMessage(session: WsSession, data: ArrayBuffer | Uint8Array, send: (msg: Uint8Array) => void): Promise<void>;
-    /**
-     * Called when a peer's WebSocket connection closes.
-     *
-     * Notifies the `YDocManager` so it can flush and discard Y.Docs that no longer
-     * have any active peers.
-     *
-     * @param session - The session state of the disconnecting peer.
-     */
-    handleClose(session: WsSession): Promise<void>;
-    /**
-     * Broadcasts a Brainy change event to a connected client.
-     *
-     * @param event - The change event to broadcast.
-     * @param send - Callback to send the encoded event to the target client.
-     */
-    broadcastChange(event: BrainyChangeEvent, send: (msg: Uint8Array) => void): void;
-}
-/**
- * Creates a server-side WebSocket handler for bidirectional Brainy RPC, real-time
- * change push, and optional Y.js collaborative document editing.
- *
- * ## Y.js collaborative editing
- *
- * Pass a `ydocManager` in the config to enable co-editing. The handler will
- * automatically route `y-sync`, `y-update`, and `y-awareness` messages through the
- * manager. The product server must:
- *
- * 1. Maintain a `Map<scope, Map<peerId, sendFn>>` of connected peers.
- * 2. Set `session.broadcast` after `handleUpgrade()` to fan out Y.js frames.
- * 3. Call `handleClose(session)` when a peer disconnects.
- *
- * @example Workshop server wiring with Y.js
- * ```typescript
- * import { createBrainyWsHandler, YDocManager } from '@soulcraft/sdk/server'
- *
- * const ydocManager = new YDocManager()
- * const wsHandler = createBrainyWsHandler({ resolveBrain, authenticate, ydocManager })
- *
- * // Map<scope, Map<peerId, send>>
- * const peers = new Map<string, Map<string, (msg: Uint8Array) => void>>()
- *
- * Bun.serve({
- *   async fetch(req, server) {
- *     if (new URL(req.url).pathname === '/api/brainy/ws') {
- *       const session = await wsHandler.handleUpgrade(req)
- *       if (!session) return new Response('Unauthorized', { status: 401 })
- *       // Register peer in broadcast map
- *       if (!peers.has(session.scope)) peers.set(session.scope, new Map())
- *       server.upgrade(req, { data: session })
- *       return undefined
- *     }
- *   },
- *   websocket: {
- *     open(ws) {
- *       const session = ws.data as WsSession
- *       peers.get(session.scope)!.set(session.peerId, (msg) => ws.send(msg))
- *       session.broadcast = (msg, excludeId) => {
- *         for (const [id, send] of peers.get(session.scope) ?? []) {
- *           if (id !== excludeId) send(msg)
- *         }
- *       }
- *       ws.send(encode({ type: 'ready', scope: session.scope }))
- *     },
- *     async message(ws, data) {
- *       await wsHandler.handleMessage(ws.data, data as ArrayBuffer, (msg) => ws.send(msg))
- *     },
- *     async close(ws) {
- *       const session = ws.data as WsSession
- *       peers.get(session.scope)?.delete(session.peerId)
- *       await wsHandler.handleClose(session)
- *     },
- *   },
- * })
- * ```
- *
- * @param config - Handler configuration.
- * @returns A {@link BrainyWsHandler} instance.
- */
-export declare function createBrainyWsHandler(config: BrainyWsHandlerConfig): BrainyWsHandler;
-//# sourceMappingURL=handlers.d.ts.map

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

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