@vaam-apps/vpay-sdk 0.9.0 → 0.10.0

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,40 @@ 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
+dots, without minting a token or sending anything. No signature changed —
+each already returned a `Promise` — but the outcome for those inputs did.
+They used to be sent, and `fetch`'s URL parser resolved them before the
+request left, so `customers.del("..")` was a `DELETE /v1/` and
+`paymentIntents.retrieve("")` a `GET /v1/payment_intents/`; escaping cannot
+help, because the parser reads `%2E%2E` as `..` too. What vpay answered for
+each is on
+[the dated verification page](../../docs/status/verification/2026-10-21-sdk-dot-segment-ids.md).
+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`. _(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
 2026-09-02, and false since Step 2 landed the next day.
@@ -672,7 +707,17 @@ 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 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;
+  and, as the premise, that WHATWG `URL` resolves `..`, `%2E%2E` and `.%2e`
+  alike.
 - 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,
@@ -697,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/checkout-sessions.js

@@ -1,3 +1,4 @@
+import { pathSegment } from "../validate.js";
 const INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
 /**
  * The `url` of a hosted session with its fragment redacted.
@@ -89,7 +90,7 @@ export class CheckoutSessionsResource {
     }
     /** `GET /v1/checkout/sessions/{id}`. Answers the session with `client_secret`. */
     async retrieve(id) {
-        return withRedactedInspect(await this.#http.request("GET", `/checkout/sessions/${encodeURIComponent(id)}`));
+        return withRedactedInspect(await this.#http.request("GET", `/checkout/sessions/${pathSegment(id)}`));
     }
     /** `GET /v1/checkout/sessions`. List items never carry `client_secret`. */
     async list(params) {
@@ -106,7 +107,7 @@ export class CheckoutSessionsResource {
      * whose intent already has a live charge is refused `409`.
      */
     async expire(id, options) {
-        return withRedactedInspect(await this.#http.request("POST", `/checkout/sessions/${encodeURIComponent(id)}/expire`, {}, options));
+        return withRedactedInspect(await this.#http.request("POST", `/checkout/sessions/${pathSegment(id)}/expire`, {}, options));
     }
 }
 /**

package/dist/resources/customers.js

@@ -1,3 +1,4 @@
+import { pathSegment } from "../validate.js";
 /**
  * One patch field, in the wire's own three-state encoding.
  *
@@ -79,7 +80,7 @@ export class CustomersResource {
     }
     /** `GET /v1/customers/{id}`. */
     async retrieve(id) {
-        return this.#http.request("GET", `/customers/${encodeURIComponent(id)}`);
+        return this.#http.request("GET", `/customers/${pathSegment(id)}`);
     }
     /**
      * `POST /v1/customers/{id}` — the update.
@@ -116,7 +117,7 @@ export class CustomersResource {
         if (params.metadata !== undefined) {
             body["metadata"] = params.metadata;
         }
-        return this.#http.request("POST", `/customers/${encodeURIComponent(id)}`, body, options);
+        return this.#http.request("POST", `/customers/${pathSegment(id)}`, body, options);
     }
     /** `GET /v1/customers`. */
     async list(params) {
@@ -152,6 +153,6 @@ export class CustomersResource {
      * than a `404`.
      */
     async del(id, options) {
-        return this.#http.request("DELETE", `/customers/${encodeURIComponent(id)}`, undefined, options);
+        return this.#http.request("DELETE", `/customers/${pathSegment(id)}`, undefined, options);
     }
 }

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,4 +1,5 @@
-import { assertIntegerAmount } from "../validate.js";
+import { VpayInvalidParamsError } from "../errors.js";
+import { assertIntegerAmount, pathSegment } from "../validate.js";
 /**
  * One patch field, in the wire's own three-state encoding.
  *
@@ -61,7 +62,7 @@ export class InvoicesResource {
      * never existed.
      */
     async retrieve(id) {
-        return this.#http.request("GET", `/invoices/${encodeURIComponent(id)}`);
+        return this.#http.request("GET", `/invoices/${pathSegment(id)}`);
     }
     /**
      * `POST /v1/invoices/{id}` — patches a **draft**.
@@ -88,7 +89,7 @@ export class InvoicesResource {
         if (params.metadata !== undefined) {
             body["metadata"] = params.metadata;
         }
-        return this.#http.request("POST", `/invoices/${encodeURIComponent(id)}`, body, options);
+        return this.#http.request("POST", `/invoices/${pathSegment(id)}`, body, options);
     }
     /** `GET /v1/invoices` — newest first. */
     async list(params) {
@@ -107,7 +108,7 @@ export class InvoicesResource {
      * delete answer the original `{deleted: true}` rather than a `404`.
      */
     async del(id, options) {
-        return this.#http.request("DELETE", `/invoices/${encodeURIComponent(id)}`, undefined, options);
+        return this.#http.request("DELETE", `/invoices/${pathSegment(id)}`, undefined, options);
     }
     /**
      * `POST /v1/invoices/{id}/finalize` — issues the document. **Draft only.**
@@ -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)");
                 }
             }
         }
@@ -216,7 +218,7 @@ export class InvoicesResource {
                 },
             }
             : { success_url: params.success_url, cancel_url: params.cancel_url };
-        return this.#http.request("POST", `/invoices/${encodeURIComponent(id)}/pay`, body, options);
+        return this.#http.request("POST", `/invoices/${pathSegment(id)}/pay`, body, options);
     }
     /**
      * The three transitions that take no parameters, which are one shape:
@@ -228,7 +230,7 @@ export class InvoicesResource {
      * that is easy to get wrong in only one of them.
      */
     async #transition(id, name, options) {
-        return this.#http.request("POST", `/invoices/${encodeURIComponent(id)}/${name}`, {}, options);
+        return this.#http.request("POST", `/invoices/${pathSegment(id)}/${name}`, {}, options);
     }
 }
 /**
@@ -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.
      */
@@ -271,13 +273,13 @@ export class InvoiceItemsResource {
     }
     /** `GET /v1/invoice_items/{id}` — readable whatever the parent's status. */
     async retrieve(id) {
-        return this.#http.request("GET", `/invoice_items/${encodeURIComponent(id)}`);
+        return this.#http.request("GET", `/invoice_items/${pathSegment(id)}`);
     }
     /**
      * `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) {
@@ -294,13 +296,13 @@ export class InvoiceItemsResource {
         if (params.unit_amount !== undefined) {
             body["unit_amount"] = params.unit_amount;
         }
-        return this.#http.request("POST", `/invoice_items/${encodeURIComponent(id)}`, body, options);
+        return this.#http.request("POST", `/invoice_items/${pathSegment(id)}`, body, options);
     }
     /**
      * `DELETE /v1/invoice_items/{id}` — **draft parent only**, and the invoice
      * re-totals.
      */
     async del(id, options) {
-        return this.#http.request("DELETE", `/invoice_items/${encodeURIComponent(id)}`, undefined, options);
+        return this.#http.request("DELETE", `/invoice_items/${pathSegment(id)}`, undefined, options);
     }
 }

package/dist/resources/payment-intents.js

@@ -1,4 +1,4 @@
-import { assertIntegerAmount } from "../validate.js";
+import { assertIntegerAmount, pathSegment } from "../validate.js";
 /** `/v1/payment_intents` — docs/flows/merchant-auth.md, "Resources". */
 export class PaymentIntentsResource {
     #http;
@@ -24,7 +24,7 @@ export class PaymentIntentsResource {
         return this.#http.request("POST", "/payment_intents", body, options);
     }
     async retrieve(id) {
-        return this.#http.request("GET", `/payment_intents/${encodeURIComponent(id)}`);
+        return this.#http.request("GET", `/payment_intents/${pathSegment(id)}`);
     }
     async confirm(id, params, options) {
         const body = {
@@ -33,10 +33,10 @@ export class PaymentIntentsResource {
         if ("return_url" in params) {
             body["return_url"] = params.return_url;
         }
-        return this.#http.request("POST", `/payment_intents/${encodeURIComponent(id)}/confirm`, body, options);
+        return this.#http.request("POST", `/payment_intents/${pathSegment(id)}/confirm`, body, options);
     }
     async cancel(id, options) {
-        return this.#http.request("POST", `/payment_intents/${encodeURIComponent(id)}/cancel`, {}, options);
+        return this.#http.request("POST", `/payment_intents/${pathSegment(id)}/cancel`, {}, options);
     }
     /** `GET /v1/payment_intents`, newest first; `customer` narrows it. */
     async list(params) {

package/dist/resources/refunds.js

@@ -1,4 +1,4 @@
-import { assertIntegerAmount } from "../validate.js";
+import { assertIntegerAmount, pathSegment } from "../validate.js";
 /**
  * The rail-agnostic envelope, built around the rail-specific interior.
  *
@@ -62,7 +62,7 @@ export class RefundsResource {
      * order.
      */
     async retrieve(id) {
-        return this.#http.request("GET", `/refunds/${encodeURIComponent(id)}`);
+        return this.#http.request("GET", `/refunds/${pathSegment(id)}`);
     }
     /**
      * `POST /v1/refunds/{id}` — the **metadata** update, and nothing else.
@@ -82,7 +82,7 @@ export class RefundsResource {
         if (params.metadata !== undefined) {
             body["metadata"] = params.metadata;
         }
-        return this.#http.request("POST", `/refunds/${encodeURIComponent(id)}`, body, options);
+        return this.#http.request("POST", `/refunds/${pathSegment(id)}`, body, options);
     }
     /** `GET /v1/refunds` — this merchant's refunds, newest first. */
     async list(params) {
@@ -101,6 +101,6 @@ export class RefundsResource {
      * rail was ever told to start. See the module doc.
      */
     async cancel(id, options) {
-        return this.#http.request("POST", `/refunds/${encodeURIComponent(id)}/cancel`, {}, options);
+        return this.#http.request("POST", `/refunds/${pathSegment(id)}/cancel`, {}, 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,5 +15,25 @@
  * `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;
+/**
+ * Percent-encodes one merchant-supplied id for a URL path, and refuses the
+ * ids escaping cannot keep in place.
+ *
+ * `encodeURIComponent` keeps a `/`, `?` or `#` inside its segment, but it
+ * leaves `.` alone, so `""`, `.` and `..` pass through, and as whole segments
+ * `fetch`'s URL parser resolves them before the request leaves:
+ * `customers.del("..")` was a `DELETE /v1/`. Escaping the dots would not
+ * help, because WHATWG parsing reads `%2E%2E` as `..` too. So an empty or
+ * all-dots id throws before anything is sent, the token request included —
+ * `sdks/rust`'s `path_segment` refuses the same ids with
+ * `Error::InvalidParams`. `...` is refused by decision rather than by the
+ * standard: `docs/reference/rails.md` § "A path segment the caller chose"
+ * says why.
+ *
+ * @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,9 +16,43 @@
  * `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`. {@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";
+/**
+ * Percent-encodes one merchant-supplied id for a URL path, and refuses the
+ * ids escaping cannot keep in place.
+ *
+ * `encodeURIComponent` keeps a `/`, `?` or `#` inside its segment, but it
+ * leaves `.` alone, so `""`, `.` and `..` pass through, and as whole segments
+ * `fetch`'s URL parser resolves them before the request leaves:
+ * `customers.del("..")` was a `DELETE /v1/`. Escaping the dots would not
+ * help, because WHATWG parsing reads `%2E%2E` as `..` too. So an empty or
+ * all-dots id throws before anything is sent, the token request included —
+ * `sdks/rust`'s `path_segment` refuses the same ids with
+ * `Error::InvalidParams`. `...` is refused by decision rather than by the
+ * standard: `docs/reference/rails.md` § "A path segment the caller chose"
+ * says why.
+ *
+ * @throws {VpayInvalidParamsError} naming `id`.
+ */
+export function pathSegment(id) {
+    if (/^\.*$/u.test(id)) {
+        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.0";
+export declare const SDK_VERSION = "0.10.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.9.0"; // x-release-please-version
+export const SDK_VERSION = "0.10.0"; // x-release-please-version

package/package.json

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