@soulcraft/sdk 2.0.0 → 2.0.2

package/dist/server/create-sdk.js

@@ -1,104 +0,0 @@
-/**
- * @module server/create-sdk
- * @description `createSDK` factory for server-mode @soulcraft/sdk.
- *
- * Assembles a complete `SoulcraftSDK` instance from a live Brainy instance.
- * In server mode the SDK uses the {@link LocalTransport} — zero overhead, no
- * serialization, in-process method dispatch directly into the Brainy instance.
- *
- * The returned SDK object is scoped to a single Brainy instance. In a typical
- * server request handler the caller resolves the correct Brainy instance from a
- * {@link BrainyInstancePool} and then calls `createSDK({ brain })`. A new SDK
- * object per request is cheap — it's a thin wrapper, not a connection.
- *
- * @example Workshop request handler
- * ```typescript
- * import { BrainyInstancePool, createSDK } from '@soulcraft/sdk/server'
- *
- * const pool = new BrainyInstancePool({ storage: 'filesystem', dataPath: './data', strategy: 'per-user' })
- *
- * app.get('/api/inventory', requireAuth, async (c) => {
- *   const user = c.get('user')!
- *   const brain = await pool.forUser(user.emailHash, 'main')
- *   const sdk = createSDK({ brain })
- *
- *   const items = await sdk.brainy.find({ query: 'inventory items', type: 'Product' })
- *   const readme = await sdk.vfs.readFile('/projects/my-project/README.md')
- *   return c.json({ items })
- * })
- * ```
- */
-import { LocalTransport } from '../transports/local.js';
-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
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Create a server-mode `SoulcraftSDK` wrapping a live Brainy instance.
- *
- * All `sdk.brainy.*` and `sdk.vfs.*` calls are dispatched in-process with zero
- * serialization overhead via {@link LocalTransport}.
- *
- * `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 via Portal credits (prod via `PORTAL_CREDIT_SECRET`).
- * `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.
- *
- * @example
- * ```typescript
- * const brain = await pool.forUser(user.emailHash, workspaceId)
- * const sdk = createSDK({ brain })
- *
- * const results = await sdk.brainy.find({ query: 'candle inventory' })
- * const readme = await sdk.vfs.readFile('/projects/README.md')
- * await sdk.events.emit('kit:session-completed', { userId, sessionId, kitId })
- * ```
- */
-export function createSDK(options) {
-    const { brain } = options;
-    const transport = new LocalTransport(brain);
-    const brainyProxy = createBrainyProxy(transport);
-    const events = createEventsModule();
-    const ai = createAiModule();
-    const skills = createSkillsModule(brain);
-    const billing = createBillingModule();
-    const license = createLicenseModule({ billing });
-    const kits = createKitsModule();
-    const notifications = createNotificationsModule();
-    // This legacy factory wires only the Tier 1 modules (brainy, ai, billing, etc.).
-    // For full namespace support, use createSoulcraftRouter() which dispatches all
-    // 25 namespaces via the unified RPC endpoint.
-    return {
-        brainy: brainyProxy,
-        events,
-        ai,
-        skills,
-        license,
-        kits,
-        billing,
-        notifications,
-        async shutdown() {
-            billing.stopFlush();
-            await billing.flush();
-            license.stopHeartbeat();
-            // brain.close() flushes all deferred writes (HNSW dirty nodes, indexes,
-            // storage counts) and frees all resources — the correct full-shutdown path.
-            await brain.close();
-        },
-    };
-}
-//# sourceMappingURL=create-sdk.js.map

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

@@ -1 +0,0 @@
-{"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,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,iFAAiF;IACjF,+EAA+E;IAC/E,8CAA8C;IAC9C,OAAO;QACL,MAAM,EAAE,WAAW;QACnB,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,wEAAwE;YACxE,4EAA4E;YAC5E,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;KACyB,CAAA;AAC9B,CAAC"}

package/dist/server/from-license.d.ts

@@ -1,252 +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 type { Brainy } from '@soulcraft/brainy';
-import type { HallModule } from '../modules/hall/types.js';
-import type { SoulcraftSDK, SoulcraftProduct } from '../types.js';
-/**
- * Per-org billing configuration for Venue, distributed via the Portal activate response.
- *
- * Stored in Portal's Firestore license document under `venueOrgConfig[orgSlug]` and
- * returned at boot time so Venue cannot self-modify its own platform fee rate.
- *
- * @example
- * ```typescript
- * const cfg = server.venueOrgConfig['canvas-and-corks']
- * // { platformFeeRate: 0.065, feeMode: 'online-only', billingModel: 'per-transaction' }
- * ```
- */
-export interface VenueOrgBillingConfig {
-    /** Platform fee rate as a decimal (e.g. `0.065` for 6.5%). */
-    platformFeeRate?: number;
-    /** Which channels the fee applies to. */
-    feeMode?: 'online-only' | 'all-channels' | 'none';
-    /** Billing model for this org. */
-    billingModel?: 'per-transaction' | 'subscription' | 'hybrid';
-}
-/**
- * Config bundle returned by the Portal `licenseActivate` endpoint.
- * Only non-null fields are included in the response.
- */
-export interface LicenseConfigBundle {
-    /** Anthropic API key for `sdk.ai.*` calls. */
-    anthropicApiKey?: string;
-    /** Shared secret for the Portal credit API (`sdk.billing.*`). */
-    portalCreditSecret?: string;
-    /** WebSocket URL of the Hall server (e.g. `wss://hall.soulcraft.com`). */
-    hallUrl?: string;
-    /** Per-product shared secret for Hall authentication. */
-    hallSecret?: string;
-    /** Stripe secret key for `sdk.billing.*` Stripe operations. */
-    stripeSecretKey?: string;
-    /** Stripe webhook signing secret. */
-    stripeWebhookSecret?: string;
-    /** Workshop deploy bearer token secret. */
-    workshopDeploySecret?: string;
-    /** Academy publish bearer token secret. */
-    academyPublishSecret?: string;
-    /** Venue RPC capability token secret. */
-    venueRpcSecret?: string;
-    /** Postmark server token for email notifications. */
-    postmarkToken?: string;
-    /** From-address for Postmark email. */
-    postmarkFromEmail?: string;
-    /** Twilio account SID for SMS notifications. */
-    twilioSid?: string;
-    /** Twilio auth token for SMS notifications. */
-    twilioToken?: string;
-    /** Twilio from-number for SMS. */
-    twilioFromNumber?: string;
-    /**
-     * Internal Cortex Ed25519 JWT license key for this product.
-     * Written to `.soulcraft.json` before Brainy/Cortex initializes so that
-     * Cortex validates offline without a separate activation step.
-     */
-    cortexLicenseKey?: string;
-}
-/**
- * Options for `createServerSDK.fromLicense()`.
- */
-export interface FromLicenseOptions {
-    /**
-     * The Soulcraft product name.
-     * Used to retrieve the correct per-product secrets (e.g. Hall secret, deploy secret)
-     * from the Portal config bundle.
-     *
-     * @example `'workshop'` | `'venue'` | `'academy'`
-     */
-    product: SoulcraftProduct;
-    /**
-     * Override the license key.
-     * When not provided, `SOULCRAFT_LICENSE_KEY` is read from the environment.
-     */
-    licenseKey?: string;
-}
-/**
- * A long-lived server SDK object returned by `createServerSDK.fromLicense()`.
- *
- * Wraps the Portal config bundle and exposes `createSDK(brain)` for per-request SDK
- * construction. The Hall module (if configured) is available as `server.hall`.
- */
-export interface ServerSDK {
-    /**
-     * Create a per-request `SoulcraftSDK` wrapping a live Brainy instance.
-     *
-     * All secrets are already injected from the license bundle — pass the resolved
-     * Brainy instance and the SDK is ready to use.
-     *
-     * @param brain - A Brainy instance from a `BrainyInstancePool`.
-     * @returns A fully assembled `SoulcraftSDK`.
-     */
-    createSDK(brain: Brainy): SoulcraftSDK;
-    /**
-     * The Hall module, connected to the Hall server at startup.
-     * Present only when the license bundle includes `hallSecret` and `hallUrl`.
-     */
-    readonly hall: HallModule | undefined;
-    /**
-     * The resolved license config bundle.
-     * Contains all secrets injected into the environment at startup.
-     */
-    readonly config: LicenseConfigBundle;
-    /**
-     * The product tier from the license response.
-     * `'free'` | `'pro'` | `'enterprise'` | `'internal'`
-     */
-    readonly tier: string;
-    /**
-     * Per-org billing configuration for Venue, keyed by org slug.
-     *
-     * Always present — empty object `{}` for non-Venue licenses. Populated from
-     * the Portal activate response and refreshed on the 4-hour re-validation cycle.
-     * Venue reads this at booking time rather than storing fee config in tenant Brainy,
-     * ensuring operators cannot self-modify their own platform fee rate.
-     *
-     * @example
-     * ```typescript
-     * const cfg = server.venueOrgConfig['canvas-and-corks']
-     * const rate = cfg?.platformFeeRate ?? 0.065
-     * ```
-     */
-    readonly venueOrgConfig: Record<string, VenueOrgBillingConfig>;
-    /**
-     * Gracefully shut down the server SDK.
-     *
-     * Stops the background re-validation timer and disconnects the Hall module.
-     */
-    shutdown(): void;
-}
-/**
- * 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())
- * ```
- */
-declare function fromLicense(options: FromLicenseOptions): Promise<ServerSDK>;
-/**
- * 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 declare const createServerSDK: {
-    fromLicense: typeof fromLicense;
-};
-export {};
-//# sourceMappingURL=from-license.d.ts.map

package/dist/server/from-license.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"from-license.d.ts","sourceRoot":"","sources":["../../src/server/from-license.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAG/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AA2BjE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,yCAAyC;IACzC,OAAO,CAAC,EAAE,aAAa,GAAG,cAAc,GAAG,MAAM,CAAA;IACjD,kCAAkC;IAClC,YAAY,CAAC,EAAE,iBAAiB,GAAG,cAAc,GAAG,QAAQ,CAAA;CAC7D;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qCAAqC;IACrC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,2CAA2C;IAC3C,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,2CAA2C;IAC3C,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kCAAkC;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAwBD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,OAAO,EAAE,gBAAgB,CAAA;IAEzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAA;IAEtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CAAA;IAErC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;IAEpC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAA;IAE9D;;;;OAIG;IACH,QAAQ,IAAI,IAAI,CAAA;CACjB;AA6HD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iBAAe,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,CA6H1E;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe;;CAE3B,CAAA"}