@nehorai/credits 2.2.0 → 3.1.0

package/dist/adapters/index.cjs

@@ -27,6 +27,166 @@ module.exports = __toCommonJS(adapters_exports);
 // src/config/index.ts
 var import_zod = require("zod");
 
+// 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 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;
+}
+var FLOAT_NOISE_RELATIVE = 64 * Number.EPSILON;
+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 isRepresentableAmount(value) {
+  if (typeof value !== "number") return false;
+  const cents = toCents(value);
+  return cents !== null && Math.abs(cents) <= MAX_CENTS;
+}
+
 // src/config/provider.ts
 var configProvider = null;
 function getConfigProvider() {
@@ -183,17 +343,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");
@@ -287,160 +455,6 @@ function getOperationLabel(operationType) {
 }
 initializeConfig();
 
-// 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 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`;
-}
-
 // src/repository/types.ts
 function supportsCreditsV2(repository) {
   return typeof repository.reserveCreditsV2 === "function" && typeof repository.commitReservationV2 === "function" && typeof repository.releaseReservationV2 === "function" && typeof repository.expireReservationV2 === "function";