feat(fygaro): fee-aware auto-credit — credit net, configurable via ERPNext

[islandbitcoin]

Money flow

The Fygaro card-topup webhook credited the full gross face value. But Fygaro/PayPal take a processor cut off what actually settles to Flash, and Flash wants a margin — so today Flash loses money on every top-up. This PR makes the credited amount the NET, driven by operator-configurable fees, and stamps the fee breakdown onto the ERPNext audit row.

Fee source — ERPNext "Fygaro Settings"

A new ErpNext.getFygaroSettings() reads the Fygaro Settings Single doctype (processor, processor_fee_percent, processor_fee_fixed, flash_margin_percent, flash_margin_fixed, auto_credit_limit, minimum_topup, auto_credit_enabled). It is memoised for ~60s in fygaro-settings.ts so the webhook never hammers ERPNext per payment. A failed read, a missing row, or a malformed row all resolve to unavailable — never "assume zero fees" — and the failure is cached so an outage degrades to record-only without a fetch storm.

The formula (integer cents; each fee rounded to the nearest cent)

gross_cents         = round(amount * 100)
processor_fee_cents = round(gross_cents * processor_fee_percent/100) + round(processor_fee_fixed * 100)
flash_fee_cents     = round(gross_cents * flash_margin_percent/100)  + round(flash_margin_fixed * 100)
net_cents           = gross_cents - processor_fee_cents - flash_fee_cents

$10.00 → processor $0.79, flash $0.20, net $9.01.

Gating

Auto-credit runs only if all hold:

1. FygaroConfig.credit.enabled — the existing yaml deploy-level master gate (kept as-is)
2. Fygaro Settings read succeeded AND auto_credit_enabled
3. currency === "USD"
4. gross_cents ≤ auto_credit_limit * 100 (threshold on gross)
5. net_cents > 0

Otherwise → RECORD-ONLY: the ERPNext row stays Fiat Received, nothing is credited, and one ops alert (notifyOpsEvent + alertBridge) names the specific failing gate: settings-unavailable / auto-credit-disabled / non-usd / over-limit / non-positive-net. The credit-disabled master gate records silently (unchanged deploy behavior; settings aren't even read).

When it does credit: it sends net_cents (not gross) and populates the row — initial_amount = gross, processor_fee, flash_fee, final_amount = net credited (fields added to the BridgeTransferRequest model/writer; the doctype fields ship in the companion PR).

All existing safety is preserved: idempotency on the transaction id, Pending-means-credited, the releasing-lock + Completed-row processed-marker, and the ResourceAttemptsLockServiceError-vs-other-error distinction.

GraphQL — globals.fygaroTopup

New nullable public field so the mobile app can compute "you'll receive $X" locally:

type FygaroTopupInfo {
  minimumAmount: Float!       # USD, from minimum_topup
  processorFeePercent: Float!
  processorFeeFixed: Float!   # USD
  flashFeePercent: Float!     # from flash_margin_percent
  flashFeeFixed: Float!       # USD, from flash_margin_fixed
}

type Globals {
  # ...
  fygaroTopup: FygaroTopupInfo   # null when settings unavailable → app falls back gracefully
}

Sourced from the same 60s-cached settings. SDL regenerated via yarn write-sdl (public schema + composed supergraph).

Safe degradation

If ERPNext is unreachable or the settings row is malformed while credit is enabled, every payment is recorded, not credited, with a settings-unavailable ops alert — money is never credited off missing fee data, and the GraphQL field returns null so the app hides the estimate.

Tests

test/flash/unit/services/fygaro/webhook-server/:

• fee math — table ($10/$1/$500/$33.33 rounding), independent per-component rounding, fixed-margin
• gating matrix — credits when all gates pass; record-only for each failing gate with the right alert reason; inclusive limit threshold
• settings — validation/coercion, 60s caching, failure fallback + failure-caching + recovery, malformed-row rejection
• row fields — initial/processor_fee/flash_fee/final populated on credit

yarn tsc-check, yarn eslint-check, and the full yarn test:unit (174 suites / 1487 tests) all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NcEjF6SS3Ci5D4CzZqdPjb