@nehorai/credits 2.1.0 → 3.0.0

package/dist/repository/index.d.cts

@@ -1,6 +1,6 @@
-import { I as ICreditRepository, b as AddCreditsV2Input, a as AddCreditsOutcome, l as ReservationTransitionOptions, C as CommitOutcome, R as ReleaseOutcome, m as ReserveCreditsV2Input, n as ReserveOutcome, g as CreditBalanceUpdate, o as TierUpdateInput, d as CreateReservationInput, i as ExpireReservationV2Options, E as ExpireOutcome, A as AddCreditsAtomicOptions, e as CreateTransactionInput, f as CreateUsageLogInput, U as UsageLogQuery, c as CreateJournalEntryInput, J as JournalEntryQuery } from '../types-wtksMa4n.cjs';
-export { h as CreditRepositoryFactory, j as ICreditRepositoryCreditsV2, k as ICreditRepositoryV2, s as reservationJournalKey, t as supportsCreditsV2, u as supportsIdempotentCredit, v as toClientUserCredits } from '../types-wtksMa4n.cjs';
-import { c as PortableUserCredits, S as SubscriptionTier, a as PortableReservation, R as ReservationStatus, P as PortableTransaction, d as PortableUsageLog, f as PortableJournalEntry, M as MonthlyResetResult, e as SubscriptionExpiryResult } from '../types-Dzc443vy.cjs';
+import { I as ICreditRepository, b as AddCreditsV2Input, a as AddCreditsOutcome, m as ReservationTransitionOptions, C as CommitOutcome, R as ReleaseOutcome, n as ReserveCreditsV2Input, o as ReserveOutcome, g as CreditBalanceUpdate, h as CreditPolicyOptions, p as TierUpdateInput, d as CreateReservationInput, j as ExpireReservationV2Options, E as ExpireOutcome, A as AddCreditsAtomicOptions, D as DeductJournalInput, e as CreateTransactionInput, f as CreateUsageLogInput, U as UsageLogQuery, c as CreateJournalEntryInput, J as JournalEntryQuery } from '../types-DOjguhEX.cjs';
+export { i as CreditRepositoryFactory, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from '../types-DOjguhEX.cjs';
+import { c as PortableUserCredits, S as SubscriptionTier, a as PortableReservation, R as ReservationStatus, P as PortableTransaction, d as PortableUsageLog, f as PortableJournalEntry, M as MonthlyResetResult, e as SubscriptionExpiryResult } from '../types-C3sxDvNb.cjs';
 
 /**
  * One reservation flow for both repository generations.
@@ -62,6 +62,7 @@ declare function addCreditsThroughRepository(repository: ICreditRepository, inpu
  * These are pure functions with no server-only dependencies,
  * making them safe to use in any repository implementation.
  */
+
 /**
  * Generate a unique ID
  * Uses timestamp + random string for uniqueness
@@ -77,6 +78,27 @@ declare function toDate(value: Date | string | unknown): Date;
  * Used for calculating monthly reset dates
  */
 declare function getNextMonthlyReset(from?: Date): Date;
+/** Result of validating a balance update. */
+interface BalanceValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Whether an update leaves a valid account: no negative field, and `reserved` covered
+ * by `balance + bonusCredits`, which is the floor outstanding holds put under the
+ * balance. An increment is applied on top of the absolute value when a call names both.
+ *
+ * An update is a delta the caller asked for, so one that cannot be honoured is refused,
+ * as a deduct is. Only tier writes and resets stop at the floor: they state a target.
+ *
+ * A negative balance increment is a charge, so it draws only on the balance above
+ * `expiredHoldBacking`: those credits are expired and leave when their hold closes, so
+ * charging them would hand the charge back. An absolute balance replaces the field and
+ * the marks with it, so only an increment on the stored balance meets this limit.
+ */
+declare function validateBalanceUpdate(current: Pick<PortableUserCredits, "balance" | "bonusCredits" | "reserved" | "expiredHoldBacking">, updates: CreditBalanceUpdate): BalanceValidationResult;
+/** Refuse an update {@link validateBalanceUpdate} finds invalid. */
+declare function assertValidBalanceUpdate(current: Pick<PortableUserCredits, "balance" | "bonusCredits" | "reserved" | "expiredHoldBacking">, updates: CreditBalanceUpdate): void;
 
 /**
  * In-Memory Credit Repository Implementation
@@ -92,6 +114,8 @@ declare function getNextMonthlyReset(from?: Date): Date;
 
 declare class InMemoryCreditRepository implements ICreditRepository {
     private readonly store;
+    private readonly options;
+    constructor(options?: CreditPolicyOptions);
     /**
      * A copy, never the live record.
      *
@@ -157,9 +181,10 @@ declare class InMemoryCreditRepository implements ICreditRepository {
      * that *is* the idempotent no-op the caller asked for.
      */
     addCreditsAtomic(userId: string, amount: number, description: string, paymentRef?: string, options?: AddCreditsAtomicOptions): Promise<void>;
-    deductCreditsAtomic(userId: string, amount: number): Promise<{
+    deductCreditsAtomic(userId: string, amount: number, journal?: DeductJournalInput): Promise<{
         previousBalance: number;
         newBalance: number;
+        journalEntryId?: string;
     }>;
     createTransaction(input: CreateTransactionInput): Promise<PortableTransaction>;
     /** The unguarded writer, for `addCreditsV2` — which has moved the balance. */
@@ -192,7 +217,11 @@ declare class InMemoryCreditRepository implements ICreditRepository {
         creditsReleased: number;
         errors: string[];
     }>;
-    atomicMonthlyReset(userId: string, tier: SubscriptionTier, expectedResetAt: Date | string): Promise<MonthlyResetResult>;
+    /**
+     * @param _tier - Not trusted. The caller read it earlier and the account may
+     *   have changed tier since, so the reset uses the tier stored on the account.
+     */
+    atomicMonthlyReset(userId: string, _tier: SubscriptionTier, expectedResetAt: Date | string): Promise<MonthlyResetResult>;
     checkAndHandleSubscriptionExpiry(userId: string, gracePeriodDays?: number): Promise<SubscriptionExpiryResult>;
     /**
      * Clear all data (useful for testing)
@@ -221,6 +250,6 @@ declare class InMemoryCreditRepository implements ICreditRepository {
  * Create a new in-memory repository instance
  * Each call creates a fresh, isolated instance
  */
-declare function createInMemoryCreditRepository(): InMemoryCreditRepository;
+declare function createInMemoryCreditRepository(options?: CreditPolicyOptions): InMemoryCreditRepository;
 
-export { AddCreditsAtomicOptions, AddCreditsV2Input, CreateJournalEntryInput, CreateReservationInput, CreateTransactionInput, CreateUsageLogInput, CreditBalanceUpdate, ExpireReservationV2Options, ICreditRepository, InMemoryCreditRepository, JournalEntryQuery, ReservationTransitionOptions, ReserveCreditsV2Input, TierUpdateInput, UsageLogQuery, addCreditsThroughRepository, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, toDate };
+export { AddCreditsAtomicOptions, AddCreditsV2Input, type BalanceValidationResult, CreateJournalEntryInput, CreateReservationInput, CreateTransactionInput, CreateUsageLogInput, CreditBalanceUpdate, DeductJournalInput, ExpireReservationV2Options, ICreditRepository, InMemoryCreditRepository, JournalEntryQuery, ReservationTransitionOptions, ReserveCreditsV2Input, TierUpdateInput, UsageLogQuery, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, toDate, validateBalanceUpdate };

package/dist/repository/index.d.ts

@@ -1,6 +1,6 @@
-import { I as ICreditRepository, b as AddCreditsV2Input, a as AddCreditsOutcome, l as ReservationTransitionOptions, C as CommitOutcome, R as ReleaseOutcome, m as ReserveCreditsV2Input, n as ReserveOutcome, g as CreditBalanceUpdate, o as TierUpdateInput, d as CreateReservationInput, i as ExpireReservationV2Options, E as ExpireOutcome, A as AddCreditsAtomicOptions, e as CreateTransactionInput, f as CreateUsageLogInput, U as UsageLogQuery, c as CreateJournalEntryInput, J as JournalEntryQuery } from '../types-BhCdep_t.js';
-export { h as CreditRepositoryFactory, j as ICreditRepositoryCreditsV2, k as ICreditRepositoryV2, s as reservationJournalKey, t as supportsCreditsV2, u as supportsIdempotentCredit, v as toClientUserCredits } from '../types-BhCdep_t.js';
-import { c as PortableUserCredits, S as SubscriptionTier, a as PortableReservation, R as ReservationStatus, P as PortableTransaction, d as PortableUsageLog, f as PortableJournalEntry, M as MonthlyResetResult, e as SubscriptionExpiryResult } from '../types-Dzc443vy.js';
+import { I as ICreditRepository, b as AddCreditsV2Input, a as AddCreditsOutcome, m as ReservationTransitionOptions, C as CommitOutcome, R as ReleaseOutcome, n as ReserveCreditsV2Input, o as ReserveOutcome, g as CreditBalanceUpdate, h as CreditPolicyOptions, p as TierUpdateInput, d as CreateReservationInput, j as ExpireReservationV2Options, E as ExpireOutcome, A as AddCreditsAtomicOptions, D as DeductJournalInput, e as CreateTransactionInput, f as CreateUsageLogInput, U as UsageLogQuery, c as CreateJournalEntryInput, J as JournalEntryQuery } from '../types-CY-oHIMA.js';
+export { i as CreditRepositoryFactory, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from '../types-CY-oHIMA.js';
+import { c as PortableUserCredits, S as SubscriptionTier, a as PortableReservation, R as ReservationStatus, P as PortableTransaction, d as PortableUsageLog, f as PortableJournalEntry, M as MonthlyResetResult, e as SubscriptionExpiryResult } from '../types-C3sxDvNb.js';
 
 /**
  * One reservation flow for both repository generations.
@@ -62,6 +62,7 @@ declare function addCreditsThroughRepository(repository: ICreditRepository, inpu
  * These are pure functions with no server-only dependencies,
  * making them safe to use in any repository implementation.
  */
+
 /**
  * Generate a unique ID
  * Uses timestamp + random string for uniqueness
@@ -77,6 +78,27 @@ declare function toDate(value: Date | string | unknown): Date;
  * Used for calculating monthly reset dates
  */
 declare function getNextMonthlyReset(from?: Date): Date;
+/** Result of validating a balance update. */
+interface BalanceValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Whether an update leaves a valid account: no negative field, and `reserved` covered
+ * by `balance + bonusCredits`, which is the floor outstanding holds put under the
+ * balance. An increment is applied on top of the absolute value when a call names both.
+ *
+ * An update is a delta the caller asked for, so one that cannot be honoured is refused,
+ * as a deduct is. Only tier writes and resets stop at the floor: they state a target.
+ *
+ * A negative balance increment is a charge, so it draws only on the balance above
+ * `expiredHoldBacking`: those credits are expired and leave when their hold closes, so
+ * charging them would hand the charge back. An absolute balance replaces the field and
+ * the marks with it, so only an increment on the stored balance meets this limit.
+ */
+declare function validateBalanceUpdate(current: Pick<PortableUserCredits, "balance" | "bonusCredits" | "reserved" | "expiredHoldBacking">, updates: CreditBalanceUpdate): BalanceValidationResult;
+/** Refuse an update {@link validateBalanceUpdate} finds invalid. */
+declare function assertValidBalanceUpdate(current: Pick<PortableUserCredits, "balance" | "bonusCredits" | "reserved" | "expiredHoldBacking">, updates: CreditBalanceUpdate): void;
 
 /**
  * In-Memory Credit Repository Implementation
@@ -92,6 +114,8 @@ declare function getNextMonthlyReset(from?: Date): Date;
 
 declare class InMemoryCreditRepository implements ICreditRepository {
     private readonly store;
+    private readonly options;
+    constructor(options?: CreditPolicyOptions);
     /**
      * A copy, never the live record.
      *
@@ -157,9 +181,10 @@ declare class InMemoryCreditRepository implements ICreditRepository {
      * that *is* the idempotent no-op the caller asked for.
      */
     addCreditsAtomic(userId: string, amount: number, description: string, paymentRef?: string, options?: AddCreditsAtomicOptions): Promise<void>;
-    deductCreditsAtomic(userId: string, amount: number): Promise<{
+    deductCreditsAtomic(userId: string, amount: number, journal?: DeductJournalInput): Promise<{
         previousBalance: number;
         newBalance: number;
+        journalEntryId?: string;
     }>;
     createTransaction(input: CreateTransactionInput): Promise<PortableTransaction>;
     /** The unguarded writer, for `addCreditsV2` — which has moved the balance. */
@@ -192,7 +217,11 @@ declare class InMemoryCreditRepository implements ICreditRepository {
         creditsReleased: number;
         errors: string[];
     }>;
-    atomicMonthlyReset(userId: string, tier: SubscriptionTier, expectedResetAt: Date | string): Promise<MonthlyResetResult>;
+    /**
+     * @param _tier - Not trusted. The caller read it earlier and the account may
+     *   have changed tier since, so the reset uses the tier stored on the account.
+     */
+    atomicMonthlyReset(userId: string, _tier: SubscriptionTier, expectedResetAt: Date | string): Promise<MonthlyResetResult>;
     checkAndHandleSubscriptionExpiry(userId: string, gracePeriodDays?: number): Promise<SubscriptionExpiryResult>;
     /**
      * Clear all data (useful for testing)
@@ -221,6 +250,6 @@ declare class InMemoryCreditRepository implements ICreditRepository {
  * Create a new in-memory repository instance
  * Each call creates a fresh, isolated instance
  */
-declare function createInMemoryCreditRepository(): InMemoryCreditRepository;
+declare function createInMemoryCreditRepository(options?: CreditPolicyOptions): InMemoryCreditRepository;
 
-export { AddCreditsAtomicOptions, AddCreditsV2Input, CreateJournalEntryInput, CreateReservationInput, CreateTransactionInput, CreateUsageLogInput, CreditBalanceUpdate, ExpireReservationV2Options, ICreditRepository, InMemoryCreditRepository, JournalEntryQuery, ReservationTransitionOptions, ReserveCreditsV2Input, TierUpdateInput, UsageLogQuery, addCreditsThroughRepository, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, toDate };
+export { AddCreditsAtomicOptions, AddCreditsV2Input, type BalanceValidationResult, CreateJournalEntryInput, CreateReservationInput, CreateTransactionInput, CreateUsageLogInput, CreditBalanceUpdate, DeductJournalInput, ExpireReservationV2Options, ICreditRepository, InMemoryCreditRepository, JournalEntryQuery, ReservationTransitionOptions, ReserveCreditsV2Input, TierUpdateInput, UsageLogQuery, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, toDate, validateBalanceUpdate };