@nehorai/credits 1.0.0

package/dist/service/credits-service.js

@@ -0,0 +1,372 @@
+import { toDate } from "../core/types";
+import { toClientUserCredits } from "../repository/types";
+import { DEFAULT_FREE_CREDITS, RESERVATION_EXPIRY_MS, getMonthlyLimit } from "../config/costs";
+/**
+ * Check if a date is past the monthly reset date
+ */
+function isPastMonthlyReset(resetAt) {
+    if (!resetAt)
+        return false;
+    const resetDate = toDate(resetAt);
+    return new Date() >= resetDate;
+}
+/**
+ * Default grace period for subscription expiry (in days)
+ */
+const DEFAULT_GRACE_PERIOD_DAYS = 3;
+/**
+ * Credits service with dependency injection for repository
+ *
+ * Provides business logic for credit operations, delegating
+ * database operations to the injected repository.
+ */
+export class CreditsService {
+    repository;
+    lowBalanceCallback;
+    subscriptionExpiredCallback;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    /**
+     * Set callback for low balance notifications
+     */
+    setLowBalanceCallback(callback) {
+        this.lowBalanceCallback = callback;
+    }
+    /**
+     * Set callback for subscription expired notifications
+     */
+    setSubscriptionExpiredCallback(callback) {
+        this.subscriptionExpiredCallback = callback;
+    }
+    /**
+     * Get user credits, performing monthly reset and subscription expiry checks if needed
+     *
+     * This method uses atomic operations to prevent race conditions:
+     * 1. Checks subscription expiry with grace period
+     * 2. Atomically performs monthly reset if needed (with optimistic locking)
+     *
+     * @param userId - User ID
+     * @returns User credits or null if not found
+     */
+    async getUserCredits(userId) {
+        let data = await this.repository.getUserCredits(userId);
+        if (!data) {
+            return null;
+        }
+        // Step 1: Check subscription expiry (for non-free tiers)
+        if (data.tier !== "free" && data.subscriptionExpiresAt) {
+            const expiryResult = await this.repository.checkAndHandleSubscriptionExpiry(userId, DEFAULT_GRACE_PERIOD_DAYS);
+            if (expiryResult.wasDowngraded) {
+                // Create journal entry for downgrade
+                await this.repository.createJournalEntry({
+                    userId,
+                    entryType: "debit",
+                    amount: 0, // No credits deducted, just tier change
+                    balanceAfter: expiryResult.credits.balance,
+                    source: "subscription_downgrade",
+                    referenceId: `downgrade-${Date.now()}`,
+                    referenceType: "subscription",
+                    description: `Subscription expired. Downgraded from ${data.tier} to free tier.`,
+                    metadata: {
+                        previousTier: data.tier,
+                        previousBalance: data.balance,
+                        newBalance: expiryResult.credits.balance,
+                    },
+                });
+                // Trigger subscription expired notification (non-blocking)
+                if (this.subscriptionExpiredCallback) {
+                    this.subscriptionExpiredCallback(userId, true).catch((error) => {
+                        console.error("[Credits] Failed to send subscription expired notification:", error);
+                    });
+                }
+            }
+            // Use the potentially updated credits
+            data = expiryResult.credits;
+        }
+        // Step 2: Check if monthly reset is needed (use atomic operation)
+        if (isPastMonthlyReset(data.monthlyResetAt)) {
+            // Convert monthlyResetAt to a compatible type (Date or string)
+            const expectedResetAt = toDate(data.monthlyResetAt);
+            const resetResult = await this.repository.atomicMonthlyReset(userId, data.tier, expectedResetAt);
+            if (resetResult.wasReset) {
+                // Create journal entry for monthly reset
+                const balanceChange = resetResult.credits.balance - data.balance;
+                if (balanceChange !== 0) {
+                    await this.repository.createJournalEntry({
+                        userId,
+                        entryType: balanceChange > 0 ? "credit" : "debit",
+                        amount: Math.abs(balanceChange),
+                        balanceAfter: resetResult.credits.balance,
+                        source: "monthly_reset",
+                        referenceId: `reset-${Date.now()}`,
+                        referenceType: "reset",
+                        description: `Monthly credit reset for ${data.tier} tier.`,
+                        metadata: {
+                            tier: data.tier,
+                            previousBalance: data.balance,
+                            newBalance: resetResult.credits.balance,
+                        },
+                    });
+                }
+            }
+            // Use the potentially updated credits
+            data = resetResult.credits;
+        }
+        return toClientUserCredits(data);
+    }
+    /**
+     * Initialize credits for a new user with free tier
+     * @param userId - User ID
+     * @returns Initialized user credits
+     */
+    async initializeUserCredits(userId) {
+        const credits = await this.repository.initializeUserCredits(userId, "free", DEFAULT_FREE_CREDITS);
+        return toClientUserCredits(credits);
+    }
+    /**
+     * Get or create user credits
+     * Initializes with free tier if not exists
+     * @param userId - User ID
+     * @returns User credits
+     */
+    async getOrCreateUserCredits(userId) {
+        const existing = await this.getUserCredits(userId);
+        if (existing) {
+            return existing;
+        }
+        return this.initializeUserCredits(userId);
+    }
+    /**
+     * Check if user has sufficient credits for an operation
+     * @param userId - User ID
+     * @param requiredCredits - Credits required
+     * @returns Credit check result
+     */
+    async checkCredits(userId, requiredCredits) {
+        const credits = await this.getOrCreateUserCredits(userId);
+        // Available = balance + bonusCredits - reserved
+        const totalBalance = credits.balance + credits.bonusCredits;
+        const available = totalBalance - credits.reserved;
+        const hasCredits = available >= requiredCredits;
+        return {
+            hasCredits,
+            balance: totalBalance,
+            required: requiredCredits,
+            shortfall: hasCredits ? 0 : requiredCredits - available,
+        };
+    }
+    /**
+     * Reserve credits for an operation (phase 1 of two-phase commit)
+     * Creates a reservation and locks the credits
+     * @param userId - User ID
+     * @param amount - Credits to reserve
+     * @param operationType - Operation type for tracking
+     * @returns Reservation object
+     * @throws Error if insufficient credits
+     */
+    async reserveCredits(userId, amount, operationType) {
+        const expiresAt = new Date(Date.now() + RESERVATION_EXPIRY_MS);
+        return this.repository.reserveCreditsAtomic(userId, amount, operationType, expiresAt);
+    }
+    /**
+     * Commit a reservation (phase 2 of two-phase commit - success)
+     * Deducts credits and marks reservation as committed
+     * Also triggers low balance notifications if balance drops below threshold
+     */
+    async commitCredits(userId, reservationId) {
+        // Get the reservation to know the amount
+        const reservation = await this.repository.getReservation(userId, reservationId);
+        if (!reservation) {
+            throw new Error(`Reservation ${reservationId} not found`);
+        }
+        // Commit the reservation atomically
+        await this.repository.commitReservationAtomic(userId, reservationId);
+        // Create journal entry
+        const credits = await this.repository.getUserCredits(userId);
+        if (credits) {
+            await this.repository.createJournalEntry({
+                userId,
+                entryType: "debit",
+                amount: reservation.amount,
+                balanceAfter: credits.balance,
+                source: "operation_commit",
+                referenceId: reservationId,
+                referenceType: "reservation",
+                description: `Committed ${reservation.amount} credits for ${reservation.operationType}`,
+                metadata: {
+                    operationType: reservation.operationType,
+                },
+            });
+            // Trigger low balance notification (non-blocking)
+            if (this.lowBalanceCallback) {
+                this.lowBalanceCallback(userId, credits.balance).catch((error) => {
+                    console.error("[Credits] Failed to send low balance notification:", error);
+                });
+            }
+        }
+    }
+    /**
+     * Release a reservation (phase 2 of two-phase commit - failure)
+     * Returns reserved credits and marks reservation as released
+     */
+    async releaseCredits(userId, reservationId) {
+        // Get the reservation to check its state
+        const reservation = await this.repository.getReservation(userId, reservationId);
+        // Release the reservation atomically
+        await this.repository.releaseReservationAtomic(userId, reservationId);
+        // Create journal entry only if reservation was in reserved state
+        if (reservation?.status === "reserved") {
+            const credits = await this.repository.getUserCredits(userId);
+            if (credits) {
+                await this.repository.createJournalEntry({
+                    userId,
+                    entryType: "credit",
+                    amount: 0, // No actual credits returned (they were reserved, not spent)
+                    balanceAfter: credits.balance,
+                    source: "operation_release",
+                    referenceId: reservationId,
+                    referenceType: "reservation",
+                    description: `Released ${reservation.amount} reserved credits for ${reservation.operationType}`,
+                    metadata: {
+                        operationType: reservation.operationType,
+                        amount: reservation.amount,
+                    },
+                });
+            }
+        }
+    }
+    /**
+     * Log usage for audit trail
+     * @param log - Usage log data
+     */
+    async logUsage(log) {
+        await this.repository.logUsage(log);
+    }
+    /**
+     * Add credits to user account (for purchases, bonuses, etc.)
+     * @param userId - User ID
+     * @param amount - Credits to add
+     * @param description - Transaction description
+     * @param paymentRef - Optional payment reference
+     */
+    async addCredits(userId, amount, description, paymentRef) {
+        return this.repository.addCreditsAtomic(userId, amount, description, paymentRef);
+    }
+    /**
+     * Update user subscription tier
+     * @param userId - User ID
+     * @param tier - New subscription tier
+     * @param expiresAt - Subscription expiry date (optional)
+     */
+    async updateTier(userId, tier, expiresAt) {
+        const monthlyLimit = getMonthlyLimit(tier);
+        await this.repository.updateUserTier(userId, {
+            tier,
+            monthlyLimit: monthlyLimit === Infinity ? 0 : monthlyLimit,
+            // Reset balance to new tier limit if upgrading
+            balance: tier !== "free"
+                ? (monthlyLimit === Infinity ? 999999 : monthlyLimit)
+                : undefined,
+            monthlyUsed: tier !== "free" ? 0 : undefined,
+            subscriptionExpiresAt: expiresAt ? expiresAt.toISOString() : null,
+        });
+    }
+    /**
+     * Get usage logs with optional filtering
+     * @param userId - Optional user ID filter
+     * @param limit - Max results
+     * @param offset - Skip results
+     * @returns List of usage logs
+     */
+    async getUsageLogs(userId, limit = 50, offset = 0) {
+        return this.repository.getUsageLogs({ userId, limit, offset });
+    }
+    /**
+     * Get user-friendly usage history
+     * Combines journal entries into a user-facing format
+     *
+     * @param userId - User ID
+     * @param limit - Max results per page
+     * @param offset - Skip results for pagination
+     * @returns Paginated usage history response
+     */
+    async getUsageHistory(userId, limit = 20, offset = 0) {
+        // Get journal entries
+        const [entries, total] = await Promise.all([
+            this.repository.getJournalEntries({ userId, limit, offset }),
+            this.repository.getJournalEntriesCount({ userId }),
+        ]);
+        // Convert journal entries to user-friendly format
+        const historyEntries = entries.map((entry) => {
+            const type = this.mapSourceToHistoryType(entry.source);
+            const creditsChange = entry.entryType === "credit" ? entry.amount : -entry.amount;
+            return {
+                id: entry.id,
+                type,
+                creditsChange,
+                balanceAfter: entry.balanceAfter,
+                description: entry.description,
+                createdAt: typeof entry.createdAt === "string"
+                    ? entry.createdAt
+                    : toDate(entry.createdAt).toISOString(),
+            };
+        });
+        return {
+            entries: historyEntries,
+            pagination: {
+                total,
+                limit,
+                offset,
+                hasMore: offset + entries.length < total,
+            },
+        };
+    }
+    /**
+     * Map journal entry source to user-friendly history type
+     */
+    mapSourceToHistoryType(source) {
+        switch (source) {
+            case "operation_commit":
+            case "reservation_expired":
+                return "usage";
+            case "purchase":
+                return "purchase";
+            case "subscription_grant":
+            case "subscription_upgrade":
+            case "bonus":
+                return "bonus";
+            case "monthly_reset":
+                return "reset";
+            case "refund":
+            case "operation_release":
+                return "refund";
+            case "admin_adjustment":
+            case "subscription_downgrade":
+            case "expiry":
+            default:
+                return "adjustment";
+        }
+    }
+    /**
+     * Get journal entries directly (for admin or debugging)
+     * @param query - Journal entry query parameters
+     * @returns List of journal entries
+     */
+    async getJournalEntries(query) {
+        return this.repository.getJournalEntries(query);
+    }
+    /**
+     * Get the underlying repository (for advanced use cases)
+     */
+    getRepository() {
+        return this.repository;
+    }
+}
+/**
+ * Create a credits service with a repository
+ */
+export function createCreditsService(repository) {
+    return new CreditsService(repository);
+}
+//# sourceMappingURL=credits-service.js.map

package/dist/service/credits-service.js.map

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

package/dist/service/index.d.ts

@@ -0,0 +1,3 @@
+export { CreditsService, createCreditsService, } from "./credits-service";
+export type { LowBalanceNotificationCallback, SubscriptionExpiredNotificationCallback, } from "./credits-service";
+//# sourceMappingURL=index.d.ts.map

package/dist/service/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,8BAA8B,EAC9B,uCAAuC,GACxC,MAAM,mBAAmB,CAAC"}

package/dist/service/index.js

@@ -0,0 +1,2 @@
+export { CreditsService, createCreditsService, } from "./credits-service";
+//# sourceMappingURL=index.js.map

package/dist/service/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,GACrB,MAAM,mBAAmB,CAAC"}

package/dist/utils/error-utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Credit error utilities
+ *
+ * Provides functions to parse and identify credit-related errors
+ * for consistent error handling across the application.
+ */
+/**
+ * Parsed information from a credit error message
+ */
+export interface CreditErrorInfo {
+    /** Credits currently available */
+    available: number;
+    /** Credits required for the operation */
+    required: number;
+    /** Difference between required and available */
+    shortfall: number;
+    /** Original error message */
+    rawMessage: string;
+}
+/**
+ * Parse a credit error message to extract available/required credits
+ *
+ * @param error - Error message string
+ * @returns Parsed credit info or null if not a valid credit error format
+ *
+ * @example
+ * ```ts
+ * const error = "Insufficient credits. Available: 3, Required: 10";
+ * const info = parseCreditError(error);
+ * // { available: 3, required: 10, shortfall: 7, rawMessage: "..." }
+ * ```
+ */
+export declare function parseCreditError(error: string): CreditErrorInfo | null;
+/**
+ * Check if an error message is a credit-related error
+ *
+ * @param error - Error message string
+ * @returns true if the error is credit-related
+ *
+ * @example
+ * ```ts
+ * if (isCreditError(error)) {
+ *   showCreditErrorDialog(parseCreditError(error));
+ * }
+ * ```
+ */
+export declare function isCreditErrorMessage(error: string): boolean;
+//# sourceMappingURL=error-utils.d.ts.map

package/dist/utils/error-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAsBtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAM3D"}

package/dist/utils/error-utils.js

@@ -0,0 +1,57 @@
+/**
+ * Credit error utilities
+ *
+ * Provides functions to parse and identify credit-related errors
+ * for consistent error handling across the application.
+ */
+/**
+ * Parse a credit error message to extract available/required credits
+ *
+ * @param error - Error message string
+ * @returns Parsed credit info or null if not a valid credit error format
+ *
+ * @example
+ * ```ts
+ * const error = "Insufficient credits. Available: 3, Required: 10";
+ * const info = parseCreditError(error);
+ * // { available: 3, required: 10, shortfall: 7, rawMessage: "..." }
+ * ```
+ */
+export function parseCreditError(error) {
+    // Pattern: Available: X, Required: Y (case insensitive, flexible whitespace)
+    const match = error.match(/Available:\s*(\d+)\s*,\s*Required:\s*(\d+)/i);
+    if (!match) {
+        return null;
+    }
+    const available = parseInt(match[1], 10);
+    const required = parseInt(match[2], 10);
+    // Validate parsed numbers
+    if (isNaN(available) || isNaN(required)) {
+        return null;
+    }
+    return {
+        available,
+        required,
+        shortfall: required - available,
+        rawMessage: error,
+    };
+}
+/**
+ * Check if an error message is a credit-related error
+ *
+ * @param error - Error message string
+ * @returns true if the error is credit-related
+ *
+ * @example
+ * ```ts
+ * if (isCreditError(error)) {
+ *   showCreditErrorDialog(parseCreditError(error));
+ * }
+ * ```
+ */
+export function isCreditErrorMessage(error) {
+    const lowerError = error.toLowerCase();
+    return (lowerError.includes("insufficient credits") ||
+        lowerError.includes("not enough credits"));
+}
+//# sourceMappingURL=error-utils.js.map

package/dist/utils/error-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.js","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,6EAA6E;IAC7E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAEzE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAExC,0BAA0B;IAC1B,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,SAAS;QACT,QAAQ;QACR,SAAS,EAAE,QAAQ,GAAG,SAAS;QAC/B,UAAU,EAAE,KAAK;KAClB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACvC,OAAO,CACL,UAAU,CAAC,QAAQ,CAAC,sBAAsB,CAAC;QAC3C,UAAU,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAC1C,CAAC;AACJ,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Credit utility functions
+ *
+ * Common helper functions for credit calculations
+ */
+import type { PortableReservation } from "../core";
+export { parseCreditError, isCreditErrorMessage, type CreditErrorInfo, } from "./error-utils";
+/**
+ * Calculate total available credits from balance and bonus credits
+ *
+ * @param credits - Object containing balance and bonusCredits properties
+ * @returns Total credits (balance + bonusCredits)
+ *
+ * @example
+ * ```ts
+ * const total = getTotalCredits({ balance: 100, bonusCredits: 50 });
+ * // Returns 150
+ * ```
+ */
+export declare function getTotalCredits(credits: {
+    balance: number;
+    bonusCredits: number;
+}): number;
+/**
+ * Generate a unique request ID
+ *
+ * Format: req_{timestamp}_{randomPart}
+ * Example: req_1706234567890_a1b2c3d4e5f6
+ *
+ * @returns URL-safe request ID string
+ */
+export declare function generateRequestId(): string;
+/**
+ * Check if the input data indicates preview mode
+ *
+ * Preview mode skips actual credit deduction - used for dry runs
+ * and UI previews where the user wants to see results without committing.
+ *
+ * @param data - The input data to check
+ * @returns true if data has preview: true
+ */
+export declare function isPreviewMode(data: unknown): boolean;
+/**
+ * Create a dummy reservation for preview mode
+ *
+ * Used when `isPreviewMode(data)` returns true to provide
+ * a valid reservation object without actual credit operations.
+ *
+ * @param userId - The user ID
+ * @param operationType - The operation type
+ * @returns A dummy PortableReservation with id "preview-mode"
+ */
+export declare function createDummyReservation(userId: string, operationType: string): PortableReservation;
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAOpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,mBAAmB,CAWrB"}

package/dist/utils/index.js

@@ -0,0 +1,72 @@
+/**
+ * Credit utility functions
+ *
+ * Common helper functions for credit calculations
+ */
+export { parseCreditError, isCreditErrorMessage, } from "./error-utils";
+/**
+ * Calculate total available credits from balance and bonus credits
+ *
+ * @param credits - Object containing balance and bonusCredits properties
+ * @returns Total credits (balance + bonusCredits)
+ *
+ * @example
+ * ```ts
+ * const total = getTotalCredits({ balance: 100, bonusCredits: 50 });
+ * // Returns 150
+ * ```
+ */
+export function getTotalCredits(credits) {
+    return credits.balance + credits.bonusCredits;
+}
+/**
+ * Generate a unique request ID
+ *
+ * Format: req_{timestamp}_{randomPart}
+ * Example: req_1706234567890_a1b2c3d4e5f6
+ *
+ * @returns URL-safe request ID string
+ */
+export function generateRequestId() {
+    const timestamp = Date.now();
+    const randomPart = Math.random().toString(36).substring(2, 14);
+    return `req_${timestamp}_${randomPart}`;
+}
+/**
+ * Check if the input data indicates preview mode
+ *
+ * Preview mode skips actual credit deduction - used for dry runs
+ * and UI previews where the user wants to see results without committing.
+ *
+ * @param data - The input data to check
+ * @returns true if data has preview: true
+ */
+export function isPreviewMode(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        "preview" in data &&
+        data.preview === true);
+}
+/**
+ * Create a dummy reservation for preview mode
+ *
+ * Used when `isPreviewMode(data)` returns true to provide
+ * a valid reservation object without actual credit operations.
+ *
+ * @param userId - The user ID
+ * @param operationType - The operation type
+ * @returns A dummy PortableReservation with id "preview-mode"
+ */
+export function createDummyReservation(userId, operationType) {
+    const now = new Date().toISOString();
+    return {
+        id: "preview-mode",
+        userId,
+        amount: 0,
+        operationType,
+        status: "released",
+        createdAt: now,
+        expiresAt: now,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,GAErB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,OAG/B;IACC,OAAO,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/D,OAAO,OAAO,SAAS,IAAI,UAAU,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,SAAS,IAAI,IAAI;QAChB,IAAgC,CAAC,OAAO,KAAK,IAAI,CACnD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,aAAqB;IAErB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO;QACL,EAAE,EAAE,cAAc;QAClB,MAAM;QACN,MAAM,EAAE,CAAC;QACT,aAAa;QACb,MAAM,EAAE,UAAU;QAClB,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,GAAG;KACf,CAAC;AACJ,CAAC"}