@atumlabs/payment-gateway-client 1.0.2 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-07-31
+
+### Added
+- The CLIs read an optional `.env` file from the working directory, so `cp .env.example .env` configures them. Resolution order: a CLI flag, then the environment, then `.env`, then the built-in default. This applies to the CLIs only; the SDK reads the environment but never modifies it, so an application embedding the SDK stays in control of its own configuration.
+- `getErrorResponse(err)` returns the typed, public-facing gateway error (`ErrorResponse` — `code`, `message`, `request_id?`, `docs_url?`, `domain?`) from a caught `ApiError`, or `undefined` for anything else; `isApiError(err)` type guard for the transport-level error. No internal error taxonomy is exposed.
+- Idempotency and retries documentation (`docs/idempotency.md`) plus a summary in the README: the two guarantees (gateway dedup and on-chain single-settlement) and the per-chain differences (EVM/Tron vs Solana).
+- The published package now ships `LICENSE` and an autogenerated `THIRD-PARTY-NOTICES.txt` (attributing the third-party components statically bundled into `dist/`).
+- The gateway base URL now honors a `GATEWAY_URL` environment variable. Precedence: an explicit URL (SDK `{ BASE }` or the CLI `--gateway` flag), then `GATEWAY_URL`, then the built-in production-testnet default. A blank or whitespace-only `GATEWAY_URL` counts as unset and falls through to the default. An explicit `{ BASE: '' }` is used verbatim, which is how a caller targets a same-origin proxy.
+- The exported `OpenAPI` configuration now reports this package's default gateway (production-testnet), matching what a client resolves when no URL is supplied. The OpenAPI contract continues to list the mainnet server first, in line with the other Atum service contracts.
+
+### Changed
+- README signing example now uses the shipped signer helpers (`createSenderSigner` + `signPaymentRequest`) instead of manual signing, and the error-handling example reads the typed `ErrorResponse` fields.
+- The idempotency docs now state the consequence of reusing a `request_id` with different terms: the gateway returns the original payment, so the new terms are silently dropped and a genuinely new payment needs a new id.
+- The `fulfillment_verifier.endpoint` example in the OpenAPI spec is now a bare origin (`https://veri-fill.production-testnet.atum.xyz`) and its description says so. The field is a base URL to which the caller appends the verifier's own paths, so an example carrying `/v1/fulfillment` would double the path for anyone copying its shape.
+- Two documentation links in the OpenAPI contract now point at `schemas.atum.xyz`. Descriptive text only: JSON-LD `@context` prefixes, schema `$id` values, and `did:web:` identifiers are unchanged, since those take part in signature canonicalization.
+- The package is marked `restricted` and its `license` field is `SEE LICENSE IN LICENSE`. The publish guard now also fails on any inlined copyleft dependency, stale/incomplete third-party notices, missing license materials in the tarball, or an incorrect `license` field.
+- Default gateway hosts point at the canonical `payment-gw.production-{testnet,mainnet}.atum.xyz` endpoints (the SDK/CLI default and the generated client default), replacing the retired `atumlabs.xyz` / `api.atum.network` hosts.
+
+### Fixed
+- The CLIs (`send-payment`, `request-quote`, `quote-status`, `payment-status`) report the real package version via `--version` (they previously hardcoded `1.0.0`).
+- `docs/` is now included in the published package. The README links to `docs/idempotency.md`, which had not been shipped, so the link was dead for anyone installing from npm.
+- README corrections: the install instructions now distinguish a global install (for the command-line tools) from a project install (for the SDK), and the removal instructions match; the `.env` file and the gateway-URL precedence are documented; monorepo build detail moved to `CONTRIBUTING.md`.
+- A zero-config client (`new PaymentGatewayClient()` with no `BASE`) now uses a single, consistent gateway host; previously it fetched chain defaults from the testnet host but submitted payments to the mainnet host.
+
+## [2.0.0] - 2026-07-27
+
+### Breaking
+- `request_id` is now required on `preparePaymentRequest` (the client no longer silently auto-generates one, which could turn a retry into a second payment). Callers must supply a stable `request_id` and reuse it on retry. The `send-payment` CLI generates a one-shot id when `--request-id` is omitted.
+- An explicit `deadlineSeconds` that is shorter than the settlement window (`fulfillmentDeadlineSeconds`) is now rejected — the deposit permit must stay valid until settlement.
+- Solana now honors an explicit `nonce` (it was ignored on Solana in 1.0.2) and validates it at build time: a caller-supplied nonce must fit an unsigned 64-bit integer and its low byte (the on-chain replay slot) must be `< 235`, otherwise the build throws instead of failing later on-chain. Omitting `nonce` still derives it deterministically as before.
+
+### Changed
+- Deposits are now built and signed through the shared `@atum-labs/payment-request-sender-auth` library instead of the client's own copy of that logic (single source of truth across the payment stack). The public signing API (`createSenderSigner`, `signPaymentRequest`, `resolveTurnkeyAddresses`) is unchanged.
+- The EVM/Tron deposit permit deadline now tracks the payment's settlement (`fulfillment_deadline`) instead of a fixed far-future date, so the authorization's validity window is meaningful.
+
+### Added
+- The deposit's single-use nonce is now derived deterministically from `request_id` + depositor, so rebuilding the same payment (e.g. on retry) reproduces the same single-use nonce. The guarantee differs by chain: on EVM/Tron the Permit2 nonce is a permanent on-chain bitmap, so of any number of rebuilds only one deposit can ever settle; on Solana the escrow replay nonce protects only within a ~128s window (`issued_at` is re-read per build), and the gateway's `request_id` dedup is the durable backstop beyond it — pin `issued_at` via `solanaClockReader` to keep a rebuild inside the same window.
+- The depositor address is canonicalized before it seeds the nonce: EVM `0x` addresses are lower-cased (so a checksummed and a lowercase address derive the same nonce), while case-sensitive base58 (Solana/Tron) is used verbatim.
+
 ## [1.0.2] - 2026-07-17
 
 ### Added

package/README.md

@@ -2,25 +2,38 @@
 
 TypeScript client for Atum Payment Gateway API with CLI support.
 
+> **Proprietary software - not open source.**
+>
+> Copyright (c) 2026 Atum Labs, Inc. All rights reserved. Access to and use of `@atumlabs/payment-gateway-client` are limited to entities expressly authorized by Atum and are governed by the Atum Payment Gateway Client Private Repository License Agreement in the LICENSE file included with this package. Do not redistribute, publish, mirror, sublicense, or provide this package to any unauthorized person. By accessing, installing, copying, or using the package, you agree to the license terms.
+
 > NOTE: Payments from EVM chains require prior ERC-20 approval on the source token for the Permit2 contract (0x000000000022D473030F116dDEE9F6B43aC78BA3 on virtually all EVM chains).
 > 
-> (And the same applies for Tron/TRC-20, with a Permit2 address of TJhMXTHQHeQyMD7TcKQFqAePNgG4b31H9m on mainnet or TPUqJPASUn1zLvbLBgRZ5pBYrx7WSe5ahp on Shasta)`)
+> (And the same applies for Tron/TRC-20, with a Permit2 address of TJhMXTHQHeQyMD7TcKQFqAePNgG4b31H9m on mainnet or TPUqJPASUn1zLvbLBgRZ5pBYrx7WSe5ahp on Shasta).
 
 ## Installation
 
 `@atumlabs/payment-gateway-client` is a private npm package. Once your npm account
-has been granted access, install it with npm:
+has been granted access, install it with npm.
+
+To use the SDK in a project:
 
 ```bash
 npm install @atumlabs/payment-gateway-client
 ```
 
-This also installs the `send-payment`, `request-quote`, `quote-status`, and
-`payment-status` CLI commands.
+To use the command-line tools, install globally so they are on your `PATH`:
+
+```bash
+npm install -g @atumlabs/payment-gateway-client
+```
+
+A project-local install also provides the commands, under `node_modules/.bin`, so
+`npx send-payment ...` works without a global install.
 
 ## CLI Usage
 
-After linking, the `send-payment` command is available globally:
+The package provides four commands: `send-payment`, `request-quote`,
+`quote-status`, and `payment-status`. After a global install:
 
 ```bash
 send-payment [options] <sender> <amount> <sourceAsset> <receiver> <destinationAsset>
@@ -38,8 +51,8 @@ send-payment [options] <sender> <amount> <sourceAsset> <receiver> <destinationAs
 
 - `-V, --version` - Output the version number
 - `--gateway <url>` - Payment gateway URL (default: testnet)
-- `--request-id <id>` - Custom request ID (overrides prefix)
-- `--request-id-prefix <prefix>` - Custom request ID prefix (default: `pmt-gw-cli`)
+- `--request-id <id>` - Idempotency key; seeds the on-chain deposit nonce. Reuse the same id to retry a payment safely. Omitted: a one-shot id is generated and printed (see [Idempotency and retries](#idempotency-and-retries))
+- `--request-id-prefix <prefix>` - Prefix for the auto-generated request id (default: `pmt-gw-cli`)
 - `-h, --help` - Display help
 
 ### CAIP-19 Asset Format Examples
@@ -75,19 +88,32 @@ export TURNKEY_API_PRIVATE_KEY=...
 send-payment --provider turnkey <args...>
 ```
 
-Turnkey signing uses the shared `@atum-labs/turnkey-signer` (and `@atum-labs/km-core`),
-which live in this monorepo under `key-management/` and are consumed as pnpm workspace
-packages (`workspace:*`), built locally by the `build:deps` step. `@solana/web3.js` and
-the other Turnkey deps are already declared, so no extra setup is required.
+Everything Turnkey signing needs is already declared as a dependency, so no extra
+setup is required. The Turnkey code is loaded on demand, so the private-key path
+does not pull in Turnkey or `@solana/web3.js`.
+
+### Configuration file
+
+The command-line tools also read an optional `.env` file from the directory you
+run them in, so credentials and settings do not have to be retyped each time:
+
+```
+PRIVATE_KEY=0x...
+GATEWAY_URL=https://payment-gw.production-testnet.atum.xyz
+SOLANA_RPC_URL=
+TURNKEY_ORGANIZATION_ID=
+TURNKEY_WALLET_ID=
+TURNKEY_API_PUBLIC_KEY=
+TURNKEY_API_PRIVATE_KEY=
+```
 
-Notes:
-- The shared packages are workspace members, so a root `pnpm install` links them, and
-  `pnpm run build` and `pnpm test` build them first (`build:deps`).
-- The Turnkey code is loaded lazily (`import('./turnkey-impl')`), so the private-key
-  path never pulls in Turnkey or `@solana/web3.js`.
-- For publishing, the build (tsup) bundles the shared `@atum-labs/*` packages directly
-  into `dist`, so the published package is self-contained with no `@atum-labs/*` runtime
-  dependencies. The siblings stay `workspace:*` devDependencies used only at build time.
+Where a setting has a matching flag, the flag takes precedence, then a value
+already set in your environment, then `.env`, then the built-in default. Keep the
+file out of version control — it holds signing keys.
+
+This applies to the command-line tools only. The SDK does not read `.env`; pass
+configuration as arguments, or set `GATEWAY_URL` in your own application's
+environment.
 
 ### Output
 
@@ -105,12 +131,10 @@ PRIVATE_KEY=0xabc... send-payment \
   tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs
 ```
 
-### Unlinking
-
-To remove the global CLI command:
+### Removing the command-line tools
 
 ```bash
-npm unlink -g @atumlabs/payment-gateway-client
+npm uninstall -g @atumlabs/payment-gateway-client
 ```
 
 ## SDK Usage
@@ -118,18 +142,31 @@ npm unlink -g @atumlabs/payment-gateway-client
 ### Basic Setup
 
 ```typescript
-import { 
+import {
   PaymentGatewayClient,
+  createSenderSigner,
+  signPaymentRequest,
+  getErrorResponse,
   type PaymentResponse,
-  ApiError
+  ApiError,
 } from '@atumlabs/payment-gateway-client';
-import { ethers } from 'ethers';
 
 const client = new PaymentGatewayClient({
-  BASE: 'https://payment-gateway.atumlabs.xyz' // or your gateway URL
+  BASE: 'https://payment-gw.production-testnet.atum.xyz' // or your gateway URL
 });
 ```
 
+### Gateway URL
+
+The client uses the production-testnet gateway by default. To target another
+environment, in order of precedence:
+
+1. Pass it explicitly — SDK `new PaymentGatewayClient({ BASE })`, or the CLI `--gateway` flag.
+2. Set the `GATEWAY_URL` environment variable.
+3. Otherwise the built-in default `https://payment-gw.production-testnet.atum.xyz` is used.
+
+Mainnet access is granted by Atum; use the mainnet gateway URL provided to you.
+
 ### Example: Tron to Celo Sepolia Payment
 
 ```typescript
@@ -149,15 +186,22 @@ async function sendPayment() {
     fulfillmentAmount: '100000', // 0.10 USDT (6 decimals)
     sourceAsset: 'tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs', // USDT on Tron Shasta
     destinationAccount: '0xYourEthereumAddressHere',
-    destinationAsset: 'eip155:11142220/erc20:0x456a3D042C0DbD3db53D5489e98dFb038553B0d0' // USDC on Celo Sepolia
+    destinationAsset: 'eip155:11142220/erc20:0x456a3D042C0DbD3db53D5489e98dFb038553B0d0', // USDC on Celo Sepolia
+    // Required. Your stable idempotency key — reuse the SAME value on retry so a
+    // retry never becomes a second payment (see "Idempotency and retries" below).
+    requestId: 'order-4711',
   });
 
-  // Sign the message (Tron uses the same signing as Ethereum, but without the 0x private key prefix)
-  const wallet = new ethers.Wallet(privateKey.replace(/^0x/, ''));
-  paymentRequest.sender_auth.signed_messages[0].signature = 
-    wallet.signingKey.sign(
-      paymentRequest.sender_auth.signed_messages[0].message
-    ).serialized;
+  // Sign the prepared request with the SDK signer helper. It handles the
+  // per-chain signing differences internally (EVM typed-data, Tron hash,
+  // Solana Ed25519), so you never touch a chain library directly.
+  const sourceChainId = 'tron:shasta'; // CAIP-2 chain id, i.e. sourceAsset.split('/')[0]
+  const signer = createSenderSigner(sourceChainId, {
+    provider: 'raw',
+    privateKey,
+    pinnedAddress: tronSender,
+  });
+  await signPaymentRequest(paymentRequest, signer);
 
   try {
     // Submit the payment
@@ -172,9 +216,11 @@ async function sendPayment() {
     
     return response;
   } catch (error) {
-    if (error instanceof ApiError) {
-      console.error('API Error:', error.status, error.statusText);
-      console.error('Response:', error.body);
+    const gwError = getErrorResponse(error);
+    if (gwError) {
+      console.error('Gateway error:', gwError.code, gwError.message, gwError.request_id);
+    } else if (error instanceof ApiError) {
+      console.error('HTTP', error.status, error.statusText, error.url);
     }
     throw error;
   }
@@ -183,15 +229,29 @@ async function sendPayment() {
 
 ### Error Handling
 
-The SDK provides detailed error information through the `ApiError` type:
+The gateway returns a typed, public error body — `ErrorResponse`
+(`{ code, message, request_id?, docs_url?, domain? }`). Use `getErrorResponse`
+to narrow a caught error to it; it returns `undefined` for anything that is not
+a gateway error with that shape. For transport-level detail (HTTP status, URL),
+the thrown value is still an `ApiError`.
 
 ```typescript
-catch (error) {
-  if (error instanceof ApiError) {
-    console.error('Status:', error.status);
-    console.error('Status Text:', error.statusText);
-    console.error('URL:', error.url);
-    console.error('Response Body:', error.body);
+import { getErrorResponse, ApiError } from '@atumlabs/payment-gateway-client';
+
+try {
+  await client.payments.submitPayment({ requestBody: paymentRequest });
+} catch (error) {
+  const gwError = getErrorResponse(error);
+  if (gwError) {
+    console.error('Code:', gwError.code);             // machine-readable category
+    console.error('Message:', gwError.message);       // safe, human-readable text
+    console.error('Request ID:', gwError.request_id); // quote this to support
+    console.error('Docs:', gwError.docs_url);
+  } else if (error instanceof ApiError) {
+    // Transport-level failure with no typed body (e.g. a proxy/gateway error).
+    console.error('HTTP', error.status, error.statusText, error.url);
+  } else {
+    throw error;
   }
 }
 ```
@@ -203,13 +263,29 @@ Assets are identified using the [CAIP-19](https://chainagnostic.org/CAIPs/caip-1
 - Tron example: `tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs`
 - EVM example: `eip155:11142220/erc20:0x456a3D042C0DbD3db53D5489e98dFb038553B0d0`
 
-## Package Structure
+## Idempotency and retries
+
+Every payment carries a `request_id`. Pass a stable value and reuse the exact
+same one on every retry (a timeout, a network blip, a restart) and you end up
+with one payment, not two — and you get the same answer each time.
+
+- Using this SDK, `request_id` is **required** on the payment path
+  (`preparePaymentRequest`), and it is the only thing you manage: the SDK derives
+  the on-chain deposit nonce deterministically from it, so retries line up on
+  their own. Reuse the same `request_id` to retry safely.
+- On the CLI, `--request-id` is optional; when omitted a one-shot id is generated
+  and printed, so you can re-run with `--request-id <id>` to retry the same
+  payment.
+- A genuinely new payment needs a **new** `request_id`. Reusing one with different
+  terms (a corrected amount, a different token) returns the original payment
+  rather than an error, so the new terms are silently dropped.
 
-- `src/` - Source TypeScript files
-  - `generated/` - Auto-generated API client from OpenAPI spec
-  - `cli/` - CLI implementation
-- `dist/` - Pre-compiled JavaScript (ready to use)
+See [docs/idempotency.md](docs/idempotency.md) for the full model: the two
+guarantees and the per-chain differences (EVM/Tron vs Solana).
 
----
+## What is in the package
 
-This repository contains proprietary Atum Labs code. Access is restricted and governed by the Private Repository License included in this repo.
+- `dist/` — compiled JavaScript and TypeScript declarations, ready to use
+- `dist/cli/` — the four command-line tools
+- `docs/` — reference documentation, including [idempotency and retries](docs/idempotency.md)
+- `LICENSE`, `THIRD-PARTY-NOTICES.txt` — license terms and third-party attribution

package/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,45 @@
+THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
+==============================================================================
+@atumlabs/payment-gateway-client
+
+The published artifact of this package (the compiled code under dist/) statically
+bundles the third-party open-source components listed below; their source is
+redistributed within this package, so their license and copyright notices are
+reproduced here. Components and versions were taken from the exact modules the
+build inlined. This file does NOT cover packages the consumer installs separately
+as dependencies of this package (for example @solana/web3.js, axios, ethers, bs58,
+commander, dotenv, tweetnacl, and zod) — those ship under their own licenses and are not
+redistributed here.
+
+LICENSE SUMMARY (1 component)
+------------------------------------------------------------------------------
+    1  MIT
+==============================================================================
+
+------------------------------------------------------------------------------
+@noble/hashes  1.8.0   (MIT)
+Author: Paul Miller (https://paulmillr.com)
+------------------------------------------------------------------------------
+
+The MIT License (MIT)
+
+Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+