@vaam-apps/vpay-sdk 0.9.1 → 0.10.1

package/README.md

@@ -225,6 +225,7 @@ works as a catch-all; narrow further with `instanceof` on a specific subclass:
 | `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.                                                                                                                                                                                                                                                         | —                                            |
+| `VpayInvalidParamsError`      | A request parameter this SDK refuses to send, caught before anything is sent: an amount outside `0..=2^53-1`, a value the form encoder cannot put on the wire exactly (a non-safe-integer number, a `Date`, a `Map`), an empty or all-dots path `id`, a URL beside `outOfBand`. Not a `TypeError` (2026-10-21).            | `param`, `message`                           |
 | `WebhookSignatureError`       | `verifyWebhook` rejected a signature.                                                                                                                                                                                                                                                                                      | —                                            |
 
 ```ts
@@ -591,6 +592,21 @@ VPAY_AUDIENCE=https://api.vpay.example/v1/oauth/token \
 
 ## Status
 
+**Breaking, 2026-10-21: every local refusal is a `VpayInvalidParamsError`,
+not a `TypeError`.** An amount outside `0..=2^53-1`, a value the form
+encoder cannot put on the wire exactly, an empty or all-dots path `id` and a
+URL beside `outOfBand` on `invoices.pay` now reject with the new exported
+`VpayInvalidParamsError`. It extends `VpayError`, so the README's
+`instanceof VpayError` catch-all finally catches it, and its `param` names
+the parameter, like `sdks/rust`'s `Error::InvalidParams { param, .. }`. Its
+`message` is that variant's `Display` text,
+`invalid request parameter {param}: {detail}`. **A caller that tested
+`instanceof TypeError` for these no longer matches**, and cannot be made to:
+a class has one superclass, and making `VpayError` a `TypeError` would make
+every error here one, a network failure included. Switch to
+`instanceof VpayInvalidParamsError`. No signature changed and nothing that
+was sent before is refused now.
+
 **Behaviour change, 2026-10-21: an empty or all-dots `id` is refused before
 any request.** Every one of the twenty-one methods that put an `id` in the
 path now rejects with a `TypeError` for `""`, `.`, `..` or any longer run of
@@ -605,7 +621,10 @@ each is on
 A caller catching `VpayApiError` for those inputs now gets a `TypeError`,
 and so does one narrowing on `VpayError`: like the amount refusal, it is not
 one (a dated gap in [docs/sdks/parity.md](../../docs/sdks/parity.md)).
-`sdks/rust` refuses the same ids with `Error::InvalidParams`.
+`sdks/rust` refuses the same ids with `Error::InvalidParams`. _(Corrected
+later the same day: the refusal is a `VpayInvalidParamsError` now, so a
+`VpayError` narrowing catches it and the gap is closed — the paragraph
+above.)_
 
 **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
@@ -688,8 +707,12 @@ none of them touches the network:
   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.
-- That an empty or all-dots `id` throws `TypeError` on all twenty-one
+  that a non-integer `amount` throws `VpayInvalidParamsError` before any
+  request is sent.
+- That every kind of local refusal — an amount, an id, an out-of-band URL, a
+  `Date` in `metadata` — is a `VpayInvalidParamsError` naming its parameter,
+  caught by `instanceof VpayError` and not a `TypeError`, with nothing sent.
+- That an empty or all-dots `id` throws `VpayInvalidParamsError` on all twenty-one
   id-taking methods before any request, the token request included, with one
   fixed message that never quotes it; that an id with dots in it that is not
   only dots (`a..b`, `.a`, `%2E%2E`) is still sent as exactly one segment;
@@ -719,8 +742,8 @@ none of them touches the network:
   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,
+  `unit_amount` outside the safe-integer range throws `VpayInvalidParamsError`
+  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

package/dist/errors.d.ts

@@ -57,6 +57,32 @@ export declare class VpayUnexpectedResponseError extends VpayError {
     readonly bodyPrefix: string;
     constructor(status: number, bodyPrefix: string);
 }
+/**
+ * A request parameter this SDK refuses to put on the wire, caught before
+ * anything is sent — no token is minted and no request is built. The twin
+ * of `sdks/rust`'s `Error::InvalidParams { param, message }`, and its
+ * `message` is that variant's `Display` text: `invalid request parameter
+ * {param}: {detail}`.
+ *
+ * Thrown for an amount outside `0..=2^53-1`, a value the form encoder cannot
+ * put on the wire exactly (a non-safe-integer number, a `Date`, a `Map`, a
+ * class instance), a path `id` that is empty or only dots, and a URL beside
+ * `outOfBand` on `invoices.pay`.
+ *
+ * **Not a `TypeError`, since 2026-10-21.** Every one of these was a bare
+ * `TypeError` until then, which the one narrowing this package documents —
+ * `instanceof VpayError` — missed. It cannot be both: a class has one
+ * superclass, and making `VpayError` extend `TypeError` would make every
+ * error this package throws a `TypeError`, a network failure included.
+ */
+export declare class VpayInvalidParamsError extends VpayError {
+    /**
+     * The offending parameter's wire name — `amount`, `unit_amount`, `id`,
+     * `success_url`, or a nested form path such as `metadata[order_id]`.
+     */
+    readonly param: string;
+    constructor(param: string, detail: string);
+}
 /** A transport-level failure — DNS, TLS, connection refused, timeout. */
 export declare class VpayTransportError extends VpayError {
     constructor(message: string, options?: ErrorOptions);

package/dist/errors.js

@@ -69,6 +69,35 @@ export class VpayUnexpectedResponseError extends VpayError {
         this.bodyPrefix = bodyPrefix;
     }
 }
+/**
+ * A request parameter this SDK refuses to put on the wire, caught before
+ * anything is sent — no token is minted and no request is built. The twin
+ * of `sdks/rust`'s `Error::InvalidParams { param, message }`, and its
+ * `message` is that variant's `Display` text: `invalid request parameter
+ * {param}: {detail}`.
+ *
+ * Thrown for an amount outside `0..=2^53-1`, a value the form encoder cannot
+ * put on the wire exactly (a non-safe-integer number, a `Date`, a `Map`, a
+ * class instance), a path `id` that is empty or only dots, and a URL beside
+ * `outOfBand` on `invoices.pay`.
+ *
+ * **Not a `TypeError`, since 2026-10-21.** Every one of these was a bare
+ * `TypeError` until then, which the one narrowing this package documents —
+ * `instanceof VpayError` — missed. It cannot be both: a class has one
+ * superclass, and making `VpayError` extend `TypeError` would make every
+ * error this package throws a `TypeError`, a network failure included.
+ */
+export class VpayInvalidParamsError extends VpayError {
+    /**
+     * The offending parameter's wire name — `amount`, `unit_amount`, `id`,
+     * `success_url`, or a nested form path such as `metadata[order_id]`.
+     */
+    param;
+    constructor(param, detail) {
+        super(`invalid request parameter ${param}: ${detail}`);
+        this.param = param;
+    }
+}
 /** A transport-level failure — DNS, TLS, connection refused, timeout. */
 export class VpayTransportError extends VpayError {
     constructor(message, options) {

package/dist/form.d.ts

@@ -30,6 +30,9 @@
  *   is decimal integers with no separators (docs/flows/money.md bans floating
  *   point in the money path outright), so a float or a `1e21` is a bug in the
  *   caller, not a value to transmit approximately.
+ *
+ * Both refusals are a {@link VpayInvalidParamsError} naming the value's form
+ * path (`amount`, `metadata[order_id]`), thrown before anything is sent.
  */
 /** A value the form encoder can flatten. `null` is treated like `undefined`: omitted. */
 export type FormValue = string | number | boolean | undefined | null | readonly FormValue[] | {

package/dist/form.js

@@ -30,8 +30,12 @@
  *   is decimal integers with no separators (docs/flows/money.md bans floating
  *   point in the money path outright), so a float or a `1e21` is a bug in the
  *   caller, not a value to transmit approximately.
+ *
+ * Both refusals are a {@link VpayInvalidParamsError} naming the value's form
+ * path (`amount`, `metadata[order_id]`), thrown before anything is sent.
  */
-/** Renders a path back into the bracket syntax, for error messages only. */
+import { VpayInvalidParamsError } from "./errors.js";
+/** Renders a path back into the bracket syntax, for an error's `param` only. */
 function describePath(path) {
     const [head, ...rest] = path;
     return `${head ?? ""}${rest.map((segment) => `[${segment}]`).join("")}`;
@@ -53,7 +57,7 @@ function isPlainObject(value) {
 /** Renders a number for the wire, refusing anything that is not an exact decimal integer. */
 function encodeNumber(value, path) {
     if (!Number.isSafeInteger(value)) {
-        throw new TypeError(`${describePath(path)} must be a safe integer, got ${value}`);
+        throw new VpayInvalidParamsError(describePath(path), `must be a safe integer, got ${value}`);
     }
     const text = String(value);
     // Subsumed by the check above as the language stands today — JavaScript
@@ -63,7 +67,7 @@ function encodeNumber(value, path) {
     // format actually requires: no test can kill this branch on its own, and
     // the comment says so rather than implying it is covered.
     if (text.includes("e") || text.includes("E")) {
-        throw new TypeError(`${describePath(path)} must encode as a plain decimal integer, got ${text}`);
+        throw new VpayInvalidParamsError(describePath(path), `must encode as a plain decimal integer, got ${text}`);
     }
     return text;
 }
@@ -77,7 +81,7 @@ function flattenValue(path, value, out) {
     }
     if (typeof value === "object") {
         if (!isPlainObject(value)) {
-            throw new TypeError(`${describePath(path)} must be a plain object, array or scalar, got ${value.constructor?.name ?? "an object"}`);
+            throw new VpayInvalidParamsError(describePath(path), `must be a plain object, array or scalar, got ${value.constructor?.name ?? "an object"}`);
         }
         for (const [childKey, childValue] of Object.entries(value)) {
             flattenValue([...path, childKey], childValue, out);

package/dist/index.d.ts

@@ -10,6 +10,6 @@ export { mintClientAssertion, type MintClientAssertionOptions, } from "./auth.js
 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 { VpayError, VpayApiError, VpayAuthError, VpayUnexpectedResponseError, VpayTransportError, VpayConfigError, VpayInvalidParamsError, 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, 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/index.js

@@ -10,5 +10,5 @@ export { mintClientAssertion, } from "./auth.js";
 export { verifyWebhook } 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 { VpayError, VpayApiError, VpayAuthError, VpayUnexpectedResponseError, VpayTransportError, VpayConfigError, VpayInvalidParamsError, WebhookSignatureError, } from "./errors.js";
 export { isCheckoutSessionEvent, isInvoiceEvent, isPaymentIntentEvent, isRefundEvent, } from "./types.js";

package/dist/resources/invoices.d.ts

@@ -153,7 +153,8 @@ export declare class InvoicesResource {
      * `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.
+     * beside `outOfBand` is refused with a `VpayInvalidParamsError` naming it,
+     * before any request.
      */
     pay(id: string, params: PayInvoiceParams, options?: RequestOptions): Promise<Invoice>;
 }
@@ -177,7 +178,7 @@ export declare class InvoiceItemsResource {
      * `POST /v1/invoice_items` — adds a line to a draft, and the invoice's
      * `amount_due` moves with it.
      *
-     * Throws `TypeError` before any request when `unit_amount` is not a
+     * Throws `VpayInvalidParamsError` before any request when `unit_amount` is not a
      * non-negative safe integer; a `400` naming `invoice` when it is not one of
      * your drafts.
      */
@@ -188,7 +189,7 @@ export declare class InvoiceItemsResource {
      * `POST /v1/invoice_items/{id}` — **draft parent only**, with `amount`
      * recomputed.
      *
-     * Throws `TypeError` before any request for a `unit_amount` outside the
+     * Throws `VpayInvalidParamsError` before any request for a `unit_amount` outside the
      * bound; a `409` once the parent is no longer a draft.
      */
     update(id: string, params: UpdateInvoiceItemParams, options?: RequestOptions): Promise<InvoiceLine>;

package/dist/resources/invoices.js

@@ -1,3 +1,4 @@
+import { VpayInvalidParamsError } from "../errors.js";
 import { assertIntegerAmount, pathSegment } from "../validate.js";
 /**
  * One patch field, in the wire's own three-state encoding.
@@ -189,7 +190,8 @@ export class InvoicesResource {
      * `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.
+     * beside `outOfBand` is refused with a `VpayInvalidParamsError` naming it,
+     * before any request.
      */
     async pay(id, params, options) {
         const outOfBand = params.outOfBand;
@@ -200,7 +202,7 @@ export class InvoicesResource {
             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)`);
+                    throw new VpayInvalidParamsError(param, "has no meaning when recording a payment made outside vpay (outOfBand is set)");
                 }
             }
         }
@@ -253,7 +255,7 @@ export class InvoiceItemsResource {
      * `POST /v1/invoice_items` — adds a line to a draft, and the invoice's
      * `amount_due` moves with it.
      *
-     * Throws `TypeError` before any request when `unit_amount` is not a
+     * Throws `VpayInvalidParamsError` before any request when `unit_amount` is not a
      * non-negative safe integer; a `400` naming `invoice` when it is not one of
      * your drafts.
      */
@@ -277,7 +279,7 @@ export class InvoiceItemsResource {
      * `POST /v1/invoice_items/{id}` — **draft parent only**, with `amount`
      * recomputed.
      *
-     * Throws `TypeError` before any request for a `unit_amount` outside the
+     * Throws `VpayInvalidParamsError` before any request for a `unit_amount` outside the
      * bound; a `409` once the parent is no longer a draft.
      */
     async update(id, params, options) {

package/dist/types.d.ts

@@ -1109,8 +1109,8 @@ export interface CreateInvoiceItemParams {
     quantity?: number | undefined;
     /**
      * The price of one, in integer minor units. A non-integer, a negative, or
-     * anything past `Number.MAX_SAFE_INTEGER` throws `TypeError` before any
-     * request — `sdks/rust` refuses the identical set.
+     * anything past `Number.MAX_SAFE_INTEGER` throws `VpayInvalidParamsError`
+     * before any request — `sdks/rust` refuses the identical set.
      */
     unit_amount: number;
 }
@@ -1134,7 +1134,8 @@ export interface UpdateInvoiceItemParams {
 export interface CreatePaymentIntentParams {
     /**
      * Integer minor units. A non-integer, a negative, or anything past
-     * `Number.MAX_SAFE_INTEGER` throws `TypeError` before any request.
+     * `Number.MAX_SAFE_INTEGER` throws `VpayInvalidParamsError` before any
+     * request.
      */
     amount: number;
     currency: string;
@@ -1164,7 +1165,8 @@ export type OrangeMoneyPaymentMethodData = {
 /**
  * Notch Pay (RFC-0012, 2026-10-20): a push rail, so the same instrument as
  * MTN's, under this rail's own code. The server's adapter is proven against a
- * stub only and has never called Notch Pay.
+ * stub and took three test-mode payments through Notch Pay's real sandbox on
+ * 2026-10-21 (RFC-0012 step 5); it has never called Notch Pay's production.
  */
 export type NotchPayPaymentMethodData = {
     type: "notchpay";

package/dist/validate.d.ts

@@ -1,5 +1,8 @@
 /**
  * Shared request-shape validation, run before anything reaches the wire.
+ *
+ * Every refusal here is a {@link VpayInvalidParamsError}, so it is caught by
+ * the same `instanceof VpayError` as every other error this package throws.
  */
 /**
  * Mirrors `@vpay/api-client`'s `formatAmount` integer check
@@ -12,6 +15,8 @@
  * `Number.MAX_SAFE_INTEGER`, where the value the caller wrote and the value
  * JavaScript holds have already diverged. An amount must be a non-negative
  * **safe** integer or nothing goes to the wire.
+ *
+ * @throws {VpayInvalidParamsError} naming `field`.
  */
 export declare function assertIntegerAmount(amount: number, field?: string): void;
 /**
@@ -29,7 +34,6 @@ export declare function assertIntegerAmount(amount: number, field?: string): voi
  * standard: `docs/reference/rails.md` § "A path segment the caller chose"
  * says why.
  *
- * A `TypeError`, like {@link assertIntegerAmount}'s refusal, and not a
- * `VpayError` — the dated gap `docs/sdks/parity.md` records for both.
+ * @throws {VpayInvalidParamsError} naming `id`.
  */
 export declare function pathSegment(id: string): string;

package/dist/validate.js

@@ -1,6 +1,10 @@
 /**
  * Shared request-shape validation, run before anything reaches the wire.
+ *
+ * Every refusal here is a {@link VpayInvalidParamsError}, so it is caught by
+ * the same `instanceof VpayError` as every other error this package throws.
  */
+import { VpayInvalidParamsError } from "./errors.js";
 /**
  * Mirrors `@vpay/api-client`'s `formatAmount` integer check
  * (frontends/packages/api-client/src/index.ts) and
@@ -12,18 +16,21 @@
  * `Number.MAX_SAFE_INTEGER`, where the value the caller wrote and the value
  * JavaScript holds have already diverged. An amount must be a non-negative
  * **safe** integer or nothing goes to the wire.
+ *
+ * @throws {VpayInvalidParamsError} naming `field`.
  */
 export function assertIntegerAmount(amount, field = "amount") {
     if (!Number.isSafeInteger(amount) || amount < 0) {
-        throw new TypeError(`${field} must be a non-negative safe integer in minor units, got ${amount}`);
+        throw new VpayInvalidParamsError(field, `must be a non-negative safe integer in minor units, got ${amount}`);
     }
 }
 /**
  * The one message {@link pathSegment}'s refusal carries, whatever the id.
  *
  * Fixed so that it cannot quote the id, and byte-identical to `sdks/rust`'s
- * `DOT_SEGMENT_REFUSAL` behind the same `invalid request parameter id: `
- * prefix that crate's `Error::InvalidParams` displays.
+ * `DOT_SEGMENT_REFUSAL`. {@link VpayInvalidParamsError} puts the same
+ * `invalid request parameter id: ` prefix in front of it that crate's
+ * `Error::InvalidParams` displays.
  */
 const DOT_SEGMENT_REFUSAL = "an id that is empty or only dots would address a different endpoint once the URL is parsed; nothing was sent";
 /**
@@ -41,12 +48,11 @@ const DOT_SEGMENT_REFUSAL = "an id that is empty or only dots would address a di
  * standard: `docs/reference/rails.md` § "A path segment the caller chose"
  * says why.
  *
- * A `TypeError`, like {@link assertIntegerAmount}'s refusal, and not a
- * `VpayError` — the dated gap `docs/sdks/parity.md` records for both.
+ * @throws {VpayInvalidParamsError} naming `id`.
  */
 export function pathSegment(id) {
     if (/^\.*$/u.test(id)) {
-        throw new TypeError(`invalid request parameter id: ${DOT_SEGMENT_REFUSAL}`);
+        throw new VpayInvalidParamsError("id", DOT_SEGMENT_REFUSAL);
     }
     return encodeURIComponent(id);
 }

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.9.1";
+export declare const SDK_VERSION = "0.10.1";

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.9.1"; // x-release-please-version
+export const SDK_VERSION = "0.10.1"; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaam-apps/vpay-sdk",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "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": {