fix(ibex): surface typed INSUFFICIENT_BALANCE on payment failure

[islandbitcoin]

Root cause

IBEX answers an underfunded payment with a 400 and a JSON body like {"error":"insufficient balance. Current Balance: 5.000000. Estimated Fee: 0.001109. invoice amount: 5.042164. account: ..."}, but the API returned only a generic error. Two stacked defects:

1. Classification never fired. src/services/ibex/errors.ts matched e.message.includes("insufficient balance") — but ibex-client@3.2.0's ApiError message is just the wrapped FetchError stack (FetchError: Bad Request…). The JSON body lives on FetchError.data and is discarded at wrap time (lnflash/ibex-client#6), so on the SDK pay path the InsufficientIbexBalance branch was dead code. This also silently broke the fygaro credit-topup treasury-float detection, which matches on InsufficientIbexBalance by class.
2. The resolver swallowed it anyway. lnInvoicePaymentSend collapsed every IbexError subclass into a hardcoded "An unexpected error occurred. Please try again later.", bypassing mapAndParseErrorForGqlResponse.

Design

Works with the currently pinned ibex-client@3.2.0 — no dependency bumps:

• payInvoice now invokes the generated SDK through Ibex.authentication.withAuth directly (both fields are public API; getIbexToken already uses Ibex.authentication.storage the same way), so the raw FetchError — parsed IBEX body on .data — reaches the new httpErrorHandler before ibex-client's wrapper can discard it. httpErrorHandler classifies insufficient-balance / payment-already-prepared from the body and wraps results in the existing IbexError hierarchy (httpCode preserved via ApiError).
• errorHandler additionally reads structured detail (duck-typed ibexMessage / .data), with the existing message-text matching kept as fallback. Once a release containing lnflash/ibex-client#6's fix (lnflash/ibex-client#12, which puts the body on ApiError.ibexResponse/ibexMessage) is adopted, every other call site picks up body-level classification with no further code change here.
• InsufficientIbexBalance now carries a clean client-facing message — the full IBEX detail when available, "insufficient balance" otherwise. The error map forwards message verbatim for the INSUFFICIENT_BALANCE case, which previously would have shipped a raw stack trace to the client.
• lnInvoicePaymentSend branches on InsufficientIbexBalance → mapAndParseErrorForGqlResponse (code INSUFFICIENT_BALANCE); all other IBEX failures keep the exact existing generic message. error-map.ts needed no changes — the InsufficientIbexBalance → INSUFFICIENT_BALANCE case already existed.

Tests

• test/flash/unit/services/ibex/errors.spec.ts — ibexErrorDetail extraction (JSON error/message fields, plain-text body, structured ibexMessage, no-body); errorHandler (raw-fetch-style message match, future structured shape, pinned-version stack-only ApiError stays generic, CompletedInvoice, AuthenticationError, success passthrough); httpErrorHandler (insufficient-balance 400 JSON and non-JSON → typed error with httpCode 400 + full detail message; other 400s → generic IbexError unchanged; network errors → no httpCode; non-Error throwables).
• test/flash/unit/services/ibex/pay-invoice.spec.ts — payInvoice wiring through withAuth: insufficient-balance 400 → InsufficientIbexBalance, other 400 → generic, network failure → generic, success passthrough.
• test/flash/unit/graphql/error-map.spec.ts — InsufficientIbexBalance → INSUFFICIENT_BALANCE (with detail and with fallback message, never a stack), mapAndParseErrorForGqlResponse shape, generic IbexError → IBEX_ERROR unchanged.
• test/flash/unit/graphql/ln-invoice-payment-send.spec.ts — resolver returns typed INSUFFICIENT_BALANCE for insufficient balance, keeps the generic message for other IBEX errors, success path intact.

Local checks: targeted unit suites (14 suites / 197 tests including adjacent client-usd-wallet and fygaro credit-topup consumers) pass; yarn tsc-check passes; eslint clean on all changed files. No changes to .env or yarn.lock.

Fixes #93

🤖 Generated with Claude Code

https://claude.ai/code/session_015fAxSGEsL2LsMx1uCjAzHH