@soulcraft/sdk 2.6.1 → 3.0.0

package/dist/server/hono-router.d.ts

@@ -1,70 +0,0 @@
-/**
- * @module server/hono-router
- * @description Hono integration factory for the Soulcraft SDK namespace router.
- *
- * Creates a Hono app with the unified RPC endpoint:
- *
- * - `POST /api/rpc` — Unified namespace RPC endpoint. Accepts the
- *   {@link SoulcraftRPC} envelope and dispatches via the namespace router.
- *   Streaming responses are delivered as SSE (`text/event-stream`).
- *
- * Products mount this router in their Hono app with `app.route('', sdkRouter)`.
- *
- * @example Workshop server-hono.ts
- * ```typescript
- * import { createSoulcraftRouter } from '@soulcraft/sdk/server'
- *
- * const sdkRouter = createSoulcraftRouter({
- *   resolveBrain: async (ctx) => getUserBrainy(ctx.user!.emailHash, ctx.workspaceId),
- *   authenticate: async (ctx) => verifySession(ctx.request),
- *   providers: {
- *     chat: chatHandler,
- *     graph: graphHandler,
- *     search: searchHandler,
- *   },
- * })
- *
- * app.route('', sdkRouter)
- * ```
- */
-import { Hono } from 'hono';
-import type { NamespaceRouterConfig } from './namespace-router.js';
-import type { RpcCacheConfig } from './rpc-cache.js';
-/**
- * Configuration for {@link createSoulcraftRouter}.
- *
- * Extends {@link NamespaceRouterConfig} with optional RPC response caching.
- */
-export interface SoulcraftRouterConfig extends NamespaceRouterConfig {
-    /**
-     * Optional RPC response cache configuration.
-     *
-     * When provided, cacheable read methods are served from an in-process LRU cache
-     * with singleflight deduplication. Write methods flush the scope automatically.
-     *
-     * @see {@link RpcCacheConfig}
-     */
-    cache?: RpcCacheConfig;
-}
-/**
- * Creates a Hono app with the unified Soulcraft RPC routes.
- *
- * The returned Hono app should be mounted at the root of your product server
- * (not under a prefix) since it defines its own `/api/rpc` path.
- *
- * @param config - Namespace router configuration.
- * @returns A Hono app ready to be mounted with `app.route('', sdkRouter)`.
- *
- * @example
- * ```typescript
- * const sdkRouter = createSoulcraftRouter({
- *   resolveBrain: async (ctx) => pool.forUser(ctx.user!.emailHash, ctx.workspaceId),
- *   authenticate: async (ctx) => verifySession(ctx.request),
- *   providers: { chat: chatHandler },
- * })
- *
- * app.route('', sdkRouter)
- * ```
- */
-export declare function createSoulcraftRouter(config: SoulcraftRouterConfig): Hono;
-//# sourceMappingURL=hono-router.d.ts.map

package/dist/server/hono-router.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hono-router.d.ts","sourceRoot":"","sources":["../../src/server/hono-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG3B,OAAO,KAAK,EAAE,qBAAqB,EAAkB,MAAM,uBAAuB,CAAA;AAClF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAGpD;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,qBAAqB;IAClE;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,cAAc,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAyCzE"}

package/dist/server/hono-router.js

@@ -1,167 +0,0 @@
-/**
- * @module server/hono-router
- * @description Hono integration factory for the Soulcraft SDK namespace router.
- *
- * Creates a Hono app with the unified RPC endpoint:
- *
- * - `POST /api/rpc` — Unified namespace RPC endpoint. Accepts the
- *   {@link SoulcraftRPC} envelope and dispatches via the namespace router.
- *   Streaming responses are delivered as SSE (`text/event-stream`).
- *
- * Products mount this router in their Hono app with `app.route('', sdkRouter)`.
- *
- * @example Workshop server-hono.ts
- * ```typescript
- * import { createSoulcraftRouter } from '@soulcraft/sdk/server'
- *
- * const sdkRouter = createSoulcraftRouter({
- *   resolveBrain: async (ctx) => getUserBrainy(ctx.user!.emailHash, ctx.workspaceId),
- *   authenticate: async (ctx) => verifySession(ctx.request),
- *   providers: {
- *     chat: chatHandler,
- *     graph: graphHandler,
- *     search: searchHandler,
- *   },
- * })
- *
- * app.route('', sdkRouter)
- * ```
- */
-import { Hono } from 'hono';
-import { createNamespaceRouter } from './namespace-router.js';
-import { createCachedDispatch } from './rpc-cache.js';
-/**
- * Creates a Hono app with the unified Soulcraft RPC routes.
- *
- * The returned Hono app should be mounted at the root of your product server
- * (not under a prefix) since it defines its own `/api/rpc` path.
- *
- * @param config - Namespace router configuration.
- * @returns A Hono app ready to be mounted with `app.route('', sdkRouter)`.
- *
- * @example
- * ```typescript
- * const sdkRouter = createSoulcraftRouter({
- *   resolveBrain: async (ctx) => pool.forUser(ctx.user!.emailHash, ctx.workspaceId),
- *   authenticate: async (ctx) => verifySession(ctx.request),
- *   providers: { chat: chatHandler },
- * })
- *
- * app.route('', sdkRouter)
- * ```
- */
-export function createSoulcraftRouter(config) {
-    const baseRouter = createNamespaceRouter(config);
-    const router = config.cache
-        ? createCachedDispatch(baseRouter, config.cache)
-        : baseRouter;
-    const app = new Hono();
-    // ── POST /api/rpc — Unified namespace RPC ────────────────────────────────
-    app.post('/api/rpc', async (c) => {
-        let body;
-        try {
-            body = await c.req.json();
-        }
-        catch {
-            return c.json({ error: { code: 'BAD_REQUEST', message: 'Request body must be valid JSON' } }, 400);
-        }
-        // Validate required fields.
-        if (typeof body.ns !== 'string' || typeof body.method !== 'string' || !Array.isArray(body.args)) {
-            return c.json({ error: { code: 'BAD_REQUEST', message: '{ ns: string, method: string, args: unknown[] } required' } }, 400);
-        }
-        const rpc = {
-            id: typeof body.id === 'string' ? body.id : crypto.randomUUID(),
-            ns: body.ns,
-            method: body.method,
-            args: body.args,
-            stream: body.stream ?? false,
-        };
-        const result = await router.dispatch(rpc, c.req.raw);
-        return _sendResult(c, result);
-    });
-    return app;
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Response helpers
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Converts a {@link DispatchResult} into a Hono Response.
- *
- * For `response` results, returns JSON.
- * For `stream` results, returns an SSE stream.
- *
- * @param c - Hono context.
- * @param result - The dispatch result from the namespace router.
- * @returns A Response.
- */
-function _sendResult(c, result) {
-    if (result.type === 'response') {
-        const { response } = result;
-        const status = response.error ? _errorStatusCode(response.error.code) : 200;
-        const headers = { 'Content-Type': 'application/json' };
-        // Merge cache headers (Cache-Control, ETag, X-Cache) when present.
-        if (result.headers) {
-            for (const [key, value] of Object.entries(result.headers)) {
-                headers[key] = value;
-            }
-        }
-        return new Response(JSON.stringify(response), { status, headers });
-    }
-    // Streaming result — deliver as SSE.
-    const { id, iterable } = result;
-    const stream = new ReadableStream({
-        async start(controller) {
-            const encoder = new TextEncoder();
-            try {
-                for await (const chunk of iterable) {
-                    const frame = { id, chunk };
-                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(frame)}\n\n`));
-                }
-                // Send done signal.
-                const doneFrame = { id, done: true };
-                controller.enqueue(encoder.encode(`data: ${JSON.stringify(doneFrame)}\n\n`));
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                const errorFrame = { id, error: message };
-                controller.enqueue(encoder.encode(`data: ${JSON.stringify(errorFrame)}\n\n`));
-            }
-            finally {
-                controller.close();
-            }
-        },
-    });
-    return new Response(stream, {
-        status: 200,
-        headers: {
-            'Content-Type': 'text/event-stream',
-            'Cache-Control': 'no-cache',
-            'Connection': 'keep-alive',
-        },
-    });
-}
-/**
- * Maps error codes to HTTP status codes for JSON responses.
- *
- * @param code - The error code from the RPC response.
- * @returns The appropriate HTTP status code.
- */
-function _errorStatusCode(code) {
-    switch (code) {
-        case 'UNAUTHORIZED':
-        case 'AUTH_ERROR':
-            return 401;
-        case 'FORBIDDEN':
-            return 403;
-        case 'NAMESPACE_NOT_FOUND':
-        case 'METHOD_NOT_FOUND':
-            return 404;
-        case 'BRAIN_UNAVAILABLE':
-            return 503;
-        case 'BAD_REQUEST':
-            return 400;
-        default:
-            return 500;
-    }
-}
-//# sourceMappingURL=hono-router.js.map

package/dist/server/hono-router.js.map

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