@nehorai/credits 3.0.0 → 3.1.0

package/dist/{types-CY-oHIMA.d.ts → types-BL3YqxUD.d.ts}

@@ -369,6 +369,7 @@ interface CreditBalanceUpdate {
     balance?: number;
     bonusCredits?: number;
     reserved?: number;
+    /** Writes no journal line. To change a tier, use `updateUserTier`. */
     tier?: SubscriptionTier;
     monthlyLimit?: number;
     monthlyUsed?: number;
@@ -461,7 +462,9 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      */
     getUserCredits(userId: string): Promise<PortableUserCredits | null>;
     /**
-     * Initialize credits for a new user
+     * Initialize credits for a new user. Creating an account with a balance above 0
+     * writes its journal line (`signupGrantJournalInput`) in the same atomic step, and
+     * a call that finds the account writes nothing.
      * @param userId - User ID
      * @param tier - Initial subscription tier
      * @param initialBalance - Initial credit balance
@@ -469,13 +472,16 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      */
     initializeUserCredits(userId: string, tier: SubscriptionTier, initialBalance: number): Promise<PortableUserCredits>;
     /**
-     * Update user credits balance
+     * Patch fields of the account. This writes no journal line, whatever it changes.
+     * A tier change goes through `updateUserTier`, which journals a balance it moves.
      * @param userId - User ID
      * @param updates - Partial updates to apply
      */
     updateUserCredits(userId: string, updates: CreditBalanceUpdate): Promise<void>;
     /**
-     * Update user subscription tier
+     * Update user subscription tier. A write that moves the balance writes one journal
+     * line (`tierChangeJournalInput`) in the same atomic step, and one that does not
+     * writes none.
      * @param userId - User ID
      * @param input - Tier update data
      */

package/dist/{types-DOjguhEX.d.cts → types-YLAB8bFk.d.cts}

@@ -369,6 +369,7 @@ interface CreditBalanceUpdate {
     balance?: number;
     bonusCredits?: number;
     reserved?: number;
+    /** Writes no journal line. To change a tier, use `updateUserTier`. */
     tier?: SubscriptionTier;
     monthlyLimit?: number;
     monthlyUsed?: number;
@@ -461,7 +462,9 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      */
     getUserCredits(userId: string): Promise<PortableUserCredits | null>;
     /**
-     * Initialize credits for a new user
+     * Initialize credits for a new user. Creating an account with a balance above 0
+     * writes its journal line (`signupGrantJournalInput`) in the same atomic step, and
+     * a call that finds the account writes nothing.
      * @param userId - User ID
      * @param tier - Initial subscription tier
      * @param initialBalance - Initial credit balance
@@ -469,13 +472,16 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      */
     initializeUserCredits(userId: string, tier: SubscriptionTier, initialBalance: number): Promise<PortableUserCredits>;
     /**
-     * Update user credits balance
+     * Patch fields of the account. This writes no journal line, whatever it changes.
+     * A tier change goes through `updateUserTier`, which journals a balance it moves.
      * @param userId - User ID
      * @param updates - Partial updates to apply
      */
     updateUserCredits(userId: string, updates: CreditBalanceUpdate): Promise<void>;
     /**
-     * Update user subscription tier
+     * Update user subscription tier. A write that moves the balance writes one journal
+     * line (`tierChangeJournalInput`) in the same atomic step, and one that does not
+     * writes none.
      * @param userId - User ID
      * @param input - Tier update data
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nehorai/credits",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",