@nehorai/credits 1.2.0 → 1.4.0

package/dist/auth/{api-key.d.ts → index.d.cts}

@@ -1,4 +1,6 @@
-import type { ICreditsAuthProvider, CreditsUser } from "./types.js";
+import { I as ICreditsAuthProvider, a as CreditsUser } from '../types-OZU3I5OM.cjs';
+export { C as CreditsAuthProviderFactory } from '../types-OZU3I5OM.cjs';
+
 /**
  * Verify a Bearer token from an Authorization header
  *
@@ -6,14 +8,14 @@ import type { ICreditsAuthProvider, CreditsUser } from "./types.js";
  * @param secret - The expected secret value
  * @returns True if token is valid
  */
-export declare function verifyBearerToken(header: string | null, secret: string): boolean;
+declare function verifyBearerToken(header: string | null, secret: string): boolean;
 /**
  * API Key auth provider for admin routes
  *
  * Uses Bearer token authentication for external API access
  * The API key is stored in CREDITS_ADMIN_API_KEY environment variable
  */
-export declare class ApiKeyCreditsProvider implements ICreditsAuthProvider {
+declare class ApiKeyCreditsProvider implements ICreditsAuthProvider {
     private readonly apiKey;
     private isValidated;
     constructor(authHeader?: string | null, apiKey?: string);
@@ -26,12 +28,13 @@ export declare class ApiKeyCreditsProvider implements ICreditsAuthProvider {
  * @param apiKey - Optional API key to use (defaults to CREDITS_ADMIN_API_KEY env var)
  * @returns True if API key is valid
  */
-export declare function verifyAdminApiKey(authHeader: string | null, apiKey?: string): boolean;
+declare function verifyAdminApiKey(authHeader: string | null, apiKey?: string): boolean;
 /**
  * Create an API key auth provider from a request
  * @param request - Request object with headers
  * @param apiKey - Optional API key to use
  * @returns API key auth provider
  */
-export declare function createApiKeyProvider(request: Request, apiKey?: string): ApiKeyCreditsProvider;
-//# sourceMappingURL=api-key.d.ts.map
+declare function createApiKeyProvider(request: Request, apiKey?: string): ApiKeyCreditsProvider;
+
+export { ApiKeyCreditsProvider, CreditsUser, ICreditsAuthProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken };

package/dist/auth/index.d.ts

@@ -1,8 +1,40 @@
+import { I as ICreditsAuthProvider, a as CreditsUser } from '../types-OZU3I5OM.js';
+export { C as CreditsAuthProviderFactory } from '../types-OZU3I5OM.js';
+
 /**
- * Credits auth providers - barrel exports
+ * Verify a Bearer token from an Authorization header
  *
- * Provides authentication abstraction for credits system
+ * @param header - The Authorization header value (e.g., "Bearer secret123")
+ * @param secret - The expected secret value
+ * @returns True if token is valid
  */
-export type { ICreditsAuthProvider, CreditsAuthProviderFactory, CreditsUser, } from "./types.js";
-export { ApiKeyCreditsProvider, verifyAdminApiKey, createApiKeyProvider, verifyBearerToken, } from "./api-key.js";
-//# sourceMappingURL=index.d.ts.map
+declare function verifyBearerToken(header: string | null, secret: string): boolean;
+/**
+ * API Key auth provider for admin routes
+ *
+ * Uses Bearer token authentication for external API access
+ * The API key is stored in CREDITS_ADMIN_API_KEY environment variable
+ */
+declare class ApiKeyCreditsProvider implements ICreditsAuthProvider {
+    private readonly apiKey;
+    private isValidated;
+    constructor(authHeader?: string | null, apiKey?: string);
+    getCurrentUser(): Promise<CreditsUser | null>;
+    verifyAdminAccess(): Promise<boolean>;
+}
+/**
+ * Verify an API key from a request header
+ * @param authHeader - Authorization header value
+ * @param apiKey - Optional API key to use (defaults to CREDITS_ADMIN_API_KEY env var)
+ * @returns True if API key is valid
+ */
+declare function verifyAdminApiKey(authHeader: string | null, apiKey?: string): boolean;
+/**
+ * Create an API key auth provider from a request
+ * @param request - Request object with headers
+ * @param apiKey - Optional API key to use
+ * @returns API key auth provider
+ */
+declare function createApiKeyProvider(request: Request, apiKey?: string): ApiKeyCreditsProvider;
+
+export { ApiKeyCreditsProvider, CreditsUser, ICreditsAuthProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken };

package/dist/auth/index.js

@@ -1,8 +1,66 @@
-/**
- * Credits auth providers - barrel exports
- *
- * Provides authentication abstraction for credits system
- */
-// API Key implementation (for admin routes)
-export { ApiKeyCreditsProvider, verifyAdminApiKey, createApiKeyProvider, verifyBearerToken, } from "./api-key.js";
+// src/auth/api-key.ts
+function timingSafeEqual(a, b) {
+  if (!a || !b) {
+    return false;
+  }
+  const maxLength = Math.max(a.length, b.length);
+  const paddedA = a.padEnd(maxLength);
+  const paddedB = b.padEnd(maxLength);
+  let result = 0;
+  for (let i = 0; i < maxLength; i++) {
+    result |= paddedA.charCodeAt(i) ^ paddedB.charCodeAt(i);
+  }
+  return result === 0 && a.length === b.length;
+}
+function verifyBearerToken(header, secret) {
+  if (!header || !secret) {
+    return false;
+  }
+  const token = header.replace(/^Bearer\s+/i, "");
+  return timingSafeEqual(token, secret);
+}
+var ApiKeyCreditsProvider = class {
+  apiKey;
+  isValidated = false;
+  constructor(authHeader, apiKey) {
+    this.apiKey = apiKey ?? process.env.CREDITS_ADMIN_API_KEY;
+    if (authHeader && this.apiKey) {
+      this.isValidated = verifyBearerToken(authHeader, this.apiKey);
+    }
+  }
+  async getCurrentUser() {
+    if (!this.isValidated) {
+      return null;
+    }
+    return {
+      id: "api-admin",
+      email: "api@admin.internal",
+      name: "API Admin"
+    };
+  }
+  async verifyAdminAccess() {
+    return this.isValidated;
+  }
+};
+function verifyAdminApiKey(authHeader, apiKey) {
+  if (!authHeader) {
+    return false;
+  }
+  const expectedKey = apiKey ?? process.env.CREDITS_ADMIN_API_KEY;
+  if (!expectedKey) {
+    console.warn("CREDITS_ADMIN_API_KEY not configured");
+    return false;
+  }
+  return verifyBearerToken(authHeader, expectedKey);
+}
+function createApiKeyProvider(request, apiKey) {
+  const authHeader = request.headers.get("Authorization");
+  return new ApiKeyCreditsProvider(authHeader, apiKey);
+}
+export {
+  ApiKeyCreditsProvider,
+  createApiKeyProvider,
+  verifyAdminApiKey,
+  verifyBearerToken
+};
 //# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,4CAA4C;AAC5C,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,cAAc,CAAC"}
+{"version":3,"sources":["../../src/auth/api-key.ts"],"sourcesContent":["import type { ICreditsAuthProvider, CreditsUser } from \"./types.js\";\n\n/**\n * Timing-safe string comparison to prevent timing attacks\n */\nfunction timingSafeEqual(a: string, b: string): boolean {\n  if (!a || !b) {\n    return false;\n  }\n\n  // Pad strings to same length to prevent length-based timing attacks\n  const maxLength = Math.max(a.length, b.length);\n  const paddedA = a.padEnd(maxLength);\n  const paddedB = b.padEnd(maxLength);\n\n  let result = 0;\n  for (let i = 0; i < maxLength; i++) {\n    result |= paddedA.charCodeAt(i) ^ paddedB.charCodeAt(i);\n  }\n\n  // Also check that lengths were originally equal\n  return result === 0 && a.length === b.length;\n}\n\n/**\n * Verify a Bearer token from an Authorization header\n *\n * @param header - The Authorization header value (e.g., \"Bearer secret123\")\n * @param secret - The expected secret value\n * @returns True if token is valid\n */\nexport function verifyBearerToken(header: string | null, secret: string): boolean {\n  if (!header || !secret) {\n    return false;\n  }\n\n  // Extract token from \"Bearer {token}\" format\n  const token = header.replace(/^Bearer\\s+/i, \"\");\n\n  // Use timing-safe comparison\n  return timingSafeEqual(token, secret);\n}\n\n/**\n * API Key auth provider for admin routes\n *\n * Uses Bearer token authentication for external API access\n * The API key is stored in CREDITS_ADMIN_API_KEY environment variable\n */\nexport class ApiKeyCreditsProvider implements ICreditsAuthProvider {\n  private readonly apiKey: string | undefined;\n  private isValidated = false;\n\n  constructor(authHeader?: string | null, apiKey?: string) {\n    this.apiKey = apiKey ?? process.env.CREDITS_ADMIN_API_KEY;\n\n    // Validate the provided auth header using timing-safe comparison\n    if (authHeader && this.apiKey) {\n      this.isValidated = verifyBearerToken(authHeader, this.apiKey);\n    }\n  }\n\n  async getCurrentUser(): Promise<CreditsUser | null> {\n    if (!this.isValidated) {\n      return null;\n    }\n\n    // API key auth returns a special \"admin\" user\n    return {\n      id: \"api-admin\",\n      email: \"api@admin.internal\",\n      name: \"API Admin\",\n    };\n  }\n\n  async verifyAdminAccess(): Promise<boolean> {\n    return this.isValidated;\n  }\n}\n\n/**\n * Verify an API key from a request header\n * @param authHeader - Authorization header value\n * @param apiKey - Optional API key to use (defaults to CREDITS_ADMIN_API_KEY env var)\n * @returns True if API key is valid\n */\nexport function verifyAdminApiKey(authHeader: string | null, apiKey?: string): boolean {\n  if (!authHeader) {\n    return false;\n  }\n\n  const expectedKey = apiKey ?? process.env.CREDITS_ADMIN_API_KEY;\n  if (!expectedKey) {\n    console.warn(\"CREDITS_ADMIN_API_KEY not configured\");\n    return false;\n  }\n\n  // Use timing-safe comparison to prevent timing attacks\n  return verifyBearerToken(authHeader, expectedKey);\n}\n\n/**\n * Create an API key auth provider from a request\n * @param request - Request object with headers\n * @param apiKey - Optional API key to use\n * @returns API key auth provider\n */\nexport function createApiKeyProvider(request: Request, apiKey?: string): ApiKeyCreditsProvider {\n  const authHeader = request.headers.get(\"Authorization\");\n  return new ApiKeyCreditsProvider(authHeader, apiKey);\n}\n"],"mappings":";AAKA,SAAS,gBAAgB,GAAW,GAAoB;AACtD,MAAI,CAAC,KAAK,CAAC,GAAG;AACZ,WAAO;AAAA,EACT;AAGA,QAAM,YAAY,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM;AAC7C,QAAM,UAAU,EAAE,OAAO,SAAS;AAClC,QAAM,UAAU,EAAE,OAAO,SAAS;AAElC,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,WAAW,KAAK;AAClC,cAAU,QAAQ,WAAW,CAAC,IAAI,QAAQ,WAAW,CAAC;AAAA,EACxD;AAGA,SAAO,WAAW,KAAK,EAAE,WAAW,EAAE;AACxC;AASO,SAAS,kBAAkB,QAAuB,QAAyB;AAChF,MAAI,CAAC,UAAU,CAAC,QAAQ;AACtB,WAAO;AAAA,EACT;AAGA,QAAM,QAAQ,OAAO,QAAQ,eAAe,EAAE;AAG9C,SAAO,gBAAgB,OAAO,MAAM;AACtC;AAQO,IAAM,wBAAN,MAA4D;AAAA,EAChD;AAAA,EACT,cAAc;AAAA,EAEtB,YAAY,YAA4B,QAAiB;AACvD,SAAK,SAAS,UAAU,QAAQ,IAAI;AAGpC,QAAI,cAAc,KAAK,QAAQ;AAC7B,WAAK,cAAc,kBAAkB,YAAY,KAAK,MAAM;AAAA,IAC9D;AAAA,EACF;AAAA,EAEA,MAAM,iBAA8C;AAClD,QAAI,CAAC,KAAK,aAAa;AACrB,aAAO;AAAA,IACT;AAGA,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,MAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,oBAAsC;AAC1C,WAAO,KAAK;AAAA,EACd;AACF;AAQO,SAAS,kBAAkB,YAA2B,QAA0B;AACrF,MAAI,CAAC,YAAY;AACf,WAAO;AAAA,EACT;AAEA,QAAM,cAAc,UAAU,QAAQ,IAAI;AAC1C,MAAI,CAAC,aAAa;AAChB,YAAQ,KAAK,sCAAsC;AACnD,WAAO;AAAA,EACT;AAGA,SAAO,kBAAkB,YAAY,WAAW;AAClD;AAQO,SAAS,qBAAqB,SAAkB,QAAwC;AAC7F,QAAM,aAAa,QAAQ,QAAQ,IAAI,eAAe;AACtD,SAAO,IAAI,sBAAsB,YAAY,MAAM;AACrD;","names":[]}

package/dist/core/index.cjs

@@ -0,0 +1,522 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/index.ts
+var core_exports = {};
+__export(core_exports, {
+  CreditError: () => CreditError,
+  CreditErrorCode: () => CreditErrorCode,
+  calculateAvailableCredits: () => calculateAvailableCredits,
+  commitReservationWithJournal: () => commitReservationWithJournal,
+  createDeferredExecutor: () => createDeferredExecutor,
+  createInsufficientCreditsError: () => createInsufficientCreditsError,
+  createInvalidOperationTypeError: () => createInvalidOperationTypeError,
+  createReservationAlreadyProcessedError: () => createReservationAlreadyProcessedError,
+  createReservationExpiredError: () => createReservationExpiredError,
+  createReservationNotFoundError: () => createReservationNotFoundError,
+  createUserNotFoundError: () => createUserNotFoundError,
+  genericDeferred: () => genericDeferred,
+  isCreditError: () => isCreditError,
+  isInsufficientCreditsError: () => isInsufficientCreditsError,
+  noopDeferred: () => noopDeferred,
+  releaseReservationWithJournal: () => releaseReservationWithJournal,
+  reserveCreditsForOperation: () => reserveCreditsForOperation,
+  synchronousDeferred: () => synchronousDeferred,
+  toDate: () => toDate,
+  toPortableTimestamp: () => toPortableTimestamp
+});
+module.exports = __toCommonJS(core_exports);
+
+// src/core/types.ts
+function calculateAvailableCredits(balance, bonusCredits, reserved) {
+  return balance + bonusCredits - reserved;
+}
+function toPortableTimestamp(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" && value !== null && "toDate" in value && typeof value.toDate === "function") {
+    return value.toDate().toISOString();
+  }
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function toDate(value) {
+  if (value instanceof Date) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return new Date(value);
+  }
+  if (typeof value === "object" && value !== null && "toDate" in value && typeof value.toDate === "function") {
+    return value.toDate();
+  }
+  return /* @__PURE__ */ new Date();
+}
+
+// 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"
+};
+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: required - available }
+  );
+}
+function createReservationNotFoundError(reservationId) {
+  return new CreditError(
+    `Reservation ${reservationId} not found`,
+    CreditErrorCode.RESERVATION_NOT_FOUND,
+    { reservationId }
+  );
+}
+function createReservationExpiredError(reservationId) {
+  return new CreditError(
+    `Reservation ${reservationId} has expired`,
+    CreditErrorCode.RESERVATION_EXPIRED,
+    { reservationId }
+  );
+}
+function createReservationAlreadyProcessedError(reservationId, status) {
+  return new CreditError(
+    `Reservation ${reservationId} has already been ${status}`,
+    CreditErrorCode.RESERVATION_ALREADY_PROCESSED,
+    { reservationId, status }
+  );
+}
+function createUserNotFoundError(userId) {
+  return new CreditError(
+    `User ${userId} not found`,
+    CreditErrorCode.USER_NOT_FOUND,
+    { userId }
+  );
+}
+function createInvalidOperationTypeError(operationType, validTypes) {
+  return new CreditError(
+    `Invalid operation type: ${operationType}. Valid types: ${validTypes.join(", ")}`,
+    CreditErrorCode.INVALID_OPERATION_TYPE,
+    { operationType, validTypes }
+  );
+}
+
+// src/core/deferred.ts
+var genericDeferred = {
+  defer(fn) {
+    const scheduler = typeof setImmediate !== "undefined" ? setImmediate : setTimeout;
+    scheduler(() => {
+      fn().catch((error) => {
+        console.error("[Credits] Deferred task error:", error);
+      });
+    });
+  }
+};
+var synchronousDeferred = {
+  defer(fn) {
+    fn().catch((error) => {
+      console.error("[Credits] Deferred task error:", error);
+    });
+  }
+};
+function createDeferredExecutor(schedule) {
+  return {
+    defer: schedule
+  };
+}
+var noopDeferred = {
+  defer(_fn) {
+  }
+};
+
+// src/config/index.ts
+var import_zod = require("zod");
+
+// src/config/provider.ts
+var configProvider = null;
+function getConfigProvider() {
+  return configProvider;
+}
+
+// src/config/index.ts
+var tierConfigSchema = import_zod.z.object({
+  tier: import_zod.z.enum(["free", "basic", "premium", "unlimited"]),
+  monthlyCredits: import_zod.z.number().min(0),
+  priceUsd: import_zod.z.number().min(0),
+  features: import_zod.z.array(import_zod.z.string())
+});
+var creditSystemConfigSchema = import_zod.z.object({
+  /**
+   * Operation costs in credits
+   * Keys are operation type names (any non-empty string)
+   * Values are positive numbers representing credit cost
+   */
+  operationCosts: import_zod.z.record(
+    import_zod.z.string().min(1),
+    import_zod.z.number().positive()
+  ),
+  /**
+   * Display labels for operation types (English canonical labels).
+   * Falls back to auto-generating from snake_case keys if not provided.
+   */
+  operationLabels: import_zod.z.record(
+    import_zod.z.string().min(1),
+    import_zod.z.string().min(1)
+  ).optional().default({}),
+  /**
+   * Tier configurations
+   */
+  tierConfigs: import_zod.z.record(
+    import_zod.z.enum(["free", "basic", "premium", "unlimited"]),
+    tierConfigSchema
+  ),
+  /**
+   * Reservation expiry time in milliseconds
+   */
+  reservationExpiryMs: import_zod.z.number().positive().default(5 * 60 * 1e3),
+  /**
+   * Default credits for new users (free tier)
+   */
+  defaultFreeCredits: import_zod.z.number().positive().default(25),
+  /**
+   * Grace period in days after subscription expires before downgrade
+   */
+  subscriptionGracePeriodDays: import_zod.z.number().min(0).default(3),
+  /**
+   * Low balance notification threshold
+   */
+  lowBalanceThreshold: import_zod.z.number().min(0).default(10),
+  /**
+   * Cooldown in hours between low balance notifications
+   */
+  lowBalanceNotificationCooldownHours: import_zod.z.number().positive().default(24),
+  /**
+   * Feature flags for optional features
+   */
+  features: import_zod.z.object({
+    journalEntries: import_zod.z.boolean().default(true),
+    notifications: import_zod.z.boolean().default(true),
+    subscriptionExpiry: import_zod.z.boolean().default(true),
+    usageHistory: import_zod.z.boolean().default(true)
+  }).default({
+    journalEntries: true,
+    notifications: true,
+    subscriptionExpiry: true,
+    usageHistory: true
+  })
+});
+var DEFAULT_CONFIG = {
+  operationCosts: {
+    story_generation: 5,
+    conversation: 2,
+    image_generation: 10,
+    template_generation: 10
+  },
+  operationLabels: {
+    story_generation: "Story generation",
+    conversation: "Conversation",
+    image_generation: "Image generation",
+    template_generation: "Template generation"
+  },
+  tierConfigs: {
+    free: {
+      tier: "free",
+      monthlyCredits: 25,
+      priceUsd: 0,
+      features: [
+        "25 credits per month",
+        "Basic story generation",
+        "Standard image quality"
+      ]
+    },
+    basic: {
+      tier: "basic",
+      monthlyCredits: 200,
+      priceUsd: 9.99,
+      features: [
+        "200 credits per month",
+        "All story features",
+        "High quality images",
+        "Priority support"
+      ]
+    },
+    premium: {
+      tier: "premium",
+      monthlyCredits: 500,
+      priceUsd: 19.99,
+      features: [
+        "500 credits per month",
+        "All features",
+        "Highest quality images",
+        "Early access to new features",
+        "Priority support"
+      ]
+    },
+    unlimited: {
+      tier: "unlimited",
+      monthlyCredits: 0,
+      // 0 = unlimited
+      priceUsd: 49.99,
+      features: [
+        "Unlimited credits",
+        "All features",
+        "Highest quality images",
+        "Early access to new features",
+        "Dedicated support"
+      ]
+    }
+  },
+  reservationExpiryMs: 5 * 60 * 1e3,
+  // 5 minutes
+  defaultFreeCredits: 25,
+  subscriptionGracePeriodDays: 3,
+  lowBalanceThreshold: 10,
+  lowBalanceNotificationCooldownHours: 24,
+  features: {
+    journalEntries: true,
+    notifications: true,
+    subscriptionExpiry: true,
+    usageHistory: true
+  }
+};
+var currentConfig = DEFAULT_CONFIG;
+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) {
+        envConfig.operationCosts = {
+          ...DEFAULT_CONFIG.operationCosts,
+          ...parsed
+        };
+      }
+    } catch {
+      console.warn("[Credits Config] Failed to parse CREDITS_OPERATION_COSTS env var as JSON");
+    }
+  }
+  const reservationExpiry = process.env.CREDITS_RESERVATION_EXPIRY_MS;
+  if (reservationExpiry) {
+    envConfig.reservationExpiryMs = parseInt(reservationExpiry, 10);
+  }
+  const defaultCredits = process.env.CREDITS_DEFAULT_FREE;
+  if (defaultCredits) {
+    envConfig.defaultFreeCredits = parseInt(defaultCredits, 10);
+  }
+  const gracePeriod = process.env.CREDITS_GRACE_PERIOD_DAYS;
+  if (gracePeriod) {
+    envConfig.subscriptionGracePeriodDays = parseInt(gracePeriod, 10);
+  }
+  const lowBalanceThreshold = process.env.CREDITS_LOW_BALANCE_THRESHOLD;
+  if (lowBalanceThreshold) {
+    envConfig.lowBalanceThreshold = parseInt(lowBalanceThreshold, 10);
+  }
+  const featuresEnv = process.env.CREDITS_FEATURES;
+  if (featuresEnv) {
+    try {
+      const features = JSON.parse(featuresEnv);
+      envConfig.features = {
+        ...DEFAULT_CONFIG.features,
+        ...features
+      };
+    } catch {
+      console.warn("[Credits Config] Failed to parse CREDITS_FEATURES env var");
+    }
+  }
+  return envConfig;
+}
+function initializeConfig(overrides) {
+  const envConfig = loadConfigFromEnv();
+  const mergedConfig = {
+    ...DEFAULT_CONFIG,
+    ...envConfig,
+    ...overrides,
+    operationCosts: {
+      ...DEFAULT_CONFIG.operationCosts,
+      ...envConfig.operationCosts,
+      ...overrides?.operationCosts
+    },
+    operationLabels: {
+      ...DEFAULT_CONFIG.operationLabels,
+      ...envConfig.operationLabels,
+      ...overrides?.operationLabels
+    },
+    tierConfigs: {
+      ...DEFAULT_CONFIG.tierConfigs,
+      ...envConfig.tierConfigs,
+      ...overrides?.tierConfigs
+    },
+    features: {
+      ...DEFAULT_CONFIG.features,
+      ...envConfig.features,
+      ...overrides?.features
+    }
+  };
+  const result = creditSystemConfigSchema.safeParse(mergedConfig);
+  if (!result.success) {
+    console.error("[Credits Config] Invalid configuration:", result.error.issues);
+    throw new Error("Invalid credit system configuration");
+  }
+  currentConfig = result.data;
+  return currentConfig;
+}
+function getConfig() {
+  const provider = getConfigProvider();
+  if (provider) {
+    return provider.getConfig();
+  }
+  return currentConfig;
+}
+function snakeCaseToTitleCase(str) {
+  return str.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function getOperationLabel(operationType) {
+  const labels = getConfig().operationLabels;
+  if (labels && operationType in labels) {
+    return labels[operationType];
+  }
+  return snakeCaseToTitleCase(operationType);
+}
+initializeConfig();
+
+// src/core/operations.ts
+async function commitReservationWithJournal(repository, userId, reservationId) {
+  const reservation = await repository.getReservation(userId, reservationId);
+  if (!reservation) {
+    throw new Error(`Reservation ${reservationId} not found`);
+  }
+  await repository.commitReservationAtomic(userId, reservationId);
+  const credits = await repository.getUserCredits(userId);
+  if (credits) {
+    await 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
+      }
+    });
+  }
+}
+async function releaseReservationWithJournal(repository, userId, reservationId) {
+  const reservation = await repository.getReservation(userId, reservationId);
+  await repository.releaseReservationAtomic(userId, reservationId);
+  if (reservation?.status === "reserved") {
+    const credits = await repository.getUserCredits(userId);
+    if (credits) {
+      await 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 function reserveCreditsForOperation(repository, userId, amount, operationType, expiryMs = 5 * 60 * 1e3) {
+  const expiresAt = new Date(Date.now() + expiryMs);
+  return repository.reserveCreditsAtomic(userId, amount, operationType, expiresAt);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CreditError,
+  CreditErrorCode,
+  calculateAvailableCredits,
+  commitReservationWithJournal,
+  createDeferredExecutor,
+  createInsufficientCreditsError,
+  createInvalidOperationTypeError,
+  createReservationAlreadyProcessedError,
+  createReservationExpiredError,
+  createReservationNotFoundError,
+  createUserNotFoundError,
+  genericDeferred,
+  isCreditError,
+  isInsufficientCreditsError,
+  noopDeferred,
+  releaseReservationWithJournal,
+  reserveCreditsForOperation,
+  synchronousDeferred,
+  toDate,
+  toPortableTimestamp
+});
+//# sourceMappingURL=index.cjs.map