@nehorai/credits 1.7.0 → 2.0.0

package/dist/{types-CjLj3GW5.d.cts → types-DJ8yqaVr.d.cts}

@@ -122,6 +122,20 @@ interface PortableReservation {
     expiresAt: string;
     /** When reservation was committed/released - ISO 8601 or undefined */
     completedAt?: string;
+    /**
+     * Caller-supplied idempotency key (V2). Absent on legacy reservations.
+     * Unique per user; a replay with the same key returns this same reservation.
+     */
+    idempotencyKey?: string;
+    /**
+     * When the atomic reserve placed this hold - ISO 8601, or absent.
+     *
+     * Written by `reserveCreditsV2` inside the same transaction that increases
+     * `reserved`, so its presence is proof that the hold exists. `createReservation`
+     * never sets it, and the V2 transitions refuse to move a row without it.
+     * See `assertHoldPlaced` in `core/reservation-integrity.ts`.
+     */
+    holdPlacedAt?: string;
 }
 /**
  * Result of a credit check operation
@@ -165,6 +179,15 @@ interface MonthlyResetResult {
     wasReset: boolean;
     /** The user credits after the operation */
     credits: PortableUserCredits;
+    /**
+     * `true` when the repository wrote the reset's journal entry inside the same
+     * atomic step as the balance write. The service then skips its own journal
+     * call — a separate call sits outside the reset's atomicity, and if it fails
+     * after the CAS was consumed, the line is lost for good (no retry ever sees
+     * the reset again). Absent/`false` means the repository did not journal and
+     * the service falls back to the legacy non-atomic write.
+     */
+    journaled?: boolean;
 }
 /**
  * Result of subscription expiry check
@@ -178,6 +201,16 @@ interface SubscriptionExpiryResult {
     graceDaysRemaining: number;
     /** The user credits after the operation */
     credits: PortableUserCredits;
+    /**
+     * `true` when the repository wrote the downgrade's journal entry inside the
+     * same atomic step as the tier write. The service then skips its own journal
+     * call — a separate call sits outside the downgrade's atomicity, and if it
+     * fails after the tier write committed, the account is downgraded with no
+     * audit line and no retry ever fires (the row is no longer eligible).
+     * Absent/`false` means the repository did not journal and the service falls
+     * back to the legacy non-atomic write.
+     */
+    journaled?: boolean;
 }
 /**
  * Credit transaction type
@@ -229,6 +262,11 @@ interface PortableJournalEntry {
     description: string;
     /** Additional metadata */
     metadata?: Record<string, unknown>;
+    /**
+     * Deterministic key that makes this entry unique per user (V2). Absent on
+     * legacy entries; present entries cannot be written twice.
+     */
+    idempotencyKey?: string;
     /** When this entry was created - ISO 8601 */
     createdAt: string;
 }
@@ -308,4 +346,4 @@ interface WithCreditsOptions {
     resourceType?: ResourceType;
 }
 
-export { type AIProviderType as A, type BuiltinTier as B, type CreditSource as C, type DeductCreditsResult as D, type JournalReferenceType as J, type MonthlyResetResult as M, type PortableTransaction as P, type ReservationStatus as R, type SubscriptionTier as S, type TierConfig as T, type UsageHistoryEntry as U, type WithCreditsOptions as W, type CreditOperationType as a, type PortableUserCredits as b, type PortableReservation as c, type PortableUsageLog as d, type SubscriptionExpiryResult as e, type PortableJournalEntry as f, type CreditCheckResult as g, type ResourceType as h, type TransactionType as i, type UsageHistoryResponse as j, calculateAvailableCredits as k, toPortableTimestamp as l, toDate as t };
+export { type AIProviderType as A, type BuiltinTier as B, type CreditOperationType as C, type DeductCreditsResult as D, type JournalReferenceType as J, type MonthlyResetResult as M, type PortableTransaction as P, type ReservationStatus as R, type SubscriptionTier as S, type TierConfig as T, type UsageHistoryEntry as U, type WithCreditsOptions as W, type PortableReservation as a, type CreditSource as b, type PortableUserCredits as c, type PortableUsageLog as d, type SubscriptionExpiryResult as e, type PortableJournalEntry as f, type CreditCheckResult as g, type ResourceType as h, type TransactionType as i, type UsageHistoryResponse as j, calculateAvailableCredits as k, toPortableTimestamp as l, toDate as t };

package/dist/{types-CjLj3GW5.d.ts → types-DJ8yqaVr.d.ts}

@@ -122,6 +122,20 @@ interface PortableReservation {
     expiresAt: string;
     /** When reservation was committed/released - ISO 8601 or undefined */
     completedAt?: string;
+    /**
+     * Caller-supplied idempotency key (V2). Absent on legacy reservations.
+     * Unique per user; a replay with the same key returns this same reservation.
+     */
+    idempotencyKey?: string;
+    /**
+     * When the atomic reserve placed this hold - ISO 8601, or absent.
+     *
+     * Written by `reserveCreditsV2` inside the same transaction that increases
+     * `reserved`, so its presence is proof that the hold exists. `createReservation`
+     * never sets it, and the V2 transitions refuse to move a row without it.
+     * See `assertHoldPlaced` in `core/reservation-integrity.ts`.
+     */
+    holdPlacedAt?: string;
 }
 /**
  * Result of a credit check operation
@@ -165,6 +179,15 @@ interface MonthlyResetResult {
     wasReset: boolean;
     /** The user credits after the operation */
     credits: PortableUserCredits;
+    /**
+     * `true` when the repository wrote the reset's journal entry inside the same
+     * atomic step as the balance write. The service then skips its own journal
+     * call — a separate call sits outside the reset's atomicity, and if it fails
+     * after the CAS was consumed, the line is lost for good (no retry ever sees
+     * the reset again). Absent/`false` means the repository did not journal and
+     * the service falls back to the legacy non-atomic write.
+     */
+    journaled?: boolean;
 }
 /**
  * Result of subscription expiry check
@@ -178,6 +201,16 @@ interface SubscriptionExpiryResult {
     graceDaysRemaining: number;
     /** The user credits after the operation */
     credits: PortableUserCredits;
+    /**
+     * `true` when the repository wrote the downgrade's journal entry inside the
+     * same atomic step as the tier write. The service then skips its own journal
+     * call — a separate call sits outside the downgrade's atomicity, and if it
+     * fails after the tier write committed, the account is downgraded with no
+     * audit line and no retry ever fires (the row is no longer eligible).
+     * Absent/`false` means the repository did not journal and the service falls
+     * back to the legacy non-atomic write.
+     */
+    journaled?: boolean;
 }
 /**
  * Credit transaction type
@@ -229,6 +262,11 @@ interface PortableJournalEntry {
     description: string;
     /** Additional metadata */
     metadata?: Record<string, unknown>;
+    /**
+     * Deterministic key that makes this entry unique per user (V2). Absent on
+     * legacy entries; present entries cannot be written twice.
+     */
+    idempotencyKey?: string;
     /** When this entry was created - ISO 8601 */
     createdAt: string;
 }
@@ -308,4 +346,4 @@ interface WithCreditsOptions {
     resourceType?: ResourceType;
 }
 
-export { type AIProviderType as A, type BuiltinTier as B, type CreditSource as C, type DeductCreditsResult as D, type JournalReferenceType as J, type MonthlyResetResult as M, type PortableTransaction as P, type ReservationStatus as R, type SubscriptionTier as S, type TierConfig as T, type UsageHistoryEntry as U, type WithCreditsOptions as W, type CreditOperationType as a, type PortableUserCredits as b, type PortableReservation as c, type PortableUsageLog as d, type SubscriptionExpiryResult as e, type PortableJournalEntry as f, type CreditCheckResult as g, type ResourceType as h, type TransactionType as i, type UsageHistoryResponse as j, calculateAvailableCredits as k, toPortableTimestamp as l, toDate as t };
+export { type AIProviderType as A, type BuiltinTier as B, type CreditOperationType as C, type DeductCreditsResult as D, type JournalReferenceType as J, type MonthlyResetResult as M, type PortableTransaction as P, type ReservationStatus as R, type SubscriptionTier as S, type TierConfig as T, type UsageHistoryEntry as U, type WithCreditsOptions as W, type PortableReservation as a, type CreditSource as b, type PortableUserCredits as c, type PortableUsageLog as d, type SubscriptionExpiryResult as e, type PortableJournalEntry as f, type CreditCheckResult as g, type ResourceType as h, type TransactionType as i, type UsageHistoryResponse as j, calculateAvailableCredits as k, toPortableTimestamp as l, toDate as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nehorai/credits",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/dist/types-DFe5BoJY.d.cts

@@ -1,329 +0,0 @@
-import { C as CreditSource, J as JournalReferenceType, a as CreditOperationType, P as PortableTransaction, A as AIProviderType, S as SubscriptionTier, b as PortableUserCredits, c as PortableReservation, R as ReservationStatus, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-CjLj3GW5.cjs';
-
-/**
- * Input for creating a credit reservation
- */
-interface CreateReservationInput {
-    userId: string;
-    amount: number;
-    operationType: CreditOperationType;
-    expiresAt: Date;
-}
-/**
- * Input for creating a credit transaction
- */
-interface CreateTransactionInput {
-    userId: string;
-    type: PortableTransaction["type"];
-    amount: number;
-    description: string;
-    paymentRef?: string;
-    previousBalance: number;
-    newBalance: number;
-}
-/**
- * Input for logging usage
- */
-interface CreateUsageLogInput {
-    userId: string;
-    operationType: CreditOperationType;
-    provider: AIProviderType;
-    creditsUsed: number;
-    success: boolean;
-    errorMessage?: string;
-    resourceId?: string;
-    resourceType?: string;
-    requestId?: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Query options for usage logs
- */
-interface UsageLogQuery {
-    userId?: string;
-    operationType?: CreditOperationType;
-    success?: boolean;
-    limit?: number;
-    offset?: number;
-    startDate?: Date;
-    endDate?: Date;
-}
-/**
- * Input for creating a journal entry
- */
-interface CreateJournalEntryInput {
-    userId: string;
-    entryType: "debit" | "credit";
-    amount: number;
-    balanceAfter: number;
-    source: CreditSource;
-    referenceId: string;
-    referenceType: JournalReferenceType;
-    description: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Query options for journal entries
- */
-interface JournalEntryQuery {
-    userId: string;
-    source?: CreditSource;
-    referenceType?: JournalReferenceType;
-    limit?: number;
-    offset?: number;
-    startDate?: Date;
-    endDate?: Date;
-}
-/**
- * Partial update for user credits balance
- */
-interface CreditBalanceUpdate {
-    balance?: number;
-    bonusCredits?: number;
-    reserved?: number;
-    tier?: SubscriptionTier;
-    monthlyLimit?: number;
-    monthlyUsed?: number;
-    monthlyResetAt?: Date | string;
-    subscriptionExpiresAt?: Date | string | null;
-    /** Increment balance by this amount (alternative to absolute value) */
-    balanceIncrement?: number;
-    /** Increment bonusCredits by this amount (alternative to absolute value) */
-    bonusCreditsIncrement?: number;
-    /** Increment reserved by this amount (alternative to absolute value) */
-    reservedIncrement?: number;
-    /** Increment monthlyUsed by this amount */
-    monthlyUsedIncrement?: number;
-}
-/**
- * Input for tier update
- */
-interface TierUpdateInput {
-    tier: SubscriptionTier;
-    monthlyLimit: number;
-    balance?: number;
-    monthlyUsed?: number;
-    subscriptionExpiresAt?: Date | string | null;
-}
-/**
- * Optional journal customization for `addCreditsAtomic`.
- *
- * By default a credit add records a journal entry with `source: "purchase"`,
- * `referenceType: "transaction"`, and `{ paymentRef }` metadata. These options
- * let callers override that — e.g. tag a signup grant as `source: "bonus"`, or
- * carry revenue-attribution fields (gross amount, credits granted) so a single
- * journal can serve as the app's revenue ledger.
- */
-interface AddCreditsAtomicOptions {
-    /** Journal entry source (defaults to `"purchase"`). */
-    source?: CreditSource;
-    /** Journal reference type (defaults to `"transaction"`). */
-    referenceType?: JournalReferenceType;
-    /**
-     * Extra metadata merged onto the journal entry. When `paymentRef` is present
-     * it is merged in too (explicit keys here win on collision).
-     */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Repository interface for credits database operations
- *
- * Implementations can use any database (Firestore, PostgreSQL, etc.)
- * All methods should handle their own error handling and transactions
- */
-interface ICreditRepository {
-    /**
-     * Get user credits balance
-     * @param userId - User ID
-     * @returns User credits or null if not found
-     */
-    getUserCredits(userId: string): Promise<PortableUserCredits | null>;
-    /**
-     * Initialize credits for a new user
-     * @param userId - User ID
-     * @param tier - Initial subscription tier
-     * @param initialBalance - Initial credit balance
-     * @returns Initialized user credits
-     */
-    initializeUserCredits(userId: string, tier: SubscriptionTier, initialBalance: number): Promise<PortableUserCredits>;
-    /**
-     * Update user credits balance
-     * @param userId - User ID
-     * @param updates - Partial updates to apply
-     */
-    updateUserCredits(userId: string, updates: CreditBalanceUpdate): Promise<void>;
-    /**
-     * Update user subscription tier
-     * @param userId - User ID
-     * @param input - Tier update data
-     */
-    updateUserTier(userId: string, input: TierUpdateInput): Promise<void>;
-    /**
-     * Create a credit reservation (phase 1 of two-phase commit)
-     * @param input - Reservation data
-     * @returns Created reservation
-     */
-    createReservation(input: CreateReservationInput): Promise<PortableReservation>;
-    /**
-     * Get a reservation by ID
-     * @param userId - User ID
-     * @param reservationId - Reservation ID
-     * @returns Reservation or null
-     */
-    getReservation(userId: string, reservationId: string): Promise<PortableReservation | null>;
-    /**
-     * Update reservation status
-     * @param userId - User ID
-     * @param reservationId - Reservation ID
-     * @param status - New status
-     * @param completedAt - Completion timestamp
-     */
-    updateReservationStatus(userId: string, reservationId: string, status: ReservationStatus, completedAt?: Date): Promise<void>;
-    /**
-     * Reserve credits atomically (creates reservation + updates balance in transaction)
-     * @param userId - User ID
-     * @param amount - Credits to reserve
-     * @param operationType - Operation type for tracking
-     * @param expiresAt - Reservation expiry time
-     * @returns Created reservation
-     * @throws Error if insufficient credits
-     */
-    reserveCreditsAtomic(userId: string, amount: number, operationType: CreditOperationType, expiresAt: Date): Promise<PortableReservation>;
-    /**
-     * Commit a reservation atomically (deducts credits + marks reservation committed)
-     * @param userId - User ID
-     * @param reservationId - Reservation ID
-     * @throws Error if reservation not found or not in reserved state
-     */
-    commitReservationAtomic(userId: string, reservationId: string): Promise<void>;
-    /**
-     * Release a reservation atomically (releases reserved credits + marks reservation released)
-     * @param userId - User ID
-     * @param reservationId - Reservation ID
-     */
-    releaseReservationAtomic(userId: string, reservationId: string): Promise<void>;
-    /**
-     * Add credits atomically (creates transaction + updates balance)
-     * @param userId - User ID
-     * @param amount - Credits to add
-     * @param description - Transaction description
-     * @param paymentRef - Optional payment reference
-     * @param options - Optional journal source / reference type / extra metadata
-     *   for the credit journal entry (e.g. revenue attribution fields). Lets
-     *   callers record a purchase's gross amount, a bonus/refund source, etc.,
-     *   instead of the default `source: "purchase"` + `{ paymentRef }` metadata.
-     */
-    addCreditsAtomic(userId: string, amount: number, description: string, paymentRef?: string, options?: AddCreditsAtomicOptions): Promise<void>;
-    /**
-     * Deduct credits from a user's balance atomically.
-     *
-     * Splits the deduction across `balance` and `bonusCredits`, draining
-     * `balance` (monthly, resets each cycle) first so persistent bonus
-     * credits survive longer. Runs in a single atomic transaction so
-     * concurrent deducts cannot drive either field negative.
-     *
-     * Callers are responsible for writing any audit record (journal /
-     * transaction) — this method only moves credits.
-     *
-     * @param userId - User ID
-     * @param amount - Credits to deduct (positive)
-     * @returns Combined totals (balance + bonusCredits) before and after.
-     * @throws If user has no credits doc or insufficient credits
-     */
-    deductCreditsAtomic(userId: string, amount: number): Promise<{
-        previousBalance: number;
-        newBalance: number;
-    }>;
-    /**
-     * Create a credit transaction record
-     * @param input - Transaction data
-     * @returns Created transaction
-     */
-    createTransaction(input: CreateTransactionInput): Promise<PortableTransaction>;
-    /**
-     * Get user's transaction history
-     * @param userId - User ID
-     * @param limit - Max results
-     * @param offset - Skip results
-     * @returns List of transactions
-     */
-    getTransactions(userId: string, limit?: number, offset?: number): Promise<PortableTransaction[]>;
-    /**
-     * Log a usage event
-     * @param input - Usage log data
-     * @returns Created usage log
-     */
-    logUsage(input: CreateUsageLogInput): Promise<PortableUsageLog>;
-    /**
-     * Query usage logs
-     * @param query - Query parameters
-     * @returns List of usage logs
-     */
-    getUsageLogs(query: UsageLogQuery): Promise<PortableUsageLog[]>;
-    /**
-     * Get usage log count (for pagination)
-     * @param query - Query parameters (without limit/offset)
-     * @returns Count of matching logs
-     */
-    getUsageLogsCount(query: Omit<UsageLogQuery, "limit" | "offset">): Promise<number>;
-    /**
-     * Find and expire reservations past their expiration time
-     * Used by cron job to clean up stale reservations
-     * @param batchSize - Maximum number of reservations to process per batch (default: 100)
-     * @param maxIterations - Maximum number of pagination iterations to prevent infinite loops (default: 100)
-     * @returns Cleanup results with counts and errors
-     */
-    findAndExpireReservations(batchSize?: number, maxIterations?: number): Promise<{
-        expiredCount: number;
-        creditsReleased: number;
-        errors: string[];
-    }>;
-    /**
-     * Atomically perform monthly reset if needed
-     * Uses optimistic locking to prevent race conditions
-     *
-     * @param userId - User ID
-     * @param tier - User's current subscription tier (for determining new balance)
-     * @param expectedResetAt - The expected monthlyResetAt value (for optimistic locking)
-     * @returns Result indicating whether reset was performed and updated credits
-     */
-    atomicMonthlyReset(userId: string, tier: SubscriptionTier, expectedResetAt: Date | string): Promise<MonthlyResetResult>;
-    /**
-     * Check and handle subscription expiry with grace period
-     * Auto-downgrades expired subscriptions after grace period
-     *
-     * @param userId - User ID
-     * @param gracePeriodDays - Days to allow after expiry before downgrade (default: 3)
-     * @returns Result indicating whether downgrade occurred
-     */
-    checkAndHandleSubscriptionExpiry(userId: string, gracePeriodDays?: number): Promise<SubscriptionExpiryResult>;
-    /**
-     * Create a journal entry for audit trail
-     * @param input - Journal entry data
-     * @returns Created journal entry
-     */
-    createJournalEntry(input: CreateJournalEntryInput): Promise<PortableJournalEntry>;
-    /**
-     * Get journal entries for a user
-     * @param query - Query parameters
-     * @returns List of journal entries
-     */
-    getJournalEntries(query: JournalEntryQuery): Promise<PortableJournalEntry[]>;
-    /**
-     * Get journal entry count for pagination
-     * @param query - Query parameters (without limit/offset)
-     * @returns Count of matching entries
-     */
-    getJournalEntriesCount(query: Omit<JournalEntryQuery, "limit" | "offset">): Promise<number>;
-}
-/**
- * Factory type for creating repository instances
- */
-type CreditRepositoryFactory = () => ICreditRepository;
-/**
- * Convert PortableUserCredits to client-safe format
- * Utility function that implementations can use
- */
-declare function toClientUserCredits(credits: PortableUserCredits): PortableUserCredits;
-
-export { type AddCreditsAtomicOptions as A, type CreateJournalEntryInput as C, type ICreditRepository as I, type JournalEntryQuery as J, type TierUpdateInput as T, type UsageLogQuery as U, type CreateReservationInput as a, type CreateTransactionInput as b, type CreateUsageLogInput as c, type CreditBalanceUpdate as d, type CreditRepositoryFactory as e, toClientUserCredits as t };