@nehorai/credits 3.0.0 → 3.1.0

package/dist/repository/index.d.cts

@@ -1,255 +1,3 @@
-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, 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, c as CreateJournalEntryInput, J as JournalEntryQuery } from '../types-DOjguhEX.cjs';
-export { i as CreditRepositoryFactory, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from '../types-DOjguhEX.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;
-
-/**
- * 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 { AddCreditsAtomicOptions, AddCreditsV2Input, type BalanceValidationResult, CreateJournalEntryInput, CreateReservationInput, CreateTransactionInput, CreateUsageLogInput, CreditBalanceUpdate, DeductJournalInput, ExpireReservationV2Options, ICreditRepository, InMemoryCreditRepository, JournalEntryQuery, ReservationTransitionOptions, ReserveCreditsV2Input, TierUpdateInput, UsageLogQuery, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, toDate, validateBalanceUpdate };
+export { A as AddCreditsAtomicOptions, b as AddCreditsV2Input, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, i as CreditRepositoryFactory, D as DeductJournalInput, j as ExpireReservationV2Options, I as ICreditRepository, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, J as JournalEntryQuery, m as ReservationTransitionOptions, n as ReserveCreditsV2Input, p as TierUpdateInput, U as UsageLogQuery, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from '../types-YLAB8bFk.cjs';
+export { B as BalanceValidationResult, I as InMemoryCreditRepository, a as addCreditsThroughRepository, b as assertValidBalanceUpdate, c as commitThroughRepository, d as createInMemoryCreditRepository, g as generateId, e as getNextMonthlyReset, r as releaseThroughRepository, f as reserveThroughRepository, h as toDate, v as validateBalanceUpdate } from '../index-BrogG0Gc.cjs';
+import '../types-C3sxDvNb.cjs';

package/dist/repository/index.d.ts

@@ -1,255 +1,3 @@
-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, 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, c as CreateJournalEntryInput, J as JournalEntryQuery } from '../types-CY-oHIMA.js';
-export { i as CreditRepositoryFactory, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from '../types-CY-oHIMA.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;
-
-/**
- * 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 { AddCreditsAtomicOptions, AddCreditsV2Input, type BalanceValidationResult, CreateJournalEntryInput, CreateReservationInput, CreateTransactionInput, CreateUsageLogInput, CreditBalanceUpdate, DeductJournalInput, ExpireReservationV2Options, ICreditRepository, InMemoryCreditRepository, JournalEntryQuery, ReservationTransitionOptions, ReserveCreditsV2Input, TierUpdateInput, UsageLogQuery, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, toDate, validateBalanceUpdate };
+export { A as AddCreditsAtomicOptions, b as AddCreditsV2Input, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, i as CreditRepositoryFactory, D as DeductJournalInput, j as ExpireReservationV2Options, I as ICreditRepository, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, J as JournalEntryQuery, m as ReservationTransitionOptions, n as ReserveCreditsV2Input, p as TierUpdateInput, U as UsageLogQuery, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from '../types-BL3YqxUD.js';
+export { B as BalanceValidationResult, I as InMemoryCreditRepository, a as addCreditsThroughRepository, b as assertValidBalanceUpdate, c as commitThroughRepository, d as createInMemoryCreditRepository, g as generateId, e as getNextMonthlyReset, r as releaseThroughRepository, f as reserveThroughRepository, h as toDate, v as validateBalanceUpdate } from '../index-DOvJES2m.js';
+import '../types-C3sxDvNb.js';

package/dist/repository/index.js

@@ -591,17 +591,25 @@ var DEFAULT_CONFIG = {
   }
 };
 var currentConfig = DEFAULT_CONFIG;
+function isOperationCostMap(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((cost) => isRepresentableAmount(cost) && cost >= 0);
+}
 function loadConfigFromEnv() {
   const envConfig = {};
   const operationCostsEnv = process.env.CREDITS_OPERATION_COSTS;
   if (operationCostsEnv) {
     try {
       const parsed = JSON.parse(operationCostsEnv);
-      if (typeof parsed === "object" && parsed !== null) {
+      if (isOperationCostMap(parsed)) {
         envConfig.operationCosts = {
           ...DEFAULT_CONFIG.operationCosts,
           ...parsed
         };
+      } else {
+        console.warn(
+          "[Credits Config] Ignoring CREDITS_OPERATION_COSTS: it must be a JSON object whose costs are numbers >= 0, exact to the cent"
+        );
       }
     } catch {
       console.warn("[Credits Config] Failed to parse CREDITS_OPERATION_COSTS env var as JSON");
@@ -946,6 +954,50 @@ function assertValidBalanceUpdate(current, updates) {
     throw new Error(`Invalid balance update: ${result.errors.join("; ")}`);
   }
 }
+function signupGrantJournalInput(userId, tier, grant) {
+  if (grant <= 0) return null;
+  return {
+    userId,
+    entryType: "credit",
+    amount: grant,
+    balanceBefore: 0,
+    balanceAfter: grant,
+    source: "bonus",
+    referenceId: `signup-${userId}`,
+    referenceType: "adjustment",
+    description: `Signup grant for ${tier} tier.`,
+    metadata: { tier }
+  };
+}
+function tierChangeJournalInput(input) {
+  const { userId, previousTier, newTier, previousBalance, newBalance, bonusCredits } = input;
+  const change = sumAmounts(newBalance, -previousBalance);
+  if (change === 0) return null;
+  const raised = change > 0;
+  const amount = raised ? newBalance : 0;
+  const balanceBefore = sumAmounts(previousBalance, bonusCredits);
+  const balanceAfter = sumAmounts(newBalance, bonusCredits);
+  assertRepresentableFields(
+    {
+      "journal amount": amount,
+      "journal balanceBefore": balanceBefore,
+      "journal balanceAfter": balanceAfter
+    },
+    { userId, operation: "updateUserTier" }
+  );
+  return {
+    userId,
+    entryType: raised ? "credit" : "debit",
+    amount,
+    balanceBefore,
+    balanceAfter,
+    source: raised ? "subscription_upgrade" : "subscription_downgrade",
+    referenceId: `tier-${Date.now()}`,
+    referenceType: "subscription",
+    description: `Tier changed from ${previousTier} to ${newTier}.`,
+    metadata: { previousTier, newTier, previousBalance, newBalance }
+  };
+}
 
 // src/repository/memory/snapshot.ts
 function copyRecord(record) {
@@ -1590,6 +1642,8 @@ var InMemoryCreditRepository = class {
       updatedAt: now
     };
     this.store.users.set(userId, credits);
+    const grantLine = signupGrantJournalInput(userId, tier, initialBalance);
+    if (grantLine) this.recordJournalEntry(grantLine);
     return credits;
   }
   async updateUserCredits(userId, updates) {
@@ -1670,21 +1724,29 @@ var InMemoryCreditRepository = class {
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
-    if (input.balanceCap !== void 0 && !isFreeTier(credits.tier)) {
-      const capped = planBalanceCap(
+    let planned;
+    if (input.balance !== void 0) {
+      planned = planBalanceTarget(input.balance, credits.reserved, credits.bonusCredits);
+    } else if (input.balanceCap !== void 0 && !isFreeTier(credits.tier)) {
+      planned = planBalanceCap(
         credits.balance,
         input.balanceCap,
         credits.reserved,
         credits.bonusCredits,
         credits.expiredHoldBacking
       );
-      credits.balance = capped.balance;
-      writeExpiredHoldBacking(this.store, credits, capped.expiredHoldBacking);
     }
+    const journalLine = planned ? tierChangeJournalInput({
+      userId,
+      previousTier: credits.tier,
+      newTier: input.tier,
+      previousBalance: credits.balance,
+      newBalance: planned.balance,
+      bonusCredits: credits.bonusCredits
+    }) : null;
     credits.tier = input.tier;
     credits.monthlyLimit = input.monthlyLimit;
-    if (input.balance !== void 0) {
-      const planned = planBalanceTarget(input.balance, credits.reserved, credits.bonusCredits);
+    if (planned) {
       credits.balance = planned.balance;
       writeExpiredHoldBacking(this.store, credits, planned.expiredHoldBacking);
     }
@@ -1703,6 +1765,7 @@ var InMemoryCreditRepository = class {
     }
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.store.users.set(userId, credits);
+    if (journalLine) this.recordJournalEntry(journalLine);
   }
   // ==================== Reservations ====================
   async createReservation(input) {
@@ -2324,7 +2387,7 @@ var InMemoryCreditRepository = class {
       userId,
       entryType: "debit",
       amount: 0,
-      // No credits deducted, just tier change
+      // 0, however far the cap lowered the balance: the totals record the move
       balanceBefore: sumAmounts(previousBalance, credits.bonusCredits),
       balanceAfter,
       source: "subscription_downgrade",