@vaam-apps/vpay-sdk 0.5.0 → 0.6.0

package/README.md

@@ -727,8 +727,21 @@ manual check, run on demand — it needs a Rust toolchain, it is not part of
 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
+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).
+all~~ — see [`docs/status.md`](../../docs/status.md).
+
+_(Struck 2026-09-23. All three clauses had gone stale. **Run against
+`vpay-server`:** since 2026-09-10, `src/invoices.live.test.ts`, joined by
+`src/refunds.live.test.ts` on 2026-09-16, drives a real `vpay-server` over a
+socket, and CI's `e2e` job runs them (`pnpm --filter @vaam-apps/vpay-sdk
+test:live`). **The defaults:** those suites' preflight
+(`src/testing/live-preflight.ts`) builds its client from `baseUrl` alone, so
+every live run exercises the default `issuer` and `tokenEndpoint` against the
+server's own OP. **The routes:** every method's route is mounted except
+`balance.retrieve`, which answers `404` by design
+([`docs/sdks/parity.md`](../../docs/sdks/parity.md)). What still stands is the
+sentence this paragraph opens with. That stack is a compose stack with
+WireMock rails, not a deployment.)_

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { verifyWebhook, type VerifyWebhookOptions } from "./webhooks.js";
 /** This package's own version, as sent in the `vpay-sdk-node/<version>` User-Agent. */
 export { SDK_VERSION } from "./version.js";
 export { VpayError, VpayApiError, VpayAuthError, VpayUnexpectedResponseError, VpayTransportError, VpayConfigError, WebhookSignatureError, } from "./errors.js";
-export type { AccountHolder, RetrieveAccountHolderParams, CheckoutSession, CheckoutSessionStatus, CheckoutSessionUiMode, CheckoutPaymentStatus, CreateCheckoutSessionParams, ListCheckoutSessionsParams, Customer, DeletedCustomer, Address, AddressParams, CreateCustomerParams, UpdateCustomerParams, ListCustomersParams, Invoice, InvoiceLine, InvoiceStatus, InvoiceStatusTransitions, DeletedInvoice, DeletedInvoiceItem, CreateInvoiceParams, UpdateInvoiceParams, ListInvoicesParams, PayInvoiceParams, CreateInvoiceItemParams, UpdateInvoiceItemParams, PaymentIntent, PaymentIntentStatus, PaymentMethodType, NextAction, LastPaymentError, FailureCode, Refund, RefundStatus, Event, KnownEventType, Balance, BalanceAmount, List, ListParams, ListEventsParams, CreatePaymentIntentParams, ConfirmPaymentIntentParams, MtnMomoPaymentMethodData, OrangeMoneyPaymentMethodData, CreateRefundParams, RefundDestination, UpdateRefundParams, ListRefundsParams, RequestOptions, } from "./types.js";
+export type { AccountHolder, RetrieveAccountHolderParams, CheckoutSession, CheckoutSessionStatus, CheckoutSessionUiMode, CheckoutPaymentStatus, CreateCheckoutSessionParams, ListCheckoutSessionsParams, Customer, DeletedCustomer, Address, AddressParams, CreateCustomerParams, UpdateCustomerParams, ListCustomersParams, Invoice, InvoiceLine, InvoiceStatus, InvoiceStatusTransitions, DeletedInvoice, DeletedInvoiceItem, CreateInvoiceParams, UpdateInvoiceParams, ListInvoicesParams, PayInvoiceParams, HostedPayInvoiceParams, OutOfBandPayInvoiceParams, OutOfBandParams, OutOfBandMethod, OutOfBandPayment, CreateInvoiceItemParams, UpdateInvoiceItemParams, PaymentIntent, PaymentIntentStatus, PaymentMethodType, NextAction, LastPaymentError, FailureCode, Refund, RefundStatus, Event, KnownEventType, Balance, BalanceAmount, List, ListParams, ListPaymentIntentsParams, ListEventsParams, CreatePaymentIntentParams, ConfirmPaymentIntentParams, MtnMomoPaymentMethodData, OrangeMoneyPaymentMethodData, CreateRefundParams, RefundDestination, UpdateRefundParams, ListRefundsParams, RequestOptions, } from "./types.js";
 export { isCheckoutSessionEvent, isInvoiceEvent, isPaymentIntentEvent, isRefundEvent, } from "./types.js";

package/dist/resources/invoices.d.ts

@@ -147,6 +147,13 @@ export declare class InvoicesResource {
      *
      * A `500 checkout_not_configured` when this deployment serves no checkout
      * page.
+     *
+     * **With `outOfBand`** it records instead that the invoice was settled
+     * outside vpay (RFC-0004 § 6): `open` → `paid` on the merchant's word,
+     * `invoice.paid` emitted, no intent, no checkout, no URL, and nothing
+     * verified or posted to any ledger. While an intent that is not canceled is
+     * attached it is the same `409` as `void`; cancel the intent first. A URL
+     * beside `outOfBand` is refused with a `TypeError` before any request.
      */
     pay(id: string, params: PayInvoiceParams, options?: RequestOptions): Promise<Invoice>;
 }

package/dist/resources/invoices.js

@@ -183,9 +183,40 @@ export class InvoicesResource {
      *
      * A `500 checkout_not_configured` when this deployment serves no checkout
      * page.
+     *
+     * **With `outOfBand`** it records instead that the invoice was settled
+     * outside vpay (RFC-0004 § 6): `open` → `paid` on the merchant's word,
+     * `invoice.paid` emitted, no intent, no checkout, no URL, and nothing
+     * verified or posted to any ledger. While an intent that is not canceled is
+     * attached it is the same `409` as `void`; cancel the intent first. A URL
+     * beside `outOfBand` is refused with a `TypeError` before any request.
      */
     async pay(id, params, options) {
-        return this.#http.request("POST", `/invoices/${encodeURIComponent(id)}/pay`, { success_url: params.success_url, cancel_url: params.cancel_url }, options);
+        const outOfBand = params.outOfBand;
+        if (outOfBand !== undefined) {
+            // The type forbids this; a plain-JS caller can still send it, and the
+            // server would answer a `400`. Refused here for parity with
+            // `sdks/rust`, which refuses the same combination as `InvalidParams`.
+            for (const param of ["success_url", "cancel_url"]) {
+                const value = params[param];
+                if (value !== undefined && value !== "") {
+                    throw new TypeError(`${param} has no meaning when recording a payment made outside vpay (outOfBand is set)`);
+                }
+            }
+        }
+        // Field order is the wire order `sdks/rust` pins too: the flag, then
+        // `out_of_band[method]`, `[reference]`, `[received_at]`.
+        const body = outOfBand !== undefined
+            ? {
+                paid_out_of_band: true,
+                out_of_band: {
+                    method: outOfBand.method,
+                    reference: outOfBand.reference,
+                    received_at: outOfBand.receivedAt,
+                },
+            }
+            : { success_url: params.success_url, cancel_url: params.cancel_url };
+        return this.#http.request("POST", `/invoices/${encodeURIComponent(id)}/pay`, body, options);
     }
     /**
      * The three transitions that take no parameters, which are one shape:

package/dist/resources/payment-intents.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from "../http.js";
-import type { ConfirmPaymentIntentParams, CreatePaymentIntentParams, List, ListParams, PaymentIntent, RequestOptions } from "../types.js";
+import type { ConfirmPaymentIntentParams, CreatePaymentIntentParams, List, ListPaymentIntentsParams, PaymentIntent, RequestOptions } from "../types.js";
 /** `/v1/payment_intents` — docs/flows/merchant-auth.md, "Resources". */
 export declare class PaymentIntentsResource {
     #private;
@@ -8,5 +8,6 @@ export declare class PaymentIntentsResource {
     retrieve(id: string): Promise<PaymentIntent>;
     confirm(id: string, params: ConfirmPaymentIntentParams, options?: RequestOptions): Promise<PaymentIntent>;
     cancel(id: string, options?: RequestOptions): Promise<PaymentIntent>;
-    list(params?: ListParams): Promise<List<PaymentIntent>>;
+    /** `GET /v1/payment_intents`, newest first; `customer` narrows it. */
+    list(params?: ListPaymentIntentsParams): Promise<List<PaymentIntent>>;
 }

package/dist/resources/payment-intents.js

@@ -38,6 +38,7 @@ export class PaymentIntentsResource {
     async cancel(id, options) {
         return this.#http.request("POST", `/payment_intents/${encodeURIComponent(id)}/cancel`, {}, options);
     }
+    /** `GET /v1/payment_intents`, newest first; `customer` narrows it. */
     async list(params) {
         return this.#http.request("GET", "/payment_intents", params);
     }

package/dist/types.d.ts

@@ -345,6 +345,11 @@ export interface CheckoutSession {
      * The `cus_…` this session is for, or `null` (S4a). Copied from the
      * session's intent at create when the intent has one. The id, never the
      * expanded object — {@link PaymentIntent.customer}'s reason, unchanged.
+     *
+     * The other direction, from 2026-09-23 (ADR-0025): a session created with
+     * a customer for an intent that had none wrote it onto the intent too, so
+     * the two agree. A session created that way before then, or by a server
+     * without ADR-0025, may name a customer its intent does not.
      */
     customer?: string | null;
     /** Unix seconds. 24 h from create. */
@@ -459,6 +464,46 @@ export type ListParams = {
     starting_after?: string | undefined;
     ending_before?: string | undefined;
 };
+/**
+ * `GET /v1/payment_intents` query parameters: {@link ListParams} plus the
+ * `customer` filter (RFC-0004 § 5).
+ *
+ * Written flat rather than as `ListParams & { … }` for {@link ListParams}'
+ * index-signature reason. `ListParams` itself stays exported and unchanged —
+ * it is public, and every `ListParams` value is still a valid one of these.
+ */
+export type ListPaymentIntentsParams = {
+    limit?: number | undefined;
+    starting_after?: string | undefined;
+    ending_before?: string | undefined;
+    /**
+     * Only intents for this `cus_…` (the intent's own `customer`).
+     *
+     * Held to the Customer id shape by the server, which answers `400` naming
+     * `customer` for anything else. An id of the right shape that names
+     * nothing, or another merchant's customer, is an **empty page** and not a
+     * `404`, so the filter cannot tell you which customers exist under some
+     * other account.
+     *
+     * **A checkout session's customer is seen here, from 2026-09-23 on.** A
+     * session created with `customer` on an intent that has none now writes
+     * that customer onto the intent (ADR-0025,
+     * `docs/adr/0025-session-customer-onto-intent.md`), so the payment it
+     * collects is in this list. **Historical rows are not:** a session created
+     * that way before the change, or against a server without it, stored the
+     * customer on the session only, those intents were not backfilled, and
+     * only {@link ListCheckoutSessionsParams}' `customer` finds their payment.
+     * _(Until ADR-0025 this said the session's customer was never seen here,
+     * and called the question open question 3 of ADR-0024.)_
+     *
+     * **Needs a vpay server that has this filter**: no release up to and
+     * including 0.5.0 has it (as of 2026-09-23). A
+     * self-hosted server at 0.5.0 or earlier does not know this parameter: it
+     * ignores it and answers the **unfiltered** list — every customer's rows,
+     * with no error. Check the server's version before relying on it.
+     */
+    customer?: string | undefined;
+};
 /**
  * A postal address on a {@link Customer} — Stripe's six formal components
  * **and** the GPS point (issue #67).
@@ -764,7 +809,8 @@ export interface InvoiceStatusTransitions {
     marked_uncollectible_at: number | null;
 }
 /**
- * An `invoice` (S4b): a merchant's bill to one customer. **Eighteen keys.**
+ * An `invoice` (S4b): a merchant's bill to one customer. **Twenty-one keys** (this
+ * said "Eighteen" through two additions; corrected 2026-09-23).
  *
  * # `lines` is always expanded, and always unpaged
  *
@@ -826,6 +872,16 @@ export interface Invoice {
      * a server that predates migration `0042`, where the key is absent.
      */
     amount_refunded?: number;
+    /**
+     * Stripe's key: `true` exactly when the merchant recorded that this invoice
+     * was settled outside vpay (`client.invoices.pay` with `outOfBand`).
+     * Always `false` on a bill a payer paid through
+     * a rail. Optional in the type so a client of this version keeps compiling
+     * against a server that predates migration `0049`.
+     */
+    paid_out_of_band?: boolean;
+    /** The record behind `paid_out_of_band`, or `null`. Present exactly when the flag is `true`. */
+    out_of_band_payment?: OutOfBandPayment | null;
     /**
      * Unix **seconds**, or `null`. **Advisory**: nothing in vpay reads it —
      * there is no dunning, no reminder and no automatic transition.
@@ -965,10 +1021,68 @@ export type ListInvoicesParams = {
  * carry the literal `{CHECKOUT_SESSION_ID}` — and this SDK deliberately does
  * not duplicate them, for {@link CreateCheckoutSessionParams}' reason.
  */
-export type PayInvoiceParams = {
+export type PayInvoiceParams = HostedPayInvoiceParams | OutOfBandPayInvoiceParams;
+/** The hosted-checkout payment: both URLs, and no `outOfBand`. */
+export interface HostedPayInvoiceParams {
     success_url: string;
     cancel_url: string;
-};
+    outOfBand?: undefined;
+}
+/**
+ * Records the invoice as settled **outside vpay** (RFC-0004 § 6). The
+ * presence of `outOfBand` is the flag: it puts Stripe's
+ * `paid_out_of_band=true` plus vpay's `out_of_band[…]` on the wire. The
+ * invoice becomes `"paid"` on the merchant's word, with no intent and no
+ * checkout, and **nothing is verified or posted to any ledger**. No URL may
+ * go with it — the type forbids one, and `client.invoices.pay` refuses one at
+ * runtime for a caller the type did not reach — and none needs configuring.
+ *
+ * `outOfBand` and its keys are camelCase, unlike the snake_case URL fields
+ * beside them, by the maintainer's decision of 2026-09-23 (ADR-0024).
+ */
+export interface OutOfBandPayInvoiceParams {
+    outOfBand: OutOfBandParams;
+    success_url?: undefined;
+    cancel_url?: undefined;
+}
+/** How a merchant says an out-of-band payment arrived. vpay's own words. */
+export type OutOfBandMethod = "cash" | "cheque" | "bank_transfer" | "other";
+/**
+ * What the merchant says about a payment made outside vpay. Every key is
+ * optional: `{}` is Stripe's bare `paid_out_of_band=true`, which the server
+ * records with the method `"other"`.
+ */
+export interface OutOfBandParams {
+    /** Sent as `out_of_band[method]`; omitted, the server records `"other"`. */
+    method?: OutOfBandMethod | undefined;
+    /**
+     * Sent as `out_of_band[reference]`. A cheque number, a transfer reference;
+     * at most 500 characters. **Treat it as personal data**: vpay does — a
+     * reference routinely names the payer — and replaces it with `[redacted]`
+     * when the invoice's customer is erased, and refuses one on an erased
+     * customer's invoice.
+     */
+    reference?: string | undefined;
+    /**
+     * Sent as `out_of_band[received_at]`, unix **seconds**. The server defaults
+     * it to now, and refuses one more than 30 seconds in the future or earlier
+     * than the second the invoice was finalized in.
+     */
+    receivedAt?: number | undefined;
+}
+/**
+ * `invoice.out_of_band_payment` — the merchant's own statement, echoed back.
+ * **Nothing in vpay verified it.** Four keys and no `object`.
+ */
+export interface OutOfBandPayment {
+    /** `mp_…`. */
+    id: string;
+    method: OutOfBandMethod;
+    /** `null`, or `"[redacted]"` once the invoice's customer has been erased. */
+    reference: string | null;
+    /** Unix **seconds**: when the merchant says the money arrived. */
+    received_at: number;
+}
 /**
  * `POST /v1/invoice_items` request fields (S4b).
  *
@@ -1079,8 +1193,19 @@ export interface CreateCheckoutSessionParams {
      * The `cus_…` this session is for (issue #70), or omit to inherit the
      * intent's customer — see {@link CheckoutSession.customer}.
      *
-     * Refused `409` naming `customer` when the session's PaymentIntent already
+     * Refused `400` naming `customer` when the session's PaymentIntent already
      * names a *different* customer; the server never lets the two disagree.
+     * _(This said `409` until 2026-09-23. The server has always answered
+     * `400` (`invalid_param`), which
+     * `a_sessions_customer_is_inherited_supplied_or_a_refused_contradiction` in
+     * `backends/tests/integration/tests/customers.rs` asserts.)_
+     *
+     * When the intent has **no** customer, a server with ADR-0025 (2026-09-23,
+     * `docs/adr/0025-session-customer-onto-intent.md`) writes this one onto
+     * the intent, in the same transaction as the session. So the intent's own
+     * `customer` and the intent and refund list filters see it, and a later
+     * session on that intent cannot name somebody else. A server without it
+     * stores the customer on the session only.
      */
     customer?: string | undefined;
 }
@@ -1094,6 +1219,34 @@ export type ListCheckoutSessionsParams = {
     ending_before?: string | undefined;
     /** Only sessions for this `pi_…`. */
     payment_intent?: string | undefined;
+    /**
+     * Only sessions for this `cus_…` — the session's own `customer`, which is
+     * the one it renders.
+     *
+     * Held to the Customer id shape by the server, which answers `400` naming
+     * `customer` for anything else. An id of the right shape that names
+     * nothing, or another merchant's customer, is an **empty page** and not a
+     * `404`, so the filter cannot tell you which customers exist under some
+     * other account.
+     *
+     * This is the **session's** customer, and it includes a session created
+     * with `customer` on an intent that has none. From 2026-09-23 on such a
+     * session also writes its customer onto the intent (ADR-0025,
+     * `docs/adr/0025-session-customer-onto-intent.md`), so
+     * {@link ListPaymentIntentsParams}' and {@link ListRefundsParams}'
+     * `customer` find its payment too. A session created that way **before**
+     * the change, or against a server without it, has its customer on the
+     * session only; its intent was not backfilled, and this filter is the only
+     * one that finds its payment. _(Until ADR-0025 this said that of every such
+     * session, and called the question open question 3 of ADR-0024.)_
+     *
+     * **Needs a vpay server that has this filter**: no release up to and
+     * including 0.5.0 has it (as of 2026-09-23). A
+     * self-hosted server at 0.5.0 or earlier does not know this parameter: it
+     * ignores it and answers the **unfiltered** list — every customer's rows,
+     * with no error. Check the server's version before relying on it.
+     */
+    customer?: string | undefined;
 };
 /**
  * Where a refund's money goes, on a rail that cannot send it back the way it
@@ -1249,6 +1402,34 @@ export type ListRefundsParams = {
      * page** and not a `404`.
      */
     payment_intent?: string | undefined;
+    /**
+     * Only refunds of payments by this `cus_…` — matched through each refund's
+     * PaymentIntent, since a refund carries no customer of its own.
+     *
+     * Held to the Customer id shape by the server, which answers `400` naming
+     * `customer` for anything else. An id of the right shape that names
+     * nothing, or another merchant's customer, is an **empty page** and not a
+     * `404`, so the filter cannot tell you which customers exist under some
+     * other account.
+     *
+     * **A checkout session's customer is seen here, from 2026-09-23 on.** A
+     * session created with `customer` on an intent that has none now writes
+     * that customer onto the intent (ADR-0025,
+     * `docs/adr/0025-session-customer-onto-intent.md`), and this filter reads
+     * the refund's intent's `customer`, so refunds of its payment are in this
+     * list. **Historical rows are not:** a session created that way before the
+     * change, or against a server without it, stored the customer on the
+     * session only, and those intents were not backfilled. _(Until ADR-0025
+     * this said the session's customer was never seen here, and called the
+     * question open question 3 of ADR-0024.)_
+     *
+     * **Needs a vpay server that has this filter**: no release up to and
+     * including 0.5.0 has it (as of 2026-09-23). A
+     * self-hosted server at 0.5.0 or earlier does not know this parameter: it
+     * ignores it and answers the **unfiltered** list — every customer's rows,
+     * with no error. Check the server's version before relying on it.
+     */
+    customer?: string | undefined;
 };
 /**
  * Written flat rather than as `ListParams & { … }` for the same

package/dist/version.d.ts

@@ -9,4 +9,4 @@
  * releases. A hand-written constant has no such landmine — it just needs to
  * be bumped alongside `package.json`'s own `version` field.
  */
-export declare const SDK_VERSION = "0.5.0";
+export declare const SDK_VERSION = "0.6.0";

package/dist/version.js

@@ -9,4 +9,4 @@
  * releases. A hand-written constant has no such landmine — it just needs to
  * be bumped alongside `package.json`'s own `version` field.
  */
-export const SDK_VERSION = "0.5.0"; // x-release-please-version
+export const SDK_VERSION = "0.6.0"; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaam-apps/vpay-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The Node.js merchant SDK for vpay's /v1 API: OAuth2 private_key_jwt, payment intents, checkout sessions, refunds, events and webhook verification.",
   "license": "Apache-2.0",
   "publishConfig": {