@nehorai/credits 3.0.0 → 3.1.0

package/dist/index-BrogG0Gc.d.cts

@@ -0,0 +1,277 @@
+import { I as ICreditRepository, b as AddCreditsV2Input, a as AddCreditsOutcome, m as ReservationTransitionOptions, C as CommitOutcome, R as ReleaseOutcome, n as ReserveCreditsV2Input, o as ReserveOutcome, g as CreditBalanceUpdate, c as CreateJournalEntryInput, h as CreditPolicyOptions, p as TierUpdateInput, d as CreateReservationInput, j as ExpireReservationV2Options, E as ExpireOutcome, A as AddCreditsAtomicOptions, D as DeductJournalInput, e as CreateTransactionInput, f as CreateUsageLogInput, U as UsageLogQuery, J as JournalEntryQuery } from './types-YLAB8bFk.cjs';
+import { c as PortableUserCredits, S as SubscriptionTier, a as PortableReservation, R as ReservationStatus, P as PortableTransaction, d as PortableUsageLog, f as PortableJournalEntry, M as MonthlyResetResult, e as SubscriptionExpiryResult } from './types-C3sxDvNb.cjs';
+
+/**
+ * One reservation flow for both repository generations.
+ *
+ * Adapters that implement the V2 boundary get the idempotent, race-safe path
+ * and own their journal entry. Adapters that do not (Firestore, custom
+ * implementations) keep the legacy read-then-write path, with the service
+ * writing the journal exactly as it always did — so upgrading this package
+ * does not change their behaviour, and does not double-write anyone's ledger.
+ */
+
+/**
+ * Reserve credits through V2 when available.
+ *
+ * A legacy adapter cannot honour an idempotency key — it has no unique index
+ * to enforce it — so asking for one there is a caller error rather than a
+ * silently ignored option.
+ */
+declare function reserveThroughRepository(repository: ICreditRepository, input: ReserveCreditsV2Input): Promise<ReserveOutcome>;
+/**
+ * Commit through V2 when available, else the legacy read-then-write path.
+ *
+ * **The legacy path cannot promise a single winner.** It reads the status and
+ * then writes, with no lock and no compare-and-set between the two, so two
+ * concurrent commits of the same reservation can both observe `reserved` and
+ * both proceed. The typed outcome still describes what *this* call saw, but on
+ * a legacy adapter `committed` means "this call did the work", not "this call
+ * was the only one that did". Callers needing exactly-once must use a
+ * repository for which `supportsCreditsV2` returns `true`.
+ */
+declare function commitThroughRepository(repository: ICreditRepository, userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<CommitOutcome>;
+/**
+ * Release through V2 when available, else the legacy read-then-write path.
+ *
+ * Same caveat as {@link commitThroughRepository}: on a legacy adapter the
+ * read-then-write sequence is unguarded, so `released` does not exclude a
+ * concurrent commit having also run. Only V2 repositories serialise the two.
+ */
+declare function releaseThroughRepository(repository: ICreditRepository, userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<ReleaseOutcome>;
+/**
+ * Credit an account through the idempotent path when the adapter has one.
+ *
+ * A legacy adapter cannot resolve `created` / `replayed` / `conflict`: it has
+ * no global unique index over `payment_ref`, so it cannot tell a re-delivered
+ * webhook from a second, genuinely different payment that reuses a reference.
+ * Rather than invent an outcome, this reports `created` — which is what the
+ * legacy method actually did — and the ambiguity is documented on the return
+ * type instead of hidden inside it.
+ *
+ * The reference is normalised here as well as in the adapters, so a legacy
+ * adapter that stores the raw string does not persist a whitespace-only
+ * reference that would then deduplicate nothing.
+ */
+declare function addCreditsThroughRepository(repository: ICreditRepository, input: AddCreditsV2Input): Promise<AddCreditsOutcome>;
+
+/**
+ * Shared utilities for credit repository implementations
+ *
+ * These are pure functions with no server-only dependencies,
+ * making them safe to use in any repository implementation.
+ */
+
+/**
+ * Generate a unique ID
+ * Uses timestamp + random string for uniqueness
+ */
+declare function generateId(): string;
+/**
+ * Convert date-like value to Date object
+ * Handles: Date, string, Firestore Timestamp
+ */
+declare function toDate(value: Date | string | unknown): Date;
+/**
+ * Get the first day of next month
+ * Used for calculating monthly reset dates
+ */
+declare function getNextMonthlyReset(from?: Date): Date;
+/** Result of validating a balance update. */
+interface BalanceValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Whether an update leaves a valid account: no negative field, and `reserved` covered
+ * by `balance + bonusCredits`, which is the floor outstanding holds put under the
+ * balance. An increment is applied on top of the absolute value when a call names both.
+ *
+ * An update is a delta the caller asked for, so one that cannot be honoured is refused,
+ * as a deduct is. Only tier writes and resets stop at the floor: they state a target.
+ *
+ * A negative balance increment is a charge, so it draws only on the balance above
+ * `expiredHoldBacking`: those credits are expired and leave when their hold closes, so
+ * charging them would hand the charge back. An absolute balance replaces the field and
+ * the marks with it, so only an increment on the stored balance meets this limit.
+ */
+declare function validateBalanceUpdate(current: Pick<PortableUserCredits, "balance" | "bonusCredits" | "reserved" | "expiredHoldBacking">, updates: CreditBalanceUpdate): BalanceValidationResult;
+/** Refuse an update {@link validateBalanceUpdate} finds invalid. */
+declare function assertValidBalanceUpdate(current: Pick<PortableUserCredits, "balance" | "bonusCredits" | "reserved" | "expiredHoldBacking">, updates: CreditBalanceUpdate): void;
+/**
+ * The journal line of a new account's starting balance, or null when it starts at 0.
+ * Write it in the step that creates the account: that step creates it once, so the
+ * line needs no guard of its own.
+ */
+declare function signupGrantJournalInput(userId: string, tier: SubscriptionTier, grant: number): CreateJournalEntryInput | null;
+/**
+ * The journal line of a tier write that moved the balance, or null when it did not.
+ * Call it before writing anything: it refuses a total the ledger cannot record.
+ *
+ * `amount` follows the lines this one sits beside, not the difference between the
+ * totals: a raise records the balance it set, like `subscription_grant`, and a cut
+ * records 0, like the expiry `subscription_downgrade`. `balanceBefore` and
+ * `balanceAfter` say how far the balance moved.
+ */
+declare function tierChangeJournalInput(input: {
+    userId: string;
+    previousTier: SubscriptionTier;
+    newTier: SubscriptionTier;
+    previousBalance: number;
+    newBalance: number;
+    bonusCredits: number;
+}): CreateJournalEntryInput | null;
+
+/**
+ * In-Memory Credit Repository Implementation
+ *
+ * A database-agnostic implementation of ICreditRepository for testing and prototyping.
+ * All data is stored in memory and lost when the process restarts.
+ *
+ * Usage:
+ * - Unit tests without database dependency
+ * - Local development and prototyping
+ * - Reference implementation for custom repositories
+ */
+
+declare class InMemoryCreditRepository implements ICreditRepository {
+    private readonly store;
+    private readonly options;
+    constructor(options?: CreditPolicyOptions);
+    /**
+     * A copy, never the live record.
+     *
+     * Handing out the stored object made this adapter behave unlike any real
+     * one: a caller holding a "before" snapshot saw it mutate under them. The
+     * service's monthly reset compared `resetResult.credits.balance` against the
+     * balance it had read moments earlier, got zero because both were the same
+     * object, and silently skipped the reset's journal entry — while the SQL
+     * adapter, which maps each row into a fresh object, wrote it.
+     */
+    getUserCredits(userId: string): Promise<PortableUserCredits | null>;
+    initializeUserCredits(userId: string, tier: SubscriptionTier, initialBalance: number): Promise<PortableUserCredits>;
+    /**
+     * The synchronous body of `initializeUserCredits`.
+     *
+     * Kept `await`-free on purpose: `addCreditsV2` seeds a missing user *inside*
+     * its critical section, and an `await` between the payment-reference check
+     * and the transaction write opens a gap another caller can run through — two
+     * simultaneous first deliveries of the same reference would then both credit.
+     */
+    private seedUser;
+    updateUserCredits(userId: string, updates: CreditBalanceUpdate): Promise<void>;
+    updateUserTier(userId: string, input: TierUpdateInput): Promise<void>;
+    createReservation(input: CreateReservationInput): Promise<PortableReservation>;
+    getReservation(userId: string, reservationId: string): Promise<PortableReservation | null>;
+    updateReservationStatus(userId: string, reservationId: string, status: ReservationStatus, completedAt?: Date): Promise<void>;
+    reserveCreditsV2(input: ReserveCreditsV2Input): Promise<ReserveOutcome>;
+    commitReservationV2(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<CommitOutcome>;
+    releaseReservationV2(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<ReleaseOutcome>;
+    expireReservationV2(userId: string, reservationId: string, options?: ExpireReservationV2Options): Promise<ExpireOutcome>;
+    reserveCreditsAtomic(userId: string, amount: number, operationType: string, expiresAt: Date): Promise<PortableReservation>;
+    commitReservationAtomic(userId: string, reservationId: string): Promise<void>;
+    releaseReservationAtomic(userId: string, reservationId: string): Promise<void>;
+    /**
+     * The stored transaction carrying this reference, in *any* user's ledger.
+     *
+     * Deliberately not scoped to one user. The SQL adapter's unique index covers
+     * `payment_ref` alone, so searching only the crediting user's own history made
+     * the same reference credit two different accounts here while the SQL adapter
+     * treated the second delivery as a duplicate. See `core/payment-ref.ts`.
+     */
+    private findByPaymentRef;
+    /** The journal entry written alongside a stored purchase, if there is one. */
+    private journalForTransaction;
+    /**
+     * Credit an account, resolving `paymentRef` to created / replayed / conflict.
+     *
+     * The reference is checked and the transaction is recorded with no `await`
+     * between them. `createTransaction` is `async` but its body is synchronous, so
+     * under JavaScript's run-to-completion semantics no other caller can observe
+     * the gap — which is what stands in for the SQL adapter's unique index.
+     *
+     * A `replayed` or `conflict` outcome writes nothing at all: the check runs
+     * before the balance moves, not after.
+     */
+    addCreditsV2(input: AddCreditsV2Input): Promise<AddCreditsOutcome>;
+    /**
+     * The legacy signature, on top of {@link addCreditsV2}.
+     *
+     * `Promise<void>` has nowhere to report a conflict, and silently returning is
+     * indistinguishable from "credited" — the exact failure this round is closing
+     * — so a conflict throws. A genuine replay still returns quietly, because
+     * that *is* the idempotent no-op the caller asked for.
+     */
+    addCreditsAtomic(userId: string, amount: number, description: string, paymentRef?: string, options?: AddCreditsAtomicOptions): Promise<void>;
+    deductCreditsAtomic(userId: string, amount: number, journal?: DeductJournalInput): Promise<{
+        previousBalance: number;
+        newBalance: number;
+        journalEntryId?: string;
+    }>;
+    createTransaction(input: CreateTransactionInput): Promise<PortableTransaction>;
+    /** The unguarded writer, for `addCreditsV2` — which has moved the balance. */
+    private recordTransaction;
+    getTransactions(userId: string, limit?: number, offset?: number): Promise<PortableTransaction[]>;
+    logUsage(input: CreateUsageLogInput): Promise<PortableUsageLog>;
+    getUsageLogs(query: UsageLogQuery): Promise<PortableUsageLog[]>;
+    getUsageLogsCount(query: Omit<UsageLogQuery, "limit" | "offset">): Promise<number>;
+    createJournalEntry(input: CreateJournalEntryInput): Promise<PortableJournalEntry>;
+    /**
+     * The synchronous body of `createJournalEntry`, so `atomicMonthlyReset` can
+     * write its journal line inside the same run-to-completion step as the
+     * balance write — an `await` between the two is exactly the gap that loses
+     * the line when the second half fails.
+     */
+    private recordJournalEntry;
+    getJournalEntries(query: JournalEntryQuery): Promise<PortableJournalEntry[]>;
+    getJournalEntriesCount(query: Omit<JournalEntryQuery, "limit" | "offset">): Promise<number>;
+    /**
+     * Expire every hold whose deadline has passed.
+     *
+     * Each candidate goes through the guarded {@link expireReservationV2}, which
+     * re-checks the status and the deadline under the user's lock. The previous
+     * implementation released the hold and then overwrote the status to
+     * `expired`, so a commit landing in between got its credits handed back and
+     * was then relabelled.
+     */
+    findAndExpireReservations(_batchSize?: number, _maxIterations?: number): Promise<{
+        expiredCount: number;
+        creditsReleased: number;
+        errors: string[];
+    }>;
+    /**
+     * @param _tier - Not trusted. The caller read it earlier and the account may
+     *   have changed tier since, so the reset uses the tier stored on the account.
+     */
+    atomicMonthlyReset(userId: string, _tier: SubscriptionTier, expectedResetAt: Date | string): Promise<MonthlyResetResult>;
+    checkAndHandleSubscriptionExpiry(userId: string, gracePeriodDays?: number): Promise<SubscriptionExpiryResult>;
+    /**
+     * Clear all data (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Install a yield point inside every V2 critical section (testing only).
+     *
+     * Unset, the critical sections run start-to-finish synchronously, so
+     * concurrent callers never interleave and a concurrency test would pass even
+     * with the locking removed. Setting this to a real yield (a macrotask or a
+     * barrier) makes callers genuinely overlap, so the tests exercise the lock
+     * instead of the event loop. Never call this in production code.
+     */
+    setSchedulingHook(hook: (() => Promise<void>) | undefined): void;
+    /**
+     * Get all users (useful for testing/debugging)
+     */
+    getAllUsers(): PortableUserCredits[];
+    /**
+     * Get all reservations for a user (useful for testing)
+     */
+    getAllReservations(userId: string): PortableReservation[];
+}
+/**
+ * Create a new in-memory repository instance
+ * Each call creates a fresh, isolated instance
+ */
+declare function createInMemoryCreditRepository(options?: CreditPolicyOptions): InMemoryCreditRepository;
+
+export { type BalanceValidationResult as B, InMemoryCreditRepository as I, addCreditsThroughRepository as a, assertValidBalanceUpdate as b, commitThroughRepository as c, createInMemoryCreditRepository as d, getNextMonthlyReset as e, reserveThroughRepository as f, generateId as g, toDate as h, releaseThroughRepository as r, signupGrantJournalInput as s, tierChangeJournalInput as t, validateBalanceUpdate as v };

package/dist/index-DOvJES2m.d.ts

@@ -0,0 +1,277 @@
+import { I as ICreditRepository, b as AddCreditsV2Input, a as AddCreditsOutcome, m as ReservationTransitionOptions, C as CommitOutcome, R as ReleaseOutcome, n as ReserveCreditsV2Input, o as ReserveOutcome, g as CreditBalanceUpdate, c as CreateJournalEntryInput, h as CreditPolicyOptions, p as TierUpdateInput, d as CreateReservationInput, j as ExpireReservationV2Options, E as ExpireOutcome, A as AddCreditsAtomicOptions, D as DeductJournalInput, e as CreateTransactionInput, f as CreateUsageLogInput, U as UsageLogQuery, J as JournalEntryQuery } from './types-BL3YqxUD.js';
+import { c as PortableUserCredits, S as SubscriptionTier, a as PortableReservation, R as ReservationStatus, P as PortableTransaction, d as PortableUsageLog, f as PortableJournalEntry, M as MonthlyResetResult, e as SubscriptionExpiryResult } from './types-C3sxDvNb.js';
+
+/**
+ * One reservation flow for both repository generations.
+ *
+ * Adapters that implement the V2 boundary get the idempotent, race-safe path
+ * and own their journal entry. Adapters that do not (Firestore, custom
+ * implementations) keep the legacy read-then-write path, with the service
+ * writing the journal exactly as it always did — so upgrading this package
+ * does not change their behaviour, and does not double-write anyone's ledger.
+ */
+
+/**
+ * Reserve credits through V2 when available.
+ *
+ * A legacy adapter cannot honour an idempotency key — it has no unique index
+ * to enforce it — so asking for one there is a caller error rather than a
+ * silently ignored option.
+ */
+declare function reserveThroughRepository(repository: ICreditRepository, input: ReserveCreditsV2Input): Promise<ReserveOutcome>;
+/**
+ * Commit through V2 when available, else the legacy read-then-write path.
+ *
+ * **The legacy path cannot promise a single winner.** It reads the status and
+ * then writes, with no lock and no compare-and-set between the two, so two
+ * concurrent commits of the same reservation can both observe `reserved` and
+ * both proceed. The typed outcome still describes what *this* call saw, but on
+ * a legacy adapter `committed` means "this call did the work", not "this call
+ * was the only one that did". Callers needing exactly-once must use a
+ * repository for which `supportsCreditsV2` returns `true`.
+ */
+declare function commitThroughRepository(repository: ICreditRepository, userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<CommitOutcome>;
+/**
+ * Release through V2 when available, else the legacy read-then-write path.
+ *
+ * Same caveat as {@link commitThroughRepository}: on a legacy adapter the
+ * read-then-write sequence is unguarded, so `released` does not exclude a
+ * concurrent commit having also run. Only V2 repositories serialise the two.
+ */
+declare function releaseThroughRepository(repository: ICreditRepository, userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<ReleaseOutcome>;
+/**
+ * Credit an account through the idempotent path when the adapter has one.
+ *
+ * A legacy adapter cannot resolve `created` / `replayed` / `conflict`: it has
+ * no global unique index over `payment_ref`, so it cannot tell a re-delivered
+ * webhook from a second, genuinely different payment that reuses a reference.
+ * Rather than invent an outcome, this reports `created` — which is what the
+ * legacy method actually did — and the ambiguity is documented on the return
+ * type instead of hidden inside it.
+ *
+ * The reference is normalised here as well as in the adapters, so a legacy
+ * adapter that stores the raw string does not persist a whitespace-only
+ * reference that would then deduplicate nothing.
+ */
+declare function addCreditsThroughRepository(repository: ICreditRepository, input: AddCreditsV2Input): Promise<AddCreditsOutcome>;
+
+/**
+ * Shared utilities for credit repository implementations
+ *
+ * These are pure functions with no server-only dependencies,
+ * making them safe to use in any repository implementation.
+ */
+
+/**
+ * Generate a unique ID
+ * Uses timestamp + random string for uniqueness
+ */
+declare function generateId(): string;
+/**
+ * Convert date-like value to Date object
+ * Handles: Date, string, Firestore Timestamp
+ */
+declare function toDate(value: Date | string | unknown): Date;
+/**
+ * Get the first day of next month
+ * Used for calculating monthly reset dates
+ */
+declare function getNextMonthlyReset(from?: Date): Date;
+/** Result of validating a balance update. */
+interface BalanceValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Whether an update leaves a valid account: no negative field, and `reserved` covered
+ * by `balance + bonusCredits`, which is the floor outstanding holds put under the
+ * balance. An increment is applied on top of the absolute value when a call names both.
+ *
+ * An update is a delta the caller asked for, so one that cannot be honoured is refused,
+ * as a deduct is. Only tier writes and resets stop at the floor: they state a target.
+ *
+ * A negative balance increment is a charge, so it draws only on the balance above
+ * `expiredHoldBacking`: those credits are expired and leave when their hold closes, so
+ * charging them would hand the charge back. An absolute balance replaces the field and
+ * the marks with it, so only an increment on the stored balance meets this limit.
+ */
+declare function validateBalanceUpdate(current: Pick<PortableUserCredits, "balance" | "bonusCredits" | "reserved" | "expiredHoldBacking">, updates: CreditBalanceUpdate): BalanceValidationResult;
+/** Refuse an update {@link validateBalanceUpdate} finds invalid. */
+declare function assertValidBalanceUpdate(current: Pick<PortableUserCredits, "balance" | "bonusCredits" | "reserved" | "expiredHoldBacking">, updates: CreditBalanceUpdate): void;
+/**
+ * The journal line of a new account's starting balance, or null when it starts at 0.
+ * Write it in the step that creates the account: that step creates it once, so the
+ * line needs no guard of its own.
+ */
+declare function signupGrantJournalInput(userId: string, tier: SubscriptionTier, grant: number): CreateJournalEntryInput | null;
+/**
+ * The journal line of a tier write that moved the balance, or null when it did not.
+ * Call it before writing anything: it refuses a total the ledger cannot record.
+ *
+ * `amount` follows the lines this one sits beside, not the difference between the
+ * totals: a raise records the balance it set, like `subscription_grant`, and a cut
+ * records 0, like the expiry `subscription_downgrade`. `balanceBefore` and
+ * `balanceAfter` say how far the balance moved.
+ */
+declare function tierChangeJournalInput(input: {
+    userId: string;
+    previousTier: SubscriptionTier;
+    newTier: SubscriptionTier;
+    previousBalance: number;
+    newBalance: number;
+    bonusCredits: number;
+}): CreateJournalEntryInput | null;
+
+/**
+ * In-Memory Credit Repository Implementation
+ *
+ * A database-agnostic implementation of ICreditRepository for testing and prototyping.
+ * All data is stored in memory and lost when the process restarts.
+ *
+ * Usage:
+ * - Unit tests without database dependency
+ * - Local development and prototyping
+ * - Reference implementation for custom repositories
+ */
+
+declare class InMemoryCreditRepository implements ICreditRepository {
+    private readonly store;
+    private readonly options;
+    constructor(options?: CreditPolicyOptions);
+    /**
+     * A copy, never the live record.
+     *
+     * Handing out the stored object made this adapter behave unlike any real
+     * one: a caller holding a "before" snapshot saw it mutate under them. The
+     * service's monthly reset compared `resetResult.credits.balance` against the
+     * balance it had read moments earlier, got zero because both were the same
+     * object, and silently skipped the reset's journal entry — while the SQL
+     * adapter, which maps each row into a fresh object, wrote it.
+     */
+    getUserCredits(userId: string): Promise<PortableUserCredits | null>;
+    initializeUserCredits(userId: string, tier: SubscriptionTier, initialBalance: number): Promise<PortableUserCredits>;
+    /**
+     * The synchronous body of `initializeUserCredits`.
+     *
+     * Kept `await`-free on purpose: `addCreditsV2` seeds a missing user *inside*
+     * its critical section, and an `await` between the payment-reference check
+     * and the transaction write opens a gap another caller can run through — two
+     * simultaneous first deliveries of the same reference would then both credit.
+     */
+    private seedUser;
+    updateUserCredits(userId: string, updates: CreditBalanceUpdate): Promise<void>;
+    updateUserTier(userId: string, input: TierUpdateInput): Promise<void>;
+    createReservation(input: CreateReservationInput): Promise<PortableReservation>;
+    getReservation(userId: string, reservationId: string): Promise<PortableReservation | null>;
+    updateReservationStatus(userId: string, reservationId: string, status: ReservationStatus, completedAt?: Date): Promise<void>;
+    reserveCreditsV2(input: ReserveCreditsV2Input): Promise<ReserveOutcome>;
+    commitReservationV2(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<CommitOutcome>;
+    releaseReservationV2(userId: string, reservationId: string, options?: ReservationTransitionOptions): Promise<ReleaseOutcome>;
+    expireReservationV2(userId: string, reservationId: string, options?: ExpireReservationV2Options): Promise<ExpireOutcome>;
+    reserveCreditsAtomic(userId: string, amount: number, operationType: string, expiresAt: Date): Promise<PortableReservation>;
+    commitReservationAtomic(userId: string, reservationId: string): Promise<void>;
+    releaseReservationAtomic(userId: string, reservationId: string): Promise<void>;
+    /**
+     * The stored transaction carrying this reference, in *any* user's ledger.
+     *
+     * Deliberately not scoped to one user. The SQL adapter's unique index covers
+     * `payment_ref` alone, so searching only the crediting user's own history made
+     * the same reference credit two different accounts here while the SQL adapter
+     * treated the second delivery as a duplicate. See `core/payment-ref.ts`.
+     */
+    private findByPaymentRef;
+    /** The journal entry written alongside a stored purchase, if there is one. */
+    private journalForTransaction;
+    /**
+     * Credit an account, resolving `paymentRef` to created / replayed / conflict.
+     *
+     * The reference is checked and the transaction is recorded with no `await`
+     * between them. `createTransaction` is `async` but its body is synchronous, so
+     * under JavaScript's run-to-completion semantics no other caller can observe
+     * the gap — which is what stands in for the SQL adapter's unique index.
+     *
+     * A `replayed` or `conflict` outcome writes nothing at all: the check runs
+     * before the balance moves, not after.
+     */
+    addCreditsV2(input: AddCreditsV2Input): Promise<AddCreditsOutcome>;
+    /**
+     * The legacy signature, on top of {@link addCreditsV2}.
+     *
+     * `Promise<void>` has nowhere to report a conflict, and silently returning is
+     * indistinguishable from "credited" — the exact failure this round is closing
+     * — so a conflict throws. A genuine replay still returns quietly, because
+     * that *is* the idempotent no-op the caller asked for.
+     */
+    addCreditsAtomic(userId: string, amount: number, description: string, paymentRef?: string, options?: AddCreditsAtomicOptions): Promise<void>;
+    deductCreditsAtomic(userId: string, amount: number, journal?: DeductJournalInput): Promise<{
+        previousBalance: number;
+        newBalance: number;
+        journalEntryId?: string;
+    }>;
+    createTransaction(input: CreateTransactionInput): Promise<PortableTransaction>;
+    /** The unguarded writer, for `addCreditsV2` — which has moved the balance. */
+    private recordTransaction;
+    getTransactions(userId: string, limit?: number, offset?: number): Promise<PortableTransaction[]>;
+    logUsage(input: CreateUsageLogInput): Promise<PortableUsageLog>;
+    getUsageLogs(query: UsageLogQuery): Promise<PortableUsageLog[]>;
+    getUsageLogsCount(query: Omit<UsageLogQuery, "limit" | "offset">): Promise<number>;
+    createJournalEntry(input: CreateJournalEntryInput): Promise<PortableJournalEntry>;
+    /**
+     * The synchronous body of `createJournalEntry`, so `atomicMonthlyReset` can
+     * write its journal line inside the same run-to-completion step as the
+     * balance write — an `await` between the two is exactly the gap that loses
+     * the line when the second half fails.
+     */
+    private recordJournalEntry;
+    getJournalEntries(query: JournalEntryQuery): Promise<PortableJournalEntry[]>;
+    getJournalEntriesCount(query: Omit<JournalEntryQuery, "limit" | "offset">): Promise<number>;
+    /**
+     * Expire every hold whose deadline has passed.
+     *
+     * Each candidate goes through the guarded {@link expireReservationV2}, which
+     * re-checks the status and the deadline under the user's lock. The previous
+     * implementation released the hold and then overwrote the status to
+     * `expired`, so a commit landing in between got its credits handed back and
+     * was then relabelled.
+     */
+    findAndExpireReservations(_batchSize?: number, _maxIterations?: number): Promise<{
+        expiredCount: number;
+        creditsReleased: number;
+        errors: string[];
+    }>;
+    /**
+     * @param _tier - Not trusted. The caller read it earlier and the account may
+     *   have changed tier since, so the reset uses the tier stored on the account.
+     */
+    atomicMonthlyReset(userId: string, _tier: SubscriptionTier, expectedResetAt: Date | string): Promise<MonthlyResetResult>;
+    checkAndHandleSubscriptionExpiry(userId: string, gracePeriodDays?: number): Promise<SubscriptionExpiryResult>;
+    /**
+     * Clear all data (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Install a yield point inside every V2 critical section (testing only).
+     *
+     * Unset, the critical sections run start-to-finish synchronously, so
+     * concurrent callers never interleave and a concurrency test would pass even
+     * with the locking removed. Setting this to a real yield (a macrotask or a
+     * barrier) makes callers genuinely overlap, so the tests exercise the lock
+     * instead of the event loop. Never call this in production code.
+     */
+    setSchedulingHook(hook: (() => Promise<void>) | undefined): void;
+    /**
+     * Get all users (useful for testing/debugging)
+     */
+    getAllUsers(): PortableUserCredits[];
+    /**
+     * Get all reservations for a user (useful for testing)
+     */
+    getAllReservations(userId: string): PortableReservation[];
+}
+/**
+ * Create a new in-memory repository instance
+ * Each call creates a fresh, isolated instance
+ */
+declare function createInMemoryCreditRepository(options?: CreditPolicyOptions): InMemoryCreditRepository;
+
+export { type BalanceValidationResult as B, InMemoryCreditRepository as I, addCreditsThroughRepository as a, assertValidBalanceUpdate as b, commitThroughRepository as c, createInMemoryCreditRepository as d, getNextMonthlyReset as e, reserveThroughRepository as f, generateId as g, toDate as h, releaseThroughRepository as r, signupGrantJournalInput as s, tierChangeJournalInput as t, validateBalanceUpdate as v };