@nehorai/credits 1.4.0 → 1.6.0

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(src_exports, {
   SDKReservationExpiredError: () => ReservationExpiredError,
   SDKReservationNotFoundError: () => ReservationNotFoundError,
   ServerError: () => ServerError,
+  UNLIMITED_BALANCE_SENTINEL: () => UNLIMITED_BALANCE_SENTINEL,
   ValidationError: () => ValidationError,
   calculateAvailableCredits: () => calculateAvailableCredits,
   checkAndNotifyLowBalance: () => checkAndNotifyLowBalance,
@@ -65,6 +66,7 @@ __export(src_exports, {
   getConfigProvider: () => getConfigProvider,
   getConfigTierConfig: () => getConfigTierConfig,
   getDefaultFreeCredits: () => getDefaultFreeCredits,
+  getDefaultTier: () => getDefaultTier,
   getMonthlyLimit: () => getMonthlyLimit,
   getNextMonthlyReset: () => getNextMonthlyReset,
   getOperationCost: () => getOperationCost,
@@ -75,26 +77,33 @@ __export(src_exports, {
   getReservationExpiryMs: () => getReservationExpiryMs,
   getTierConfig: () => getTierConfig,
   getTotalCredits: () => getTotalCredits,
+  getUnlimitedSentinelBalance: () => getUnlimitedSentinelBalance,
   getValidOperationTypes: () => getValidOperationTypes,
+  getValidTiers: () => getValidTiers,
   initializeConfig: () => initializeConfig,
   isCreditError: () => isCreditError,
   isCreditErrorMessage: () => isCreditErrorMessage,
   isFeatureEnabled: () => isFeatureEnabled,
+  isFreeTier: () => isFreeTier,
   isInsufficientCreditsError: () => isInsufficientCreditsError,
   isPreviewMode: () => isPreviewMode2,
+  isUnlimitedTier: () => isUnlimitedTier,
   isValidOperationType: () => isValidOperationType,
+  isValidTier: () => isValidTier,
   loadConfigFromEnv: () => loadConfigFromEnv,
   noopDeferred: () => noopDeferred,
   notifySubscriptionExpired: () => notifySubscriptionExpired,
   notifySubscriptionExpiring: () => notifySubscriptionExpiring,
   parseApiError: () => parseApiError,
   parseCreditError: () => parseCreditError,
+  parseTier: () => parseTier,
   registerConfigProvider: () => registerConfigProvider,
   registerNotificationHandler: () => registerNotificationHandler,
   releaseReservationWithJournal: () => releaseReservationWithJournal,
   reserveCreditsForOperation: () => reserveCreditsForOperation,
   resetConfig: () => resetConfig,
   synchronousDeferred: () => synchronousDeferred,
+  tierSchema: () => tierSchema,
   toClientUserCredits: () => toClientUserCredits,
   toDate: () => toDate,
   toPortableTimestamp: () => toPortableTimestamp,
@@ -270,10 +279,13 @@ function clearConfigProvider() {
 
 // src/config/index.ts
 var tierConfigSchema = import_zod.z.object({
-  tier: import_zod.z.enum(["free", "basic", "premium", "unlimited"]),
+  tier: import_zod.z.string().min(1),
   monthlyCredits: import_zod.z.number().min(0),
   priceUsd: import_zod.z.number().min(0),
-  features: import_zod.z.array(import_zod.z.string())
+  features: import_zod.z.array(import_zod.z.string()),
+  isFree: import_zod.z.boolean().optional(),
+  unlimited: import_zod.z.boolean().optional(),
+  isDefault: import_zod.z.boolean().optional()
 });
 var creditSystemConfigSchema = import_zod.z.object({
   /**
@@ -297,7 +309,7 @@ var creditSystemConfigSchema = import_zod.z.object({
    * Tier configurations
    */
   tierConfigs: import_zod.z.record(
-    import_zod.z.enum(["free", "basic", "premium", "unlimited"]),
+    import_zod.z.string().min(1),
     tierConfigSchema
   ),
   /**
@@ -353,6 +365,8 @@ var DEFAULT_CONFIG = {
       tier: "free",
       monthlyCredits: 25,
       priceUsd: 0,
+      isFree: true,
+      isDefault: true,
       features: [
         "25 credits per month",
         "Basic story generation",
@@ -386,6 +400,7 @@ var DEFAULT_CONFIG = {
       tier: "unlimited",
       monthlyCredits: 0,
       // 0 = unlimited
+      unlimited: true,
       priceUsd: 49.99,
       features: [
         "Unlimited credits",
@@ -513,12 +528,46 @@ function getConfigOperationCost(operationType) {
   }
   return cost;
 }
+function getValidTiers() {
+  return Object.keys(getConfig().tierConfigs);
+}
+function isValidTier(tier) {
+  return tier in getConfig().tierConfigs;
+}
+function isFreeTier(tier) {
+  const c = getConfig().tierConfigs[tier];
+  if (!c) return false;
+  return c.isFree ?? c.priceUsd === 0;
+}
+function isUnlimitedTier(tier) {
+  const c = getConfig().tierConfigs[tier];
+  if (!c) return false;
+  return c.unlimited ?? c.monthlyCredits === 0;
+}
+function getDefaultTier() {
+  const entries = Object.entries(getConfig().tierConfigs);
+  const def = entries.find(([, c]) => c.isDefault)?.[0] ?? entries.find(([, c]) => c.isFree ?? c.priceUsd === 0)?.[0];
+  return def ?? "free";
+}
+var UNLIMITED_BALANCE_SENTINEL = 999999;
+function getUnlimitedSentinelBalance() {
+  return UNLIMITED_BALANCE_SENTINEL;
+}
 function getConfigTierConfig(tier) {
-  return getConfig().tierConfigs[tier];
+  const cfg = getConfig().tierConfigs[tier];
+  if (cfg) return cfg;
+  const fallback = getDefaultTier();
+  console.warn(
+    `[Credits Config] Unknown tier "${tier}". Falling back to "${fallback}". Valid: ${getValidTiers().join(", ")}`
+  );
+  return getConfig().tierConfigs[fallback];
 }
 function getConfigMonthlyLimit(tier) {
-  const config = getConfig().tierConfigs[tier];
-  return config.monthlyCredits === 0 ? Infinity : config.monthlyCredits;
+  return isUnlimitedTier(tier) ? Infinity : getConfigTierConfig(tier).monthlyCredits;
+}
+var tierSchema = import_zod.z.string().refine(isValidTier, { message: "Unknown subscription tier" });
+function parseTier(value) {
+  return tierSchema.parse(value);
 }
 function isFeatureEnabled(feature) {
   return getConfig().features[feature];
@@ -1093,7 +1142,7 @@ var InMemoryCreditRepository = class {
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
-    if (credits.tier === "free" || !credits.subscriptionExpiresAt) {
+    if (isFreeTier(credits.tier) || !credits.subscriptionExpiresAt) {
       return {
         wasDowngraded: false,
         inGracePeriod: false,
@@ -1120,11 +1169,11 @@ var InMemoryCreditRepository = class {
         credits
       };
     }
-    const config = getConfig();
-    const freeTierConfig = config.tierConfigs.free;
-    credits.tier = "free";
-    credits.monthlyLimit = freeTierConfig.monthlyCredits;
-    credits.balance = Math.min(credits.balance, freeTierConfig.monthlyCredits);
+    const defaultTier = getDefaultTier();
+    const defaultTierConfig = getConfigTierConfig(defaultTier);
+    credits.tier = defaultTier;
+    credits.monthlyLimit = defaultTierConfig.monthlyCredits;
+    credits.balance = Math.min(credits.balance, defaultTierConfig.monthlyCredits);
     credits.subscriptionExpiresAt = null;
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.users.set(userId, credits);
@@ -1264,7 +1313,7 @@ var CreditsService = class {
     if (!data) {
       return null;
     }
-    if (data.tier !== "free" && data.subscriptionExpiresAt) {
+    if (!isFreeTier(data.tier) && data.subscriptionExpiresAt) {
       const expiryResult = await this.repository.checkAndHandleSubscriptionExpiry(
         userId,
         getConfig().subscriptionGracePeriodDays
@@ -1333,7 +1382,7 @@ var CreditsService = class {
   async initializeUserCredits(userId) {
     const credits = await this.repository.initializeUserCredits(
       userId,
-      "free",
+      getDefaultTier(),
       getConfig().defaultFreeCredits
     );
     return toClientUserCredits(credits);
@@ -1465,6 +1514,83 @@ var CreditsService = class {
   async addCredits(userId, amount, description, paymentRef) {
     return this.repository.addCreditsAtomic(userId, amount, description, paymentRef);
   }
+  /**
+   * One-shot atomic "deduct-if-sufficient" credit charge.
+   *
+   * Unlike the reserve/commit/release two-phase flow, this performs a single
+   * atomic check-and-deduct against the repository — suited for synchronous,
+   * in-request operations that don't need a hold across an async job. Exactly
+   * one call is made to `repository.deductCreditsAtomic`, which enforces
+   * atomicity so concurrent callers can never both succeed against the same
+   * limited balance.
+   *
+   * On success, creates a journal entry (same audit trail as `commitCredits`)
+   * and, if `options.operationType` is provided, a usage log entry via the
+   * same `logUsage` path.
+   *
+   * @param userId - User ID
+   * @param amount - Credits to deduct (must be > 0)
+   * @param options - Optional usage-log / journal metadata
+   * @returns Typed result: `{ success: true, newBalance }` or
+   *   `{ success: false, reason: 'insufficient', available, required, shortfall }`
+   * @throws Error if amount is not a positive number
+   */
+  async deductCredits(userId, amount, options) {
+    if (!(amount > 0)) {
+      throw new Error(`deductCredits amount must be positive (got ${amount})`);
+    }
+    let deduction;
+    try {
+      deduction = await this.repository.deductCreditsAtomic(userId, amount);
+    } catch (error) {
+      const credits = await this.repository.getUserCredits(userId);
+      const available = credits ? credits.balance + credits.bonusCredits - credits.reserved : 0;
+      if (available >= amount) {
+        throw error;
+      }
+      return {
+        success: false,
+        reason: "insufficient",
+        available,
+        required: amount,
+        shortfall: amount - available
+      };
+    }
+    const operationType = options?.operationType;
+    await this.repository.createJournalEntry({
+      userId,
+      entryType: "debit",
+      amount,
+      balanceAfter: deduction.newBalance,
+      source: "operation_commit",
+      referenceId: options?.requestId ?? `deduct-${Date.now()}`,
+      referenceType: "adjustment",
+      description: operationType ? `Deducted ${amount} credits for ${getOperationLabel(operationType)}` : `Deducted ${amount} credits`,
+      metadata: {
+        ...operationType && { operationType },
+        ...options?.metadata
+      }
+    });
+    if (operationType) {
+      await this.logUsage({
+        userId,
+        operationType,
+        provider: "gemini",
+        creditsUsed: amount,
+        success: true,
+        resourceId: options?.resourceId,
+        resourceType: options?.resourceType,
+        requestId: options?.requestId,
+        metadata: options?.metadata
+      });
+    }
+    if (this.lowBalanceCallback) {
+      this.lowBalanceCallback(userId, deduction.newBalance).catch((error) => {
+        console.error("[Credits] Failed to send low balance notification:", error);
+      });
+    }
+    return { success: true, newBalance: deduction.newBalance };
+  }
   /**
    * Update user subscription tier
    * @param userId - User ID
@@ -1473,12 +1599,15 @@ var CreditsService = class {
    */
   async updateTier(userId, tier, expiresAt) {
     const monthlyLimit = getConfigMonthlyLimit(tier);
+    const unlimited = isUnlimitedTier(tier);
+    const free = isFreeTier(tier);
     await this.repository.updateUserTier(userId, {
       tier,
-      monthlyLimit: monthlyLimit === Infinity ? 0 : monthlyLimit,
+      // Stored monthlyLimit uses the 0-means-unlimited convention.
+      monthlyLimit: unlimited ? 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,
+      balance: !free ? unlimited ? getUnlimitedSentinelBalance() : monthlyLimit : void 0,
+      monthlyUsed: !free ? 0 : void 0,
       subscriptionExpiresAt: expiresAt ? expiresAt.toISOString() : null
     });
   }
@@ -2447,6 +2576,7 @@ function createDummyReservation2(userId, operationType) {
   SDKReservationExpiredError,
   SDKReservationNotFoundError,
   ServerError,
+  UNLIMITED_BALANCE_SENTINEL,
   ValidationError,
   calculateAvailableCredits,
   checkAndNotifyLowBalance,
@@ -2475,6 +2605,7 @@ function createDummyReservation2(userId, operationType) {
   getConfigProvider,
   getConfigTierConfig,
   getDefaultFreeCredits,
+  getDefaultTier,
   getMonthlyLimit,
   getNextMonthlyReset,
   getOperationCost,
@@ -2485,26 +2616,33 @@ function createDummyReservation2(userId, operationType) {
   getReservationExpiryMs,
   getTierConfig,
   getTotalCredits,
+  getUnlimitedSentinelBalance,
   getValidOperationTypes,
+  getValidTiers,
   initializeConfig,
   isCreditError,
   isCreditErrorMessage,
   isFeatureEnabled,
+  isFreeTier,
   isInsufficientCreditsError,
   isPreviewMode,
+  isUnlimitedTier,
   isValidOperationType,
+  isValidTier,
   loadConfigFromEnv,
   noopDeferred,
   notifySubscriptionExpired,
   notifySubscriptionExpiring,
   parseApiError,
   parseCreditError,
+  parseTier,
   registerConfigProvider,
   registerNotificationHandler,
   releaseReservationWithJournal,
   reserveCreditsForOperation,
   resetConfig,
   synchronousDeferred,
+  tierSchema,
   toClientUserCredits,
   toDate,
   toPortableTimestamp,