@soulcraft/sdk 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -25,9 +25,10 @@ export type { AiModule, AiCompleteOptions, AiCompleteResult, AiStreamOptions, Ai
 export { AI_MODELS } from './modules/ai/types.js';
 export type { EventsModule, SoulcraftEventMap, SoulcraftEventName, VfsWriteEvent, VfsDeleteEvent, VfsRenameEvent, } from './modules/events/types.js';
 export type { SkillsModule, Skill, SkillListOptions, SkillInstallOptions, } from './modules/skills/types.js';
-export type * from './modules/license/types.js';
-export type * from './modules/kits/types.js';
-export type * from './modules/formats/types.js';
-export type * from './modules/billing/types.js';
-export type * from './modules/notifications/types.js';
+export type { LicenseResult, LicenseModule, LicensePlanTier, LicenseFeatures, AICreditCheckResult, AIUsageRecord, AIProviderConfig, } from './modules/license/types.js';
+export type { KitsModule, SoulcraftKitConfig, } from './modules/kits/types.js';
+export type { WvizDocument, WvizEntity, WvizEdge, WvizSnapshot, WvizViewType, WdocDocument, WdocMeta, WdocBlock, WdocInlineContent, WdocTextNode, WdocMark, WdocParagraphBlock, WdocHeadingBlock, WdocBlockquoteBlock, WdocCodeBlock, WdocBulletListBlock, WdocOrderedListBlock, WdocListItemBlock, WdocTaskListBlock, WdocTaskItemBlock, WdocImageBlock, WdocVideoBlock, WdocIconBlock, WdocSvgEmbedBlock, WdocEmbedBlock, WdocTableBlock, WdocTableRowBlock, WdocTableCellBlock, WdocTableHeaderBlock, WdocHorizontalRuleBlock, WdocCalloutBlock, WslideDocument, WslideSlide, WslideBackground, WslideLayout, WslideTransition, WslideConfig, WquizDocument, WquizQuestion, WquizQuestionType, WquizAnswer, WquizScoringRules, SoulcraftFormat, SoulcraftFormatDocument, } from './modules/formats/types.js';
+export { SOULCRAFT_FORMATS } from './modules/formats/types.js';
+export type { BillingModule, BillingPlanType, SubscriptionStatus, ModelUsage, UsageData, UsageStatus, SubscriptionData, LimitCheckResult, BatchIncrementData, CreateCheckoutSessionOptions, CreatePortalSessionOptions, } from './modules/billing/types.js';
+export type { NotificationsModule, Notification, NotificationResult, NotificationSender, EmailNotification, SmsNotification, } from './modules/notifications/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAG9F,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,YAAY,EACV,MAAM,EACN,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,4BAA4B,CAAA;AAGnC,YAAY,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAGvD,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAGjE,YAAY,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,YAAY,GACb,MAAM,yBAAyB,CAAA;AAGhC,YAAY,EACV,UAAU,EACV,YAAY,EACZ,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,GACT,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,MAAM,0BAA0B,CAAA;AAGjC,YAAY,EACV,QAAQ,EACR,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,UAAU,EACV,SAAS,EACT,cAAc,EACd,MAAM,EACN,OAAO,GACR,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAGjD,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,2BAA2B,CAAA;AAGlC,YAAY,EACV,YAAY,EACZ,KAAK,EACL,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAGlC,mBAAmB,4BAA4B,CAAA;AAC/C,mBAAmB,yBAAyB,CAAA;AAC5C,mBAAmB,4BAA4B,CAAA;AAC/C,mBAAmB,4BAA4B,CAAA;AAC/C,mBAAmB,kCAAkC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -14,4 +14,5 @@ export { createCapabilityToken, verifyCapabilityToken, } from './modules/brainy/
 export { SDKError, SDKDisconnectedError, SDKTimeoutError, SDKAuthError, SDKForbiddenError, SDKRpcError, SDKMethodNotFoundError, } from './modules/brainy/errors.js';
 export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, computeEmailHash, getAuthMode, getOIDCClientConfig, } from './modules/auth/config.js';
 export { AI_MODELS } from './modules/ai/types.js';
+export { SOULCRAFT_FORMATS } from './modules/formats/types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8BH,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,4BAA4B,CAAA;AAgCnC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,MAAM,0BAA0B,CAAA;AAejC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8BH,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,4BAA4B,CAAA;AAgCnC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,MAAM,0BAA0B,CAAA;AAejC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAoFjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/modules/billing/firestore-provider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module billing/firestore-provider
+ * @description Firestore-backed billing provider for production deployments.
+ *
+ * Reads subscription and license data from the `licenses` Firestore collection
+ * managed by Portal (`soulcraft.com`). Workshop, Venue, and Academy all write
+ * usage counters to the same document so Portal's Admin can see cross-product usage.
+ *
+ * This provider is activated when `FIREBASE_SERVICE_ACCOUNT_KEY` is set in the
+ * environment. `firebase-admin` is loaded lazily via dynamic import so that the
+ * SDK does not require the package when using the local provider.
+ *
+ * **Firestore document structure:**
+ * ```
+ * licenses/{docId}
+ *   email: string                  (user email — used to look up the doc)
+ *   product: 'workshop' | 'venue' | 'academy'
+ *   status: 'active' | 'past_due' | 'canceled' | 'trialing'
+ *   plan: 'standard' | 'byok'
+ *   credits: {
+ *     monthlyIncluded: number
+ *     monthlyUsed: number          (SDK increments this)
+ *     topUpBalance: number         (SDK decrements this)
+ *     inputTokens: number
+ *     outputTokens: number
+ *     byModel: Record<model, { input, output }>
+ *     periodStart: Timestamp
+ *     periodEnd: Timestamp
+ *     lastUpdated: Timestamp
+ *   }
+ *   stripeCustomerId: string
+ *   stripeSubscriptionId: string
+ *   cancelAtPeriodEnd: boolean
+ * ```
+ *
+ * Note: The `userId` passed to provider methods is the user's email address when
+ * using Firestore, since the `licenses` collection is keyed by email. Products
+ * must pass `user.email` (not `user.id`) when constructing the SDK in Firestore mode.
+ */
+import type { BillingProvider, UsageData, SubscriptionData, LimitCheckResult, UsageStatus, BatchIncrementData } from './types.js';
+/**
+ * Firestore-backed billing provider for production deployments.
+ *
+ * The `userId` parameter on all methods must be the user's **email address**,
+ * since the Firestore `licenses` collection is indexed by email.
+ */
+export declare class FirestoreBillingProvider implements 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>;
+    private _toSubscription;
+    private _resetPeriod;
+}
+//# sourceMappingURL=firestore-provider.d.ts.map

package/dist/modules/billing/firestore-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-provider.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/firestore-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAkJnB;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IACxD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8B9E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAiB5C,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAgC7E,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1H,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB7E,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAMtE,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOvD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOhD,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAM5D,OAAO,CAAC,eAAe;YA2BT,YAAY;CAe3B"}

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

@@ -0,0 +1,314 @@
+/**
+ * @module billing/firestore-provider
+ * @description Firestore-backed billing provider for production deployments.
+ *
+ * Reads subscription and license data from the `licenses` Firestore collection
+ * managed by Portal (`soulcraft.com`). Workshop, Venue, and Academy all write
+ * usage counters to the same document so Portal's Admin can see cross-product usage.
+ *
+ * This provider is activated when `FIREBASE_SERVICE_ACCOUNT_KEY` is set in the
+ * environment. `firebase-admin` is loaded lazily via dynamic import so that the
+ * SDK does not require the package when using the local provider.
+ *
+ * **Firestore document structure:**
+ * ```
+ * licenses/{docId}
+ *   email: string                  (user email — used to look up the doc)
+ *   product: 'workshop' | 'venue' | 'academy'
+ *   status: 'active' | 'past_due' | 'canceled' | 'trialing'
+ *   plan: 'standard' | 'byok'
+ *   credits: {
+ *     monthlyIncluded: number
+ *     monthlyUsed: number          (SDK increments this)
+ *     topUpBalance: number         (SDK decrements this)
+ *     inputTokens: number
+ *     outputTokens: number
+ *     byModel: Record<model, { input, output }>
+ *     periodStart: Timestamp
+ *     periodEnd: Timestamp
+ *     lastUpdated: Timestamp
+ *   }
+ *   stripeCustomerId: string
+ *   stripeSubscriptionId: string
+ *   cancelAtPeriodEnd: boolean
+ * ```
+ *
+ * Note: The `userId` passed to provider methods is the user's email address when
+ * using Firestore, since the `licenses` collection is keyed by email. Products
+ * must pass `user.email` (not `user.id`) when constructing the SDK in Firestore mode.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Lazy loader
+// ─────────────────────────────────────────────────────────────────────────────
+let _db;
+let _FieldValue;
+async function _getFirestore() {
+    if (_db && _FieldValue)
+        return { db: _db, FieldValue: _FieldValue };
+    const key = process.env['FIREBASE_SERVICE_ACCOUNT_KEY'];
+    if (!key)
+        throw new Error('FIREBASE_SERVICE_ACCOUNT_KEY is not set — cannot use Firestore billing provider');
+    // firebase-admin is an optional peer dependency — loaded at runtime only when configured.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const admin = await Function('return import("firebase-admin")')();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const { getFirestore, FieldValue } = await Function('return import("firebase-admin/firestore")')();
+    if (!admin.apps?.length) {
+        admin.initializeApp({
+            credential: admin.credential.cert(JSON.parse(Buffer.from(key, 'base64').toString('utf-8'))),
+            preferRest: true, // Use REST transport — required for Bun compatibility (avoids gRPC).
+        });
+    }
+    _db = getFirestore();
+    _FieldValue = FieldValue;
+    return { db: _db, FieldValue: _FieldValue };
+}
+const _docCache = new Map();
+const DOC_CACHE_TTL_MS = 5 * 60 * 1000;
+async function _getLicenseDoc(email) {
+    const cached = _docCache.get(email);
+    if (cached && Date.now() < cached.expiresAt)
+        return cached;
+    const { db } = await _getFirestore();
+    const snap = await db.collection('licenses')
+        .where('email', '==', email.toLowerCase())
+        .where('status', 'in', ['active', 'trialing', 'past_due'])
+        .get();
+    if (!snap.docs.length)
+        return null;
+    const doc = snap.docs[0];
+    const data = doc.data() ?? {};
+    const result = { data, docId: doc.id, ref: doc.ref, expiresAt: Date.now() + DOC_CACHE_TTL_MS };
+    _docCache.set(email, result);
+    return result;
+}
+function _invalidateCache(email) {
+    _docCache.delete(email);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Period helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function _toISO(ts) {
+    if (!ts)
+        return undefined;
+    if (typeof ts === 'string')
+        return ts;
+    // Firestore Timestamp object
+    if (typeof ts === 'object' && ts !== null && 'toDate' in ts) {
+        return ts.toDate().toISOString();
+    }
+    return undefined;
+}
+function _currentPeriod() {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+function _shouldReset(periodEnd) {
+    const iso = _toISO(periodEnd);
+    if (!iso)
+        return true;
+    return new Date() >= new Date(iso);
+}
+const FREE_TIER_LIMIT = 100;
+const MODEL_PRICING = {
+    'claude-haiku-4-5-20251001': { input: 0.80, output: 4.00 },
+    'claude-sonnet-4-6': { input: 3.00, output: 15.00 },
+    'claude-opus-4-6': { input: 15.00, output: 75.00 },
+};
+function _estimateCostUSD(byModel) {
+    let total = 0;
+    for (const [model, counts] of Object.entries(byModel)) {
+        const pricing = MODEL_PRICING[model];
+        if (!pricing)
+            continue;
+        total += (counts.input / 1_000_000) * pricing.input;
+        total += (counts.output / 1_000_000) * pricing.output;
+    }
+    return Math.round(total * 10_000) / 10_000;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider implementation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Firestore-backed billing provider for production deployments.
+ *
+ * The `userId` parameter on all methods must be the user's **email address**,
+ * since the Firestore `licenses` collection is indexed by email.
+ */
+export class FirestoreBillingProvider {
+    async checkLimit(userId, hasPersonalKey) {
+        if (hasPersonalKey) {
+            return { ok: true, remaining: Infinity, topUpBalance: 0, totalAvailable: Infinity, useTopUp: false };
+        }
+        const doc = await _getLicenseDoc(userId);
+        if (!doc) {
+            // No license — free tier.
+            return { ok: false, remaining: 0, topUpBalance: 0, totalAvailable: 0, useTopUp: false, reason: 'no_subscription' };
+        }
+        const credits = doc.data['credits'] ?? {};
+        const monthlyIncluded = credits['monthlyIncluded'] ?? FREE_TIER_LIMIT;
+        const monthlyUsed = credits['monthlyUsed'] ?? 0;
+        const topUpBalance = credits['topUpBalance'] ?? 0;
+        const periodEnd = credits['periodEnd'];
+        if (_shouldReset(periodEnd)) {
+            await this._resetPeriod(doc);
+            return { ok: true, remaining: monthlyIncluded, topUpBalance, totalAvailable: monthlyIncluded + topUpBalance, useTopUp: false };
+        }
+        const remaining = Math.max(0, monthlyIncluded - monthlyUsed);
+        const totalAvailable = remaining + topUpBalance;
+        if (remaining > 0)
+            return { ok: true, remaining, topUpBalance, totalAvailable, useTopUp: false };
+        if (topUpBalance > 0)
+            return { ok: true, remaining: 0, topUpBalance, totalAvailable, useTopUp: true };
+        return { ok: false, remaining: 0, topUpBalance: 0, totalAvailable: 0, useTopUp: false, reason: 'limit_reached' };
+    }
+    async getUsage(userId) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc) {
+            return { currentPeriod: _currentPeriod(), periodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(), messagesUsed: 0, inputTokens: 0, outputTokens: 0, byModel: {}, lastUpdated: new Date().toISOString() };
+        }
+        const credits = doc.data['credits'] ?? {};
+        return {
+            currentPeriod: _currentPeriod(),
+            periodEnd: _toISO(credits['periodEnd']) ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+            messagesUsed: credits['monthlyUsed'] ?? 0,
+            inputTokens: credits['inputTokens'] ?? 0,
+            outputTokens: credits['outputTokens'] ?? 0,
+            byModel: credits['byModel'] ?? {},
+            lastUpdated: _toISO(credits['lastUpdated']) ?? new Date().toISOString(),
+        };
+    }
+    async getUsageStatus(userId, hasPersonalKey) {
+        const usage = await this.getUsage(userId);
+        const doc = await _getLicenseDoc(userId);
+        const credits = doc?.data['credits'] ?? {};
+        const topUpBalance = credits['topUpBalance'] ?? 0;
+        const monthlyIncluded = credits['monthlyIncluded'] ?? FREE_TIER_LIMIT;
+        const subscription = doc ? this._toSubscription(doc.data) : undefined;
+        if (hasPersonalKey) {
+            return { mode: 'byok', usage, limit: null, remaining: null, topUpBalance, totalAvailable: null, percentUsed: null, resetsAt: usage.periodEnd, estimatedCostUSD: _estimateCostUSD(usage.byModel), ...(subscription ? { subscription } : {}) };
+        }
+        const isSubscriber = subscription?.status === 'active' || subscription?.status === 'trialing';
+        const remaining = Math.max(0, monthlyIncluded - usage.messagesUsed);
+        const totalAvailable = remaining + topUpBalance;
+        const percentUsed = Math.round((usage.messagesUsed / monthlyIncluded) * 100);
+        return {
+            mode: isSubscriber ? 'included' : 'free',
+            usage,
+            limit: monthlyIncluded,
+            remaining,
+            topUpBalance,
+            totalAvailable,
+            percentUsed,
+            resetsAt: usage.periodEnd,
+            estimatedCostUSD: _estimateCostUSD(usage.byModel),
+            ...(subscription ? { subscription } : {}),
+            isFreeUser: !isSubscriber,
+        };
+    }
+    async incrementUsage(userId, inputTokens, outputTokens, model, useTopUp) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return; // No license doc — free tier, usage not tracked in Firestore.
+        const { FieldValue } = await _getFirestore();
+        const updates = {
+            'credits.monthlyUsed': FieldValue.increment(1),
+            'credits.inputTokens': FieldValue.increment(inputTokens),
+            'credits.outputTokens': FieldValue.increment(outputTokens),
+            [`credits.byModel.${model}.input`]: FieldValue.increment(inputTokens),
+            [`credits.byModel.${model}.output`]: FieldValue.increment(outputTokens),
+            'credits.lastUpdated': FieldValue.serverTimestamp(),
+            'updatedAt': FieldValue.serverTimestamp(),
+        };
+        if (useTopUp)
+            updates['credits.topUpBalance'] = FieldValue.increment(-1);
+        await doc.ref.update(updates);
+        _invalidateCache(userId);
+    }
+    async batchIncrementUsage(userId, batch) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return;
+        const { FieldValue } = await _getFirestore();
+        const updates = {
+            'credits.monthlyUsed': FieldValue.increment(batch.messageCount),
+            'credits.inputTokens': FieldValue.increment(batch.inputTokens),
+            'credits.outputTokens': FieldValue.increment(batch.outputTokens),
+            'credits.lastUpdated': FieldValue.serverTimestamp(),
+            'updatedAt': FieldValue.serverTimestamp(),
+        };
+        if (batch.topUpUsed > 0)
+            updates['credits.topUpBalance'] = FieldValue.increment(-batch.topUpUsed);
+        for (const [model, counts] of Object.entries(batch.byModel)) {
+            updates[`credits.byModel.${model}.input`] = FieldValue.increment(counts.input);
+            updates[`credits.byModel.${model}.output`] = FieldValue.increment(counts.output);
+        }
+        await doc.ref.update(updates);
+        _invalidateCache(userId);
+    }
+    async getSubscription(userId) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return undefined;
+        return this._toSubscription(doc.data);
+    }
+    async hasActiveSubscription(userId) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return false;
+        const status = doc.data['status'];
+        return status === 'active' || status === 'trialing';
+    }
+    async getTopUpBalance(userId) {
+        const doc = await _getLicenseDoc(userId);
+        if (!doc)
+            return 0;
+        const credits = doc.data['credits'] ?? {};
+        return credits['topUpBalance'] ?? 0;
+    }
+    async canAccessPaidFeature(userId) {
+        return this.hasActiveSubscription(userId);
+    }
+    // ── Internal helpers ────────────────────────────────────────────────────
+    _toSubscription(data) {
+        const status = data['status'];
+        if (!status)
+            return undefined;
+        const stripeCustomerId = data['stripeCustomerId'];
+        const stripeSubscriptionId = data['stripeSubscriptionId'];
+        const cancelAtPeriodEnd = data['cancelAtPeriodEnd'];
+        const giftedBy = data['giftedBy'];
+        const currentPeriodEnd = _toISO(data['credits']?.['periodEnd']);
+        const giftedAt = _toISO(data['giftedAt']);
+        const expiresAt = _toISO(data['expiresAt']);
+        const note = data['note'];
+        return {
+            plan: data['plan'] ?? 'standard',
+            status: status,
+            ...(stripeCustomerId ? { stripeCustomerId } : {}),
+            ...(stripeSubscriptionId ? { stripeSubscriptionId } : {}),
+            ...(currentPeriodEnd ? { currentPeriodEnd } : {}),
+            ...(cancelAtPeriodEnd !== undefined ? { cancelAtPeriodEnd } : {}),
+            ...(giftedBy ? { giftedBy } : {}),
+            ...(giftedAt ? { giftedAt } : {}),
+            ...(expiresAt ? { expiresAt } : {}),
+            ...(note ? { note } : {}),
+        };
+    }
+    async _resetPeriod(doc) {
+        const { FieldValue } = await _getFirestore();
+        const newPeriodEnd = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+        await doc.ref.update({
+            'credits.monthlyUsed': 0,
+            'credits.inputTokens': 0,
+            'credits.outputTokens': 0,
+            'credits.byModel': {},
+            'credits.periodStart': FieldValue.serverTimestamp(),
+            'credits.periodEnd': newPeriodEnd,
+            'credits.lastUpdated': FieldValue.serverTimestamp(),
+            'updatedAt': FieldValue.serverTimestamp(),
+        });
+        _invalidateCache(doc.docId);
+    }
+}
+//# sourceMappingURL=firestore-provider.js.map

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

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

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

@@ -0,0 +1,46 @@
+/**
+ * @module billing
+ * @description Factory for sdk.billing.* — usage metering, subscription management,
+ * top-up credits, and Stripe integration.
+ *
+ * **Provider selection:** The billing module automatically chooses the storage backend:
+ * - `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (production)
+ * - Not set → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
+ *
+ * **Usage metering:** Fire-and-forget via a 5-second write-behind buffer. Recording
+ * usage never blocks the AI response path.
+ *
+ * **Stripe integration:** Full subscription lifecycle — checkout sessions, customer
+ * portal, and subscription cancellation. Requires `STRIPE_SECRET_KEY`.
+ *
+ * @example
+ * ```typescript
+ * // Check credits and record usage around an AI call:
+ * const check = await sdk.billing.checkLimit(user.email, user.hasByok)
+ * if (!check.ok) return c.json({ error: 'Monthly limit reached' }, 402)
+ *
+ * const response = await sdk.ai.complete(...)
+ * sdk.billing.recordUsage(user.email, response.usage.inputTokens, response.usage.outputTokens, response.model)
+ * ```
+ */
+import type { BillingModule, BillingProvider } from './types.js';
+/**
+ * Options for `createBillingModule()`.
+ */
+export interface CreateBillingModuleOptions {
+    /**
+     * Override the billing provider directly.
+     * When not provided, the provider is selected from the environment:
+     * Firestore when `FIREBASE_SERVICE_ACCOUNT_KEY` is set, local otherwise.
+     */
+    provider?: BillingProvider;
+}
+/**
+ * Create the `sdk.billing.*` module.
+ *
+ * @param options - Optional provider override (primarily for testing).
+ * @returns A fully configured `BillingModule`.
+ */
+export declare function createBillingModule(options?: CreateBillingModuleOptions): BillingModule;
+export type { BillingModule, BillingPlanType, SubscriptionStatus, ModelUsage, UsageData, UsageStatus, SubscriptionData, LimitCheckResult, BatchIncrementData, CreateCheckoutSessionOptions, CreatePortalSessionOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAOhB,MAAM,YAAY,CAAA;AAMnB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B;AAgBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAuH3F;AAGD,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,YAAY,CAAA"}

package/dist/modules/billing/index.js

@@ -0,0 +1,149 @@
+/**
+ * @module billing
+ * @description Factory for sdk.billing.* — usage metering, subscription management,
+ * top-up credits, and Stripe integration.
+ *
+ * **Provider selection:** The billing module automatically chooses the storage backend:
+ * - `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (production)
+ * - Not set → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
+ *
+ * **Usage metering:** Fire-and-forget via a 5-second write-behind buffer. Recording
+ * usage never blocks the AI response path.
+ *
+ * **Stripe integration:** Full subscription lifecycle — checkout sessions, customer
+ * portal, and subscription cancellation. Requires `STRIPE_SECRET_KEY`.
+ *
+ * @example
+ * ```typescript
+ * // Check credits and record usage around an AI call:
+ * const check = await sdk.billing.checkLimit(user.email, user.hasByok)
+ * if (!check.ok) return c.json({ error: 'Monthly limit reached' }, 402)
+ *
+ * const response = await sdk.ai.complete(...)
+ * sdk.billing.recordUsage(user.email, response.usage.inputTokens, response.usage.outputTokens, response.model)
+ * ```
+ */
+import Stripe from 'stripe';
+import { LocalBillingProvider } from './local-provider.js';
+import { FirestoreBillingProvider } from './firestore-provider.js';
+import { UsageBuffer } from './usage-buffer.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Stripe helper
+// ─────────────────────────────────────────────────────────────────────────────
+function _getStripe() {
+    const key = process.env['STRIPE_SECRET_KEY'];
+    if (!key)
+        throw new Error('STRIPE_SECRET_KEY is not set — configure it to use Stripe billing features');
+    return new Stripe(key, { apiVersion: '2026-02-25.clover', typescript: true });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create the `sdk.billing.*` module.
+ *
+ * @param options - Optional provider override (primarily for testing).
+ * @returns A fully configured `BillingModule`.
+ */
+export function createBillingModule(options = {}) {
+    const provider = options.provider
+        ?? (process.env['FIREBASE_SERVICE_ACCOUNT_KEY']
+            ? new FirestoreBillingProvider()
+            : new LocalBillingProvider());
+    const buffer = new UsageBuffer(provider);
+    return {
+        // ── Usage metering ──────────────────────────────────────────────────────
+        async checkLimit(userId, hasPersonalKey) {
+            return provider.checkLimit(userId, hasPersonalKey);
+        },
+        recordUsage(userId, inputTokens, outputTokens, model) {
+            // The limit check told us whether to draw from top-up; for the buffer we
+            // default to false here — the billing provider tracks which messages used
+            // top-up internally via the LimitCheckResult.useTopUp flag returned to the
+            // caller. Products that need exact top-up tracking should call the provider
+            // directly via the flush path.
+            buffer.increment(userId, inputTokens, outputTokens, model, false);
+        },
+        async getUsage(userId) {
+            return provider.getUsage(userId);
+        },
+        async getUsageStatus(userId, hasPersonalKey) {
+            return provider.getUsageStatus(userId, hasPersonalKey);
+        },
+        // ── Subscription management ─────────────────────────────────────────────
+        async getSubscription(userId) {
+            return provider.getSubscription(userId);
+        },
+        async hasActiveSubscription(userId) {
+            return provider.hasActiveSubscription(userId);
+        },
+        async createCheckoutSession(options) {
+            const stripe = _getStripe();
+            const session = await stripe.checkout.sessions.create({
+                mode: 'subscription',
+                line_items: [{ price: options.priceId, quantity: 1 }],
+                success_url: options.successUrl,
+                cancel_url: options.cancelUrl,
+                ...(options.customerId ? { customer: options.customerId } : {}),
+                ...(options.customerEmail && !options.customerId ? { customer_email: options.customerEmail } : {}),
+            });
+            if (!session.url)
+                throw new Error('Stripe checkout session created but returned no URL');
+            return session.url;
+        },
+        async createPortalSession(options) {
+            const stripe = _getStripe();
+            const session = await stripe.billingPortal.sessions.create({
+                customer: options.customerId,
+                return_url: options.returnUrl,
+            });
+            return session.url;
+        },
+        async cancelSubscription(userId) {
+            const stripe = _getStripe();
+            const sub = await provider.getSubscription(userId);
+            if (!sub?.stripeSubscriptionId) {
+                throw new Error(`No active Stripe subscription found for user ${userId}`);
+            }
+            await stripe.subscriptions.update(sub.stripeSubscriptionId, { cancel_at_period_end: true });
+        },
+        // ── Top-up credits ───────────────────────────────────────────────────────
+        async getTopUpBalance(userId) {
+            return provider.getTopUpBalance(userId);
+        },
+        async addTopUp(userId, amount) {
+            // For the local provider, directly update the balance.
+            // For Firestore, we use a targeted increment to avoid race conditions.
+            if (provider instanceof LocalBillingProvider) {
+                const current = await provider.getTopUpBalance(userId);
+                const newBalance = current + amount;
+                await provider.setTopUpBalance(userId, newBalance);
+                return newBalance;
+            }
+            // Firestore: increment and then read the new balance.
+            if (provider instanceof FirestoreBillingProvider) {
+                await provider.batchIncrementUsage(userId, {
+                    messageCount: 0, inputTokens: 0, outputTokens: 0,
+                    topUpUsed: -amount, // Negative topUpUsed = add credits
+                    byModel: {},
+                });
+                return provider.getTopUpBalance(userId);
+            }
+            // Generic fallback for custom providers — not atomic but correct.
+            const current = await provider.getTopUpBalance(userId);
+            return current + amount;
+        },
+        // ── Feature gating ───────────────────────────────────────────────────────
+        async canAccessPaidFeature(userId) {
+            return provider.canAccessPaidFeature(userId);
+        },
+        // ── Lifecycle ────────────────────────────────────────────────────────────
+        async flush() {
+            await buffer.flush();
+        },
+        stopFlush() {
+            buffer.stop();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map