@nehorai/credits 1.7.0 → 2.1.0

package/dist/service/index.js

@@ -1,3 +1,167 @@
+// src/core/errors.ts
+var CreditErrorCode = {
+  INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS",
+  RESERVATION_NOT_FOUND: "RESERVATION_NOT_FOUND",
+  RESERVATION_EXPIRED: "RESERVATION_EXPIRED",
+  RESERVATION_ALREADY_PROCESSED: "RESERVATION_ALREADY_PROCESSED",
+  USER_NOT_FOUND: "USER_NOT_FOUND",
+  INVALID_OPERATION_TYPE: "INVALID_OPERATION_TYPE",
+  CONFIGURATION_ERROR: "CONFIGURATION_ERROR",
+  DATABASE_ERROR: "DATABASE_ERROR",
+  /** Caller reused an idempotency key with a different immutable payload. */
+  IDEMPOTENCY_CONFLICT: "IDEMPOTENCY_CONFLICT",
+  /**
+   * Retryable infrastructure failure — serialization/deadlock, lock timeout,
+   * connection loss, pool exhaustion. Distinct from `DATABASE_ERROR`, which is
+   * a deterministic failure that will fail again identically on retry.
+   */
+  TRANSIENT_ERROR: "TRANSIENT_ERROR",
+  /** The configured repository adapter does not implement the requested V2 method. */
+  UNSUPPORTED_OPERATION: "UNSUPPORTED_OPERATION",
+  /** Amount was not a finite positive number. */
+  INVALID_AMOUNT: "INVALID_AMOUNT",
+  /** Idempotency key was supplied but empty or whitespace-only. */
+  INVALID_IDEMPOTENCY_KEY: "INVALID_IDEMPOTENCY_KEY",
+  /**
+   * A persisted reservation holds a status this library does not define, so no
+   * transition can reason about it. Quarantined rather than cast; nothing moved.
+   */
+  CORRUPT_RESERVATION_STATUS: "CORRUPT_RESERVATION_STATUS",
+  /**
+   * A persisted reservation does not record that its hold was placed
+   * atomically, so the credits it claims are not known to be reserved. Moving
+   * it would spend another hold's coverage; nothing moved.
+   */
+  UNBACKED_RESERVATION: "UNBACKED_RESERVATION"
+};
+var CreditError = class _CreditError extends Error {
+  code;
+  details;
+  constructor(message, code, details) {
+    super(message);
+    this.name = "CreditError";
+    this.code = code;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _CreditError);
+    }
+  }
+  /**
+   * Convert to JSON-serializable object
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      ...this.details && { details: this.details }
+    };
+  }
+};
+function isCreditError(error) {
+  return error instanceof CreditError;
+}
+function isInsufficientCreditsError(error) {
+  if (isCreditError(error)) {
+    return error.code === CreditErrorCode.INSUFFICIENT_CREDITS;
+  }
+  if (error instanceof Error) {
+    return error.message.toLowerCase().includes("insufficient credits");
+  }
+  return false;
+}
+function createInsufficientCreditsError(required, available) {
+  return new CreditError(
+    `Insufficient credits: available ${available}, required ${required}`,
+    CreditErrorCode.INSUFFICIENT_CREDITS,
+    { required, available, shortfall: sumAmounts(required, -available) }
+  );
+}
+function createReservationNotFoundError(reservationId) {
+  return new CreditError(
+    `Reservation ${reservationId} not found`,
+    CreditErrorCode.RESERVATION_NOT_FOUND,
+    { reservationId }
+  );
+}
+function createReservationAlreadyProcessedError(reservationId, status) {
+  return new CreditError(
+    `Reservation ${reservationId} has already been ${status}`,
+    CreditErrorCode.RESERVATION_ALREADY_PROCESSED,
+    { reservationId, status }
+  );
+}
+function createIdempotencyConflictError(idempotencyKey, details) {
+  return new CreditError(
+    `Idempotency key ${idempotencyKey} was reused with a different payload`,
+    CreditErrorCode.IDEMPOTENCY_CONFLICT,
+    { idempotencyKey, ...details }
+  );
+}
+function createUnsupportedOperationError(operation, hint) {
+  return new CreditError(
+    hint ? `Repository does not support ${operation}. ${hint}` : `Repository does not support ${operation}`,
+    CreditErrorCode.UNSUPPORTED_OPERATION,
+    { operation, ...hint ? { hint } : {} }
+  );
+}
+
+// src/core/amount.ts
+var CREDIT_AMOUNT_SCALE = 2;
+var CREDIT_AMOUNT_MAX = 999999999999e-2;
+var MAX_CENTS = 999999999999;
+function toCents(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const cents = Math.round(value * 100);
+  if (!Number.isSafeInteger(cents)) return null;
+  return value === cents / 100 ? cents : null;
+}
+function sumAmounts(...values) {
+  let cents = 0;
+  for (const value of values) {
+    const valueCents = toCents(value);
+    if (valueCents === null) return floatSum(values);
+    cents += valueCents;
+  }
+  return Number.isSafeInteger(cents) ? cents / 100 : floatSum(values);
+}
+function floatSum(values) {
+  let total = 0;
+  for (const value of values) total += value;
+  return total;
+}
+function isValidCreditAmount(value) {
+  if (typeof value !== "number") return false;
+  const cents = toCents(value);
+  return cents !== null && cents > 0 && cents <= MAX_CENTS;
+}
+function assertValidCreditAmount(value, context) {
+  if (isValidCreditAmount(value)) return;
+  throw new CreditError(
+    creditAmountReason(value),
+    CreditErrorCode.INVALID_AMOUNT,
+    { amount: value, max: CREDIT_AMOUNT_MAX, scale: CREDIT_AMOUNT_SCALE, ...context }
+  );
+}
+function creditAmountReason(value) {
+  if (typeof value !== "number") {
+    return `Credit amount must be a number (got ${typeof value})`;
+  }
+  if (!Number.isFinite(value)) {
+    return `Credit amount must be finite (got ${String(value)})`;
+  }
+  if (value <= 0) {
+    return `Credit amount must be greater than zero (got ${value})`;
+  }
+  if (value > CREDIT_AMOUNT_MAX) {
+    return `Credit amount ${value} exceeds the maximum of ${CREDIT_AMOUNT_MAX}`;
+  }
+  return `Credit amount ${value} is not exact to ${CREDIT_AMOUNT_SCALE} decimal places`;
+}
+function storedMonthlyLimit(limit) {
+  return Number.isFinite(limit) ? limit : CREDIT_AMOUNT_MAX;
+}
+
 // src/core/types.ts
 function toDate(value) {
   if (value instanceof Date) {
@@ -12,32 +176,6 @@ function toDate(value) {
   return /* @__PURE__ */ new Date();
 }
 
-// src/repository/types.ts
-function toClientUserCredits(credits) {
-  return {
-    userId: credits.userId,
-    balance: credits.balance,
-    bonusCredits: credits.bonusCredits ?? 0,
-    reserved: credits.reserved,
-    tier: credits.tier,
-    monthlyLimit: credits.monthlyLimit,
-    monthlyUsed: credits.monthlyUsed,
-    monthlyResetAt: toISOString(credits.monthlyResetAt),
-    subscriptionExpiresAt: credits.subscriptionExpiresAt ? toISOString(credits.subscriptionExpiresAt) : null,
-    createdAt: toISOString(credits.createdAt),
-    updatedAt: toISOString(credits.updatedAt)
-  };
-}
-function toISOString(value) {
-  if (!value) return (/* @__PURE__ */ new Date()).toISOString();
-  if (typeof value === "string") return value;
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "object" && "toDate" in value && typeof value.toDate === "function") {
-    return value.toDate().toISOString();
-  }
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-
 // src/config/index.ts
 import { z } from "zod";
 
@@ -61,11 +199,13 @@ var creditSystemConfigSchema = z.object({
   /**
    * Operation costs in credits
    * Keys are operation type names (any non-empty string)
-   * Values are positive numbers representing credit cost
+   * Values are non-negative numbers representing credit cost. 0 marks a free
+   * operation: `withCredits` runs it without touching the ledger. Amounts that
+   * move credits stay strictly positive, so `reserveCredits` refuses a 0.
    */
   operationCosts: z.record(
     z.string().min(1),
-    z.number().positive()
+    z.number().nonnegative()
   ),
   /**
    * Display labels for operation types (English canonical labels).
@@ -333,6 +473,178 @@ function getOperationLabel(operationType) {
 }
 initializeConfig();
 
+// src/core/payment-ref.ts
+function normalizePaymentRef(ref) {
+  if (typeof ref !== "string") return void 0;
+  const trimmed = ref.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+
+// src/repository/types.ts
+function supportsCreditsV2(repository) {
+  return typeof repository.reserveCreditsV2 === "function" && typeof repository.commitReservationV2 === "function" && typeof repository.releaseReservationV2 === "function" && typeof repository.expireReservationV2 === "function";
+}
+function supportsIdempotentCredit(repository) {
+  return typeof repository.addCreditsV2 === "function";
+}
+function toClientUserCredits(credits) {
+  return {
+    userId: credits.userId,
+    balance: credits.balance,
+    bonusCredits: credits.bonusCredits ?? 0,
+    reserved: credits.reserved,
+    tier: credits.tier,
+    monthlyLimit: credits.monthlyLimit,
+    monthlyUsed: credits.monthlyUsed,
+    monthlyResetAt: toISOString(credits.monthlyResetAt),
+    subscriptionExpiresAt: credits.subscriptionExpiresAt ? toISOString(credits.subscriptionExpiresAt) : null,
+    createdAt: toISOString(credits.createdAt),
+    updatedAt: toISOString(credits.updatedAt)
+  };
+}
+function toISOString(value) {
+  if (!value) return (/* @__PURE__ */ new Date()).toISOString();
+  if (typeof value === "string") return value;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object" && "toDate" in value && typeof value.toDate === "function") {
+    return value.toDate().toISOString();
+  }
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/repository/flow.ts
+async function reserveThroughRepository(repository, input) {
+  const v2 = supportsCreditsV2(repository);
+  if (!v2 && input.idempotencyKey !== void 0) {
+    throw createUnsupportedOperationError(
+      "reserveCredits with an idempotencyKey",
+      "This repository does not implement the V2 boundary, so it cannot enforce idempotency keys. Use a V2 repository (check with supportsCreditsV2) or omit the key and accept at-least-once holds."
+    );
+  }
+  assertValidCreditAmount(input.amount, { userId: input.userId });
+  if (v2) {
+    return repository.reserveCreditsV2(input);
+  }
+  try {
+    const reservation = await repository.reserveCreditsAtomic(
+      input.userId,
+      input.amount,
+      input.operationType,
+      input.expiresAt
+    );
+    return { outcome: "created", reservation };
+  } catch (error) {
+    if (!isInsufficientCreditsError(error)) throw error;
+    const credits = await repository.getUserCredits(input.userId);
+    const available = credits ? sumAmounts(credits.balance, credits.bonusCredits, -credits.reserved) : 0;
+    return {
+      outcome: "insufficient",
+      available,
+      required: input.amount,
+      shortfall: Math.max(sumAmounts(input.amount, -available), 0)
+    };
+  }
+}
+async function commitThroughRepository(repository, userId, reservationId, options) {
+  if (supportsCreditsV2(repository)) {
+    return repository.commitReservationV2(userId, reservationId, options);
+  }
+  const reservation = await repository.getReservation(userId, reservationId);
+  if (!reservation) return { outcome: "not_found", reservationId };
+  if (reservation.status !== "reserved") {
+    return {
+      outcome: "already_terminal",
+      reservation,
+      terminalStatus: reservation.status
+    };
+  }
+  await repository.commitReservationAtomic(userId, reservationId);
+  const credits = await repository.getUserCredits(userId);
+  const balanceAfter = credits ? sumAmounts(credits.balance, credits.bonusCredits) : 0;
+  const entry = await repository.createJournalEntry({
+    userId,
+    entryType: "debit",
+    amount: reservation.amount,
+    balanceAfter,
+    source: "operation_commit",
+    referenceId: reservationId,
+    referenceType: "reservation",
+    description: options?.description ?? `Committed ${reservation.amount} credits for ${getOperationLabel(reservation.operationType)}`,
+    // Deterministic fields last: they carry the identity of the event, and a
+    // caller who happens to send an `operationType` or an `amount` must not
+    // relabel what actually moved.
+    metadata: {
+      ...options?.metadata,
+      operationType: reservation.operationType,
+      amount: reservation.amount
+    }
+  });
+  return {
+    outcome: "committed",
+    reservation: { ...reservation, status: "committed" },
+    amount: reservation.amount,
+    balanceAfter,
+    journalEntryId: entry.id
+  };
+}
+async function releaseThroughRepository(repository, userId, reservationId, options) {
+  if (supportsCreditsV2(repository)) {
+    return repository.releaseReservationV2(userId, reservationId, options);
+  }
+  const reservation = await repository.getReservation(userId, reservationId);
+  if (!reservation) {
+    await repository.releaseReservationAtomic(userId, reservationId);
+    return { outcome: "not_found", reservationId };
+  }
+  if (reservation.status !== "reserved") {
+    await repository.releaseReservationAtomic(userId, reservationId).catch(() => void 0);
+    return {
+      outcome: "already_terminal",
+      reservation,
+      terminalStatus: reservation.status
+    };
+  }
+  await repository.releaseReservationAtomic(userId, reservationId);
+  const credits = await repository.getUserCredits(userId);
+  const entry = await repository.createJournalEntry({
+    userId,
+    entryType: "credit",
+    // No credits changed hands — the hold just moved back into "available".
+    amount: 0,
+    balanceAfter: credits ? sumAmounts(credits.balance, credits.bonusCredits) : 0,
+    source: "operation_release",
+    referenceId: reservationId,
+    referenceType: "reservation",
+    description: options?.description ?? `Released ${reservation.amount} reserved credits for ${getOperationLabel(reservation.operationType)}`,
+    metadata: {
+      ...options?.metadata,
+      operationType: reservation.operationType,
+      amount: reservation.amount
+    }
+  });
+  return {
+    outcome: "released",
+    reservation: { ...reservation, status: "released" },
+    amount: reservation.amount,
+    journalEntryId: entry.id
+  };
+}
+async function addCreditsThroughRepository(repository, input) {
+  assertValidCreditAmount(input.amount, { userId: input.userId, operation: "addCredits" });
+  const paymentRef = normalizePaymentRef(input.paymentRef);
+  if (supportsIdempotentCredit(repository)) {
+    return repository.addCreditsV2({ ...input, paymentRef });
+  }
+  await repository.addCreditsAtomic(
+    input.userId,
+    input.amount,
+    input.description,
+    paymentRef,
+    input.options
+  );
+  return paymentRef ? { outcome: "created", paymentRef } : { outcome: "created" };
+}
+
 // src/service/credits-service.ts
 function isPastMonthlyReset(resetAt) {
   if (!resetAt) return false;
@@ -377,28 +689,38 @@ var CreditsService = class {
         userId,
         getConfig().subscriptionGracePeriodDays
       );
-      if (expiryResult.wasDowngraded) {
+      if (expiryResult.wasDowngraded && !expiryResult.journaled) {
         await this.repository.createJournalEntry({
           userId,
           entryType: "debit",
           amount: 0,
           // No credits deducted, just tier change
-          balanceAfter: expiryResult.credits.balance,
+          // The ledger balance, matching every other journal writer: the V2
+          // transitions and add/deduct all record `balance + bonusCredits`, so
+          // recording `balance` alone made the audit trail disagree with itself
+          // for any user holding bonus credits.
+          balanceAfter: sumAmounts(
+            expiryResult.credits.balance,
+            expiryResult.credits.bonusCredits
+          ),
           source: "subscription_downgrade",
           referenceId: `downgrade-${Date.now()}`,
           referenceType: "subscription",
-          description: `Subscription expired. Downgraded from ${data.tier} to free tier.`,
+          // The tier actually landed on, not a hard-coded "free": the downgrade
+          // target is configurable, so naming `free` here could describe a
+          // transition that never happened.
+          description: `Subscription expired. Downgraded from ${data.tier} to ${expiryResult.credits.tier} tier.`,
           metadata: {
             previousTier: data.tier,
             previousBalance: data.balance,
             newBalance: expiryResult.credits.balance
           }
         });
-        if (this.subscriptionExpiredCallback) {
-          this.subscriptionExpiredCallback(userId, true).catch((error) => {
-            console.error("[Credits] Failed to send subscription expired notification:", error);
-          });
-        }
+      }
+      if (expiryResult.wasDowngraded && this.subscriptionExpiredCallback) {
+        this.subscriptionExpiredCallback(userId, true).catch((error) => {
+          console.error("[Credits] Failed to send subscription expired notification:", error);
+        });
       }
       data = expiryResult.credits;
     }
@@ -409,14 +731,17 @@ var CreditsService = class {
         data.tier,
         expectedResetAt
       );
-      if (resetResult.wasReset) {
-        const balanceChange = resetResult.credits.balance - data.balance;
+      if (resetResult.wasReset && !resetResult.journaled) {
+        const balanceChange = sumAmounts(resetResult.credits.balance, -data.balance);
         if (balanceChange !== 0) {
           await this.repository.createJournalEntry({
             userId,
             entryType: balanceChange > 0 ? "credit" : "debit",
             amount: Math.abs(balanceChange),
-            balanceAfter: resetResult.credits.balance,
+            balanceAfter: sumAmounts(
+              resetResult.credits.balance,
+              resetResult.credits.bonusCredits
+            ),
             source: "monthly_reset",
             referenceId: `reset-${Date.now()}`,
             referenceType: "reset",
@@ -467,14 +792,14 @@ var CreditsService = class {
    */
   async checkCredits(userId, requiredCredits) {
     const credits = await this.getOrCreateUserCredits(userId);
-    const totalBalance = credits.balance + credits.bonusCredits;
-    const available = totalBalance - credits.reserved;
+    const totalBalance = sumAmounts(credits.balance, credits.bonusCredits);
+    const available = sumAmounts(totalBalance, -credits.reserved);
     const hasCredits = available >= requiredCredits;
     return {
       hasCredits,
       balance: totalBalance,
       required: requiredCredits,
-      shortfall: hasCredits ? 0 : requiredCredits - available
+      shortfall: hasCredits ? 0 : sumAmounts(requiredCredits, -available)
     };
   }
   /**
@@ -488,74 +813,110 @@ var CreditsService = class {
    * @throws Error if insufficient credits
    */
   async reserveCredits(userId, amount, operationType, options) {
+    const outcome = await this.reserveCreditsDetailed(userId, amount, operationType, options);
+    if (outcome.outcome === "created" || outcome.outcome === "replayed") {
+      return outcome.reservation;
+    }
+    if (outcome.outcome === "insufficient") {
+      throw createInsufficientCreditsError(outcome.required, outcome.available);
+    }
+    throw createIdempotencyConflictError(outcome.idempotencyKey, {
+      userId,
+      requested: { amount, operationType },
+      existing: {
+        amount: outcome.existing.amount,
+        operationType: outcome.existing.operationType
+      }
+    });
+  }
+  /**
+   * Reserve credits and get the typed outcome instead of an exception.
+   *
+   * Prefer this over {@link reserveCredits} in async callers: it distinguishes
+   * a fresh hold from an idempotent replay, and reports insufficient funds as
+   * a value rather than as control flow.
+   */
+  async reserveCreditsDetailed(userId, amount, operationType, options) {
     const ttlMs = options?.ttlMs ?? getConfig().reservationExpiryMs;
     const expiresAt = new Date(Date.now() + ttlMs);
-    return this.repository.reserveCreditsAtomic(userId, amount, operationType, expiresAt);
+    return reserveThroughRepository(this.repository, {
+      userId,
+      amount,
+      operationType,
+      expiresAt,
+      idempotencyKey: options?.idempotencyKey
+    });
   }
   /**
-   * Commit a reservation (phase 2 of two-phase commit - success)
-   * Deducts credits and marks reservation as committed
-   * Also triggers low balance notifications if balance drops below threshold
+   * Commit a reservation (phase 2 of two-phase commit - success).
+   *
+   * Idempotent: re-delivering a commit for an already-committed reservation is
+   * a no-op. Committing one that was released or expired throws, because the
+   * credits are no longer held and pretending otherwise would hide a real bug.
    */
-  async commitCredits(userId, reservationId) {
-    const reservation = await this.repository.getReservation(userId, reservationId);
-    if (!reservation) {
-      throw new Error(`Reservation ${reservationId} not found`);
+  async commitCredits(userId, reservationId, options) {
+    const outcome = await this.commitCreditsDetailed(userId, reservationId, options);
+    if (outcome.outcome === "not_found") {
+      throw createReservationNotFoundError(reservationId);
     }
-    if (reservation.status === "committed") {
-      return;
+    if (outcome.outcome === "already_terminal" && outcome.terminalStatus !== "committed") {
+      throw createReservationAlreadyProcessedError(reservationId, outcome.terminalStatus);
     }
-    await this.repository.commitReservationAtomic(userId, reservationId);
-    const credits = await this.repository.getUserCredits(userId);
-    if (credits) {
-      await this.repository.createJournalEntry({
-        userId,
-        entryType: "debit",
-        amount: reservation.amount,
-        balanceAfter: credits.balance,
-        source: "operation_commit",
-        referenceId: reservationId,
-        referenceType: "reservation",
-        description: `Committed ${reservation.amount} credits for ${getOperationLabel(reservation.operationType)}`,
-        metadata: {
-          operationType: reservation.operationType
-        }
+  }
+  /**
+   * Commit a reservation and get the typed outcome.
+   *
+   * Exactly one concurrent caller sees `committed`; that call moved the balance
+   * and wrote the single journal entry. On a V2 repository the journal is
+   * written inside the same transaction, so this method adds none of its own —
+   * the duplicate entry the previous implementation wrote is gone.
+   *
+   * The low-balance notification fires only for the winner, and only after the
+   * transaction has committed, so no callback runs inside a database
+   * transaction.
+   */
+  async commitCreditsDetailed(userId, reservationId, options) {
+    const outcome = await commitThroughRepository(
+      this.repository,
+      userId,
+      reservationId,
+      options
+    );
+    if (outcome.outcome === "committed" && this.lowBalanceCallback) {
+      this.lowBalanceCallback(userId, outcome.balanceAfter).catch((error) => {
+        console.error("[Credits] Failed to send low balance notification:", error);
       });
-      if (this.lowBalanceCallback) {
-        this.lowBalanceCallback(userId, credits.balance).catch((error) => {
-          console.error("[Credits] Failed to send low balance notification:", error);
-        });
-      }
     }
+    return outcome;
   }
   /**
-   * Release a reservation (phase 2 of two-phase commit - failure)
-   * Returns reserved credits and marks reservation as released
+   * Release a reservation (phase 2 of two-phase commit - failure).
+   *
+   * Throws `RESERVATION_NOT_FOUND` for an unknown reservation, matching the
+   * pre-V2 behaviour — a release naming a reservation that does not exist is a
+   * caller bug, and swallowing it hides the bug while the credits stay held.
+   *
+   * Releasing one that is already terminal — `released`, `expired`, or
+   * `committed` — is a no-op, which is the behaviour this method has always
+   * had. A release that loses a race to a concurrent commit is the common
+   * case in a retry-heavy caller, and callers written against the pre-V2
+   * contract handle it by not handling it.
+   *
+   * That does mean this method cannot tell you that the credits were spent
+   * rather than returned. Use {@link releaseCreditsDetailed}, which reports
+   * `already_terminal` with `terminalStatus: 'committed'`, when you need to
+   * branch on it.
    */
-  async releaseCredits(userId, reservationId) {
-    const reservation = await this.repository.getReservation(userId, reservationId);
-    await this.repository.releaseReservationAtomic(userId, reservationId);
-    if (reservation?.status === "reserved") {
-      const credits = await this.repository.getUserCredits(userId);
-      if (credits) {
-        await this.repository.createJournalEntry({
-          userId,
-          entryType: "credit",
-          amount: 0,
-          // No actual credits returned (they were reserved, not spent)
-          balanceAfter: credits.balance,
-          source: "operation_release",
-          referenceId: reservationId,
-          referenceType: "reservation",
-          description: `Released ${reservation.amount} reserved credits for ${getOperationLabel(reservation.operationType)}`,
-          metadata: {
-            operationType: reservation.operationType,
-            amount: reservation.amount
-          }
-        });
-      }
+  async releaseCredits(userId, reservationId, options) {
+    const outcome = await this.releaseCreditsDetailed(userId, reservationId, options);
+    if (outcome.outcome === "not_found") {
+      throw createReservationNotFoundError(reservationId);
     }
   }
+  /** Release a reservation and get the typed outcome. */
+  async releaseCreditsDetailed(userId, reservationId, options) {
+    return releaseThroughRepository(this.repository, userId, reservationId, options);
+  }
   /**
    * Log usage for audit trail
    * @param log - Usage log data
@@ -571,9 +932,20 @@ var CreditsService = class {
    * @param paymentRef - Optional payment reference
    * @param options - Optional journal source / reference type / extra metadata
    *   for the credit journal entry (e.g. revenue-attribution fields).
+   * @returns Whether this delivery credited the account (`created`), repeated an
+   *   earlier one (`replayed`), or reused the reference for a different credit
+   *   event (`conflict`, which credited nothing). On a repository without
+   *   `addCreditsV2` the result is always `created` and carries no
+   *   deduplication guarantee — see {@link addCreditsThroughRepository}.
    */
   async addCredits(userId, amount, description, paymentRef, options) {
-    return this.repository.addCreditsAtomic(userId, amount, description, paymentRef, options);
+    return addCreditsThroughRepository(this.repository, {
+      userId,
+      amount,
+      description,
+      paymentRef,
+      options
+    });
   }
   /**
    * One-shot atomic "deduct-if-sufficient" credit charge.
@@ -597,15 +969,14 @@ var CreditsService = class {
    * @throws Error if amount is not a positive number
    */
   async deductCredits(userId, amount, options) {
-    if (!(amount > 0)) {
-      throw new Error(`deductCredits amount must be positive (got ${amount})`);
-    }
+    assertValidCreditAmount(amount, { userId, operation: "deductCredits" });
     let deduction;
     try {
       deduction = await this.repository.deductCreditsAtomic(userId, amount);
     } catch (error) {
+      if (isCreditError(error) && error.code === CreditErrorCode.INVALID_AMOUNT) throw error;
       const credits = await this.repository.getUserCredits(userId);
-      const available = credits ? credits.balance + credits.bonusCredits - credits.reserved : 0;
+      const available = credits ? sumAmounts(credits.balance, credits.bonusCredits, -credits.reserved) : 0;
       if (available >= amount) {
         throw error;
       }
@@ -614,7 +985,7 @@ var CreditsService = class {
         reason: "insufficient",
         available,
         required: amount,
-        shortfall: amount - available
+        shortfall: sumAmounts(amount, -available)
       };
     }
     const operationType = options?.operationType;
@@ -628,8 +999,8 @@ var CreditsService = class {
       referenceType: "adjustment",
       description: operationType ? `Deducted ${amount} credits for ${getOperationLabel(operationType)}` : `Deducted ${amount} credits`,
       metadata: {
-        ...operationType && { operationType },
-        ...options?.metadata
+        ...options?.metadata,
+        ...operationType && { operationType }
       }
     });
     if (operationType) {
@@ -664,8 +1035,15 @@ var CreditsService = class {
     const free = isFreeTier(tier);
     await this.repository.updateUserTier(userId, {
       tier,
-      // Stored monthlyLimit uses the 0-means-unlimited convention.
-      monthlyLimit: unlimited ? 0 : monthlyLimit,
+      // Through the shared contract, like every path that resolves the tier's
+      // limit from configuration. (The repository's `updateUserCredits` and
+      // `updateUserTier` still store a caller-supplied `monthlyLimit` verbatim;
+      // they are given a value, not a tier, so there is no sentinel to map.)
+      // This used to store 0 for an unlimited tier under a "0 means unlimited"
+      // convention that nothing actually implemented — no read path anywhere in
+      // the library branches on it — so upgrading a user to unlimited gave them
+      // an allowance of zero.
+      monthlyLimit: storedMonthlyLimit(monthlyLimit),
       // Reset balance to new tier limit if upgrading
       balance: !free ? unlimited ? getUnlimitedSentinelBalance() : monthlyLimit : void 0,
       monthlyUsed: !free ? 0 : void 0,