@secureprocessing/node 0.0.0-stage → 0.2.1

package/dist/errors.d.ts

@@ -0,0 +1,112 @@
+/** 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.
+     *
+     * The one exception is `isRefundNotYetPossible`: the bank definitely refused and nothing moved,
+     * so the retry after settlement takes a NEW key — this one stays bound to the refusal for 24 hours
+     * and replays it. Calling the method again WITHOUT `idempotencyKey` already sends a fresh key.
+     */
+    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;
+    /**
+     * `400 refund_not_yet_possible`: a partial refund on a payment the bank has not settled yet. The
+     * bank refunds only settled payments and cannot reverse part of one. Nothing was refunded. Retry
+     * once it has settled — usually by the next business day — with a NEW idempotency key: this
+     * answer is stored against the old one for 24 hours and replayed. Calling the method again
+     * WITHOUT `idempotencyKey` already sends a fresh key. A new key is safe for this error only. If
+     * nothing has been refunded yet, a full refund can be made now.
+     */
+    get isRefundNotYetPossible(): 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);
+}

package/dist/errors.js

@@ -0,0 +1,140 @@
+// @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.
+     *
+     * The one exception is `isRefundNotYetPossible`: the bank definitely refused and nothing moved,
+     * so the retry after settlement takes a NEW key — this one stays bound to the refusal for 24 hours
+     * and replays it. Calling the method again WITHOUT `idempotencyKey` already sends a fresh key.
+     */
+    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";
+    }
+    /**
+     * `400 refund_not_yet_possible`: a partial refund on a payment the bank has not settled yet. The
+     * bank refunds only settled payments and cannot reverse part of one. Nothing was refunded. Retry
+     * once it has settled — usually by the next business day — with a NEW idempotency key: this
+     * answer is stored against the old one for 24 hours and replayed. Calling the method again
+     * WITHOUT `idempotencyKey` already sends a fresh key. A new key is safe for this error only. If
+     * nothing has been refunded yet, a full refund can be made now.
+     */
+    get isRefundNotYetPossible() {
+        return this.code === "refund_not_yet_possible";
+    }
+    /**
+     * 🔴 `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;
+    }
+}