@nehorai/credits 1.2.0 → 1.4.0

package/dist/index.js

@@ -1,64 +1,2408 @@
-/**
- * @nehorai/credits - Framework-agnostic credits system
- *
- * Provides a complete credits/billing system with:
- * - Two-phase commit for safe credit deduction
- * - Journal-based audit trail
- * - Subscription tier management
- * - Notification hooks
- * - REST API SDK
- *
- * @example
- * ```typescript
- * import {
- *   CreditsService,
- *   createInMemoryCreditRepository,
- *   CreditError,
- * } from '@nehorai/credits';
- *
- * const repository = createInMemoryCreditRepository();
- * const service = new CreditsService(repository);
- *
- * // Check credits
- * const check = await service.checkCredits(userId, 10);
- * if (!check.hasCredits) {
- *   throw new Error(`Need ${check.shortfall} more credits`);
- * }
- *
- * // Reserve and execute
- * const reservation = await service.reserveCredits(userId, 10, 'story_generation');
- * try {
- *   await doWork();
- *   await service.commitCredits(userId, reservation.id);
- * } catch (error) {
- *   await service.releaseCredits(userId, reservation.id);
- *   throw error;
- * }
- * ```
- */
-// ==================== Core ====================
-export * from "./core/index.js";
-// ==================== Config ====================
-export { getConfig, initializeConfig, loadConfigFromEnv, getValidOperationTypes, isValidOperationType, getConfigOperationCost, getConfigTierConfig, getConfigMonthlyLimit, isFeatureEnabled, resetConfig, getOperationLabel, getOperationLabels, } from "./config/index.js";
-export { registerConfigProvider, getConfigProvider, clearConfigProvider, } from "./config/provider.js";
-export { getOperationCosts, getOperationCost, getTierConfig, getMonthlyLimit, getDefaultFreeCredits, getReservationExpiryMs, getOperationCostsWithLabels, } from "./config/costs.js";
-export { toClientUserCredits } from "./repository/types.js";
-export { generateId, getNextMonthlyReset } from "./repository/utils.js";
-export { InMemoryCreditRepository, createInMemoryCreditRepository, } from "./repository/memory/index.js";
-// ==================== Auth ====================
-export * from "./auth/index.js";
-// ==================== Service ====================
-export * from "./service/index.js";
-// ==================== Adapters ====================
-export * from "./adapters/index.js";
-// ==================== Notifications ====================
-export { registerNotificationHandler, clearNotificationHandlers, clearCooldownState, checkAndNotifyLowBalance, notifySubscriptionExpiring, notifySubscriptionExpired, ConsoleNotificationHandler, } from "./notifications/index.js";
-// ==================== SDK ====================
-// Export SDK (excluding types that conflict with core)
-export { CreditsClient } from "./sdk/client.js";
-export { AdminCreditsClient } from "./sdk/admin-client.js";
-export { SDKErrorCode } from "./sdk/types.js";
-export { CreditsSDKError, NetworkError, AuthenticationError, AuthorizationError, InsufficientCreditsError as SDKInsufficientCreditsError, ReservationNotFoundError as SDKReservationNotFoundError, ReservationExpiredError as SDKReservationExpiredError, ValidationError, ServerError, parseApiError, } from "./sdk/errors.js";
-// ==================== Utils ====================
-export { getTotalCredits, generateRequestId, parseCreditError, isCreditErrorMessage, isPreviewMode, createDummyReservation, } from "./utils/index.js";
+// 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
+import { z } from "zod";
+
+// src/config/provider.ts
+var configProvider = null;
+function registerConfigProvider(provider) {
+  configProvider = provider;
+}
+function getConfigProvider() {
+  return configProvider;
+}
+function clearConfigProvider() {
+  configProvider = null;
+}
+
+// src/config/index.ts
+var tierConfigSchema = z.object({
+  tier: z.enum(["free", "basic", "premium", "unlimited"]),
+  monthlyCredits: z.number().min(0),
+  priceUsd: z.number().min(0),
+  features: z.array(z.string())
+});
+var creditSystemConfigSchema = z.object({
+  /**
+   * Operation costs in credits
+   * Keys are operation type names (any non-empty string)
+   * Values are positive numbers representing credit cost
+   */
+  operationCosts: z.record(
+    z.string().min(1),
+    z.number().positive()
+  ),
+  /**
+   * Display labels for operation types (English canonical labels).
+   * Falls back to auto-generating from snake_case keys if not provided.
+   */
+  operationLabels: z.record(
+    z.string().min(1),
+    z.string().min(1)
+  ).optional().default({}),
+  /**
+   * Tier configurations
+   */
+  tierConfigs: z.record(
+    z.enum(["free", "basic", "premium", "unlimited"]),
+    tierConfigSchema
+  ),
+  /**
+   * Reservation expiry time in milliseconds
+   */
+  reservationExpiryMs: z.number().positive().default(5 * 60 * 1e3),
+  /**
+   * Default credits for new users (free tier)
+   */
+  defaultFreeCredits: z.number().positive().default(25),
+  /**
+   * Grace period in days after subscription expires before downgrade
+   */
+  subscriptionGracePeriodDays: z.number().min(0).default(3),
+  /**
+   * Low balance notification threshold
+   */
+  lowBalanceThreshold: z.number().min(0).default(10),
+  /**
+   * Cooldown in hours between low balance notifications
+   */
+  lowBalanceNotificationCooldownHours: z.number().positive().default(24),
+  /**
+   * Feature flags for optional features
+   */
+  features: z.object({
+    journalEntries: z.boolean().default(true),
+    notifications: z.boolean().default(true),
+    subscriptionExpiry: z.boolean().default(true),
+    usageHistory: 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 getValidOperationTypes() {
+  return Object.keys(getConfig().operationCosts);
+}
+function isValidOperationType(type) {
+  return type in getConfig().operationCosts;
+}
+function getConfigOperationCost(operationType) {
+  const cost = getConfig().operationCosts[operationType];
+  if (cost === void 0) {
+    throw new Error(
+      `Unknown operation type: ${operationType}. Valid types: ${getValidOperationTypes().join(", ")}`
+    );
+  }
+  return cost;
+}
+function getConfigTierConfig(tier) {
+  return getConfig().tierConfigs[tier];
+}
+function getConfigMonthlyLimit(tier) {
+  const config = getConfig().tierConfigs[tier];
+  return config.monthlyCredits === 0 ? Infinity : config.monthlyCredits;
+}
+function isFeatureEnabled(feature) {
+  return getConfig().features[feature];
+}
+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);
+}
+function getOperationLabels() {
+  const config = getConfig();
+  const result = {};
+  for (const key of Object.keys(config.operationCosts)) {
+    result[key] = config.operationLabels?.[key] ?? snakeCaseToTitleCase(key);
+  }
+  return result;
+}
+function resetConfig() {
+  currentConfig = DEFAULT_CONFIG;
+}
+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);
+}
+
+// src/config/costs.ts
+function getOperationCosts() {
+  return { ...getConfig().operationCosts };
+}
+function getOperationCost(type) {
+  return getConfigOperationCost(type);
+}
+function getTierConfig(tier) {
+  return getConfigTierConfig(tier);
+}
+function getMonthlyLimit(tier) {
+  return getConfigMonthlyLimit(tier);
+}
+function getDefaultFreeCredits() {
+  return getConfig().defaultFreeCredits;
+}
+function getReservationExpiryMs() {
+  return getConfig().reservationExpiryMs;
+}
+function getOperationCostsWithLabels() {
+  const config = getConfig();
+  const result = {};
+  for (const [key, cost] of Object.entries(config.operationCosts)) {
+    result[key] = {
+      key,
+      cost,
+      label: getOperationLabel(key)
+    };
+  }
+  return result;
+}
+
+// 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/repository/utils.ts
+function generateId() {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+}
+function toDate2(value) {
+  if (value instanceof Date) return value;
+  if (typeof value === "string") return new Date(value);
+  if (typeof value === "object" && value !== null && "toDate" in value) {
+    return value.toDate();
+  }
+  return /* @__PURE__ */ new Date();
+}
+function getNextMonthlyReset(from = /* @__PURE__ */ new Date()) {
+  const next = new Date(from);
+  next.setMonth(next.getMonth() + 1);
+  next.setDate(1);
+  next.setHours(0, 0, 0, 0);
+  return next;
+}
+
+// src/repository/memory/index.ts
+var InMemoryCreditRepository = class {
+  users = /* @__PURE__ */ new Map();
+  reservations = /* @__PURE__ */ new Map();
+  transactions = /* @__PURE__ */ new Map();
+  usageLogs = [];
+  journalEntries = /* @__PURE__ */ new Map();
+  // ==================== User Credits ====================
+  async getUserCredits(userId) {
+    return this.users.get(userId) ?? null;
+  }
+  async initializeUserCredits(userId, tier, initialBalance) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const credits = {
+      userId,
+      balance: initialBalance,
+      bonusCredits: 0,
+      reserved: 0,
+      tier,
+      monthlyLimit: getConfigMonthlyLimit(tier),
+      monthlyUsed: 0,
+      monthlyResetAt: getNextMonthlyReset().toISOString(),
+      subscriptionExpiresAt: null,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.users.set(userId, credits);
+    return credits;
+  }
+  async updateUserCredits(userId, updates) {
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User ${userId} not found`);
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (updates.balance !== void 0) credits.balance = updates.balance;
+    if (updates.bonusCredits !== void 0) credits.bonusCredits = updates.bonusCredits;
+    if (updates.reserved !== void 0) credits.reserved = updates.reserved;
+    if (updates.tier !== void 0) credits.tier = updates.tier;
+    if (updates.monthlyLimit !== void 0) credits.monthlyLimit = updates.monthlyLimit;
+    if (updates.monthlyUsed !== void 0) credits.monthlyUsed = updates.monthlyUsed;
+    if (updates.monthlyResetAt !== void 0) {
+      credits.monthlyResetAt = updates.monthlyResetAt instanceof Date ? updates.monthlyResetAt.toISOString() : updates.monthlyResetAt;
+    }
+    if (updates.subscriptionExpiresAt !== void 0) {
+      if (updates.subscriptionExpiresAt === null) {
+        credits.subscriptionExpiresAt = null;
+      } else {
+        credits.subscriptionExpiresAt = updates.subscriptionExpiresAt instanceof Date ? updates.subscriptionExpiresAt.toISOString() : updates.subscriptionExpiresAt;
+      }
+    }
+    if (updates.balanceIncrement !== void 0) {
+      credits.balance += updates.balanceIncrement;
+    }
+    if (updates.bonusCreditsIncrement !== void 0) {
+      credits.bonusCredits += updates.bonusCreditsIncrement;
+    }
+    if (updates.reservedIncrement !== void 0) {
+      credits.reserved += updates.reservedIncrement;
+    }
+    if (updates.monthlyUsedIncrement !== void 0) {
+      credits.monthlyUsed += updates.monthlyUsedIncrement;
+    }
+    credits.updatedAt = now;
+    this.users.set(userId, credits);
+  }
+  async updateUserTier(userId, input) {
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User ${userId} not found`);
+    }
+    credits.tier = input.tier;
+    credits.monthlyLimit = input.monthlyLimit;
+    if (input.balance !== void 0) credits.balance = input.balance;
+    if (input.monthlyUsed !== void 0) credits.monthlyUsed = input.monthlyUsed;
+    if (input.subscriptionExpiresAt !== void 0) {
+      if (input.subscriptionExpiresAt === null) {
+        credits.subscriptionExpiresAt = null;
+      } else {
+        credits.subscriptionExpiresAt = input.subscriptionExpiresAt instanceof Date ? input.subscriptionExpiresAt.toISOString() : input.subscriptionExpiresAt;
+      }
+    }
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.users.set(userId, credits);
+  }
+  // ==================== Reservations ====================
+  async createReservation(input) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const reservation = {
+      id: generateId(),
+      userId: input.userId,
+      amount: input.amount,
+      operationType: input.operationType,
+      status: "reserved",
+      createdAt: now,
+      expiresAt: input.expiresAt.toISOString()
+    };
+    if (!this.reservations.has(input.userId)) {
+      this.reservations.set(input.userId, /* @__PURE__ */ new Map());
+    }
+    this.reservations.get(input.userId).set(reservation.id, reservation);
+    return reservation;
+  }
+  async getReservation(userId, reservationId) {
+    const userReservations = this.reservations.get(userId);
+    if (!userReservations) return null;
+    return userReservations.get(reservationId) ?? null;
+  }
+  async updateReservationStatus(userId, reservationId, status, completedAt) {
+    const userReservations = this.reservations.get(userId);
+    if (!userReservations) {
+      throw new Error(`No reservations found for user ${userId}`);
+    }
+    const reservation = userReservations.get(reservationId);
+    if (!reservation) {
+      throw new Error(`Reservation ${reservationId} not found`);
+    }
+    reservation.status = status;
+    if (completedAt) reservation.completedAt = completedAt.toISOString();
+    userReservations.set(reservationId, reservation);
+  }
+  // ==================== Atomic Operations ====================
+  async reserveCreditsAtomic(userId, amount, operationType, expiresAt) {
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User ${userId} not found`);
+    }
+    const available = credits.balance + credits.bonusCredits - credits.reserved;
+    if (available < amount) {
+      throw new Error(
+        `Insufficient credits. Available: ${available}, Required: ${amount}`
+      );
+    }
+    const reservation = await this.createReservation({
+      userId,
+      amount,
+      operationType,
+      expiresAt
+    });
+    credits.reserved += amount;
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.users.set(userId, credits);
+    return reservation;
+  }
+  async commitReservationAtomic(userId, reservationId) {
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User ${userId} not found`);
+    }
+    const reservation = await this.getReservation(userId, reservationId);
+    if (!reservation) {
+      throw new Error(`Reservation ${reservationId} not found`);
+    }
+    if (reservation.status === "committed") {
+      return;
+    }
+    if (reservation.status !== "reserved") {
+      throw new Error(
+        `Cannot commit reservation in ${reservation.status} state`
+      );
+    }
+    const amount = reservation.amount;
+    credits.balance -= amount;
+    credits.reserved -= amount;
+    credits.monthlyUsed += amount;
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.users.set(userId, credits);
+    await this.updateReservationStatus(userId, reservationId, "committed", /* @__PURE__ */ new Date());
+  }
+  async releaseReservationAtomic(userId, reservationId) {
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User ${userId} not found`);
+    }
+    const reservation = await this.getReservation(userId, reservationId);
+    if (!reservation) {
+      throw new Error(`Reservation ${reservationId} not found`);
+    }
+    if (reservation.status !== "reserved") {
+      return;
+    }
+    credits.reserved -= reservation.amount;
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.users.set(userId, credits);
+    await this.updateReservationStatus(userId, reservationId, "released", /* @__PURE__ */ new Date());
+  }
+  async addCreditsAtomic(userId, amount, description, paymentRef) {
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User ${userId} not found`);
+    }
+    const previousBalance = credits.bonusCredits;
+    credits.bonusCredits += amount;
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.users.set(userId, credits);
+    await this.createTransaction({
+      userId,
+      type: "purchase",
+      amount,
+      description,
+      paymentRef,
+      previousBalance,
+      newBalance: credits.bonusCredits
+    });
+  }
+  async deductCreditsAtomic(userId, amount) {
+    if (amount <= 0) {
+      throw new Error(`deductCreditsAtomic amount must be positive (got ${amount})`);
+    }
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User credits not found for userId: ${userId}`);
+    }
+    const available = credits.balance + credits.bonusCredits - credits.reserved;
+    if (available < amount) {
+      throw new Error(
+        `Insufficient credits. Available: ${available}, requested: ${amount}`
+      );
+    }
+    const balanceDeduction = Math.min(credits.balance, amount);
+    const bonusDeduction = amount - balanceDeduction;
+    const previousBalance = credits.balance + credits.bonusCredits;
+    credits.balance -= balanceDeduction;
+    credits.bonusCredits -= bonusDeduction;
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.users.set(userId, credits);
+    return { previousBalance, newBalance: previousBalance - amount };
+  }
+  // ==================== Transactions ====================
+  async createTransaction(input) {
+    const transaction = {
+      id: generateId(),
+      userId: input.userId,
+      type: input.type,
+      amount: input.amount,
+      description: input.description,
+      paymentRef: input.paymentRef,
+      previousBalance: input.previousBalance,
+      newBalance: input.newBalance,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (!this.transactions.has(input.userId)) {
+      this.transactions.set(input.userId, []);
+    }
+    this.transactions.get(input.userId).push(transaction);
+    return transaction;
+  }
+  async getTransactions(userId, limit = 50, offset = 0) {
+    const userTransactions = this.transactions.get(userId) ?? [];
+    const sorted = [...userTransactions].sort((a, b) => {
+      const aDate = toDate2(a.createdAt).getTime();
+      const bDate = toDate2(b.createdAt).getTime();
+      return bDate - aDate;
+    });
+    return sorted.slice(offset, offset + limit);
+  }
+  // ==================== Usage Logs ====================
+  async logUsage(input) {
+    const log = {
+      id: generateId(),
+      userId: input.userId,
+      operationType: input.operationType,
+      provider: input.provider,
+      creditsUsed: input.creditsUsed,
+      success: input.success,
+      errorMessage: input.errorMessage,
+      resourceId: input.resourceId,
+      resourceType: input.resourceType,
+      requestId: input.requestId,
+      metadata: input.metadata,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.usageLogs.push(log);
+    return log;
+  }
+  async getUsageLogs(query) {
+    let results = [...this.usageLogs];
+    if (query.userId) {
+      results = results.filter((log) => log.userId === query.userId);
+    }
+    if (query.operationType) {
+      results = results.filter((log) => log.operationType === query.operationType);
+    }
+    if (query.success !== void 0) {
+      results = results.filter((log) => log.success === query.success);
+    }
+    if (query.startDate) {
+      const startTime = query.startDate.getTime();
+      results = results.filter(
+        (log) => toDate2(log.createdAt).getTime() >= startTime
+      );
+    }
+    if (query.endDate) {
+      const endTime = query.endDate.getTime();
+      results = results.filter(
+        (log) => toDate2(log.createdAt).getTime() <= endTime
+      );
+    }
+    results.sort((a, b) => {
+      return toDate2(b.createdAt).getTime() - toDate2(a.createdAt).getTime();
+    });
+    const offset = query.offset ?? 0;
+    const limit = query.limit ?? 50;
+    return results.slice(offset, offset + limit);
+  }
+  async getUsageLogsCount(query) {
+    const results = await this.getUsageLogs({ ...query, limit: Infinity, offset: 0 });
+    return results.length;
+  }
+  // ==================== Journal Entries ====================
+  async createJournalEntry(input) {
+    const entry = {
+      id: generateId(),
+      userId: input.userId,
+      entryType: input.entryType,
+      amount: input.amount,
+      balanceAfter: input.balanceAfter,
+      source: input.source,
+      referenceId: input.referenceId,
+      referenceType: input.referenceType,
+      description: input.description,
+      metadata: input.metadata,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (!this.journalEntries.has(input.userId)) {
+      this.journalEntries.set(input.userId, []);
+    }
+    this.journalEntries.get(input.userId).push(entry);
+    return entry;
+  }
+  async getJournalEntries(query) {
+    let results = this.journalEntries.get(query.userId) ?? [];
+    if (query.source) {
+      results = results.filter((entry) => entry.source === query.source);
+    }
+    if (query.referenceType) {
+      results = results.filter((entry) => entry.referenceType === query.referenceType);
+    }
+    if (query.startDate) {
+      const startTime = query.startDate.getTime();
+      results = results.filter(
+        (entry) => toDate2(entry.createdAt).getTime() >= startTime
+      );
+    }
+    if (query.endDate) {
+      const endTime = query.endDate.getTime();
+      results = results.filter(
+        (entry) => toDate2(entry.createdAt).getTime() <= endTime
+      );
+    }
+    results = [...results].sort((a, b) => {
+      return toDate2(b.createdAt).getTime() - toDate2(a.createdAt).getTime();
+    });
+    const offset = query.offset ?? 0;
+    const limit = query.limit ?? 50;
+    return results.slice(offset, offset + limit);
+  }
+  async getJournalEntriesCount(query) {
+    const results = await this.getJournalEntries({
+      ...query,
+      limit: Infinity,
+      offset: 0
+    });
+    return results.length;
+  }
+  // ==================== Cleanup Operations ====================
+  async findAndExpireReservations(_batchSize = 100, _maxIterations = 100) {
+    const now = /* @__PURE__ */ new Date();
+    let expiredCount = 0;
+    let creditsReleased = 0;
+    const errors = [];
+    for (const [userId, userReservations] of this.reservations) {
+      for (const [reservationId, reservation] of userReservations) {
+        if (reservation.status === "reserved" && toDate2(reservation.expiresAt).getTime() < now.getTime()) {
+          try {
+            await this.releaseReservationAtomic(userId, reservationId);
+            reservation.status = "expired";
+            userReservations.set(reservationId, reservation);
+            expiredCount++;
+            creditsReleased += reservation.amount;
+          } catch (error) {
+            errors.push(
+              `Failed to expire reservation ${reservationId}: ${error}`
+            );
+          }
+        }
+      }
+    }
+    return { expiredCount, creditsReleased, errors };
+  }
+  // ==================== Atomic Monthly Reset ====================
+  async atomicMonthlyReset(userId, tier, expectedResetAt) {
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User ${userId} not found`);
+    }
+    const currentResetAt = toDate2(credits.monthlyResetAt).getTime();
+    const expected = toDate2(expectedResetAt).getTime();
+    if (currentResetAt !== expected) {
+      return { wasReset: false, credits };
+    }
+    const newBalance = getConfigMonthlyLimit(tier);
+    const nextReset = getNextMonthlyReset();
+    credits.balance = newBalance === Infinity ? credits.balance : newBalance;
+    credits.monthlyUsed = 0;
+    credits.monthlyResetAt = nextReset.toISOString();
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.users.set(userId, credits);
+    return { wasReset: true, credits };
+  }
+  // ==================== Subscription Expiry ====================
+  async checkAndHandleSubscriptionExpiry(userId, gracePeriodDays = 3) {
+    const credits = this.users.get(userId);
+    if (!credits) {
+      throw new Error(`User ${userId} not found`);
+    }
+    if (credits.tier === "free" || !credits.subscriptionExpiresAt) {
+      return {
+        wasDowngraded: false,
+        inGracePeriod: false,
+        graceDaysRemaining: 0,
+        credits
+      };
+    }
+    const now = /* @__PURE__ */ new Date();
+    const expiresAt = toDate2(credits.subscriptionExpiresAt);
+    const daysSinceExpiry = (now.getTime() - expiresAt.getTime()) / (1e3 * 60 * 60 * 24);
+    if (daysSinceExpiry <= 0) {
+      return {
+        wasDowngraded: false,
+        inGracePeriod: false,
+        graceDaysRemaining: 0,
+        credits
+      };
+    }
+    if (daysSinceExpiry <= gracePeriodDays) {
+      return {
+        wasDowngraded: false,
+        inGracePeriod: true,
+        graceDaysRemaining: Math.ceil(gracePeriodDays - daysSinceExpiry),
+        credits
+      };
+    }
+    const config = getConfig();
+    const freeTierConfig = config.tierConfigs.free;
+    credits.tier = "free";
+    credits.monthlyLimit = freeTierConfig.monthlyCredits;
+    credits.balance = Math.min(credits.balance, freeTierConfig.monthlyCredits);
+    credits.subscriptionExpiresAt = null;
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.users.set(userId, credits);
+    return {
+      wasDowngraded: true,
+      inGracePeriod: false,
+      graceDaysRemaining: 0,
+      credits
+    };
+  }
+  // ==================== Testing Utilities ====================
+  /**
+   * Clear all data (useful for testing)
+   */
+  clear() {
+    this.users.clear();
+    this.reservations.clear();
+    this.transactions.clear();
+    this.usageLogs = [];
+    this.journalEntries.clear();
+  }
+  /**
+   * Get all users (useful for testing/debugging)
+   */
+  getAllUsers() {
+    return Array.from(this.users.values());
+  }
+  /**
+   * Get all reservations for a user (useful for testing)
+   */
+  getAllReservations(userId) {
+    const userReservations = this.reservations.get(userId);
+    if (!userReservations) return [];
+    return Array.from(userReservations.values());
+  }
+};
+function createInMemoryCreditRepository() {
+  return new InMemoryCreditRepository();
+}
+
+// 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);
+}
+
+// src/service/credits-service.ts
+function isPastMonthlyReset(resetAt) {
+  if (!resetAt) return false;
+  const resetDate = toDate(resetAt);
+  return /* @__PURE__ */ new Date() >= resetDate;
+}
+var CreditsService = class {
+  constructor(repository) {
+    this.repository = repository;
+  }
+  lowBalanceCallback;
+  subscriptionExpiredCallback;
+  /**
+   * Set callback for low balance notifications
+   */
+  setLowBalanceCallback(callback) {
+    this.lowBalanceCallback = callback;
+  }
+  /**
+   * Set callback for subscription expired notifications
+   */
+  setSubscriptionExpiredCallback(callback) {
+    this.subscriptionExpiredCallback = callback;
+  }
+  /**
+   * Get user credits, performing monthly reset and subscription expiry checks if needed
+   *
+   * This method uses atomic operations to prevent race conditions:
+   * 1. Checks subscription expiry with grace period
+   * 2. Atomically performs monthly reset if needed (with optimistic locking)
+   *
+   * @param userId - User ID
+   * @returns User credits or null if not found
+   */
+  async getUserCredits(userId) {
+    let data = await this.repository.getUserCredits(userId);
+    if (!data) {
+      return null;
+    }
+    if (data.tier !== "free" && data.subscriptionExpiresAt) {
+      const expiryResult = await this.repository.checkAndHandleSubscriptionExpiry(
+        userId,
+        getConfig().subscriptionGracePeriodDays
+      );
+      if (expiryResult.wasDowngraded) {
+        await this.repository.createJournalEntry({
+          userId,
+          entryType: "debit",
+          amount: 0,
+          // No credits deducted, just tier change
+          balanceAfter: expiryResult.credits.balance,
+          source: "subscription_downgrade",
+          referenceId: `downgrade-${Date.now()}`,
+          referenceType: "subscription",
+          description: `Subscription expired. Downgraded from ${data.tier} to free 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);
+          });
+        }
+      }
+      data = expiryResult.credits;
+    }
+    if (isPastMonthlyReset(data.monthlyResetAt)) {
+      const expectedResetAt = toDate(data.monthlyResetAt);
+      const resetResult = await this.repository.atomicMonthlyReset(
+        userId,
+        data.tier,
+        expectedResetAt
+      );
+      if (resetResult.wasReset) {
+        const balanceChange = 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,
+            source: "monthly_reset",
+            referenceId: `reset-${Date.now()}`,
+            referenceType: "reset",
+            description: `Monthly credit reset for ${data.tier} tier.`,
+            metadata: {
+              tier: data.tier,
+              previousBalance: data.balance,
+              newBalance: resetResult.credits.balance
+            }
+          });
+        }
+      }
+      data = resetResult.credits;
+    }
+    return toClientUserCredits(data);
+  }
+  /**
+   * Initialize credits for a new user with free tier
+   * @param userId - User ID
+   * @returns Initialized user credits
+   */
+  async initializeUserCredits(userId) {
+    const credits = await this.repository.initializeUserCredits(
+      userId,
+      "free",
+      getConfig().defaultFreeCredits
+    );
+    return toClientUserCredits(credits);
+  }
+  /**
+   * Get or create user credits
+   * Initializes with free tier if not exists
+   * @param userId - User ID
+   * @returns User credits
+   */
+  async getOrCreateUserCredits(userId) {
+    const existing = await this.getUserCredits(userId);
+    if (existing) {
+      return existing;
+    }
+    return this.initializeUserCredits(userId);
+  }
+  /**
+   * Check if user has sufficient credits for an operation
+   * @param userId - User ID
+   * @param requiredCredits - Credits required
+   * @returns Credit check result
+   */
+  async checkCredits(userId, requiredCredits) {
+    const credits = await this.getOrCreateUserCredits(userId);
+    const totalBalance = credits.balance + credits.bonusCredits;
+    const available = totalBalance - credits.reserved;
+    const hasCredits = available >= requiredCredits;
+    return {
+      hasCredits,
+      balance: totalBalance,
+      required: requiredCredits,
+      shortfall: hasCredits ? 0 : requiredCredits - available
+    };
+  }
+  /**
+   * Reserve credits for an operation (phase 1 of two-phase commit)
+   * Creates a reservation and locks the credits
+   * @param userId - User ID
+   * @param amount - Credits to reserve
+   * @param operationType - Operation type for tracking
+   * @param options - Optional settings (e.g. a custom `ttlMs` for long-running async jobs)
+   * @returns Reservation object
+   * @throws Error if insufficient credits
+   */
+  async reserveCredits(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);
+  }
+  /**
+   * 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
+   */
+  async commitCredits(userId, reservationId) {
+    const reservation = await this.repository.getReservation(userId, reservationId);
+    if (!reservation) {
+      throw new Error(`Reservation ${reservationId} not found`);
+    }
+    if (reservation.status === "committed") {
+      return;
+    }
+    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
+        }
+      });
+      if (this.lowBalanceCallback) {
+        this.lowBalanceCallback(userId, credits.balance).catch((error) => {
+          console.error("[Credits] Failed to send low balance notification:", error);
+        });
+      }
+    }
+  }
+  /**
+   * Release a reservation (phase 2 of two-phase commit - failure)
+   * Returns reserved credits and marks reservation as released
+   */
+  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
+          }
+        });
+      }
+    }
+  }
+  /**
+   * Log usage for audit trail
+   * @param log - Usage log data
+   */
+  async logUsage(log) {
+    await this.repository.logUsage(log);
+  }
+  /**
+   * Add credits to user account (for purchases, bonuses, etc.)
+   * @param userId - User ID
+   * @param amount - Credits to add
+   * @param description - Transaction description
+   * @param paymentRef - Optional payment reference
+   */
+  async addCredits(userId, amount, description, paymentRef) {
+    return this.repository.addCreditsAtomic(userId, amount, description, paymentRef);
+  }
+  /**
+   * Update user subscription tier
+   * @param userId - User ID
+   * @param tier - New subscription tier
+   * @param expiresAt - Subscription expiry date (optional)
+   */
+  async updateTier(userId, tier, expiresAt) {
+    const monthlyLimit = getConfigMonthlyLimit(tier);
+    await this.repository.updateUserTier(userId, {
+      tier,
+      monthlyLimit: monthlyLimit === Infinity ? 0 : monthlyLimit,
+      // Reset balance to new tier limit if upgrading
+      balance: tier !== "free" ? monthlyLimit === Infinity ? 999999 : monthlyLimit : void 0,
+      monthlyUsed: tier !== "free" ? 0 : void 0,
+      subscriptionExpiresAt: expiresAt ? expiresAt.toISOString() : null
+    });
+  }
+  /**
+   * Get usage logs with optional filtering
+   * @param userId - Optional user ID filter
+   * @param limit - Max results
+   * @param offset - Skip results
+   * @returns List of usage logs
+   */
+  async getUsageLogs(userId, limit = 50, offset = 0) {
+    return this.repository.getUsageLogs({ userId, limit, offset });
+  }
+  /**
+   * Get user-friendly usage history
+   * Combines journal entries into a user-facing format
+   *
+   * @param userId - User ID
+   * @param limit - Max results per page
+   * @param offset - Skip results for pagination
+   * @returns Paginated usage history response
+   */
+  async getUsageHistory(userId, limit = 20, offset = 0) {
+    const [entries, total] = await Promise.all([
+      this.repository.getJournalEntries({ userId, limit, offset }),
+      this.repository.getJournalEntriesCount({ userId })
+    ]);
+    const historyEntries = entries.map((entry) => {
+      const type = this.mapSourceToHistoryType(entry.source);
+      const creditsChange = entry.entryType === "credit" ? entry.amount : -entry.amount;
+      return {
+        id: entry.id,
+        type,
+        creditsChange,
+        balanceAfter: entry.balanceAfter,
+        description: entry.description,
+        createdAt: typeof entry.createdAt === "string" ? entry.createdAt : toDate(entry.createdAt).toISOString()
+      };
+    });
+    return {
+      entries: historyEntries,
+      pagination: {
+        total,
+        limit,
+        offset,
+        hasMore: offset + entries.length < total
+      }
+    };
+  }
+  /**
+   * Map journal entry source to user-friendly history type
+   */
+  mapSourceToHistoryType(source) {
+    switch (source) {
+      case "operation_commit":
+      case "reservation_expired":
+        return "usage";
+      case "purchase":
+        return "purchase";
+      case "subscription_grant":
+      case "subscription_upgrade":
+      case "bonus":
+        return "bonus";
+      case "monthly_reset":
+        return "reset";
+      case "refund":
+      case "operation_release":
+        return "refund";
+      case "admin_adjustment":
+      case "subscription_downgrade":
+      case "expiry":
+      default:
+        return "adjustment";
+    }
+  }
+  /**
+   * Get journal entries directly (for admin or debugging)
+   * @param query - Journal entry query parameters
+   * @returns List of journal entries
+   */
+  async getJournalEntries(query) {
+    return this.repository.getJournalEntries(query);
+  }
+  /**
+   * Get the underlying repository (for advanced use cases)
+   */
+  getRepository() {
+    return this.repository;
+  }
+};
+function createCreditsService(repository) {
+  return new CreditsService(repository);
+}
+
+// src/adapters/generic.ts
+function generateRequestId() {
+  const timestamp = Date.now();
+  const randomPart = Math.random().toString(36).substring(2, 14);
+  return `req_${timestamp}_${randomPart}`;
+}
+function createGenericAdapter(config) {
+  const { repository, authProvider, deferred, operationCosts } = config;
+  function getOperationCost2(operationType) {
+    const cost = operationCosts[operationType];
+    if (cost === void 0) {
+      throw new Error(
+        `Unknown operation type: "${operationType}". Configured types: ${Object.keys(operationCosts).join(", ")}`
+      );
+    }
+    return cost;
+  }
+  function logUsage(params) {
+    deferred.defer(async () => {
+      await repository.logUsage({
+        userId: params.userId,
+        operationType: params.operationType,
+        provider: "gemini",
+        creditsUsed: params.creditsUsed,
+        success: params.success,
+        errorMessage: params.errorMessage,
+        resourceId: params.resourceId,
+        resourceType: params.resourceType,
+        requestId: params.requestId
+      });
+    });
+  }
+  return {
+    withCredits(options, handler) {
+      return async (data) => {
+        const requestId = generateRequestId();
+        const user = await authProvider.getCurrentUser();
+        if (!user?.id) {
+          return { success: false, error: "Authentication required" };
+        }
+        if (isPreviewMode(data)) {
+          const dummyReservation = createDummyReservation(user.id, options.operationType);
+          return handler(user, data, dummyReservation);
+        }
+        let reservation;
+        try {
+          const cost = options.customCost ?? getOperationCost2(options.operationType);
+          reservation = await reserveCreditsForOperation(
+            repository,
+            user.id,
+            cost,
+            options.operationType
+          );
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Failed to reserve credits";
+          logUsage({
+            userId: user.id,
+            operationType: options.operationType,
+            creditsUsed: 0,
+            success: false,
+            errorMessage: message,
+            resourceId: options.resourceId,
+            resourceType: options.resourceType,
+            requestId
+          });
+          return { success: false, error: message };
+        }
+        try {
+          const result = await handler(user, data, reservation);
+          if (result.success) {
+            await commitReservationWithJournal(repository, user.id, reservation.id);
+            logUsage({
+              userId: user.id,
+              operationType: options.operationType,
+              creditsUsed: reservation.amount,
+              success: true,
+              resourceId: options.resourceId,
+              resourceType: options.resourceType,
+              requestId
+            });
+          } else {
+            await releaseReservationWithJournal(repository, user.id, reservation.id);
+            logUsage({
+              userId: user.id,
+              operationType: options.operationType,
+              creditsUsed: 0,
+              success: false,
+              errorMessage: result.error,
+              resourceId: options.resourceId,
+              resourceType: options.resourceType,
+              requestId
+            });
+          }
+          return result;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "An unexpected error occurred";
+          await releaseReservationWithJournal(repository, user.id, reservation.id);
+          logUsage({
+            userId: user.id,
+            operationType: options.operationType,
+            creditsUsed: 0,
+            success: false,
+            errorMessage: message,
+            resourceId: options.resourceId,
+            resourceType: options.resourceType,
+            requestId
+          });
+          console.error("Action error:", error);
+          return { success: false, error: message };
+        }
+      };
+    }
+  };
+}
+function isPreviewMode(data) {
+  return typeof data === "object" && data !== null && "preview" in data && data.preview === true;
+}
+function createDummyReservation(userId, operationType) {
+  return {
+    id: "preview-mode",
+    userId,
+    amount: 0,
+    operationType,
+    status: "released",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    expiresAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/notifications/index.ts
+var cooldownState = /* @__PURE__ */ new Map();
+function isNotificationAllowed(userId, eventType) {
+  const state = cooldownState.get(userId);
+  if (!state) return true;
+  const now = Date.now();
+  let lastNotification;
+  switch (eventType) {
+    case "lowBalance":
+      lastNotification = state.lastLowBalanceNotification;
+      break;
+    case "depleted":
+      lastNotification = state.lastDepletedNotification;
+      break;
+    case "expiring":
+      lastNotification = state.lastExpiringNotification;
+      break;
+  }
+  if (!lastNotification) return true;
+  return now - lastNotification.getTime() > getConfig().lowBalanceNotificationCooldownHours * 60 * 60 * 1e3;
+}
+function recordNotification(userId, eventType) {
+  const state = cooldownState.get(userId) || {};
+  const now = /* @__PURE__ */ new Date();
+  switch (eventType) {
+    case "lowBalance":
+      state.lastLowBalanceNotification = now;
+      break;
+    case "depleted":
+      state.lastDepletedNotification = now;
+      break;
+    case "expiring":
+      state.lastExpiringNotification = now;
+      break;
+  }
+  cooldownState.set(userId, state);
+}
+var notificationHandlers = [];
+function registerNotificationHandler(handler) {
+  notificationHandlers.push(handler);
+}
+function clearNotificationHandlers() {
+  notificationHandlers.length = 0;
+}
+function clearCooldownState() {
+  cooldownState.clear();
+}
+async function dispatchNotification(event) {
+  if (notificationHandlers.length === 0) {
+    console.debug(`[Credits] No notification handlers registered for: ${event.type}`);
+    return;
+  }
+  await Promise.allSettled(
+    notificationHandlers.map(
+      (handler) => handler.handleNotification(event).catch((error) => {
+        console.error(`[Credits] Notification handler error:`, error);
+      })
+    )
+  );
+}
+async function checkAndNotifyLowBalance(userId, newBalance, threshold = getConfig().lowBalanceThreshold) {
+  if (newBalance <= 0 && isNotificationAllowed(userId, "depleted")) {
+    recordNotification(userId, "depleted");
+    await dispatchNotification({
+      type: "balance_depleted",
+      userId
+    });
+    return;
+  }
+  if (newBalance > 0 && newBalance <= threshold && isNotificationAllowed(userId, "lowBalance")) {
+    recordNotification(userId, "lowBalance");
+    await dispatchNotification({
+      type: "low_balance",
+      userId,
+      balance: newBalance,
+      threshold
+    });
+  }
+}
+async function notifySubscriptionExpiring(userId, expiresAt, daysRemaining) {
+  if (!isNotificationAllowed(userId, "expiring")) {
+    return;
+  }
+  recordNotification(userId, "expiring");
+  await dispatchNotification({
+    type: "subscription_expiring",
+    userId,
+    expiresAt,
+    daysRemaining
+  });
+}
+async function notifySubscriptionExpired(userId, wasDowngraded) {
+  await dispatchNotification({
+    type: "subscription_expired",
+    userId,
+    wasDowngraded
+  });
+}
+var ConsoleNotificationHandler = class {
+  async handleNotification(event) {
+    switch (event.type) {
+      case "low_balance":
+        console.log(
+          `[Credits Notification] Low balance alert for user ${event.userId}: ${event.balance} credits remaining (threshold: ${event.threshold})`
+        );
+        break;
+      case "balance_depleted":
+        console.log(
+          `[Credits Notification] Balance depleted for user ${event.userId}`
+        );
+        break;
+      case "subscription_expiring":
+        console.log(
+          `[Credits Notification] Subscription expiring for user ${event.userId}: ${event.daysRemaining} days remaining`
+        );
+        break;
+      case "subscription_expired":
+        console.log(
+          `[Credits Notification] Subscription expired for user ${event.userId}: downgraded=${event.wasDowngraded}`
+        );
+        break;
+    }
+  }
+};
+
+// src/sdk/types.ts
+var SDKErrorCode = {
+  NETWORK_ERROR: "NETWORK_ERROR",
+  AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR",
+  AUTHORIZATION_ERROR: "AUTHORIZATION_ERROR",
+  INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS",
+  RESERVATION_NOT_FOUND: "RESERVATION_NOT_FOUND",
+  RESERVATION_EXPIRED: "RESERVATION_EXPIRED",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  SERVER_ERROR: "SERVER_ERROR",
+  UNKNOWN_ERROR: "UNKNOWN_ERROR"
+};
+
+// src/sdk/errors.ts
+var CreditsSDKError = class extends Error {
+  code;
+  details;
+  statusCode;
+  constructor(message, code, options) {
+    super(message, { cause: options?.cause });
+    this.name = "CreditsSDKError";
+    this.code = code;
+    this.details = options?.details;
+    this.statusCode = options?.statusCode;
+  }
+  /**
+   * Check if this is a specific error type
+   */
+  is(code) {
+    return this.code === code;
+  }
+  /**
+   * Create a JSON representation for logging
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      statusCode: this.statusCode
+    };
+  }
+};
+var NetworkError = class extends CreditsSDKError {
+  constructor(message, cause) {
+    super(message, SDKErrorCode.NETWORK_ERROR, { cause });
+    this.name = "NetworkError";
+  }
+};
+var AuthenticationError = class extends CreditsSDKError {
+  constructor(message = "Authentication required") {
+    super(message, SDKErrorCode.AUTHENTICATION_ERROR, { statusCode: 401 });
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends CreditsSDKError {
+  constructor(message = "Access denied") {
+    super(message, SDKErrorCode.AUTHORIZATION_ERROR, { statusCode: 403 });
+    this.name = "AuthorizationError";
+  }
+};
+var InsufficientCreditsError = class extends CreditsSDKError {
+  available;
+  required;
+  constructor(available, required) {
+    super(
+      `Insufficient credits: available ${available}, required ${required}`,
+      SDKErrorCode.INSUFFICIENT_CREDITS,
+      {
+        statusCode: 402,
+        details: { available, required }
+      }
+    );
+    this.name = "InsufficientCreditsError";
+    this.available = available;
+    this.required = required;
+  }
+};
+var ReservationNotFoundError = class extends CreditsSDKError {
+  reservationId;
+  constructor(reservationId) {
+    super(
+      `Reservation not found: ${reservationId}`,
+      SDKErrorCode.RESERVATION_NOT_FOUND,
+      {
+        statusCode: 404,
+        details: { reservationId }
+      }
+    );
+    this.name = "ReservationNotFoundError";
+    this.reservationId = reservationId;
+  }
+};
+var ReservationExpiredError = class extends CreditsSDKError {
+  reservationId;
+  constructor(reservationId) {
+    super(
+      `Reservation expired: ${reservationId}`,
+      SDKErrorCode.RESERVATION_EXPIRED,
+      {
+        statusCode: 410,
+        details: { reservationId }
+      }
+    );
+    this.name = "ReservationExpiredError";
+    this.reservationId = reservationId;
+  }
+};
+var ValidationError = class extends CreditsSDKError {
+  field;
+  constructor(message, field) {
+    super(message, SDKErrorCode.VALIDATION_ERROR, {
+      statusCode: 400,
+      details: field ? { field } : void 0
+    });
+    this.name = "ValidationError";
+    this.field = field;
+  }
+};
+var ServerError = class extends CreditsSDKError {
+  constructor(message = "Internal server error") {
+    super(message, SDKErrorCode.SERVER_ERROR, { statusCode: 500 });
+    this.name = "ServerError";
+  }
+};
+function parseApiError(statusCode, body) {
+  const errorCode = body.error?.code || "";
+  const errorMessage = body.error?.message || "An error occurred";
+  const details = body.error?.details;
+  switch (statusCode) {
+    case 401:
+      return new AuthenticationError(errorMessage);
+    case 403:
+      return new AuthorizationError(errorMessage);
+    case 402:
+      if (details?.available !== void 0 && details?.required !== void 0) {
+        return new InsufficientCreditsError(
+          details.available,
+          details.required
+        );
+      }
+      return new CreditsSDKError(errorMessage, SDKErrorCode.INSUFFICIENT_CREDITS, {
+        statusCode,
+        details
+      });
+    case 404:
+      if (errorCode === "RESERVATION_NOT_FOUND" && details?.reservationId) {
+        return new ReservationNotFoundError(details.reservationId);
+      }
+      return new CreditsSDKError(errorMessage, SDKErrorCode.RESERVATION_NOT_FOUND, {
+        statusCode,
+        details
+      });
+    case 410:
+      if (errorCode === "RESERVATION_EXPIRED" && details?.reservationId) {
+        return new ReservationExpiredError(details.reservationId);
+      }
+      return new CreditsSDKError(errorMessage, SDKErrorCode.RESERVATION_EXPIRED, {
+        statusCode,
+        details
+      });
+    case 400:
+    case 422:
+      return new ValidationError(errorMessage, details?.field);
+    case 500:
+    default:
+      if (statusCode >= 500) {
+        return new ServerError(errorMessage);
+      }
+      return new CreditsSDKError(errorMessage, SDKErrorCode.UNKNOWN_ERROR, {
+        statusCode,
+        details
+      });
+  }
+}
+
+// src/sdk/client.ts
+var CreditsClient = class {
+  baseUrl;
+  getAuthToken;
+  fetchFn;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.getAuthToken = config.getAuthToken;
+    this.fetchFn = config.fetch ?? fetch;
+  }
+  /**
+   * Make an authenticated request to the API
+   */
+  async request(path, options = {}) {
+    const { method = "GET", body, params } = options;
+    let url = `${this.baseUrl}${path}`;
+    if (params) {
+      const searchParams = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) {
+          searchParams.set(key, String(value));
+        }
+      }
+      const queryString = searchParams.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.getAuthToken) {
+      try {
+        const token = await this.getAuthToken();
+        if (token) {
+          headers["Authorization"] = `Bearer ${token}`;
+        }
+      } catch {
+      }
+    }
+    let response;
+    try {
+      response = await this.fetchFn(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0
+      });
+    } catch (error) {
+      throw new NetworkError(
+        error instanceof Error ? error.message : "Network request failed",
+        error instanceof Error ? error : void 0
+      );
+    }
+    const responseBody = await response.json();
+    if (!response.ok) {
+      throw parseApiError(response.status, responseBody);
+    }
+    return responseBody.data;
+  }
+  /**
+   * Get the current user's credit balance
+   *
+   * @returns User's credit information
+   * @throws AuthenticationError if not authenticated
+   */
+  async getBalance() {
+    return this.request("/api/v1/credits/balance");
+  }
+  /**
+   * Check if the user has sufficient credits for an operation
+   *
+   * @param operationType - Type of operation to check
+   * @param customCost - Optional custom cost to check against
+   * @returns Credit availability status
+   * @throws AuthenticationError if not authenticated
+   */
+  async checkAvailability(operationType, customCost) {
+    return this.request("/api/v1/credits/availability", {
+      params: {
+        operationType,
+        customCost: customCost?.toString()
+      }
+    });
+  }
+  /**
+   * Reserve credits for an operation
+   *
+   * This is the first step in the two-phase commit pattern.
+   * Reserved credits are held for 5 minutes before expiring.
+   *
+   * @param operationType - Type of operation
+   * @param options - Optional reservation options
+   * @returns Reservation details including ID and expiry
+   * @throws InsufficientCreditsError if not enough credits
+   * @throws AuthenticationError if not authenticated
+   */
+  async reserve(operationType, options) {
+    return this.request("/api/v1/credits/reserve", {
+      method: "POST",
+      body: {
+        operationType,
+        ...options
+      }
+    });
+  }
+  /**
+   * Commit a reservation (deduct credits)
+   *
+   * This is the second step in the two-phase commit pattern.
+   * Call this after your operation succeeds.
+   *
+   * @param reservationId - ID of the reservation to commit
+   * @throws ReservationNotFoundError if reservation doesn't exist
+   * @throws ReservationExpiredError if reservation has expired
+   * @throws AuthenticationError if not authenticated
+   */
+  async commit(reservationId) {
+    await this.request("/api/v1/credits/commit", {
+      method: "POST",
+      body: { reservationId }
+    });
+  }
+  /**
+   * Release a reservation (refund credits)
+   *
+   * Call this if your operation fails after reserving credits.
+   *
+   * @param reservationId - ID of the reservation to release
+   * @throws ReservationNotFoundError if reservation doesn't exist
+   * @throws AuthenticationError if not authenticated
+   */
+  async release(reservationId) {
+    await this.request("/api/v1/credits/release", {
+      method: "POST",
+      body: { reservationId }
+    });
+  }
+  /**
+   * Get usage history for the current user
+   *
+   * @param options - Optional pagination options
+   * @returns Paginated list of usage entries
+   * @throws AuthenticationError if not authenticated
+   */
+  async getHistory(options) {
+    return this.request("/api/v1/credits/history", {
+      params: {
+        page: options?.page,
+        limit: options?.limit
+      }
+    });
+  }
+  /**
+   * Get the available credits (balance + bonus - reserved)
+   *
+   * Convenience method that calculates available credits from balance.
+   *
+   * @returns Number of available credits
+   * @throws AuthenticationError if not authenticated
+   */
+  async getAvailableCredits() {
+    const balance = await this.getBalance();
+    return balance.balance + balance.bonusCredits - balance.reserved;
+  }
+  /**
+   * Execute an operation with automatic credit handling
+   *
+   * This is a convenience method that handles the full two-phase commit
+   * pattern automatically.
+   *
+   * @param operationType - Type of operation
+   * @param operation - The operation to execute
+   * @param options - Optional reservation options
+   * @returns Result of the operation
+   * @throws InsufficientCreditsError if not enough credits
+   * @throws AuthenticationError if not authenticated
+   *
+   * @example
+   * ```typescript
+   * const result = await client.withCredits(
+   *   "story_generation",
+   *   async () => {
+   *     return generateStory(data);
+   *   }
+   * );
+   * ```
+   */
+  async withCredits(operationType, operation, options) {
+    const reservation = await this.reserve(operationType, options);
+    try {
+      const result = await operation();
+      await this.commit(reservation.reservationId);
+      return result;
+    } catch (error) {
+      try {
+        await this.release(reservation.reservationId);
+      } catch {
+      }
+      throw error;
+    }
+  }
+};
+
+// src/sdk/admin-client.ts
+var AdminCreditsClient = class {
+  baseUrl;
+  apiKey;
+  fetchFn;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.fetchFn = config.fetch ?? fetch;
+  }
+  /**
+   * Make an authenticated admin request to the API
+   */
+  async request(path, options = {}) {
+    const { method = "GET", body, params } = options;
+    let url = `${this.baseUrl}${path}`;
+    if (params) {
+      const searchParams = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) {
+          searchParams.set(key, String(value));
+        }
+      }
+      const queryString = searchParams.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      "x-api-key": this.apiKey
+    };
+    let response;
+    try {
+      response = await this.fetchFn(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0
+      });
+    } catch (error) {
+      throw new NetworkError(
+        error instanceof Error ? error.message : "Network request failed",
+        error instanceof Error ? error : void 0
+      );
+    }
+    const responseBody = await response.json();
+    if (!response.ok) {
+      throw parseApiError(response.status, responseBody);
+    }
+    return responseBody.data;
+  }
+  /**
+   * Get a specific user's credits
+   *
+   * @param userId - ID of the user
+   * @returns User's credit information
+   * @throws AuthorizationError if API key is invalid
+   */
+  async getUserCredits(userId) {
+    return this.request(`/api/admin/credits/users/${userId}`);
+  }
+  /**
+   * Add credits to a user's account
+   *
+   * Credits are added to bonusCredits, which don't expire on monthly reset.
+   *
+   * @param userId - ID of the user
+   * @param amount - Amount of credits to add
+   * @param description - Reason for adding credits
+   * @throws AuthorizationError if API key is invalid
+   */
+  async addCredits(userId, amount, description) {
+    await this.request(
+      `/api/admin/credits/users/${userId}/add`,
+      {
+        method: "POST",
+        body: { amount, description }
+      }
+    );
+  }
+  /**
+   * Update a user's subscription tier
+   *
+   * @param userId - ID of the user
+   * @param tier - New subscription tier
+   * @param expiresAt - Optional expiration date (ISO 8601)
+   * @throws AuthorizationError if API key is invalid
+   */
+  async updateSubscription(userId, tier, expiresAt) {
+    const body = { tier };
+    if (expiresAt) {
+      body.expiresAt = expiresAt;
+    }
+    await this.request(
+      `/api/admin/credits/users/${userId}/subscription`,
+      {
+        method: "PUT",
+        body
+      }
+    );
+  }
+  /**
+   * Get the current credits configuration
+   *
+   * @returns Credits system configuration
+   * @throws AuthorizationError if API key is invalid
+   */
+  async getConfig() {
+    return this.request("/api/admin/credits/config");
+  }
+  /**
+   * Update operation costs
+   *
+   * @param costs - New operation costs (operation type -> cost)
+   * @throws AuthorizationError if API key is invalid
+   */
+  async updateCosts(costs) {
+    await this.request("/api/admin/credits/config/costs", {
+      method: "PUT",
+      body: { operationCosts: costs }
+    });
+  }
+  /**
+   * List all users with their credits
+   *
+   * @param options - Pagination and filtering options
+   * @returns Paginated list of users
+   * @throws AuthorizationError if API key is invalid
+   */
+  async listUsers(options) {
+    return this.request("/api/admin/credits/users", {
+      params: {
+        page: options?.page,
+        limit: options?.limit,
+        tier: options?.tier,
+        search: options?.search
+      }
+    });
+  }
+  /**
+   * Deduct credits from a user's account
+   *
+   * @param userId - ID of the user
+   * @param amount - Amount of credits to deduct
+   * @param description - Reason for deducting credits
+   * @throws AuthorizationError if API key is invalid
+   */
+  async deductCredits(userId, amount, description) {
+    await this.request(
+      `/api/admin/credits/users/${userId}/deduct`,
+      {
+        method: "POST",
+        body: { amount, description }
+      }
+    );
+  }
+  /**
+   * Get usage statistics for a user
+   *
+   * @param userId - ID of the user
+   * @param options - Optional date range
+   * @returns Usage statistics
+   * @throws AuthorizationError if API key is invalid
+   */
+  async getUserStats(userId, options) {
+    return this.request(`/api/admin/credits/users/${userId}/stats`, {
+      params: {
+        startDate: options?.startDate,
+        endDate: options?.endDate
+      }
+    });
+  }
+};
+
+// src/utils/error-utils.ts
+function parseCreditError(error) {
+  const match = error.match(/Available:\s*(\d+)\s*,\s*Required:\s*(\d+)/i);
+  if (!match) {
+    return null;
+  }
+  const available = parseInt(match[1], 10);
+  const required = parseInt(match[2], 10);
+  if (isNaN(available) || isNaN(required)) {
+    return null;
+  }
+  return {
+    available,
+    required,
+    shortfall: required - available,
+    rawMessage: error
+  };
+}
+function isCreditErrorMessage(error) {
+  const lowerError = error.toLowerCase();
+  return lowerError.includes("insufficient credits") || lowerError.includes("not enough credits");
+}
+
+// src/utils/index.ts
+function getTotalCredits(credits) {
+  return credits.balance + credits.bonusCredits;
+}
+function generateRequestId2() {
+  const timestamp = Date.now();
+  const randomPart = Math.random().toString(36).substring(2, 14);
+  return `req_${timestamp}_${randomPart}`;
+}
+function isPreviewMode2(data) {
+  return typeof data === "object" && data !== null && "preview" in data && data.preview === true;
+}
+function createDummyReservation2(userId, operationType) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    id: "preview-mode",
+    userId,
+    amount: 0,
+    operationType,
+    status: "released",
+    createdAt: now,
+    expiresAt: now
+  };
+}
+export {
+  AdminCreditsClient,
+  ApiKeyCreditsProvider,
+  AuthenticationError,
+  AuthorizationError,
+  ConsoleNotificationHandler,
+  CreditError,
+  CreditErrorCode,
+  CreditsClient,
+  CreditsSDKError,
+  CreditsService,
+  InMemoryCreditRepository,
+  NetworkError,
+  SDKErrorCode,
+  InsufficientCreditsError as SDKInsufficientCreditsError,
+  ReservationExpiredError as SDKReservationExpiredError,
+  ReservationNotFoundError as SDKReservationNotFoundError,
+  ServerError,
+  ValidationError,
+  calculateAvailableCredits,
+  checkAndNotifyLowBalance,
+  clearConfigProvider,
+  clearCooldownState,
+  clearNotificationHandlers,
+  commitReservationWithJournal,
+  createApiKeyProvider,
+  createCreditsService,
+  createDeferredExecutor,
+  createDummyReservation2 as createDummyReservation,
+  createGenericAdapter,
+  createInMemoryCreditRepository,
+  createInsufficientCreditsError,
+  createInvalidOperationTypeError,
+  createReservationAlreadyProcessedError,
+  createReservationExpiredError,
+  createReservationNotFoundError,
+  createUserNotFoundError,
+  generateId,
+  generateRequestId2 as generateRequestId,
+  genericDeferred,
+  getConfig,
+  getConfigMonthlyLimit,
+  getConfigOperationCost,
+  getConfigProvider,
+  getConfigTierConfig,
+  getDefaultFreeCredits,
+  getMonthlyLimit,
+  getNextMonthlyReset,
+  getOperationCost,
+  getOperationCosts,
+  getOperationCostsWithLabels,
+  getOperationLabel,
+  getOperationLabels,
+  getReservationExpiryMs,
+  getTierConfig,
+  getTotalCredits,
+  getValidOperationTypes,
+  initializeConfig,
+  isCreditError,
+  isCreditErrorMessage,
+  isFeatureEnabled,
+  isInsufficientCreditsError,
+  isPreviewMode2 as isPreviewMode,
+  isValidOperationType,
+  loadConfigFromEnv,
+  noopDeferred,
+  notifySubscriptionExpired,
+  notifySubscriptionExpiring,
+  parseApiError,
+  parseCreditError,
+  registerConfigProvider,
+  registerNotificationHandler,
+  releaseReservationWithJournal,
+  reserveCreditsForOperation,
+  resetConfig,
+  synchronousDeferred,
+  toClientUserCredits,
+  toDate,
+  toPortableTimestamp,
+  verifyAdminApiKey,
+  verifyBearerToken
+};
 //# sourceMappingURL=index.js.map