@nehorai/credits 1.2.0 → 1.4.0

package/dist/types-D1vdeBcA.d.cts

@@ -0,0 +1,305 @@
+import { C as CreditSource, J as JournalReferenceType, a as CreditOperationType, P as PortableTransaction, A as AIProviderType, S as SubscriptionTier, b as PortableUserCredits, c as PortableReservation, R as ReservationStatus, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-BBxIWHK2.cjs';
+
+/**
+ * Input for creating a credit reservation
+ */
+interface CreateReservationInput {
+    userId: string;
+    amount: number;
+    operationType: CreditOperationType;
+    expiresAt: Date;
+}
+/**
+ * Input for creating a credit transaction
+ */
+interface CreateTransactionInput {
+    userId: string;
+    type: PortableTransaction["type"];
+    amount: number;
+    description: string;
+    paymentRef?: string;
+    previousBalance: number;
+    newBalance: number;
+}
+/**
+ * Input for logging usage
+ */
+interface CreateUsageLogInput {
+    userId: string;
+    operationType: CreditOperationType;
+    provider: AIProviderType;
+    creditsUsed: number;
+    success: boolean;
+    errorMessage?: string;
+    resourceId?: string;
+    resourceType?: string;
+    requestId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Query options for usage logs
+ */
+interface UsageLogQuery {
+    userId?: string;
+    operationType?: CreditOperationType;
+    success?: boolean;
+    limit?: number;
+    offset?: number;
+    startDate?: Date;
+    endDate?: Date;
+}
+/**
+ * Input for creating a journal entry
+ */
+interface CreateJournalEntryInput {
+    userId: string;
+    entryType: "debit" | "credit";
+    amount: number;
+    balanceAfter: number;
+    source: CreditSource;
+    referenceId: string;
+    referenceType: JournalReferenceType;
+    description: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Query options for journal entries
+ */
+interface JournalEntryQuery {
+    userId: string;
+    source?: CreditSource;
+    referenceType?: JournalReferenceType;
+    limit?: number;
+    offset?: number;
+    startDate?: Date;
+    endDate?: Date;
+}
+/**
+ * Partial update for user credits balance
+ */
+interface CreditBalanceUpdate {
+    balance?: number;
+    bonusCredits?: number;
+    reserved?: number;
+    tier?: SubscriptionTier;
+    monthlyLimit?: number;
+    monthlyUsed?: number;
+    monthlyResetAt?: Date | string;
+    subscriptionExpiresAt?: Date | string | null;
+    /** Increment balance by this amount (alternative to absolute value) */
+    balanceIncrement?: number;
+    /** Increment bonusCredits by this amount (alternative to absolute value) */
+    bonusCreditsIncrement?: number;
+    /** Increment reserved by this amount (alternative to absolute value) */
+    reservedIncrement?: number;
+    /** Increment monthlyUsed by this amount */
+    monthlyUsedIncrement?: number;
+}
+/**
+ * Input for tier update
+ */
+interface TierUpdateInput {
+    tier: SubscriptionTier;
+    monthlyLimit: number;
+    balance?: number;
+    monthlyUsed?: number;
+    subscriptionExpiresAt?: Date | string | null;
+}
+/**
+ * Repository interface for credits database operations
+ *
+ * Implementations can use any database (Firestore, PostgreSQL, etc.)
+ * All methods should handle their own error handling and transactions
+ */
+interface ICreditRepository {
+    /**
+     * Get user credits balance
+     * @param userId - User ID
+     * @returns User credits or null if not found
+     */
+    getUserCredits(userId: string): Promise<PortableUserCredits | null>;
+    /**
+     * Initialize credits for a new user
+     * @param userId - User ID
+     * @param tier - Initial subscription tier
+     * @param initialBalance - Initial credit balance
+     * @returns Initialized user credits
+     */
+    initializeUserCredits(userId: string, tier: SubscriptionTier, initialBalance: number): Promise<PortableUserCredits>;
+    /**
+     * Update user credits balance
+     * @param userId - User ID
+     * @param updates - Partial updates to apply
+     */
+    updateUserCredits(userId: string, updates: CreditBalanceUpdate): Promise<void>;
+    /**
+     * Update user subscription tier
+     * @param userId - User ID
+     * @param input - Tier update data
+     */
+    updateUserTier(userId: string, input: TierUpdateInput): Promise<void>;
+    /**
+     * Create a credit reservation (phase 1 of two-phase commit)
+     * @param input - Reservation data
+     * @returns Created reservation
+     */
+    createReservation(input: CreateReservationInput): Promise<PortableReservation>;
+    /**
+     * Get a reservation by ID
+     * @param userId - User ID
+     * @param reservationId - Reservation ID
+     * @returns Reservation or null
+     */
+    getReservation(userId: string, reservationId: string): Promise<PortableReservation | null>;
+    /**
+     * Update reservation status
+     * @param userId - User ID
+     * @param reservationId - Reservation ID
+     * @param status - New status
+     * @param completedAt - Completion timestamp
+     */
+    updateReservationStatus(userId: string, reservationId: string, status: ReservationStatus, completedAt?: Date): Promise<void>;
+    /**
+     * Reserve credits atomically (creates reservation + updates balance in transaction)
+     * @param userId - User ID
+     * @param amount - Credits to reserve
+     * @param operationType - Operation type for tracking
+     * @param expiresAt - Reservation expiry time
+     * @returns Created reservation
+     * @throws Error if insufficient credits
+     */
+    reserveCreditsAtomic(userId: string, amount: number, operationType: CreditOperationType, expiresAt: Date): Promise<PortableReservation>;
+    /**
+     * Commit a reservation atomically (deducts credits + marks reservation committed)
+     * @param userId - User ID
+     * @param reservationId - Reservation ID
+     * @throws Error if reservation not found or not in reserved state
+     */
+    commitReservationAtomic(userId: string, reservationId: string): Promise<void>;
+    /**
+     * Release a reservation atomically (releases reserved credits + marks reservation released)
+     * @param userId - User ID
+     * @param reservationId - Reservation ID
+     */
+    releaseReservationAtomic(userId: string, reservationId: string): Promise<void>;
+    /**
+     * Add credits atomically (creates transaction + updates balance)
+     * @param userId - User ID
+     * @param amount - Credits to add
+     * @param description - Transaction description
+     * @param paymentRef - Optional payment reference
+     */
+    addCreditsAtomic(userId: string, amount: number, description: string, paymentRef?: string): Promise<void>;
+    /**
+     * Deduct credits from a user's balance atomically.
+     *
+     * Splits the deduction across `balance` and `bonusCredits`, draining
+     * `balance` (monthly, resets each cycle) first so persistent bonus
+     * credits survive longer. Runs in a single atomic transaction so
+     * concurrent deducts cannot drive either field negative.
+     *
+     * Callers are responsible for writing any audit record (journal /
+     * transaction) — this method only moves credits.
+     *
+     * @param userId - User ID
+     * @param amount - Credits to deduct (positive)
+     * @returns Combined totals (balance + bonusCredits) before and after.
+     * @throws If user has no credits doc or insufficient credits
+     */
+    deductCreditsAtomic(userId: string, amount: number): Promise<{
+        previousBalance: number;
+        newBalance: number;
+    }>;
+    /**
+     * Create a credit transaction record
+     * @param input - Transaction data
+     * @returns Created transaction
+     */
+    createTransaction(input: CreateTransactionInput): Promise<PortableTransaction>;
+    /**
+     * Get user's transaction history
+     * @param userId - User ID
+     * @param limit - Max results
+     * @param offset - Skip results
+     * @returns List of transactions
+     */
+    getTransactions(userId: string, limit?: number, offset?: number): Promise<PortableTransaction[]>;
+    /**
+     * Log a usage event
+     * @param input - Usage log data
+     * @returns Created usage log
+     */
+    logUsage(input: CreateUsageLogInput): Promise<PortableUsageLog>;
+    /**
+     * Query usage logs
+     * @param query - Query parameters
+     * @returns List of usage logs
+     */
+    getUsageLogs(query: UsageLogQuery): Promise<PortableUsageLog[]>;
+    /**
+     * Get usage log count (for pagination)
+     * @param query - Query parameters (without limit/offset)
+     * @returns Count of matching logs
+     */
+    getUsageLogsCount(query: Omit<UsageLogQuery, "limit" | "offset">): Promise<number>;
+    /**
+     * Find and expire reservations past their expiration time
+     * Used by cron job to clean up stale reservations
+     * @param batchSize - Maximum number of reservations to process per batch (default: 100)
+     * @param maxIterations - Maximum number of pagination iterations to prevent infinite loops (default: 100)
+     * @returns Cleanup results with counts and errors
+     */
+    findAndExpireReservations(batchSize?: number, maxIterations?: number): Promise<{
+        expiredCount: number;
+        creditsReleased: number;
+        errors: string[];
+    }>;
+    /**
+     * Atomically perform monthly reset if needed
+     * Uses optimistic locking to prevent race conditions
+     *
+     * @param userId - User ID
+     * @param tier - User's current subscription tier (for determining new balance)
+     * @param expectedResetAt - The expected monthlyResetAt value (for optimistic locking)
+     * @returns Result indicating whether reset was performed and updated credits
+     */
+    atomicMonthlyReset(userId: string, tier: SubscriptionTier, expectedResetAt: Date | string): Promise<MonthlyResetResult>;
+    /**
+     * Check and handle subscription expiry with grace period
+     * Auto-downgrades expired subscriptions after grace period
+     *
+     * @param userId - User ID
+     * @param gracePeriodDays - Days to allow after expiry before downgrade (default: 3)
+     * @returns Result indicating whether downgrade occurred
+     */
+    checkAndHandleSubscriptionExpiry(userId: string, gracePeriodDays?: number): Promise<SubscriptionExpiryResult>;
+    /**
+     * Create a journal entry for audit trail
+     * @param input - Journal entry data
+     * @returns Created journal entry
+     */
+    createJournalEntry(input: CreateJournalEntryInput): Promise<PortableJournalEntry>;
+    /**
+     * Get journal entries for a user
+     * @param query - Query parameters
+     * @returns List of journal entries
+     */
+    getJournalEntries(query: JournalEntryQuery): Promise<PortableJournalEntry[]>;
+    /**
+     * Get journal entry count for pagination
+     * @param query - Query parameters (without limit/offset)
+     * @returns Count of matching entries
+     */
+    getJournalEntriesCount(query: Omit<JournalEntryQuery, "limit" | "offset">): Promise<number>;
+}
+/**
+ * Factory type for creating repository instances
+ */
+type CreditRepositoryFactory = () => ICreditRepository;
+/**
+ * Convert PortableUserCredits to client-safe format
+ * Utility function that implementations can use
+ */
+declare function toClientUserCredits(credits: PortableUserCredits): PortableUserCredits;
+
+export { type CreateJournalEntryInput as C, type ICreditRepository as I, type JournalEntryQuery as J, type TierUpdateInput as T, type UsageLogQuery as U, type CreateReservationInput as a, type CreateTransactionInput as b, type CreateUsageLogInput as c, type CreditBalanceUpdate as d, type CreditRepositoryFactory as e, toClientUserCredits as t };

package/dist/{auth/types.d.ts → types-OZU3I5OM.d.cts}

@@ -1,7 +1,7 @@
 /**
  * Authenticated user information for credits operations
  */
-export interface CreditsUser {
+interface CreditsUser {
     id: string;
     email?: string | null;
     name?: string | null;
@@ -11,7 +11,7 @@ export interface CreditsUser {
  *
  * Implementations can use any auth system (NextAuth, JWT, API keys, etc.)
  */
-export interface ICreditsAuthProvider {
+interface ICreditsAuthProvider {
     /**
      * Get the currently authenticated user
      * @returns User information or null if not authenticated
@@ -27,5 +27,6 @@ export interface ICreditsAuthProvider {
 /**
  * Factory type for creating auth provider instances
  */
-export type CreditsAuthProviderFactory = () => ICreditsAuthProvider;
-//# sourceMappingURL=types.d.ts.map
+type CreditsAuthProviderFactory = () => ICreditsAuthProvider;
+
+export type { CreditsAuthProviderFactory as C, ICreditsAuthProvider as I, CreditsUser as a };

package/dist/types-OZU3I5OM.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Authenticated user information for credits operations
+ */
+interface CreditsUser {
+    id: string;
+    email?: string | null;
+    name?: string | null;
+}
+/**
+ * Auth provider interface for credits system
+ *
+ * Implementations can use any auth system (NextAuth, JWT, API keys, etc.)
+ */
+interface ICreditsAuthProvider {
+    /**
+     * Get the currently authenticated user
+     * @returns User information or null if not authenticated
+     */
+    getCurrentUser(): Promise<CreditsUser | null>;
+    /**
+     * Verify if a user has admin access for credits management
+     * @param userId - User ID to check
+     * @returns True if user has admin access
+     */
+    verifyAdminAccess(userId: string): Promise<boolean>;
+}
+/**
+ * Factory type for creating auth provider instances
+ */
+type CreditsAuthProviderFactory = () => ICreditsAuthProvider;
+
+export type { CreditsAuthProviderFactory as C, ICreditsAuthProvider as I, CreditsUser as a };

package/dist/{repository/types.d.ts → types-aJsyv8df.d.ts}

@@ -1,8 +1,9 @@
-import type { PortableUserCredits, PortableReservation, PortableTransaction, PortableUsageLog, PortableJournalEntry, CreditOperationType, SubscriptionTier, ReservationStatus, AIProviderType, MonthlyResetResult, SubscriptionExpiryResult, CreditSource, JournalReferenceType } from "../core/types.js";
+import { C as CreditSource, J as JournalReferenceType, a as CreditOperationType, P as PortableTransaction, A as AIProviderType, S as SubscriptionTier, b as PortableUserCredits, c as PortableReservation, R as ReservationStatus, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-BBxIWHK2.js';
+
 /**
  * Input for creating a credit reservation
  */
-export interface CreateReservationInput {
+interface CreateReservationInput {
     userId: string;
     amount: number;
     operationType: CreditOperationType;
@@ -11,7 +12,7 @@ export interface CreateReservationInput {
 /**
  * Input for creating a credit transaction
  */
-export interface CreateTransactionInput {
+interface CreateTransactionInput {
     userId: string;
     type: PortableTransaction["type"];
     amount: number;
@@ -23,7 +24,7 @@ export interface CreateTransactionInput {
 /**
  * Input for logging usage
  */
-export interface CreateUsageLogInput {
+interface CreateUsageLogInput {
     userId: string;
     operationType: CreditOperationType;
     provider: AIProviderType;
@@ -38,7 +39,7 @@ export interface CreateUsageLogInput {
 /**
  * Query options for usage logs
  */
-export interface UsageLogQuery {
+interface UsageLogQuery {
     userId?: string;
     operationType?: CreditOperationType;
     success?: boolean;
@@ -50,7 +51,7 @@ export interface UsageLogQuery {
 /**
  * Input for creating a journal entry
  */
-export interface CreateJournalEntryInput {
+interface CreateJournalEntryInput {
     userId: string;
     entryType: "debit" | "credit";
     amount: number;
@@ -64,7 +65,7 @@ export interface CreateJournalEntryInput {
 /**
  * Query options for journal entries
  */
-export interface JournalEntryQuery {
+interface JournalEntryQuery {
     userId: string;
     source?: CreditSource;
     referenceType?: JournalReferenceType;
@@ -76,7 +77,7 @@ export interface JournalEntryQuery {
 /**
  * Partial update for user credits balance
  */
-export interface CreditBalanceUpdate {
+interface CreditBalanceUpdate {
     balance?: number;
     bonusCredits?: number;
     reserved?: number;
@@ -97,7 +98,7 @@ export interface CreditBalanceUpdate {
 /**
  * Input for tier update
  */
-export interface TierUpdateInput {
+interface TierUpdateInput {
     tier: SubscriptionTier;
     monthlyLimit: number;
     balance?: number;
@@ -110,7 +111,7 @@ export interface TierUpdateInput {
  * Implementations can use any database (Firestore, PostgreSQL, etc.)
  * All methods should handle their own error handling and transactions
  */
-export interface ICreditRepository {
+interface ICreditRepository {
     /**
      * Get user credits balance
      * @param userId - User ID
@@ -189,6 +190,26 @@ export interface ICreditRepository {
      * @param paymentRef - Optional payment reference
      */
     addCreditsAtomic(userId: string, amount: number, description: string, paymentRef?: string): Promise<void>;
+    /**
+     * Deduct credits from a user's balance atomically.
+     *
+     * Splits the deduction across `balance` and `bonusCredits`, draining
+     * `balance` (monthly, resets each cycle) first so persistent bonus
+     * credits survive longer. Runs in a single atomic transaction so
+     * concurrent deducts cannot drive either field negative.
+     *
+     * Callers are responsible for writing any audit record (journal /
+     * transaction) — this method only moves credits.
+     *
+     * @param userId - User ID
+     * @param amount - Credits to deduct (positive)
+     * @returns Combined totals (balance + bonusCredits) before and after.
+     * @throws If user has no credits doc or insufficient credits
+     */
+    deductCreditsAtomic(userId: string, amount: number): Promise<{
+        previousBalance: number;
+        newBalance: number;
+    }>;
     /**
      * Create a credit transaction record
      * @param input - Transaction data
@@ -274,10 +295,11 @@ export interface ICreditRepository {
 /**
  * Factory type for creating repository instances
  */
-export type CreditRepositoryFactory = () => ICreditRepository;
+type CreditRepositoryFactory = () => ICreditRepository;
 /**
  * Convert PortableUserCredits to client-safe format
  * Utility function that implementations can use
  */
-export declare function toClientUserCredits(credits: PortableUserCredits): PortableUserCredits;
-//# sourceMappingURL=types.d.ts.map
+declare function toClientUserCredits(credits: PortableUserCredits): PortableUserCredits;
+
+export { type CreateJournalEntryInput as C, type ICreditRepository as I, type JournalEntryQuery as J, type TierUpdateInput as T, type UsageLogQuery as U, type CreateReservationInput as a, type CreateTransactionInput as b, type CreateUsageLogInput as c, type CreditBalanceUpdate as d, type CreditRepositoryFactory as e, toClientUserCredits as t };

package/package.json

@@ -1,48 +1,50 @@
 {
   "name": "@nehorai/credits",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
+      "require": "./dist/index.cjs"
     },
     "./core": {
       "types": "./dist/core/index.d.ts",
       "import": "./dist/core/index.js",
-      "default": "./dist/core/index.js"
+      "require": "./dist/core/index.cjs"
     },
     "./repository": {
       "types": "./dist/repository/index.d.ts",
       "import": "./dist/repository/index.js",
-      "default": "./dist/repository/index.js"
+      "require": "./dist/repository/index.cjs"
     },
     "./auth": {
       "types": "./dist/auth/index.d.ts",
       "import": "./dist/auth/index.js",
-      "default": "./dist/auth/index.js"
+      "require": "./dist/auth/index.cjs"
     },
     "./service": {
       "types": "./dist/service/index.d.ts",
       "import": "./dist/service/index.js",
-      "default": "./dist/service/index.js"
+      "require": "./dist/service/index.cjs"
     },
     "./adapters": {
       "types": "./dist/adapters/index.d.ts",
       "import": "./dist/adapters/index.js",
-      "default": "./dist/adapters/index.js"
+      "require": "./dist/adapters/index.cjs"
     },
     "./sdk": {
       "types": "./dist/sdk/index.d.ts",
       "import": "./dist/sdk/index.js",
-      "default": "./dist/sdk/index.js"
+      "require": "./dist/sdk/index.cjs"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "license": "MIT",
   "author": "Nehorai Hadad",
   "repository": {
@@ -50,13 +52,6 @@
     "url": "https://github.com/NehoraiHadad/nehorai-plugins",
     "directory": "packages/credits"
   },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "zod": "^3.24.2"
   },
@@ -64,5 +59,12 @@
     "typescript": "^5.7.3",
     "vitest": "^3.0.5",
     "@types/node": "^22.13.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}

package/dist/adapters/generic.d.ts

@@ -1,18 +0,0 @@
-/**
- * Generic credits adapter - framework agnostic
- *
- * This adapter uses standard JavaScript APIs and works in any
- * JavaScript environment (Node.js, browser, etc.).
- */
-import type { CreditsAdapter, CreditsAdapterConfig } from "./types.js";
-/**
- * Create a generic credits adapter
- *
- * This adapter:
- * - Authenticates users via the provided auth provider
- * - Reserves credits before action execution
- * - Commits credits on success, releases on failure
- * - Logs usage asynchronously via the deferred executor
- */
-export declare function createGenericAdapter(config: CreditsAdapterConfig): CreditsAdapter;
-//# sourceMappingURL=generic.d.ts.map

package/dist/adapters/generic.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generic.d.ts","sourceRoot":"","sources":["../../src/adapters/generic.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAgB,cAAc,EAAE,oBAAoB,EAAuB,MAAM,YAAY,CAAC;AAgB1G;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAqIjF"}