@vaam-apps/vpay-sdk 0.2.1

package/dist/errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Error taxonomy for `@vaam-apps/vpay-sdk`, per docs/flows/merchant-auth.md's
+ * "Errors" section and the token-endpoint error shape it documents.
+ *
+ * Every error extends {@link VpayError} so callers can `catch (err) { if
+ * (err instanceof VpayError) ... }` once and still narrow further by
+ * `err.name` or an `instanceof` check on a specific subclass.
+ */
+/** Base class for every error this SDK throws. */
+export declare class VpayError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A non-2xx response from a `/v1` resource route, shaped like
+ * `vpay_api::error_envelope`: `{ "error": { "type", "code", "message",
+ * "param" } }`.
+ */
+export declare class VpayApiError extends VpayError {
+    /** The HTTP status code of the response. */
+    readonly status: number;
+    /** Stripe-shaped error type, e.g. `invalid_request_error`. */
+    readonly type: string;
+    /** Machine-readable error code, when the server sent one. */
+    readonly code: string | undefined;
+    /** The offending request parameter, when the server named one. */
+    readonly param: string | undefined;
+    constructor(status: number, body: {
+        type: string;
+        code?: string | undefined;
+        message: string;
+        param?: string | undefined;
+    });
+}
+/**
+ * A `400`/`401` from the OAuth2 token endpoint:
+ * `{ "error": "invalid_client", "error_description": "…" }`
+ * (`TokenErrorResponse` in `authkestra-op`). Never retried automatically —
+ * see docs/flows/merchant-auth.md, "Re-authentication".
+ */
+export declare class VpayAuthError extends VpayError {
+    /** The OAuth2 `error` code, e.g. `invalid_client`. */
+    readonly error: string;
+    /** Human-readable detail, when the server sent one. */
+    readonly errorDescription: string | undefined;
+    constructor(error: string, errorDescription: string | undefined);
+}
+/**
+ * A response that is not the Stripe-shaped error envelope this SDK expects —
+ * a proxy's HTML 502, an empty body, or JSON with an unrecognised shape.
+ * Carries a bounded prefix of the body so the cause is diagnosable without
+ * risking an unbounded string in logs.
+ */
+export declare class VpayUnexpectedResponseError extends VpayError {
+    /** The HTTP status code of the response. */
+    readonly status: number;
+    /** At most the first 500 **bytes** of the response body, decoded as UTF-8. */
+    readonly bodyPrefix: string;
+    constructor(status: number, bodyPrefix: string);
+}
+/** A transport-level failure — DNS, TLS, connection refused, timeout. */
+export declare class VpayTransportError extends VpayError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * The SDK was configured incorrectly — caught before any request is sent.
+ *
+ * Almost always at construction (a missing `clientId`, an unreadable
+ * `privateKey`, an `assertionLifetimeSeconds` outside the OP's `1..=300`).
+ * The one exception is `@vaam-apps/vpay-sdk/stripe`'s host binding: an authenticator
+ * asked to sign a request addressed somewhere other than its `baseUrl`
+ * throws this *per request*, because that is when the destination becomes
+ * knowable. Still before anything is sent — no token is minted and no
+ * `Authorization` header is written.
+ */
+export declare class VpayConfigError extends VpayError {
+}
+/** A webhook signature failed verification — see {@link verifyWebhook}. */
+export declare class WebhookSignatureError extends VpayError {
+}
+/**
+ * Truncates a response body to a bounded prefix for
+ * {@link VpayUnexpectedResponseError}.
+ *
+ * The bound is on **bytes**, not `String.prototype.length`: a body of
+ * multi-byte characters (a UTF-8 error page, a JSON body of CJK text) is up
+ * to four times its code-unit count on the wire, and the point of the bound
+ * is to keep an unbounded response out of a log line. `TextDecoder` is used
+ * in streaming mode and never flushed, so a multi-byte character straddling
+ * the cut is dropped rather than emitted as a replacement character.
+ */
+export declare function boundedBodyPrefix(body: string): string;

package/dist/errors.js

@@ -0,0 +1,112 @@
+/**
+ * Error taxonomy for `@vaam-apps/vpay-sdk`, per docs/flows/merchant-auth.md's
+ * "Errors" section and the token-endpoint error shape it documents.
+ *
+ * Every error extends {@link VpayError} so callers can `catch (err) { if
+ * (err instanceof VpayError) ... }` once and still narrow further by
+ * `err.name` or an `instanceof` check on a specific subclass.
+ */
+/** Base class for every error this SDK throws. */
+export class VpayError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/**
+ * A non-2xx response from a `/v1` resource route, shaped like
+ * `vpay_api::error_envelope`: `{ "error": { "type", "code", "message",
+ * "param" } }`.
+ */
+export class VpayApiError extends VpayError {
+    /** The HTTP status code of the response. */
+    status;
+    /** Stripe-shaped error type, e.g. `invalid_request_error`. */
+    type;
+    /** Machine-readable error code, when the server sent one. */
+    code;
+    /** The offending request parameter, when the server named one. */
+    param;
+    constructor(status, body) {
+        super(body.message);
+        this.status = status;
+        this.type = body.type;
+        this.code = body.code;
+        this.param = body.param;
+    }
+}
+/**
+ * A `400`/`401` from the OAuth2 token endpoint:
+ * `{ "error": "invalid_client", "error_description": "…" }`
+ * (`TokenErrorResponse` in `authkestra-op`). Never retried automatically —
+ * see docs/flows/merchant-auth.md, "Re-authentication".
+ */
+export class VpayAuthError extends VpayError {
+    /** The OAuth2 `error` code, e.g. `invalid_client`. */
+    error;
+    /** Human-readable detail, when the server sent one. */
+    errorDescription;
+    constructor(error, errorDescription) {
+        super(errorDescription ? `${error}: ${errorDescription}` : error);
+        this.error = error;
+        this.errorDescription = errorDescription;
+    }
+}
+/**
+ * A response that is not the Stripe-shaped error envelope this SDK expects —
+ * a proxy's HTML 502, an empty body, or JSON with an unrecognised shape.
+ * Carries a bounded prefix of the body so the cause is diagnosable without
+ * risking an unbounded string in logs.
+ */
+export class VpayUnexpectedResponseError extends VpayError {
+    /** The HTTP status code of the response. */
+    status;
+    /** At most the first 500 **bytes** of the response body, decoded as UTF-8. */
+    bodyPrefix;
+    constructor(status, bodyPrefix) {
+        super(`unexpected response (status ${status}): ${bodyPrefix.slice(0, 200)}`);
+        this.status = status;
+        this.bodyPrefix = bodyPrefix;
+    }
+}
+/** A transport-level failure — DNS, TLS, connection refused, timeout. */
+export class VpayTransportError extends VpayError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/**
+ * The SDK was configured incorrectly — caught before any request is sent.
+ *
+ * Almost always at construction (a missing `clientId`, an unreadable
+ * `privateKey`, an `assertionLifetimeSeconds` outside the OP's `1..=300`).
+ * The one exception is `@vaam-apps/vpay-sdk/stripe`'s host binding: an authenticator
+ * asked to sign a request addressed somewhere other than its `baseUrl`
+ * throws this *per request*, because that is when the destination becomes
+ * knowable. Still before anything is sent — no token is minted and no
+ * `Authorization` header is written.
+ */
+export class VpayConfigError extends VpayError {
+}
+/** A webhook signature failed verification — see {@link verifyWebhook}. */
+export class WebhookSignatureError extends VpayError {
+}
+const BODY_PREFIX_LIMIT_BYTES = 500;
+/**
+ * Truncates a response body to a bounded prefix for
+ * {@link VpayUnexpectedResponseError}.
+ *
+ * The bound is on **bytes**, not `String.prototype.length`: a body of
+ * multi-byte characters (a UTF-8 error page, a JSON body of CJK text) is up
+ * to four times its code-unit count on the wire, and the point of the bound
+ * is to keep an unbounded response out of a log line. `TextDecoder` is used
+ * in streaming mode and never flushed, so a multi-byte character straddling
+ * the cut is dropped rather than emitted as a replacement character.
+ */
+export function boundedBodyPrefix(body) {
+    const bytes = Buffer.from(body, "utf8");
+    if (bytes.length <= BODY_PREFIX_LIMIT_BYTES) {
+        return body;
+    }
+    return new TextDecoder("utf-8").decode(bytes.subarray(0, BODY_PREFIX_LIMIT_BYTES), { stream: true });
+}

package/dist/form.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Stripe's bracket-nested `application/x-www-form-urlencoded` encoding
+ * (docs/flows/merchant-auth.md, "Encoding" table), used for every request
+ * body and — identically — every `GET` query string.
+ *
+ * | Shape | Wire form |
+ * |---|---|
+ * | scalar | `amount=5000` |
+ * | nested object | `metadata[order_id]=1234` |
+ * | array | `payment_method_types[0]=mtn_momo&payment_method_types[1]=…` (indexed) |
+ * | boolean | `true` / `false` |
+ * | `undefined` | omitted entirely |
+ *
+ * A key is carried through the flattener as an **array of path segments**, and
+ * only assembled into wire syntax at the very end. The brackets a nested key
+ * is written with are therefore structural — produced by this encoder — while
+ * every segment, including one a merchant supplied containing `[` or `]`, is
+ * percent-encoded via `encodeURIComponent`. (An earlier version re-parsed the
+ * assembled key with a bracket regex, which silently corrupted a merchant key
+ * such as `metadata: { "a[b]": "x" }` into `metadata[b]=x`.)
+ *
+ * Two things are refused rather than silently mangled, because both would
+ * otherwise reach a payment API as something other than what the caller wrote:
+ *
+ * - a value that is an object but not a plain one (a `Date`, a `Map`, a class
+ *   instance) — `Object.entries` on it yields no own enumerable keys, so it
+ *   would vanish from the request entirely;
+ * - a number that is not a non-negative-or-negative *safe* integer, or whose
+ *   `String()` form carries an exponent (`1e21` → `1e+21`). vpay's wire format
+ *   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.
+ */
+/** A value the form encoder can flatten. `null` is treated like `undefined`: omitted. */
+export type FormValue = string | number | boolean | undefined | null | readonly FormValue[] | {
+    [key: string]: FormValue;
+};
+/**
+ * Flattens a params object into ordered `[path segments, value]` pairs.
+ *
+ * The key is still segments at this point, deliberately: assembling it into
+ * `a[b][c]` before encoding is what made merchant-supplied brackets
+ * ambiguous.
+ */
+export declare function flattenForm(params: Record<string, FormValue>): Array<[readonly string[], string]>;
+/** Encodes `params` as an `application/x-www-form-urlencoded` body (or query string). */
+export declare function encodeForm(params: Record<string, FormValue>): string;

package/dist/form.js

@@ -0,0 +1,127 @@
+/**
+ * Stripe's bracket-nested `application/x-www-form-urlencoded` encoding
+ * (docs/flows/merchant-auth.md, "Encoding" table), used for every request
+ * body and — identically — every `GET` query string.
+ *
+ * | Shape | Wire form |
+ * |---|---|
+ * | scalar | `amount=5000` |
+ * | nested object | `metadata[order_id]=1234` |
+ * | array | `payment_method_types[0]=mtn_momo&payment_method_types[1]=…` (indexed) |
+ * | boolean | `true` / `false` |
+ * | `undefined` | omitted entirely |
+ *
+ * A key is carried through the flattener as an **array of path segments**, and
+ * only assembled into wire syntax at the very end. The brackets a nested key
+ * is written with are therefore structural — produced by this encoder — while
+ * every segment, including one a merchant supplied containing `[` or `]`, is
+ * percent-encoded via `encodeURIComponent`. (An earlier version re-parsed the
+ * assembled key with a bracket regex, which silently corrupted a merchant key
+ * such as `metadata: { "a[b]": "x" }` into `metadata[b]=x`.)
+ *
+ * Two things are refused rather than silently mangled, because both would
+ * otherwise reach a payment API as something other than what the caller wrote:
+ *
+ * - a value that is an object but not a plain one (a `Date`, a `Map`, a class
+ *   instance) — `Object.entries` on it yields no own enumerable keys, so it
+ *   would vanish from the request entirely;
+ * - a number that is not a non-negative-or-negative *safe* integer, or whose
+ *   `String()` form carries an exponent (`1e21` → `1e+21`). vpay's wire format
+ *   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.
+ */
+/** Renders a path back into the bracket syntax, for error messages only. */
+function describePath(path) {
+    const [head, ...rest] = path;
+    return `${head ?? ""}${rest.map((segment) => `[${segment}]`).join("")}`;
+}
+/**
+ * True only for `{}`-shaped values: an object literal, or one created with a
+ * null prototype. A `Date`, `Map`, `URL` or class instance is not one. Nor,
+ * deliberately, is a plain object from another realm (`node:vm`,
+ * `worker_threads`) — its prototype is that realm's `Object.prototype`, not
+ * this one's — so structured data crossing a realm boundary must be
+ * re-created (e.g. via `JSON.parse(JSON.stringify(..))`) before it is
+ * encoded, rather than silently accepted on one side and refused on the
+ * other.
+ */
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** 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}`);
+    }
+    const text = String(value);
+    // Subsumed by the check above as the language stands today — JavaScript
+    // renders every integer below 1e21 without an exponent, and 1e21 is far
+    // past `Number.MAX_SAFE_INTEGER`, so no safe integer reaches here with an
+    // `e` in it. Kept as an independent guard on the one property the wire
+    // 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}`);
+    }
+    return text;
+}
+function flattenValue(path, value, out) {
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => flattenValue([...path, String(index)], item, out));
+        return;
+    }
+    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"}`);
+        }
+        for (const [childKey, childValue] of Object.entries(value)) {
+            flattenValue([...path, childKey], childValue, out);
+        }
+        return;
+    }
+    if (typeof value === "boolean") {
+        out.push([path, value ? "true" : "false"]);
+        return;
+    }
+    if (typeof value === "number") {
+        out.push([path, encodeNumber(value, path)]);
+        return;
+    }
+    out.push([path, value]);
+}
+/**
+ * Flattens a params object into ordered `[path segments, value]` pairs.
+ *
+ * The key is still segments at this point, deliberately: assembling it into
+ * `a[b][c]` before encoding is what made merchant-supplied brackets
+ * ambiguous.
+ */
+export function flattenForm(params) {
+    const out = [];
+    for (const [key, value] of Object.entries(params)) {
+        flattenValue([key], value, out);
+    }
+    return out;
+}
+/**
+ * Assembles one flattened path into wire syntax: every segment percent-encoded,
+ * the brackets between them literal.
+ */
+function encodePath(path) {
+    const [head, ...rest] = path;
+    const encodedRest = rest
+        .map((segment) => `[${encodeURIComponent(segment)}]`)
+        .join("");
+    return `${encodeURIComponent(head ?? "")}${encodedRest}`;
+}
+/** Encodes `params` as an `application/x-www-form-urlencoded` body (or query string). */
+export function encodeForm(params) {
+    return flattenForm(params)
+        .map(([path, value]) => `${encodePath(path)}=${encodeURIComponent(value)}`)
+        .join("&");
+}

package/dist/http.d.ts

@@ -0,0 +1,33 @@
+import type { TokenManager } from "./auth.js";
+import { type FormValue } from "./form.js";
+import type { RequestOptions } from "./types.js";
+export interface HttpClientOptions {
+    baseUrl: string;
+    tokenManager: TokenManager;
+    fetchImpl: typeof fetch;
+    timeoutMs: number;
+    userAgent: string;
+}
+/**
+ * `DELETE` since 2026-09-06 (S4a) — `DELETE /v1/customers/{id}` is the one
+ * this API has. It is handled as a write below, not as a read: it carries an
+ * `Idempotency-Key` and, deliberately, **no body**.
+ *
+ * The header is the server's contract (`docs/flows/merchant-auth.md`: every
+ * write under `/v1` carries one) and it is the verb where a replay is most
+ * confusing without it — the second call would otherwise answer `404` for a
+ * deletion that succeeded, which a merchant retrying a timed-out request
+ * cannot tell from "somebody else deleted it".
+ *
+ * No body, because an empty `application/x-www-form-urlencoded` body and no
+ * body are different requests to some proxies, and the request hash the
+ * server stores against the idempotency key is taken over the bytes.
+ */
+type HttpMethod = "GET" | "POST" | "DELETE";
+/** Thin wrapper over `fetch` implementing the merchant-auth wire contract for `/v1`. */
+export declare class HttpClient {
+    #private;
+    constructor(options: HttpClientOptions);
+    request<T>(method: HttpMethod, path: string, params?: Record<string, FormValue>, requestOptions?: RequestOptions): Promise<T>;
+}
+export {};

package/dist/http.js

@@ -0,0 +1,115 @@
+/**
+ * The `/v1` resource HTTP layer: request encoding, headers, the single
+ * 401-triggered re-auth retry, and error-envelope mapping
+ * (docs/flows/merchant-auth.md, "Headers"/"Errors"/"Re-authentication").
+ */
+import { randomUUID } from "node:crypto";
+import { VpayApiError, VpayTransportError, VpayUnexpectedResponseError, boundedBodyPrefix, } from "./errors.js";
+import { encodeForm } from "./form.js";
+function isErrorEnvelope(value) {
+    if (typeof value !== "object" || value === null || !("error" in value)) {
+        return false;
+    }
+    const err = value.error;
+    return (typeof err === "object" &&
+        err !== null &&
+        typeof err["type"] === "string" &&
+        typeof err["message"] === "string");
+}
+/** Thin wrapper over `fetch` implementing the merchant-auth wire contract for `/v1`. */
+export class HttpClient {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    async request(method, path, params, requestOptions) {
+        let url = `${this.#options.baseUrl}${path}`;
+        let body;
+        const headers = {
+            Accept: "application/json",
+            "User-Agent": this.#options.userAgent,
+        };
+        if (method === "GET") {
+            if (params) {
+                const query = encodeForm(params);
+                if (query.length > 0) {
+                    url += `?${query}`;
+                }
+            }
+        }
+        else if (method === "DELETE") {
+            // Keyed like every other write, and `body` is left `undefined` — see
+            // the `HttpMethod` comment for why both halves are deliberate.
+            headers["Idempotency-Key"] =
+                requestOptions?.idempotencyKey ?? randomUUID();
+        }
+        else {
+            body = params ? encodeForm(params) : "";
+            headers["Content-Type"] = "application/x-www-form-urlencoded";
+            headers["Idempotency-Key"] =
+                requestOptions?.idempotencyKey ?? randomUUID();
+        }
+        // `headers` and `body` are built once, above the retry loop, and the
+        // 401 re-auth below reuses them untouched — only `Authorization` is
+        // rewritten. The second attempt therefore carries a byte-identical
+        // `Idempotency-Key` and body, so a re-auth can never double-create
+        // (docs/flows/merchant-auth.md, "Headers"/"Re-authentication").
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
+            const token = await this.#options.tokenManager.getToken();
+            headers["Authorization"] = `Bearer ${token}`;
+            let status;
+            let ok;
+            let text;
+            try {
+                const init = {
+                    method,
+                    headers,
+                    signal: AbortSignal.timeout(this.#options.timeoutMs),
+                };
+                if (body !== undefined) {
+                    init.body = body;
+                }
+                const response = await this.#options.fetchImpl(url, init);
+                status = response.status;
+                ok = response.ok;
+                // Read the body inside the same `try`. `fetch` resolves as soon as the
+                // response headers arrive, so a stalled or truncated body — or the
+                // timeout signal firing mid-stream — rejects *here*, not at the call
+                // above. Outside this block that rejection escapes as a raw
+                // `DOMException: TimeoutError` instead of a `VpayTransportError`.
+                text = await response.text();
+            }
+            catch (err) {
+                throw new VpayTransportError("request failed", { cause: err });
+            }
+            if (status === 401 && attempt === 1) {
+                this.#options.tokenManager.invalidate();
+                continue;
+            }
+            return this.#mapResponse(status, ok, text);
+        }
+    }
+    #mapResponse(status, ok, text) {
+        if (ok) {
+            try {
+                return (text.length > 0 ? JSON.parse(text) : undefined);
+            }
+            catch {
+                throw new VpayUnexpectedResponseError(status, boundedBodyPrefix(text));
+            }
+        }
+        let parsed;
+        try {
+            parsed = text.length > 0 ? JSON.parse(text) : undefined;
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (isErrorEnvelope(parsed)) {
+            throw new VpayApiError(status, parsed.error);
+        }
+        throw new VpayUnexpectedResponseError(status, boundedBodyPrefix(text));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@vaam-apps/vpay-sdk` — the Node.js merchant SDK for vpay.
+ *
+ * See README.md for the handshake, a usage example, and this package's own
+ * Status section (the server serves `/v1/oauth` and the `/v1` auth boundary;
+ * no `/v1` resource route exists yet).
+ */
+export { VpayClient, type VpayClientOptions } from "./client.js";
+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 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 { isCheckoutSessionEvent, isInvoiceEvent, isPaymentIntentEvent, isRefundEvent, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@vaam-apps/vpay-sdk` — the Node.js merchant SDK for vpay.
+ *
+ * See README.md for the handshake, a usage example, and this package's own
+ * Status section (the server serves `/v1/oauth` and the `/v1` auth boundary;
+ * no `/v1` resource route exists yet).
+ */
+export { VpayClient } from "./client.js";
+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 { isCheckoutSessionEvent, isInvoiceEvent, isPaymentIntentEvent, isRefundEvent, } from "./types.js";

package/dist/resources/account-holders.d.ts

@@ -0,0 +1,36 @@
+import type { HttpClient } from "../http.js";
+import type { AccountHolder, RetrieveAccountHolderParams } from "../types.js";
+/**
+ * `/v1/account_holders` — whose mobile-money account a number is
+ * (issue #47).
+ *
+ * The one resource on this surface that returns a **third party's** name.
+ * vpay projects the rail's answer down to a name, logs neither the name nor
+ * the unmasked number, and stores nothing;
+ * `docs/flows/account-holder-lookup.md` is the policy, and an integrator
+ * holding the returned name inherits the same obligation.
+ */
+export declare class AccountHoldersResource {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * `GET /v1/account_holders`.
+     *
+     * `name` is `null` when **the rail has no record** of the number. It is
+     * never `null` because vpay could not ask: that case throws
+     * (`VpayApiError`, `502` for a rail that could not be reached, `400` for a
+     * rail with no such API), so a caller matching a name can tell "not
+     * registered" from "not checked". Both are refusals; only one of them is
+     * the payer's to fix.
+     *
+     * Nothing is validated locally — not the number's shape, not whether the
+     * rail can answer. The first is a *market* rule vpay owns and may widen,
+     * and an SDK copy would refuse offline a number a later server version
+     * accepts; the second is a property of the deployment. Both come back as a
+     * `400` naming the parameter, which is the same information one round trip
+     * later. `sdks/rust`'s `RetrieveAccountHolderParams` takes the identical
+     * line, which is what keeps the two at parity on the refusals as well as
+     * the acceptances.
+     */
+    retrieve(params: RetrieveAccountHolderParams): Promise<AccountHolder>;
+}

package/dist/resources/account-holders.js

@@ -0,0 +1,46 @@
+/**
+ * `/v1/account_holders` — whose mobile-money account a number is
+ * (issue #47).
+ *
+ * The one resource on this surface that returns a **third party's** name.
+ * vpay projects the rail's answer down to a name, logs neither the name nor
+ * the unmasked number, and stores nothing;
+ * `docs/flows/account-holder-lookup.md` is the policy, and an integrator
+ * holding the returned name inherits the same obligation.
+ */
+export class AccountHoldersResource {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    /**
+     * `GET /v1/account_holders`.
+     *
+     * `name` is `null` when **the rail has no record** of the number. It is
+     * never `null` because vpay could not ask: that case throws
+     * (`VpayApiError`, `502` for a rail that could not be reached, `400` for a
+     * rail with no such API), so a caller matching a name can tell "not
+     * registered" from "not checked". Both are refusals; only one of them is
+     * the payer's to fix.
+     *
+     * Nothing is validated locally — not the number's shape, not whether the
+     * rail can answer. The first is a *market* rule vpay owns and may widen,
+     * and an SDK copy would refuse offline a number a later server version
+     * accepts; the second is a property of the deployment. Both come back as a
+     * `400` naming the parameter, which is the same information one round trip
+     * later. `sdks/rust`'s `RetrieveAccountHolderParams` takes the identical
+     * line, which is what keeps the two at parity on the refusals as well as
+     * the acceptances.
+     */
+    async retrieve(params) {
+        // Built explicitly rather than spread from `params`, and in this order:
+        // the encoder walks insertion order, and `sdks/rust/tests/resources.rs`
+        // pins the identical query string byte for byte. A spread would make the
+        // wire depend on how a caller happened to write their object literal.
+        const query = {
+            msisdn: params.msisdn,
+            payment_method_type: params.payment_method_type,
+        };
+        return this.#http.request("GET", "/account_holders", query);
+    }
+}

package/dist/resources/balance.d.ts

@@ -0,0 +1,8 @@
+import type { HttpClient } from "../http.js";
+import type { Balance } from "../types.js";
+/** `/v1/balance` — docs/flows/merchant-auth.md, "Resources". */
+export declare class BalanceResource {
+    #private;
+    constructor(http: HttpClient);
+    retrieve(): Promise<Balance>;
+}

package/dist/resources/balance.js

@@ -0,0 +1,10 @@
+/** `/v1/balance` — docs/flows/merchant-auth.md, "Resources". */
+export class BalanceResource {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    async retrieve() {
+        return this.#http.request("GET", "/balance");
+    }
+}