@soulcraft/sdk 1.0.0 → 1.2.0

package/dist/modules/kits/index.js

@@ -0,0 +1,85 @@
+/**
+ * @module kits
+ * @description Factory for sdk.kits.* — the Soulcraft kit registry module.
+ *
+ * Provides read-only access to kit configurations from the `@soulcraft/kits`
+ * package. The package is an optional peer dependency loaded lazily via
+ * `createRequire` so that the SDK compiles and runs without it installed;
+ * calls gracefully return `null` / empty array when it is absent.
+ *
+ * The factory accepts an optional `bundledRegistry` override (used in tests)
+ * to inject a mock registry without needing the real package.
+ *
+ * @example
+ * ```typescript
+ * import { createKitsModule } from '@soulcraft/sdk/server'
+ *
+ * const kits = createKitsModule()
+ * const kit = await kits.load('wicks-and-whiskers')
+ * console.log(kit?.name) // "Wicks & Whiskers"
+ * ```
+ */
+import { createRequire } from 'node:module';
+// createRequire enables CJS-style require() inside an ESM module — the only
+// reliable way to conditionally load optional peer dependencies in Node/Bun ESM.
+const _require = createRequire(import.meta.url);
+// Module-level cache — loaded once per process, not per SDK instance.
+let _registryCache = undefined;
+/**
+ * Load the kit registry from the installed `@soulcraft/kits` package.
+ * Returns `null` when the package is not installed, allowing callers to
+ * degrade gracefully rather than throwing.
+ */
+function _getBundledRegistry() {
+    if (_registryCache !== undefined)
+        return _registryCache;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const kits = _require('@soulcraft/kits');
+        _registryCache = kits.kitRegistry ?? null;
+    }
+    catch {
+        _registryCache = null;
+    }
+    return _registryCache;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create the `sdk.kits.*` module.
+ *
+ * @param options - Optional overrides, primarily for testing.
+ * @returns A `KitsModule` backed by the `@soulcraft/kits` registry.
+ *
+ * @example
+ * ```typescript
+ * // In production:
+ * const kits = createKitsModule()
+ *
+ * // In tests — inject a mock registry to avoid the peer dep:
+ * const kits = createKitsModule({
+ *   bundledRegistry: { 'test-kit': { id: 'test-kit', name: 'Test Kit', ... } }
+ * })
+ * ```
+ */
+export function createKitsModule(options = {}) {
+    const getRegistry = options.bundledRegistry !== undefined
+        ? () => options.bundledRegistry ?? null
+        : _getBundledRegistry;
+    return {
+        async load(kitId) {
+            const registry = getRegistry();
+            if (!registry)
+                return null;
+            return registry[kitId] ?? null;
+        },
+        async list() {
+            const registry = getRegistry();
+            if (!registry)
+                return [];
+            return Object.values(registry);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/modules/kits/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C,4EAA4E;AAC5E,iFAAiF;AACjF,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAE/C,sEAAsE;AACtE,IAAI,cAAc,GAA0D,SAAS,CAAA;AAErF;;;;GAIG;AACH,SAAS,mBAAmB;IAC1B,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,cAAc,CAAA;IACvD,IAAI,CAAC;QACH,8DAA8D;QAC9D,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAQ,CAAA;QAC/C,cAAc,GAAI,IAAI,CAAC,WAAkD,IAAI,IAAI,CAAA;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,cAAc,GAAG,IAAI,CAAA;IACvB,CAAC;IACD,OAAO,cAAc,CAAA;AACvB,CAAC;AAED,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAmC,EAAE;IACpE,MAAM,WAAW,GAAG,OAAO,CAAC,eAAe,KAAK,SAAS;QACvD,CAAC,CAAC,GAA8C,EAAE,CAAC,OAAO,CAAC,eAAe,IAAI,IAAI;QAClF,CAAC,CAAC,mBAAmB,CAAA;IAEvB,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,KAAa;YACtB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;YAC9B,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAA;YAC1B,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAA;QAChC,CAAC;QAED,KAAK,CAAC,IAAI;YACR,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;YAC9B,IAAI,CAAC,QAAQ;gBAAE,OAAO,EAAE,CAAA;YACxB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAChC,CAAC;KACF,CAAA;AACH,CAAC"}

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

@@ -1,7 +1,111 @@
 /**
  * @module kits/types
- * @description Type definitions for sdk.kits.*
- * Implementation: Phase 4 per ADR-001.
+ * @description Type definitions for sdk.kits.* — the kit loader and registry module.
+ *
+ * Kits (`@soulcraft/kits`) are pure configuration packages: `kit.json` manifests
+ * and `SKILL.md` prompt files that describe a domain, persona, glossary, and
+ * workflow. They contain no TypeScript logic, no server code, and no SDK imports.
+ *
+ * The `KitsModule` provides read-only access to the kit registry: loading a single
+ * kit by ID, listing all available kits, and accessing the raw skill registry.
+ *
+ * Kit initialization (populating a workspace's Brainy and VFS from a kit's
+ * `starterFiles`) is a product-level concern and lives in each product's
+ * bootstrap code, not in the SDK.
+ *
+ * @see `@soulcraft/kit-schema` for the full kit manifest schema with product-specific fields.
+ * @see `sdk.skills.*` for loading SKILL.md prompt files.
  */
-export type {};
+/**
+ * Base fields shared by every Soulcraft kit manifest.
+ *
+ * This is a structural subset of `BaseKitManifest` from `@soulcraft/kit-schema`.
+ * The SDK uses this minimal type to avoid a hard dependency on the schema package.
+ * Product-specific fields (venue config, workshop config, etc.) are accessible
+ * via type assertion against the full `@soulcraft/kit-schema` types if needed.
+ */
+export interface SoulcraftKitConfig {
+    /** Unique kit identifier, used as the registry key (e.g. `'wicks-and-whiskers'`). */
+    id: string;
+    /** Display name of the kit. */
+    name: string;
+    /** One-sentence description of what this kit is for. */
+    description: string;
+    /** Semantic version string (e.g. `'1.0.0'`). */
+    version: string;
+    /** Kit type discriminant. */
+    type: 'venue' | 'content' | 'app' | 'academy' | 'soulcraft';
+    /** Shared cross-product configuration. */
+    shared?: {
+        /** AI persona system prompt. */
+        aiPersona?: string;
+        /** Suggestion chips for AI chat interfaces. */
+        suggestions?: Array<{
+            label: string;
+            prompt: string;
+        }>;
+    };
+    /** Additional product-specific fields are permitted. */
+    [key: string]: unknown;
+}
+/**
+ * Options passed to `createKitsModule()` to override the bundled registry.
+ * Primarily useful in tests.
+ */
+export interface CreateKitsModuleOptions {
+    /**
+     * Override the kit registry loaded from `@soulcraft/kits`.
+     * When provided, the module uses this registry directly instead of requiring
+     * the package. Set to `null` to simulate the package being absent.
+     */
+    bundledRegistry?: Record<string, SoulcraftKitConfig> | null;
+}
+/**
+ * The `sdk.kits.*` namespace — read-only access to the Soulcraft kit registry.
+ *
+ * Backed by the `@soulcraft/kits` package (a peer dependency). If the package
+ * is not installed, `load()` returns `null` and `list()` returns an empty array.
+ *
+ * @example
+ * ```typescript
+ * const kit = await sdk.kits.load('wicks-and-whiskers')
+ * if (kit) {
+ *   const response = await sdk.ai.complete({
+ *     messages: [{ role: 'user', content: 'What candles are low in stock?' }],
+ *     systemPrompt: kit.shared?.aiPersona,
+ *   })
+ * }
+ * ```
+ */
+export interface KitsModule {
+    /**
+     * Load a single kit configuration by ID.
+     *
+     * Returns `null` if the kit is not found or `@soulcraft/kits` is not installed.
+     *
+     * @param kitId - The kit identifier (e.g. `'wicks-and-whiskers'`).
+     * @returns The kit configuration, or `null` if not found.
+     *
+     * @example
+     * ```typescript
+     * const kit = await sdk.kits.load('wicks-and-whiskers')
+     * console.log(kit?.name) // → "Wicks & Whiskers"
+     * ```
+     */
+    load(kitId: string): Promise<SoulcraftKitConfig | null>;
+    /**
+     * List all available kits from the registry.
+     *
+     * Returns an empty array if `@soulcraft/kits` is not installed.
+     *
+     * @returns All kit configurations as an array.
+     *
+     * @example
+     * ```typescript
+     * const kits = await sdk.kits.list()
+     * console.log(kits.map(k => k.name))
+     * ```
+     */
+    list(): Promise<SoulcraftKitConfig[]>;
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAA;IACV,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,6BAA6B;IAC7B,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,CAAA;IAC3D,0CAA0C;IAC1C,MAAM,CAAC,EAAE;QACP,gCAAgC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,+CAA+C;QAC/C,WAAW,CAAC,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACvD,CAAA;IACD,wDAAwD;IACxD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAMD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAA;CAC5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAA;IAEvD;;;;;;;;;;;;OAYG;IACH,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;CACtC"}

package/dist/modules/kits/types.js

@@ -1,7 +1,20 @@
 /**
  * @module kits/types
- * @description Type definitions for sdk.kits.*
- * Implementation: Phase 4 per ADR-001.
+ * @description Type definitions for sdk.kits.* — the kit loader and registry module.
+ *
+ * Kits (`@soulcraft/kits`) are pure configuration packages: `kit.json` manifests
+ * and `SKILL.md` prompt files that describe a domain, persona, glossary, and
+ * workflow. They contain no TypeScript logic, no server code, and no SDK imports.
+ *
+ * The `KitsModule` provides read-only access to the kit registry: loading a single
+ * kit by ID, listing all available kits, and accessing the raw skill registry.
+ *
+ * Kit initialization (populating a workspace's Brainy and VFS from a kit's
+ * `starterFiles`) is a product-level concern and lives in each product's
+ * bootstrap code, not in the SDK.
+ *
+ * @see `@soulcraft/kit-schema` for the full kit manifest schema with product-specific fields.
+ * @see `sdk.skills.*` for loading SKILL.md prompt files.
  */
 export {};
 //# sourceMappingURL=types.js.map

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

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

package/dist/modules/license/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module license
+ * @description Factory for sdk.license.* — license validation, AI credit management,
+ * and BYOK API key support.
+ *
+ * Validates the product license against the Portal license server. Initialization
+ * is lazy: the first call to `validate()` performs an online check against
+ * `portal.soulcraft.com` and starts the background heartbeat.
+ *
+ * License state is read from the `SOULCRAFT_LICENSE_KEY` environment variable
+ * or a `.soulcraft.json` file in the working directory. On free-tier deployments
+ * (no key configured), `validate()` returns `{ valid: false, tier: 'free' }` and
+ * all AI credit limits apply.
+ *
+ * **AI credit metering** delegates to the `sdk.billing.*` module for storage and
+ * period management. The license module provides the gate check and credit recording
+ * interface; billing handles persistence.
+ *
+ * **BYOK users** always bypass credit metering — they provide their own Anthropic key
+ * and are not subject to monthly limits.
+ *
+ * @example Server startup
+ * ```typescript
+ * // Force immediate license check and start heartbeat:
+ * sdk.license.startHeartbeat()
+ * const result = await sdk.license.validate(true)
+ * if (!result.valid) console.warn('[SDK] No active license — running in free tier')
+ * ```
+ */
+import type { LicenseModule } from './types.js';
+import type { BillingModule } from '../billing/types.js';
+/** Options for `createLicenseModule()`. */
+export interface CreateLicenseModuleOptions {
+    /**
+     * The billing module instance, used for AI credit metering.
+     * When not provided, credit checks assume unlimited (no billing gate).
+     */
+    billing?: BillingModule;
+    /**
+     * Register a user's BYOK Anthropic API key.
+     * The license module uses this to short-circuit credit checks for BYOK users.
+     */
+    byokKeys?: Map<string, string>;
+}
+/**
+ * Create the `sdk.license.*` module.
+ *
+ * @param options - Optional billing module and BYOK key overrides.
+ * @returns A fully configured `LicenseModule`.
+ */
+export declare function createLicenseModule(options?: CreateLicenseModuleOptions): LicenseModule;
+export type { LicenseResult, LicensePlanTier, LicenseFeatures, AICreditCheckResult, AIUsageRecord, AIProviderConfig, LicenseModule, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/license/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/license/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EACV,aAAa,EAMd,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAqDxD,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAqK3F;AAGD,YAAY,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAA"}

package/dist/modules/license/index.js

@@ -0,0 +1,233 @@
+/**
+ * @module license
+ * @description Factory for sdk.license.* — license validation, AI credit management,
+ * and BYOK API key support.
+ *
+ * Validates the product license against the Portal license server. Initialization
+ * is lazy: the first call to `validate()` performs an online check against
+ * `portal.soulcraft.com` and starts the background heartbeat.
+ *
+ * License state is read from the `SOULCRAFT_LICENSE_KEY` environment variable
+ * or a `.soulcraft.json` file in the working directory. On free-tier deployments
+ * (no key configured), `validate()` returns `{ valid: false, tier: 'free' }` and
+ * all AI credit limits apply.
+ *
+ * **AI credit metering** delegates to the `sdk.billing.*` module for storage and
+ * period management. The license module provides the gate check and credit recording
+ * interface; billing handles persistence.
+ *
+ * **BYOK users** always bypass credit metering — they provide their own Anthropic key
+ * and are not subject to monthly limits.
+ *
+ * @example Server startup
+ * ```typescript
+ * // Force immediate license check and start heartbeat:
+ * sdk.license.startHeartbeat()
+ * const result = await sdk.license.validate(true)
+ * if (!result.valid) console.warn('[SDK] No active license — running in free tier')
+ * ```
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Portal license API
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default heartbeat interval: 4 hours. */
+const DEFAULT_CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000;
+/** Portal license validation endpoint. */
+const PORTAL_LICENSE_URL = 'https://portal.soulcraft.com/api/license/validate';
+/**
+ * Validate the license key against Portal.
+ * Reads `SOULCRAFT_LICENSE_KEY` from the environment.
+ * Returns a free-tier result when no key is configured.
+ */
+async function _validateWithPortal() {
+    const key = process.env['SOULCRAFT_LICENSE_KEY'];
+    if (!key) {
+        return { valid: false, tier: 'free', reason: 'No license key configured (SOULCRAFT_LICENSE_KEY)' };
+    }
+    try {
+        const response = await fetch(PORTAL_LICENSE_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ key }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            return { valid: false, tier: 'free', reason: `Portal responded ${response.status}` };
+        }
+        return (await response.json());
+    }
+    catch {
+        // Network failure — degrade gracefully. The cached result (if any) remains valid.
+        return { valid: false, tier: 'free', reason: 'License check failed (network error)' };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// BYOK key storage (in-process, keyed by userId)
+// ─────────────────────────────────────────────────────────────────────────────
+// BYOK keys are stored in memory only — they are never written to disk by the
+// SDK. Products are responsible for persisting them (e.g. encrypted in Firestore
+// or a user settings document). The license module reads them via getAIProvider()
+// which is overridable per-user via the byokStore.
+const _byokStore = new Map();
+/**
+ * Create the `sdk.license.*` module.
+ *
+ * @param options - Optional billing module and BYOK key overrides.
+ * @returns A fully configured `LicenseModule`.
+ */
+export function createLicenseModule(options = {}) {
+    const billing = options.billing;
+    const byokStore = options.byokKeys ?? _byokStore;
+    // Cached validation result — refreshed by heartbeat or explicit forceRefresh.
+    let _cachedResult;
+    // Whether the heartbeat interval is running.
+    let _heartbeatTimer;
+    // Pending init promise — deduplicates concurrent first-call races.
+    let _initPromise;
+    // ── Internal helpers ──────────────────────────────────────────────────────
+    async function _init() {
+        if (_initPromise)
+            return _initPromise;
+        _initPromise = (async () => {
+            const result = await _validateWithPortal();
+            _cachedResult = result;
+            // Start background heartbeat after first successful init.
+            if (!_heartbeatTimer) {
+                _startHeartbeat(DEFAULT_CHECK_INTERVAL_MS);
+            }
+            return result;
+        })();
+        return _initPromise;
+    }
+    async function _refreshHeartbeat() {
+        try {
+            const result = await _validateWithPortal();
+            _cachedResult = result;
+        }
+        catch {
+            // Heartbeat failures are non-fatal — the cached result remains valid.
+        }
+    }
+    function _startHeartbeat(intervalMs) {
+        if (_heartbeatTimer)
+            clearInterval(_heartbeatTimer);
+        _heartbeatTimer = setInterval(() => {
+            void _refreshHeartbeat();
+        }, intervalMs);
+        // Allow the process to exit normally even if the heartbeat is running.
+        if (_heartbeatTimer.unref)
+            _heartbeatTimer.unref();
+    }
+    function _tierToFeatures(tier) {
+        switch (tier) {
+            case 'enterprise':
+            case 'internal':
+                return { cortex: true, ai: { monthlyCredits: null } };
+            case 'pro':
+                return { cortex: true, ai: { monthlyCredits: 1000 } };
+            case 'free':
+            default:
+                return { cortex: false, ai: { monthlyCredits: 100 } };
+        }
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    return {
+        async validate(forceRefresh = false) {
+            if (forceRefresh || !_cachedResult) {
+                _initPromise = undefined; // Allow re-init on force refresh.
+                return _init();
+            }
+            return _cachedResult;
+        },
+        async isActive() {
+            const result = await _init();
+            return result.valid;
+        },
+        async plan() {
+            const result = await _init();
+            if (!result.valid)
+                return 'free';
+            return result.tier;
+        },
+        async features() {
+            const tier = await this.plan();
+            return _tierToFeatures(tier);
+        },
+        async checkAICredits(userId) {
+            // BYOK users bypass all credit metering.
+            if (byokStore.has(userId)) {
+                return { ok: true, remaining: null, isByok: true };
+            }
+            // If no billing module, assume unlimited (dev/free tier).
+            if (!billing) {
+                const active = await this.isActive();
+                if (!active) {
+                    return { ok: false, remaining: null, isByok: false, reason: 'license_inactive' };
+                }
+                return { ok: true, remaining: null, isByok: false };
+            }
+            const check = await billing.checkLimit(userId, false);
+            if (!check.ok) {
+                return { ok: false, remaining: check.remaining, isByok: false, reason: 'limit_reached' };
+            }
+            return { ok: true, remaining: check.remaining, isByok: false };
+        },
+        consumeAICredit(userId, usage) {
+            // BYOK users are not metered.
+            if (byokStore.has(userId))
+                return;
+            if (!billing)
+                return;
+            // Fire-and-forget — billing buffers and flushes asynchronously.
+            void billing.recordUsage(userId, usage.inputTokens, usage.outputTokens, usage.model);
+        },
+        async validateBYOK(apiKey) {
+            // Validate by attempting a minimal Anthropic API call (count_tokens endpoint
+            // is cheaper than a full completion).
+            try {
+                const response = await fetch('https://api.anthropic.com/v1/messages/count_tokens', {
+                    method: 'POST',
+                    headers: {
+                        'x-api-key': apiKey,
+                        'anthropic-version': '2023-06-01',
+                        'content-type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        model: 'claude-haiku-4-5-20251001',
+                        messages: [{ role: 'user', content: 'hi' }],
+                    }),
+                });
+                // 200 = valid key, 401 = invalid key, other = network/service error
+                return response.status === 200;
+            }
+            catch {
+                return false;
+            }
+        },
+        async getAIProvider(userId) {
+            const byokKey = byokStore.get(userId);
+            if (byokKey) {
+                return { apiKey: byokKey, source: 'byok' };
+            }
+            const platformKey = process.env['ANTHROPIC_API_KEY'];
+            if (!platformKey) {
+                throw new Error('No Anthropic API key available. Set ANTHROPIC_API_KEY in the environment ' +
+                    'or provide a BYOK key for this user via sdk.license.');
+            }
+            return { apiKey: platformKey, source: 'platform' };
+        },
+        startHeartbeat(intervalMs) {
+            const interval = intervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+            _startHeartbeat(interval);
+            // Force an immediate online check on explicit startHeartbeat() call.
+            void _refreshHeartbeat();
+        },
+        stopHeartbeat() {
+            if (_heartbeatTimer) {
+                clearInterval(_heartbeatTimer);
+                _heartbeatTimer = undefined;
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/modules/license/index.js.map

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