feat: per-user Flash-fee discounts + payer-email attribution on Fygaro topups

[islandbitcoin]

Backed by the new ERPNext Fee Discount doctype (lnflash/frappe-flash-admin#67). Two operator-facing features:

1. Fee Discount whitelist (topups + Jamaican bank cashouts)

A whitelisted username gets a 0–100% discount off the FLASH fee — never processor fees — on Fygaro card top-ups and/or cashout offers.

• New cached reader src/services/frappe/fee-discounts.ts (60s TTL, mirrors fygaro-settings.ts) that fails OPEN to 0%: an unreadable/malformed whitelist charges the standard fee; it can never block a credit or an offer (deliberately the opposite polarity of Fygaro Settings, which fails closed). Malformed rows are dropped individually, and the operator's Active tick is honoured in the validator, not only in the query filter.
• computeFygaroFees discounts the whole Flash fee (percent + fixed components), clamped 0–100 so garbage can never inflate a fee. The discounted breakdown lands on the ERPNext audit row (flash_fee, final_amount) and in the credited net. A 100% discount = full waiver and can rescue an otherwise non-positive-net payment.
• CashoutManager.createOffer applies the discount to the service fee in one multiplyBips step (0.01% precision), before the JMD/USD payout branch — covers both JMD and USD payouts to Jamaican banks. The offer the app displays carries the discounted fee automatically. Bridge/ACH withdrawals untouched.
• API change — cashoutRate.feeBasisPoints is now per-account. The authed cashoutRate query previously returned the flat config fee; it now returns the caller's discounted fee, so the entry-screen preview matches the offer the user then accepts. That means the query reads ERPNext (the 60s-cached Fee Discount whitelist) on every call, and fails open to the standard fee. Because the field is an Int, the quote is rounded to a whole basis point while the offer keeps full precision and rounds once at the end on money — so a fractional discount_percent can leave the two up to 1 bip apart (at the configured 200-bip fee: any discount that is not a multiple of 0.5%; e.g. 33.4% quotes 133 bips / $6.65 on a $500 cashout while the offer charges 133.2 bips / $6.66). The SDL description states that tolerance and cashout-rate.spec.ts pins it. Whole- and half-percent discounts are exact.
• Whitelist consulted only when a credit could actually happen (same guard as the history read), so a credit-disabled deploy still never touches ERPNext.

2. Payer-email fallback attribution (username on every topup)

When customReference is blank or unknown (every pre-fix app build), the webhook now resolves the checkout payer email → Kratos identity (email is a login identifier) → Flash account, and stamps account_id on the audit row — so the admin Transfer Requests page shows the username on every top-up, credited or not.

• DISPLAY-ONLY by design: the checkout email is payer-typed, not verified app identity. The credit path stays keyed strictly on customReference; the email-matched account never feeds the credit gate (test-pinned).
• The unattributed ops alert now names the matched username as an unverified lead to confirm, not an instruction to credit — no more manual email→kratos→mongo chase.
• source_systems_seen gains email_attribution so the detail view shows how the row got its account.
• Best-effort: a Kratos/Mongo failure on the email lookup degrades to today's unattributed row. A repository fault on the customReference lookup is different — it is not "unknown username" and now returns 500 so Fygaro retries (see below).

Known gap — email-attributed rows are EXCLUDED from the daily cap. sumFygaroTopupGrossCentsSince skips any row marked email_attribution, because that account_id came from payer-typed input nobody verified: counting it would let anyone who knows a victim's email burn the victim's daily allowance and lock them out of auto-credit for 24h. The consequence is the inverse, and worth sizing the caps around: payer-email-attributed top-ups do not consume the account's daily allowance, and they still don't after an ops hand-credit — the marker survives in source_systems_seen, and a hand-credit is a human decision taken outside this auto-credit gate. Since a blank customReference is every pre-fix app build, that is currently the dominant population of top-ups. The L1/L2/L3 daily caps shipped in #482 therefore bound customReference-attributed volume only. Whoever tunes those numbers should read them that way. The marker is cleared the moment a later delivery attributes the same transaction from customReference, so a row only stays exempt while it is genuinely email-attributed.

Known gap: the unauthenticated globals.fygaroTopup fee preview shows standard rates, so a discounted user sees a conservative "you'll receive" estimate in the app and receives more.

Review fixes folded in

• Case-insensitive matching + guard dedupe — usernames normalize to lowercase on both sides (registration case vs whatever the operator types into ERPNext).
• Active honoured in the validator — unticking Active is how a promo ends; enforcing it only in the query filter meant a dropped filter would discount forever, silently, because the reader fails open.
• Repository fault ≠ unknown username (payment.ts) — findByUsername returns CouldNotFindAccountFromUsernameError for a real miss and parseRepositoryError(err) for a Mongo fault. Collapsing them meant a re-delivery during a Mongo blip fell through to the payer-email fallback and stamped email_attribution onto a row whose account_id was already verified — permanently exempting an already-credited top-up from the cap sum (so the account read $0 spent and could auto-credit its full cap again) while acking 200 and stranding the payment. A fault now logs, fires a TTL-deduped warning on a static fygaro:account-lookup-failed key, and returns 500 so Fygaro retries — same self-heal policy the handler already applies to transient ERPNext reads.
• The email_attribution marker is no longer sticky (ErpNext.applyUpdateGuards) — it is a live claim about how this row's account_id was resolved, not provenance, so an incoming payload that names an account without claiming email attribution clears it from the merged set. Unattributed re-deliveries leave it alone.

Tests

• fee-discounts.spec.ts (new): validation/coercion, Active enforcement, flow scoping, fail-open on error + failure caching, malformed-row isolation, TTL behavior.
• fees.spec.ts: discount math incl. fixed-component, fractional %, clamping, gate flow-through, non-positive-net rescue.
• payment.spec.ts: email attribution (stamped + alert-named + never credited; skipped when customReference resolves; kratos-down safe; no-email safe), repository-fault → 500 with no audit write and no email fallback, discounted credit path end-to-end (flashFee "0.10"/"0.00" on the promoted row), whitelist not consulted when auto-credit is off.
• ErpNext.spec.ts: cap sum skips email-attributed rows (and does not treat a lookalike system or an absent value as an exemption); a customReference-attributed upsert clears the marker on both the direct and create-race paths, while an email-attributed or account-less write keeps it.
• cashout-fee-discount.spec.ts (new): real Money math — 0/25/100% and username-less accounts.
• cashout-rate.spec.ts: discounted quote, 100% waiver, no-username, ERPNext-down fail-closed, and the ±1 bip rounding contract (33.4% inexact, 33.5% exact).
• Full unit suite: 189 suites, 1808 passed, 3 skipped. tsc (both configs), eslint, prettier, check-yaml, check:sdl and madge all clean.

Deploy

Deploy frappe-flash-admin#67 first (fail-open makes order non-load-bearing, but discounts only take effect once the doctype exists). No chart/env changes: the fygaro-webhook workload already gets galoy.kratos.env and the ErpNext client.

🤖 Generated with Claude Code

https://claude.ai/code/session_017z72JdVxFAYpCQ3RJYkBRQ