@secureprocessing/node 0.2.0 → 0.2.1

package/README.md

@@ -4,21 +4,24 @@ Card payments for Belize. Zero dependencies; runs on Node 20+, Deno, Bun and Clo
 
 ## Install
 
-From our own domain — this file is the npm package itself:
+```bash
+npm install @secureprocessing/node@0.2.1
+```
+
+The same version is served from our own domain, byte for byte — npm publishes the very file at this
+URL, so either one records the same hash in your lockfile:
 
 ```bash
-npm install https://secureprocessing.app/sdk/secureprocessing-node-0.2.0.tgz
+npm install https://secureprocessing.app/sdk/secureprocessing-node-0.2.1.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.
+It installs as `@secureprocessing/node` either way, so every `import ... from "@secureprocessing/node"`
+below works unchanged. `pnpm add` takes the same name or URL.
 
 Deno, including Supabase Edge Functions:
 
 ```ts
-import { SecureProcessing } from "https://secureprocessing.app/sdk/0.2.0/index.js";
+import { SecureProcessing } from "https://secureprocessing.app/sdk/0.2.1/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
@@ -153,6 +156,13 @@ try {
 (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.
 
+`400 refund_not_yet_possible` (`err.isRefundNotYetPossible`) is a partial refund on a payment the
+bank has not settled yet. The bank definitely refused and nothing was refunded. It is **the one
+error to retry under a NEW idempotency key**, once the payment has settled — usually by the next
+business day: the original key stays bound to this answer for 24 hours and would only replay it.
+Calling the method again WITHOUT `idempotencyKey` already sends a fresh key, so that is all the
+retry needs. If nothing has been refunded yet, a full refund can be made now.
+
 🔴 `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
@@ -231,11 +241,15 @@ whatever today's is.
 
 Keys beginning `sk_test_` never move real money. Test cards:
 
-| Number | Result |
-|---|---|
-| `4000001111111118` | Succeeds |
-| `4444444411111111` | Declined |
-| `5555555555555599` | 3-D Secure challenge |
+| Number | Expiry | Result |
+|---|---|---|
+| `5555555555555599` | 12/34 | Succeeds |
+| `4111111111111111` | 12/26 | Succeeds |
+| `5168494895055780` | 12/26 | Declined |
+
+CVC `123` for all of them. These are the bank's sandbox cards as they stood when this version was
+released, and two of them expire 12/26; the current list is always at
+<https://docs.secureprocessing.app/test-cards>.
 
 ## Options
 

package/dist/errors.d.ts

@@ -33,6 +33,10 @@ export declare class SecureProcessingError extends Error {
      * 🔴 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;
     /**
@@ -70,6 +74,15 @@ export declare class SecureProcessingError extends Error {
      * 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.

package/dist/errors.js

@@ -21,6 +21,10 @@ export class SecureProcessingError extends Error {
      * 🔴 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;
     /**
@@ -80,6 +84,17 @@ export class SecureProcessingError extends Error {
     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.

package/dist/index.d.ts

@@ -76,6 +76,9 @@ export declare class SecureProcessing {
          * 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.
+         *
+         * A partial refund on a payment the bank has not settled yet throws with
+         * `isRefundNotYetPossible`. That one is retried after settlement under a NEW key.
          */
         create: (params: CreateRefundParams, options?: RequestOptions) => Promise<ApiResponse<Refund>>;
         retrieve: (id: string) => Promise<ApiResponse<Refund>>;
@@ -237,6 +240,9 @@ export declare class SecureProcessing {
          * 🔴 `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.
+         *
+         * If the overpaying payment has not been settled by the bank yet, this throws with
+         * `isRefundNotYetPossible`. That one is retried after settlement under a NEW key.
          */
         refundOverpayment: (id: string, options?: RequestOptions) => Promise<ApiResponse<Refund>>;
         /**

package/dist/index.js

@@ -73,6 +73,9 @@ export class SecureProcessing {
          * 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.
+         *
+         * A partial refund on a payment the bank has not settled yet throws with
+         * `isRefundNotYetPossible`. That one is retried after settlement under a NEW key.
          */
         create: (params, options) => this.http.post("/v1/refunds", params, options),
         retrieve: (id) => this.http.get(`/v1/refunds/${encodeURIComponent(id)}`),
@@ -209,6 +212,9 @@ export class SecureProcessing {
          * 🔴 `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.
+         *
+         * If the overpaying payment has not been settled by the bank yet, this throws with
+         * `isRefundNotYetPossible`. That one is retried after settlement under a NEW key.
          */
         refundOverpayment: (id, options) => this.http.post(`/v1/invoices/${encodeURIComponent(id)}/refund_overpayment`, {}, options),
         /**

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * filesystem. `test/sdk.test.ts` fails if the two disagree — 0.1.0's User-Agent was a literal in two
  * places, and a bump would have left both claiming the old version.
  */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.1";

package/dist/version.js

@@ -6,4 +6,4 @@
  * filesystem. `test/sdk.test.ts` fails if the two disagree — 0.1.0's User-Agent was a literal in two
  * places, and a bump would have left both claiming the old version.
  */
-export const VERSION = "0.2.0";
+export const VERSION = "0.2.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secureprocessing/node",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Secure Processing API client. Card payments for Belize.",
   "homepage": "https://docs.secureprocessing.app/sdk",
   "bugs": {