@nehorai/credits 2.1.0 → 3.0.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,
@@ -36,12 +38,16 @@ __export(core_exports, {
   assertRepresentableTierAmount: () => assertRepresentableTierAmount,
   assertUnkeyedDirectReservation: () => assertUnkeyedDirectReservation,
   assertUnreferencedDirectTransaction: () => assertUnreferencedDirectTransaction,
+  assertValidBalanceTarget: () => assertValidBalanceTarget,
   assertValidCreditAmount: () => assertValidCreditAmount,
   assertValidIdempotencyKey: () => assertValidIdempotencyKey,
   assertValidStoredAmount: () => assertValidStoredAmount,
   assertValidStoredAmountRaw: () => assertValidStoredAmountRaw,
+  assertValidTierBalanceInput: () => assertValidTierBalanceInput,
   backedBalanceFloor: () => backedBalanceFloor,
   calculateAvailableCredits: () => calculateAvailableCredits,
+  canonicalAmount: () => canonicalAmount,
+  cappedBalance: () => cappedBalance,
   classifyDatabaseError: () => classifyDatabaseError,
   commitReservationWithJournal: () => commitReservationWithJournal,
   createDeferredExecutor: () => createDeferredExecutor,
@@ -57,9 +63,13 @@ __export(core_exports, {
   createUnsupportedOperationError: () => createUnsupportedOperationError,
   createUserNotFoundError: () => createUserNotFoundError,
   describePaymentMismatch: () => describePaymentMismatch,
+  expiredBackingPatch: () => expiredBackingPatch,
   genericDeferred: () => genericDeferred,
   getSqlState: () => getSqlState,
   hasPlacedHold: () => hasPlacedHold,
+  heldExpiredBacking: () => heldExpiredBacking,
+  holdExpiredBacking: () => holdExpiredBacking,
+  holdPlacedAtAfter: () => holdPlacedAtAfter,
   isCreditError: () => isCreditError,
   isCreditedOutcome: () => isCreditedOutcome,
   isIdempotencyConflictError: () => isIdempotencyConflictError,
@@ -75,12 +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,
@@ -260,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);
@@ -312,6 +365,150 @@ function backedBalanceFloor(reserved, bonusCredits) {
   assertRepresentableAmount(floor, "backedBalanceFloor", { reserved, bonusCredits });
   return floor;
 }
+function cappedBalance(balance, cap, reserved, bonusCredits) {
+  return Math.min(balance, Math.max(cap, backedBalanceFloor(reserved, bonusCredits)));
+}
+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) {
+  const spendable = spendableBalance(balance, expiredHoldBacking);
+  const target = Math.min(spendable, cap);
+  const kept = Math.max(
+    sumAmounts(balance, -spendable),
+    sumAmounts(backedBalanceFloor(reserved, bonusCredits), -target)
+  );
+  const next = Math.min(balance, sumAmounts(target, kept));
+  return { balance: next, expiredHoldBacking: Math.max(0, sumAmounts(next, -target)) };
+}
+function settleExpiredHoldBacking(balance, expiredHoldBacking, 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) {
+  const backing = settleExpiredHoldBacking(balance, expiredHoldBacking, holdBacking);
+  const rest = sumAmounts(amount, -backing.used);
+  const fromSpendable = Math.min(spendableBalance(balance, expiredHoldBacking), rest);
+  const fromBonus = sumAmounts(rest, -fromSpendable);
+  return {
+    covered: fromBonus <= bonusCredits,
+    balance: sumAmounts(balance, -backing.used, -fromSpendable),
+    bonusCredits: sumAmounts(bonusCredits, -fromBonus),
+    expiredHoldBacking: backing.remaining
+  };
+}
+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);
+  }
+  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 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);
+  if (value < 0) {
+    throw new CreditError(
+      `${field} cannot be negative (got ${value})`,
+      CreditErrorCode.INVALID_AMOUNT,
+      { field, value, ...context }
+    );
+  }
+}
+function assertValidTierBalanceInput(input, context) {
+  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",
+      CreditErrorCode.INVALID_AMOUNT,
+      { balance: input.balance, balanceCap: input.balanceCap, ...context }
+    );
+  }
+  assertValidBalanceTarget(input.balanceCap, "balanceCap", context);
+}
 function assertRepresentableTierAmount(value, field, context) {
   if (value === Number.POSITIVE_INFINITY) return;
   assertRepresentableAmount(value, field, context);
@@ -714,9 +911,9 @@ var creditSystemConfigSchema = import_zod.z.object({
    */
   reservationExpiryMs: import_zod.z.number().positive().default(5 * 60 * 1e3),
   /**
-   * Default credits for new users (free tier)
+   * Default credits for new users (free tier). 0 means no signup grant.
    */
-  defaultFreeCredits: import_zod.z.number().positive().default(25),
+  defaultFreeCredits: import_zod.z.number().min(0).default(25),
   /**
    * Grace period in days after subscription expires before downgrade
    */
@@ -1088,9 +1285,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,
@@ -1100,12 +1299,16 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   assertRepresentableTierAmount,
   assertUnkeyedDirectReservation,
   assertUnreferencedDirectTransaction,
+  assertValidBalanceTarget,
   assertValidCreditAmount,
   assertValidIdempotencyKey,
   assertValidStoredAmount,
   assertValidStoredAmountRaw,
+  assertValidTierBalanceInput,
   backedBalanceFloor,
   calculateAvailableCredits,
+  canonicalAmount,
+  cappedBalance,
   classifyDatabaseError,
   commitReservationWithJournal,
   createDeferredExecutor,
@@ -1121,9 +1324,13 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   createUnsupportedOperationError,
   createUserNotFoundError,
   describePaymentMismatch,
+  expiredBackingPatch,
   genericDeferred,
   getSqlState,
   hasPlacedHold,
+  heldExpiredBacking,
+  holdExpiredBacking,
+  holdPlacedAtAfter,
   isCreditError,
   isCreditedOutcome,
   isIdempotencyConflictError,
@@ -1139,12 +1346,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,