@nehorai/credits 2.2.0 → 3.1.0

package/dist/core/index.cjs

@@ -24,9 +24,11 @@ __export(core_exports, {
   CREDIT_AMOUNT_SCALE: () => CREDIT_AMOUNT_SCALE,
   CreditError: () => CreditError,
   CreditErrorCode: () => CreditErrorCode,
+  NO_EXPIRED_BACKING_PREFIX: () => NO_EXPIRED_BACKING_PREFIX,
   RESERVATION_STATUSES: () => RESERVATION_STATUSES,
   RESERVED_JOURNAL_KEY_PREFIX: () => RESERVED_JOURNAL_KEY_PREFIX,
   TERMINAL_RESERVATION_STATUSES: () => TERMINAL_RESERVATION_STATUSES,
+  allocateExpiredBacking: () => allocateExpiredBacking,
   assertDirectStatusWriteAllowed: () => assertDirectStatusWriteAllowed,
   assertHoldPlaced: () => assertHoldPlaced,
   assertKnownReservationStatus: () => assertKnownReservationStatus,
@@ -42,9 +44,9 @@ __export(core_exports, {
   assertValidStoredAmount: () => assertValidStoredAmount,
   assertValidStoredAmountRaw: () => assertValidStoredAmountRaw,
   assertValidTierBalanceInput: () => assertValidTierBalanceInput,
-  attributeExpiredBacking: () => attributeExpiredBacking,
   backedBalanceFloor: () => backedBalanceFloor,
   calculateAvailableCredits: () => calculateAvailableCredits,
+  canonicalAmount: () => canonicalAmount,
   cappedBalance: () => cappedBalance,
   classifyDatabaseError: () => classifyDatabaseError,
   commitReservationWithJournal: () => commitReservationWithJournal,
@@ -61,10 +63,13 @@ __export(core_exports, {
   createUnsupportedOperationError: () => createUnsupportedOperationError,
   createUserNotFoundError: () => createUserNotFoundError,
   describePaymentMismatch: () => describePaymentMismatch,
-  expiredHoldBackingPatch: () => expiredHoldBackingPatch,
+  expiredBackingPatch: () => expiredBackingPatch,
   genericDeferred: () => genericDeferred,
   getSqlState: () => getSqlState,
   hasPlacedHold: () => hasPlacedHold,
+  heldExpiredBacking: () => heldExpiredBacking,
+  holdExpiredBacking: () => holdExpiredBacking,
+  holdPlacedAtAfter: () => holdPlacedAtAfter,
   isCreditError: () => isCreditError,
   isCreditedOutcome: () => isCreditedOutcome,
   isIdempotencyConflictError: () => isIdempotencyConflictError,
@@ -80,17 +85,21 @@ __export(core_exports, {
   isValidCreditAmount: () => isValidCreditAmount,
   isValidIdempotencyKey: () => isValidIdempotencyKey,
   isWinningOutcome: () => isWinningOutcome,
+  multiplyAmount: () => multiplyAmount,
   noopDeferred: () => noopDeferred,
   normalizePaymentRef: () => normalizePaymentRef,
   numericToCents: () => numericToCents,
   planBalanceCap: () => planBalanceCap,
   planBalanceTarget: () => planBalanceTarget,
   planHoldCommit: () => planHoldCommit,
+  recordedExpiredBacking: () => recordedExpiredBacking,
   releaseReservationWithJournal: () => releaseReservationWithJournal,
   reserveCreditsForOperation: () => reserveCreditsForOperation,
   sameAmount: () => sameAmount,
   settleExpiredHoldBacking: () => settleExpiredHoldBacking,
   spendableBalance: () => spendableBalance,
+  storedAmountCeil: () => storedAmountCeil,
+  storedAmountFloor: () => storedAmountFloor,
   storedMonthlyLimit: () => storedMonthlyLimit,
   sumAmounts: () => sumAmounts,
   synchronousDeferred: () => synchronousDeferred,
@@ -270,6 +279,40 @@ function floatSum(values) {
   for (const value of values) total += value;
   return total;
 }
+function multiplyAmount(unit, quantity) {
+  const cents = toCents(unit);
+  const product = cents === null ? Number.NaN : cents * quantity;
+  if (cents === null || cents < 0 || !Number.isSafeInteger(quantity) || quantity < 0 || !Number.isSafeInteger(product) || product > MAX_CENTS) {
+    throw new CreditError(
+      `Cannot price ${quantity} units at ${unit}: the price must be a non-negative amount exact to ${CREDIT_AMOUNT_SCALE} decimals, the quantity a whole number, and the result at most ${CREDIT_AMOUNT_MAX}`,
+      CreditErrorCode.INVALID_AMOUNT,
+      { unit, quantity, max: CREDIT_AMOUNT_MAX, scale: CREDIT_AMOUNT_SCALE }
+    );
+  }
+  return product / 100;
+}
+var FLOAT_NOISE_FLOOR = 1e-6;
+var FLOAT_NOISE_RELATIVE = 64 * Number.EPSILON;
+function floatNoise(value) {
+  return Math.max(FLOAT_NOISE_FLOOR, Math.abs(value) * FLOAT_NOISE_RELATIVE);
+}
+function canonicalAmount(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return value;
+  const cents = Math.round(value * 100);
+  if (!Number.isSafeInteger(cents)) return value;
+  const onGrid = cents / 100 + 0;
+  return Math.abs(value - onGrid) < floatNoise(value) ? onGrid : value;
+}
+function storedAmountFloor(value) {
+  const canonical = canonicalAmount(value);
+  if (!Number.isFinite(canonical) || toCents(canonical) !== null) return canonical;
+  return Math.floor(canonical * 100) / 100;
+}
+function storedAmountCeil(value) {
+  const canonical = canonicalAmount(value);
+  if (!Number.isFinite(canonical) || toCents(canonical) !== null) return canonical;
+  return Math.ceil(canonical * 100) / 100;
+}
 function isValidCreditAmount(value) {
   if (typeof value !== "number") return false;
   const cents = toCents(value);
@@ -325,14 +368,19 @@ function backedBalanceFloor(reserved, bonusCredits) {
 function cappedBalance(balance, cap, reserved, bonusCredits) {
   return Math.min(balance, Math.max(cap, backedBalanceFloor(reserved, bonusCredits)));
 }
-function spendableBalance(balance, expiredHoldBacking = 0) {
-  return sumAmounts(balance, -Math.min(expiredHoldBacking, balance));
+function heldExpiredBacking(balance, stored) {
+  if (!(stored !== void 0 && stored > 0)) return 0;
+  return Math.max(0, Math.min(stored, balance));
+}
+function spendableBalance(balance, expiredHoldBacking) {
+  return sumAmounts(balance, -heldExpiredBacking(balance, expiredHoldBacking));
 }
 function planBalanceTarget(target, reserved, bonusCredits) {
+  assertValidBalanceTarget(target, "balance target", { reserved, bonusCredits });
   const balance = Math.max(target, backedBalanceFloor(reserved, bonusCredits));
   return { balance, expiredHoldBacking: sumAmounts(balance, -target) };
 }
-function planBalanceCap(balance, cap, reserved, bonusCredits, expiredHoldBacking = 0) {
+function planBalanceCap(balance, cap, reserved, bonusCredits, expiredHoldBacking) {
   const spendable = spendableBalance(balance, expiredHoldBacking);
   const target = Math.min(spendable, cap);
   const kept = Math.max(
@@ -343,8 +391,8 @@ function planBalanceCap(balance, cap, reserved, bonusCredits, expiredHoldBacking
   return { balance: next, expiredHoldBacking: Math.max(0, sumAmounts(next, -target)) };
 }
 function settleExpiredHoldBacking(balance, expiredHoldBacking, holdBacking) {
-  const held = Math.min(expiredHoldBacking, balance);
-  const used = Math.min(held, holdBacking);
+  const held = heldExpiredBacking(balance, expiredHoldBacking);
+  const used = Math.max(0, Math.min(held, holdBacking));
   return { used, remaining: sumAmounts(held, -used) };
 }
 function planHoldCommit(balance, bonusCredits, expiredHoldBacking, holdBacking, amount) {
@@ -359,27 +407,83 @@ function planHoldCommit(balance, bonusCredits, expiredHoldBacking, holdBacking,
     expiredHoldBacking: backing.remaining
   };
 }
-function attributeExpiredBacking(holds, total) {
-  const placed = holds.filter((hold) => hold.holdPlacedAt).sort(
-    (a, b) => a.holdPlacedAt === b.holdPlacedAt ? a.id < b.id ? -1 : 1 : a.holdPlacedAt < b.holdPlacedAt ? -1 : 1
-  );
-  const shares = /* @__PURE__ */ new Map();
-  let left = total;
-  for (const hold of placed) {
-    const kept = Math.min(hold.expiredBacking ?? 0, hold.amount, left);
-    shares.set(hold.id, kept);
-    left = sumAmounts(left, -kept);
+var NO_EXPIRED_BACKING_PREFIX = {
+  holdPlacedAt: "",
+  id: "",
+  share: 0
+};
+function compareHolds(a, b) {
+  if (a.holdPlacedAt !== b.holdPlacedAt) return a.holdPlacedAt < b.holdPlacedAt ? -1 : 1;
+  if (a.id === b.id) return 0;
+  return a.id < b.id ? -1 : 1;
+}
+function recordedExpiredBacking(hold) {
+  const stored = hold.expiredBacking;
+  if (typeof stored !== "number" || !Number.isFinite(stored) || stored <= 0) return 0;
+  if (!isValidCreditAmount(hold.amount)) return 0;
+  return Math.min(storedAmountCeil(stored), hold.amount);
+}
+function allocateExpiredBacking(holds, total) {
+  const placed = holds.filter((hold) => hold.holdPlacedAt && isValidCreditAmount(hold.amount)).map((hold) => ({ ...hold, holdPlacedAt: hold.holdPlacedAt })).sort(compareHolds);
+  const wanted = Math.max(0, total);
+  if (wanted === 0) return { total: 0, frontier: null };
+  const recorded = placed.filter((hold) => recordedExpiredBacking(hold) > 0);
+  const shares = new Map(recorded.map((hold) => [hold.id, recordedExpiredBacking(hold)]));
+  let left = sumAmounts(wanted, ...[...shares.values()].map((share) => -share));
+  for (const hold of [...recorded].reverse()) {
+    if (left >= 0) break;
+    const share = shares.get(hold.id);
+    const cut = Math.min(share, -left);
+    shares.set(hold.id, sumAmounts(share, -cut));
+    left = sumAmounts(left, cut);
   }
+  let frontier = NO_EXPIRED_BACKING_PREFIX;
   for (const hold of placed) {
+    if (left <= 0) break;
+    if (shares.has(hold.id)) continue;
+    const share = Math.min(hold.amount, left);
+    frontier = { holdPlacedAt: hold.holdPlacedAt, id: hold.id, share };
+    left = sumAmounts(left, -share);
+  }
+  for (const hold of recorded) {
+    if (left <= 0) break;
     const share = shares.get(hold.id);
     const added = Math.min(sumAmounts(hold.amount, -share), left);
     shares.set(hold.id, sumAmounts(share, added));
     left = sumAmounts(left, -added);
   }
-  return shares;
+  const rewrites = recorded.filter((hold) => shares.get(hold.id) !== hold.expiredBacking).map((hold) => ({ id: hold.id, expiredBacking: shares.get(hold.id) }));
+  return { total: wanted, frontier, ...rewrites.length > 0 ? { rewrites } : {} };
 }
-function expiredHoldBackingPatch(next, stored = 0) {
-  return next > 0 || stored > 0 ? { expiredHoldBacking: next } : {};
+function holdExpiredBacking(hold, frontier, rewrites) {
+  const rewritten = rewrites?.find((rewrite) => rewrite.id === hold.id);
+  const recorded = recordedExpiredBacking(
+    rewritten ? { ...hold, expiredBacking: rewritten.expiredBacking } : hold
+  );
+  if (recorded > 0) return recorded;
+  if (!frontier || !hold.holdPlacedAt) return 0;
+  const order = compareHolds({ holdPlacedAt: hold.holdPlacedAt, id: hold.id }, frontier);
+  if (order > 0) return 0;
+  return order < 0 ? hold.amount : Math.min(frontier.share, hold.amount);
+}
+function holdPlacedAtAfter(now, frontier) {
+  if (!frontier?.holdPlacedAt) return now;
+  const earliest = new Date(Date.parse(frontier.holdPlacedAt) + 1).toISOString();
+  return now > earliest ? now : earliest;
+}
+function expiredBackingPatch(next, stored) {
+  const total = Math.max(0, next.total);
+  const patch = {};
+  const storedTotal = stored.expiredHoldBacking;
+  if (total > 0 || storedTotal !== void 0 && storedTotal !== 0) {
+    patch.expiredHoldBacking = total;
+  }
+  if (total <= 0) {
+    if (stored.expiredBackingFrontier) patch.expiredBackingFrontier = null;
+  } else if (next.frontier) {
+    patch.expiredBackingFrontier = next.frontier;
+  }
+  return patch;
 }
 function assertValidBalanceTarget(value, field, context) {
   assertRepresentableAmount(value, field, context);
@@ -392,7 +496,10 @@ function assertValidBalanceTarget(value, field, context) {
   }
 }
 function assertValidTierBalanceInput(input, context) {
-  if (input.balanceCap === void 0) return;
+  if (input.balanceCap === void 0) {
+    if (input.balance !== void 0) assertValidBalanceTarget(input.balance, "balance", context);
+    return;
+  }
   if (input.balance !== void 0) {
     throw new CreditError(
       "A tier update cannot set both balance and balanceCap",
@@ -912,17 +1019,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");
@@ -1178,9 +1293,11 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   CREDIT_AMOUNT_SCALE,
   CreditError,
   CreditErrorCode,
+  NO_EXPIRED_BACKING_PREFIX,
   RESERVATION_STATUSES,
   RESERVED_JOURNAL_KEY_PREFIX,
   TERMINAL_RESERVATION_STATUSES,
+  allocateExpiredBacking,
   assertDirectStatusWriteAllowed,
   assertHoldPlaced,
   assertKnownReservationStatus,
@@ -1196,9 +1313,9 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   assertValidStoredAmount,
   assertValidStoredAmountRaw,
   assertValidTierBalanceInput,
-  attributeExpiredBacking,
   backedBalanceFloor,
   calculateAvailableCredits,
+  canonicalAmount,
   cappedBalance,
   classifyDatabaseError,
   commitReservationWithJournal,
@@ -1215,10 +1332,13 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   createUnsupportedOperationError,
   createUserNotFoundError,
   describePaymentMismatch,
-  expiredHoldBackingPatch,
+  expiredBackingPatch,
   genericDeferred,
   getSqlState,
   hasPlacedHold,
+  heldExpiredBacking,
+  holdExpiredBacking,
+  holdPlacedAtAfter,
   isCreditError,
   isCreditedOutcome,
   isIdempotencyConflictError,
@@ -1234,17 +1354,21 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   isValidCreditAmount,
   isValidIdempotencyKey,
   isWinningOutcome,
+  multiplyAmount,
   noopDeferred,
   normalizePaymentRef,
   numericToCents,
   planBalanceCap,
   planBalanceTarget,
   planHoldCommit,
+  recordedExpiredBacking,
   releaseReservationWithJournal,
   reserveCreditsForOperation,
   sameAmount,
   settleExpiredHoldBacking,
   spendableBalance,
+  storedAmountCeil,
+  storedAmountFloor,
   storedMonthlyLimit,
   sumAmounts,
   synchronousDeferred,