bml_connect 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91517f1cbbf91c13d81d93227136d7a53c5ed19d1668f035675c364c4c67f96f
-  data.tar.gz: 460a93c1c771a53f56fd7fdbbfa6183031e2862b82cf75e08b273f0ccfe52aee
+  metadata.gz: 3188c8c01dd2f98bf493c8e9dfd17e7698b562c9f5e881f151aaa83ff71fdc23
+  data.tar.gz: aa04de2dbe02ff410bfa23e6be2ba6bf91fc8b130dada0a6b6fa1ca9ebd06bd5
 SHA512:
-  metadata.gz: ef33690f58f716fc30f275ad3e0a3e0ddef3279eb13973a5f2c4fbe2273f6caac4b7fac56136fd320eed7ba497dcbd50349d2f0a64e40780a6ad1f7f23011d8b
-  data.tar.gz: 8e5914d7c89ea92d8ed589d3b0cf8c3225fc2edacd68f152dbc763f42b3653f8f847a3aac4a212c7535b37843b4536e65f7ee00abe653fb05aec42e58a50ba76
+  metadata.gz: c8d7f7cea98ca9a3196fff43a87ef5befdb0f8ca1d009cef04f345ed408c9d48713be6849943007ab6eaf55a11097711ec7116a9d3c9ae5f811474447aea9e38
+  data.tar.gz: b295ca6fe627df089aef1f76cc9300d8440285b8c121082eb4825ba8e1e8c62f02db5610213c4f3d19ded7b5616d8c6195c78e322dfe4cafa499c734cf78cf75

data/CHANGELOG.md

@@ -1,5 +1,194 @@
 ## [Unreleased]
 
-## [0.1.0] - 2021-08-31
+## [0.3.0] - 2026-10-26
+
+Release gates, as of 2026-10-26, all observed in BML UAT through `msgowl/website`:
+
+- **Closed — `tokenId` identity.** `token_id` takes `Token#id`. Charges made that way returned
+  `CONFIRMED` (2026-10-21 onward; see `docs/website/research/bml-saved-card-adhoc-charge.md`).
+- **Closed — webhook identifier field.** Every delivery carries a top-level `transactionId`, the first
+  built-in candidate, for both `NOTIFY_TRANSACTION_CHANGE` and `NOTIFY_TOKENISATION_STATUS`
+  (2026-10-21/22). No `extract_id:` override is needed.
+- **Closed — live token and charge observation.** Customers, token listing, tokenizing transactions,
+  stored-card charges and webhook verification have all run end to end in UAT.
+- **Works, key not pinned — v2 payment URL.** Hosted-page redirects from `create_v2` work in UAT
+  through the `url` / `redirectUrl` / `qr.url` fallback, but which of them BML populates has not been
+  recorded.
+- **Still unobserved** — a declined charge, a charge returning `nextAction`, and a charge whose outcome
+  never arrives. These are handled against the published contract only.
+
+### Added
+- **Webhook dispatch** (`BMLConnect::Webhooks::Router`, and a `router:` keyword on
+  `client.webhooks.handle`). A merchant registers one hook in BML's portal, so a single endpoint
+  receives notifications for every transaction the merchant creates. The router sends a **verified**
+  result to the handler the consumer's own resolver names — the gem stays ignorant of what those
+  names mean, because the payload cannot say which of a consumer's flows owns a transaction and
+  only the consumer's records can. Registering two handlers under one name, naming an unregistered
+  handler, or receiving a transaction nothing owns with no fallback all raise rather than passing
+  silently. `router:` chooses where a verified result goes; it cannot affect whether verification
+  happened, which `spec/unit/webhooks_surface_spec.rb` continues to guard.
+- **Transaction-status webhook handling** (`client.webhooks.handle`), implementing feature
+  `005-webhook-handler`. Accepts a raw inbound notification — body, headers, and optionally a
+  caller-presented shared secret — and returns a `BMLConnect::Models::StatusChangeResult`. The
+  published contract documents the callback **nowhere** (no payload schema, no event list, no
+  signature or authentication), so the entire inbound surface is `[UNVERIFIED]` and the design is
+  built to need almost nothing from it. Highlights:
+  - **Verify-by-fetch, with no opt-out.** The payload is an untrusted hint that something changed;
+    the reported status always comes from a fresh `GET /public/transactions/{id}`. A forged "payment
+    confirmed" can at worst cost one wasted retrieve. No flag, option, or mode skips the retrieve —
+    test-enforced against the public surface, not merely defaulted.
+  - **No web-framework dependency and no new gem dependency at all.** Parsing uses stdlib `json` and
+    `uri`; the constant-time secret comparison uses stdlib `digest`. The library owns no route and
+    never writes a response.
+  - **At most two retrieves per notification, neither auto-retried.** The verify, plus at most one
+    delayed re-check when the payload's claimed status disagrees with the authoritative one
+    (default delay 3s, `0` disables it — the delay is spent inside the caller's request).
+  - **Advisory HTTP status on every result and error** (`advisory_http_status`), distinguishing
+    permanent outcomes from transient ones so a host application knows when redelivery helps.
+    `404` is never advised, even for a missing transaction: it reads as "no such endpoint" and risks
+    the hook being disabled.
+  - **Optional shared secret that gates spend, not trust.** When configured, a delivery presenting
+    no value or a wrong one is rejected with **zero** retrieves; a match never causes the payload to
+    be believed. The caller extracts the value (BML controls the callback's headers, so in practice
+    it rides in the registered URL) — the library never infers a location.
+  - **No raw payload on the result.** Payload-derived data is limited to a masked `claimed_status`
+    and a `disagreed?` flag; the raw body reaches the masked audit record only.
+  - **Audits every outcome, including rejections** — a refused delivery is the signature of a forgery
+    attempt, and an operator needs to see it.
+  - **No state enumeration, no deduplication, no body-size limit** — the published contract defines
+    no states, the gem owns no datastore, and it does not own the socket.
+  - **Identifier field observed**: UAT deliveries carry a top-level `transactionId`, the first
+    built-in candidate. A wrong guess still fails loudly rather than reporting a false status, and
+    `extract_id:` still overrides the list outright.
+- `BMLConnect::WebhookRejectedError` — raised when an inbound notification fails the optional
+  shared-secret check. A distinct class so a security rejection stays observably separate from a
+  malformed body.
+
+### Changed
+- `BMLConnect::Error` now carries an `advisory_http_status` accessor (nil unless set by the webhook
+  path). No existing error class or raise site changed behavior.
+- `Transactions#retrieve` accepts an optional `retries:` keyword (default `true`, preserving released
+  behavior). The webhook handler passes `false`: the two-retrieve cap counts HTTP calls, so with
+  retry left on, one notification arriving while BML was flaky could have made six requests.
+- BML's own error text is now masked before it becomes an exception message, so a card-like value in
+  an upstream error body cannot reach a log or an error message. Applies to every resource.
+
+### Added (earlier)
+- **Stored-card charge** (`client.customers.charge`), implementing feature `004-token-charge` on
+  the documented `POST /public-customers/charge` endpoint. Takes `customer_id:`, `transaction_id:`
+  and `token_id:` (all required, validated locally by name before any remote call) plus an optional
+  `actor:`, and returns a `BMLConnect::Models::TransactionRecord`. Highlights:
+  - **Two-call flow, kept two calls.** No combined create-and-charge method exists (test-enforced);
+    the transaction is created first (`create_v2`) and supplies the amount — the charge carries no
+    `amount` of its own.
+  - **Never auto-retried** — the charge schema has no idempotency key, so exactly one HTTP attempt
+    is made; a timeout/transport failure raises `AvailabilityError` whose message names the
+    `transaction_id` for reconciliation by retrieval.
+  - **Returned vs. raised** are never conflated: a returned record (including a decline in a failed
+    `state`) is a business outcome; a raised error is a transport/validation outcome.
+  - **Audits failures too** (success, decline, validation failure, availability failure), masked and
+    carrying the transaction and token ids but never card data.
+  - **`token_id` is `Token#id`**, confirmed in UAT: charges against `Token#id` return `CONFIRMED`.
+    The opt-in UAT spec (`spec/integration/customers_charge_uat_spec.rb`) still exercises it.
+- **Transactions v2 surface**, implementing feature `003-transactions-v2` on the shared `Resource`
+  transport — **additive**, no released method changed. New value-object methods `create_v2`,
+  `retrieve`, `update`, `capture` and `cancel` target the documented `/public/v2/transactions` and
+  `/public/transactions/{id}` endpoints, return whitelisted `BMLConnect::Models::TransactionRecord`
+  objects, and raise the shared typed error hierarchy. Highlights:
+  - `create_v2` supports variant 3 (existing `customerId`) and variant 4 (inline `customer`);
+    variants 1/2 (shop orders) and 5 (foreign exchange) are rejected locally by name.
+  - `tokenizationDetails` (`BMLConnect::Models::TokenizationDetails`) instructs BML to store a card;
+    `tokenize`/`paymentType` are required, and `recurringFrequency`/future `expiryDate` are required
+    when `paymentType` is `RECURRING` — all validated before any remote call.
+  - `amount` (on both `create_v2` and `capture`) must be a **positive Integer in minor units**; a
+    Float, String, zero, or negative is rejected by name and never coerced.
+  - **No auto-retry on create or capture** (no documented idempotency key); a timeout raises
+    `AvailabilityError` after exactly one attempt. Retrieve/list/update/cancel retry with backoff.
+  - `create_v2`/`update`/`capture`/`cancel` emit masked audit records; the hosted payment URL is
+    treated as a completion secret — omitted from `#to_h`/`#inspect` and never logged or audited.
+    `TransactionRecord#payment_url` raises `UnverifiedFieldError` (new) rather than returning `nil`
+    when no URL field is present, pending UAT confirmation of which v2 field carries it.
+  - `state` is passed through verbatim (never normalized); v2 requests send **no** `signature`
+    until UAT settles whether v2 accepts one.
+- **Deprecated** the legacy v1 `transactions.create` (undocumented-but-live `POST
+  /public/transactions`). It still works unchanged and returns a `Faraday::Response`, but now logs a
+  single, once-per-process deprecation warning pointing at `create_v2`.
+- Fixed a latent Ruby 2.7 bug in `BMLConnect::Models::Transaction`: a missing-fields `create`
+  raised `NoMethodError` (`Set#join`, Ruby 3.0+) instead of the intended `ArgumentError` on the 2.7
+  runtime `msgowl/website` uses. Bug fix only — makes the code do what its own test already asserts.
+- **Stored card tokens resource** (`client.tokens`), implementing feature `002-stored-card-tokens`
+  against BML's `/public-customers/{customerId}/tokens` contract: `list`, `retrieve`, and `delete`
+  (soft delete, `204`). Read-and-delete **only** — BML publishes no token-creation endpoint, so the
+  resource deliberately exposes no `create`/`tokenize`/`detokenize` method and a test enforces the
+  absence (SC-006). Returns whitelisted `BMLConnect::Models::Token` / `TokenList` value objects
+  (mirroring BML's field names — no `last_four`/`scheme` alias) and raises the shared typed error
+  hierarchy. Only `delete` is audited, once, even across retries; the optional `actor:` is screened
+  for card data.
+- Extended the shared transport to retry `429` responses (in addition to `408`/timeouts/`5xx`) with
+  bounded backoff on every resource (FR-013a); a surviving `429` still surfaces as `RateLimitError`
+  carrying `Retry-After`. Retry knobs are `max_retries` / `retry_backoff` on the client
+  (`max_retries: 0` disables).
+- **Customers resource** (`client.customers`), implementing feature `001-customers-endpoints`
+  against BML's `/public-customers` contract: `create`, `retrieve`, `list`, partial `update`
+  (`PATCH`), and `archive` (soft delete). Returns whitelisted `BMLConnect::Models::Customer` /
+  `CustomerList` value objects and raises a typed error hierarchy
+  (`ValidationError`/`NotFoundError`/`AuthenticationError`/`ConflictError`/`RateLimitError`/`AvailabilityError`)
+  instead of the raw `Faraday::Response` that `transactions` returns.
+- Shared infrastructure consumed by later features `002`/`004`: `BMLConnect::Errors`,
+  `Masking` (Luhn-gated PAN detection + log scrubbing), `Audit` (masked structured audit line via
+  the client's logger — no separate sink), and a `Resource` transport base (URL derived from the
+  client's base URL, status→error mapping, bounded retry with backoff, `Retry-After` on 429).
+- Local safeguards: required-field and lightweight email-shape validation, and PAN/CVV screening
+  of **every** caller-supplied string (and the optional `actor`) before any remote call.
+- Test tiers: unit, contract (WebMock, stub URLs derived from `client.base_url`), an
+  OpenAPI-conformance test that reads `reference/Connect-API.json` (Constitution II anti-stub
+  gate), and an opt-in, credential-gated UAT suite that loads a repo-local `.env` (git-ignored;
+  see `.env.example`). Added `webmock` and `dotenv` development dependencies and a `.gitleaks.toml`
+  secret-scanning config.
+- Vendored BML's published OpenAPI contract at `reference/Connect-API.json` (Connect API v2.0),
+  with `reference/README.md` describing the endpoint inventory, what is out of scope, and the two
+  things this gem does that the document does not describe.
+- Spec Kit machinery (`.specify/`, `speckit-feature`) and four feature specifications covering
+  the tokenization surface, each with plan, research, data model, tasks, and both an HTTP and a
+  Ruby contract:
+  - `specs/001-customers-endpoints` — `/public-customers` CRUD + archive
+  - `specs/002-stored-card-tokens` — `/public-customers/{customerId}/tokens` list, retrieve, delete
+  - `specs/003-transactions-v2` — `/public/v2/transactions`, `tokenizationDetails`, update, capture, cancel
+  - `specs/004-token-charge` — `/public-customers/charge`
+- `MIGRATION.md` recording the move of tokenization work into this gem from `bml_tokenization`,
+  including the endpoint, authentication, data-model and flow corrections that prompted it.
+
+### Changed
+- Project constitution amended to **2.0.0** (`.specify/memory/constitution.md`). Principle III
+  now requires contracts to derive from `reference/Connect-API.json` and be verified against a
+  live environment. Principle II gains an explicit gate that a stubbed test is not evidence an
+  endpoint exists. Principle V gains a rule against presenting one call where the platform
+  requires two.
+- `README.md` gains a roadmap, an explanation of how BML tokenization actually works, and a
+  backward-compatibility statement.
+
+### Notes
+- Features `001-customers-endpoints`, `002-stored-card-tokens` and `003-transactions-v2` are now
+  **implemented**; `004-token-charge` remains specified, not implemented. `BMLConnect::Client`
+  gains memoized `#customers`/`#tokens` plus `#logger`/`#timeout`/`#max_retries`/`#retry_backoff`
+  accessors with safe defaults. Feature `003` is additive to the released transactions surface:
+  `create`, `get` and `list` keep their 0.2.0 behavior, signature, and `Faraday::Response` return
+  type; the v2 value-object methods sit alongside them.
+- Feature `003` is **not production-ready** until UAT confirms which v2 response field carries the
+  hosted payment URL (`create_v2` may be called but its `payment_url` will raise until then), and
+  until the `msgowl/website` suite is verified to pass unchanged against this gem (release gate).
+- `specs/004-token-charge` is **release-blocked**: it is unconfirmed whether BML's `tokenId`
+  field expects a token's `id` or its `token` value. Charging the wrong identifier is a
+  money-movement defect.
+- No feature has yet been observed against BML UAT. The available API key is rejected there with
+  `PP-C-004` even on the known-working legacy transactions path, so every feature's verification
+  table is open pending a newly issued UAT credential.
+
+## [0.2.0] - 2021-09-17
+
+### Changes
+- Downgraded ruby to >=2.3
+
+## [0.1.0] - 2021-09-16
 
 - Initial release

data/README.md

@@ -3,7 +3,13 @@
 Ruby gem for the Bank of Maldives Connect API
 
 Use this gem to interact with your Bank of Maldives Connect API:
-- 💳 __Transactions__
+- 💳 __Transactions__ (v1, and v2 with tokenization)
+- 👤 __Customers__
+- 🔐 __Stored card tokens__
+- 🔁 __Charging a stored card__
+- 📬 __Transaction-status webhooks__
+
+See [Roadmap](#roadmap) for what has been verified against BML UAT.
 
 
 ## Installation
@@ -24,6 +30,424 @@ Or install it yourself as:
 
 ## Usage
 
+First get your API key and App ID from Merchant Portal for [`production`](https://dashboard.merchants.bankofmaldives.com.mv) or [`sandbox`](https://dashboard.uat.merchants.bankofmaldives.com.mv).
+
+For production client:
+```ruby
+require 'bml_connect`
+
+client = BMLConnect::Client.new(api_key: '<your-api-key>', app_id: '<your-app-id>')
+```
+For sandbox client:
+```ruby
+require 'bml_connect`
+
+client = BMLConnect::Client.new(api_key: '<your-api-key>', app_id: '<your-app-id>', mode: 'sandbox')
+```
+In Ruby on Rails, to configure globally, add an intilializer `bml_connect.rb`:
+```ruby
+module BMLConnect
+  class Client
+    BML_API_KEY = ENV['BML_MPG_KEY']
+    BML_APP_ID = ENV['BML_MPG_APP_ID']
+    BML_MODE = ENV['BML_MPG_MODE']
+  end
+end
+````
+```ruby
+client = BMLConnect::Client.new
+```
+### API Operations
+
+> **Deprecation.** `transactions.create` posts to the legacy, undocumented-but-live
+> `POST /public/transactions` (signed). It still works and its return type is unchanged, but it is
+> **deprecated** in favour of `create_v2`, which targets BML's documented
+> `POST /public/v2/transactions`. The first call in a process logs a one-time deprecation warning.
+
+```ruby
+# DEPRECATED v1 create — still works, returns a Faraday::Response
+resp = client.transactions.create({
+  amount: 10000,
+  currency: 'MVR',
+  redirectUrl: '<your-redirect-uri>',
+  localId: 'local-1',
+  customerReference: 'INV-0001'
+})
+resp = client.transactions.get(id)          # => Faraday::Response
+resp = client.transactions.list({ page: 2 }) # => Faraday::Response
+```
+
+The v1 responses are [`Faraday::Response`](https://github.com/lostisland/faraday/blob/main/lib/faraday/response.rb) objects, `json`-encoded with symbolized names.
+
+#### v2 surface (value objects)
+
+The v2 methods target the documented endpoints, return whitelisted `TransactionRecord` value
+objects, and **raise** on failure. `amount` MUST be a **positive Integer in minor units**
+(`10_000` = MVR 100.00); a Float or String is rejected locally, never coerced.
+
+```ruby
+txn = client.transactions.create_v2(
+  amount:      10_000,          # required — positive Integer, minor units
+  currency:    "MVR",           # required
+  redirectUrl: "https://merchant.example.mv/return",
+  localId:     "INV-0001",
+  customerId:  "cus_123"        # variant 3 (or supply an inline `customer:` — variant 4)
+)
+txn.id
+txn.state                       # passed through verbatim (e.g. "CONFIRMED")
+txn.payment_url                 # hosted page to send the cardholder to (never logged/audited)
+
+client.transactions.retrieve("txn_…")                       # => TransactionRecord (`get` still returns raw)
+client.transactions.update("txn_…", customerReference: "…") # partial merge: customerReference/localData/pnr
+client.transactions.capture("txn_…", amount: 10_000)        # amount obeys the same rule as create
+client.transactions.cancel("txn_…")
+```
+
+Store a card while taking payment by adding `tokenizationDetails`; the token appears under the
+customer (via `client.tokens.list`) only **after** the cardholder completes the payment:
+
+```ruby
+client.transactions.create_v2(
+  amount: 10_000, currency: "MVR", customerId: "cus_123",
+  redirectUrl: "https://merchant.example.mv/return",
+  tokenizationDetails: {
+    tokenize:           true,
+    paymentType:        "RECURRING",   # or "UNSCHEDULED"
+    recurringFrequency: "MONTHLY",     # required when RECURRING
+    expiryDate:         "2027-01-01"   # required when RECURRING; yyyy-mm-dd, future
+  }
+)
+```
+
+Create and capture are **never auto-retried** (no documented idempotency key); retrieve, list,
+update and cancel retry with backoff. Which v2 response field carries the hosted payment URL is
+still being verified against UAT — until then, `payment_url` raises `UnverifiedFieldError` rather
+than returning `nil`, so `create_v2` should not be adopted in production yet.
+
+### Customers
+
+The customers resource wraps BML's `/public-customers` endpoints. Unlike `transactions` (which
+returns a raw `Faraday::Response`), it returns whitelisted value objects and **raises** on
+failure. Reach it through the same configured client:
+
+```ruby
+customer = client.customers.create(name: "Aisha Ali", email: "aisha@example.mv")
+customer.id         # => BML-assigned id, the handle for tokens and charges
+customer.companyId  # => platform-set
+
+client.customers.retrieve(customer.id)                       # => Customer
+client.customers.list.each { |c| puts c.email }              # Enumerable {count, items} envelope
+client.customers.update(customer.id, billingCity: "Male")    # partial merge: only supplied keys sent
+client.customers.archive(customer.id)                        # => true (soft delete; record keeps deleted: true)
+```
+
+Notes:
+
+- **Required on create:** `name` and `email`. Optional documented fields (`billingEmail`,
+  `billingAddress1`, `billingCity`, `billingCountry`, `billingPostCode`, `taxId`, …) pass through
+  unchanged. `email`/`billingEmail` get a lightweight shape check (must contain an `@` and a
+  domain); BML remains the authority beyond that.
+- **Update is a partial merge** (`PATCH`): only the keys you pass are sent — an unset field is
+  never serialized as `null`, so it cannot erase stored data.
+- **No card data.** Every caller-supplied string is screened for a card-number pattern and
+  rejected locally before any request; responses are whitelisted so a stray card field can never
+  reach an object, a log line, or the audit trail.
+- **Auditing.** `create`, `update` and `archive` emit a masked, structured audit line through the
+  client's logger (who / what / when / outcome). Pass an optional `actor:` to attribute the call;
+  reads are not audited. Inject your own logger via `Client.new(options: { logger: my_logger })`.
+- **Errors** are a typed hierarchy under `BMLConnect::Error`: `ValidationError` (carries `#field`),
+  `NotFoundError`, `AuthenticationError`, `ConflictError`, `RateLimitError` (carries
+  `#retry_after`), and `AvailabilityError` (timeouts / 5xx after bounded retries).
+
+### Stored cards (tokens)
+
+The tokens resource wraps BML's `/public-customers/{customerId}/tokens` endpoints. It is
+**read-and-delete only** — list, retrieve, delete — because BML publishes no endpoint that
+creates a token. A stored card comes into existence only as a side effect of a tokenizing
+transaction (feature `003`), completed by the cardholder on BML's hosted page; see
+[How tokenization actually works](#how-tokenization-actually-works). Every path is nested under a
+`customerId`.
+
+```ruby
+# List a customer's saved cards
+client.tokens.list("cus_123").each do |t|
+  puts "#{t.brand} #{t.paddedCardNumber} exp #{t.tokenExpiryMonth}/#{t.tokenExpiryYear}"
+end
+
+client.tokens.retrieve("cus_123", "tok_456")                    # => Token
+client.tokens.delete("cus_123", "tok_456", actor: "ops:jane")   # => true (soft delete)
+```
+
+Notes:
+
+- **No create, no detokenize.** There is deliberately no `client.tokens.create`/`tokenize`/
+  `detokenize` — the absence is enforced by a test. If you are looking for one, tokens are created
+  via feature `003`, not here.
+- **No card data.** No operation accepts a PAN, CVV, expiry, or capture handle. A token is
+  represented only by BML's own fields (`token`, `brand`, `paddedCardNumber`, `tokenExpiryMonth`,
+  `tokenExpiryYear`, …); the gem invents no `last_four`/`scheme` alias and exposes no full card
+  number. Responses are whitelisted, so a stray card field can never reach an object, log, or audit
+  record.
+- **Empty vs. broken.** An empty token list is an empty `TokenList`, never an error, and an
+  authentication failure is never swallowed into one.
+- **Auditing.** Only `delete` is audited (reads are not); it emits a single masked audit line —
+  once, even if the delete is retried. Pass an optional `actor:` (screened for card data) to
+  attribute it.
+- **Retries.** Transient failures (`429`, `408`, timeouts, `5xx`) are retried on all three
+  operations — delete included, since soft-delete is idempotent — with bounded backoff, then raised
+  as `RateLimitError`/`AvailabilityError`. Tune via `Client.new(options: { max_retries: 2,
+  retry_backoff: 0.5 })`; set `max_retries: 0` to disable. A `429`'s `Retry-After` is surfaced on
+  `RateLimitError#retry_after`.
+
+### Charging a stored card
+
+Once a customer has a stored card (a token), you can take a payment from it with no cardholder
+present — a subscription renewal, an account top-up, an ad-hoc charge. It is a **two-call flow**,
+and the gem keeps it that way on purpose: BML has no single endpoint that creates a transaction
+and charges it, so this gem offers none either (a hidden combined call would obscure a money
+movement). The **amount lives on the transaction**, not on the charge.
+
+```ruby
+# 1 ── create the transaction to be charged (the amount lives HERE)
+renewal = client.transactions.create_v2(
+  amount: 10_000, currency: "MVR",       # MVR 100.00, in minor units
+  customerId: "cus_123", localId: "SUB-2026-10"
+)
+
+# 2 ── charge the stored card against it
+charged = client.customers.charge(
+  customer_id:    "cus_123",
+  transaction_id: renewal.id,
+  token_id:       "tok_789",             # the stored card's Token#id
+  actor:          "billing:cron"          # optional, for the audit "who"
+)
+
+charged.state    # resolved synchronously — no cardholder redirect
+```
+
+Notes:
+
+- **Returned vs. raised.** A **returned** `TransactionRecord` means BML answered — inspect
+  `charged.state` for the business outcome (a decline is a returned record, not an exception). A
+  **raised** error means BML did not answer. The gem never converts one into the other, so a
+  declined card and a network outage are always distinguishable.
+- **Never auto-retried.** The charge schema carries no idempotency key, so a retry could take
+  payment twice. Exactly one HTTP attempt is made. On a timeout, an `AvailabilityError` is raised
+  whose message **names the `transaction_id`** — reconcile by retrieving that transaction
+  (`client.transactions.retrieve(id)`) rather than re-charging blindly.
+- **No `amount` on the charge.** To bill a different amount, create a different transaction.
+- **Audited, failures included.** Every charge emits a masked audit line — success, decline,
+  validation failure, and availability failure alike — carrying the transaction and token ids and
+  never any card data.
+- **`token_id` is `Token#id`.** Confirmed in BML UAT: a charge against `Token#id` returns `CONFIRMED`.
+
+### Receiving transaction-status webhooks
+
+BML can notify your application when a transaction's status changes. The published contract
+documents how to *register* a hook URL and **nothing at all** about the notification it sends — no
+payload schema, no event list, and no signature, secret, or authentication. So this handler never
+trusts the delivery: it reads one field (which transaction) and takes every consequential fact from a
+fresh retrieve.
+
+Framework-agnostic by design — the gem is handed a body and returns a value object. It adds **no web
+framework dependency**, owns no route, and never writes a response.
+
+```ruby
+# config/routes.rb → post "/bml/notify" => "bml#notify"
+
+def notify
+  result = BML.client.webhooks.handle(
+    body:    request.body.read,
+    headers: request.env                    # Rails request.headers works too
+  )
+
+  Order.find_by!(transaction_id: result.transaction_id)
+       .apply_bml_status(result.status)     # ← authoritative, from BML
+
+  head result.advisory_http_status          # 200
+rescue BMLConnect::Error => e
+  head e.advisory_http_status || 500        # 4xx = stop; 503 = please redeliver
+end
+```
+
+**The status never comes from the payload.** A forged "payment confirmed" posted to your public
+endpoint cannot ship goods: the library retrieves the transaction and reports what BML says. There is
+no flag that turns this off — `handle(verify: false)` raises `ArgumentError`, because the option does
+not exist.
+
+```ruby
+result.status          # authoritative, retrieved fresh from BML — verbatim, never coerced
+result.claimed_status  # what the delivery claimed. Diagnostic only. Never act on it.
+result.disagreed?      # they differed → a replay, a read-path lag, or a forgery
+result.transaction     # BMLConnect::Models::TransactionRecord
+```
+
+Expect states this gem has never heard of: the published contract enumerates none, so nothing is
+coerced or rejected. Treat `result.status` as **current-as-of-retrieve**, not final.
+
+#### What to return to BML
+
+Every result and error carries `advisory_http_status`. It is advice — the library never writes a
+response and does not require you to honor it.
+
+| Outcome | Advisory | Meaning to the sender |
+|---|---|---|
+| Accepted | `200` | done |
+| Malformed / empty / unparseable body | `400` | permanent — do not redeliver |
+| Secret absent or wrong | `401` | permanent |
+| No identifier extractable | `422` | permanent |
+| Transaction does not exist | `422` | permanent |
+| BML unreachable, timeout, 5xx, rate limited | `503` | **transient — please redeliver** |
+| Our API key rejected | `503` | transient |
+
+`404` is never advised. A missing transaction gets `422` instead: `404` from an HTTP endpoint reads as
+"no such endpoint", and a sender that decides your hook URL is gone may stop delivering — turning one
+forged identifier into an outage for every genuine notification after it.
+
+#### Configuration
+
+```ruby
+BMLConnect::Client.new(
+  api_key: ENV.fetch("BML_API_KEY"),
+  options: {
+    webhook_secret:        ENV["BML_WEBHOOK_SECRET"],  # optional
+    webhook_recheck_delay: 3                           # seconds; 0 disables the re-check
+  }
+)
+```
+
+**`webhook_secret` gates spend, not trust.** With one configured, a delivery whose presented value is
+absent or wrong is rejected before any retrieve is spent. A match never causes the payload to be
+believed and never skips the retrieve — the same notification reports an identical status either way.
+
+You extract the value; the library only compares it (in constant time). It never guesses where the
+secret travels and never asks for the request URL. BML controls the callback's headers, so in practice
+a secret can only ride in the URL you registered:
+
+```ruby
+# registered hook URL: https://you.example/bml/notify?t=SECRET
+BML.client.webhooks.handle(body: body, headers: headers, presented_secret: params[:t])
+```
+
+> Enabling a secret on an existing hook? Re-register or update the URL **first**. Deliveries with
+> nothing to present are rejected, and legitimate notifications drop silently until you do.
+
+**`webhook_recheck_delay` is spent inside your request.** When the payload's claimed status disagrees
+with the first retrieve, the library waits (default **3 seconds**) and retrieves once more — BML's read
+path may lag the event that fired the callback. **If your endpoint's response deadline is at or below
+3 seconds, set this to `0`**; a sender that times out will redeliver, turning a latency problem into a
+replay problem. The cost lands on every disagreeing delivery, including every replay.
+
+At most **two** retrieves per notification, neither auto-retried. Nothing a payload claims produces a
+third.
+
+#### Limits you own, not the gem
+
+- **Request size.** The library enforces **no** body size or nesting limit and parses whatever you
+  hand it — it does not own the socket, so a limit it invented would be the wrong one. Bound it at
+  your web server (`client_max_body_size`, a Rack middleware).
+- **Every request costs a retrieve** when no secret is configured. Your endpoint is public;
+  protecting it is yours.
+- **Deduplication and ordering.** The gem owns no datastore and deduplicates nothing. Deliveries are
+  at-least-once and possibly out of order; `result.transaction_id` is surfaced so you can key on it.
+  Handling the same delivery twice produces equal results against an unchanged record, with no side
+  effect beyond the retrieve.
+- **Registration.** `POST/DELETE /public/webhooks` are not implemented. Register through the merchant
+  portal, or per-transaction via `webhook:` on `create_v2`.
+
+If a notification never arrives, reconcile directly — no webhook needed:
+
+```ruby
+BML.client.transactions.retrieve(transaction_id).state
+```
+
+#### When the built-in field names are wrong
+
+The identifier is looked for under `transactionId`, `transaction_id`, then `id` (top-level keys only).
+BML UAT deliveries carry `transactionId`, so the defaults work. If your deliveries differ, say so and
+the library will not second-guess you:
+
+```ruby
+BML.client.webhooks.handle(
+  body: body, headers: headers,
+  extract_id: ->(payload, headers) { payload.dig(:transaction, :id) }
+)
+```
+
+The callable receives the parsed payload and the normalized headers — headers included so an
+identifier arriving outside the body does not block you. Return `nil` for "not found" and you get the
+same loud `ValidationError` as an exhausted list, with no remote call.
+
+Bodies are accepted as JSON or form-encoded, selected by `Content-Type` (with a documented fallback
+when it is absent). Header names are normalized for you, so `request.env`, `request.headers`, and a
+plain hash all work.
+
+> **Observed in UAT.** `NOTIFY_TRANSACTION_CHANGE` and `NOTIFY_TOKENISATION_STATUS` deliveries both
+> carry a top-level `transactionId`. A wrong guess would still fail loudly rather than report a false
+> status. See [`specs/005-webhook-handler/`](specs/005-webhook-handler/).
+
+## Roadmap
+
+Tokenization support lives in this gem. It was previously being built as a separate
+`bml_tokenization` gem, which turned out to have been specified against an assumed API contract
+that does not match BML's published one.
+
+Work is now spec-driven against BML's own OpenAPI document, vendored at
+[`reference/Connect-API.json`](reference/Connect-API.json). Where this library and that document
+disagree, the document wins.
+
+| Feature | Endpoints | Status |
+|---|---|---|
+| [`001-customers-endpoints`](specs/001-customers-endpoints/) | `/public-customers` | Implemented, verified in UAT |
+| [`002-stored-card-tokens`](specs/002-stored-card-tokens/) | `/public-customers/{id}/tokens` | Implemented, verified in UAT |
+| [`003-transactions-v2`](specs/003-transactions-v2/) | `/public/v2/transactions` | Implemented, verified in UAT (payment-URL key not pinned) |
+| [`004-token-charge`](specs/004-token-charge/) | `/public-customers/charge` | Implemented, verified in UAT (decline path unobserved) |
+| [`005-webhook-handler`](specs/005-webhook-handler/) | inbound callback + `/public/transactions/{id}` | Implemented, verified in UAT |
+
+Each feature directory carries a `spec.md`, `plan.md`, `research.md`, `data-model.md`, `tasks.md`
+and two contracts — one for the BML HTTP surface, one for the Ruby surface this gem exposes.
+
+### How tokenization actually works
+
+Worth stating up front, because it is not what most payment APIs do: **there is no endpoint that
+creates a token.** A stored card comes into existence as a side effect of a transaction that
+carries `tokenizationDetails`, completed by the cardholder on BML's hosted page. Later charges
+are a two-step flow — create a transaction, then charge it against the stored token.
+
+```
+create customer  ─►  create transaction with tokenizationDetails  ─►  cardholder pays
+                                                                          │
+                     charge stored token  ◄──  token now listed  ◄────────┘
+```
+
+### Backward compatibility
+
+The transactions methods documented above are **not changing**. `create`, `get` and `list` keep
+their current endpoints, signatures and `Faraday::Response` return type. New capabilities arrive
+under new method names.
+
+`transactions.create` will be marked **deprecated** in favour of a `create_v2` targeting BML's
+documented `/public/v2/transactions`, but it will continue to work — it is live and carries
+production traffic today.
+
+## Contributing to the specs
+
+This repository uses [Spec Kit](https://github.com/github/spec-kit). The active feature is
+tracked in `.specify/feature.json`:
+
+```bash
+./speckit-feature            # show the active feature and the status of each
+./speckit-feature 002        # switch the active feature
+```
+
+The project constitution is at [`.specify/memory/constitution.md`](.specify/memory/constitution.md).
+Two rules matter most for anyone adding a remote call:
+
+1. **A stubbed test is not evidence that an endpoint exists.** Every path must be traceable to
+   `reference/Connect-API.json`, and stub URLs must derive from the client's base URL rather than
+   being hardcoded.
+2. **Anything not in the published document is marked `[UNVERIFIED]`** and must be confirmed
+   against UAT before it is relied on.
 
 ## Development