@vaam-apps/vpay-sdk 0.8.0 → 0.9.1

package/README.md

@@ -591,6 +591,22 @@ VPAY_AUDIENCE=https://api.vpay.example/v1/oauth/token \
 
 ## Status
 
+**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 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.
@@ -673,6 +689,12 @@ none of them touches the network:
   `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
+  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,

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.js

@@ -1,4 +1,4 @@
-import { assertIntegerAmount } from "../validate.js";
+import { assertIntegerAmount, pathSegment } from "../validate.js";
 /**
  * One patch field, in the wire's own three-state encoding.
  *
@@ -61,7 +61,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 +88,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 +107,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.**
@@ -216,7 +216,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 +228,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);
     }
 }
 /**
@@ -271,7 +271,7 @@ 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`
@@ -294,13 +294,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.d.ts

@@ -10,6 +10,9 @@
  *
  * - `orange_money`'s refund is a declared `NotImplemented` token — an Orange
  *   refund is an outbound transfer this repository has no specification for;
+ * - `notchpay`'s refund is a declared `NotImplemented` token too — Notch Pay
+ *   documents refunds in a guide only, with nothing that makes a replay safe
+ *   (RFC-0012 § 7);
  * - `mtn_momo`'s is MTN's Disbursements `transfer`, WireMock-proven and
  *   rail-unproven: **no real MTN Disbursements credential exists in this
  *   project** — the only `disbursement_subscription_key` anywhere is the stub

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

@@ -10,7 +10,7 @@
  */
 export type PaymentIntentStatus = "requires_payment_method" | "requires_action" | "processing" | "succeeded" | "canceled";
 /** Rail codes this SDK's `payment_method_types` values may hold. */
-export type PaymentMethodType = "mtn_momo" | "orange_money";
+export type PaymentMethodType = "mtn_momo" | "orange_money" | "notchpay";
 /** Redirect-rail next step, Stripe's own `next_action.redirect_to_url` shape. */
 export interface NextAction {
     type: "redirect_to_url";
@@ -1161,8 +1161,21 @@ export type MtnMomoPaymentMethodData = {
 export type OrangeMoneyPaymentMethodData = {
     type: "orange_money";
 };
+/**
+ * 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.
+ */
+export type NotchPayPaymentMethodData = {
+    type: "notchpay";
+    notchpay: {
+        msisdn: string;
+    };
+};
 export type ConfirmPaymentIntentParams = {
     payment_method_data: MtnMomoPaymentMethodData;
+} | {
+    payment_method_data: NotchPayPaymentMethodData;
 } | {
     payment_method_data: OrangeMoneyPaymentMethodData;
     return_url: string;
@@ -1323,8 +1336,8 @@ export type RefundDestination = {
  * # No refund this creates has ever moved money
  *
  * The route is real and so is every refusal it makes, but nothing on the
- * other side of it pays anybody: `orange_money`'s refund is a declared
- * `NotImplemented` token, `mtn_momo`'s is MTN's Disbursements `transfer`
+ * other side of it pays anybody: `orange_money`'s and `notchpay`'s refunds
+ * are declared `NotImplemented` tokens, `mtn_momo`'s is MTN's Disbursements `transfer`
  * which is WireMock-proven and for which **no real MTN credential exists in
  * this project** — the only `disbursement_subscription_key` anywhere is the
  * stub the e2e/demo stack points at a WireMock container, and the product has
@@ -1352,10 +1365,12 @@ export interface CreateRefundParams {
      *
      * Optional because the port allows a rail that refunds to the instrument
      * that paid, and such a rail refuses a `destination` with a `400`.
-     * **Neither rail vpay carries today is one**: `mtn_momo` and `orange_money`
-     * both declare that a refund needs a payee, so a create with no
-     * `destination` is a `400` naming `destination` against every deployment
-     * this repository can build.
+     * `mtn_momo` and `orange_money` both declare that a refund needs a payee,
+     * so a create with no `destination` is a `400` naming `destination` on
+     * either. `notchpay` (2026-10-20) is the first shipping rail that refunds
+     * to the instrument that paid and so refuses one — but its refund is a
+     * declared `NotImplemented` token, so a refund there fails whatever it
+     * carries.
      */
     destination?: RefundDestination | undefined;
     metadata?: Record<string, string> | undefined;

package/dist/validate.d.ts

@@ -14,3 +14,22 @@
  * **safe** integer or nothing goes to the wire.
  */
 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.
+ *
+ * A `TypeError`, like {@link assertIntegerAmount}'s refusal, and not a
+ * `VpayError` — the dated gap `docs/sdks/parity.md` records for both.
+ */
+export declare function pathSegment(id: string): string;

package/dist/validate.js

@@ -18,3 +18,35 @@ export function assertIntegerAmount(amount, field = "amount") {
         throw new TypeError(`${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.
+ */
+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.
+ *
+ * A `TypeError`, like {@link assertIntegerAmount}'s refusal, and not a
+ * `VpayError` — the dated gap `docs/sdks/parity.md` records for both.
+ */
+export function pathSegment(id) {
+    if (/^\.*$/u.test(id)) {
+        throw new TypeError(`invalid request parameter 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.8.0";
+export declare const SDK_VERSION = "0.9.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.8.0"; // x-release-please-version
+export const SDK_VERSION = "0.9.1"; // x-release-please-version

package/package.json

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