Function debitIfCovers

@suluk/credits — a metered credit ledger (C046, extracted verbatim). The package OWNS the schema (credit_transaction

the credit_amount/credit_key sidecars); the app injects a Drizzle handle (D1 in prod, bun:sqlite in tests). The money-correctness core: the ATOMIC debitIfCovers (a conditional INSERT that can't drive the ledger negative under concurrency) + the idempotent debitOnceIfCovers (the partial-refund double-spend guard) + per-key spend + the activity-log query. App-specific payment-alert kinds + the user-table count stay in the app.

debitIfCovers(
    db: CreditsDB,
    userId: string,
    amount: number,
    reason: string,
    keyId?: string | null,
): Promise<boolean>
ATOMIC metered debit — append -amount ONLY IF the balance still covers it, in ONE conditional INSERT (atomic on both bun:sqlite and D1), then best-effort attribute it. Returns true when debited, false when the balance raced below the cost. Closes the read-then-write window where K concurrent charges each read the same balance, all pass cost <= balance, and all append — driving the ledger NEGATIVE. The self-guard rejects a non-positive/non-integer amount (a negative would compute delta=+amount and trivially pass the WHERE, MINTING credits).
Parameters
- db: CreditsDB
- userId: string
- amount: number
- reason: string
- OptionalkeyId: string | null
Returns Promise<boolean>
- Defined in packages/credits/src/credits.ts:60