@vaam-apps/vpay-sdk 0.2.1

package/README.md

@@ -0,0 +1,732 @@
+# @vaam-apps/vpay-sdk
+
+The Node.js merchant SDK for vpay's `/v1` API. Implements the wire contract in
+[`docs/flows/merchant-auth.md`](../../docs/flows/merchant-auth.md) exactly —
+`private_key_jwt` client assertions, `client_credentials` token exchange and
+caching, the form-encoded resource calls, and outbound-webhook verification.
+
+**Not yet on the registry.** `npm view @vaam-apps/vpay-sdk` answered `E404` on
+2026-09-05 and no workflow in this repository publishes anything. What changed
+on that date is only that the manifest stopped saying `"private": true`, so a
+release can happen without editing it; the release workflow that would do the
+publishing does not exist yet. See "Status" below for what the server it talks
+to actually serves.
+
+## Install
+
+Inside this workspace:
+
+```bash
+pnpm --filter @vaam-apps/vpay-sdk build
+```
+
+From a registry, once a release workflow exists and has run:
+
+```bash
+pnpm add @vaam-apps/vpay-sdk   # not yet published — see above
+```
+
+Requires Node.js `>=22.11.0`.
+
+## The handshake, in prose
+
+`/v1` never accepts an API key ([ADR-0010](../../docs/adr/0010-merchant-auth-private-key-jwt.md)).
+Every merchant is a statically registered OAuth2 client authenticating with
+`client_credentials` (RFC 6749 §4.4) via a signed `private_key_jwt` assertion
+(RFC 7523). Concretely:
+
+1. **Mint an assertion.** The SDK signs a short-lived RS256 JWT with your
+   private key: `iss`/`sub` are your `client_id`, `aud` is the OP's own token
+   endpoint (see `assertionAudience`), `jti` is a fresh UUIDv4, and `exp` is
+   `now + assertionLifetimeSeconds` (default 60s, capped at 300s — the OP
+   refuses anything further out).
+2. **Exchange it for an access token.** The SDK `POST`s the assertion to the
+   token endpoint alongside `grant_type=client_credentials` and
+   `audience=vpay:v1`. No `client_secret` is ever sent — there is nothing to
+   send; vpay stores only your **public** key.
+3. **Call `/v1` with the token.** Every resource call carries
+   `Authorization: Bearer <access_token>`. The SDK caches the token until
+   shortly before it expires and reuses it across calls; concurrent calls
+   share one in-flight token request.
+4. **Re-authenticate on expiry or a 401.** There is no refresh token by
+   design. On a `401` from a resource route, the SDK discards the cached
+   token, repeats steps 1–2 once, and retries the original request exactly
+   once. A second `401` is returned to you as a `VpayApiError`.
+
+## Usage
+
+```ts
+import { readFileSync } from "node:fs";
+import { VpayClient } from "@vaam-apps/vpay-sdk";
+
+const vpay = new VpayClient({
+  baseUrl: "https://api.vpay.example",
+  clientId: "merchant_a",
+  privateKey: readFileSync("./merchant_a.key.pem", "utf8"),
+});
+
+const intent = await vpay.paymentIntents.create(
+  {
+    amount: 5000, // 5,000 FCFA — XAF is zero-decimal, see docs/flows/money.md
+    currency: "xaf",
+    payment_method_types: ["mtn_momo"],
+    metadata: { order_id: "1234" },
+  },
+  { idempotencyKey: "order_1234_attempt_1" },
+);
+
+console.log(intent.id, intent.status); // pi_..., "requires_payment_method"
+
+const confirmed = await vpay.paymentIntents.confirm(intent.id, {
+  payment_method_data: {
+    type: "mtn_momo",
+    mtn_momo: { msisdn: "237670000000" },
+  },
+});
+
+// `processing` means NOT YET. Wait for a payment_intent.succeeded webhook,
+// or poll retrieve(). There is no `failed` status — see payment-lifecycle.md.
+console.log(confirmed.status);
+
+// Orange Money is a redirect rail:
+const redirectConfirm = await vpay.paymentIntents.confirm(intent.id, {
+  payment_method_data: { type: "orange_money" },
+  return_url: "https://shop.example/return",
+});
+if (redirectConfirm.next_action?.type === "redirect_to_url") {
+  // redirect the payer's browser to redirectConfirm.next_action.redirect_to_url.url
+}
+
+await vpay.paymentIntents.retrieve(intent.id);
+await vpay.paymentIntents.cancel(intent.id);
+await vpay.paymentIntents.list({ limit: 10 });
+
+await vpay.refunds.create({
+  payment_intent: intent.id,
+  reason: "requested_by_customer",
+});
+await vpay.events.list({ type: "payment_intent.succeeded", limit: 20 });
+await vpay.balance.retrieve();
+
+// Checkout Sessions (Step 9). A session references an intent you already
+// created; it never creates one, and it carries where the payer goes next.
+const hosted = await vpay.checkout.sessions.create({
+  payment_intent: intent.id,
+  ui_mode: "hosted",
+  // vpay substitutes {CHECKOUT_SESSION_ID} when it forwards the payer, and
+  // appends nothing else. Omit it and the return has no correlation.
+  success_url: "https://shop.example/ok?sid={CHECKOUT_SESSION_ID}",
+  cancel_url: "https://shop.example/cancel",
+});
+// Send the payer to hosted.url — the session secret is in its fragment.
+
+const embedded = await vpay.checkout.sessions.create({
+  payment_intent: intent.id,
+  ui_mode: "embedded",
+  return_url: "https://shop.example/order/42",
+});
+// Hand embedded.client_secret to @vaam-apps/vpay-stripe-js's initEmbeddedCheckout.
+
+await vpay.checkout.sessions.retrieve(hosted.id);
+await vpay.checkout.sessions.list({ payment_intent: intent.id, limit: 10 });
+await vpay.checkout.sessions.expire(hosted.id); // open -> expired
+```
+
+`create()` and `retrieve()` responses carry a `client_secret` (`intent.client_secret`,
+typed `string | undefined`) — the payer credential `/v1/browser` accepts for a
+browser-side confirm. Hand it straight to `@vaam-apps/vpay-stripe-js` on the page you
+render for the payer; never log it or send it anywhere but the browser. It is
+the one field on `PaymentIntent` that is genuinely absent — not `null` — from
+every other response shape: a `list()` item and `event.data.object` never
+carry it, so a merchant's own listing view or a stored/forwarded webhook body
+never receives a live payer credential for intents it did not just create.
+
+A Checkout Session's own `client_secret` (`cs_…_secret_…`) is a **different**
+credential from the intent's: it authorises reading that session, never
+confirming the intent. Like the intent's, it is present on `create()` and
+`retrieve()` only and absent from every `list()` item. Unlike the intent's, it
+does not print: every `CheckoutSession` this SDK returns redacts it — and the
+fragment of a hosted session's `url`, which holds the same value — from
+`util.inspect`, so `console.log(session)` cannot leak it. `JSON.stringify` is
+left faithful, because an embedded integration has to serialise the secret to
+get it to the browser at all.
+
+## Configuration
+
+| Option                     | Default               | Notes                                                                                                                                                                                                                                                                                        |
+| -------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`                  | —                     | Required, e.g. `https://api.vpay.example`.                                                                                                                                                                                                                                                   |
+| `clientId`                 | —                     | Required. Your registered OAuth2 `client_id`.                                                                                                                                                                                                                                                |
+| `privateKey`               | —                     | Required. PEM text or a `crypto.KeyObject`. Never logged, never serialized.                                                                                                                                                                                                                  |
+| `kid`                      | —                     | Required only if you registered more than one JWK.                                                                                                                                                                                                                                           |
+| `issuer`                   | `${baseUrl}/v1/oauth` | This default is what the server does: `vpay_api::op::issuer_for` builds the issuer as `{public_base_url}/v1/oauth` from the deployment YAML, and `vpay_api::router` mounts the OP there. Override only for a deployment behind a path prefix.                                                |
+| `tokenEndpoint`            | `${issuer}/token`     | The URL this package POSTs the token request to. A **reachability** setting: it must resolve from wherever your server runs. It is also the default `assertionAudience`, but the two are separate settings — see the row below.                                                              |
+| `assertionAudience`        | `tokenEndpoint`       | The client assertion's `aud` claim: the OP's own token endpoint (or issuer) **as vpay is configured publicly** — `{deployment.public_base_url}/v1/oauth/token`. Set it when your server reaches vpay by a different URL than payers do. See "Reaching vpay by an internal URL" below.        |
+| `audience`                 | `vpay:v1`             | The OAuth2 `audience` request parameter. Load-bearing: without it the OP mints a token whose `aud` is the `client_id`, which the resource server rejects. Server-side the same string is `vpay_config::MERCHANT_AUDIENCE`; this package keeps its own copy, so the two must change together. |
+| `scope`                    | —                     | Omitted from the token request unless set.                                                                                                                                                                                                                                                   |
+| `assertionLifetimeSeconds` | `60`                  | Must be an integer in `1..=300`; anything else throws `VpayConfigError` at construction, not at request time. Keep the default — see the note below the table.                                                                                                                               |
+| `timeoutMs`                | `30000`               | Applies to both the token exchange and every resource call.                                                                                                                                                                                                                                  |
+| `fetch`                    | global `fetch`        | Injection point for tests or an outbound proxy.                                                                                                                                                                                                                                              |
+
+**Do not raise `assertionLifetimeSeconds` to 300.** 300 is not a comfortable
+maximum, it is the OP's exact refusal boundary
+(`MAX_CLIENT_ASSERTION_LIFETIME_SECS`), and the OP compares it against _its_
+clock. A merchant clock running even one second fast mints an `exp` the OP
+reads as 301 seconds out, and every assertion is refused — the failure looks
+like `invalid_client`, arrives all at once, and clears up on its own when the
+clocks drift back. The default of 60 leaves 240 seconds of headroom for a
+value that only has to outlive one HTTP round trip.
+
+### Reaching vpay by an internal URL
+
+Two things look like one and are not:
+
+- **`tokenEndpoint`** — where this process sends the HTTP request. It has to
+  be reachable from _your_ server: a compose service name, a private DNS
+  name, a service-mesh address.
+- **`assertionAudience`** — what the OP calls _itself_. The OP's
+  `authenticate_client` compares the assertion's `aud` claim against its own
+  two names, `{deployment.public_base_url}/v1/oauth/token` and
+  `{deployment.public_base_url}/v1/oauth`, and against nothing else. The URL
+  you happened to POST to is never consulted.
+
+They coincide for a merchant on the public internet, which is why
+`assertionAudience` defaults to `tokenEndpoint`. They do not coincide the
+moment your server reaches vpay by an internal name, and then every token
+request answers `invalid_client` (`InvalidAudience`) with nothing in the
+response pointing at the cause — the signature, the `client_id`, the `kid`
+and the lifetime are all correct.
+
+```ts
+// The demo stack: the shop's container reaches vpay at the compose service
+// name, but vpay's `deployment.public_base_url` is the published host port.
+const vpay = new VpayClient({
+  baseUrl: "http://vpay-server:8080",
+  assertionAudience: "http://localhost:8080/v1/oauth/token",
+  clientId: "shop-merchant",
+  privateKey,
+});
+```
+
+The issuer works too — `http://localhost:8080/v1/oauth` — because the OP
+accepts either.
+
+## Error handling
+
+Every error extends `VpayError`, so `catch (err) { if (err instanceof VpayError) ... }`
+works as a catch-all; narrow further with `instanceof` on a specific subclass:
+
+| Class                         | When                                                                                                                                                                                                                                                                                                                       | Fields                                       |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `VpayApiError`                | A non-2xx response from a `/v1` resource route.                                                                                                                                                                                                                                                                            | `status`, `type`, `code`, `message`, `param` |
+| `VpayAuthError`               | A `400`/`401` from the token endpoint (`invalid_client`, etc). Never retried.                                                                                                                                                                                                                                              | `error`, `errorDescription`                  |
+| `VpayUnexpectedResponseError` | A response that isn't the shape this SDK expects — a proxy's HTML 502, an empty body, or a token-endpoint 200 that is not `{ access_token, token_type: "Bearer", expires_in }` (a non-`Bearer` `token_type` lands here, not in `VpayAuthError`: nothing failed to authenticate, the SDK simply cannot present that token). | `status`, `bodyPrefix` (first 500 bytes)     |
+| `VpayTransportError`          | DNS, TLS, connection refused, timeout.                                                                                                                                                                                                                                                                                     | `cause` (the underlying error)               |
+| `VpayConfigError`             | The SDK was misconfigured — caught at construction where possible.                                                                                                                                                                                                                                                         | —                                            |
+| `WebhookSignatureError`       | `verifyWebhook` rejected a signature.                                                                                                                                                                                                                                                                                      | —                                            |
+
+```ts
+import { VpayApiError, VpayAuthError, VpayError } from "@vaam-apps/vpay-sdk";
+
+try {
+  await vpay.paymentIntents.create({
+    amount: 5000,
+    currency: "xaf",
+    payment_method_types: ["mtn_momo"],
+  });
+} catch (err) {
+  if (err instanceof VpayApiError) {
+    console.error(err.status, err.type, err.code, err.message, err.param);
+  } else if (err instanceof VpayAuthError) {
+    console.error("authentication failed:", err.error, err.errorDescription);
+  } else if (err instanceof VpayError) {
+    console.error(err.name, err.message);
+  }
+}
+```
+
+`VpayApiError` is one class for every error envelope: the envelope's `type`
+is a _field_, not a subclass. Branch on `code`, which is what the server
+treats as the machine-readable answer — two idempotency errors share a status
+(`400`) and a `type` (`idempotency_error`) and mean opposite things:
+
+```ts
+if (err instanceof VpayApiError) {
+  if (err.code === "idempotency_key_in_flight") {
+    // The first request under this key has not finished. Wait, then send
+    // the same call again — do not mint a new key.
+  } else if (err.code === "idempotency_key_in_use") {
+    // The key was already used with a different body. Retrying cannot help.
+  }
+}
+```
+
+## Webhook verification
+
+```ts
+import { createServer } from "node:http";
+import { verifyWebhook, WebhookSignatureError } from "@vaam-apps/vpay-sdk";
+
+// Read the secret once, at startup, so a misconfigured deployment fails
+// loudly instead of rejecting every delivery as a bad signature. Under
+// `noUncheckedIndexedAccess` this is `string | undefined` until you narrow it.
+const webhookSecret = process.env["VPAY_WEBHOOK_SECRET"];
+if (webhookSecret === undefined) {
+  throw new Error("VPAY_WEBHOOK_SECRET is not set");
+}
+
+createServer((req, res) => {
+  let raw = "";
+  req.on("data", (chunk: Buffer) => (raw += chunk.toString("utf8")));
+  req.on("end", () => {
+    // `IncomingHttpHeaders` types every header as `string | string[]`, because
+    // a header may legitimately be repeated. A repeated `Vpay-Signature` is
+    // not something vpay sends, and joining or picking one arbitrarily would
+    // verify against bytes nobody promised — so reject it.
+    const header = req.headers["vpay-signature"];
+    if (typeof header !== "string") {
+      res.writeHead(400).end("missing or repeated Vpay-Signature");
+      return;
+    }
+
+    let event;
+    try {
+      // The RAW request body must be used — parsing and re-stringifying it
+      // breaks the HMAC. Do not run a body-parsing middleware before this.
+      event = verifyWebhook({
+        rawBody: raw,
+        signatureHeader: header,
+        secret: webhookSecret,
+      });
+    } catch (err) {
+      if (err instanceof WebhookSignatureError) {
+        res.writeHead(400).end("bad signature");
+        return;
+      }
+      throw err;
+    }
+
+    // Delivery is at-least-once. verifyWebhook does not dedupe by event.id —
+    // that is your job. Keep a set (or a unique DB constraint) of processed
+    // event.id values and skip anything you've already handled.
+    console.log("event", event.id, event.type);
+    res.writeHead(200).end("ok");
+  });
+}).listen(4242);
+```
+
+## Using the official Stripe SDK
+
+vpay's `/v1` surface is Stripe-shaped, and the official
+[`stripe`](https://www.npmjs.com/package/stripe) Node SDK can talk to it —
+with an **empty API key** and a `config.authenticator` that performs the
+`private_key_jwt` handshake above. `@vaam-apps/vpay-sdk/stripe` is that authenticator:
+
+```js
+import { readFileSync } from "node:fs";
+import Stripe from "stripe";
+import { createStripeAuthenticator } from "@vaam-apps/vpay-sdk/stripe";
+
+const authenticator = createStripeAuthenticator({
+  baseUrl: "http://localhost:8080",
+  clientId: "acme-cameroon",
+  privateKey: readFileSync("./merchant-key.pem", "utf8"),
+  kid: "acme-cameroon-2026-08",
+});
+
+const stripe = new Stripe("", {
+  authenticator,
+  host: "localhost",
+  port: "8080",
+  protocol: "http",
+  maxNetworkRetries: 2,
+  timeout: 30_000,
+  telemetry: false,
+});
+
+const intent = await stripe.paymentIntents.create({
+  amount: 5000,
+  currency: "xaf",
+  payment_method_types: ["mtn_momo"],
+});
+```
+
+`host`, `port` and `protocol` are not optional. The authenticator is bound to
+`baseUrl`'s origin: a request addressed anywhere else throws `VpayConfigError`
+before a token is minted. Omit them and stripe-node addresses
+`api.stripe.com:443`, which is exactly the case this refusal exists to stop.
+Behind a reverse proxy, or on split-horizon DNS, set `baseUrl` to the origin
+this client actually connects to rather than the public one — both the token
+exchange and the binding follow `baseUrl`, so a mismatch either mints the
+token against an unreachable endpoint or refuses every request as addressed
+elsewhere.
+
+`stripe` is an **optional peer dependency** of this package: install it
+yourself if you want this entry point, and `@vaam-apps/vpay-sdk`'s core entry never
+imports it. This package itself still has **zero runtime dependencies**.
+
+The empty first argument is not a trick — stripe-node's `_setAuthenticator`
+refuses only _both_ an API key and an authenticator, or _neither_. The token
+cache, its single-flight refresh and its `expires_in` safety margin are the
+same ones `VpayClient` uses, not a second implementation.
+
+`authenticator.invalidate()` discards the cached token. You need it because an
+authenticator runs _before_ a request and its promise settles before any
+status code exists — it cannot see a `401` and re-auth the way `VpayClient`
+does:
+
+```js
+try {
+  await stripe.paymentIntents.retrieve(id);
+} catch (err) {
+  if (err instanceof Stripe.errors.StripeAuthenticationError) {
+    authenticator.invalidate();
+  }
+  throw err;
+}
+```
+
+### Where vpay diverges from Stripe
+
+- **No API keys, ever.** `sk_live_…` means nothing here; authentication is the
+  OAuth2 `client_credentials` + `private_key_jwt` handshake above
+  ([ADR-0010](../../docs/adr/0010-merchant-auth-private-key-jwt.md)). There is
+  no publishable key and no Connect equivalent.
+- **`Idempotency-Key` is mandatory on every `/v1` POST**, not optional as at
+  Stripe. This costs you nothing: stripe-node puts a
+  `stripe-node-retry-<uuid>` key on every v1 POST unconditionally — _including_
+  when `maxNetworkRetries` is `0`. Pass your own with
+  `{ idempotencyKey: "order_1234_attempt_1" }` when you want the retry window
+  to span more than one process.
+- **XAF and EUR only.** XAF is zero-decimal: `amount: 5000` is 5,000 FCFA, not
+  50.00 (see [docs/flows/money.md](../../docs/flows/money.md)).
+- **`payment_method_types` is required and non-empty**, and must name an
+  enabled vpay rail. A copy-pasted `automatic_payment_methods: { enabled: true }`
+  gets a `400` naming `payment_method_types`.
+- **No `confirm: true` on create, no `search`, no Connect.** Confirm with a
+  second call to `stripe.paymentIntents.confirm(id, …)`: `confirm: true` on
+  create is **refused** with `param: "confirm"` and a message naming the
+  confirm route. `stripe.paymentIntents.search(…)` and every `stripeAccount` /
+  Connect parameter have no vpay counterpart.
+- **The fields that decide where or when money moves are refused, not
+  ignored.** `capture_method` with any value other than `automatic`,
+  `application_fee_amount`, `transfer_data` and `on_behalf_of` come back as a
+  `400` naming the field in `error.param`. vpay has no authorise-now /
+  capture-later split — confirming _is_ the charge — and no Connect, so
+  ignoring any of them would move a merchant's money somewhere, or at a time,
+  they did not ask for and could not see in the response.
+
+  Everything else Stripe sends and vpay does not implement is **accepted and
+  ignored**, because none of it changes that: `setup_future_usage`,
+  `confirmation_method`, `receipt_email`, `statement_descriptor`, `customer`,
+  `expand` and `metadata` (`metadata` is actually stored) all leave the
+  payment exactly as requested. Nothing is expandable, so an `expand` request
+  simply produces no expanded field — visible in the response itself.
+
+- **Rail codes are vpay's, not Stripe's.** `payment_method_types` entries and
+  `payment_method_data.type` are `mtn_momo` / `orange_money`; stripe-node's
+  TypeScript types enumerate Stripe's own rails and reject them, so a cast is
+  needed at those call sites — the values are right, the _type_ is Stripe's:
+
+  ```ts
+  await stripe.paymentIntents.confirm(id, {
+    payment_method_data: {
+      type: "mtn_momo",
+      mtn_momo: { msisdn: "237670000000" },
+    },
+  } as unknown as Stripe.PaymentIntentConfirmParams);
+  ```
+
+- **`429` is never emitted.** Nothing in vpay constructs a rate-limit
+  category, so `Stripe.errors.StripeRateLimitError` cannot occur. Do not build
+  a backoff path around it.
+- **`client_secret` is present, but only on `create`/`retrieve`.** vpay's
+  `create()` and `retrieve()` responses carry it — see "Usage" above — for
+  `@vaam-apps/vpay-stripe-js`'s browser-side confirm flow. `amount_received`,
+  `capture_method` and `confirmation_method` stay genuinely absent, though:
+  stripe-node's TypeScript types declare all three as present on every
+  response shape — it casts responses, it never validates them — so these
+  read as `undefined` at runtime while the type says otherwise, on every
+  route including `create`/`retrieve`.
+- **`Stripe-Version`, `Stripe-Account`, `Stripe-Context` and the
+  `X-Stripe-Client-*` headers are accepted and ignored.** vpay advertises no
+  dated API version, so `obj.lastResponse.apiVersion` is `undefined` and
+  pinning `apiVersion` has no effect.
+
+### Webhooks
+
+vpay signs outbound deliveries with the same construction Stripe uses —
+`t=<unix>,v1=<lowercase hex HMAC-SHA256 of "<t>.<raw body>">` — so
+`stripe.webhooks.constructEvent(rawBody, header, secret)` verifies a vpay
+delivery byte for byte. Read the header value, not the request object, and
+give it the **raw** body:
+
+```js
+const event = stripe.webhooks.constructEvent(
+  rawBody,
+  req.headers["stripe-signature"],
+  process.env.VPAY_WEBHOOK_SECRET,
+);
+```
+
+**Either header works, and that snippet is observed rather than argued.**
+`vpay_worker`'s deliverer sends `Vpay-Signature` and `Stripe-Signature`
+carrying the same string, byte for byte, and
+`sdks/stripe-compat`'s `webhooks.compat.test.ts` takes a delivery out of a
+WireMock receiver's request journal and puts it through
+`stripe.webhooks.constructEvent` exactly as written above — then requires the
+same call to throw `StripeSignatureVerificationError` for a body with one byte
+flipped and for the right body with the wrong secret.
+
+`Stripe-Signature` exists only so that a copy-pasted Stripe recipe needs no
+edit at all. Code written from scratch should read the authoritative name
+instead — the same call, one word changed, verifying the same bytes:
+
+```js
+const event = stripe.webhooks.constructEvent(
+  rawBody,
+  req.headers["vpay-signature"],
+  process.env.VPAY_WEBHOOK_SECRET,
+);
+```
+
+**`Vpay-Signature` is the authoritative name** whatever else is added beside
+it — prefer it in code you write from scratch, and use this package's own
+`verifyWebhook` if you are not otherwise using stripe-node.
+
+### A stripe-node defect you will hit if your key is wrong
+
+**Measured against `stripe@22.6.1`, not inferred.** When the vpay handshake
+fails — a bad key, an unregistered `client_id`, vpay unreachable — the
+authenticator rejects, as it must. stripe-node builds the right error from it
+(`StripeError: Unable to authenticate the request`, with the underlying
+`VpayAuthError` at `err.raw.exception`) but **throws it inside a detached
+promise chain that never calls its own callback**. The result: the error
+arrives as a process-level `unhandledRejection`, and the promise you awaited
+**never settles at all** — not even after `timeout`, because no HTTP request
+was ever started for a timeout to fire against.
+
+Two of the ways a key can be wrong no longer reach that path at all. A
+`privateKey` that `node:crypto` cannot read, and a `baseUrl` that is not an
+absolute URL, are both `VpayConfigError` thrown by `createStripeAuthenticator`
+**at construction** — before a `Stripe` instance exists, on the line the
+merchant wrote. What is left for the warning below is the set of failures only
+the OP can report: an unregistered `client_id`, a key whose public half vpay
+does not hold, a clock too far out, vpay unreachable.
+
+Until stripe-node fixes this, do not rely on `try`/`catch` around a call to
+surface a handshake failure. Two things that do work:
+
+- **Verify the handshake at startup**, where a rejection is yours to catch.
+  The authenticator is a plain function, so call it once against a throwaway
+  request object and let it throw before you serve traffic — a `VpayAuthError`
+  there names the OAuth2 reason (`invalid_client`, …) directly:
+
+  ```js
+  await authenticator({ headers: {} });
+  ```
+
+- **Install a process-level guard** so a mid-flight handshake failure is at
+  least logged and alerted on rather than silently hanging a request:
+  `process.on("unhandledRejection", …)`.
+
+`src/stripe-auth.test.ts` pins this behaviour, so if a future `stripe` release
+routes the failure to the caller the test fails and this warning gets deleted.
+
+### Status
+
+`createStripeAuthenticator` is **built and tested**. Its tests run against a
+real `node:http` server and, for the end-to-end case, drive the **real
+`stripe` package**: `new Stripe("", { authenticator, host, port, protocol })`
+creating a PaymentIntent, with the stub asserting the `Authorization` header
+the authenticator minted, the form-encoded body, and stripe-node's
+auto-generated `Idempotency-Key`. The type-level assertion that the returned
+function is assignable to `Stripe.StripeConfig["authenticator"]` is checked by
+`pnpm --filter @vaam-apps/vpay-sdk typecheck`.
+
+What is **not** proven here:
+
+- **Nothing in this package has run against a real `vpay-server`.** The
+  end-to-end test's server is a stub in this repository. What _has_ run
+  against a real one is
+  [`sdks/stripe-compat`](../stripe-compat/) — the official `stripe` package
+  driven through this authenticator against a live compose stack, 25 cases,
+  run by CI's `e2e (compose)` job. It is a separate package on purpose: it
+  needs a stack, and a suite that needs a stack must not be able to report
+  green in a job that has none.
+- **Every webhook verified so far was delivered to a WireMock receiver on a
+  compose network.** The _signature_ is now proven three ways — against this
+  package's own `verifyWebhook`, against `vpay_sdk::webhooks::verify_at`, and
+  against the official `stripe` package's `constructEvent` — but **no merchant
+  endpoint has ever been POSTed to**, and there is no SSRF protection on the
+  destination ([`docs/flows/webhooks.md`](../../docs/flows/webhooks.md)).
+- **The `stripe` peer range (`^22.6.1`) is asserted, not derived.** It is the
+  current major at the time of writing, tested against exactly `22.6.1`.
+  Nothing pins vpay against a future `stripe` release; a dependency bump is
+  what will surface a break.
+- **The server-side compatibility work is not in this package**, though it
+  has now landed beside it: the `request-id` response header stripe-node
+  reads, `stripe-should-retry` derived from `Classify::retry`, and refusing
+  `confirm: true` on create rather than ignoring it are all in `vpay-api`,
+  with their own unit and integration tests, and are exercised end to end by
+  `sdks/stripe-compat`. See
+  [`docs/flows/stripe-sdk-compat.md`](../../docs/flows/stripe-sdk-compat.md).
+
+## `scripts/mint-assertion.mjs`
+
+Mints one assertion and prints it, alongside the public JWK derived from the
+same private key, as JSON on stdout — used to feed a real OP verifier (e.g. a
+Rust example driving `authkestra_op::client_assertion::verify_client_assertion`
+directly) without standing up a server:
+
+```bash
+pnpm --filter @vaam-apps/vpay-sdk build
+VPAY_CLIENT_ID=merchant_a \
+VPAY_PRIVATE_KEY_FILE=./merchant_a.key.pem \
+VPAY_AUDIENCE=https://api.vpay.example/v1/oauth/token \
+  node sdks/nodejs/scripts/mint-assertion.mjs
+```
+
+## Status
+
+**Corrected 2026-09-03.** This section used to say "what it does **not**
+have is a single `/v1` resource route" — true when it was written on
+2026-09-02, and false since Step 2 landed the next day.
+
+`vpay-server` mounts the merchant OP — `POST /v1/oauth/token`,
+`GET /v1/oauth/jwks.json`,
+`GET /v1/oauth/.well-known/openid-configuration` — puts a bearer-token
+boundary in front of every other `/v1` path, and **serves four
+payment-intent routes past it**: create, retrieve and list on
+`/v1/payment_intents`, plus `/{id}`, `/{id}/confirm` and `/{id}/cancel`. A
+confirm reaches a real rail adapter over HTTP and moves the intent to
+`processing`, and `vpay-worker` then polls the rail and settles it, so an
+intent does reach **`succeeded`** — `sdks/stripe-compat` watches one do so
+through `paymentIntents.retrieve` and nothing else. `/v1/events`,
+`/v1/events/{id}` (Step 5) and `GET /v1/refunds/{id}` (issue #45,
+2026-09-05) are served, and so are `/v1/customers` (S4a) and — since
+2026-09-07 — `/v1/invoices` and `/v1/invoice_items` (S4b), which this
+package has wrapped since 2026-09-08. `POST /v1/refunds` and `/v1/balance`
+are still the honest `404 unknown_route`. ~~**This package has no client method for any of
+that beyond the payment-intent routes it already wraps.**~~ **— corrected
+2026-09-05: it has `refunds.retrieve(id)`,** added in the same change that
+served the route, so this package can now make the refund read a
+reconciliation job needs when a `charge.refund.updated` was missed or
+arrived out of order. It still has no `events.retrieve` — a dated gap in
+[`../../docs/sdks/parity.md`](../../docs/sdks/parity.md) — and
+`refunds.create` and `balance.retrieve` still reach the 404.
+
+**`checkout.sessions` is newer than this paragraph and less proven than the
+rest.** The four methods are implemented and tested against this package's
+`node:http` stub, in the shape of Step 9's wire contract. The routes they
+call — `/v1/checkout/sessions` and its three siblings — are built by lane 1
+of the same step; until that lands and
+`backends/tests/integration/tests/checkout_sessions.rs` is green, "the stub
+answers the way this SDK expects" is the whole of the evidence, and a
+mismatch would show up as a `VpayApiError` rather than as anything this
+package could catch earlier.
+
+**No test in _this package_ has ever talked to a vpay** — every server in
+these tests is a `node:http` stub started by the test. What has talked to a
+real one is `sdks/stripe-compat`, which drives the official `stripe` package
+through this package's own `createStripeAuthenticator` against a live
+compose stack (25 cases, CI's `e2e (compose)` job), and the Rust SDK's
+`backends/tests/integration/tests/merchant_token_flow.rs`. See
+[`docs/status.md`](../../docs/status.md),
+[`docs/flows/merchant-auth.md`](../../docs/flows/merchant-auth.md) and
+[`docs/flows/stripe-sdk-compat.md`](../../docs/flows/stripe-sdk-compat.md).
+
+What the tests in this package **do** prove. Everything that touches HTTP
+runs against a real `node:http` server started by the test (never a mocked
+`fetch`) and asserts the actual bytes sent on the wire; the form encoder,
+the webhook verifier and the error-body bounding are pure unit tests, since
+none of them touches the network:
+
+- The client assertion this SDK mints has every claim and header field the
+  wire contract specifies, is a fresh `jti` per mint, and its RS256 signature
+  verifies with `node:crypto` against the matching public key — and fails
+  against a different one.
+- The full `client_credentials` + `private_key_jwt` token exchange: exact
+  form fields, content type, and the resulting `Authorization: Bearer`
+  header on the following resource call.
+- Token caching (`expires_in` minus the safety margin), single-flight
+  refresh under concurrent callers, and the single 401-triggered re-auth
+  retry (including that a second consecutive 401 surfaces as `VpayApiError`
+  without a third token request).
+- Every resource method's exact HTTP method, path, headers, and
+  bracket-encoded body — including that a caller-supplied `Idempotency-Key`
+  is honoured and one is generated when omitted.
+- That `create()` and `retrieve()` surface `client_secret` typed (`string`)
+  when the server sends it, and that a `list()` item without one reads back
+  `undefined` rather than a cast or a runtime crash.
+- All four `checkout.sessions` operations: the exact path, method,
+  `Idempotency-Key` and body of `create` (including that an unset `ui_mode`
+  or URL is omitted rather than sent empty), the `GET` paths of `retrieve`
+  and `list` with its `payment_intent` filter, `expire`'s empty-bodied
+  `POST`, percent-encoding of a hostile id on both, and the `404`/`409`
+  envelopes. The body strings are the ones `sdks/rust/tests/resources.rs`
+  pins byte for byte, so the two SDKs cannot drift.
+- That a `CheckoutSession`'s `client_secret` — and the fragment of a hosted
+  session's `url`, which carries the same value — are redacted from
+  `util.inspect` while `JSON.stringify` stays faithful.
+- The form encoder's nested-object/array/boolean/percent-encoding rules, and
+  that a non-integer `amount` throws `TypeError` before any request is sent.
+- Error mapping for a Stripe-shaped `400`, an unexpected `502` HTML body, a
+  connection failure, and a token-endpoint `401` (which is never retried).
+- Webhook verification: valid/invalid signatures, timestamp tolerance,
+  multi-signature secret rotation, malformed headers, a one-byte body change,
+  and that a `Buffer` body and its string form verify identically.
+- That `util.inspect(client)` and `JSON.stringify(client)` never contain the
+  private key, and that neither the client nor any error this SDK throws
+  carries an access token into `util.inspect` output.
+- All thirteen invoice operations (S4b, added 2026-09-08): the exact body of
+  `invoices.create` and of a create that supplies nothing but the two required
+  fields (`customer` and `currency` — the second was optional for one day, and
+  a running vpay answers `400` without it); the `GET`
+  whose response carries the lines; the update's three states (`due_date=` is
+  _clear it_, an unmentioned field is absent, and a patch that mentions
+  nothing sends nothing); the list's two cursors and two filters; the
+  `DELETE` with its key and no body; that `finalize`, `void` and
+  `markUncollectible` each `POST` an **empty** body to its own path while
+  still sending a content type (the third method is camelCase and its route,
+  `/v1/invoices/{id}/mark_uncollectible`, is not — the case asserts the path
+  by name); that a refused transition arrives as a
+  `VpayApiError` carrying the server's `409` whole; that `invoices.pay` sends
+  both URLs and answers an invoice still `"open"` with a `payment_intent` and
+  a `hosted_invoice_url`; the four `invoiceItems` methods, including that
+  neither `currency` nor `amount` is ever in the body; and that a
+  `unit_amount` outside the safe-integer range throws `TypeError` before any
+  request. Every body string is the one `sdks/rust/tests/resources.rs` pins,
+  asserted as a literal on both sides.
+- **Against a real `vpay-server`, not a stub** (added 2026-09-08):
+  `src/invoices.live.test.ts` creates a customer, drafts an invoice, bills two
+  lines, finalizes it, reads it back, checks the stored lines add up to the
+  stored total, lists it, voids it and finds it keeps its number; then
+  finalizes a second and has `pay` mint a payment intent and a hosted URL
+  without charging anybody; and confirms `currency` is required. It is a
+  **separate vitest project** (`vitest.live.config.ts`, `pnpm test:live`) so
+  `pnpm test` stays runnable with no stack, and it **fails rather than
+  skipping** when there is none — `just sdk-live` is what brings one up.
+- That the four `invoice.*` types are in `KnownEventType` and narrow through
+  `isInvoiceEvent`, that `isPaymentIntentEvent` and `isCheckoutSessionEvent`
+  do **not** claim them, and that an event body's empty `lines` decodes
+  through the same `Invoice` type a `/v1` response's populated `lines` does.
+
+**Separately — and this is _not_ one of the tests above — the assertion has
+been checked against the real OP verifier by hand.** An assertion minted by
+this SDK was fed directly to
+`authkestra_op::client_assertion::verify_client_assertion` at the pinned
+`authkestra-op = "=0.7.1"`, against a `ClientRegistration` holding the
+corresponding public JWK, and was accepted. `just sdk-conformance-node`
+reproduces it: the recipe mints an assertion via `scripts/mint-assertion.mjs`
+and pipes it into `cargo run -p vpay-sdk --example verify_assertion`. It is a
+manual check, run on demand — it needs a Rust toolchain, it is not part of
+`pnpm test`, and no CI job gates on it. Nothing in the list above depends on
+it having been run.
+
+What this does **not** prove: that any of this works against a real vpay
+deployment. Nothing in this package has been run against `vpay-server`; the
+`issuer`/`tokenEndpoint` defaults agree with `vpay_api::op::issuer_for` by
+inspection, not by a test in this repository that exercises them together,
+and the resource routes every method here calls do not exist server-side at
+all — see [`docs/status.md`](../../docs/status.md).