@nehorai/credits 1.4.0 → 1.6.0

package/dist/index.d.cts

@@ -1,13 +1,13 @@
-import { S as SubscriptionTier, T as TierConfig, c as PortableReservation } from './types-BBxIWHK2.cjs';
-export { A as AIProviderType, g as CreditCheckResult, a as CreditOperationType, C as CreditSource, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, b as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, b as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-BBxIWHK2.cjs';
+import { S as SubscriptionTier, T as TierConfig, c as PortableReservation } from './types-CjLj3GW5.cjs';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, a as CreditOperationType, C as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, b as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, b as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-CjLj3GW5.cjs';
 export { CreditError, CreditErrorCode, CreditErrorCodeType, commitReservationWithJournal, createInsufficientCreditsError, createInvalidOperationTypeError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createUserNotFoundError, isCreditError, isInsufficientCreditsError, releaseReservationWithJournal, reserveCreditsForOperation } from './core/index.cjs';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from './deferred-C7rrRfkm.cjs';
 import { z } from 'zod';
-export { C as CreateJournalEntryInput, a as CreateReservationInput, b as CreateTransactionInput, c as CreateUsageLogInput, d as CreditBalanceUpdate, e as CreditRepositoryFactory, I as ICreditRepository, J as JournalEntryQuery, T as TierUpdateInput, U as UsageLogQuery, t as toClientUserCredits } from './types-D1vdeBcA.cjs';
+export { C as CreateJournalEntryInput, a as CreateReservationInput, b as CreateTransactionInput, c as CreateUsageLogInput, d as CreditBalanceUpdate, e as CreditRepositoryFactory, I as ICreditRepository, J as JournalEntryQuery, T as TierUpdateInput, U as UsageLogQuery, t as toClientUserCredits } from './types-CZNv1U3e.cjs';
 export { InMemoryCreditRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset } from './repository/index.cjs';
 export { C as CreditsAuthProviderFactory, a as CreditsUser, I as ICreditsAuthProvider } from './types-OZU3I5OM.cjs';
 export { ApiKeyCreditsProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken } from './auth/index.cjs';
-export { CreditsService, LowBalanceNotificationCallback, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.cjs';
+export { CreditsService, DeductCreditsOptions, LowBalanceNotificationCallback, ReserveCreditsOptions, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.cjs';
 export { ActionResult, CreditActionHandler, CreditsAdapter, CreditsAdapterConfig, createGenericAdapter } from './adapters/index.cjs';
 export { AdminCreditsClient, AdminCreditsClientConfig, ApiResponse, AuthenticationError, AuthorizationError, CreditsClient, CreditsClientConfig, CreditsConfig, CreditsSDKError, ListUsersOptions, ListUsersResponse, NetworkError, PaginationOptions, ReservationResult, SDKErrorCode, SDKErrorCodeType, InsufficientCreditsError as SDKInsufficientCreditsError, ReservationExpiredError as SDKReservationExpiredError, ReservationNotFoundError as SDKReservationNotFoundError, UsageHistoryEntry as SDKUsageHistoryEntry, UsageHistoryResponse as SDKUsageHistoryResponse, ServerError, ValidationError, parseApiError } from './sdk/index.cjs';
 
@@ -29,21 +29,30 @@ declare const creditSystemConfigSchema: z.ZodObject<{
     /**
      * Tier configurations
      */
-    tierConfigs: z.ZodRecord<z.ZodEnum<["free", "basic", "premium", "unlimited"]>, z.ZodObject<{
-        tier: z.ZodEnum<["free", "basic", "premium", "unlimited"]>;
+    tierConfigs: z.ZodRecord<z.ZodString, z.ZodObject<{
+        tier: z.ZodString;
         monthlyCredits: z.ZodNumber;
         priceUsd: z.ZodNumber;
         features: z.ZodArray<z.ZodString, "many">;
+        isFree: z.ZodOptional<z.ZodBoolean>;
+        unlimited: z.ZodOptional<z.ZodBoolean>;
+        isDefault: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        tier: "free" | "basic" | "premium" | "unlimited";
+        tier: string;
         monthlyCredits: number;
         priceUsd: number;
         features: string[];
+        unlimited?: boolean | undefined;
+        isFree?: boolean | undefined;
+        isDefault?: boolean | undefined;
     }, {
-        tier: "free" | "basic" | "premium" | "unlimited";
+        tier: string;
         monthlyCredits: number;
         priceUsd: number;
         features: string[];
+        unlimited?: boolean | undefined;
+        isFree?: boolean | undefined;
+        isDefault?: boolean | undefined;
     }>>;
     /**
      * Reservation expiry time in milliseconds
@@ -87,12 +96,15 @@ declare const creditSystemConfigSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     operationCosts: Record<string, number>;
     operationLabels: Record<string, string>;
-    tierConfigs: Partial<Record<"free" | "basic" | "premium" | "unlimited", {
-        tier: "free" | "basic" | "premium" | "unlimited";
+    tierConfigs: Record<string, {
+        tier: string;
         monthlyCredits: number;
         priceUsd: number;
         features: string[];
-    }>>;
+        unlimited?: boolean | undefined;
+        isFree?: boolean | undefined;
+        isDefault?: boolean | undefined;
+    }>;
     features: {
         journalEntries: boolean;
         notifications: boolean;
@@ -106,12 +118,15 @@ declare const creditSystemConfigSchema: z.ZodObject<{
     lowBalanceNotificationCooldownHours: number;
 }, {
     operationCosts: Record<string, number>;
-    tierConfigs: Partial<Record<"free" | "basic" | "premium" | "unlimited", {
-        tier: "free" | "basic" | "premium" | "unlimited";
+    tierConfigs: Record<string, {
+        tier: string;
         monthlyCredits: number;
         priceUsd: number;
         features: string[];
-    }>>;
+        unlimited?: boolean | undefined;
+        isFree?: boolean | undefined;
+        isDefault?: boolean | undefined;
+    }>;
     operationLabels?: Record<string, string> | undefined;
     features?: {
         journalEntries?: boolean | undefined;
@@ -165,7 +180,41 @@ declare function isValidOperationType(type: string): boolean;
  */
 declare function getConfigOperationCost(operationType: string): number;
 /**
- * Get tier configuration from configuration
+ * Get all valid tier ids from configuration
+ * Returns the keys of the tierConfigs object
+ */
+declare function getValidTiers(): string[];
+/**
+ * Check if a tier id is valid (configured in the system)
+ */
+declare function isValidTier(tier: string): boolean;
+/**
+ * Check if a tier is the free/default tier.
+ * Falls back to priceUsd === 0 when the isFree flag is not set.
+ */
+declare function isFreeTier(tier: SubscriptionTier): boolean;
+/**
+ * Check if a tier is unlimited.
+ * Falls back to monthlyCredits === 0 when the unlimited flag is not set.
+ */
+declare function isUnlimitedTier(tier: SubscriptionTier): boolean;
+/**
+ * Get the tier assigned to brand-new users.
+ * Prefers the tier flagged isDefault, then the first isFree tier, then "free".
+ */
+declare function getDefaultTier(): SubscriptionTier;
+/**
+ * Magic balance assigned to unlimited tiers on upgrade.
+ * Kept at 999999 for back-compat with stored/displayed balances.
+ */
+declare const UNLIMITED_BALANCE_SENTINEL = 999999;
+/**
+ * Get the magic balance assigned to unlimited tiers on upgrade.
+ */
+declare function getUnlimitedSentinelBalance(): number;
+/**
+ * Get tier configuration from configuration.
+ * Falls back to the default tier (with a warning) if the tier is unknown.
  */
 declare function getConfigTierConfig(tier: SubscriptionTier): TierConfig;
 /**
@@ -173,6 +222,16 @@ declare function getConfigTierConfig(tier: SubscriptionTier): TierConfig;
  * Returns Infinity for unlimited tier
  */
 declare function getConfigMonthlyLimit(tier: SubscriptionTier): number;
+/**
+ * Runtime zod validator for tier ids. Validates against the LIVE config keys
+ * at parse time, so apps that add tiers via config get correct validation.
+ */
+declare const tierSchema: z.ZodType<SubscriptionTier>;
+/**
+ * Parse/validate a tier id against the live config keys.
+ * @throws ZodError if the tier is not configured
+ */
+declare function parseTier(value: unknown): SubscriptionTier;
 /**
  * Check if a feature is enabled
  */
@@ -434,4 +493,4 @@ declare function isPreviewMode(data: unknown): boolean;
  */
 declare function createDummyReservation(userId: string, operationType: string): PortableReservation;
 
-export { ConsoleNotificationHandler, type CreditErrorInfo, type CreditNotificationEvent, PortableReservation as CreditReservation, type CreditSystemConfig, type ICreditConfigProvider, type ICreditNotificationHandler, type OperationCostInfo, PortableReservation, SubscriptionTier as SDKSubscriptionTier, SubscriptionTier, TierConfig, checkAndNotifyLowBalance, clearConfigProvider, clearCooldownState, clearNotificationHandlers, createDummyReservation, generateRequestId, getConfig, getConfigMonthlyLimit, getConfigOperationCost, getConfigProvider, getConfigTierConfig, getDefaultFreeCredits, getMonthlyLimit, getOperationCost, getOperationCosts, getOperationCostsWithLabels, getOperationLabel, getOperationLabels, getReservationExpiryMs, getTierConfig, getTotalCredits, getValidOperationTypes, initializeConfig, isCreditErrorMessage, isFeatureEnabled, isPreviewMode, isValidOperationType, loadConfigFromEnv, notifySubscriptionExpired, notifySubscriptionExpiring, parseCreditError, registerConfigProvider, registerNotificationHandler, resetConfig };
+export { ConsoleNotificationHandler, type CreditErrorInfo, type CreditNotificationEvent, PortableReservation as CreditReservation, type CreditSystemConfig, type ICreditConfigProvider, type ICreditNotificationHandler, type OperationCostInfo, PortableReservation, SubscriptionTier as SDKSubscriptionTier, SubscriptionTier, TierConfig, UNLIMITED_BALANCE_SENTINEL, checkAndNotifyLowBalance, clearConfigProvider, clearCooldownState, clearNotificationHandlers, createDummyReservation, generateRequestId, getConfig, getConfigMonthlyLimit, getConfigOperationCost, getConfigProvider, getConfigTierConfig, getDefaultFreeCredits, getDefaultTier, getMonthlyLimit, getOperationCost, getOperationCosts, getOperationCostsWithLabels, getOperationLabel, getOperationLabels, getReservationExpiryMs, getTierConfig, getTotalCredits, getUnlimitedSentinelBalance, getValidOperationTypes, getValidTiers, initializeConfig, isCreditErrorMessage, isFeatureEnabled, isFreeTier, isPreviewMode, isUnlimitedTier, isValidOperationType, isValidTier, loadConfigFromEnv, notifySubscriptionExpired, notifySubscriptionExpiring, parseCreditError, parseTier, registerConfigProvider, registerNotificationHandler, resetConfig, tierSchema };

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-import { S as SubscriptionTier, T as TierConfig, c as PortableReservation } from './types-BBxIWHK2.js';
-export { A as AIProviderType, g as CreditCheckResult, a as CreditOperationType, C as CreditSource, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, b as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, b as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-BBxIWHK2.js';
+import { S as SubscriptionTier, T as TierConfig, c as PortableReservation } from './types-CjLj3GW5.js';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, a as CreditOperationType, C as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, b as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, b as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-CjLj3GW5.js';
 export { CreditError, CreditErrorCode, CreditErrorCodeType, commitReservationWithJournal, createInsufficientCreditsError, createInvalidOperationTypeError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createUserNotFoundError, isCreditError, isInsufficientCreditsError, releaseReservationWithJournal, reserveCreditsForOperation } from './core/index.js';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from './deferred-C7rrRfkm.js';
 import { z } from 'zod';
-export { C as CreateJournalEntryInput, a as CreateReservationInput, b as CreateTransactionInput, c as CreateUsageLogInput, d as CreditBalanceUpdate, e as CreditRepositoryFactory, I as ICreditRepository, J as JournalEntryQuery, T as TierUpdateInput, U as UsageLogQuery, t as toClientUserCredits } from './types-aJsyv8df.js';
+export { C as CreateJournalEntryInput, a as CreateReservationInput, b as CreateTransactionInput, c as CreateUsageLogInput, d as CreditBalanceUpdate, e as CreditRepositoryFactory, I as ICreditRepository, J as JournalEntryQuery, T as TierUpdateInput, U as UsageLogQuery, t as toClientUserCredits } from './types-G4WK0rM-.js';
 export { InMemoryCreditRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset } from './repository/index.js';
 export { C as CreditsAuthProviderFactory, a as CreditsUser, I as ICreditsAuthProvider } from './types-OZU3I5OM.js';
 export { ApiKeyCreditsProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken } from './auth/index.js';
-export { CreditsService, LowBalanceNotificationCallback, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.js';
+export { CreditsService, DeductCreditsOptions, LowBalanceNotificationCallback, ReserveCreditsOptions, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.js';
 export { ActionResult, CreditActionHandler, CreditsAdapter, CreditsAdapterConfig, createGenericAdapter } from './adapters/index.js';
 export { AdminCreditsClient, AdminCreditsClientConfig, ApiResponse, AuthenticationError, AuthorizationError, CreditsClient, CreditsClientConfig, CreditsConfig, CreditsSDKError, ListUsersOptions, ListUsersResponse, NetworkError, PaginationOptions, ReservationResult, SDKErrorCode, SDKErrorCodeType, InsufficientCreditsError as SDKInsufficientCreditsError, ReservationExpiredError as SDKReservationExpiredError, ReservationNotFoundError as SDKReservationNotFoundError, UsageHistoryEntry as SDKUsageHistoryEntry, UsageHistoryResponse as SDKUsageHistoryResponse, ServerError, ValidationError, parseApiError } from './sdk/index.js';
 
@@ -29,21 +29,30 @@ declare const creditSystemConfigSchema: z.ZodObject<{
     /**
      * Tier configurations
      */
-    tierConfigs: z.ZodRecord<z.ZodEnum<["free", "basic", "premium", "unlimited"]>, z.ZodObject<{
-        tier: z.ZodEnum<["free", "basic", "premium", "unlimited"]>;
+    tierConfigs: z.ZodRecord<z.ZodString, z.ZodObject<{
+        tier: z.ZodString;
         monthlyCredits: z.ZodNumber;
         priceUsd: z.ZodNumber;
         features: z.ZodArray<z.ZodString, "many">;
+        isFree: z.ZodOptional<z.ZodBoolean>;
+        unlimited: z.ZodOptional<z.ZodBoolean>;
+        isDefault: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        tier: "free" | "basic" | "premium" | "unlimited";
+        tier: string;
         monthlyCredits: number;
         priceUsd: number;
         features: string[];
+        unlimited?: boolean | undefined;
+        isFree?: boolean | undefined;
+        isDefault?: boolean | undefined;
     }, {
-        tier: "free" | "basic" | "premium" | "unlimited";
+        tier: string;
         monthlyCredits: number;
         priceUsd: number;
         features: string[];
+        unlimited?: boolean | undefined;
+        isFree?: boolean | undefined;
+        isDefault?: boolean | undefined;
     }>>;
     /**
      * Reservation expiry time in milliseconds
@@ -87,12 +96,15 @@ declare const creditSystemConfigSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     operationCosts: Record<string, number>;
     operationLabels: Record<string, string>;
-    tierConfigs: Partial<Record<"free" | "basic" | "premium" | "unlimited", {
-        tier: "free" | "basic" | "premium" | "unlimited";
+    tierConfigs: Record<string, {
+        tier: string;
         monthlyCredits: number;
         priceUsd: number;
         features: string[];
-    }>>;
+        unlimited?: boolean | undefined;
+        isFree?: boolean | undefined;
+        isDefault?: boolean | undefined;
+    }>;
     features: {
         journalEntries: boolean;
         notifications: boolean;
@@ -106,12 +118,15 @@ declare const creditSystemConfigSchema: z.ZodObject<{
     lowBalanceNotificationCooldownHours: number;
 }, {
     operationCosts: Record<string, number>;
-    tierConfigs: Partial<Record<"free" | "basic" | "premium" | "unlimited", {
-        tier: "free" | "basic" | "premium" | "unlimited";
+    tierConfigs: Record<string, {
+        tier: string;
         monthlyCredits: number;
         priceUsd: number;
         features: string[];
-    }>>;
+        unlimited?: boolean | undefined;
+        isFree?: boolean | undefined;
+        isDefault?: boolean | undefined;
+    }>;
     operationLabels?: Record<string, string> | undefined;
     features?: {
         journalEntries?: boolean | undefined;
@@ -165,7 +180,41 @@ declare function isValidOperationType(type: string): boolean;
  */
 declare function getConfigOperationCost(operationType: string): number;
 /**
- * Get tier configuration from configuration
+ * Get all valid tier ids from configuration
+ * Returns the keys of the tierConfigs object
+ */
+declare function getValidTiers(): string[];
+/**
+ * Check if a tier id is valid (configured in the system)
+ */
+declare function isValidTier(tier: string): boolean;
+/**
+ * Check if a tier is the free/default tier.
+ * Falls back to priceUsd === 0 when the isFree flag is not set.
+ */
+declare function isFreeTier(tier: SubscriptionTier): boolean;
+/**
+ * Check if a tier is unlimited.
+ * Falls back to monthlyCredits === 0 when the unlimited flag is not set.
+ */
+declare function isUnlimitedTier(tier: SubscriptionTier): boolean;
+/**
+ * Get the tier assigned to brand-new users.
+ * Prefers the tier flagged isDefault, then the first isFree tier, then "free".
+ */
+declare function getDefaultTier(): SubscriptionTier;
+/**
+ * Magic balance assigned to unlimited tiers on upgrade.
+ * Kept at 999999 for back-compat with stored/displayed balances.
+ */
+declare const UNLIMITED_BALANCE_SENTINEL = 999999;
+/**
+ * Get the magic balance assigned to unlimited tiers on upgrade.
+ */
+declare function getUnlimitedSentinelBalance(): number;
+/**
+ * Get tier configuration from configuration.
+ * Falls back to the default tier (with a warning) if the tier is unknown.
  */
 declare function getConfigTierConfig(tier: SubscriptionTier): TierConfig;
 /**
@@ -173,6 +222,16 @@ declare function getConfigTierConfig(tier: SubscriptionTier): TierConfig;
  * Returns Infinity for unlimited tier
  */
 declare function getConfigMonthlyLimit(tier: SubscriptionTier): number;
+/**
+ * Runtime zod validator for tier ids. Validates against the LIVE config keys
+ * at parse time, so apps that add tiers via config get correct validation.
+ */
+declare const tierSchema: z.ZodType<SubscriptionTier>;
+/**
+ * Parse/validate a tier id against the live config keys.
+ * @throws ZodError if the tier is not configured
+ */
+declare function parseTier(value: unknown): SubscriptionTier;
 /**
  * Check if a feature is enabled
  */
@@ -434,4 +493,4 @@ declare function isPreviewMode(data: unknown): boolean;
  */
 declare function createDummyReservation(userId: string, operationType: string): PortableReservation;
 
-export { ConsoleNotificationHandler, type CreditErrorInfo, type CreditNotificationEvent, PortableReservation as CreditReservation, type CreditSystemConfig, type ICreditConfigProvider, type ICreditNotificationHandler, type OperationCostInfo, PortableReservation, SubscriptionTier as SDKSubscriptionTier, SubscriptionTier, TierConfig, checkAndNotifyLowBalance, clearConfigProvider, clearCooldownState, clearNotificationHandlers, createDummyReservation, generateRequestId, getConfig, getConfigMonthlyLimit, getConfigOperationCost, getConfigProvider, getConfigTierConfig, getDefaultFreeCredits, getMonthlyLimit, getOperationCost, getOperationCosts, getOperationCostsWithLabels, getOperationLabel, getOperationLabels, getReservationExpiryMs, getTierConfig, getTotalCredits, getValidOperationTypes, initializeConfig, isCreditErrorMessage, isFeatureEnabled, isPreviewMode, isValidOperationType, loadConfigFromEnv, notifySubscriptionExpired, notifySubscriptionExpiring, parseCreditError, registerConfigProvider, registerNotificationHandler, resetConfig };
+export { ConsoleNotificationHandler, type CreditErrorInfo, type CreditNotificationEvent, PortableReservation as CreditReservation, type CreditSystemConfig, type ICreditConfigProvider, type ICreditNotificationHandler, type OperationCostInfo, PortableReservation, SubscriptionTier as SDKSubscriptionTier, SubscriptionTier, TierConfig, UNLIMITED_BALANCE_SENTINEL, checkAndNotifyLowBalance, clearConfigProvider, clearCooldownState, clearNotificationHandlers, createDummyReservation, generateRequestId, getConfig, getConfigMonthlyLimit, getConfigOperationCost, getConfigProvider, getConfigTierConfig, getDefaultFreeCredits, getDefaultTier, getMonthlyLimit, getOperationCost, getOperationCosts, getOperationCostsWithLabels, getOperationLabel, getOperationLabels, getReservationExpiryMs, getTierConfig, getTotalCredits, getUnlimitedSentinelBalance, getValidOperationTypes, getValidTiers, initializeConfig, isCreditErrorMessage, isFeatureEnabled, isFreeTier, isPreviewMode, isUnlimitedTier, isValidOperationType, isValidTier, loadConfigFromEnv, notifySubscriptionExpired, notifySubscriptionExpiring, parseCreditError, parseTier, registerConfigProvider, registerNotificationHandler, resetConfig, tierSchema };

package/dist/index.js

@@ -165,10 +165,13 @@ function clearConfigProvider() {
 
 // src/config/index.ts
 var tierConfigSchema = z.object({
-  tier: z.enum(["free", "basic", "premium", "unlimited"]),
+  tier: z.string().min(1),
   monthlyCredits: z.number().min(0),
   priceUsd: z.number().min(0),
-  features: z.array(z.string())
+  features: z.array(z.string()),
+  isFree: z.boolean().optional(),
+  unlimited: z.boolean().optional(),
+  isDefault: z.boolean().optional()
 });
 var creditSystemConfigSchema = z.object({
   /**
@@ -192,7 +195,7 @@ var creditSystemConfigSchema = z.object({
    * Tier configurations
    */
   tierConfigs: z.record(
-    z.enum(["free", "basic", "premium", "unlimited"]),
+    z.string().min(1),
     tierConfigSchema
   ),
   /**
@@ -248,6 +251,8 @@ var DEFAULT_CONFIG = {
       tier: "free",
       monthlyCredits: 25,
       priceUsd: 0,
+      isFree: true,
+      isDefault: true,
       features: [
         "25 credits per month",
         "Basic story generation",
@@ -281,6 +286,7 @@ var DEFAULT_CONFIG = {
       tier: "unlimited",
       monthlyCredits: 0,
       // 0 = unlimited
+      unlimited: true,
       priceUsd: 49.99,
       features: [
         "Unlimited credits",
@@ -408,12 +414,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 = z.string().refine(isValidTier, { message: "Unknown subscription tier" });
+function parseTier(value) {
+  return tierSchema.parse(value);
 }
 function isFeatureEnabled(feature) {
   return getConfig().features[feature];
@@ -988,7 +1028,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,
@@ -1015,11 +1055,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);
@@ -1159,7 +1199,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
@@ -1228,7 +1268,7 @@ var CreditsService = class {
   async initializeUserCredits(userId) {
     const credits = await this.repository.initializeUserCredits(
       userId,
-      "free",
+      getDefaultTier(),
       getConfig().defaultFreeCredits
     );
     return toClientUserCredits(credits);
@@ -1360,6 +1400,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
@@ -1368,12 +1485,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
     });
   }
@@ -2341,6 +2461,7 @@ export {
   ReservationExpiredError as SDKReservationExpiredError,
   ReservationNotFoundError as SDKReservationNotFoundError,
   ServerError,
+  UNLIMITED_BALANCE_SENTINEL,
   ValidationError,
   calculateAvailableCredits,
   checkAndNotifyLowBalance,
@@ -2369,6 +2490,7 @@ export {
   getConfigProvider,
   getConfigTierConfig,
   getDefaultFreeCredits,
+  getDefaultTier,
   getMonthlyLimit,
   getNextMonthlyReset,
   getOperationCost,
@@ -2379,26 +2501,33 @@ export {
   getReservationExpiryMs,
   getTierConfig,
   getTotalCredits,
+  getUnlimitedSentinelBalance,
   getValidOperationTypes,
+  getValidTiers,
   initializeConfig,
   isCreditError,
   isCreditErrorMessage,
   isFeatureEnabled,
+  isFreeTier,
   isInsufficientCreditsError,
   isPreviewMode2 as isPreviewMode,
+  isUnlimitedTier,
   isValidOperationType,
+  isValidTier,
   loadConfigFromEnv,
   noopDeferred,
   notifySubscriptionExpired,
   notifySubscriptionExpiring,
   parseApiError,
   parseCreditError,
+  parseTier,
   registerConfigProvider,
   registerNotificationHandler,
   releaseReservationWithJournal,
   reserveCreditsForOperation,
   resetConfig,
   synchronousDeferred,
+  tierSchema,
   toClientUserCredits,
   toDate,
   toPortableTimestamp,