@vaam-apps/vpay-sdk 0.2.1

package/dist/resources/invoices.js

@@ -0,0 +1,275 @@
+import { assertIntegerAmount } from "../validate.js";
+/**
+ * One patch field, in the wire's own three-state encoding.
+ *
+ * Returns `undefined` for "the request did not mention this", which the
+ * caller drops from the body entirely, and the empty string for "clear it".
+ * The twin of `customers.ts`'s `patch`, kept per file rather than shared
+ * because the two differ in the value type they carry and merging them would
+ * cost a generic that says less than the two lines it replaced.
+ */
+function patch(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return value === null ? "" : value;
+}
+/** `client.invoices` — see the module doc. */
+export class InvoicesResource {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    /**
+     * `POST /v1/invoices` — creates a **draft**, with no number and zero
+     * amounts.
+     *
+     * Field order is the wire order `sdks/rust/tests/resources.rs` pins byte
+     * for byte; an unset field is omitted from the body entirely, because
+     * `description=` and no `description` are different requests and only the
+     * second means "not applicable".
+     *
+     * A `400` naming `customer` when it is absent, unknown, or another
+     * merchant's — one sentence for all three, so the parameter is not an
+     * oracle; and a `400` naming `currency` for one this deployment does not
+     * settle.
+     */
+    async create(params, options) {
+        const body = {
+            customer: params.customer,
+            currency: params.currency.toLowerCase(),
+        };
+        if (params.description !== undefined) {
+            body["description"] = params.description;
+        }
+        if (params.due_date !== undefined) {
+            body["due_date"] = params.due_date;
+        }
+        if (params.metadata !== undefined) {
+            body["metadata"] = params.metadata;
+        }
+        return this.#http.request("POST", "/invoices", body, options);
+    }
+    /**
+     * `GET /v1/invoices/{id}` — the invoice **with its lines**.
+     *
+     * This is the read a webhook handler falls back to: an `invoice.*` event
+     * body carries an empty `lines.data`, and this response always carries the
+     * lines.
+     *
+     * Another merchant's `in_…` is the same `404`, byte for byte, as one that
+     * never existed.
+     */
+    async retrieve(id) {
+        return this.#http.request("GET", `/invoices/${encodeURIComponent(id)}`);
+    }
+    /**
+     * `POST /v1/invoices/{id}` — patches a **draft**.
+     *
+     * A `POST` and not a `PATCH`, for `customers.update`'s reason, even though
+     * the server mounts both verbs on the one handler: `POST` is what a
+     * merchant's existing Stripe client sends, so it is the one that has to
+     * work.
+     *
+     * A `409` naming the status once the invoice is no longer a draft — an
+     * issued document's terms are what was sent to the payer. Void it and issue
+     * a new one.
+     */
+    async update(id, params, options) {
+        const body = {};
+        const description = patch(params.description);
+        if (description !== undefined) {
+            body["description"] = description;
+        }
+        const dueDate = patch(params.due_date);
+        if (dueDate !== undefined) {
+            body["due_date"] = dueDate;
+        }
+        if (params.metadata !== undefined) {
+            body["metadata"] = params.metadata;
+        }
+        return this.#http.request("POST", `/invoices/${encodeURIComponent(id)}`, body, options);
+    }
+    /** `GET /v1/invoices` — newest first. */
+    async list(params) {
+        return this.#http.request("GET", "/invoices", params);
+    }
+    /**
+     * `DELETE /v1/invoices/{id}` — **draft only**, and its lines go with it.
+     *
+     * An issued invoice is {@link InvoicesResource.void}ed, never deleted: a
+     * voided draft would be a non-draft row with no number, which the database
+     * refuses outright, and a document that vanished is a hole an accountant
+     * reads as a destroyed one.
+     *
+     * `del` and not `delete`, for `customers.del`'s reason. Carries an
+     * `Idempotency-Key` like every other write, which is what makes a retried
+     * delete answer the original `{deleted: true}` rather than a `404`.
+     */
+    async del(id, options) {
+        return this.#http.request("DELETE", `/invoices/${encodeURIComponent(id)}`, undefined, options);
+    }
+    /**
+     * `POST /v1/invoices/{id}/finalize` — issues the document. **Draft only.**
+     *
+     * The money transition: the invoice takes the next number out of this
+     * merchant's own sequence under a row lock, its lines freeze, its amounts
+     * are computed once, and it moves to `"open"` — all in one transaction,
+     * with `invoice.finalized` inside it. Numbers are consecutive and have no
+     * holes, unlike Stripe's.
+     *
+     * A `400` naming `invoice` when it has no lines, or when its total is past
+     * `Number.MAX_SAFE_INTEGER` minor units; a `409` when it is not a draft.
+     */
+    async finalize(id, options) {
+        return this.#transition(id, "finalize", options);
+    }
+    /**
+     * `POST /v1/invoices/{id}/void` — cancels an issued document. **Open
+     * only.**
+     *
+     * The invoice **keeps its number**. Terminal.
+     *
+     * A `409` when it is not open, and a `409` while a payment intent is
+     * attached and not yet canceled — cancel that intent first.
+     */
+    async void(id, options) {
+        return this.#transition(id, "void", options);
+    }
+    /**
+     * `POST /v1/invoices/{id}/mark_uncollectible` — writes an issued document
+     * off. **Open only.**
+     *
+     * Still owed, never expected. Terminal, and it **emits no event**: vpay
+     * does not write `invoice.marked_uncollectible`, so nothing arrives on a
+     * webhook and a merchant reconciling write-offs reads them with
+     * `list({ status: "uncollectible" })`.
+     *
+     * # `markUncollectible` here, `mark_uncollectible` in `sdks/rust`
+     *
+     * The only capability the two SDKs spell differently, and the difference is
+     * each language's own casing rather than a divergence: `sdks/rust` may not
+     * spell `markUncollectible` (`non_snake_case` is a rustc lint, not a
+     * preference) and this package should not spell `mark_uncollectible` —
+     * Stripe's own Node SDK, which merchants arrive from, says
+     * `markUncollectible`, and the other spelling would be the one snake_case
+     * method in a camelCase package.
+     *
+     * [ADR-0015](../../../docs/adr/0015-sdk-parity.md) decision 1 is that
+     * parity is **per capability, not per method name**, and its alternatives
+     * reject method-name parity in as many words. Until 2026-09-08
+     * `verify-sdk-parity` could not express that — it keyed a row on one
+     * spelling — and this method was named `mark_uncollectible` to satisfy the
+     * gate. It is `markUncollectible` now because the gate learned the
+     * distinction instead: `PARITY_COLUMN_SPELLINGS` in `.xtask/src/main.rs`
+     * carries the one entry, and an entry that exempts nothing fails the build.
+     */
+    async markUncollectible(id, options) {
+        return this.#transition(id, "mark_uncollectible", options);
+    }
+    /**
+     * `POST /v1/invoices/{id}/pay` — mints a payment intent and a hosted
+     * checkout for what is left. **Open only.**
+     *
+     * **This does not charge anybody.** Stripe's `pay` charges a stored payment
+     * method; vpay has none, so this answers the invoice with
+     * {@link Invoice.payment_intent} and {@link Invoice.hosted_invoice_url}
+     * set — a page to send the payer to. The invoice stays `"open"` until the
+     * settlement moves it, which is when `invoice.paid` is emitted.
+     *
+     * One payment at a time: calling this again while the attached intent is
+     * live is a `409`, and cancelling that intent is the way back. Two
+     * concurrent calls attach exactly one intent.
+     *
+     * A `500 checkout_not_configured` when this deployment serves no checkout
+     * page.
+     */
+    async pay(id, params, options) {
+        return this.#http.request("POST", `/invoices/${encodeURIComponent(id)}/pay`, { success_url: params.success_url, cancel_url: params.cancel_url }, options);
+    }
+    /**
+     * The three transitions that take no parameters, which are one shape:
+     * a `POST` with an **empty body** to the invoice's own sub-path, carrying
+     * an `Idempotency-Key` like every other write.
+     *
+     * Private, so it is not a capability the parity gate has to record — and
+     * written once rather than three times, because the empty body is the part
+     * 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);
+    }
+}
+/**
+ * `client.invoiceItems` — the four operations on `/v1/invoice_items`: the
+ * lines of a **draft** invoice.
+ *
+ * There is deliberately no `list`: an invoice's lines are read off the
+ * invoice ({@link Invoice.lines}, expanded on every render), and a
+ * merchant-wide list of lines across invoices answers no question anybody
+ * asked. The server mounts no collection `GET` either, so this is not an
+ * omission here.
+ *
+ * Every write requires the parent to still be a `"draft"`;
+ * {@link InvoiceItemsResource.retrieve} does not.
+ */
+export class InvoiceItemsResource {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    /**
+     * `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
+     * non-negative safe integer; a `400` naming `invoice` when it is not one of
+     * your drafts.
+     */
+    async create(params, options) {
+        assertIntegerAmount(params.unit_amount, "unit_amount");
+        const body = {
+            invoice: params.invoice,
+            description: params.description,
+        };
+        if (params.quantity !== undefined) {
+            body["quantity"] = params.quantity;
+        }
+        body["unit_amount"] = params.unit_amount;
+        return this.#http.request("POST", "/invoice_items", body, options);
+    }
+    /** `GET /v1/invoice_items/{id}` — readable whatever the parent's status. */
+    async retrieve(id) {
+        return this.#http.request("GET", `/invoice_items/${encodeURIComponent(id)}`);
+    }
+    /**
+     * `POST /v1/invoice_items/{id}` — **draft parent only**, with `amount`
+     * recomputed.
+     *
+     * Throws `TypeError` 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) {
+        if (params.unit_amount !== undefined) {
+            assertIntegerAmount(params.unit_amount, "unit_amount");
+        }
+        const body = {};
+        if (params.description !== undefined) {
+            body["description"] = params.description;
+        }
+        if (params.quantity !== undefined) {
+            body["quantity"] = params.quantity;
+        }
+        if (params.unit_amount !== undefined) {
+            body["unit_amount"] = params.unit_amount;
+        }
+        return this.#http.request("POST", `/invoice_items/${encodeURIComponent(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);
+    }
+}

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

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

package/dist/resources/payment-intents.js

@@ -0,0 +1,44 @@
+import { assertIntegerAmount } from "../validate.js";
+/** `/v1/payment_intents` — docs/flows/merchant-auth.md, "Resources". */
+export class PaymentIntentsResource {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    async create(params, options) {
+        assertIntegerAmount(params.amount);
+        const body = {
+            amount: params.amount,
+            currency: params.currency.toLowerCase(),
+            payment_method_types: params.payment_method_types,
+        };
+        if (params.metadata !== undefined) {
+            body["metadata"] = params.metadata;
+        }
+        if (params.description !== undefined) {
+            body["description"] = params.description;
+        }
+        if (params.customer !== undefined) {
+            body["customer"] = params.customer;
+        }
+        return this.#http.request("POST", "/payment_intents", body, options);
+    }
+    async retrieve(id) {
+        return this.#http.request("GET", `/payment_intents/${encodeURIComponent(id)}`);
+    }
+    async confirm(id, params, options) {
+        const body = {
+            payment_method_data: params.payment_method_data,
+        };
+        if ("return_url" in params) {
+            body["return_url"] = params.return_url;
+        }
+        return this.#http.request("POST", `/payment_intents/${encodeURIComponent(id)}/confirm`, body, options);
+    }
+    async cancel(id, options) {
+        return this.#http.request("POST", `/payment_intents/${encodeURIComponent(id)}/cancel`, {}, options);
+    }
+    async list(params) {
+        return this.#http.request("GET", "/payment_intents", params);
+    }
+}

package/dist/resources/refunds.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `/v1/refunds` — the five merchant operations on the Refund object
+ * (RFC-0003 § 2).
+ *
+ * # No refund any of these creates has ever moved money
+ *
+ * Read this before any sentence elsewhere that says a refund "works". The
+ * routes are real and so is every refusal they make, but nothing on the other
+ * side of them pays anybody:
+ *
+ * - `orange_money`'s refund is a declared `NotImplemented` token — an Orange
+ *   refund is an outbound transfer this repository has no specification for;
+ * - `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
+ *   the e2e/demo stack points at a WireMock container — and the product has
+ *   never been called;
+ * - **nothing settles a `pending` refund.** There is no refund poll ladder,
+ *   so a refund created here stays `"pending"` until an operator or the
+ *   settlement path moves it.
+ *
+ * `docs/status.md` carries all three. A `200` from
+ * {@link RefundsResource.create} means a refund row exists and its amount is
+ * reserved against the intent. It does not mean the payee has been paid.
+ *
+ * # The state machine is the server's `WHERE` clause
+ *
+ * {@link RefundsResource.cancel} works while the refund is `"pending"` and
+ * answers a `409` naming the current status otherwise. This SDK does not try
+ * to predict which — reading the refund first to decide whether to call is a
+ * race. Call, and read the refusal.
+ */
+import type { HttpClient } from "../http.js";
+import type { CreateRefundParams, List, ListRefundsParams, Refund, RequestOptions, UpdateRefundParams } from "../types.js";
+/** `client.refunds` — see the module doc. */
+export declare class RefundsResource {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * `POST /v1/refunds`.
+     *
+     * Field order is the wire order `sdks/rust/tests/resources.rs` pins byte
+     * for byte; an unset field is omitted from the body entirely.
+     *
+     * A `400` naming `destination` for a payee this rail will not take — and
+     * for **no** payee at all, since both rails vpay carries need one; a `400`
+     * naming `amount` for a partial refund on a rail that has no partials; a
+     * `409` for an intent with nothing left to refund.
+     *
+     * See the module doc for what a `200` here does and does not mean.
+     */
+    create(params: CreateRefundParams, options?: RequestOptions): Promise<Refund>;
+    /**
+     * `GET /v1/refunds/{id}`.
+     *
+     * A refund is asynchronous on this rail — `RefundStatus` has a
+     * non-terminal `"pending"` — and webhook delivery is at-least-once and
+     * unordered, so this is the authoritative read a reconciliation job falls
+     * back to when a `charge.refund.updated` was missed or arrived out of
+     * order.
+     */
+    retrieve(id: string): Promise<Refund>;
+    /**
+     * `POST /v1/refunds/{id}` — the **metadata** update, and nothing else.
+     *
+     * See {@link UpdateRefundParams}: the other four fields of a refund are
+     * fixed once it exists, the merge is key-wise, and an empty value deletes a
+     * key. A refund whose metadata actually changes emits
+     * `charge.refund.updated`; one sent no `metadata` is read back unchanged
+     * and emits nothing.
+     *
+     * A `404` for a refund this merchant has none of, and a `400` naming the
+     * parameter for anything but `metadata` — which this params type has no way
+     * to send.
+     */
+    update(id: string, params: UpdateRefundParams, options?: RequestOptions): Promise<Refund>;
+    /** `GET /v1/refunds` — this merchant's refunds, newest first. */
+    list(params?: ListRefundsParams): Promise<List<Refund>>;
+    /**
+     * `POST /v1/refunds/{id}/cancel` — **while it is still pending**. No
+     * request fields.
+     *
+     * The reservation this refund holds against its intent is released and
+     * `charge.refund.updated` is written. A `404` for a refund this merchant
+     * has none of, and a `409` naming the current status for one that is no
+     * longer `"pending"`.
+     *
+     * Nothing here reaches a rail: a cancel is a vpay-side release, because no
+     * rail was ever told to start. See the module doc.
+     */
+    cancel(id: string, options?: RequestOptions): Promise<Refund>;
+}

package/dist/resources/refunds.js

@@ -0,0 +1,106 @@
+import { assertIntegerAmount } from "../validate.js";
+/**
+ * The rail-agnostic envelope, built around the rail-specific interior.
+ *
+ * The rail's own code is the **outer key** and the interior is what that
+ * rail's adapter parses; see {@link RefundDestination}. One function so the
+ * envelope is written in one place and no caller can flatten it, and so the
+ * `msisdn` goes to the wire byte for byte as the merchant wrote it — this SDK
+ * does not canonicalise a payee's number (the server does, and it requires a
+ * leading `+`).
+ */
+function destinationForm(destination) {
+    return { [destination.payment_method_type]: { msisdn: destination.msisdn } };
+}
+/** `client.refunds` — see the module doc. */
+export class RefundsResource {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    /**
+     * `POST /v1/refunds`.
+     *
+     * Field order is the wire order `sdks/rust/tests/resources.rs` pins byte
+     * for byte; an unset field is omitted from the body entirely.
+     *
+     * A `400` naming `destination` for a payee this rail will not take — and
+     * for **no** payee at all, since both rails vpay carries need one; a `400`
+     * naming `amount` for a partial refund on a rail that has no partials; a
+     * `409` for an intent with nothing left to refund.
+     *
+     * See the module doc for what a `200` here does and does not mean.
+     */
+    async create(params, options) {
+        if (params.amount !== undefined) {
+            assertIntegerAmount(params.amount);
+        }
+        const body = {
+            payment_intent: params.payment_intent,
+        };
+        if (params.amount !== undefined) {
+            body["amount"] = params.amount;
+        }
+        if (params.reason !== undefined) {
+            body["reason"] = params.reason;
+        }
+        if (params.destination !== undefined) {
+            body["destination"] = destinationForm(params.destination);
+        }
+        if (params.metadata !== undefined) {
+            body["metadata"] = params.metadata;
+        }
+        return this.#http.request("POST", "/refunds", body, options);
+    }
+    /**
+     * `GET /v1/refunds/{id}`.
+     *
+     * A refund is asynchronous on this rail — `RefundStatus` has a
+     * non-terminal `"pending"` — and webhook delivery is at-least-once and
+     * unordered, so this is the authoritative read a reconciliation job falls
+     * back to when a `charge.refund.updated` was missed or arrived out of
+     * order.
+     */
+    async retrieve(id) {
+        return this.#http.request("GET", `/refunds/${encodeURIComponent(id)}`);
+    }
+    /**
+     * `POST /v1/refunds/{id}` — the **metadata** update, and nothing else.
+     *
+     * See {@link UpdateRefundParams}: the other four fields of a refund are
+     * fixed once it exists, the merge is key-wise, and an empty value deletes a
+     * key. A refund whose metadata actually changes emits
+     * `charge.refund.updated`; one sent no `metadata` is read back unchanged
+     * and emits nothing.
+     *
+     * A `404` for a refund this merchant has none of, and a `400` naming the
+     * parameter for anything but `metadata` — which this params type has no way
+     * to send.
+     */
+    async update(id, params, options) {
+        const body = {};
+        if (params.metadata !== undefined) {
+            body["metadata"] = params.metadata;
+        }
+        return this.#http.request("POST", `/refunds/${encodeURIComponent(id)}`, body, options);
+    }
+    /** `GET /v1/refunds` — this merchant's refunds, newest first. */
+    async list(params) {
+        return this.#http.request("GET", "/refunds", params);
+    }
+    /**
+     * `POST /v1/refunds/{id}/cancel` — **while it is still pending**. No
+     * request fields.
+     *
+     * The reservation this refund holds against its intent is released and
+     * `charge.refund.updated` is written. A `404` for a refund this merchant
+     * has none of, and a `409` naming the current status for one that is no
+     * longer `"pending"`.
+     *
+     * Nothing here reaches a rail: a cancel is a vpay-side release, because no
+     * rail was ever told to start. See the module doc.
+     */
+    async cancel(id, options) {
+        return this.#http.request("POST", `/refunds/${encodeURIComponent(id)}/cancel`, {}, options);
+    }
+}