@nehorai/credits 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -1,13 +1,13 @@
-import { S as SubscriptionTier, T as TierConfig, c as PortableReservation } from './types-DgQtamEe.cjs';
-export { A as AIProviderType, B as BuiltinTier, 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-DgQtamEe.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-KgNdBuEF.cjs';
+export { A as AddCreditsAtomicOptions, 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-DFe5BoJY.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';
 

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-import { S as SubscriptionTier, T as TierConfig, c as PortableReservation } from './types-DgQtamEe.js';
-export { A as AIProviderType, B as BuiltinTier, 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-DgQtamEe.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-fW2JNmmr.js';
+export { A as AddCreditsAtomicOptions, 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-_bSybQnb.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';
 

package/dist/index.js

@@ -798,23 +798,39 @@ var InMemoryCreditRepository = class {
     this.users.set(userId, credits);
     await this.updateReservationStatus(userId, reservationId, "released", /* @__PURE__ */ new Date());
   }
-  async addCreditsAtomic(userId, amount, description, paymentRef) {
+  async addCreditsAtomic(userId, amount, description, paymentRef, options) {
     const credits = this.users.get(userId);
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
-    const previousBalance = credits.bonusCredits;
+    const previousTotal = credits.balance + credits.bonusCredits;
     credits.bonusCredits += amount;
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.users.set(userId, credits);
-    await this.createTransaction({
+    const newTotal = credits.balance + credits.bonusCredits;
+    const transaction = await this.createTransaction({
       userId,
       type: "purchase",
       amount,
       description,
       paymentRef,
-      previousBalance,
-      newBalance: credits.bonusCredits
+      previousBalance: previousTotal,
+      newBalance: newTotal
+    });
+    const journalMetadata = {
+      ...paymentRef ? { paymentRef } : {},
+      ...options?.metadata ?? {}
+    };
+    await this.createJournalEntry({
+      userId,
+      entryType: "credit",
+      amount,
+      balanceAfter: newTotal,
+      source: options?.source ?? "purchase",
+      referenceId: transaction.id ?? paymentRef ?? "unknown",
+      referenceType: options?.referenceType ?? "transaction",
+      description,
+      metadata: Object.keys(journalMetadata).length > 0 ? journalMetadata : void 0
     });
   }
   async deductCreditsAtomic(userId, amount) {
@@ -1396,9 +1412,88 @@ var CreditsService = class {
    * @param amount - Credits to add
    * @param description - Transaction description
    * @param paymentRef - Optional payment reference
+   * @param options - Optional journal source / reference type / extra metadata
+   *   for the credit journal entry (e.g. revenue-attribution fields).
    */
-  async addCredits(userId, amount, description, paymentRef) {
-    return this.repository.addCreditsAtomic(userId, amount, description, paymentRef);
+  async addCredits(userId, amount, description, paymentRef, options) {
+    return this.repository.addCreditsAtomic(userId, amount, description, paymentRef, options);
+  }
+  /**
+   * 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