@atumlabs/payment-gateway-client 3.0.1 → 4.0.0

package/docs/idempotency.md

@@ -129,8 +129,7 @@ altogether is from a gateway predating it.
 
 ## Reading the outcome (payments)
 
-`status` is on every payment response, and the three endings mean different things for a
-retry:
+`status` is on every payment response, and its endings mean different things for a retry:
 
 | `status`               | What it means                     | What to do                                             |
 | ---------------------- | --------------------------------- | ------------------------------------------------------ |
@@ -138,13 +137,16 @@ retry:
 | `pending`              | Accepted, still settling.         | Re-submit the **same** `request_id`, or read the status endpoint. Do not start a new payment. |
 | `finalizing`           | Paid on chain, collecting confirmations. Not final. | As `pending`. Do not treat it as delivered. |
 | `failed`               | Terminal — it can never complete. | A fresh attempt needs a **new** `request_id`.          |
+| `refunding`            | Not delivered, the escrowed funds are being returned. Not final. | As `pending`. |
+| `refund_available`     | Not delivered, funds still in escrow. The status endpoint returns `refund_signature`. Not final. | Submit `refund_signature` to the source escrow to return the funds. Do not start a new payment until it is `refunded`: a late delivery can still complete it. |
+| `refunded`             | Terminal, not delivered. The funds were returned. | A fresh attempt needs a **new** `request_id`. |
 
 `pending` is not success. Cross-chain settlement can outrun the gateway's
 synchronous window, so a payment that has been accepted may still have no result
 when you get your response.
 
-A terminal failure **keeps** its `request_id`. Re-submitting that id returns the
-same failed payment for good, which is why recovering from one means minting a
+A terminal payment **keeps** its `request_id`. Re-submitting that id returns the
+same payment for good, which is why recovering from one means minting a
 new id — the opposite of what a pending payment needs. Getting these two the
 wrong way round is how a caller either pays twice or waits for something that
 will never happen.

package/docs/signing.md

@@ -15,10 +15,9 @@ unidentified originator. The reverse identifies an originator who has authorized
 integrations need the first two; the third applies once the originator holds credentials about
 itself.
 
-> The two names are confusingly close, and that is not an accident of this client: the upstream
-> library calls its document signer `signPaymentRequest` too. This package exports it as
-> `signDeclaration` so the two cannot be confused for one another, matching `SignDeclaration`
-> in the Go client.
+> The underlying declaration library also names its document signer `signPaymentRequest`. This
+> package exports it as `signDeclaration`, matching `SignDeclaration` in the Go client, so the two
+> cannot be confused.
 
 ## Keys never reach this package
 
@@ -83,18 +82,13 @@ await new PaymentGatewayClient({ BASE: gateway }).payments.submitPayment({ reque
 
 ## Check what you are signing
 
-`signPaymentRequest` signs **every** entry in `sender_auth.signed_messages[]` as given. It does
-not check that the terms inside those messages are the ones you agreed to, and neither does the
-Go client — the same is true of building the request in the first place, because the permit's
-spender, escrow and amounts come from the gateway's chain defaults.
+`signPaymentRequest` signs **every** entry in `sender_auth.signed_messages[]` as given, in both
+the TypeScript and Go clients. The permit's spender, escrow and amounts come from the gateway's
+chain defaults, and the signer has no notion of what you intended.
 
-That is a deliberate division of labour, not an oversight: the SDK holds no notion of what you
-intended. But it means a gateway that returned hostile defaults would have your wallet sign a
-permit naming an address you never chose, and nothing in the signing path would object.
-
-If you are signing on behalf of someone else's funds, bind the signed permit to the terms **you**
-agreed before the request leaves your process. `verifyPaymentRequest` recovers every
-`signed_messages[]` entry and checks the terms it actually commits to:
+Bind the signed permit to the terms **you** agreed before the request leaves your process.
+`verifyPaymentRequest` recovers every `signed_messages[]` entry and checks the terms it commits
+to:
 
 ```ts
 import { verifyPaymentRequest } from '@atum-labs/payment-gateway-client/signing';
@@ -107,22 +101,40 @@ const { recoveredAccount } = verifyPaymentRequest(signed, {
 });
 ```
 
-`sourceAsset` is the **bare token address**, not a CAIP-19 identifier — it differs in shape from
-the request's own `source.asset_identifier`, which is full CAIP-19. Passing the CAIP form here
-fails to match and rejects a request that was in fact correct.
+`sourceAsset` is the **bare token address**, not the CAIP-19 identifier used in the request's
+`source.asset_identifier`. Passing the CAIP form fails to match.
+
+**Pass those three fields.** Without them, `verifyPaymentRequest` takes the token, network and
+amount from the request itself, which proves only that the signatures are consistent with the
+request's own fields.
+
+It always checks the payee: the deposit must commit to the request's own `destination` and
+`request_id`, so a request whose payee or request id was changed after signing is refused.
 
-**Pass those three fields.** Called bare, `verifyPaymentRequest` takes the token, network and
-amount *from the request itself*, so it proves only that the signatures are self-consistent with
-the request's own stated fields — which a hostile gateway controls. It is the `sourceAsset` /
-`network` / `maxSourceAmount` arguments that turn it into a check against your terms, and
-omitting them is the difference between a real check and a reassuring one.
+If you hold the request as JSON text, call `verifyPaymentRequestJSON(json, expected)` instead. It
+also refuses a repeated member name, including names that differ only in letter case, where it is
+read: any top-level name, or inside `source`, `destination`, `request_id` or `sender_auth`.
+On a refusal, `commitmentResultOf(error)` returns the outcome (for example
+`destination_mismatch`) and both copies of the payee, ready to log. A verified entry carries the
+same result as `results[i].commitment`.
 
-It is strict by design: every entry must be a bindable permit, and a malformed one throws rather
-than being skipped. A caller with deliberately mixed messages — say an EVM setup approval
-alongside the permit — must compose the per-entry adapter calls itself and own the skip policy.
+**Contract-account payers.** `verifyPaymentRequest` recovers each signer, so it refuses a payer
+that is a contract account (ERC-1271, such as a Safe): its signature comes from an owner key, never
+from the account itself. For such a payer, call `verifyRequestCommitment(json)`. It checks the
+payee and request id the deposit commits to without recovering the signer; Permit2 checks the
+signature on chain when the deposit is made.
 
-In Go, `senderauth.GetChainAdapter(caip2).RecoverAndVerify(signed, source, expected)` returns the
-same signed terms for the same comparison.
+Every entry must be a bindable permit; a malformed entry throws. A caller with mixed messages
+(for example an EVM setup approval alongside the permit) composes the per-entry adapter calls
+itself.
+
+In Go, `senderauth.VerifyRequestCommitment(raw, solanaDomain)` is the payee check alone,
+`senderauth.VerifyPaymentRequestJSON(raw, expected)` and
+`senderauth.VerifyPaymentRequest(request, expected)` run the same checks,
+`senderauth.CommitmentResultOf(err)` reads the outcome from an error, and
+`senderauth.GetChainAdapter(caip2).RecoverAndVerify(signed, source, commitment, expected)` checks
+one signed message against a `CommitmentExpectation` built from the request's `destination` and
+`request_id`.
 
 A custodial signer is the natural place to enforce this: it is the component that can refuse.
 
@@ -170,21 +182,13 @@ loader in place of its built-in fetcher. A document whose `@context` names an un
 refused rather than resolved, since an attacker-served context could otherwise change what each
 term means, and therefore what the signature covers.
 
-One precision, because this page is about what your signatures cover: the embedded copies can be
-overridden by an environment variable intended for development against a modified snapshot. It
-reads from local disk, never the network, and nothing in normal operation sets it — but if it is
-set, the library now says so on first use rather than substituting the contexts silently.
-
-This is structural: there is no HTTP client in the signing libraries, and the JSON-LD processor
-is always handed the local loader in place of its built-in fetcher.
+For development against a modified snapshot, an environment variable can override the embedded
+copies. It reads from local disk only, and the library reports it on first use when it is set.
 
 ## The identity envelope
 
-**Read this before the example: you need an issuer-signed credential about yourself, and
-originators do not hold one yet.** The schema requires at least one credential and rejects an
-empty bag, so until issuance exists this surface cannot be exercised end to end. It
-is documented because the shape is stable and the signing half is done, not because it is
-callable today.
+**Prerequisite: at least one issuer-signed credential about the originator.** The schema rejects
+an envelope without one.
 
 `buildEnvelope` wraps the originator's issuer-signed credentials in a holder-signed
 PaymentRequestEnvelope. It takes the same kind of signer as the other surfaces, so a custodial
@@ -207,8 +211,7 @@ const envelope = await buildEnvelopeForAccount('eip155:1', wallet.address.toLowe
 
 Three things the verifier enforces, so they are not optional:
 
-- **At least one credential.** The schema requires it and an empty bag is rejected — see the
-  prerequisite above.
+- **At least one credential.** An empty bag is rejected.
 - **The challenge binds one request** and **the domain binds one environment**. Both are checked
   against the values the gateway expects, so an envelope cannot be replayed across either.
 - **The declaration type is bound into the signature**, not merely present in the document —

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@atumlabs/payment-gateway-client",
-  "version": "3.0.1",
+  "version": "4.0.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",
+  "homepage": "https://github.com/Atum-Labs/protocol/tree/main/schemas/apis/payment-gateway/v1/bindings/payment-gateway-client#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Atum-Labs/protocol.git",
-    "directory": "payment-gateway-client"
+    "directory": "schemas/apis/payment-gateway/v1/bindings/payment-gateway-client"
   },
   "bugs": {
     "url": "https://github.com/Atum-Labs/protocol/issues"
@@ -50,9 +50,9 @@
     "approve-permit2": "./dist/cli/approve-permit2.js"
   },
   "scripts": {
-    "generate": "openapi-ts --input ../schemas/apis/payment-gateway/v1/openapi.yaml --output \"${PGC_GEN_OUT:-./src/generated}\" --client axios --name PaymentGatewayClient --useOptions",
+    "generate": "openapi-ts --input ../../openapi.yaml --output \"${PGC_GEN_OUT:-./src/generated}\" --client axios --name PaymentGatewayClient --useOptions",
     "lint": "eslint . --max-warnings 0",
-    "prebuild:deps": "node -e \"if(!require('fs').existsSync('../pnpm-workspace.yaml')){console.error('protocol workspace not found at ../pnpm-workspace.yaml. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
+    "prebuild:deps": "node -e \"if(!require('fs').existsSync('../../../../../../pnpm-workspace.yaml')){console.error('protocol workspace not found at ../../../../../../pnpm-workspace.yaml. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
     "build:deps": "pnpm --filter \"@atum-labs/payment-gateway-client^...\" run build",
     "build": "tsup && chmod +x dist/cli/*.js && node scripts/stamp-entry-headers.mjs",
     "typecheck:tests": "tsc -p tsconfig.test.json",
@@ -73,6 +73,7 @@
     "dotenv": "^16.6.1",
     "ethers": "^6.11.0",
     "jsonld": "8.3.3",
+    "rdf-canonize": "3.4.0",
     "tweetnacl": "^1.0.3",
     "zod": "^3.25.0"
   },
@@ -85,6 +86,7 @@
     "@atum-labs/payment-request-sender-auth": "workspace:*",
     "@atum-labs/payment-request-token-approval": "workspace:*",
     "@atum-labs/publish-guard": "workspace:*",
+    "@atum-labs/schema-declarations": "workspace:*",
     "@atum-labs/solana-escrow-encoding": "workspace:*",
     "@atum-labs/turnkey-signer": "workspace:*",
     "@atum-labs/tvm-escrow-encoding": "workspace:*",
@@ -98,7 +100,7 @@
     "ts-jest": "^29.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.0.0",
-    "uuid": "^9.0.0"
+    "uuid": "^11.1.1"
   },
   "files": [
     "dist/**/*",