@secureprocessing/node 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,520 @@
+// @ts-self-types="./index.d.ts"
+import { HttpClient } from "./client.js";
+import { constructEvent, parseSignatureHeader, SIGNATURE_HEADER } from "./webhooks.js";
+export * from "./types.js";
+export * from "./errors.js";
+export { constructEvent, parseSignatureHeader, SIGNATURE_HEADER };
+export { VERSION } from "./version.js";
+export { autoPaginate } from "./pagination.js";
+/**
+ * The Secure Processing API client.
+ *
+ * ```ts
+ * const sp = new SecureProcessing(process.env.SECURE_PROCESSING_KEY!);
+ *
+ * const intent = await sp.paymentIntents.create({
+ *   amount: 6000,            // minor units — $60.00
+ *   currency: "usd",
+ *   description: "SCU-B0161 — Blue Hole Two-Tank",
+ *   metadata: { shop_id: "scuba-sensation" },
+ * });
+ *
+ * const session = await sp.checkoutSessions.create({
+ *   payment_intent: intent.id,
+ *   success_url: "https://example.com/thanks",
+ * });
+ * // Send the customer to session.url
+ * ```
+ *
+ * Runs on Node 20+, Deno, Bun and Cloudflare Workers: it has no dependencies and uses only
+ * `fetch` and Web Crypto.
+ */
+export class SecureProcessing {
+    http;
+    constructor(apiKey, options = {}) {
+        this.http = new HttpClient(apiKey, options);
+    }
+    paymentIntents = {
+        /**
+         * Create a payment intent, and with `confirm: true` charge a saved card now.
+         *
+         * 🔴 A confirmed intent that comes back `processing` was sent to the bank and its answer has not
+         * reached us yet. The card may have been charged: do not create another payment for it. It
+         * settles on its own to `succeeded` or `requires_payment_method`, and the webhook follows. A
+         * thrown `SecureProcessingError` with `isOutcomeUnknown` means the same: check `status` on a
+         * `retrieve`, and never repeat the charge under a new idempotency key.
+         */
+        create: (params, options) => this.http.post("/v1/payment_intents", params, options),
+        retrieve: (id) => this.http.get(`/v1/payment_intents/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/payment_intents", params),
+        /** Settle a payment created with `capture_method: "manual"`. */
+        capture: (id, params = {}, options) => this.http.post(`/v1/payment_intents/${encodeURIComponent(id)}/capture`, params, options),
+        /**
+         * Release a hold, or abandon a payment nobody completed. A succeeded payment is refunded instead.
+         *
+         * Throws `409` with `isPaymentInProgress` while the customer may still be on the bank's page or
+         * in 3-D Secure: nothing was cancelled, the message says when to try again, and an unpaid
+         * payment is cancelled automatically anyway. The client does not retry it.
+         */
+        cancel: (id, params = {}, options) => this.http.post(`/v1/payment_intents/${encodeURIComponent(id)}/cancel`, params, options),
+    };
+    checkoutSessions = {
+        create: (params, options) => this.http.post("/v1/checkout_sessions", params, options),
+        retrieve: (id) => this.http.get(`/v1/checkout_sessions/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/checkout_sessions", params),
+        expire: (id, options) => this.http.post(`/v1/checkout_sessions/${encodeURIComponent(id)}/expire`, {}, options),
+    };
+    refunds = {
+        /**
+         * Refund all or part of a payment.
+         *
+         * 🔴 `status: "pending"` means the refund was sent and the bank's answer has not reached us yet;
+         * the money may already be on its way back. Do not refund again — the pending amount is held
+         * against what is refundable — and wait for `refund.succeeded` or `refund.failed`. A thrown
+         * error with `isOutcomeUnknown` means the same without a refund object to hold: list the
+         * payment's refunds to see it, and never retry under a new idempotency key.
+         */
+        create: (params, options) => this.http.post("/v1/refunds", params, options),
+        retrieve: (id) => this.http.get(`/v1/refunds/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/refunds", params),
+    };
+    customers = {
+        create: (params, options) => this.http.post("/v1/customers", params, options),
+        retrieve: (id) => this.http.get(`/v1/customers/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/customers", params),
+        /** The cards this customer has let you keep. */
+        listPaymentMethods: (id) => this.http.get(`/v1/customers/${encodeURIComponent(id)}/payment_methods`),
+    };
+    products = {
+        create: (params, options) => this.http.post("/v1/products", params, options),
+        retrieve: (id) => this.http.get(`/v1/products/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/products", params),
+        /** Everything is editable, including `active: false` to archive it. Prices are left alone. */
+        update: (id, params, options) => this.http.post(`/v1/products/${encodeURIComponent(id)}`, params, options),
+    };
+    prices = {
+        /**
+         * Give `unit_amount` in MINOR UNITS — 6000 is $60.00 — or a `custom_unit_amount` range for
+         * the payer to choose within. Exactly one of the two.
+         */
+        create: (params, options) => this.http.post("/v1/prices", params, options),
+        retrieve: (id) => this.http.get(`/v1/prices/${encodeURIComponent(id)}`),
+        /** `product` is how you read one product's prices — they are not embedded in the product. */
+        list: (params) => this.http.get("/v1/prices", params),
+        /**
+         * 🔴 Only `active`, `nickname` and `metadata`. The amount cannot be changed: a payment link
+         * already stores this id, and repricing it would change what that link charges with nothing in
+         * the record to say so. Create a new price and archive this one.
+         */
+        update: (id, params, options) => this.http.post(`/v1/prices/${encodeURIComponent(id)}`, params, options),
+    };
+    /**
+     * One URL that takes a payment, over and over.
+     *
+     * ```ts
+     * const link = await sp.paymentLinks.create({ price: price.id });
+     * // Share link.url — every visitor gets their own payment.
+     * ```
+     */
+    paymentLinks = {
+        /**
+         * The `price` must be an active price of yours. Its amount is what the link charges, and
+         * nothing a visitor sends can change it — the one exception is a price with a
+         * `custom_unit_amount`, where the payer chooses inside the range you published.
+         */
+        create: (params, options) => this.http.post("/v1/payment_links", params, options),
+        retrieve: (id) => this.http.get(`/v1/payment_links/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/payment_links", params),
+        /**
+         * 🔴 Everything except the price and the quantity. Those are fixed for the life of the link:
+         * the URL is already on a poster, in a QR code and in messages nobody can recall, and the
+         * people who will pay it have been told what it costs. Create a new link and deactivate this
+         * one — `paymentLinks.update(id, { active: false })`.
+         */
+        update: (id, params, options) => this.http.post(`/v1/payment_links/${encodeURIComponent(id)}`, params, options),
+    };
+    /**
+     * The rates you charge on invoice lines.
+     *
+     * Belize GST — 12.5%, added on top — is created for you when your account is. A rate's
+     * percentage and inclusivity cannot be changed: see the note on `update`.
+     */
+    taxRates = {
+        create: (params, options) => this.http.post("/v1/tax_rates", params, options),
+        retrieve: (id) => this.http.get(`/v1/tax_rates/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/tax_rates", params),
+        /**
+         * 🔴 Only `display_name`, `active` and `metadata`. A finalized invoice names the rate that
+         * produced the tax printed on it, and a rate that moved would make the two disagree on a
+         * document your customer is already holding. Create a new rate and archive this one —
+         * `taxRates.update(id, { active: false })`.
+         */
+        update: (id, params, options) => this.http.post(`/v1/tax_rates/${encodeURIComponent(id)}`, params, options),
+    };
+    /**
+     * Bill a customer, send them a link, and let us chase it.
+     *
+     * ```ts
+     * const invoice = await sp.invoices.create({ customer: cus.id, days_until_due: 14 });
+     * await sp.invoiceItems.create({ invoice: invoice.id, description: "Dive", unit_amount: 50000 });
+     * const open = await sp.invoices.finalize(invoice.id);  // assigns INV-0007, freezes the totals
+     * await sp.invoices.send(invoice.id);
+     * ```
+     *
+     * 🔴 An invoice is created as a DRAFT and its money comes from its lines. Finalizing is the
+     * moment it becomes a document: it takes a number from your own consecutive sequence, freezes
+     * the totals, and stops the lines being touched. There is no way back from that — fix a mistake
+     * by voiding it and raising a new one.
+     */
+    invoices = {
+        create: (params, options) => this.http.post("/v1/invoices", params, options),
+        retrieve: (id) => this.http.get(`/v1/invoices/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/invoices", params),
+        update: (id, params, options) => this.http.post(`/v1/invoices/${encodeURIComponent(id)}`, params, options),
+        /**
+         * Gives the invoice its number, freezes its totals, and moves it to `open`.
+         *
+         * ⚠️ Irreversible. Afterwards the lines and the amounts cannot change — by us, by you, or by
+         * anything with a database connection. It does not email anything; `send` does that.
+         */
+        finalize: (id, options) => this.http.post(`/v1/invoices/${encodeURIComponent(id)}/finalize`, {}, options),
+        /**
+         * Emails the customer a link to the hosted page. Safe to call again.
+         *
+         * A success means the email left. Two failures say otherwise:
+         * - `503 email_not_sent`: it could not be sent right now, and nothing about the invoice changed.
+         *   The client retries it for you under the same key (a 503 is never stored against a key, so a
+         *   retry really sends); if it still fails, retry later with `{ idempotencyKey: err.idempotencyKey }`.
+         * - `400 email_recipient_rejected` (`param: "customer.email"`): the address itself was refused.
+         *   Not retryable — fix the customer's email first.
+         */
+        send: (id, options) => this.http.post(`/v1/invoices/${encodeURIComponent(id)}/send`, {}, options),
+        /**
+         * Marks an invoice as raised in error. It keeps its number and its lines, so the copy in the
+         * customer's inbox still matches something.
+         *
+         * 🔴 Refused once any money has been received. Refund the payment first, then void — in that
+         * order, so the money moves before the paperwork does.
+         */
+        void: (id, options) => this.http.post(`/v1/invoices/${encodeURIComponent(id)}/void`, {}, options),
+        /** The bill was owed and is being written off. Not the same as void: the debt was real. */
+        markUncollectible: (id, options) => this.http.post(`/v1/invoices/${encodeURIComponent(id)}/mark_uncollectible`, {}, options),
+        /**
+         * Refunds the amount by which an invoice has been overpaid, from its most recent payment.
+         *
+         * An invoice can be overpaid: two browser tabs can both reach the hosted page and both be paid,
+         * and the money moved at the bank before anyone heard about it. `amount_due` goes negative and
+         * this is how you give the difference back.
+         *
+         * 🔴 `amount_paid` does NOT change — the payment happened, and the refund is its own record, so
+         * the excess is netted against anything already refunded. Calling this twice returns an error
+         * rather than refunding twice. Returns the refund, not the invoice.
+         */
+        refundOverpayment: (id, options) => this.http.post(`/v1/invoices/${encodeURIComponent(id)}/refund_overpayment`, {}, options),
+        /**
+         * Charge a card the customer already saved with you, with nobody present.
+         *
+         * ⚠️ **Beta.** This relies on a `tii` parameter Belize Bank requires and documents nowhere, and
+         * a merchant-initiated charge has never been proved in production. There is no way to charge a
+         * card the customer has not saved — `send` the invoice and let them pay on the hosted page.
+         *
+         * 🔴 A `202` means the charge was sent and the bank's answer has not reached us yet. Tell it from
+         * a `200` by the status, not by the body — the invoice looks the same either way:
+         *
+         * ```ts
+         * const invoice = await sp.invoices.pay(id, { payment_method: "pm_..." });
+         * if (invoice.lastResponse.statusCode === 202) {
+         *   // sent, outcome unknown: the card may already have been charged
+         * }
+         * ```
+         *
+         * Do NOT call this again under a new idempotency key. `paymentIntents.list({ invoice: id })`
+         * shows the payment `processing`; it settles on its own, and `invoice.paid` or
+         * `invoice.payment_succeeded` follows if it went through. A `500` with `isOutcomeUnknown` means
+         * the same thing, said by an error.
+         */
+        pay: (id, params, options) => this.http.post(`/v1/invoices/${encodeURIComponent(id)}/pay`, params, options),
+        /**
+         * 🔴 VOIDS a draft; it does not delete it, and the returned invoice says
+         * `status: "void"`. Stripe deletes drafts and this method exists so code written against that
+         * does not break, but a bill that was raised stays on the record here — "was this customer
+         * ever invoiced?" has to remain answerable.
+         */
+        del: (id, options) => this.http.request("DELETE", `/v1/invoices/${encodeURIComponent(id)}`, undefined, options),
+    };
+    /**
+     * The lines on a draft invoice.
+     *
+     * 🔴 Every write is refused once the invoice has been finalized. Freezing the totals alone would
+     * not be enough: a line edited afterwards leaves an invoice whose stored total is right and whose
+     * printed lines do not add up to it, which is worse than being simply wrong.
+     */
+    invoiceItems = {
+        /** Give `price` to quote your catalogue, or `unit_amount` (minor units) and `description`. */
+        create: (params, options) => this.http.post("/v1/invoice_items", params, options),
+        list: (params) => this.http.get("/v1/invoice_items", params),
+        update: (id, params, options) => this.http.post(`/v1/invoice_items/${encodeURIComponent(id)}`, params, options),
+        /** The one thing in invoicing that really deletes, and only while the invoice is a draft. */
+        del: (id, options) => this.http.request("DELETE", `/v1/invoice_items/${encodeURIComponent(id)}`, undefined, options),
+    };
+    paymentMethods = {
+        /**
+         * Forget a saved card.
+         *
+         * ⚠️ Definitive here, best effort at the bank. If the gateway refuses to forget the binding the
+         * card is still detached on our side, which is what governs whether it can ever be charged
+         * again — so this succeeding means what you need it to mean.
+         */
+        detach: (id, options) => this.http.post(`/v1/payment_methods/${encodeURIComponent(id)}/detach`, {}, options),
+    };
+    balance = {
+        retrieve: () => this.http.get("/v1/balance"),
+    };
+    /**
+     * Every movement of your balance, in one list.
+     *
+     * `net` sums to `balance.pending + balance.available`, so this is the list you reconcile with.
+     * A charge appears once and changes `status` from `pending` to `available`; the settlement
+     * release is not a second row.
+     */
+    balanceTransactions = {
+        list: (params) => this.http.get("/v1/balance_transactions", params),
+    };
+    /**
+     * Payouts: money on its way to your bank account.
+     *
+     * 🔴 Read-only, and that is the design. A payout's amount is never a number you supply — it is
+     * the whole of your available balance at the moment of the cut, decided by the ledger. Payouts
+     * are cut by the schedule you chose in the dashboard, or by asking for one there.
+     *
+     * ⚠️ Between `pending` and `paid` there is a person making a bank transfer, because the acquiring
+     * bank offers no disbursement API. `bank_reference` is the bank's own reference for it.
+     */
+    payouts = {
+        retrieve: (id) => this.http.get(`/v1/payouts/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/payouts", params),
+        /** Everything one payout covers, as `balance_transaction`s whose `net` sums to its amount. */
+        listTransactions: (id, params) => this.http.get("/v1/balance_transactions", {
+            ...params,
+            payout: id,
+        }),
+    };
+    /**
+     * Reports: the documents you reconcile your own books against.
+     *
+     * ```ts
+     * const month = await sp.reports.balanceSummary();
+     * if (!month.reconciled) throw new Error("our statement and our balance disagree");
+     *
+     * const csv = await sp.reports.export("payments", { start: "2026-09-01", end: "2026-10-01" });
+     * await pipeline(Readable.fromWeb(csv.body!), createWriteStream("payments.csv"));
+     * ```
+     */
+    reports = {
+        /**
+         * Opening balance, everything that moved, closing balance — and whether the ledger agrees.
+         *
+         * 🔴 Check `reconciled`. It is false only when the period's movements and the ledger's own
+         * recomputed balance disagree, which means your statement and your balance are telling you
+         * different things. Get in touch rather than reconciling around it.
+         *
+         * Defaults to the current calendar month up to now. At most 366 days per call.
+         */
+        balanceSummary: (params) => this.http.get("/v1/reports/balance_summary", params),
+        /**
+         * A CSV export, as a STREAM.
+         *
+         * Returns the `Response` rather than a string: a year of payments is tens of thousands of rows
+         * and reading it into memory to hand you a string is the thing this endpoint exists to avoid.
+         * Pipe `response.body`, or `await response.text()` when you know it is small.
+         *
+         * Every money column appears twice — `…_minor` is the integer this API speaks in, and the
+         * column beside it is the same figure formatted for a person. Dates are ISO 8601 UTC. At most
+         * 366 days per call; page by date for longer.
+         */
+        export: (kind, params) => this.http.raw(`/v1/reports/exports/${kind}.csv`, params),
+        /**
+         * Everything one payout paid for, as CSV. Its lines sum to the payout's amount by
+         * construction, and the header prints that amount separately so the two can be compared.
+         */
+        payoutReconciliation: (payoutId) => this.http.raw(`/v1/reports/payout_reconciliation/${encodeURIComponent(payoutId)}`),
+    };
+    /**
+     * Your own account.
+     *
+     * ```ts
+     * const account = await sp.account.retrieve();
+     * if (!account.live_enabled) {
+     *   // Still in test. account.requirements.currently_due says what is missing.
+     * }
+     * ```
+     *
+     * 🔴 THERE IS NO `account.application` OR `files` RESOURCE HERE, and that is deliberate rather
+     * than unfinished. Those endpoints exist — `/v1/account/application`, `/v1/files` — and they are
+     * SESSION-ONLY: they carry the beneficial owners' dates of birth, passport numbers and home
+     * addresses, and the bank account the business will be paid into. An API key is a long-lived
+     * bearer credential in an environment variable on somebody's server; a leaked one should be a
+     * payments incident, not an identity-theft one.
+     *
+     * So an SDK method for them would be a method that returns 403 every time it is called, for every
+     * caller, forever — which is worse than no method, because a client library is read as a
+     * statement of what the API can do. The application is filled in from the dashboard. If a
+     * programmatic path is ever needed it will be a purpose-scoped credential, not this one.
+     */
+    account = {
+        retrieve: () => this.http.get("/v1/account"),
+    };
+    events = {
+        retrieve: (id) => this.http.get(`/v1/events/${encodeURIComponent(id)}`),
+        /** Everything that has happened, newest first. Use it to catch up after a delivery failure. */
+        list: (params) => this.http.get("/v1/events", params),
+    };
+    webhookEndpoints = {
+        create: (params, options) => this.http.post("/v1/webhook_endpoints", params, options),
+        list: (params) => this.http.get("/v1/webhook_endpoints", params),
+        /** Issues a new secret; the old one keeps working for the overlap you specify. */
+        rotateSecret: (id, params = {}, options) => this.http.post(`/v1/webhook_endpoints/${encodeURIComponent(id)}/rotate_secret`, params, options),
+        retrieve: (id) => this.http.get(`/v1/webhook_endpoints/${encodeURIComponent(id)}`),
+        /**
+         * Change the URL, the description or which events are sent, or switch the endpoint off and on.
+         *
+         * The signing secret is deliberately unchanged: moving an endpoint to a new hostname and having
+         * its key rotate underneath is how a migration becomes an outage. Rotate explicitly.
+         */
+        update: (id, params, options) => this.http.post(`/v1/webhook_endpoints/${encodeURIComponent(id)}`, params, options),
+        /** Every attempt at every delivery for this endpoint, newest first. */
+        deliveries: (id, params) => this.http.get(`/v1/webhook_endpoints/${encodeURIComponent(id)}/deliveries`, params),
+        /** Deliver a `webhook_endpoint.test` event to THIS endpoint and no other. */
+        sendTest: (id, options) => this.http.post(`/v1/webhook_endpoints/${encodeURIComponent(id)}/send_test`, {}, options),
+        /** Disabled, never deleted: the delivery history is how you answer "did you send it?" later. */
+        disable: (id) => this.http.delete(`/v1/webhook_endpoints/${encodeURIComponent(id)}`),
+        /**
+         * Send one delivery again, now, without waiting for its schedule.
+         *
+         * ⚠️ The delivery keeps its own retry schedule either way. This is for after you have fixed the
+         * endpoint and do not want to wait out the backoff.
+         */
+        retryDelivery: (deliveryId, options) => this.http.post(`/v1/webhook_deliveries/${encodeURIComponent(deliveryId)}/retry`, {}, options),
+    };
+    /**
+     * Risk rules: the tests every one of your payments passes through before the bank is called.
+     *
+     * ```ts
+     * await sp.riskRules.create({
+     *   name: "Review anything over BZ$2,000",
+     *   action: "review",
+     *   predicate: { all: [{ attr: "amount_minor", op: "gte", value: 200000 }] },
+     * });
+     * ```
+     *
+     * The list includes the platform defaults Secure Processing applies to every business. Those
+     * carry `platform_default: true`, cannot be edited, and are overridden only by an entry on your
+     * own allow list.
+     */
+    riskRules = {
+        create: (params, options) => this.http.post("/v1/risk_rules", params, options),
+        retrieve: (id) => this.http.get(`/v1/risk_rules/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/risk_rules", params),
+        /**
+         * 🔴 `name`, `enabled`, `priority` and `metadata` only. Every evaluation records the rule that
+         * fired, so a rewritten predicate would make those records describe a test that no longer
+         * exists. Create a new rule and disable this one.
+         */
+        update: (id, params, options) => this.http.post(`/v1/risk_rules/${encodeURIComponent(id)}`, params, options),
+    };
+    /**
+     * Allow and block lists: exact values, checked before any rule runs.
+     *
+     * An `allow` entry beats everything, including our platform defaults. A `block` entry refuses
+     * the payment with `payment_blocked`.
+     *
+     * ⚠️ `card_fingerprint` can only match on a charge against a card already saved. The card number
+     * is entered on the bank's own page, so there is nothing to fingerprint on somebody's first
+     * visit to a checkout.
+     */
+    riskLists = {
+        create: (params, options) => this.http.post("/v1/risk_lists", params, options),
+        retrieve: (id) => this.http.get(`/v1/risk_lists/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/risk_lists", params),
+        /**
+         * ⚠️ A real delete, unlike `webhookEndpoints.disable`. A list is a live control surface:
+         * unblocking somebody has to actually unblock them. What the entry did is kept in the
+         * evaluations it decided.
+         */
+        remove: (id) => this.http.delete(`/v1/risk_lists/${encodeURIComponent(id)}`),
+    };
+    /**
+     * Reviews: payments a rule asked you to look at.
+     *
+     * A review exists only for a payment that was credited — an abandoned checkout never makes one.
+     * Close it by approving (keep the money) or refunding (give it all back); the refund goes
+     * through the ordinary refund path, fee proration and all.
+     */
+    reviews = {
+        retrieve: (id) => this.http.get(`/v1/reviews/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/reviews", params),
+        approve: (id, params = {}, options) => this.http.post(`/v1/reviews/${encodeURIComponent(id)}/approve`, params, options),
+        /**
+         * Refunds the payment in full and closes the review. The bank refusing leaves it open.
+         *
+         * 🔴 A `202` means the refund was sent and the bank has not confirmed it: the refund is
+         * `pending`, and the review stays `open` until it settles. Check the status, not only the body:
+         *
+         * ```ts
+         * const review = await sp.reviews.refund(id);
+         * if (review.lastResponse.statusCode === 202) {
+         *   // refund pending; the review closes once it settles
+         * }
+         * ```
+         *
+         * Calling it again never refunds twice: while the refund is pending it answers `202` again, and
+         * once it has settled it closes the review as `refunded` (`200`).
+         */
+        refund: (id, params = {}, options) => this.http.post(`/v1/reviews/${encodeURIComponent(id)}/refund`, params, options),
+    };
+    /**
+     * Disputes: a chargeback, and the evidence you answer it with.
+     *
+     * ```ts
+     * const dispute = await sp.disputes.retrieve("dp_...");
+     * await sp.disputes.update(dispute.id, {
+     *   evidence: { shipping_carrier: "DHL", shipping_tracking_number: "CP123456789BZ" },
+     *   submit: true,
+     * });
+     * ```
+     *
+     * ⚠️ The file fields take a `file_` id, and uploading one is **session only** — there is no
+     * `files` resource on this client. A document uploaded for a dispute is often an invoice naming
+     * a customer or a signed delivery note, and an API key is a long-lived credential sitting in an
+     * environment variable. Upload from the dashboard and paste the id, or send only the text fields.
+     *
+     * 🔴 THERE IS NO `create`. A dispute is something the card network asserted, not something a
+     * business declares about itself — Belize Bank emails us a case reference and we open it. You
+     * hear about it through `dispute.created` and an email to the account owner.
+     *
+     * ⚠️ `evidence_details.due_by` is the only field worth alerting on. A dispute is lost by silence
+     * far more often than by argument, and the bank does not extend the deadline.
+     */
+    disputes = {
+        retrieve: (id) => this.http.get(`/v1/disputes/${encodeURIComponent(id)}`),
+        list: (params) => this.http.get("/v1/disputes", params),
+        /**
+         * Add evidence, and optionally submit it.
+         *
+         * Fields MERGE, so posting the shipping section does not erase the receipt. Submitting is
+         * final: we forward the bundle to Belize Bank by hand, and the bundle they see has to be the
+         * one this record shows.
+         */
+        update: (id, params, options) => this.http.post(`/v1/disputes/${encodeURIComponent(id)}`, params, options),
+        /**
+         * Concede. Stripe's verb and Stripe's meaning: you are not contesting this one.
+         *
+         * ⚠️ It moves no money and does not mark the dispute lost. The bank has not answered yet, and
+         * we will not debit you before the network has decided.
+         */
+        close: (id, options) => this.http.post(`/v1/disputes/${encodeURIComponent(id)}/close`, {}, options),
+    };
+    /** Verify an incoming webhook and get the event. Pass the RAW body. */
+    webhooks = { constructEvent };
+}
+export default SecureProcessing;

package/dist/pagination.d.ts

@@ -0,0 +1,32 @@
+import type { ListParams, ListResponse } from "./types.js";
+/**
+ * Every item from a list endpoint, fetching the next page only when you reach it.
+ *
+ * ```ts
+ * let total = 0;
+ * for await (const line of autoPaginate((page) => sp.payouts.listTransactions(payoutId, page))) {
+ *   total += line.net;
+ * }
+ * ```
+ *
+ * 🔴 Why it exists: the balance-and-payouts page reconciled a payout by summing
+ * `listTransactions(id).data` — the FIRST page, ten rows by default — and claimed the result
+ * equals the payout's amount. For any payout covering more than ten movements it did not, and the
+ * snippet's whole point is that a mismatch means something is wrong. A total has to read every page.
+ *
+ * Pass a function that makes one list call with the paging parameters it is given; any filters go
+ * in that call. Pages are requested 100 at a time.
+ *
+ * It never loops for ever, and it never silently stops short:
+ * - an empty page ends the walk, whatever `has_more` says;
+ * - a page that repeats an id already seen THROWS before yielding it. That is what happens when the
+ *   function drops its `page` argument (`() => sp.payouts.list({...})`), or when the endpoint takes
+ *   no cursor but still says `has_more` (`riskRules.list` and `webhookEndpoints.deliveries` page
+ *   nothing). Stopping quietly there would hand a total over the first page as if it were all of
+ *   them — the very bug this exists to prevent — so it is an error with the reason in it.
+ */
+export declare function autoPaginate<T extends {
+    id: string;
+}>(listPage: (page: ListParams) => Promise<ListResponse<T>>, options?: {
+    limit?: number;
+}): AsyncGenerator<T, void, undefined>;

package/dist/pagination.js

@@ -0,0 +1,52 @@
+// @ts-self-types="./pagination.d.ts"
+/**
+ * Every item from a list endpoint, fetching the next page only when you reach it.
+ *
+ * ```ts
+ * let total = 0;
+ * for await (const line of autoPaginate((page) => sp.payouts.listTransactions(payoutId, page))) {
+ *   total += line.net;
+ * }
+ * ```
+ *
+ * 🔴 Why it exists: the balance-and-payouts page reconciled a payout by summing
+ * `listTransactions(id).data` — the FIRST page, ten rows by default — and claimed the result
+ * equals the payout's amount. For any payout covering more than ten movements it did not, and the
+ * snippet's whole point is that a mismatch means something is wrong. A total has to read every page.
+ *
+ * Pass a function that makes one list call with the paging parameters it is given; any filters go
+ * in that call. Pages are requested 100 at a time.
+ *
+ * It never loops for ever, and it never silently stops short:
+ * - an empty page ends the walk, whatever `has_more` says;
+ * - a page that repeats an id already seen THROWS before yielding it. That is what happens when the
+ *   function drops its `page` argument (`() => sp.payouts.list({...})`), or when the endpoint takes
+ *   no cursor but still says `has_more` (`riskRules.list` and `webhookEndpoints.deliveries` page
+ *   nothing). Stopping quietly there would hand a total over the first page as if it were all of
+ *   them — the very bug this exists to prevent — so it is an error with the reason in it.
+ */
+export async function* autoPaginate(listPage, options = {}) {
+    const seen = new Set();
+    let startingAfter;
+    for (;;) {
+        const page = await listPage({ limit: options.limit ?? 100, starting_after: startingAfter });
+        const last = page.data[page.data.length - 1];
+        if (startingAfter !== undefined && last?.id === startingAfter) {
+            throw new Error(`autoPaginate: the list did not advance past ${startingAfter}: does listPage pass its page ` +
+                "argument through, and does this endpoint take a starting_after cursor?");
+        }
+        const repeated = page.data.find((item) => seen.has(item.id));
+        if (repeated) {
+            throw new Error(`autoPaginate: ${repeated.id} was already returned by an earlier page, so the list did not ` +
+                "advance: does listPage pass its page argument through, and does this endpoint take a " +
+                "starting_after cursor?");
+        }
+        for (const item of page.data) {
+            seen.add(item.id);
+            yield item;
+        }
+        if (!page.has_more || !last)
+            return;
+        startingAfter = last.id;
+    }
+}