@nehorai/credits 1.6.0 → 2.0.0

package/dist/service/index.d.cts

@@ -1,5 +1,5 @@
-import { b as PortableUserCredits, g as CreditCheckResult, a as CreditOperationType, c as PortableReservation, d as PortableUsageLog, D as DeductCreditsResult, S as SubscriptionTier, j as UsageHistoryResponse, f as PortableJournalEntry } from '../types-CjLj3GW5.cjs';
-import { I as ICreditRepository, J as JournalEntryQuery } from '../types-CZNv1U3e.cjs';
+import { c as PortableUserCredits, g as CreditCheckResult, C as CreditOperationType, a as PortableReservation, d as PortableUsageLog, D as DeductCreditsResult, S as SubscriptionTier, j as UsageHistoryResponse, f as PortableJournalEntry } from '../types-DJ8yqaVr.cjs';
+import { I as ICreditRepository, n as ReserveOutcome, l as ReservationTransitionOptions, C as CommitOutcome, R as ReleaseOutcome, A as AddCreditsAtomicOptions, a as AddCreditsOutcome, J as JournalEntryQuery } from '../types-C8hZMe8a.cjs';
 
 /**
  * Notification callback type for low balance notifications
@@ -22,6 +22,20 @@ interface ReserveCreditsOptions {
      * legitimately in flight.
      */
     ttlMs?: number;
+    /**
+     * Caller-supplied idempotency key, unique per user.
+     *
+     * Retrying a reserve with the same key and the same amount/operation returns
+     * the original reservation instead of placing a second hold — the fix for a
+     * webhook or job runner delivering the same request twice. Reusing a key
+     * with a *different* amount or operation is a
+     * `CreditErrorCode.IDEMPOTENCY_CONFLICT`.
+     *
+     * Requires a repository implementing the V2 boundary (see
+     * `supportsCreditsV2`). A legacy adapter has no unique index to enforce the
+     * key, so it is ignored there rather than silently promised.
+     */
+    idempotencyKey?: string;
 }
 /**
  * Options for a one-shot atomic credit deduction via `deductCredits`.
@@ -103,16 +117,55 @@ declare class CreditsService {
      */
     reserveCredits(userId: string, amount: number, operationType: CreditOperationType, options?: ReserveCreditsOptions): Promise<PortableReservation>;
     /**
-     * Commit a reservation (phase 2 of two-phase commit - success)
-     * Deducts credits and marks reservation as committed
-     * Also triggers low balance notifications if balance drops below threshold
+     * Reserve credits and get the typed outcome instead of an exception.
+     *
+     * Prefer this over {@link reserveCredits} in async callers: it distinguishes
+     * a fresh hold from an idempotent replay, and reports insufficient funds as
+     * a value rather than as control flow.
+     */
+    reserveCreditsDetailed(userId: string, amount: number, operationType: CreditOperationType, options?: ReserveCreditsOptions): Promise<ReserveOutcome>;
+    /**
+     * Commit a reservation (phase 2 of two-phase commit - success).
+     *
+     * Idempotent: re-delivering a commit for an already-committed reservation is
+     * a no-op. Committing one that was released or expired throws, because the
+     * credits are no longer held and pretending otherwise would hide a real bug.
      */
-    commitCredits(userId: string, reservationId: string): Promise<void>;
+    commitCredits(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<void>;
     /**
-     * Release a reservation (phase 2 of two-phase commit - failure)
-     * Returns reserved credits and marks reservation as released
+     * Commit a reservation and get the typed outcome.
+     *
+     * Exactly one concurrent caller sees `committed`; that call moved the balance
+     * and wrote the single journal entry. On a V2 repository the journal is
+     * written inside the same transaction, so this method adds none of its own —
+     * the duplicate entry the previous implementation wrote is gone.
+     *
+     * The low-balance notification fires only for the winner, and only after the
+     * transaction has committed, so no callback runs inside a database
+     * transaction.
+     */
+    commitCreditsDetailed(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<CommitOutcome>;
+    /**
+     * Release a reservation (phase 2 of two-phase commit - failure).
+     *
+     * Throws `RESERVATION_NOT_FOUND` for an unknown reservation, matching the
+     * pre-V2 behaviour — a release naming a reservation that does not exist is a
+     * caller bug, and swallowing it hides the bug while the credits stay held.
+     *
+     * Releasing one that is already terminal — `released`, `expired`, or
+     * `committed` — is a no-op, which is the behaviour this method has always
+     * had. A release that loses a race to a concurrent commit is the common
+     * case in a retry-heavy caller, and callers written against the pre-V2
+     * contract handle it by not handling it.
+     *
+     * That does mean this method cannot tell you that the credits were spent
+     * rather than returned. Use {@link releaseCreditsDetailed}, which reports
+     * `already_terminal` with `terminalStatus: 'committed'`, when you need to
+     * branch on it.
      */
-    releaseCredits(userId: string, reservationId: string): Promise<void>;
+    releaseCredits(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<void>;
+    /** Release a reservation and get the typed outcome. */
+    releaseCreditsDetailed(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<ReleaseOutcome>;
     /**
      * Log usage for audit trail
      * @param log - Usage log data
@@ -124,8 +177,15 @@ declare class CreditsService {
      * @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).
+     * @returns Whether this delivery credited the account (`created`), repeated an
+     *   earlier one (`replayed`), or reused the reference for a different credit
+     *   event (`conflict`, which credited nothing). On a repository without
+     *   `addCreditsV2` the result is always `created` and carries no
+     *   deduplication guarantee — see {@link addCreditsThroughRepository}.
      */
-    addCredits(userId: string, amount: number, description: string, paymentRef?: string): Promise<void>;
+    addCredits(userId: string, amount: number, description: string, paymentRef?: string, options?: AddCreditsAtomicOptions): Promise<AddCreditsOutcome>;
     /**
      * One-shot atomic "deduct-if-sufficient" credit charge.
      *

package/dist/service/index.d.ts

@@ -1,5 +1,5 @@
-import { b as PortableUserCredits, g as CreditCheckResult, a as CreditOperationType, c as PortableReservation, d as PortableUsageLog, D as DeductCreditsResult, S as SubscriptionTier, j as UsageHistoryResponse, f as PortableJournalEntry } from '../types-CjLj3GW5.js';
-import { I as ICreditRepository, J as JournalEntryQuery } from '../types-G4WK0rM-.js';
+import { c as PortableUserCredits, g as CreditCheckResult, C as CreditOperationType, a as PortableReservation, d as PortableUsageLog, D as DeductCreditsResult, S as SubscriptionTier, j as UsageHistoryResponse, f as PortableJournalEntry } from '../types-DJ8yqaVr.js';
+import { I as ICreditRepository, n as ReserveOutcome, l as ReservationTransitionOptions, C as CommitOutcome, R as ReleaseOutcome, A as AddCreditsAtomicOptions, a as AddCreditsOutcome, J as JournalEntryQuery } from '../types-BmG5Omzj.js';
 
 /**
  * Notification callback type for low balance notifications
@@ -22,6 +22,20 @@ interface ReserveCreditsOptions {
      * legitimately in flight.
      */
     ttlMs?: number;
+    /**
+     * Caller-supplied idempotency key, unique per user.
+     *
+     * Retrying a reserve with the same key and the same amount/operation returns
+     * the original reservation instead of placing a second hold — the fix for a
+     * webhook or job runner delivering the same request twice. Reusing a key
+     * with a *different* amount or operation is a
+     * `CreditErrorCode.IDEMPOTENCY_CONFLICT`.
+     *
+     * Requires a repository implementing the V2 boundary (see
+     * `supportsCreditsV2`). A legacy adapter has no unique index to enforce the
+     * key, so it is ignored there rather than silently promised.
+     */
+    idempotencyKey?: string;
 }
 /**
  * Options for a one-shot atomic credit deduction via `deductCredits`.
@@ -103,16 +117,55 @@ declare class CreditsService {
      */
     reserveCredits(userId: string, amount: number, operationType: CreditOperationType, options?: ReserveCreditsOptions): Promise<PortableReservation>;
     /**
-     * Commit a reservation (phase 2 of two-phase commit - success)
-     * Deducts credits and marks reservation as committed
-     * Also triggers low balance notifications if balance drops below threshold
+     * Reserve credits and get the typed outcome instead of an exception.
+     *
+     * Prefer this over {@link reserveCredits} in async callers: it distinguishes
+     * a fresh hold from an idempotent replay, and reports insufficient funds as
+     * a value rather than as control flow.
+     */
+    reserveCreditsDetailed(userId: string, amount: number, operationType: CreditOperationType, options?: ReserveCreditsOptions): Promise<ReserveOutcome>;
+    /**
+     * Commit a reservation (phase 2 of two-phase commit - success).
+     *
+     * Idempotent: re-delivering a commit for an already-committed reservation is
+     * a no-op. Committing one that was released or expired throws, because the
+     * credits are no longer held and pretending otherwise would hide a real bug.
      */
-    commitCredits(userId: string, reservationId: string): Promise<void>;
+    commitCredits(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<void>;
     /**
-     * Release a reservation (phase 2 of two-phase commit - failure)
-     * Returns reserved credits and marks reservation as released
+     * Commit a reservation and get the typed outcome.
+     *
+     * Exactly one concurrent caller sees `committed`; that call moved the balance
+     * and wrote the single journal entry. On a V2 repository the journal is
+     * written inside the same transaction, so this method adds none of its own —
+     * the duplicate entry the previous implementation wrote is gone.
+     *
+     * The low-balance notification fires only for the winner, and only after the
+     * transaction has committed, so no callback runs inside a database
+     * transaction.
+     */
+    commitCreditsDetailed(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<CommitOutcome>;
+    /**
+     * Release a reservation (phase 2 of two-phase commit - failure).
+     *
+     * Throws `RESERVATION_NOT_FOUND` for an unknown reservation, matching the
+     * pre-V2 behaviour — a release naming a reservation that does not exist is a
+     * caller bug, and swallowing it hides the bug while the credits stay held.
+     *
+     * Releasing one that is already terminal — `released`, `expired`, or
+     * `committed` — is a no-op, which is the behaviour this method has always
+     * had. A release that loses a race to a concurrent commit is the common
+     * case in a retry-heavy caller, and callers written against the pre-V2
+     * contract handle it by not handling it.
+     *
+     * That does mean this method cannot tell you that the credits were spent
+     * rather than returned. Use {@link releaseCreditsDetailed}, which reports
+     * `already_terminal` with `terminalStatus: 'committed'`, when you need to
+     * branch on it.
      */
-    releaseCredits(userId: string, reservationId: string): Promise<void>;
+    releaseCredits(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<void>;
+    /** Release a reservation and get the typed outcome. */
+    releaseCreditsDetailed(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<ReleaseOutcome>;
     /**
      * Log usage for audit trail
      * @param log - Usage log data
@@ -124,8 +177,15 @@ declare class CreditsService {
      * @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).
+     * @returns Whether this delivery credited the account (`created`), repeated an
+     *   earlier one (`replayed`), or reused the reference for a different credit
+     *   event (`conflict`, which credited nothing). On a repository without
+     *   `addCreditsV2` the result is always `created` and carries no
+     *   deduplication guarantee — see {@link addCreditsThroughRepository}.
      */
-    addCredits(userId: string, amount: number, description: string, paymentRef?: string): Promise<void>;
+    addCredits(userId: string, amount: number, description: string, paymentRef?: string, options?: AddCreditsAtomicOptions): Promise<AddCreditsOutcome>;
     /**
      * One-shot atomic "deduct-if-sufficient" credit charge.
      *