@soulcraft/sdk 1.0.0 → 1.2.0

package/dist/modules/billing/portal-provider.js

@@ -0,0 +1,204 @@
+/**
+ * @module billing/portal-provider
+ * @description Portal-backed billing provider for unified cross-product credit tracking.
+ *
+ * Delegates all credit checks and usage recording to the Portal credit API at
+ * `https://portal.soulcraft.com/api/credits/*`. This ensures that a user's
+ * 1,000 monthly credits are shared across Workshop, Venue, and Academy — not siloed
+ * per product.
+ *
+ * Activated when `PORTAL_CREDIT_SECRET` is set in the environment. Takes precedence
+ * over the Firestore provider.
+ *
+ * **Endpoint summary:**
+ * ```
+ * POST /api/credits/check   — pre-flight before an AI call
+ * POST /api/credits/consume — deduct usage after a single AI response
+ * POST /api/credits/batch   — flush buffered usage at end of session
+ * ```
+ *
+ * All requests carry `X-Portal-Credit-Secret: <PORTAL_CREDIT_SECRET>`.
+ *
+ * Subscription data, top-up balances, and usage history are not surfaced via
+ * this API — those are managed by Portal directly. Methods that require them
+ * (`getUsageStatus`, `getSubscription`, `addTopUp`) return safe defaults.
+ * Products that need rich billing UI should call Portal's management API directly.
+ *
+ * @example
+ * ```typescript
+ * // Automatically selected when PORTAL_CREDIT_SECRET is set:
+ * const billing = createBillingModule()
+ *
+ * // Explicit override (e.g. for testing):
+ * const billing = createBillingModule({
+ *   provider: new PortalBillingProvider('https://portal.soulcraft.com', secret, 'workshop'),
+ * })
+ * ```
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Period helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function _currentPeriod() {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+function _thirtyDaysFromNow() {
+    return new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Portal-backed billing provider.
+ *
+ * Calls the Portal credit API for all gate checks and usage recording.
+ * All requests are authenticated with the `X-Portal-Credit-Secret` header.
+ *
+ * The `userId` parameter on all methods must be the user's **email address** —
+ * the same identifier Portal uses to look up the license document.
+ */
+export class PortalBillingProvider {
+    baseUrl;
+    secret;
+    product;
+    /**
+     * @param baseUrl - Portal base URL (e.g. `"https://portal.soulcraft.com"`).
+     * @param secret - The value of `PORTAL_CREDIT_SECRET`.
+     * @param product - The product name sent with consume/batch calls (`'workshop'`, `'venue'`, `'academy'`).
+     */
+    constructor(baseUrl, secret, product) {
+        this.baseUrl = baseUrl;
+        this.secret = secret;
+        this.product = product;
+    }
+    // ── Internal helpers ──────────────────────────────────────────────────────
+    _headers() {
+        return {
+            'Content-Type': 'application/json',
+            'X-Portal-Credit-Secret': this.secret,
+        };
+    }
+    async _post(path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            throw new Error(`Portal credit API error (${response.status}) at ${path}`);
+        }
+        return response.json();
+    }
+    // ── BillingProvider interface ─────────────────────────────────────────────
+    async checkLimit(userId, hasPersonalKey) {
+        if (hasPersonalKey) {
+            return { ok: true, remaining: Infinity, topUpBalance: 0, totalAvailable: Infinity, useTopUp: false };
+        }
+        try {
+            const result = await this._post('/api/credits/check', { userEmail: userId, product: this.product });
+            return {
+                ok: result.ok,
+                remaining: result.remaining ?? 0,
+                topUpBalance: result.topUpBalance ?? 0,
+                totalAvailable: result.totalAvailable ?? 0,
+                useTopUp: !result.ok ? false : (result.remaining ?? 1) <= 0,
+                ...(!result.ok && result.reason ? { reason: result.reason === 'no_subscription' ? 'no_subscription' : 'limit_reached' } : {}),
+            };
+        }
+        catch {
+            // Network failure — fail open to avoid blocking AI calls due to Portal downtime.
+            return { ok: true, remaining: 1, topUpBalance: 0, totalAvailable: 1, useTopUp: false };
+        }
+    }
+    async getUsage(userId) {
+        // Portal does not expose per-product usage history via the credit API.
+        // Return a minimal placeholder — products that need full usage dashboards
+        // should call Portal's management API directly.
+        void userId;
+        return {
+            currentPeriod: _currentPeriod(),
+            periodEnd: _thirtyDaysFromNow(),
+            messagesUsed: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            byModel: {},
+            lastUpdated: new Date().toISOString(),
+        };
+    }
+    async getUsageStatus(userId, hasPersonalKey) {
+        const check = await this.checkLimit(userId, hasPersonalKey);
+        const usage = await this.getUsage(userId);
+        if (hasPersonalKey) {
+            return {
+                mode: 'byok',
+                usage,
+                limit: null,
+                remaining: null,
+                topUpBalance: 0,
+                totalAvailable: null,
+                percentUsed: null,
+                resetsAt: usage.periodEnd,
+                estimatedCostUSD: 0,
+            };
+        }
+        return {
+            mode: check.ok ? 'included' : 'free',
+            usage,
+            limit: null, // Portal doesn't expose the plan limit via this API
+            remaining: check.remaining === Infinity ? null : check.remaining,
+            topUpBalance: check.topUpBalance,
+            totalAvailable: check.totalAvailable === Infinity ? null : check.totalAvailable,
+            percentUsed: null,
+            resetsAt: usage.periodEnd,
+            estimatedCostUSD: 0,
+            isFreeUser: !check.ok,
+        };
+    }
+    async incrementUsage(userId, inputTokens, outputTokens, model, _useTopUp) {
+        try {
+            await this._post('/api/credits/consume', {
+                userEmail: userId,
+                product: this.product,
+                inputTokens,
+                outputTokens,
+                model,
+            });
+        }
+        catch {
+            // Fire-and-forget — a consume failure does not block the caller.
+            console.error('[SDK/billing] Portal consume failed — usage may be under-counted');
+        }
+    }
+    async batchIncrementUsage(userId, batch) {
+        try {
+            await this._post('/api/credits/batch', {
+                userEmail: userId,
+                product: this.product,
+                messageCount: batch.messageCount,
+                inputTokens: batch.inputTokens,
+                outputTokens: batch.outputTokens,
+                byModel: batch.byModel,
+            });
+        }
+        catch {
+            console.error('[SDK/billing] Portal batch flush failed — usage may be under-counted');
+        }
+    }
+    async getSubscription(_userId) {
+        // Subscription data is not exposed via the credit API.
+        return undefined;
+    }
+    async hasActiveSubscription(userId) {
+        const check = await this.checkLimit(userId, false);
+        return check.ok;
+    }
+    async getTopUpBalance(userId) {
+        const check = await this.checkLimit(userId, false);
+        return check.topUpBalance;
+    }
+    async canAccessPaidFeature(userId) {
+        return this.hasActiveSubscription(userId);
+    }
+}
+//# sourceMappingURL=portal-provider.js.map

package/dist/modules/billing/portal-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal-provider.js","sourceRoot":"","sources":["../../../src/modules/billing/portal-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAWH,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,SAAS,cAAc;IACrB,MAAM,CAAC,GAAG,IAAI,IAAI,EAAE,CAAA;IACpB,OAAO,GAAG,CAAC,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;AAC1E,CAAC;AAED,SAAS,kBAAkB;IACzB,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAA;AACtE,CAAC;AAED,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,OAAO,qBAAqB;IAOb;IACA;IACA;IARnB;;;;OAIG;IACH,YACmB,OAAe,EACf,MAAc,EACd,OAAe;QAFf,YAAO,GAAP,OAAO,CAAQ;QACf,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAQ;IAC/B,CAAC;IAEJ,6EAA6E;IAErE,QAAQ;QACd,OAAO;YACL,cAAc,EAAE,kBAAkB;YAClC,wBAAwB,EAAE,IAAI,CAAC,MAAM;SACtC,CAAA;IACH,CAAC;IAEO,KAAK,CAAC,KAAK,CAAI,IAAY,EAAE,IAAa;QAChD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YACrD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE;YACxB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;SACpC,CAAC,CAAA;QACF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,CAAC,MAAM,QAAQ,IAAI,EAAE,CAAC,CAAA;QAC5E,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,EAAgB,CAAA;IACtC,CAAC;IAED,6EAA6E;IAE7E,KAAK,CAAC,UAAU,CAAC,MAAc,EAAE,cAAuB;QACtD,IAAI,cAAc,EAAE,CAAC;YACnB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;QACtG,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAM5B,oBAAoB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;YAEtE,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,CAAC;gBAChC,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,CAAC;gBACtC,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,CAAC;gBAC1C,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC;gBAC3D,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,KAAK,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9H,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACP,iFAAiF;YACjF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;QACxF,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAc;QAC3B,uEAAuE;QACvE,0EAA0E;QAC1E,gDAAgD;QAChD,KAAK,MAAM,CAAA;QACX,OAAO;YACL,aAAa,EAAE,cAAc,EAAE;YAC/B,SAAS,EAAE,kBAAkB,EAAE;YAC/B,YAAY,EAAE,CAAC;YACf,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;YACf,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAA;IACH,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,MAAc,EAAE,cAAuB;QAC1D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;QAC3D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QAEzC,IAAI,cAAc,EAAE,CAAC;YACnB,OAAO;gBACL,IAAI,EAAE,MAAM;gBACZ,KAAK;gBACL,KAAK,EAAE,IAAI;gBACX,SAAS,EAAE,IAAI;gBACf,YAAY,EAAE,CAAC;gBACf,cAAc,EAAE,IAAI;gBACpB,WAAW,EAAE,IAAI;gBACjB,QAAQ,EAAE,KAAK,CAAC,SAAS;gBACzB,gBAAgB,EAAE,CAAC;aACpB,CAAA;QACH,CAAC;QAED,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM;YACpC,KAAK;YACL,KAAK,EAAE,IAAI,EAAI,oDAAoD;YACnE,SAAS,EAAE,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS;YAChE,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,cAAc,EAAE,KAAK,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc;YAC/E,WAAW,EAAE,IAAI;YACjB,QAAQ,EAAE,KAAK,CAAC,SAAS;YACzB,gBAAgB,EAAE,CAAC;YACnB,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE;SACtB,CAAA;IACH,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,MAAc,EACd,WAAmB,EACnB,YAAoB,EACpB,KAAa,EACb,SAAkB;QAElB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,sBAAsB,EAAE;gBACvC,SAAS,EAAE,MAAM;gBACjB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,WAAW;gBACX,YAAY;gBACZ,KAAK;aACN,CAAC,CAAA;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;YACjE,OAAO,CAAC,KAAK,CAAC,kEAAkE,CAAC,CAAA;QACnF,CAAC;IACH,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAC,MAAc,EAAE,KAAyB;QACjE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,oBAAoB,EAAE;gBACrC,SAAS,EAAE,MAAM;gBACjB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAA;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,KAAK,CAAC,sEAAsE,CAAC,CAAA;QACvF,CAAC;IACH,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,OAAe;QACnC,uDAAuD;QACvD,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAC,MAAc;QACxC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QAClD,OAAO,KAAK,CAAC,EAAE,CAAA;IACjB,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,MAAc;QAClC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QAClD,OAAO,KAAK,CAAC,YAAY,CAAA;IAC3B,CAAC;IAED,KAAK,CAAC,oBAAoB,CAAC,MAAc;QACvC,OAAO,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAA;IAC3C,CAAC;CACF"}

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

@@ -1,7 +1,327 @@
 /**
  * @module billing/types
- * @description Type definitions for sdk.billing.*
- * Implementation: Phase 5 per ADR-001.
+ * @description Type definitions for sdk.billing.* — usage metering, subscription
+ * management, top-up credits, and Stripe integration.
+ *
+ * The billing module provides:
+ * - **Usage metering**: track AI message counts and token consumption per user per period
+ * - **Limit enforcement**: check whether a user can make another AI request
+ * - **Stripe subscriptions**: create checkout sessions, manage subscriptions, customer portal
+ * - **Top-up credits**: purchase additional credits beyond the monthly allowance
+ * - **Provider abstraction**: local file storage (dev) or Firestore (production)
+ *
+ * The billing provider is selected automatically (priority order):
+ * 1. `PORTAL_CREDIT_SECRET` set → `PortalBillingProvider` (cross-product unified credits)
+ * 2. `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (per-product production)
+ * 3. Neither → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
+ *
+ * @example Checking limits before an AI call
+ * ```typescript
+ * const check = await sdk.billing.checkLimit(user.id, user.hasByok)
+ * if (!check.ok) return c.json({ error: 'Monthly limit reached', reason: check.reason }, 402)
+ * const response = await sdk.ai.complete(...)
+ * sdk.billing.recordUsage(user.id, response.usage.inputTokens, response.usage.outputTokens, response.model)
+ * ```
  */
-export type {};
+/**
+ * Soulcraft subscription plan identifier.
+ *
+ * - `free` — No subscription; limited monthly message allowance
+ * - `standard` — Paid subscription with included monthly credits
+ * - `byok` — Bring Your Own Key; unlimited usage with personal Anthropic key
+ */
+export type BillingPlanType = 'free' | 'standard' | 'byok';
+/**
+ * Stripe/Firestore subscription status.
+ */
+export type SubscriptionStatus = 'active' | 'past_due' | 'canceled' | 'trialing';
+/**
+ * Per-model token usage breakdown.
+ */
+export interface ModelUsage {
+    /** Input tokens consumed on this model. */
+    input: number;
+    /** Output tokens consumed on this model. */
+    output: number;
+}
+/**
+ * Aggregated usage data for a user in a billing period.
+ */
+export interface UsageData {
+    /** Billing period identifier in `'YYYY-MM'` format (for display only). */
+    currentPeriod: string;
+    /**
+     * ISO 8601 date when the current period ends and usage resets.
+     * Anniversary-based (tied to subscription renewal date, not calendar month).
+     */
+    periodEnd: string;
+    /** Total AI messages sent this period. */
+    messagesUsed: number;
+    /** Total input tokens consumed this period across all models. */
+    inputTokens: number;
+    /** Total output tokens consumed this period across all models. */
+    outputTokens: number;
+    /** Per-model breakdown of token usage. Keys are model IDs. */
+    byModel: Record<string, ModelUsage>;
+    /** ISO 8601 timestamp of the last usage update. */
+    lastUpdated: string;
+}
+/**
+ * Stripe subscription state stored in the billing backend.
+ */
+export interface SubscriptionData {
+    /** Stripe customer ID (e.g. `'cus_...'`). */
+    stripeCustomerId?: string;
+    /** Stripe subscription ID (e.g. `'sub_...'`). */
+    stripeSubscriptionId?: string;
+    /** Active plan. */
+    plan: BillingPlanType;
+    /** Stripe subscription status. */
+    status: SubscriptionStatus;
+    /**
+     * ISO 8601 timestamp when the current billing period ends.
+     * Used to determine the anniversary-based reset date.
+     */
+    currentPeriodEnd?: string;
+    /** Whether the subscription is set to cancel at the end of the current period. */
+    cancelAtPeriodEnd?: boolean;
+    /** Admin-assigned gift: the staff member's user ID who granted this subscription. */
+    giftedBy?: string;
+    /** ISO 8601 timestamp when the gift was granted. */
+    giftedAt?: string;
+    /** ISO 8601 timestamp when a gift subscription expires. */
+    expiresAt?: string;
+    /** Admin note (e.g. `'Beta tester'`, `'Partner: Acme Corp'`). */
+    note?: string;
+}
+/**
+ * Result of a pre-request credit limit check.
+ */
+export interface LimitCheckResult {
+    /** Whether the user is allowed to make an AI request. */
+    ok: boolean;
+    /** Remaining monthly credits (excluding top-ups). */
+    remaining: number;
+    /** Top-up credit balance. */
+    topUpBalance: number;
+    /** Total available credits (`remaining + topUpBalance`). */
+    totalAvailable: number;
+    /** When `true`, this request should draw from top-up balance, not monthly allowance. */
+    useTopUp: boolean;
+    /** Reason for denial when `ok` is `false`. */
+    reason?: 'limit_reached' | 'no_subscription';
+}
+/**
+ * Full usage status for a user — suitable for billing dashboards and quota displays.
+ */
+export interface UsageStatus {
+    /** Whether this user is BYOK (`'byok'`), has included credits (`'included'`), or is on free tier (`'free'`). */
+    mode: 'byok' | 'included' | 'free';
+    /** Raw usage data for the current period. */
+    usage: UsageData;
+    /** Monthly credit limit. `null` for BYOK users (unlimited). */
+    limit: number | null;
+    /** Credits remaining this period. `null` for BYOK users. */
+    remaining: number | null;
+    /** Top-up credit balance. */
+    topUpBalance: number;
+    /** Total available (`remaining + topUpBalance`). `null` for BYOK users. */
+    totalAvailable: number | null;
+    /** Usage as a percentage of the monthly limit (0–100). `null` for BYOK users. */
+    percentUsed: number | null;
+    /** ISO 8601 date when the usage period resets. */
+    resetsAt: string;
+    /** Estimated cost in USD based on token counts and model pricing. */
+    estimatedCostUSD: number;
+    /** Current subscription details. */
+    subscription?: SubscriptionData;
+    /** Whether this user is on the free tier (no active subscription). */
+    isFreeUser?: boolean;
+}
+/**
+ * Options for creating a Stripe checkout session.
+ */
+export interface CreateCheckoutSessionOptions {
+    /** The Stripe price ID for the subscription plan. */
+    priceId: string;
+    /** URL to redirect to on successful checkout. */
+    successUrl: string;
+    /** URL to redirect to if the user cancels checkout. */
+    cancelUrl: string;
+    /** Pre-fill the customer email in the Stripe checkout form. */
+    customerEmail?: string;
+    /** Existing Stripe customer ID (skips the email pre-fill). */
+    customerId?: string;
+}
+/**
+ * Options for creating a Stripe customer portal session.
+ */
+export interface CreatePortalSessionOptions {
+    /** Stripe customer ID. */
+    customerId: string;
+    /** URL to redirect to when the customer closes the portal. */
+    returnUrl: string;
+}
+/**
+ * Internal billing provider interface. Implemented by `LocalBillingProvider`
+ * and `FirestoreBillingProvider`.
+ *
+ * @internal
+ */
+export interface BillingProvider {
+    checkLimit(userId: string, hasPersonalKey: boolean): Promise<LimitCheckResult>;
+    getUsage(userId: string): Promise<UsageData>;
+    getUsageStatus(userId: string, hasPersonalKey: boolean): Promise<UsageStatus>;
+    incrementUsage(userId: string, inputTokens: number, outputTokens: number, model: string, useTopUp: boolean): Promise<void>;
+    batchIncrementUsage(userId: string, batch: BatchIncrementData): Promise<void>;
+    getSubscription(userId: string): Promise<SubscriptionData | undefined>;
+    hasActiveSubscription(userId: string): Promise<boolean>;
+    getTopUpBalance(userId: string): Promise<number>;
+    canAccessPaidFeature(userId: string): Promise<boolean>;
+}
+/**
+ * Accumulated usage data for a batch flush.
+ * @internal
+ */
+export interface BatchIncrementData {
+    messageCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    topUpUsed: number;
+    byModel: Record<string, {
+        input: number;
+        output: number;
+    }>;
+}
+/**
+ * The `sdk.billing.*` namespace — usage metering, subscriptions, and top-up credits.
+ */
+export interface BillingModule {
+    /**
+     * Check whether a user has credits available for an AI request.
+     *
+     * Returns immediately from cache where possible. BYOK users (`hasPersonalKey: true`)
+     * always return `{ ok: true }`.
+     *
+     * @param userId - The authenticated user's ID.
+     * @param hasPersonalKey - Whether this user has a BYOK Anthropic API key.
+     * @returns Credit availability result including remaining balance.
+     */
+    checkLimit(userId: string, hasPersonalKey: boolean): Promise<LimitCheckResult>;
+    /**
+     * Record AI usage for a user after a completed model call.
+     *
+     * This is fire-and-forget — buffered in memory and flushed to the billing
+     * backend every 5 seconds. Does not block the caller.
+     *
+     * @param userId - The authenticated user's ID.
+     * @param inputTokens - Input tokens consumed.
+     * @param outputTokens - Output tokens consumed.
+     * @param model - Model ID (e.g. `'claude-haiku-4-5-20251001'`).
+     */
+    recordUsage(userId: string, inputTokens: number, outputTokens: number, model: string): void;
+    /**
+     * Get the current usage data for a user.
+     *
+     * @param userId - The authenticated user's ID.
+     * @returns Usage totals for the current billing period.
+     */
+    getUsage(userId: string): Promise<UsageData>;
+    /**
+     * Get the full usage status for a user, suitable for billing dashboards.
+     *
+     * @param userId - The authenticated user's ID.
+     * @param hasPersonalKey - Whether this user has a BYOK key.
+     * @returns Detailed usage status with limits, remaining, and cost estimate.
+     */
+    getUsageStatus(userId: string, hasPersonalKey: boolean): Promise<UsageStatus>;
+    /**
+     * Get the active Stripe subscription for a user.
+     *
+     * @param userId - The authenticated user's ID.
+     * @returns Subscription data, or `undefined` if the user has no subscription.
+     */
+    getSubscription(userId: string): Promise<SubscriptionData | undefined>;
+    /**
+     * Check whether a user has an active Stripe subscription.
+     *
+     * @param userId - The authenticated user's ID.
+     * @returns `true` if the user has an active or trialing subscription.
+     */
+    hasActiveSubscription(userId: string): Promise<boolean>;
+    /**
+     * Create a Stripe checkout session for a new subscription.
+     *
+     * @param options - Checkout session parameters.
+     * @returns The Stripe checkout session URL to redirect the user to.
+     *
+     * @throws When `STRIPE_SECRET_KEY` is not configured.
+     *
+     * @example
+     * ```typescript
+     * const url = await sdk.billing.createCheckoutSession({
+     *   priceId: 'price_...',
+     *   successUrl: 'https://app.example.com/billing/success',
+     *   cancelUrl: 'https://app.example.com/billing',
+     *   customerEmail: user.email,
+     * })
+     * return c.redirect(url)
+     * ```
+     */
+    createCheckoutSession(options: CreateCheckoutSessionOptions): Promise<string>;
+    /**
+     * Create a Stripe customer portal session for managing subscriptions.
+     *
+     * @param options - Portal session parameters.
+     * @returns The Stripe portal session URL to redirect the user to.
+     *
+     * @throws When `STRIPE_SECRET_KEY` is not configured.
+     */
+    createPortalSession(options: CreatePortalSessionOptions): Promise<string>;
+    /**
+     * Cancel a user's active Stripe subscription at the end of the current period.
+     *
+     * @param userId - The authenticated user's ID.
+     * @throws When the user has no active subscription or Stripe is not configured.
+     */
+    cancelSubscription(userId: string): Promise<void>;
+    /**
+     * Get the current top-up credit balance for a user.
+     *
+     * @param userId - The authenticated user's ID.
+     * @returns The number of purchased top-up credits remaining.
+     */
+    getTopUpBalance(userId: string): Promise<number>;
+    /**
+     * Add top-up credits to a user's balance.
+     *
+     * Typically called from a Stripe webhook handler after a successful one-time purchase.
+     *
+     * @param userId - The authenticated user's ID.
+     * @param amount - Number of credits to add.
+     * @returns The new top-up balance after adding credits.
+     */
+    addTopUp(userId: string, amount: number): Promise<number>;
+    /**
+     * Check whether a user can access paid features.
+     *
+     * Returns `true` for active subscribers and BYOK users; `false` for free tier
+     * users who have exhausted their allowance.
+     *
+     * @param userId - The authenticated user's ID.
+     */
+    canAccessPaidFeature(userId: string): Promise<boolean>;
+    /**
+     * Flush all pending usage increments to the billing backend immediately.
+     *
+     * Called automatically every 5 seconds and on graceful shutdown.
+     * Safe to call manually (e.g. before a deployment restart).
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the background flush interval.
+     * Call this during graceful shutdown to avoid keeping the process alive.
+     */
+    stopFlush(): void;
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/types.ts"],"names":[],"mappings":"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"}

package/dist/modules/billing/types.js

@@ -1,7 +1,27 @@
 /**
  * @module billing/types
- * @description Type definitions for sdk.billing.*
- * Implementation: Phase 5 per ADR-001.
+ * @description Type definitions for sdk.billing.* — usage metering, subscription
+ * management, top-up credits, and Stripe integration.
+ *
+ * The billing module provides:
+ * - **Usage metering**: track AI message counts and token consumption per user per period
+ * - **Limit enforcement**: check whether a user can make another AI request
+ * - **Stripe subscriptions**: create checkout sessions, manage subscriptions, customer portal
+ * - **Top-up credits**: purchase additional credits beyond the monthly allowance
+ * - **Provider abstraction**: local file storage (dev) or Firestore (production)
+ *
+ * The billing provider is selected automatically (priority order):
+ * 1. `PORTAL_CREDIT_SECRET` set → `PortalBillingProvider` (cross-product unified credits)
+ * 2. `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (per-product production)
+ * 3. Neither → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
+ *
+ * @example Checking limits before an AI call
+ * ```typescript
+ * const check = await sdk.billing.checkLimit(user.id, user.hasByok)
+ * if (!check.ok) return c.json({ error: 'Monthly limit reached', reason: check.reason }, 402)
+ * const response = await sdk.ai.complete(...)
+ * sdk.billing.recordUsage(user.id, response.usage.inputTokens, response.usage.outputTokens, response.model)
+ * ```
  */
 export {};
 //# sourceMappingURL=types.js.map

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

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

package/dist/modules/billing/usage-buffer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @module billing/usage-buffer
+ * @description Fire-and-forget write-behind buffer for AI usage tracking.
+ *
+ * The usage buffer accumulates per-user token increments in memory and flushes
+ * them to the billing provider in a single batch write every 5 seconds. This
+ * pattern eliminates billing writes from the critical path of AI responses —
+ * the SSE `done` event is emitted before any billing I/O.
+ *
+ * Up to 5 seconds of usage may be lost on unclean process exits. This is
+ * acceptable for the billing use case — users are not double-charged on restart,
+ * and a few messages of under-counting per process lifetime is tolerable.
+ *
+ * @example
+ * ```typescript
+ * const buffer = new UsageBuffer(billingProvider)
+ *
+ * // Fire-and-forget — never await this:
+ * buffer.increment('user-123', 500, 200, 'claude-haiku-4-5-20251001', false)
+ *
+ * // On graceful shutdown:
+ * await buffer.flush()
+ * buffer.stop()
+ * ```
+ */
+import type { BillingProvider } from './types.js';
+/**
+ * Write-behind usage buffer.
+ *
+ * Thread-safe within a single Node.js/Bun process (single-threaded event loop).
+ * Accumulates increments in memory and flushes to the billing provider on a
+ * 5-second interval. Also exposes `flush()` for explicit drain on shutdown.
+ */
+export declare class UsageBuffer {
+    private readonly provider;
+    private readonly pending;
+    private _timer;
+    /**
+     * @param provider - The billing provider to flush to.
+     */
+    constructor(provider: BillingProvider);
+    /**
+     * Record a usage increment for a user.
+     *
+     * This method is synchronous and never throws. Usage is accumulated in memory
+     * and written to the billing backend on the next flush.
+     *
+     * @param userId - The authenticated user's ID.
+     * @param inputTokens - Input tokens consumed.
+     * @param outputTokens - Output tokens consumed.
+     * @param model - Model ID (e.g. `'claude-haiku-4-5-20251001'`).
+     * @param useTopUp - Whether this message drew from the top-up balance.
+     */
+    increment(userId: string, inputTokens: number, outputTokens: number, model: string, useTopUp: boolean): void;
+    /**
+     * Flush all pending usage increments to the billing provider.
+     *
+     * Called automatically on the 5-second interval, and on explicit calls from
+     * the billing module's `flush()` method (e.g. graceful shutdown).
+     *
+     * Errors are caught and logged — a flush failure never propagates to callers.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the background flush interval.
+     * Call this during graceful shutdown after flushing.
+     */
+    stop(): void;
+    private _start;
+    private _requeue;
+}
+//# sourceMappingURL=usage-buffer.d.ts.map

package/dist/modules/billing/usage-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-buffer.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/usage-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,YAAY,CAAA;AAcrE;;;;;;GAMG;AACH,qBAAa,WAAW;IAOV,OAAO,CAAC,QAAQ,CAAC,QAAQ;IANrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,MAAM,CAA4C;IAE1D;;OAEG;gBAC0B,QAAQ,EAAE,eAAe;IAItD;;;;;;;;;;;OAWG;IACH,SAAS,CACP,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,GAChB,IAAI;IAmBP;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B5B;;;OAGG;IACH,IAAI,IAAI,IAAI;IASZ,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,QAAQ;CAgBjB"}