Normalize Bridge webhook payload envelopes

[islandbitcoin]

Summary

• Normalizes Bridge deposit webhook payloads across transfer, virtual-account, and bridge-wallet activity shapes.
• Handles Bridge customer/external-account KYC webhook field differences (id/customer_id, status/kyc_status).
• Normalizes transfer webhook envelopes from event_object while keeping legacy fallback fields.
• Writes normalized deposit events into the ERPNext transfer-request audit path.

Verification

• git diff --check
• eslint --no-ignore src/services/bridge/webhook-server/routes/deposit.ts src/services/bridge/webhook-server/routes/kyc.ts src/services/bridge/webhook-server/routes/transfer.ts src/services/frappe/BridgeTransferRequestWriter.ts

[islandbitcoin]

Reviewed the webhook envelope normalization (deposit/kyc/transfer + the ERPNext writer). The normalization approach is reasonable and the graceful-degradation logging is a nice touch. A few correctness concerns inline — the strongest are the destination_payment_rail-as-currency fallback (in two files) and a silent audit-skip in the writer.

[linear]

ENG-415

[islandbitcoin]

Addressed in 52e42f70f:

• Removed destination_payment_rail as a currency fallback in both the deposit webhook route and ERPNext writer.
• Valid Bridge activity events that lack amount/customer fields are now acknowledged with a 200 skip instead of returning 400 and causing provider retry storms.
• ERPNext audit skips without a stable Bridge request id now log a warning instead of silently returning.
• Confirmed repeated approved KYC webhooks route through the existing idempotent createVirtualAccount path, which checks for a stored VA before creating one.

Focused verification run:

• yarn test:unit test/flash/unit/services/bridge/webhook-server/deposit.spec.ts
• yarn test:unit test/flash/unit/services/frappe/BridgeTransferRequestWriter.spec.ts

[islandbitcoin]

Review comments addressed (902cafe)

All five review threads resolved. Summary:

Thread	Resolution
deposit.ts rail-as-currency	Removed destination_payment_rail fallback → currency ?? "usd". Confirmed via Bridge API docs that payment_rail/destination_payment_rail carries rail values (ach/wire/sepa/base/fednow), always a sibling of currency. Regression test added.
deposit.ts 400 retry-storm	Missing amount/customer now returns 200 skipped instead of 400, so bridge_wallet.activity shapes don't trigger Bridge retries. Test added.
kyc.ts duplicate VA creation	Confirmed safe — createVirtualAccount has the ENG-284 idempotency guard (findVirtualAccountByAccountId early-return) before any mutation.
BridgeTransferRequestWriter.ts rail-as-currency	Same fix — currency ?? "usd", no rail fallback.
BridgeTransferRequestWriter.ts silent drop	No-stableRequestId skip now logs baseLogger.warn before return true.

Additional fixes in this push

• transfer.spec.ts: updated to post Bridge's real webhook envelope (event_type/event_object, nested source.failure_reason) — the handler rewrite changed its input contract but the spec still sent the legacy { event, data } shape, so failed-cashout-audit and already_terminal coverage had silently regressed. Now 10/10 pass.
• kyc.ts: fixed a TS error — bridgeKycStatus was cast to BridgeKycStatus which is never defined/imported; now Account["bridgeKycStatus"].

Verification

• deposit.spec.ts 13/13, transfer.spec.ts 10/10, BridgeTransferRequestWriter.spec.ts 7/7, verify-signature.spec.ts pass
• tsc clean on kyc.ts/transfer.ts/transfer.spec.ts
• eslint clean on changed files

Out of scope (pre-existing on base, not introduced here)

• replay.spec.ts suite-error (getFeesConfig is not a function — @config mock gap from fix(bridge/ENG-375): correct replay tooling — mock name, API params, local date filtering #381)
• deposit.spec.ts delete operator TS strictness warnings (tests pass at runtime)