@nehorai/credits 2.1.0 → 2.2.0

package/dist/core/index.cjs

@@ -36,12 +36,16 @@ __export(core_exports, {
   assertRepresentableTierAmount: () => assertRepresentableTierAmount,
   assertUnkeyedDirectReservation: () => assertUnkeyedDirectReservation,
   assertUnreferencedDirectTransaction: () => assertUnreferencedDirectTransaction,
+  assertValidBalanceTarget: () => assertValidBalanceTarget,
   assertValidCreditAmount: () => assertValidCreditAmount,
   assertValidIdempotencyKey: () => assertValidIdempotencyKey,
   assertValidStoredAmount: () => assertValidStoredAmount,
   assertValidStoredAmountRaw: () => assertValidStoredAmountRaw,
+  assertValidTierBalanceInput: () => assertValidTierBalanceInput,
+  attributeExpiredBacking: () => attributeExpiredBacking,
   backedBalanceFloor: () => backedBalanceFloor,
   calculateAvailableCredits: () => calculateAvailableCredits,
+  cappedBalance: () => cappedBalance,
   classifyDatabaseError: () => classifyDatabaseError,
   commitReservationWithJournal: () => commitReservationWithJournal,
   createDeferredExecutor: () => createDeferredExecutor,
@@ -57,6 +61,7 @@ __export(core_exports, {
   createUnsupportedOperationError: () => createUnsupportedOperationError,
   createUserNotFoundError: () => createUserNotFoundError,
   describePaymentMismatch: () => describePaymentMismatch,
+  expiredHoldBackingPatch: () => expiredHoldBackingPatch,
   genericDeferred: () => genericDeferred,
   getSqlState: () => getSqlState,
   hasPlacedHold: () => hasPlacedHold,
@@ -78,9 +83,14 @@ __export(core_exports, {
   noopDeferred: () => noopDeferred,
   normalizePaymentRef: () => normalizePaymentRef,
   numericToCents: () => numericToCents,
+  planBalanceCap: () => planBalanceCap,
+  planBalanceTarget: () => planBalanceTarget,
+  planHoldCommit: () => planHoldCommit,
   releaseReservationWithJournal: () => releaseReservationWithJournal,
   reserveCreditsForOperation: () => reserveCreditsForOperation,
   sameAmount: () => sameAmount,
+  settleExpiredHoldBacking: () => settleExpiredHoldBacking,
+  spendableBalance: () => spendableBalance,
   storedMonthlyLimit: () => storedMonthlyLimit,
   sumAmounts: () => sumAmounts,
   synchronousDeferred: () => synchronousDeferred,
@@ -312,6 +322,86 @@ 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 spendableBalance(balance, expiredHoldBacking = 0) {
+  return sumAmounts(balance, -Math.min(expiredHoldBacking, balance));
+}
+function planBalanceTarget(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) {
+  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 = Math.min(expiredHoldBacking, balance);
+  const used = 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
+  };
+}
+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);
+  }
+  for (const hold of placed) {
+    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;
+}
+function expiredHoldBackingPatch(next, stored = 0) {
+  return next > 0 || stored > 0 ? { expiredHoldBacking: next } : {};
+}
+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) 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 +804,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
    */
@@ -1100,12 +1190,16 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   assertRepresentableTierAmount,
   assertUnkeyedDirectReservation,
   assertUnreferencedDirectTransaction,
+  assertValidBalanceTarget,
   assertValidCreditAmount,
   assertValidIdempotencyKey,
   assertValidStoredAmount,
   assertValidStoredAmountRaw,
+  assertValidTierBalanceInput,
+  attributeExpiredBacking,
   backedBalanceFloor,
   calculateAvailableCredits,
+  cappedBalance,
   classifyDatabaseError,
   commitReservationWithJournal,
   createDeferredExecutor,
@@ -1121,6 +1215,7 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   createUnsupportedOperationError,
   createUserNotFoundError,
   describePaymentMismatch,
+  expiredHoldBackingPatch,
   genericDeferred,
   getSqlState,
   hasPlacedHold,
@@ -1142,9 +1237,14 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   noopDeferred,
   normalizePaymentRef,
   numericToCents,
+  planBalanceCap,
+  planBalanceTarget,
+  planHoldCommit,
   releaseReservationWithJournal,
   reserveCreditsForOperation,
   sameAmount,
+  settleExpiredHoldBacking,
+  spendableBalance,
   storedMonthlyLimit,
   sumAmounts,
   synchronousDeferred,