@catena/sdk 0.0.0-alpha-20260818193756 → 0.1.0

package/README.md

@@ -1,33 +1,34 @@
 # @catena/sdk
 
 Typed client for the Catena agent API: read accounts, balances, and policy, move
-money through policy-checked intents, and pay x402 (HTTP 402) challenges.
+money through policy-checked intents, and pay MPP or x402 HTTP 402 challenges.
 Node >= 20; no framework dependencies.
 
-## Status: prerelease snapshots
+## Status
 
-Versions published under the `alpha` dist-tag are throwaway development
-snapshots cut directly from the Catena monorepo. They carry no stability or
-semver guarantees: any API may change or disappear between snapshots, and
-snapshot versions (`0.0.0-alpha-<timestamp>`) never match ordinary semver ranges
-— only an exact version, an explicit prerelease range, or a dist-tag like
-`alpha` selects one.
+The SDK is in initial development. Patch releases within a `0.x` minor are
+intended to remain compatible; a new minor may change the public API. Test
+upgrades before moving to a new `0.x` minor.
 
 ```sh
-npm install @catena/sdk@alpha
+npm install @catena/sdk
 ```
 
-Pin the exact version you tested against; do not depend on the `alpha` tag
-resolving to anything compatible over time.
-
 ## Entry points
 
 - `@catena/sdk` — the client: `createCatenaClient`, intents, accounts,
   counterparties, error types.
 - `@catena/sdk/keypair` — generate or derive the P-256 credential and compute
   its thumbprint.
+- `@catena/sdk/mpp` — a managed MPP `fetch` wrapper plus Catena-backed
+  `evm/charge` and `usdc/charge` methods for custom mppx integrations. Requires
+  `mppx` and its viem peer dependencies (both optional SDK peer dependencies;
+  install `mppx@0.9.0` and `viem@^2.54.0`).
 - `@catena/sdk/x402` — a `fetch` wrapper that pays x402 402 challenges through
   Catena.
+- `@catena/sdk/viem` — a viem `Account` backed by a Catena wallet, for x402
+  client tooling that expects an account or `{ address, signTypedData }`.
+  Requires `viem` (an optional peer dependency — install it yourself, `^2.21`).
 
 ## Authentication
 
@@ -81,6 +82,18 @@ await client.submitIntent({
 // Email-only creation saves a counterparty without sending an email. A completed
 // intent returns data.counterparty with status "awaiting_details" and no rails.
 
+await client.submitIntent({
+  action: {
+    type: "request_counterparty_details",
+    counterpartyId: counterparties[0].id,
+    methods: { bank: true, wallet: false },
+  },
+})
+
+// The request follows policy and may remain pending for human approval. While
+// an invitation is outstanding, another request returns ApiError status 409
+// with code "counterparty_payment_request_conflict" and details.invite.
+
 // The rail must match the method: "ach" and "wire" need a bank rail,
 // "on-chain" needs a wallet rail. Pass the rail id, not the counterparty id.
 const bankRail = counterparties
@@ -90,7 +103,6 @@ const bankRail = counterparties
 const intent = await client.submitIntent({
   action: {
     type: "send",
-    accountId: accounts[0].id,
     counterpartyRailId: bankRail.id,
     // Decimal USD string: "12.50" is $12.50. Never cents or atomic units.
     amount: "12.50",
@@ -99,18 +111,37 @@ const intent = await client.submitIntent({
 })
 ```
 
+For `send`, omit `accountId` when the agent's current effective policy allows
+sends from exactly one account. Other readable or transfer accounts do not
+count. The server rejects zero send accounts with HTTP 403
+(`policy_send_account_unavailable`) and multiple send accounts with HTTP 400
+(`policy_send_account_required`). An explicit account always stays explicit; it
+is never replaced with another account. Transfers still require `accountId`.
+
+The result's `accountId` is the resolved source, pinned at creation and returned
+by `getIntent` too, including for pending or blocked intents. Approval checks
+the pinned account against the current policy; it never chooses a new source.
+
+Each new accountless operation resolves the current policy. Reusing an explicit
+idempotency key keeps the original intent's source, even if the policy now
+selects another account or no longer has a unique send account. Changed payment
+details or an explicitly different source return HTTP 409. Policy-blocked
+attempts are reevaluated against the current policy with the source still
+pinned. Use a new key for a new operation. If the outcome of a submission is
+unknown, check that intent before submitting again.
+
 `submitIntent` returns a disposition, not a guarantee of execution — branch on
 `intent.status`:
 
 - `"completed"` — the action succeeded: money moved for send, transfer, and
-  wallet_send; for x402 the payment authorization was delivered (on-chain
-  settlement is verified separately); the counterparty exists for
+  wallet_send; for MPP and x402 the payment authorization was delivered
+  (on-chain settlement is verified separately); the counterparty exists for
   create_counterparty.
 - `"pending"` — parked, typically awaiting a human approval; `reasons` says why,
   `expiresAt` says when the approval request lapses.
 - `"processing"` — accepted and in progress. Executing intents advance on their
-  own; poll `getIntent(intent.id)`. An approved x402 payment instead rests here
-  until the paid request is re-run — polling never advances it.
+  own; poll `getIntent(intent.id)`. An approved MPP or x402 payment instead
+  rests here until the paid request is re-run — polling never advances it.
 - `"blocked"` — declined by policy or denied by an operator; `reasons` explains
   why approval was required, not necessarily why it was denied. Terminal.
 - `"failed"` — failed, expired, or reversed. Terminal.
@@ -144,12 +175,13 @@ deadline, so a multi-exchange operation may take several timeout periods.
   directly; a submit-stamp timeout is the `cause` of an `IntentSubmitError`
   whose `outcome` is `"unknown"`.
   - A timeout means the SDK stopped waiting, not that the server did no work.
-  - After a create-intent timeout, retry only the identical action with the same
-    explicit `idempotencyKey`, or leave the key omitted on both attempts so the
-    server derives the same one. A derived key deduplicates send and transfer
-    retries for about 15 minutes after the first intent settles. Use a stable
-    explicit key if the retry can happen later. Never use a fresh key merely
-    because the response was lost.
+  - Each `submitIntent` invocation generates a fresh UUID when `idempotencyKey`
+    is omitted. Matching actions alone are not deduplicated.
+  - To recover an exact submission after a create-intent timeout, choose and
+    persist an explicit `idempotencyKey` before the first call, then retry the
+    unchanged action with that key. Reusing it with a different action
+    returns 409. If the first call omitted the key, do not treat a second call
+    as its retry: it is a new logical operation.
   - If that retry throws an `ApiError` with status `409` and code
     `wallet_send_intent_not_executing` or `x402_intent_state_mismatch`, the SDK
     cannot reissue the co-signing body and the response carries no intent ID.
@@ -160,11 +192,16 @@ deadline, so a multi-exchange operation may take several timeout periods.
     awaiting expiry. A payment pending or granted approval is instead matched by
     its canonical requirements and reused; a lapsed approval may park again.
 - `IntentSubmitError` — `submitIntent` failed after the intent was created.
-  Branch on `outcome`: `"not-submitted"` means no money moved — recovery is a
-  new `submitIntent` with a fresh explicit `idempotencyKey` (omitting it replays
-  the same stranded intent); `"unknown"` means the server may have acted — poll
-  `getIntent(err.intentId)` to a terminal status and resubmit only after blocked
-  or failed, never blindly.
+  Branch on `outcome`:
+
+  - `"not-submitted"` means no money moved. Recover with a new `submitIntent`
+    invocation and a new key, typically after fixing the signing credential.
+    Omit `idempotencyKey` to generate one, or supply a different value. Reusing
+    the original key finds the stranded intent and can return a 409 rather than
+    restart signing.
+  - `"unknown"` means the server may have acted — poll `getIntent(err.intentId)`
+    to a terminal status and resubmit only after blocked or failed, never
+    blindly.
 
 ## Paying x402 challenges
 
@@ -204,6 +241,241 @@ re-run the same request after approval; `X402RetryFailedError` and
 `X402SubmitInterruptedError` mean money may have already moved — follow the
 recovery steps in the error message instead of paying again.
 
+## Paying MPP challenges
+
+Install mppx and its compatible viem version alongside the SDK. Catena supports
+the `evm/charge` and `usdc/charge` wire pairs for native USDC on Base and Base
+Sepolia:
+
+```sh
+npm install @catena/sdk mppx@0.9.0 viem@^2.54.0
+```
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+import { wrapFetchWithMppPayment } from "@catena/sdk/mpp"
+
+const client = createCatenaClient()
+const fetchWithPayment = wrapFetchWithMppPayment(client, {
+  accountId: walletAccountId,
+  // Refuse a price above 1 USDC before creating an intent.
+  maxAtomicAmount: 1_000_000n,
+  onPayment: (receipt) => {
+    recordPayment(receipt)
+  },
+})
+
+const response = await fetchWithPayment("https://api.example.com/paid-thing")
+```
+
+The managed wrapper passes ordinary responses and undecodable 402s through
+untouched. For an eligible challenge, mppx parses and orders the candidates,
+chooses `Authorization` or `Payment-Authorization`, and attaches the credential.
+The wrapper tries at most the first five supported candidates and moves to the
+next only when Catena returns `mpp_challenge_not_payable`,
+`mpp_network_mismatch`, or `mpp_counterparty_rail_not_found`. It creates at most
+one credential and makes exactly one paid retry.
+
+The payment is bound to the response's final canonical URL. A cross-origin
+redirect is rejected before an intent is created. The credential-bearing retry
+preserves the caller's redirect mode and delegates redirect handling to the
+configured Fetch implementation, consistent with the x402 wrapper. Request
+bodies must be replayable: use a string, `URLSearchParams`, Blob, ArrayBuffer,
+or typed array in the `init` argument; a body-bearing `Request`,
+`ReadableStream`, or raw `FormData` is refused before payment. The wrapper does
+not pre-verify an optional request digest—the seller verifies it when accepting
+the credential.
+
+`onPayment` runs once after Catena completes and validates the credential, but
+before the paid retry. Its `MppPaymentReceipt` contains the intent ID, validated
+method and terms, and canonical resource URL; it never contains the credential.
+If the callback, retry, or a second 402 fails, `MppRetryFailedError.receipt`
+identifies the completed intent so the caller does not pay twice.
+
+Recovery errors are explicit: retry the original request after resolving
+`MppApprovalPendingError`; treat `MppPaymentDeclinedError` as terminal; fund one
+of `MppNetworkMismatchError.requiredNetworks`; and add the rail named by
+`MppCounterpartyNotFoundError`. For `MppSubmitInterruptedError`, first reconcile
+`intentId` with `client.getIntent(...)`, because submission may have succeeded.
+A create-phase `TimeoutError`, non-fallback `ApiError`, and `IntentSubmitError`
+with outcome `"not-submitted"` propagate unchanged.
+
+### Custom mppx integration
+
+Use the lower-level Catena methods when the host needs its own candidate policy,
+retry count, event hooks, or transport behavior:
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+import { catena } from "@catena/sdk/mpp"
+import { Mppx } from "mppx/client"
+
+const client = createCatenaClient()
+const mppx = Mppx.create({
+  methods: [
+    catena({
+      client,
+      accountId: walletAccountId,
+      maxAtomicAmount: 1_000_000n,
+    }),
+  ],
+  maxPaymentRetries: 1,
+  polyfill: false,
+})
+
+const response = await mppx.fetch("https://api.example.com/paid-thing")
+```
+
+`catena.charge(...)` is an equivalent alias for `catena(...)`. mppx parses and
+selects challenges, chooses `Authorization` or `Payment-Authorization`, retries
+the request, and runs its response hooks. The Catena method submits the selected
+challenge through the normal policy and approval lifecycle, then returns the
+serialized credential to mppx.
+
+By default, `mppx@0.9.0` allows up to three automatic payment attempts per
+fetch. If the seller keeps returning payable challenges with fresh IDs, one
+fetch can produce multiple payment authorizations that may be redeemed
+separately. Each attempt still goes through Catena policy and approval checks;
+these checks do not guarantee one payment per fetch.
+
+Set `maxAtomicAmount` when creating the Catena methods to refuse an individual
+challenge above that price before creating an intent. The value uses atomic USDC
+units (6 decimals, so `1_000_000n` is 1 USDC). The server's policy limits still
+apply. This ceiling is checked separately for every challenge and does not limit
+the number of attempts.
+
+To allow only one automatic payment attempt per fetch, set
+`maxPaymentRetries: 1` in `Mppx.create(...)`. This stops automatic negotiation
+of fresh challenges after that attempt, but does not prevent duplicate purchases
+across separate fetch calls.
+
+With `mppx@0.9.0`, pass the HTTP method and body in the fetch `init` argument,
+not only inside a `Request` object. mppx rebuilds the paid retry from `init`, so
+a method or body stored only in `Request` can be lost: a POST may retry as a
+bodiless GET, and even a bodiless DELETE may retry as GET. For example:
+
+```ts
+const response = await mppx.fetch("https://api.example.com/paid-thing", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ query: "example" }),
+})
+```
+
+The body must also be reusable and byte-stable: every attempt must send the same
+bytes, as with the JSON string above. Raw `FormData` can generate a new
+multipart boundary each time it is sent, so identical fields can still fail a
+seller's request-body digest check. Serialize multipart bodies once, then reuse
+the resulting bytes and matching `Content-Type` on every attempt. Do not rely on
+`ReadableStream` bodies being replayed: the first send consumes the stream, and
+the paid retry can fail after authorization. Buffer the body before the first
+request instead; this uses memory and sacrifices streaming uploads.
+
+The method relays a challenge digest unchanged; it does not read or hash the
+HTTP request body. The seller verifies any body binding when it accepts the
+credential. Unsupported methods, intents, currencies, networks, and credential
+types are rejected before a Catena intent is submitted.
+
+Additional selection requirements apply: the UTC challenge expiry must end in
+`Z`, use no more than 3 fractional-second digits, and leave at least 5 seconds
+and no more than 1 hour. The optional credential header must be omitted or be
+exactly `Payment-Authorization`. An optional digest must use
+`sha-256=:<base64>:` or the mppx 0.9 spelling `sha-256=<base64>`, with a
+canonical, padded standard-base64 SHA-256 value. Optional `opaque` data must be
+nonempty, unpadded base64url. Addresses must be lowercase or have a valid EIP-55
+checksum. Request `description` and `externalId` text must contain valid Unicode
+without unpaired surrogates. When `maxAtomicAmount` is configured, the request
+amount must not exceed it.
+
+When Catena declines a challenge during selection, mppx can report
+`No method found for challenges` even when it lists `evm.charge` or
+`usdc.charge` as available. Check these requirements as well as the supported
+payment types when diagnosing that error.
+
+An intent result that does not yield a usable credential throws
+`MppPaymentError`, which exposes `intentId`, `status`, `reasons`, and
+`expiresAt`. A pending payment needs human approval. Inspect an in-flight intent
+with `client.getIntent(error.intentId)`. After approval, re-run the original
+paid request so its fresh challenge can consume the approved grant; polling
+reports the status but never advances an approved MPP payment. Blocked and
+failed payments include the server's reasons in the thrown error.
+
+Submission can also throw `IntentSubmitError` from `@catena/sdk`. An `outcome`
+of `"unknown"` means the server may already have signed an authorization. Poll
+`client.getIntent(error.intentId)` to determine the outcome before making
+another payment attempt.
+
+An HTTP failure (including another 402), network error, or later
+`MppPaymentError` does not prove that earlier authorizations were unused. An
+`MppPaymentError` describes only its own intent; earlier attempts in the same
+fetch may already have produced redeemable credentials. Before retrying the
+original request, including after approval, reconcile all payment attempts, not
+just the intent named in the last error. Use `client.getIntent(intentId)` for
+known intents; for MPP, `completed` means an authorization was produced, not
+proof of settlement or delivery of the purchased resource. If earlier outcomes
+are unclear, reconcile with the operator and seller before making another
+payment attempt. Do not automatically retry an ambiguous payment.
+
+## Using the wallet as a viem account
+
+A Catena wallet is custodial: your credential authenticates requests and
+co-signs intents, and the wallet's own key never leaves the custodian. So the
+account `@catena/sdk/viem` returns signs exactly one thing — x402 EIP-3009
+`TransferWithAuthorization` typed data for USDC on Base or Base Sepolia, routed
+through a policy-checked payment intent. That is the payload x402 client
+libraries build, which makes the account a drop-in signer for tooling that knows
+nothing about Catena:
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+import { createCatenaAccount } from "@catena/sdk/viem"
+
+const client = createCatenaClient()
+const account = await createCatenaAccount(client, {
+  accountId: walletAccountId,
+  // Must match the network the wallet account is configured for; defaults to
+  // "base". A testnet wallet needs "base-sepolia" here.
+  network: "base",
+})
+
+// Hand `account` to any x402 client that accepts a viem account or
+// an { address, signTypedData } signer, e.g.:
+//   wrapFetchWithPayment(fetch, clientWithScheme(account))
+```
+
+The contract, in brief:
+
+- `signTypedData` accepts only `TransferWithAuthorization` for USDC on Base
+  (8453) or Base Sepolia (84532). Anything else throws
+  `UnsupportedTypedDataError` client-side, with a machine-readable `reason` —
+  nothing is submitted.
+- The returned signature is verified to recover to the wallet address for the
+  exact typed data you passed before it is returned; a mismatch throws
+  `SignatureVerificationFailedError` instead of surfacing a bad signature. That
+  check runs after the payment completed, so it belongs to the
+  money-may-have-moved group below, not to the client-side refusals above.
+- `signMessage` and `signTransaction` throw `UnsupportedAccountCapabilityError`;
+  there is no raw-hash `sign`.
+- A payment over a policy approval threshold throws `X402ApprovalPendingError`
+  (the same class `@catena/sdk/x402` throws). Approve it in the Catena console,
+  then let the tooling retry — a retry with a fresh nonce still consumes the
+  approval.
+- A policy block or terminal failure throws `X402PaymentDeclinedError` with the
+  server's reasons; request-level failures (for example a reused nonce)
+  propagate as `ApiError` with a stable `code`.
+- Once the payment may have moved, every failure carries the intent id:
+  `X402SubmitInterruptedError` (the submission was interrupted after the payment
+  may have been claimed), `X402PaymentSignatureUnusableError` (it completed
+  carrying a signature this SDK cannot use), `X402PaymentInFlightError` (still
+  in flight — note that polling does not advance an approved x402 payment
+  resting there; it waits for the paid request to be re-run), and
+  `SignatureVerificationFailedError`. Reconcile with `getIntent(intentId)`
+  instead of paying again. Note the shape difference: the intent's
+  `data.paymentCredential.value` is the base64 x402 envelope used as the
+  `PAYMENT-SIGNATURE` header, whereas `signTypedData` returns the inner hex
+  signature decoded out of it — passing the envelope to a viem-based signer path
+  will fail on shape.
+
 ## License
 
 [Apache-2.0](./LICENSE)