@nehorai/credits 3.0.0 → 3.1.0

package/dist/index.d.cts

@@ -1,10 +1,10 @@
 import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-C3sxDvNb.cjs';
 export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, E as ExpiredBackingFrontier, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, c as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, c as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-C3sxDvNb.cjs';
-export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditPolicyOptions, i as CreditRepositoryFactory, D as DeductJournalInput, E as ExpireOutcome, j as ExpireReservationV2Options, I as ICreditRepository, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, m as ReservationTransitionOptions, n as ReserveCreditsV2Input, o as ReserveOutcome, T as TerminalReservationStatus, p as TierUpdateInput, U as UsageLogQuery, q as isCreditedOutcome, r as isReservedOutcome, s as isWinningOutcome, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from './types-DOjguhEX.cjs';
+export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditPolicyOptions, i as CreditRepositoryFactory, D as DeductJournalInput, E as ExpireOutcome, j as ExpireReservationV2Options, I as ICreditRepository, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, m as ReservationTransitionOptions, n as ReserveCreditsV2Input, o as ReserveOutcome, T as TerminalReservationStatus, p as TierUpdateInput, U as UsageLogQuery, q as isCreditedOutcome, r as isReservedOutcome, s as isWinningOutcome, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from './types-YLAB8bFk.cjs';
 export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, ExpiredBackingAllocation, ExpiredBackingFields, ExpiredBackingHold, ExpiredBackingRewrite, NO_EXPIRED_BACKING_PREFIX, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, allocateExpiredBacking, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidBalanceTarget, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, assertValidTierBalanceInput, backedBalanceFloor, canonicalAmount, cappedBalance, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, expiredBackingPatch, getSqlState, hasPlacedHold, heldExpiredBacking, holdExpiredBacking, holdPlacedAtAfter, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, multiplyAmount, normalizePaymentRef, numericToCents, planBalanceCap, planBalanceTarget, planHoldCommit, recordedExpiredBacking, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, settleExpiredHoldBacking, spendableBalance, storedAmountCeil, storedAmountFloor, storedMonthlyLimit, sumAmounts, terminalStatusOf, toCents } from './core/index.cjs';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from './deferred-C7rrRfkm.cjs';
 import { z } from 'zod';
-export { BalanceValidationResult, InMemoryCreditRepository, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, validateBalanceUpdate } from './repository/index.cjs';
+export { B as BalanceValidationResult, I as InMemoryCreditRepository, a as addCreditsThroughRepository, b as assertValidBalanceUpdate, c as commitThroughRepository, d as createInMemoryCreditRepository, g as generateId, e as getNextMonthlyReset, r as releaseThroughRepository, f as reserveThroughRepository, s as signupGrantJournalInput, t as tierChangeJournalInput, v as validateBalanceUpdate } from './index-BrogG0Gc.cjs';
 export { C as CreditsAuthProviderFactory, a as CreditsUser, I as ICreditsAuthProvider } from './types-OZU3I5OM.cjs';
 export { ApiKeyCreditsProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken } from './auth/index.cjs';
 export { CreditsService, DeductCreditsOptions, LowBalanceNotificationCallback, ReserveCreditsOptions, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.cjs';

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-C3sxDvNb.js';
 export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, E as ExpiredBackingFrontier, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, c as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, c as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-C3sxDvNb.js';
-export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditPolicyOptions, i as CreditRepositoryFactory, D as DeductJournalInput, E as ExpireOutcome, j as ExpireReservationV2Options, I as ICreditRepository, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, m as ReservationTransitionOptions, n as ReserveCreditsV2Input, o as ReserveOutcome, T as TerminalReservationStatus, p as TierUpdateInput, U as UsageLogQuery, q as isCreditedOutcome, r as isReservedOutcome, s as isWinningOutcome, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from './types-CY-oHIMA.js';
+export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditPolicyOptions, i as CreditRepositoryFactory, D as DeductJournalInput, E as ExpireOutcome, j as ExpireReservationV2Options, I as ICreditRepository, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, m as ReservationTransitionOptions, n as ReserveCreditsV2Input, o as ReserveOutcome, T as TerminalReservationStatus, p as TierUpdateInput, U as UsageLogQuery, q as isCreditedOutcome, r as isReservedOutcome, s as isWinningOutcome, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from './types-BL3YqxUD.js';
 export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, ExpiredBackingAllocation, ExpiredBackingFields, ExpiredBackingHold, ExpiredBackingRewrite, NO_EXPIRED_BACKING_PREFIX, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, allocateExpiredBacking, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidBalanceTarget, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, assertValidTierBalanceInput, backedBalanceFloor, canonicalAmount, cappedBalance, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, expiredBackingPatch, getSqlState, hasPlacedHold, heldExpiredBacking, holdExpiredBacking, holdPlacedAtAfter, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, multiplyAmount, normalizePaymentRef, numericToCents, planBalanceCap, planBalanceTarget, planHoldCommit, recordedExpiredBacking, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, settleExpiredHoldBacking, spendableBalance, storedAmountCeil, storedAmountFloor, storedMonthlyLimit, sumAmounts, terminalStatusOf, toCents } from './core/index.js';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from './deferred-C7rrRfkm.js';
 import { z } from 'zod';
-export { BalanceValidationResult, InMemoryCreditRepository, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, validateBalanceUpdate } from './repository/index.js';
+export { B as BalanceValidationResult, I as InMemoryCreditRepository, a as addCreditsThroughRepository, b as assertValidBalanceUpdate, c as commitThroughRepository, d as createInMemoryCreditRepository, g as generateId, e as getNextMonthlyReset, r as releaseThroughRepository, f as reserveThroughRepository, s as signupGrantJournalInput, t as tierChangeJournalInput, v as validateBalanceUpdate } from './index-DOvJES2m.js';
 export { C as CreditsAuthProviderFactory, a as CreditsUser, I as ICreditsAuthProvider } from './types-OZU3I5OM.js';
 export { ApiKeyCreditsProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken } from './auth/index.js';
 export { CreditsService, DeductCreditsOptions, LowBalanceNotificationCallback, ReserveCreditsOptions, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.js';

package/dist/index.js

@@ -913,17 +913,25 @@ var DEFAULT_CONFIG = {
   }
 };
 var currentConfig = DEFAULT_CONFIG;
+function isOperationCostMap(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((cost) => isRepresentableAmount(cost) && cost >= 0);
+}
 function loadConfigFromEnv() {
   const envConfig = {};
   const operationCostsEnv = process.env.CREDITS_OPERATION_COSTS;
   if (operationCostsEnv) {
     try {
       const parsed = JSON.parse(operationCostsEnv);
-      if (typeof parsed === "object" && parsed !== null) {
+      if (isOperationCostMap(parsed)) {
         envConfig.operationCosts = {
           ...DEFAULT_CONFIG.operationCosts,
           ...parsed
         };
+      } else {
+        console.warn(
+          "[Credits Config] Ignoring CREDITS_OPERATION_COSTS: it must be a JSON object whose costs are numbers >= 0, exact to the cent"
+        );
       }
     } catch {
       console.warn("[Credits Config] Failed to parse CREDITS_OPERATION_COSTS env var as JSON");
@@ -1371,6 +1379,50 @@ function assertValidBalanceUpdate(current, updates) {
     throw new Error(`Invalid balance update: ${result.errors.join("; ")}`);
   }
 }
+function signupGrantJournalInput(userId, tier, grant) {
+  if (grant <= 0) return null;
+  return {
+    userId,
+    entryType: "credit",
+    amount: grant,
+    balanceBefore: 0,
+    balanceAfter: grant,
+    source: "bonus",
+    referenceId: `signup-${userId}`,
+    referenceType: "adjustment",
+    description: `Signup grant for ${tier} tier.`,
+    metadata: { tier }
+  };
+}
+function tierChangeJournalInput(input) {
+  const { userId, previousTier, newTier, previousBalance, newBalance, bonusCredits } = input;
+  const change = sumAmounts(newBalance, -previousBalance);
+  if (change === 0) return null;
+  const raised = change > 0;
+  const amount = raised ? newBalance : 0;
+  const balanceBefore = sumAmounts(previousBalance, bonusCredits);
+  const balanceAfter = sumAmounts(newBalance, bonusCredits);
+  assertRepresentableFields(
+    {
+      "journal amount": amount,
+      "journal balanceBefore": balanceBefore,
+      "journal balanceAfter": balanceAfter
+    },
+    { userId, operation: "updateUserTier" }
+  );
+  return {
+    userId,
+    entryType: raised ? "credit" : "debit",
+    amount,
+    balanceBefore,
+    balanceAfter,
+    source: raised ? "subscription_upgrade" : "subscription_downgrade",
+    referenceId: `tier-${Date.now()}`,
+    referenceType: "subscription",
+    description: `Tier changed from ${previousTier} to ${newTier}.`,
+    metadata: { previousTier, newTier, previousBalance, newBalance }
+  };
+}
 
 // src/repository/memory/snapshot.ts
 function copyRecord(record) {
@@ -1914,6 +1966,8 @@ var InMemoryCreditRepository = class {
       updatedAt: now
     };
     this.store.users.set(userId, credits);
+    const grantLine = signupGrantJournalInput(userId, tier, initialBalance);
+    if (grantLine) this.recordJournalEntry(grantLine);
     return credits;
   }
   async updateUserCredits(userId, updates) {
@@ -1994,21 +2048,29 @@ var InMemoryCreditRepository = class {
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
-    if (input.balanceCap !== void 0 && !isFreeTier(credits.tier)) {
-      const capped = planBalanceCap(
+    let planned;
+    if (input.balance !== void 0) {
+      planned = planBalanceTarget(input.balance, credits.reserved, credits.bonusCredits);
+    } else if (input.balanceCap !== void 0 && !isFreeTier(credits.tier)) {
+      planned = planBalanceCap(
         credits.balance,
         input.balanceCap,
         credits.reserved,
         credits.bonusCredits,
         credits.expiredHoldBacking
       );
-      credits.balance = capped.balance;
-      writeExpiredHoldBacking(this.store, credits, capped.expiredHoldBacking);
     }
+    const journalLine = planned ? tierChangeJournalInput({
+      userId,
+      previousTier: credits.tier,
+      newTier: input.tier,
+      previousBalance: credits.balance,
+      newBalance: planned.balance,
+      bonusCredits: credits.bonusCredits
+    }) : null;
     credits.tier = input.tier;
     credits.monthlyLimit = input.monthlyLimit;
-    if (input.balance !== void 0) {
-      const planned = planBalanceTarget(input.balance, credits.reserved, credits.bonusCredits);
+    if (planned) {
       credits.balance = planned.balance;
       writeExpiredHoldBacking(this.store, credits, planned.expiredHoldBacking);
     }
@@ -2027,6 +2089,7 @@ var InMemoryCreditRepository = class {
     }
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.store.users.set(userId, credits);
+    if (journalLine) this.recordJournalEntry(journalLine);
   }
   // ==================== Reservations ====================
   async createReservation(input) {
@@ -2648,7 +2711,7 @@ var InMemoryCreditRepository = class {
       userId,
       entryType: "debit",
       amount: 0,
-      // No credits deducted, just tier change
+      // 0, however far the cap lowered the balance: the totals record the move
       balanceBefore: sumAmounts(previousBalance, credits.bonusCredits),
       balanceAfter,
       source: "subscription_downgrade",
@@ -2812,7 +2875,7 @@ var CreditsService = class {
           userId,
           entryType: "debit",
           amount: 0,
-          // No credits deducted, just tier change
+          // 0, however far the cap lowered the balance: the totals record the move
           balanceBefore: sumAmounts(data.balance, data.bonusCredits),
           // The ledger balance, matching every other journal writer: the V2
           // transitions and add/deduct all record `balance + bonusCredits`, so
@@ -3204,7 +3267,8 @@ var CreditsService = class {
     ]);
     const historyEntries = entries.map((entry) => {
       const type = this.mapSourceToHistoryType(entry.source);
-      const creditsChange = entry.entryType === "credit" ? entry.amount : -entry.amount;
+      const signedAmount = entry.entryType === "credit" ? entry.amount : -entry.amount;
+      const creditsChange = entry.balanceBefore !== void 0 ? sumAmounts(entry.balanceAfter, -entry.balanceBefore) : signedAmount;
       return {
         id: entry.id,
         type,
@@ -4276,6 +4340,7 @@ export {
   resetConfig,
   sameAmount,
   settleExpiredHoldBacking,
+  signupGrantJournalInput,
   spendableBalance,
   storedAmountCeil,
   storedAmountFloor,
@@ -4285,6 +4350,7 @@ export {
   supportsIdempotentCredit,
   synchronousDeferred,
   terminalStatusOf,
+  tierChangeJournalInput,
   tierSchema,
   toCents,
   toClientUserCredits,