@nehorai/credits 2.2.0 → 3.1.0

package/dist/{types-3c-IAwZI.d.ts → types-BL3YqxUD.d.ts}

@@ -1,4 +1,4 @@
-import { P as PortableTransaction, a as PortableReservation, R as ReservationStatus, C as CreditOperationType, b as CreditSource, J as JournalReferenceType, A as AIProviderType, S as SubscriptionTier, c as PortableUserCredits, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-MaViK5tD.js';
+import { P as PortableTransaction, a as PortableReservation, R as ReservationStatus, C as CreditOperationType, b as CreditSource, J as JournalReferenceType, A as AIProviderType, S as SubscriptionTier, c as PortableUserCredits, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-C3sxDvNb.js';
 
 /**
  * Typed outcomes for the V2 reservation boundary.
@@ -326,7 +326,10 @@ interface CreateJournalEntryInput {
     userId: string;
     entryType: "debit" | "credit";
     amount: number;
+    /** `balance + bonusCredits` after this entry. */
     balanceAfter: number;
+    /** `balance + bonusCredits` before this entry. */
+    balanceBefore?: number;
     source: CreditSource;
     referenceId: string;
     referenceType: JournalReferenceType;
@@ -335,6 +338,18 @@ interface CreateJournalEntryInput {
     /** Deterministic key making this entry unique per user (V2, optional). */
     idempotencyKey?: string;
 }
+/**
+ * The journal entry of a one-shot deduct, written in the deduct's own atomic step.
+ */
+interface DeductJournalInput {
+    referenceId: string;
+    description: string;
+    /** Defaults to `"operation_commit"`. */
+    source?: CreditSource;
+    /** Defaults to `"adjustment"`. */
+    referenceType?: JournalReferenceType;
+    metadata?: Record<string, unknown>;
+}
 /**
  * Query options for journal entries
  */
@@ -354,6 +369,7 @@ interface CreditBalanceUpdate {
     balance?: number;
     bonusCredits?: number;
     reserved?: number;
+    /** Writes no journal line. To change a tier, use `updateUserTier`. */
     tier?: SubscriptionTier;
     monthlyLimit?: number;
     monthlyUsed?: number;
@@ -446,7 +462,9 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      */
     getUserCredits(userId: string): Promise<PortableUserCredits | null>;
     /**
-     * Initialize credits for a new user
+     * Initialize credits for a new user. Creating an account with a balance above 0
+     * writes its journal line (`signupGrantJournalInput`) in the same atomic step, and
+     * a call that finds the account writes nothing.
      * @param userId - User ID
      * @param tier - Initial subscription tier
      * @param initialBalance - Initial credit balance
@@ -454,13 +472,16 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      */
     initializeUserCredits(userId: string, tier: SubscriptionTier, initialBalance: number): Promise<PortableUserCredits>;
     /**
-     * Update user credits balance
+     * Patch fields of the account. This writes no journal line, whatever it changes.
+     * A tier change goes through `updateUserTier`, which journals a balance it moves.
      * @param userId - User ID
      * @param updates - Partial updates to apply
      */
     updateUserCredits(userId: string, updates: CreditBalanceUpdate): Promise<void>;
     /**
-     * Update user subscription tier
+     * Update user subscription tier. A write that moves the balance writes one journal
+     * line (`tierChangeJournalInput`) in the same atomic step, and one that does not
+     * writes none.
      * @param userId - User ID
      * @param input - Tier update data
      */
@@ -556,9 +577,10 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      * @returns Combined totals (balance + bonusCredits) before and after.
      * @throws If user has no credits doc or insufficient credits
      */
-    deductCreditsAtomic(userId: string, amount: number): Promise<{
+    deductCreditsAtomic(userId: string, amount: number, journal?: DeductJournalInput): Promise<{
         previousBalance: number;
         newBalance: number;
+        journalEntryId?: string;
     }>;
     /**
      * Create a credit transaction *record* — no balance moves.
@@ -678,4 +700,4 @@ declare function supportsIdempotentCredit(repository: ICreditRepository): reposi
  */
 declare function toClientUserCredits(credits: PortableUserCredits): PortableUserCredits;
 
-export { type AddCreditsAtomicOptions as A, type CommitOutcome as C, type ExpireOutcome as E, type ICreditRepository as I, type JournalEntryQuery as J, type ReleaseOutcome as R, type TerminalReservationStatus as T, type UsageLogQuery as U, type AddCreditsOutcome as a, type AddCreditsV2Input as b, type CreateJournalEntryInput as c, type CreateReservationInput as d, type CreateTransactionInput as e, type CreateUsageLogInput as f, type CreditBalanceUpdate as g, type CreditPolicyOptions as h, type CreditRepositoryFactory as i, type ExpireReservationV2Options as j, type ICreditRepositoryCreditsV2 as k, type ICreditRepositoryV2 as l, type ReservationTransitionOptions as m, type ReserveCreditsV2Input as n, type ReserveOutcome as o, type TierUpdateInput as p, isCreditedOutcome as q, isReservedOutcome as r, isWinningOutcome as s, reservationJournalKey as t, supportsCreditsV2 as u, supportsIdempotentCredit as v, toClientUserCredits as w };
+export { type AddCreditsAtomicOptions as A, type CommitOutcome as C, type DeductJournalInput as D, type ExpireOutcome as E, type ICreditRepository as I, type JournalEntryQuery as J, type ReleaseOutcome as R, type TerminalReservationStatus as T, type UsageLogQuery as U, type AddCreditsOutcome as a, type AddCreditsV2Input as b, type CreateJournalEntryInput as c, type CreateReservationInput as d, type CreateTransactionInput as e, type CreateUsageLogInput as f, type CreditBalanceUpdate as g, type CreditPolicyOptions as h, type CreditRepositoryFactory as i, type ExpireReservationV2Options as j, type ICreditRepositoryCreditsV2 as k, type ICreditRepositoryV2 as l, type ReservationTransitionOptions as m, type ReserveCreditsV2Input as n, type ReserveOutcome as o, type TierUpdateInput as p, isCreditedOutcome as q, isReservedOutcome as r, isWinningOutcome as s, reservationJournalKey as t, supportsCreditsV2 as u, supportsIdempotentCredit as v, toClientUserCredits as w };

package/dist/{types-MaViK5tD.d.cts → types-C3sxDvNb.d.cts}

@@ -99,6 +99,11 @@ interface PortableUserCredits {
      * Absent means 0. See `planBalanceCap`.
      */
     expiredHoldBacking?: number;
+    /**
+     * Where those credits end among the open holds, so a hold's share needs no write
+     * to the hold. Internal to the repositories: `toClientUserCredits` drops it.
+     */
+    expiredBackingFrontier?: ExpiredBackingFrontier | null;
     /**
      * Set when the account was created with a signup-grant claim: the amount
      * granted, 0 when the claim was already taken. Absent on any other account.
@@ -109,6 +114,21 @@ interface PortableUserCredits {
     /** Last update timestamp - ISO 8601 */
     updatedAt: string;
 }
+/**
+ * The newest open hold carrying marked credits (`expiredHoldBacking`).
+ *
+ * Credits are marked oldest hold first, so a single point describes every share:
+ * a hold older than this carries its full amount, this hold carries `share`, and a
+ * newer one carries nothing. A marked credit leaves the balance when its hold closes,
+ * however it closes. See `allocateExpiredBacking` and `holdExpiredBacking`.
+ */
+interface ExpiredBackingFrontier {
+    /** The hold's `holdPlacedAt`. */
+    holdPlacedAt: string;
+    /** The hold's id, which orders holds placed in the same millisecond. */
+    id: string;
+    share: number;
+}
 /**
  * Credit reservation status for two-phase commit
  */
@@ -148,10 +168,8 @@ interface PortableReservation {
      */
     holdPlacedAt?: string;
     /**
-     * The part of this hold backed by credits that expired while it was open, and so
-     * leave the balance when it closes, however it closes. Absent means 0, as on every
-     * hold placed after the expiry. Open holds' shares sum to the account's
-     * `expiredHoldBacking`.
+     * This hold's share of the marked credits, stored by 2.2.0. A hold placed since carries
+     * none and takes its share from the account's frontier. See `holdExpiredBacking`.
      */
     expiredBacking?: number;
 }
@@ -268,8 +286,13 @@ interface PortableJournalEntry {
     entryType: "debit" | "credit";
     /** Amount of credits involved */
     amount: number;
-    /** Balance after this entry */
+    /** `balance + bonusCredits` after this entry */
     balanceAfter: number;
+    /**
+     * `balance + bonusCredits` before this entry, read in the same atomic step.
+     * Absent on entries written before 3.0.0.
+     */
+    balanceBefore?: number;
     /** Source of the credit change */
     source: CreditSource;
     /** Reference ID (e.g., reservationId, transactionId) */
@@ -368,4 +391,4 @@ interface WithCreditsOptions {
     resourceType?: ResourceType;
 }
 
-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 };
+export { type AIProviderType as A, type BuiltinTier as B, type CreditOperationType as C, type DeductCreditsResult as D, type ExpiredBackingFrontier as E, 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-MaViK5tD.d.ts → types-C3sxDvNb.d.ts}

@@ -99,6 +99,11 @@ interface PortableUserCredits {
      * Absent means 0. See `planBalanceCap`.
      */
     expiredHoldBacking?: number;
+    /**
+     * Where those credits end among the open holds, so a hold's share needs no write
+     * to the hold. Internal to the repositories: `toClientUserCredits` drops it.
+     */
+    expiredBackingFrontier?: ExpiredBackingFrontier | null;
     /**
      * Set when the account was created with a signup-grant claim: the amount
      * granted, 0 when the claim was already taken. Absent on any other account.
@@ -109,6 +114,21 @@ interface PortableUserCredits {
     /** Last update timestamp - ISO 8601 */
     updatedAt: string;
 }
+/**
+ * The newest open hold carrying marked credits (`expiredHoldBacking`).
+ *
+ * Credits are marked oldest hold first, so a single point describes every share:
+ * a hold older than this carries its full amount, this hold carries `share`, and a
+ * newer one carries nothing. A marked credit leaves the balance when its hold closes,
+ * however it closes. See `allocateExpiredBacking` and `holdExpiredBacking`.
+ */
+interface ExpiredBackingFrontier {
+    /** The hold's `holdPlacedAt`. */
+    holdPlacedAt: string;
+    /** The hold's id, which orders holds placed in the same millisecond. */
+    id: string;
+    share: number;
+}
 /**
  * Credit reservation status for two-phase commit
  */
@@ -148,10 +168,8 @@ interface PortableReservation {
      */
     holdPlacedAt?: string;
     /**
-     * The part of this hold backed by credits that expired while it was open, and so
-     * leave the balance when it closes, however it closes. Absent means 0, as on every
-     * hold placed after the expiry. Open holds' shares sum to the account's
-     * `expiredHoldBacking`.
+     * This hold's share of the marked credits, stored by 2.2.0. A hold placed since carries
+     * none and takes its share from the account's frontier. See `holdExpiredBacking`.
      */
     expiredBacking?: number;
 }
@@ -268,8 +286,13 @@ interface PortableJournalEntry {
     entryType: "debit" | "credit";
     /** Amount of credits involved */
     amount: number;
-    /** Balance after this entry */
+    /** `balance + bonusCredits` after this entry */
     balanceAfter: number;
+    /**
+     * `balance + bonusCredits` before this entry, read in the same atomic step.
+     * Absent on entries written before 3.0.0.
+     */
+    balanceBefore?: number;
     /** Source of the credit change */
     source: CreditSource;
     /** Reference ID (e.g., reservationId, transactionId) */
@@ -368,4 +391,4 @@ interface WithCreditsOptions {
     resourceType?: ResourceType;
 }
 
-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 };
+export { type AIProviderType as A, type BuiltinTier as B, type CreditOperationType as C, type DeductCreditsResult as D, type ExpiredBackingFrontier as E, 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-XSjNXO5l.d.cts → types-YLAB8bFk.d.cts}

@@ -1,4 +1,4 @@
-import { P as PortableTransaction, a as PortableReservation, R as ReservationStatus, C as CreditOperationType, b as CreditSource, J as JournalReferenceType, A as AIProviderType, S as SubscriptionTier, c as PortableUserCredits, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-MaViK5tD.cjs';
+import { P as PortableTransaction, a as PortableReservation, R as ReservationStatus, C as CreditOperationType, b as CreditSource, J as JournalReferenceType, A as AIProviderType, S as SubscriptionTier, c as PortableUserCredits, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-C3sxDvNb.cjs';
 
 /**
  * Typed outcomes for the V2 reservation boundary.
@@ -326,7 +326,10 @@ interface CreateJournalEntryInput {
     userId: string;
     entryType: "debit" | "credit";
     amount: number;
+    /** `balance + bonusCredits` after this entry. */
     balanceAfter: number;
+    /** `balance + bonusCredits` before this entry. */
+    balanceBefore?: number;
     source: CreditSource;
     referenceId: string;
     referenceType: JournalReferenceType;
@@ -335,6 +338,18 @@ interface CreateJournalEntryInput {
     /** Deterministic key making this entry unique per user (V2, optional). */
     idempotencyKey?: string;
 }
+/**
+ * The journal entry of a one-shot deduct, written in the deduct's own atomic step.
+ */
+interface DeductJournalInput {
+    referenceId: string;
+    description: string;
+    /** Defaults to `"operation_commit"`. */
+    source?: CreditSource;
+    /** Defaults to `"adjustment"`. */
+    referenceType?: JournalReferenceType;
+    metadata?: Record<string, unknown>;
+}
 /**
  * Query options for journal entries
  */
@@ -354,6 +369,7 @@ interface CreditBalanceUpdate {
     balance?: number;
     bonusCredits?: number;
     reserved?: number;
+    /** Writes no journal line. To change a tier, use `updateUserTier`. */
     tier?: SubscriptionTier;
     monthlyLimit?: number;
     monthlyUsed?: number;
@@ -446,7 +462,9 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      */
     getUserCredits(userId: string): Promise<PortableUserCredits | null>;
     /**
-     * Initialize credits for a new user
+     * Initialize credits for a new user. Creating an account with a balance above 0
+     * writes its journal line (`signupGrantJournalInput`) in the same atomic step, and
+     * a call that finds the account writes nothing.
      * @param userId - User ID
      * @param tier - Initial subscription tier
      * @param initialBalance - Initial credit balance
@@ -454,13 +472,16 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      */
     initializeUserCredits(userId: string, tier: SubscriptionTier, initialBalance: number): Promise<PortableUserCredits>;
     /**
-     * Update user credits balance
+     * Patch fields of the account. This writes no journal line, whatever it changes.
+     * A tier change goes through `updateUserTier`, which journals a balance it moves.
      * @param userId - User ID
      * @param updates - Partial updates to apply
      */
     updateUserCredits(userId: string, updates: CreditBalanceUpdate): Promise<void>;
     /**
-     * Update user subscription tier
+     * Update user subscription tier. A write that moves the balance writes one journal
+     * line (`tierChangeJournalInput`) in the same atomic step, and one that does not
+     * writes none.
      * @param userId - User ID
      * @param input - Tier update data
      */
@@ -556,9 +577,10 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      * @returns Combined totals (balance + bonusCredits) before and after.
      * @throws If user has no credits doc or insufficient credits
      */
-    deductCreditsAtomic(userId: string, amount: number): Promise<{
+    deductCreditsAtomic(userId: string, amount: number, journal?: DeductJournalInput): Promise<{
         previousBalance: number;
         newBalance: number;
+        journalEntryId?: string;
     }>;
     /**
      * Create a credit transaction *record* — no balance moves.
@@ -678,4 +700,4 @@ declare function supportsIdempotentCredit(repository: ICreditRepository): reposi
  */
 declare function toClientUserCredits(credits: PortableUserCredits): PortableUserCredits;
 
-export { type AddCreditsAtomicOptions as A, type CommitOutcome as C, type ExpireOutcome as E, type ICreditRepository as I, type JournalEntryQuery as J, type ReleaseOutcome as R, type TerminalReservationStatus as T, type UsageLogQuery as U, type AddCreditsOutcome as a, type AddCreditsV2Input as b, type CreateJournalEntryInput as c, type CreateReservationInput as d, type CreateTransactionInput as e, type CreateUsageLogInput as f, type CreditBalanceUpdate as g, type CreditPolicyOptions as h, type CreditRepositoryFactory as i, type ExpireReservationV2Options as j, type ICreditRepositoryCreditsV2 as k, type ICreditRepositoryV2 as l, type ReservationTransitionOptions as m, type ReserveCreditsV2Input as n, type ReserveOutcome as o, type TierUpdateInput as p, isCreditedOutcome as q, isReservedOutcome as r, isWinningOutcome as s, reservationJournalKey as t, supportsCreditsV2 as u, supportsIdempotentCredit as v, toClientUserCredits as w };
+export { type AddCreditsAtomicOptions as A, type CommitOutcome as C, type DeductJournalInput as D, type ExpireOutcome as E, type ICreditRepository as I, type JournalEntryQuery as J, type ReleaseOutcome as R, type TerminalReservationStatus as T, type UsageLogQuery as U, type AddCreditsOutcome as a, type AddCreditsV2Input as b, type CreateJournalEntryInput as c, type CreateReservationInput as d, type CreateTransactionInput as e, type CreateUsageLogInput as f, type CreditBalanceUpdate as g, type CreditPolicyOptions as h, type CreditRepositoryFactory as i, type ExpireReservationV2Options as j, type ICreditRepositoryCreditsV2 as k, type ICreditRepositoryV2 as l, type ReservationTransitionOptions as m, type ReserveCreditsV2Input as n, type ReserveOutcome as o, type TierUpdateInput as p, isCreditedOutcome as q, isReservedOutcome as r, isWinningOutcome as s, reservationJournalKey as t, supportsCreditsV2 as u, supportsIdempotentCredit as v, toClientUserCredits as w };

package/package.json

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