@nehorai/credits 1.2.0 → 1.4.0

package/dist/service/index.cjs

@@ -0,0 +1,675 @@
+"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/service/index.ts
+var service_exports = {};
+__export(service_exports, {
+  CreditsService: () => CreditsService,
+  createCreditsService: () => createCreditsService
+});
+module.exports = __toCommonJS(service_exports);
+
+// src/core/types.ts
+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/repository/types.ts
+function toClientUserCredits(credits) {
+  return {
+    userId: credits.userId,
+    balance: credits.balance,
+    bonusCredits: credits.bonusCredits ?? 0,
+    reserved: credits.reserved,
+    tier: credits.tier,
+    monthlyLimit: credits.monthlyLimit,
+    monthlyUsed: credits.monthlyUsed,
+    monthlyResetAt: toISOString(credits.monthlyResetAt),
+    subscriptionExpiresAt: credits.subscriptionExpiresAt ? toISOString(credits.subscriptionExpiresAt) : null,
+    createdAt: toISOString(credits.createdAt),
+    updatedAt: toISOString(credits.updatedAt)
+  };
+}
+function toISOString(value) {
+  if (!value) return (/* @__PURE__ */ new Date()).toISOString();
+  if (typeof value === "string") return value;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object" && "toDate" in value && typeof value.toDate === "function") {
+    return value.toDate().toISOString();
+  }
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/config/index.ts
+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 getConfigMonthlyLimit(tier) {
+  const config = getConfig().tierConfigs[tier];
+  return config.monthlyCredits === 0 ? Infinity : config.monthlyCredits;
+}
+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/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);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CreditsService,
+  createCreditsService
+});
+//# sourceMappingURL=index.cjs.map