@nehorai/credits 2.1.0 → 2.2.0

package/dist/{types-BhCdep_t.d.ts → types-3c-IAwZI.d.ts}

@@ -1,4 +1,4 @@
-import { P as PortableTransaction, a as PortableReservation, R as ReservationStatus, C as CreditOperationType, b as CreditSource, J as JournalReferenceType, A as AIProviderType, S as SubscriptionTier, c as PortableUserCredits, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-Dzc443vy.js';
+import { P as PortableTransaction, a as PortableReservation, R as ReservationStatus, C as CreditOperationType, b as CreditSource, J as JournalReferenceType, A as AIProviderType, S as SubscriptionTier, c as PortableUserCredits, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-MaViK5tD.js';
 
 /**
  * Typed outcomes for the V2 reservation boundary.
@@ -375,9 +375,43 @@ interface TierUpdateInput {
     tier: SubscriptionTier;
     monthlyLimit: number;
     balance?: number;
+    /**
+     * Atomically lowers balance to at most this, only when the account's current tier is not free.
+     * Ignored for an account already free. Cannot be combined with `balance`.
+     * Like every balance reduction, it stops at the credits backing outstanding holds.
+     */
+    balanceCap?: number;
     monthlyUsed?: number;
     subscriptionExpiresAt?: Date | string | null;
 }
+/**
+ * Free-tier policy an application hands to a repository, for the decisions that
+ * have to be made inside the write, from the account's current state.
+ */
+interface CreditPolicyOptions {
+    /**
+     * Decides a due monthly reset, inside the reset transaction, from the account's current state.
+     * null: no reset and no write (wasReset false, monthlyResetAt unchanged).
+     * Takes precedence over getMonthlyLimit. monthlyLimit is written only when returned.
+     * A throw aborts the transaction.
+     *
+     * Must be synchronous and free of side effects: a contended transaction runs it again.
+     * The balance is validated, and floored at the credits backing outstanding holds.
+     */
+    resolveMonthlyReset?: (credits: {
+        tier: SubscriptionTier;
+        balance: number;
+    }) => {
+        balance: number;
+        monthlyLimit?: number;
+    } | null;
+    /**
+     * Balance cap and monthlyLimit on a subscription-expiry downgrade.
+     * Default: DEFAULT_FREE_CREDITS in the Firestore adapter, the default tier's
+     * configured limit in the in-memory adapter.
+     */
+    getDowngradeBalanceCap?: () => number;
+}
 /**
  * Optional journal customization for `addCreditsAtomic`.
  *
@@ -582,7 +616,8 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      * Uses optimistic locking to prevent race conditions
      *
      * @param userId - User ID
-     * @param tier - User's current subscription tier (for determining new balance)
+     * @param tier - The tier the caller last read. Not trusted: it may be stale by the
+     *   time the write runs, so implementations must use the tier stored on the account.
      * @param expectedResetAt - The expected monthlyResetAt value (for optimistic locking)
      * @returns Result indicating whether reset was performed and updated credits
      */
@@ -643,4 +678,4 @@ declare function supportsIdempotentCredit(repository: ICreditRepository): reposi
  */
 declare function toClientUserCredits(credits: PortableUserCredits): PortableUserCredits;
 
-export { type AddCreditsAtomicOptions as A, type CommitOutcome as C, type ExpireOutcome as E, type ICreditRepository as I, type JournalEntryQuery as J, type ReleaseOutcome as R, type TerminalReservationStatus as T, type UsageLogQuery as U, type AddCreditsOutcome as a, type AddCreditsV2Input as b, type CreateJournalEntryInput as c, type CreateReservationInput as d, type CreateTransactionInput as e, type CreateUsageLogInput as f, type CreditBalanceUpdate as g, type CreditRepositoryFactory as h, type ExpireReservationV2Options as i, type ICreditRepositoryCreditsV2 as j, type ICreditRepositoryV2 as k, type ReservationTransitionOptions as l, type ReserveCreditsV2Input as m, type ReserveOutcome as n, type TierUpdateInput as o, isCreditedOutcome as p, isReservedOutcome as q, isWinningOutcome as r, reservationJournalKey as s, supportsCreditsV2 as t, supportsIdempotentCredit as u, toClientUserCredits as v };
+export { type AddCreditsAtomicOptions as A, type CommitOutcome as C, type ExpireOutcome as E, type ICreditRepository as I, type JournalEntryQuery as J, type ReleaseOutcome as R, type TerminalReservationStatus as T, type UsageLogQuery as U, type AddCreditsOutcome as a, type AddCreditsV2Input as b, type CreateJournalEntryInput as c, type CreateReservationInput as d, type CreateTransactionInput as e, type CreateUsageLogInput as f, type CreditBalanceUpdate as g, type CreditPolicyOptions as h, type CreditRepositoryFactory as i, type ExpireReservationV2Options as j, type ICreditRepositoryCreditsV2 as k, type ICreditRepositoryV2 as l, type ReservationTransitionOptions as m, type ReserveCreditsV2Input as n, type ReserveOutcome as o, type TierUpdateInput as p, isCreditedOutcome as q, isReservedOutcome as r, isWinningOutcome as s, reservationJournalKey as t, supportsCreditsV2 as u, supportsIdempotentCredit as v, toClientUserCredits as w };

package/dist/{types-Dzc443vy.d.cts → types-MaViK5tD.d.cts}

@@ -93,6 +93,17 @@ interface PortableUserCredits {
     monthlyResetAt: string;
     /** Subscription expiry (null/undefined for free tier) - ISO 8601 or null */
     subscriptionExpiresAt?: string | null;
+    /**
+     * The part of `balance` a balance-lowering write kept only to back outstanding
+     * holds. A commit consumes it; a release or expiry removes it from `balance`.
+     * Absent means 0. See `planBalanceCap`.
+     */
+    expiredHoldBacking?: number;
+    /**
+     * Set when the account was created with a signup-grant claim: the amount
+     * granted, 0 when the claim was already taken. Absent on any other account.
+     */
+    signupGrant?: number;
     /** Creation timestamp - ISO 8601 */
     createdAt: string;
     /** Last update timestamp - ISO 8601 */
@@ -136,6 +147,13 @@ interface PortableReservation {
      * See `assertHoldPlaced` in `core/reservation-integrity.ts`.
      */
     holdPlacedAt?: string;
+    /**
+     * The part of this hold backed by credits that expired while it was open, and so
+     * leave the balance when it closes, however it closes. Absent means 0, as on every
+     * hold placed after the expiry. Open holds' shares sum to the account's
+     * `expiredHoldBacking`.
+     */
+    expiredBacking?: number;
 }
 /**
  * Result of a credit check operation

package/dist/{types-Dzc443vy.d.ts → types-MaViK5tD.d.ts}

@@ -93,6 +93,17 @@ interface PortableUserCredits {
     monthlyResetAt: string;
     /** Subscription expiry (null/undefined for free tier) - ISO 8601 or null */
     subscriptionExpiresAt?: string | null;
+    /**
+     * The part of `balance` a balance-lowering write kept only to back outstanding
+     * holds. A commit consumes it; a release or expiry removes it from `balance`.
+     * Absent means 0. See `planBalanceCap`.
+     */
+    expiredHoldBacking?: number;
+    /**
+     * Set when the account was created with a signup-grant claim: the amount
+     * granted, 0 when the claim was already taken. Absent on any other account.
+     */
+    signupGrant?: number;
     /** Creation timestamp - ISO 8601 */
     createdAt: string;
     /** Last update timestamp - ISO 8601 */
@@ -136,6 +147,13 @@ interface PortableReservation {
      * See `assertHoldPlaced` in `core/reservation-integrity.ts`.
      */
     holdPlacedAt?: string;
+    /**
+     * The part of this hold backed by credits that expired while it was open, and so
+     * leave the balance when it closes, however it closes. Absent means 0, as on every
+     * hold placed after the expiry. Open holds' shares sum to the account's
+     * `expiredHoldBacking`.
+     */
+    expiredBacking?: number;
 }
 /**
  * Result of a credit check operation

package/dist/{types-wtksMa4n.d.cts → types-XSjNXO5l.d.cts}

@@ -1,4 +1,4 @@
-import { P as PortableTransaction, a as PortableReservation, R as ReservationStatus, C as CreditOperationType, b as CreditSource, J as JournalReferenceType, A as AIProviderType, S as SubscriptionTier, c as PortableUserCredits, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-Dzc443vy.cjs';
+import { P as PortableTransaction, a as PortableReservation, R as ReservationStatus, C as CreditOperationType, b as CreditSource, J as JournalReferenceType, A as AIProviderType, S as SubscriptionTier, c as PortableUserCredits, d as PortableUsageLog, M as MonthlyResetResult, e as SubscriptionExpiryResult, f as PortableJournalEntry } from './types-MaViK5tD.cjs';
 
 /**
  * Typed outcomes for the V2 reservation boundary.
@@ -375,9 +375,43 @@ interface TierUpdateInput {
     tier: SubscriptionTier;
     monthlyLimit: number;
     balance?: number;
+    /**
+     * Atomically lowers balance to at most this, only when the account's current tier is not free.
+     * Ignored for an account already free. Cannot be combined with `balance`.
+     * Like every balance reduction, it stops at the credits backing outstanding holds.
+     */
+    balanceCap?: number;
     monthlyUsed?: number;
     subscriptionExpiresAt?: Date | string | null;
 }
+/**
+ * Free-tier policy an application hands to a repository, for the decisions that
+ * have to be made inside the write, from the account's current state.
+ */
+interface CreditPolicyOptions {
+    /**
+     * Decides a due monthly reset, inside the reset transaction, from the account's current state.
+     * null: no reset and no write (wasReset false, monthlyResetAt unchanged).
+     * Takes precedence over getMonthlyLimit. monthlyLimit is written only when returned.
+     * A throw aborts the transaction.
+     *
+     * Must be synchronous and free of side effects: a contended transaction runs it again.
+     * The balance is validated, and floored at the credits backing outstanding holds.
+     */
+    resolveMonthlyReset?: (credits: {
+        tier: SubscriptionTier;
+        balance: number;
+    }) => {
+        balance: number;
+        monthlyLimit?: number;
+    } | null;
+    /**
+     * Balance cap and monthlyLimit on a subscription-expiry downgrade.
+     * Default: DEFAULT_FREE_CREDITS in the Firestore adapter, the default tier's
+     * configured limit in the in-memory adapter.
+     */
+    getDowngradeBalanceCap?: () => number;
+}
 /**
  * Optional journal customization for `addCreditsAtomic`.
  *
@@ -582,7 +616,8 @@ interface ICreditRepository extends Partial<ICreditRepositoryV2>, Partial<ICredi
      * Uses optimistic locking to prevent race conditions
      *
      * @param userId - User ID
-     * @param tier - User's current subscription tier (for determining new balance)
+     * @param tier - The tier the caller last read. Not trusted: it may be stale by the
+     *   time the write runs, so implementations must use the tier stored on the account.
      * @param expectedResetAt - The expected monthlyResetAt value (for optimistic locking)
      * @returns Result indicating whether reset was performed and updated credits
      */
@@ -643,4 +678,4 @@ declare function supportsIdempotentCredit(repository: ICreditRepository): reposi
  */
 declare function toClientUserCredits(credits: PortableUserCredits): PortableUserCredits;
 
-export { type AddCreditsAtomicOptions as A, type CommitOutcome as C, type ExpireOutcome as E, type ICreditRepository as I, type JournalEntryQuery as J, type ReleaseOutcome as R, type TerminalReservationStatus as T, type UsageLogQuery as U, type AddCreditsOutcome as a, type AddCreditsV2Input as b, type CreateJournalEntryInput as c, type CreateReservationInput as d, type CreateTransactionInput as e, type CreateUsageLogInput as f, type CreditBalanceUpdate as g, type CreditRepositoryFactory as h, type ExpireReservationV2Options as i, type ICreditRepositoryCreditsV2 as j, type ICreditRepositoryV2 as k, type ReservationTransitionOptions as l, type ReserveCreditsV2Input as m, type ReserveOutcome as n, type TierUpdateInput as o, isCreditedOutcome as p, isReservedOutcome as q, isWinningOutcome as r, reservationJournalKey as s, supportsCreditsV2 as t, supportsIdempotentCredit as u, toClientUserCredits as v };
+export { type AddCreditsAtomicOptions as A, type CommitOutcome as C, type ExpireOutcome as E, type ICreditRepository as I, type JournalEntryQuery as J, type ReleaseOutcome as R, type TerminalReservationStatus as T, type UsageLogQuery as U, type AddCreditsOutcome as a, type AddCreditsV2Input as b, type CreateJournalEntryInput as c, type CreateReservationInput as d, type CreateTransactionInput as e, type CreateUsageLogInput as f, type CreditBalanceUpdate as g, type CreditPolicyOptions as h, type CreditRepositoryFactory as i, type ExpireReservationV2Options as j, type ICreditRepositoryCreditsV2 as k, type ICreditRepositoryV2 as l, type ReservationTransitionOptions as m, type ReserveCreditsV2Input as n, type ReserveOutcome as o, type TierUpdateInput as p, isCreditedOutcome as q, isReservedOutcome as r, isWinningOutcome as s, reservationJournalKey as t, supportsCreditsV2 as u, supportsIdempotentCredit as v, toClientUserCredits as w };

package/package.json

@@ -1,71 +1,70 @@
-{
-  "name": "@nehorai/credits",
-  "version": "2.1.0",
-  "type": "module",
-  "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.cjs"
-    },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "require": "./dist/core/index.cjs"
-    },
-    "./repository": {
-      "types": "./dist/repository/index.d.ts",
-      "import": "./dist/repository/index.js",
-      "require": "./dist/repository/index.cjs"
-    },
-    "./auth": {
-      "types": "./dist/auth/index.d.ts",
-      "import": "./dist/auth/index.js",
-      "require": "./dist/auth/index.cjs"
-    },
-    "./service": {
-      "types": "./dist/service/index.d.ts",
-      "import": "./dist/service/index.js",
-      "require": "./dist/service/index.cjs"
-    },
-    "./adapters": {
-      "types": "./dist/adapters/index.d.ts",
-      "import": "./dist/adapters/index.js",
-      "require": "./dist/adapters/index.cjs"
-    },
-    "./sdk": {
-      "types": "./dist/sdk/index.d.ts",
-      "import": "./dist/sdk/index.js",
-      "require": "./dist/sdk/index.cjs"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "license": "MIT",
-  "author": "Nehorai Hadad",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/NehoraiHadad/nehorai-plugins",
-    "directory": "packages/credits"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "pnpm build"
-  },
-  "dependencies": {
-    "zod": "^3.24.2"
-  },
-  "devDependencies": {
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5",
-    "@types/node": "^22.13.4"
-  }
-}
+{
+  "name": "@nehorai/credits",
+  "version": "2.2.0",
+  "type": "module",
+  "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.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
+    },
+    "./repository": {
+      "types": "./dist/repository/index.d.ts",
+      "import": "./dist/repository/index.js",
+      "require": "./dist/repository/index.cjs"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js",
+      "require": "./dist/auth/index.cjs"
+    },
+    "./service": {
+      "types": "./dist/service/index.d.ts",
+      "import": "./dist/service/index.js",
+      "require": "./dist/service/index.cjs"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js",
+      "require": "./dist/adapters/index.cjs"
+    },
+    "./sdk": {
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js",
+      "require": "./dist/sdk/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "author": "Nehorai Hadad",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NehoraiHadad/nehorai-plugins",
+    "directory": "packages/credits"
+  },
+  "dependencies": {
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "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"
+  }
+}