@atumlabs/payment-gateway-client 1.0.2 → 2.1.0

package/docs/idempotency.md

@@ -0,0 +1,62 @@
+# Payment idempotency
+
+Submit the same payment twice — a retry, a timeout, a network blip — and you
+should end up with **one** payment, not two, and receive the **same** answer both
+times. The key to both properties is the `request_id` you send with each payment.
+
+## Using the SDK
+
+With `@atumlabs/payment-gateway-client` this is automatic. Pass a stable
+`request_id` and reuse it on retry. `request_id` is required on the payment path
+(`preparePaymentRequest`); the SDK derives the on-chain deposit nonce
+deterministically from it, so both guarantees below line up on their own. You
+never manage nonces — `request_id` is the only value you control.
+
+Reuse the same `request_id` across attempts of the same logical payment. Use a
+fresh `request_id` only for a genuinely new payment.
+
+## The two guarantees
+
+### 1. Gateway dedup — enforced for every caller
+
+The gateway records your `request_id` (scoped to your source account and signing
+identity). If the same `request_id` arrives again, the gateway returns the
+original payment — same `payment_id`, same status and receipt — and never creates
+a second payment or broadcasts a second deposit. This holds whether you use the
+SDK or call the API directly, as long as you send a stable `request_id` and reuse
+it on retry.
+
+### 2. On-chain single-settlement — enforced by the blockchain
+
+Each deposit authorization carries a nonce, and the chain guarantees a given
+nonce can settle at most once. This ties your retries together on-chain **only
+if** each retry carries the **same** nonce. The SDK derives that nonce from your
+`request_id`, so retries reuse it automatically. A direct caller sets the nonce
+themselves in the signed permit.
+
+The caveat runs in both directions. A changing `request_id` defeats both
+guarantees, because each attempt is then treated as a different payment — keep it
+stable and reuse it on retry. Equally, reusing a `request_id` with different terms
+(a corrected amount, a different token) returns the **original** payment rather
+than an error, so the new terms are silently dropped. A genuinely new payment
+always needs a new id.
+
+## Chain-specific behavior
+
+The SDK gives you the same guarantee on every chain; the on-chain half works
+slightly differently underneath:
+
+- **EVM / Tron:** the on-chain nonce is spent permanently, so guarantee 2 lasts
+  indefinitely.
+- **Solana:** the on-chain guard covers only a short, bounded window (roughly two
+  minutes). Beyond that window the durable protection is guarantee 1 (the
+  gateway's `request_id` record). The SDK keeps a rebuild inside the window by
+  pinning `issued_at` through its Solana clock reader, so you do not have to.
+
+Either way, a stable `request_id` keeps you safe on every chain.
+
+## A note on addresses
+
+EVM `0x` addresses are case-insensitive, so casing never affects your payment.
+Solana and Tron base58 addresses **are** case-sensitive — pass them exactly as
+issued.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atumlabs/payment-gateway-client",
-  "version": "1.0.2",
+  "version": "2.1.0",
   "description": "TypeScript client for Atum Payment Gateway API",
   "author": "Atum Labs, Inc.",
   "homepage": "https://github.com/Atum-Labs/protocol/tree/main/payment-gateway-client#readme",
@@ -40,12 +40,13 @@
   "scripts": {
     "generate": "openapi-ts --input ../schemas/apis/payment-gateway/v1/openapi.yaml --output ./src/generated --client axios --name PaymentGatewayClient --useOptions",
     "prebuild:deps": "node -e \"if(!require('fs').existsSync('../key-management/common/typescript/tsconfig.json')){console.error('protocol key-management packages not found at ../key-management. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
-    "build:deps": "tsc -p ../key-management/common/typescript/tsconfig.json && tsc -p ../key-management/providers/turnkey/typescript/tsconfig.json && tsc -p ../contracts/svm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/evm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/tvm/escrow-encoding/typescript/tsconfig.json",
-    "build": "pnpm run build:deps && tsup && chmod +x dist/cli/*.js",
+    "build:deps": "tsc -p ../key-management/common/typescript/tsconfig.json && tsc -p ../key-management/providers/turnkey/typescript/tsconfig.json && tsc -p ../contracts/svm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/evm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/tvm/escrow-encoding/typescript/tsconfig.json && tsc -p ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/tsconfig.json",
+    "build": "pnpm run build:deps && tsup && chmod +x dist/cli/*.js && node scripts/stamp-entry-headers.mjs",
     "pretest": "pnpm run build:deps",
     "test": "jest",
-    "clean": "rm -rf dist ../key-management/common/typescript/dist ../key-management/providers/turnkey/typescript/dist ../contracts/svm/escrow-encoding/typescript/dist ../contracts/evm/escrow-encoding/typescript/dist ../contracts/tvm/escrow-encoding/typescript/dist",
+    "clean": "rm -rf dist ../key-management/common/typescript/dist ../key-management/providers/turnkey/typescript/dist ../contracts/svm/escrow-encoding/typescript/dist ../contracts/evm/escrow-encoding/typescript/dist ../contracts/tvm/escrow-encoding/typescript/dist ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist",
     "check:publishable": "node scripts/check-publishable.mjs",
+    "gen:notices": "node scripts/gen-third-party-notices.mjs",
     "prepare": "pnpm run build",
     "prepublishOnly": "pnpm run build && pnpm run check:publishable"
   },
@@ -54,6 +55,7 @@
     "axios": "1.13.2",
     "bs58": "^6.0.0",
     "commander": "^12.0.0",
+    "dotenv": "^16.6.1",
     "ethers": "^6.11.0",
     "tweetnacl": "^1.0.3",
     "zod": "^3.25.0"
@@ -61,6 +63,8 @@
   "devDependencies": {
     "@atum-labs/evm-escrow-encoding": "workspace:*",
     "@atum-labs/km-core": "workspace:*",
+    "@atum-labs/payment-request-sender-auth": "workspace:*",
+    "@atum-labs/publish-guard": "workspace:*",
     "@atum-labs/solana-escrow-encoding": "workspace:*",
     "@atum-labs/turnkey-signer": "workspace:*",
     "@atum-labs/tvm-escrow-encoding": "workspace:*",
@@ -75,7 +79,14 @@
   },
   "files": [
     "dist/**/*",
-    "CHANGELOG.md"
+    "README.md",
+    "CHANGELOG.md",
+    "docs/**",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.txt"
   ],
-  "license": "MIT"
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "restricted"
+  }
 }