@lastbrain/module-ai 2.0.26 → 2.0.30

package/dist/server/quota.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Server-side quota management functions
+ * Handles monthly token quota (separate from purchased tokens)
+ */
+import type { TokenQuotaStatus, DebitTokensResponse, UpdateQuotaRequest } from "../types/quota";
+/**
+ * Get user's current quota status
+ */
+export declare function getUserQuotaStatus(userId: string): Promise<TokenQuotaStatus>;
+/**
+ * Debit tokens with priority: quota first, then purchased
+ * This is the CENTRAL function for token consumption
+ */
+export declare function debitTokensWithPriority(userId: string, tokensToDebit: number, model?: string, prompt?: string, meta?: Record<string, unknown>): Promise<DebitTokensResponse>;
+/**
+ * Update or create user quota (for subscription updates/renewals)
+ */
+export declare function updateUserQuota(request: UpdateQuotaRequest): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Handle subscription update from billing-pro webhook
+ * This function is called by billing-pro when subscription events occur
+ *
+ * @param params Subscription parameters from Stripe
+ * @returns Success status
+ */
+export declare function handleSubscriptionQuotaUpdate(params: {
+    owner_id: string;
+    plan_slug: string;
+    subscription_id: string | null;
+    current_period_start: string;
+    current_period_end: string;
+}): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Update custom quota for a user (admin override)
+ */
+export declare function updateCustomQuota(userId: string, customTokens: number | null): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Get quota usage history for a user
+ */
+export declare function getQuotaUsageHistory(userId: string, limit?: number, offset?: number): Promise<any[]>;
+/**
+ * Refund/credit tokens back to user in case of error after debit
+ * This ensures users don't lose tokens if the operation fails after AI generation
+ *
+ * @param userId User ID
+ * @param tokensToRefund Number of tokens to credit back
+ * @param model Model that was used (for logging)
+ * @param reason Reason for the refund (for logging)
+ * @returns Success status with refund details
+ */
+export declare function refundTokens(userId: string, tokensToRefund: number, model: string, reason: string): Promise<{
+    success: boolean;
+    error?: string;
+    refundedToQuota: number;
+    refundedToPurchased: number;
+}>;
+//# sourceMappingURL=quota.d.ts.map

package/dist/server/quota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/server/quota.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAEV,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAEnB,MAAM,gBAAgB,CAAC;AAWxB;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC,CA0E3B;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,mBAAmB,CAAC,CA+Q9B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAwC/C;AAED;;;;;;GAMG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0DhD;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0C/C;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,kBAkBnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,CAAC,CAgHD"}

package/dist/server/quota.js

@@ -0,0 +1,538 @@
+/**
+ * Server-side quota management functions
+ * Handles monthly token quota (separate from purchased tokens)
+ */
+import { getSupabaseServiceClient } from "@lastbrain/core/server";
+import { logger } from "@lastbrain/core";
+// Import default quotas
+const PLAN_DEFAULTS = {
+    free: 0,
+    pro: 50000,
+    premium: 100000,
+    enterprise: 150000,
+};
+/**
+ * Get user's current quota status
+ */
+export async function getUserQuotaStatus(userId) {
+    const supabase = await getSupabaseServiceClient();
+    try {
+        // Get the most recent quota record (not .single() to avoid PGRST116 error)
+        const { data, error } = await supabase
+            .from("user_token_quota_monthly")
+            .select("*")
+            .eq("owner_id", userId)
+            .order("created_at", { ascending: false })
+            .limit(1);
+        if (error) {
+            logger.debug(`[getUserQuotaStatus] Query error: ${error.code} - ${error.message}`);
+        }
+        // Take the first (most recent) record
+        const record = data?.[0];
+        if (!record) {
+            return {
+                hasQuota: false,
+                plan: "free",
+                effectiveQuota: 0,
+                usedQuota: 0,
+                remainingQuota: 0,
+                periodStart: null,
+                periodEnd: null,
+                isActive: false,
+            };
+        }
+        const quota = record;
+        const now = new Date();
+        const periodStart = quota.period_start
+            ? new Date(quota.period_start)
+            : null;
+        const periodEnd = quota.period_end ? new Date(quota.period_end) : null;
+        // Check if within period
+        const isActive = periodStart && periodEnd && now >= periodStart && now <= periodEnd;
+        const result = {
+            hasQuota: quota.effective_included_tokens > 0,
+            plan: quota.plan,
+            effectiveQuota: quota.effective_included_tokens,
+            usedQuota: quota.used_included_tokens,
+            remainingQuota: Math.max(0, quota.effective_included_tokens - quota.used_included_tokens),
+            periodStart: quota.period_start,
+            periodEnd: quota.period_end,
+            isActive: !!isActive,
+        };
+        return result;
+    }
+    catch (error) {
+        logger.error("[getUserQuotaStatus] Error:", error);
+        return {
+            hasQuota: false,
+            plan: "free",
+            effectiveQuota: 0,
+            usedQuota: 0,
+            remainingQuota: 0,
+            periodStart: null,
+            periodEnd: null,
+            isActive: false,
+        };
+    }
+}
+/**
+ * Debit tokens with priority: quota first, then purchased
+ * This is the CENTRAL function for token consumption
+ */
+export async function debitTokensWithPriority(userId, tokensToDebit, model, prompt, meta = {}) {
+    logger.debug(`[debitTokensWithPriority] START for user ${userId}: tokensToDebit=${tokensToDebit}, model=${model}`);
+    if (tokensToDebit <= 0) {
+        logger.warn(`[debitTokensWithPriority] Invalid amount: ${tokensToDebit}`);
+        return {
+            success: false,
+            debitedFromQuota: 0,
+            debitedFromPurchased: 0,
+            remainingQuota: 0,
+            remainingPurchased: 0,
+            error: "Le montant doit être positif",
+        };
+    }
+    const supabase = await getSupabaseServiceClient();
+    try {
+        // Step 1: Get quota status
+        const quotaStatus = await getUserQuotaStatus(userId);
+        logger.debug(`[debitTokensWithPriority] Quota status:`, {
+            hasQuota: quotaStatus.hasQuota,
+            plan: quotaStatus.plan,
+            effectiveQuota: quotaStatus.effectiveQuota,
+            usedQuota: quotaStatus.usedQuota,
+            remainingQuota: quotaStatus.remainingQuota,
+            isActive: quotaStatus.isActive,
+            periodStart: quotaStatus.periodStart,
+            periodEnd: quotaStatus.periodEnd,
+        });
+        let debitedFromQuota = 0;
+        let debitedFromPurchased = 0;
+        let tokensRemaining = tokensToDebit;
+        // Step 2: Try to debit from quota first (if active and available)
+        if (quotaStatus.isActive && quotaStatus.remainingQuota > 0) {
+            debitedFromQuota = Math.min(tokensRemaining, quotaStatus.remainingQuota);
+            tokensRemaining -= debitedFromQuota;
+            logger.debug(`[debitTokensWithPriority] Debiting from quota: ${debitedFromQuota} tokens (remaining to debit: ${tokensRemaining})`);
+            // Update quota usage
+            const { data: quotaData, error: quotaError } = await supabase
+                .from("user_token_quota_monthly")
+                .update({
+                used_included_tokens: quotaStatus.usedQuota + debitedFromQuota,
+            })
+                .eq("owner_id", userId)
+                .select()
+                .single();
+            if (quotaError) {
+                logger.error("[debitTokensWithPriority] Quota update error:", quotaError);
+                throw new Error("Erreur lors de la mise à jour du quota");
+            }
+            logger.debug(`[debitTokensWithPriority] Quota updated successfully:`, quotaData);
+            // Log quota usage
+            if (debitedFromQuota > 0 &&
+                quotaStatus.periodStart &&
+                quotaStatus.periodEnd) {
+                // Truncate prompt to 32 characters for GDPR compliance
+                const truncatedPrompt = prompt ? prompt.substring(0, 32) : null;
+                logger.debug(`[debitTokensWithPriority] Inserting to user_token_quota_ledger:`, {
+                    owner_id: userId,
+                    tokens_used: debitedFromQuota,
+                    model,
+                    period_start: quotaStatus.periodStart,
+                    period_end: quotaStatus.periodEnd,
+                });
+                const { data: ledgerData, error: ledgerInsertError } = await supabase
+                    .from("user_token_quota_ledger")
+                    .insert({
+                    owner_id: userId,
+                    tokens_used: debitedFromQuota,
+                    model,
+                    prompt: truncatedPrompt,
+                    period_start: quotaStatus.periodStart,
+                    period_end: quotaStatus.periodEnd,
+                    meta,
+                })
+                    .select();
+                if (ledgerInsertError) {
+                    logger.error("[debitTokensWithPriority] Ledger insert error:", ledgerInsertError);
+                    throw new Error("Erreur lors de l'insertion en ledger quota");
+                }
+                logger.debug(`[debitTokensWithPriority] Ledger insertion successful:`, ledgerData);
+            }
+            else {
+                logger.debug(`[debitTokensWithPriority] Skipped ledger insertion: debitedFromQuota=${debitedFromQuota}, periodStart=${quotaStatus.periodStart}, periodEnd=${quotaStatus.periodEnd}`);
+            }
+        }
+        else {
+            logger.debug(`[debitTokensWithPriority] Skipped quota debit: isActive=${quotaStatus.isActive}, remainingQuota=${quotaStatus.remainingQuota}`);
+        }
+        // Step 3: Debit remaining from purchased tokens (if any)
+        if (tokensRemaining > 0) {
+            logger.debug(`[debitTokensWithPriority] Need to debit from purchased: ${tokensRemaining} tokens`);
+            // Check purchased balance
+            const { data: balanceData } = await supabase
+                .from("user_token_balance_v")
+                .select("balance")
+                .eq("owner_id", userId)
+                .single();
+            const purchasedBalance = balanceData?.balance || 0;
+            logger.debug(`[debitTokensWithPriority] Purchased balance: ${purchasedBalance}`);
+            if (purchasedBalance < tokensRemaining) {
+                logger.warn(`[debitTokensWithPriority] Purchased tokens insufficient: balance=${purchasedBalance}, required=${tokensRemaining}`);
+                // If the caller explicitly allows an overdraft (one-time negative balance), proceed
+                const allowOverdraft = Boolean(meta?.allowOverdraft);
+                if (!allowOverdraft) {
+                    return {
+                        success: false,
+                        debitedFromQuota,
+                        debitedFromPurchased: 0,
+                        remainingQuota: quotaStatus.remainingQuota - debitedFromQuota,
+                        remainingPurchased: purchasedBalance,
+                        error: `Tokens insuffisants. Quota: ${quotaStatus.remainingQuota}, Achetés: ${purchasedBalance}, Requis: ${tokensToDebit}`,
+                    };
+                }
+                logger.debug(`[debitTokensWithPriority] allowOverdraft=true, proceeding to insert negative ledger entry`);
+                // continue and insert the ledger entry below which will make the balance negative
+            }
+            // Debit from purchased
+            logger.debug(`[debitTokensWithPriority] Inserting to user_token_ledger: ${tokensRemaining} tokens`);
+            // Truncate prompt to 32 characters for GDPR compliance
+            const truncatedPrompt = prompt ? prompt.substring(0, 32) : null;
+            // Insert ledger entry for purchased tokens. Use try/catch and fallback
+            // to a minimal insert if the full insert fails (to avoid blocking generation).
+            let insertData = null;
+            try {
+                const res = await supabase
+                    .from("user_token_ledger")
+                    .insert({
+                    owner_id: userId,
+                    type: "use",
+                    amount: -tokensRemaining,
+                    model,
+                    prompt: truncatedPrompt,
+                    meta,
+                })
+                    .select();
+                insertData = res.data;
+                if (res.error)
+                    throw res.error;
+            }
+            catch (err) {
+                logger.error("[debitTokensWithPriority] Ledger insert failed (full payload):", err);
+                // Retry with minimal payload (avoid meta or potentially invalid fields)
+                try {
+                    const res2 = await supabase
+                        .from("user_token_ledger")
+                        .insert({
+                        owner_id: userId,
+                        type: "use",
+                        amount: -tokensRemaining,
+                        model,
+                    })
+                        .select();
+                    insertData = res2.data;
+                    if (res2.error)
+                        throw res2.error;
+                    logger.debug("[debitTokensWithPriority] Purchased tokens debited with fallback insert:", insertData);
+                }
+                catch (err2) {
+                    logger.error("[debitTokensWithPriority] Ledger insert fallback failed:", err2);
+                    return {
+                        success: false,
+                        debitedFromQuota,
+                        debitedFromPurchased: 0,
+                        remainingQuota: quotaStatus.remainingQuota - debitedFromQuota,
+                        remainingPurchased: purchasedBalance,
+                        error: (err2 && err2.message) ||
+                            "Erreur lors du débit des tokens achetés (ledger insert)",
+                    };
+                }
+            }
+            logger.debug(`[debitTokensWithPriority] Purchased tokens debited successfully:`, insertData);
+            debitedFromPurchased = tokensRemaining;
+        }
+        else {
+            logger.debug(`[debitTokensWithPriority] No purchased tokens to debit`);
+        }
+        // Step 4: Get final balances
+        const finalQuotaStatus = await getUserQuotaStatus(userId);
+        const { data: finalBalanceData } = await supabase
+            .from("user_token_balance_v")
+            .select("balance")
+            .eq("owner_id", userId)
+            .single();
+        const result = {
+            success: true,
+            debitedFromQuota,
+            debitedFromPurchased,
+            remainingQuota: finalQuotaStatus.remainingQuota,
+            remainingPurchased: finalBalanceData?.balance || 0,
+        };
+        logger.debug(`[debitTokensWithPriority] SUCCESS:`, result);
+        return result;
+    }
+    catch (error) {
+        logger.error("[debitTokensWithPriority] FATAL ERROR:", error);
+        return {
+            success: false,
+            debitedFromQuota: 0,
+            debitedFromPurchased: 0,
+            remainingQuota: 0,
+            remainingPurchased: 0,
+            error: error.message || "Erreur lors du débit des tokens",
+        };
+    }
+}
+/**
+ * Update or create user quota (for subscription updates/renewals)
+ */
+export async function updateUserQuota(request) {
+    const supabase = await getSupabaseServiceClient();
+    try {
+        const defaultTokens = PLAN_DEFAULTS[request.plan] || 0;
+        const effectiveTokens = request.custom_included_tokens ?? defaultTokens;
+        const quotaData = {
+            owner_id: request.owner_id,
+            plan: request.plan,
+            default_included_tokens: defaultTokens,
+            custom_included_tokens: request.custom_included_tokens ?? null,
+            effective_included_tokens: effectiveTokens,
+            period_start: request.period_start,
+            period_end: request.period_end,
+            subscription_id: request.subscription_id || null,
+            source: "stripe",
+        };
+        // Reset usage if requested
+        if (request.reset_usage) {
+            quotaData.used_included_tokens = 0;
+        }
+        const { error } = await supabase
+            .from("user_token_quota_monthly")
+            .upsert(quotaData, {
+            onConflict: "owner_id",
+        });
+        if (error) {
+            logger.error("[updateUserQuota] Error:", error);
+            return { success: false, error: error.message };
+        }
+        return { success: true };
+    }
+    catch (error) {
+        logger.error("[updateUserQuota] Error:", error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Handle subscription update from billing-pro webhook
+ * This function is called by billing-pro when subscription events occur
+ *
+ * @param params Subscription parameters from Stripe
+ * @returns Success status
+ */
+export async function handleSubscriptionQuotaUpdate(params) {
+    const { owner_id, plan_slug, subscription_id, current_period_start, current_period_end, } = params;
+    logger.debug(`[handleSubscriptionQuotaUpdate] Processing for user ${owner_id}, plan ${plan_slug}`);
+    try {
+        // Map plan slug to plan type
+        // Note: Starter plan receives same 100K token quota as Pro plan
+        const planMapping = {
+            pro: "pro",
+            premium: "premium",
+            enterprise: "enterprise",
+            starter: "pro", // Starter plans receive Pro quota (100K tokens/month)
+            free: "free",
+        };
+        const planType = planMapping[plan_slug.toLowerCase()] || "free";
+        // Check if there's an existing custom quota
+        const supabase = await getSupabaseServiceClient();
+        const { data: existingQuota } = await supabase
+            .from("user_token_quota_monthly")
+            .select("custom_included_tokens")
+            .eq("owner_id", owner_id)
+            .single();
+        // Update quota with period reset
+        const result = await updateUserQuota({
+            owner_id,
+            plan: planType,
+            custom_included_tokens: existingQuota?.custom_included_tokens ?? null,
+            period_start: current_period_start,
+            period_end: current_period_end,
+            subscription_id,
+            reset_usage: true, // Reset used tokens on renewal
+        });
+        if (!result.success) {
+            logger.error(`[handleSubscriptionQuotaUpdate] Failed: ${result.error}`);
+            return result;
+        }
+        logger.debug(`[handleSubscriptionQuotaUpdate] Success for user ${owner_id}`);
+        return { success: true };
+    }
+    catch (error) {
+        logger.error("[handleSubscriptionQuotaUpdate] Error:", error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Update custom quota for a user (admin override)
+ */
+export async function updateCustomQuota(userId, customTokens) {
+    const supabase = await getSupabaseServiceClient();
+    try {
+        // Get current quota
+        const { data: currentQuota, error: fetchError } = await supabase
+            .from("user_token_quota_monthly")
+            .select("*")
+            .eq("owner_id", userId)
+            .single();
+        if (fetchError && fetchError.code !== "PGRST116") {
+            return { success: false, error: fetchError.message };
+        }
+        if (!currentQuota) {
+            return {
+                success: false,
+                error: "Aucun quota trouvé pour cet utilisateur",
+            };
+        }
+        const defaultTokens = PLAN_DEFAULTS[currentQuota.plan] || 0;
+        const effectiveTokens = customTokens ?? defaultTokens;
+        const { error } = await supabase
+            .from("user_token_quota_monthly")
+            .update({
+            custom_included_tokens: customTokens,
+            effective_included_tokens: effectiveTokens,
+        })
+            .eq("owner_id", userId);
+        if (error) {
+            return { success: false, error: error.message };
+        }
+        return { success: true };
+    }
+    catch (error) {
+        logger.error("[updateCustomQuota] Error:", error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Get quota usage history for a user
+ */
+export async function getQuotaUsageHistory(userId, limit = 50, offset = 0) {
+    const supabase = await getSupabaseServiceClient();
+    try {
+        const { data, error } = await supabase
+            .from("user_token_quota_ledger")
+            .select("*")
+            .eq("owner_id", userId)
+            .order("created_at", { ascending: false })
+            .range(offset, offset + limit - 1);
+        if (error)
+            throw error;
+        return data || [];
+    }
+    catch (error) {
+        logger.error("[getQuotaUsageHistory] Error:", error);
+        return [];
+    }
+}
+/**
+ * Refund/credit tokens back to user in case of error after debit
+ * This ensures users don't lose tokens if the operation fails after AI generation
+ *
+ * @param userId User ID
+ * @param tokensToRefund Number of tokens to credit back
+ * @param model Model that was used (for logging)
+ * @param reason Reason for the refund (for logging)
+ * @returns Success status with refund details
+ */
+export async function refundTokens(userId, tokensToRefund, model, reason) {
+    logger.debug(`[refundTokens] START for user ${userId}: tokensToRefund=${tokensToRefund}, model=${model}, reason=${reason}`);
+    if (tokensToRefund <= 0) {
+        return {
+            success: true,
+            refundedToQuota: 0,
+            refundedToPurchased: 0,
+        };
+    }
+    const supabase = await getSupabaseServiceClient();
+    try {
+        let refundedToQuota = 0;
+        let refundedToPurchased = 0;
+        let remainingToRefund = tokensToRefund;
+        // 1. Check if user has active quota that was debited
+        const quotaStatus = await getUserQuotaStatus(userId);
+        if (quotaStatus.hasQuota && quotaStatus.isActive) {
+            const { data: quotaData } = await supabase
+                .from("user_token_quota_monthly")
+                .select("used_included_tokens, effective_included_tokens")
+                .eq("owner_id", userId)
+                .single();
+            if (quotaData && quotaData.used_included_tokens > 0) {
+                // Calculate how much to refund to quota (cannot exceed what was used)
+                const maxQuotaRefund = Math.min(remainingToRefund, quotaData.used_included_tokens);
+                if (maxQuotaRefund > 0) {
+                    const newUsed = quotaData.used_included_tokens - maxQuotaRefund;
+                    const { error: quotaError } = await supabase
+                        .from("user_token_quota_monthly")
+                        .update({ used_included_tokens: newUsed })
+                        .eq("owner_id", userId);
+                    if (quotaError) {
+                        logger.error("[refundTokens] Quota refund error:", quotaError);
+                    }
+                    else {
+                        refundedToQuota = maxQuotaRefund;
+                        remainingToRefund -= maxQuotaRefund;
+                        logger.debug(`[refundTokens] Refunded ${maxQuotaRefund} tokens to quota`);
+                        // Log quota refund
+                        await supabase.from("user_token_quota_ledger").insert({
+                            owner_id: userId,
+                            tokens_used: -maxQuotaRefund, // Negative = refund
+                            model,
+                            prompt: `REFUND: ${reason.substring(0, 32)}`,
+                            period_start: quotaStatus.periodStart,
+                            period_end: quotaStatus.periodEnd,
+                            meta: { refund: true, reason },
+                        });
+                    }
+                }
+            }
+        }
+        // 2. Refund remaining to purchased tokens
+        if (remainingToRefund > 0) {
+            const { error: ledgerError } = await supabase
+                .from("user_token_ledger")
+                .insert({
+                owner_id: userId,
+                type: "refund",
+                amount: remainingToRefund, // Positive = credit
+                model,
+                prompt: `REFUND: ${reason.substring(0, 32)}`,
+                meta: { refund: true, reason },
+            });
+            if (ledgerError) {
+                logger.error("[refundTokens] Ledger refund error:", ledgerError);
+            }
+            else {
+                refundedToPurchased = remainingToRefund;
+                logger.debug(`[refundTokens] Refunded ${remainingToRefund} tokens to purchased balance`);
+            }
+        }
+        logger.debug("[refundTokens] SUCCESS:", {
+            refundedToQuota,
+            refundedToPurchased,
+            total: refundedToQuota + refundedToPurchased,
+        });
+        return {
+            success: true,
+            refundedToQuota,
+            refundedToPurchased,
+        };
+    }
+    catch (error) {
+        logger.error("[refundTokens] Error:", error);
+        return {
+            success: false,
+            error: error.message,
+            refundedToQuota: 0,
+            refundedToPurchased: 0,
+        };
+    }
+}

package/dist/server/wallet-repair.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Wallet Repair Utilities
+ * For fixing wallets that were not initialized correctly (legacy credits, manual edits, etc.)
+ */
+/**
+ * Recalculate wallet budget from ledger history
+ * Useful for users who have tokens but wallet = 0 USD
+ */
+export declare function repairUserWallet(userId: string, tokenBalance?: number): Promise<{
+    success: boolean;
+    error?: string;
+    before?: {
+        balance: number;
+        providerBudget: number;
+        sellValue: number;
+    };
+    after?: {
+        balance: number;
+        providerBudget: number;
+        sellValue: number;
+    };
+}>;
+/**
+ * Repair all wallets in the system
+ */
+export declare function repairAllWallets(): Promise<{
+    success: boolean;
+    repaired: number;
+    failed: number;
+    errors: string[];
+}>;
+//# sourceMappingURL=wallet-repair.d.ts.map

package/dist/server/wallet-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-repair.d.ts","sourceRoot":"","sources":["../../src/server/wallet-repair.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE,CAAC,CAgKD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CA4DD"}