banking_circle

# Changelog

All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [1.0.0] - Unreleased

### Added
- Initial release.
- `BankingCircle.Config` / `BankingCircle.Environment` — validated
  per-client configuration with sandbox/production host resolution and
  `{:system, "VAR"}` secret resolution.
- `BankingCircle.Auth.TokenServer` — cached, single-flight-refreshed
  OAuth2/JWT token per client, honoring Banking Circle's documented
  5-minute token lifetime and auth-endpoint rate limiting.
- `BankingCircle.HTTP.Client` — shared Req-based request pipeline with
  auth injection, telemetry spans, and error normalization.
- `BankingCircle.HTTP.Middleware.Retry` — jittered exponential backoff,
  `Retry-After` support, restricted to GET/HEAD or idempotency-keyed
  requests to avoid duplicate payment submission.
- `BankingCircle.HTTP.Middleware.Idempotency` — UUIDv4 generation and
  header attachment.
- `BankingCircle.Error` — normalizes both documented error body shapes
  (standard `propertyName`/`errorCode` and bulk `fieldIndex`/`elementIndex`)
  into one struct, with `retryable?/1`.
- `BankingCircle.Payments` — single payment create/list/status/get/cancel/
  reject/mt103/lookup-by-reference; bulk payment create/list/get/cancel.
- `BankingCircle.Schemas.Payment` / `BankingCircle.Schemas.BulkPayment` —
  Ecto-changeset client-side validation and CSV rendering for bulk
  submission.
- `BankingCircle.Accounts` — list/get/balance/Account Holder Verification.
- `BankingCircle.Webhooks` — subscription create/list/get/activate/
  deactivate/remove, sandbox simulation.
- `BankingCircle.Webhook.Verifier` — AES-256-GCM payload decryption with
  constant-time checksum verification.
- `BankingCircle.FX` — market-order trading, batched RFQ/indicative/
  held-rate quote requests, single-pair held rate lookup, trade history
  (JSON + CSV), single-trade lookup, settlement date calendar, and
  customer exposure.
- `BankingCircle.Reporting` — the async request → poll → download report
  flow (`request_report/3`, `poll_status/2`, `download/2`), plus a
  blocking `fetch_report/3` convenience wrapper for scripts/background
  workers.
- `BankingCircle.Cases` / `BankingCircle.Cases.RFI` — case listing
  (cursor pagination), typed RFI/Recall case retrieval, attachment
  upload, and RFI answer submission (both the "request a return" and
  "answer every question" paths).
- `BankingCircle.DirectDebit` — mandate-based collection initiation
  against `/api/v1/payments/direct-debit-instructions`, always attaching
  an idempotency key (this is the one payment-initiation endpoint Banking
  Circle documents idempotency support for).
- `BankingCircle.Payments.initiate_recall/3`, `.initiate_trace/2`, and
  friends — payment recall and trace lifecycle.
- `BankingCircle.Payments.create_fi_to_fi/2` — Correspondent/Agency
  Banking payment initiation via the JSON API, plus embedded-rate/RFQ/held-
  rate FX support on the same payment.
- `BankingCircle.ISO20022` — pain.001/pacs.008 XML submission and camt.053
  retrieval (transport layer only — does not build/validate XML; see its
  moduledoc for scope).
- `BankingCircle.FX.Stream` — WebSocket-based streaming FX quotes and
  Market Order execution, with automatic token-refresh-over-the-wire to
  keep long-lived sessions alive.
- `BankingCircle.VirtualAccounts` — VIBAN listing, customer/UBO details
  for POBO/COBO accounts (write-once), and the full closure lifecycle
  (`close/2` + `close_status/2`). `order/2` is included but flagged as
  endpoint-path-inferred rather than confirmed — see its moduledoc.
- `BankingCircle.Accounts.list_bookings/3` — transaction-level ledger
  (outflows and inflows), matchable to payments via `bookingReference`/
  `transactionId`.
- `BankingCircle.Reporting.reconciliation_report/2` — the synchronous
  Reconciliation Report endpoint (up to 50,000 payments inline), as a
  direct alternative to the async request/poll/download flow.
- Full test suite (Bypass-backed) covering token single-flight behavior,
  retry policy boundaries, error normalization, webhook crypto round-trip
  and tamper detection, schema validation, FX trade/quote payload shaping,
  the full reporting request/poll/download flow, case RFI submission
  (both variants), direct debit idempotency-key attachment,
  recall/trace/fi-to-fi payload shaping, and virtual account
  list/order/close/update payload shaping.

### Known gaps (tracked for future releases)
- **Correspondent/Agency Banking via Swift is deliberately out of
  scope** — it's a SWIFT FIN network integration, not a Banking Circle
  Connect HTTP endpoint, so there's nothing here for an HTTP client to
  wrap. See the README's scope section.
- **Aliases (PayID, etc.) is genuinely not implemented** — I could not
  confirm its REST endpoint paths/payloads against available
  documentation, and chose not to guess at a payment-routing feature
  where a wrong guess is dangerous. See the README's scope section.
- `BankingCircle.VirtualAccounts.order/2`'s endpoint path is inferred,
  not confirmed — verify before relying on it.
- `BankingCircle.ISO20022` doesn't build or validate XML documents for
  you — bring your own pain.001/pacs.008 XML.
- `BankingCircle.FX.Stream` has had less real-world exercise than the
  REST modules (different transport, `WebSockex`-based) — verify
  reconnect/token-refresh behavior against your own sandbox first.