@secureprocessing/node 0.0.0-stage → 0.2.0

package/dist/errors.js

@@ -0,0 +1,125 @@
+// @ts-self-types="./errors.d.ts"
+/**
+ * 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 class SecureProcessingError extends Error {
+    type;
+    code;
+    param;
+    declineCode;
+    requestId;
+    status;
+    /**
+     * 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.
+     */
+    idempotencyKey;
+    /**
+     * 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.
+     */
+    requiredCapability;
+    /**
+     * `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, body, requestIdHeader, idempotencyKey) {
+        super(body.error.code === "outcome_unknown"
+            ? `${body.error.message} ${outcomeUnknownNote(idempotencyKey)}`
+            : body.error.message);
+        this.name = "SecureProcessingError";
+        this.idempotencyKey = idempotencyKey;
+        this.requiredCapability = body.error.required_capability;
+        this.status = status;
+        this.type = body.error.type;
+        this.code = body.error.code;
+        this.param = body.error.param;
+        this.declineCode = body.error.decline_code;
+        this.requestId = body.error.request_id ?? requestIdHeader ?? undefined;
+    }
+    /**
+     * 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() {
+        if (this.isOutcomeUnknown)
+            return false;
+        return (this.status >= 500 ||
+            this.status === 429 ||
+            this.code === "gateway_unavailable" ||
+            this.code === "idempotency_in_progress");
+    }
+    /**
+     * `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() {
+        return this.code === "payment_in_progress";
+    }
+    /**
+     * 🔴 `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() {
+        return this.code === "outcome_unknown";
+    }
+}
+/** Appended to an `outcome_unknown` message so the instruction travels into whatever logs it. */
+function outcomeUnknownNote(idempotencyKey) {
+    const key = idempotencyKey ? ` (it was sent with Idempotency-Key ${idempotencyKey}, err.idempotencyKey)` : "";
+    return (`(Do not retry this under a new Idempotency-Key${key} — the money may already have moved. ` +
+        "Retrieve the payment, refund or invoice and check its status; it settles on its own and a " +
+        "webhook follows.)");
+}
+/** The request never got an answer: a timeout, a DNS failure, a dropped connection. */
+export class SecureProcessingConnectionError extends Error {
+    // `override` because Error already declares `cause`; keeping the original is what lets a caller
+    // see the underlying network failure rather than only our wrapper.
+    cause;
+    /**
+     * 🔴 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.
+     */
+    idempotencyKey;
+    constructor(message, cause, idempotencyKey) {
+        super(message);
+        this.name = "SecureProcessingConnectionError";
+        this.cause = cause;
+        this.idempotencyKey = idempotencyKey;
+    }
+}