@secureprocessing/node 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Secure Processing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,249 @@
-# Temporary Holding Version
+# @secureprocessing/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Card payments for Belize. Zero dependencies; runs on Node 20+, Deno, Bun and Cloudflare Workers.
+
+## Install
+
+From our own domain — this file is the npm package itself:
+
+```bash
+npm install https://secureprocessing.app/sdk/secureprocessing-node-0.2.0.tgz
+```
+
+It installs as `@secureprocessing/node`, so every `import ... from "@secureprocessing/node"` below
+works unchanged, and your lockfile pins its hash. `pnpm add` takes the same URL. Once the package is
+on the npm registry, `npm install @secureprocessing/node@0.2.0` gives you these same bytes;
+[the docs](https://docs.secureprocessing.app/sdk) say which of the two to use today.
+
+Deno, including Supabase Edge Functions:
+
+```ts
+import { SecureProcessing } from "https://secureprocessing.app/sdk/0.2.0/index.js";
+
+// Deno 2 imports only from its built-in allow-list unless told otherwise:
+//   deno run --allow-net --allow-env --allow-import=secureprocessing.app your-script.ts
+```
+
+The types come with it: every hosted `.js` names its own `.d.ts`, so `deno check` and the Deno
+language server see them with no `@deno-types` line. (0.1.0 needed one and still lost every type
+behind its first import; 0.2.0 fixes that.)
+
+Both URLs are pinned to a version and that version's bytes never change, so the code you reviewed is
+the code that runs.
+
+## What is in it
+
+`paymentIntents`, `checkoutSessions`, `refunds`, `customers`, `paymentMethods`, `products`, `prices`,
+`paymentLinks`, `taxRates`, `invoices`, `invoiceItems`, `balance`, `balanceTransactions`, `payouts`,
+`reports`, `account`, `events`, `webhookEndpoints`, `riskRules`, `riskLists`, `reviews`, `disputes`,
+`webhooks.constructEvent`, and `autoPaginate` for walking a list — every call the docs site shows,
+which a test in this package checks by reading the docs.
+
+## Take a payment
+
+Amounts are integers in the currency's minor unit. `6000` is $60.00 — there are no decimals in
+this API, in either direction.
+
+```ts
+import { SecureProcessing } from "@secureprocessing/node";
+
+const sp = new SecureProcessing(process.env.SECURE_PROCESSING_KEY!);
+
+const intent = await sp.paymentIntents.create({
+  amount: 6000,
+  currency: "usd",
+  // Reaches the bank's own record of the payment, and is what you will see in their portal.
+  // Lead with your own reference so you can find it again.
+  description: "SCU-B0161 — Blue Hole Two-Tank",
+  metadata: { shop_id: "scuba-sensation", booking_id: "SCU-B0161" },
+});
+
+const session = await sp.checkoutSessions.create({
+  payment_intent: intent.id,
+  success_url: "https://example.com/thanks?session={CHECKOUT_SESSION_ID}",
+  cancel_url: "https://example.com/cart",
+});
+
+redirect(session.url!); // the card is entered on the bank's page, never on yours
+```
+
+## Hold now, charge later
+
+```ts
+const intent = await sp.paymentIntents.create({
+  amount: 20000,
+  currency: "usd",
+  capture_method: "manual", // places a hold
+});
+// ...once you know the final amount:
+await sp.paymentIntents.capture(intent.id, { amount_to_capture: 17500 });
+// or release it entirely:
+await sp.paymentIntents.cancel(intent.id);
+```
+
+## Refunds
+
+Full or partial. A full refund of a payment that has not settled yet is sent as a reversal, which
+is faster and often never reaches the cardholder's statement. You do not choose: we use whichever
+the bank accepts.
+
+```ts
+await sp.refunds.create({ payment_intent: intent.id });                 // all of it
+await sp.refunds.create({ payment_intent: intent.id, amount: 2000 });   // part of it
+```
+
+## Webhooks
+
+```ts
+const event = await sp.webhooks.constructEvent(
+  rawBody,                                   // the RAW string, not a parsed object
+  request.headers.get("Secure-Processing-Signature")!,
+  process.env.SECURE_PROCESSING_WEBHOOK_SECRET!,
+);
+
+if (event.type === "payment_intent.succeeded") {
+  const payment = event.data.object;
+  // fulfil the order
+}
+```
+
+> **Pass the raw body.** `JSON.stringify(JSON.parse(body))` produces different bytes, so the
+> signature will not match. This is the most common reason a first webhook integration fails, and
+> the error message will tell you so.
+
+Deliveries are retried for about 35 hours. Handle events idempotently — key on `event.id` — because
+at-least-once delivery means you will occasionally see one twice.
+
+## Idempotency
+
+Every `POST` carries an `Idempotency-Key` automatically, and it is kept across the client's own
+retries, so a timeout cannot take a second payment. Supply your own when the retry might come from
+elsewhere — a job runner, a queue, a customer pressing the button again:
+
+```ts
+await sp.paymentIntents.create(params, { idempotencyKey: `order-${orderId}` });
+```
+
+Reusing a key with a *different* body is an error rather than a second payment.
+
+If the first request with a key is still running, the API answers `409 idempotency_in_progress`.
+The client retries that with the same key, up to `maxRetries` times and never past 30 seconds from
+the first attempt — it cannot run twice; the API answers with the first request's result once it
+has one — and then hands you the error, whose `isRetryable` is `true`. The same 30-second limit
+applies to every retry of a POST, including after a timeout or a dropped connection: past 60
+seconds the API may treat the first request as dead and run a retry again.
+
+🔴 **Retrying yourself? Use the same key.** Every error from a POST carries the key it was sent
+with — the one you gave, or the one generated for you — as `err.idempotencyKey`, on
+`SecureProcessingError` and `SecureProcessingConnectionError` alike. Calling the method again
+without it sends a NEW key, which the API treats as a new request: a second charge or refund if the
+first one reached the bank.
+
+```ts
+try {
+  await sp.refunds.create({ payment_intent: id });
+} catch (err) {
+  if ((err instanceof SecureProcessingError && err.isRetryable) || err instanceof SecureProcessingConnectionError) {
+    await sp.refunds.create({ payment_intent: id }, { idempotencyKey: err.idempotencyKey }); // never a new key
+  }
+}
+```
+
+`409 payment_in_progress` is different: cancelling a payment the customer may be paying right now
+(on the bank's page, or in 3-D Secure). Nothing was changed, the message says when to try again,
+and `err.isPaymentInProgress` is `true`. The client never retries it — it is minutes, not a backoff.
+
+🔴 `500 outcome_unknown` (`err.isOutcomeUnknown`) means the request reached the bank and the result
+could not be confirmed: **the money may have moved.** Never repeat it under a new idempotency key —
+that is a second charge or refund. Retrying under the same key (`err.idempotencyKey`, which the
+message also names) is safe but gains nothing now: usually it replays this answer, and when the
+message says the original "has not recorded its result yet", a retry later returns that result. So
+the client does not retry it, and `isRetryable` is `false`. Retrieve the payment (or list its refunds) and check
+its `status`; it settles on its own and its webhook follows.
+
+A `202` is the same situation answered with an object: `invoices.pay` (charge sent, outcome not
+back) and `reviews.refund` (refund pending, review still open). Tell it from a `200` with
+`result.lastResponse.statusCode === 202`.
+
+## Errors
+
+```ts
+import { SecureProcessingError } from "@secureprocessing/node";
+
+try {
+  await sp.refunds.create({ payment_intent: id });
+} catch (err) {
+  if (err instanceof SecureProcessingError) {
+    console.error(err.type, err.code, err.declineCode, err.requestId);
+    if (err.isRetryable) { /* try again later, with { idempotencyKey: err.idempotencyKey } */ }
+  }
+}
+```
+
+Quote `err.requestId` to support and they can find the exact request.
+
+A `403 insufficient_permissions` names what your API key or role lacks in `err.requiredCapability`
+(for example `payments:refund`); ask the account's owner for it — retrying will not help. A
+`404 resource_missing` caused by an id in the request body names that field in `err.param`. A
+request body may be at most 1 MB (`413 body_too_large`); none of the API's own objects come close.
+None of these three is retried.
+
+A successful result carries its request id too, on a non-enumerable `lastResponse` (it does not
+appear in `JSON.stringify`, spreads or `Object.keys` — so a copy such as `{ ...intent }` does not
+have it at runtime, whatever TypeScript says; read it from the object the call returned):
+
+```ts
+const intent = await sp.paymentIntents.create({ amount: 6000, currency: "usd" });
+intent.lastResponse.requestId;          // the X-Request-Id header
+intent.lastResponse.idempotencyKey;     // what this POST was sent with
+intent.lastResponse.idempotentReplayed; // true if the API replayed an earlier answer
+```
+
+## Every page of a list
+
+List calls return one page. `autoPaginate` walks all of them, fetching each only when you reach it:
+
+```ts
+import { autoPaginate } from "@secureprocessing/node";
+
+let total = 0;
+for await (const line of autoPaginate((page) => sp.payouts.listTransactions(payoutId, page))) {
+  total += line.net;
+}
+```
+
+## Currencies
+
+Price in `usd` or `bzd`. Settlement is in BZD, and the payment object records what the card was
+actually charged and at what rate:
+
+```ts
+intent.amount;              // 6000  — what you asked for, in USD cents
+intent.settlement_amount;   // 12000 — what the card was charged, in BZD cents
+intent.settlement_currency; // "BZD"
+intent.fx_rate;             // 2
+```
+
+The rate is frozen when the payment is taken, so a later capture or refund uses that rate and not
+whatever today's is.
+
+## Test mode
+
+Keys beginning `sk_test_` never move real money. Test cards:
+
+| Number | Result |
+|---|---|
+| `4000001111111118` | Succeeds |
+| `4444444411111111` | Declined |
+| `5555555555555599` | 3-D Secure challenge |
+
+## Options
+
+```ts
+new SecureProcessing(apiKey, {
+  baseUrl: "https://api.secureprocessing.app",
+  timeout: 30_000,
+  maxRetries: 2,
+  fetch: myFetch,   // e.g. a Worker's fetch, or a test double
+});
+```

package/dist/client.d.ts

@@ -0,0 +1,94 @@
+export interface ClientOptions {
+    /** Defaults to the production API. */
+    baseUrl?: string;
+    /** `test` or `live`. Only needed when authenticating with a dashboard session. */
+    mode?: "test" | "live";
+    /** Supply your own fetch — a Worker's, a test double, or one with a proxy. */
+    fetch?: typeof fetch;
+    /** Milliseconds before giving up on a request. */
+    timeout?: number;
+    /** How many times to retry a request that failed in a way that might succeed. */
+    maxRetries?: number;
+}
+export interface RequestOptions {
+    /**
+     * Make this request safe to retry.
+     *
+     * One is generated for every POST if you do not supply one, so a retry after a timeout cannot
+     * take a second payment. Supply your own when the retry might come from somewhere else — a job
+     * runner, a queue, a user pressing the button again.
+     */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+/**
+ * What came back with a result, besides the object itself. Read it as `result.lastResponse`.
+ *
+ * ```ts
+ * const intent = await sp.paymentIntents.create({ amount: 6000, currency: "usd" });
+ * log.info("created", intent.id, intent.lastResponse.requestId); // quote this to support
+ * ```
+ */
+export interface ResponseMetadata {
+    /** The API's `X-Request-Id` for this call: what support needs to find it in our logs. */
+    requestId: string | undefined;
+    statusCode: number;
+    headers: Headers;
+    /** The `Idempotency-Key` this POST was sent with — yours, or the one generated for you. */
+    idempotencyKey: string | undefined;
+    /** True when the API replayed the stored answer to an earlier request with the same key. */
+    idempotentReplayed: boolean;
+}
+/**
+ * An API object with its response metadata attached, non-enumerably, as `lastResponse`.
+ *
+ * ⚠️ Non-enumerable means a copy loses it: `{ ...intent }` or `structuredClone(intent)` has no
+ * `lastResponse` at runtime, although TypeScript's spread type still claims one. Read it from the
+ * object the call returned.
+ */
+export type ApiResponse<T> = T & {
+    readonly lastResponse: ResponseMetadata;
+};
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly mode;
+    private readonly fetchImpl;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(apiKey: string, options?: ClientOptions);
+    request<T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * 🔴 Every retry of a keyed request (a POST) goes out within RETRY_WINDOW_MS of the FIRST
+     * attempt, or not at all — a 409 `idempotency_in_progress`, a 5xx and a connection failure alike.
+     *
+     * The API's idempotency store (packages/db, IN_PROGRESS_GRACE_SECONDS = 60) presumes a request
+     * whose key has been locked for 60 seconds has died, and lets the next caller with that key run
+     * the operation again. Inside the window a retry can only be answered with another 409 or with
+     * the first request's stored response; past it, a retry is a second execution if the first was
+     * merely slow. Before this applied to connection failures too, the defaults (30s timeout, two
+     * retries, backoff) could send a third attempt at about 63 seconds. So the client gives up at
+     * half the server's grace and hands the error back, carrying `idempotencyKey` so the caller can
+     * retry under the same key when they choose. A first attempt that timed out has already spent the
+     * window. A GET has no key and nothing to run twice, so only `maxRetries` limits it.
+     */
+    private mayRetry;
+    get<T>(path: string, query?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /**
+     * A GET whose body you want as a STREAM, not as parsed JSON.
+     *
+     * 🔴 Deliberately outside `request()`, and not retried. `request()` calls `response.json()`,
+     * which reads the whole body into memory — on a year of payments that is the point of the export
+     * defeated, and on a Worker it is the memory limit. Retrying is wrong here for a second reason:
+     * a retry can only happen after the first attempt's body has been abandoned, and a caller who
+     * has already started piping bytes to a file would have them silently interleaved with a second
+     * attempt's.
+     *
+     * The caller gets the `Response`: pipe `response.body`, or `await response.text()` for a small
+     * one. A non-2xx still throws a `SecureProcessingError` with the API's envelope, because the
+     * error path IS JSON and is small.
+     */
+    raw(path: string, query?: Record<string, unknown>, accept?: string): Promise<Response>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    delete<T>(path: string): Promise<ApiResponse<T>>;
+}

package/dist/client.js

@@ -0,0 +1,196 @@
+// @ts-self-types="./client.d.ts"
+import { SecureProcessingConnectionError, SecureProcessingError } from "./errors.js";
+import { VERSION } from "./version.js";
+const REQUEST_ID_HEADER = "X-Request-Id";
+const DEFAULT_BASE_URL = "https://api.secureprocessing.app";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+/** Half of the API's IN_PROGRESS_GRACE_SECONDS (60). See `mayRetry`. */
+const RETRY_WINDOW_MS = 30_000;
+export class HttpClient {
+    apiKey;
+    baseUrl;
+    mode;
+    fetchImpl;
+    timeout;
+    maxRetries;
+    constructor(apiKey, options = {}) {
+        if (!apiKey)
+            throw new Error("An API key is required");
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.mode = options.mode;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    }
+    async request(method, path, body, options = {}) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": `secureprocessing-node/${VERSION}`,
+        };
+        if (this.mode)
+            headers["Secure-Processing-Mode"] = this.mode;
+        // Exactly this string, lower-case: the API answers `415 unsupported_media_type` to a body whose
+        // type is not `application/json` (or a lower-case `+json` type). A test pins it.
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        // 🔴 Generated once, OUTSIDE the retry loop. A key regenerated per attempt would defeat the
+        // entire purpose: the retry would look like a new request and could take a second payment.
+        if (method === "POST") {
+            headers["Idempotency-Key"] = options.idempotencyKey ?? crypto.randomUUID();
+        }
+        const idempotencyKey = headers["Idempotency-Key"];
+        const startedAt = Date.now();
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            if (attempt > 0)
+                await sleep(backoffMs(attempt));
+            try {
+                const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                    method,
+                    headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: options.signal ?? AbortSignal.timeout(this.timeout),
+                });
+                if (response.ok) {
+                    return withLastResponse((await response.json()), response, idempotencyKey);
+                }
+                throw await errorFrom(response, idempotencyKey);
+            }
+            catch (err) {
+                if (err instanceof SecureProcessingError) {
+                    if (!err.isRetryable || !this.mayRetry(attempt, startedAt, idempotencyKey))
+                        throw err;
+                    lastError = err;
+                    continue;
+                }
+                // A connection failure is safe to retry precisely BECAUSE the idempotency key is fixed:
+                // if the first attempt reached us, the retry replays its answer rather than repeating it.
+                lastError = new SecureProcessingConnectionError(`Could not reach the Secure Processing API: ${err.message}`, err, idempotencyKey);
+                if (!this.mayRetry(attempt, startedAt, idempotencyKey))
+                    throw lastError;
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * 🔴 Every retry of a keyed request (a POST) goes out within RETRY_WINDOW_MS of the FIRST
+     * attempt, or not at all — a 409 `idempotency_in_progress`, a 5xx and a connection failure alike.
+     *
+     * The API's idempotency store (packages/db, IN_PROGRESS_GRACE_SECONDS = 60) presumes a request
+     * whose key has been locked for 60 seconds has died, and lets the next caller with that key run
+     * the operation again. Inside the window a retry can only be answered with another 409 or with
+     * the first request's stored response; past it, a retry is a second execution if the first was
+     * merely slow. Before this applied to connection failures too, the defaults (30s timeout, two
+     * retries, backoff) could send a third attempt at about 63 seconds. So the client gives up at
+     * half the server's grace and hands the error back, carrying `idempotencyKey` so the caller can
+     * retry under the same key when they choose. A first attempt that timed out has already spent the
+     * window. A GET has no key and nothing to run twice, so only `maxRetries` limits it.
+     */
+    mayRetry(attempt, startedAt, idempotencyKey) {
+        if (attempt >= this.maxRetries)
+            return false;
+        if (idempotencyKey === undefined)
+            return true;
+        return Date.now() - startedAt + backoffMs(attempt + 1) < RETRY_WINDOW_MS;
+    }
+    get(path, query) {
+        return this.request("GET", path + encodeQuery(query));
+    }
+    /**
+     * A GET whose body you want as a STREAM, not as parsed JSON.
+     *
+     * 🔴 Deliberately outside `request()`, and not retried. `request()` calls `response.json()`,
+     * which reads the whole body into memory — on a year of payments that is the point of the export
+     * defeated, and on a Worker it is the memory limit. Retrying is wrong here for a second reason:
+     * a retry can only happen after the first attempt's body has been abandoned, and a caller who
+     * has already started piping bytes to a file would have them silently interleaved with a second
+     * attempt's.
+     *
+     * The caller gets the `Response`: pipe `response.body`, or `await response.text()` for a small
+     * one. A non-2xx still throws a `SecureProcessingError` with the API's envelope, because the
+     * error path IS JSON and is small.
+     */
+    async raw(path, query, accept = "text/csv") {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: accept,
+            "User-Agent": `secureprocessing-node/${VERSION}`,
+        };
+        if (this.mode)
+            headers["Secure-Processing-Mode"] = this.mode;
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${path}${encodeQuery(query)}`, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(this.timeout),
+            });
+        }
+        catch (err) {
+            throw new SecureProcessingConnectionError(`Could not reach the Secure Processing API: ${err.message}`, err);
+        }
+        if (response.ok)
+            return response;
+        throw await errorFrom(response);
+    }
+    post(path, body, options) {
+        return this.request("POST", path, body ?? {}, options);
+    }
+    delete(path) {
+        return this.request("DELETE", path);
+    }
+}
+/** The API's envelope when there is one, and an honest stand-in when a proxy answered instead. */
+async function errorFrom(response, idempotencyKey) {
+    const payload = (await response.json().catch(() => null));
+    const requestId = response.headers.get(REQUEST_ID_HEADER);
+    return payload?.error
+        ? new SecureProcessingError(response.status, payload, requestId, idempotencyKey)
+        : new SecureProcessingError(response.status, { error: { type: "api_error", code: "unexpected_response", message: `HTTP ${response.status}` } }, requestId, idempotencyKey);
+}
+/**
+ * Attach the response's metadata as a NON-ENUMERABLE `lastResponse`, the convention Stripe's Node
+ * SDK uses for the same problem: the request id of a SUCCESSFUL call lives only in a header, and
+ * returning `{ data, response }` instead would break every caller. Non-enumerable means
+ * `JSON.stringify`, spreading, `Object.keys` and deep-equality checks see exactly the API's object,
+ * so storing or comparing a result behaves as it did in 0.1.0.
+ */
+function withLastResponse(body, response, idempotencyKey) {
+    if (body === null || typeof body !== "object")
+        return body;
+    const lastResponse = {
+        requestId: response.headers.get(REQUEST_ID_HEADER) ?? undefined,
+        statusCode: response.status,
+        headers: response.headers,
+        idempotencyKey,
+        idempotentReplayed: response.headers.get("Idempotent-Replayed") === "true",
+    };
+    Object.defineProperty(body, "lastResponse", { value: lastResponse, enumerable: false, writable: false });
+    return body;
+}
+/** Nested keys become `metadata[shop_id]=…`, which is what the list endpoints expect. */
+function encodeQuery(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === "object") {
+            for (const [inner, innerValue] of Object.entries(value)) {
+                if (innerValue !== undefined && innerValue !== null)
+                    params.append(`${key}[${inner}]`, String(innerValue));
+            }
+        }
+        else {
+            params.append(key, String(value));
+        }
+    }
+    const encoded = params.toString();
+    return encoded ? `?${encoded}` : "";
+}
+const backoffMs = (attempt) => Math.min(1000 * 2 ** (attempt - 1), 8000) + Math.floor(Math.random() * 250);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/errors.d.ts

@@ -0,0 +1,99 @@
+/** The shape every non-2xx response from the API has. */
+export interface ApiErrorBody {
+    error: {
+        type: string;
+        code: string;
+        message: string;
+        param?: string;
+        decline_code?: string;
+        request_id?: string;
+        /** On `403 insufficient_permissions`: the permission the request needed, e.g. `payments:refund`. */
+        required_capability?: string;
+    };
+}
+/**
+ * Something the API refused.
+ *
+ * Branch on `type` for the category and `code` for the specific reason. For a declined card,
+ * `declineCode` says why in terms you can show a customer. `requestId` is what to quote to support.
+ * `param` names the field at fault — including a `404 resource_missing` for an id in the body that
+ * is not yours (`param: "customer"`). A `403` names the missing permission in `requiredCapability`.
+ */
+export declare class SecureProcessingError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly param: string | undefined;
+    readonly declineCode: string | undefined;
+    readonly requestId: string | undefined;
+    readonly status: number;
+    /**
+     * The `Idempotency-Key` the failed request was sent with — yours, or the one the client generated
+     * for a POST you did not give a key. `undefined` for a GET, which has none.
+     *
+     * 🔴 To retry a failed POST, pass THIS back: `{ idempotencyKey: err.idempotencyKey }`. Calling the
+     * method again without it sends a new key, and a new key is a new request to the API: if the
+     * first one did reach the bank, that is a second charge or refund.
+     */
+    readonly idempotencyKey: string | undefined;
+    /**
+     * On `403 permission_error` / `insufficient_permissions`: the permission this request needed and
+     * your API key — or, from a dashboard session, your role — does not have, such as
+     * `payments:refund`. Ask the account's owner for it; retrying will not help (`isRetryable` is
+     * false). `undefined` on every other error.
+     */
+    readonly requiredCapability: string | undefined;
+    /**
+     * `requestId` falls back to the `X-Request-Id` response header: a response that never reached
+     * the API's error handler (a proxy's 502, say) has no envelope to carry it, and the header is
+     * the one thing support can still look up.
+     */
+    constructor(status: number, body: ApiErrorBody, requestIdHeader?: string | null, idempotencyKey?: string);
+    /**
+     * True when retrying the identical request — with the SAME idempotency key — could reasonably
+     * succeed soon. For a POST that means `{ idempotencyKey: err.idempotencyKey }`, never a new key.
+     *
+     * `idempotency_in_progress` is included: the first request with that key is still running, and
+     * the API answers a retry either with another 409 or, once it has finished, with its stored
+     * answer, so a retry under that key cannot run the operation twice. The client already retries
+     * it for you, up to `maxRetries` times and never past 30 seconds from the first attempt.
+     * `idempotency_key_in_use` (a key reused with a different body) is not: that is a bug in the
+     * caller and will fail identically for ever.
+     *
+     * `payment_in_progress` is deliberately NOT retryable. See `isPaymentInProgress`. Nor is
+     * `outcome_unknown`, although it is a 500. See `isOutcomeUnknown`.
+     */
+    get isRetryable(): boolean;
+    /**
+     * `409 payment_in_progress`: the customer may be on the bank's page, or in 3-D Secure, for this
+     * payment right now, so it cannot be cancelled yet. Nothing was changed. The message says when to
+     * try again — minutes, not a backoff — and an unpaid payment is cancelled automatically anyway.
+     * The client never retries it: a loop here would only poll the bank on the customer's behalf.
+     */
+    get isPaymentInProgress(): boolean;
+    /**
+     * 🔴 `500 outcome_unknown`: the request asked the bank to move money — a charge, a capture, a
+     * refund — and the API could not confirm what happened. The money MAY HAVE MOVED.
+     *
+     * - Do not send it again under a NEW idempotency key: that is a second charge or refund.
+     * - Retrying under the SAME key (`err.idempotencyKey`) is always safe — it never reaches the bank
+     *   again. Usually the API has stored this answer and replays it. If the message says an earlier
+     *   request with the key "has not recorded its result yet", the original is still in flight, and
+     *   a LATER retry under the same key returns its result once it finishes. Either way an immediate
+     *   retry gains nothing, so the client does not retry it, and `isRetryable` is false.
+     * - Find out by reading the object: retrieve the payment intent (or list its refunds, or the
+     *   invoice's payments) and look at its `status`. It settles on its own within minutes and its
+     *   webhook follows.
+     */
+    get isOutcomeUnknown(): boolean;
+}
+/** The request never got an answer: a timeout, a DNS failure, a dropped connection. */
+export declare class SecureProcessingConnectionError extends Error {
+    readonly cause: unknown;
+    /**
+     * 🔴 The `Idempotency-Key` the request was sent with, generated or yours. A connection failure
+     * does not say whether the request reached us: retry with `{ idempotencyKey: err.idempotencyKey }`
+     * and the API replays its answer if it did; a new key would run it again.
+     */
+    readonly idempotencyKey: string | undefined;
+    constructor(message: string, cause?: unknown, idempotencyKey?: string);
+}