@catena/sdk 0.0.0-alpha-20260724191736

package/dist/x402.d.mts

@@ -0,0 +1,175 @@
+import { T as X402Resource, i as FetchLike, n as CatenaClient, w as X402PaymentRequirements } from "./client-DZHdFs_y.mjs";
+import * as v from "valibot";
+
+//#region src/x402.d.ts
+declare const paymentRequiredSchema: v.LooseObjectSchema<{
+  /**
+   * Pinned to the wire version this loop speaks. Paying a v1 or future
+   * incompatible challenge would settle money for a retry header the server
+   * cannot consume.
+   */
+  readonly x402Version: v.LiteralSchema<2, undefined>;
+  readonly accepts: v.ArraySchema<v.LooseObjectSchema<{
+    readonly scheme: v.StringSchema<undefined>;
+    readonly network: v.StringSchema<undefined>;
+    readonly asset: v.StringSchema<undefined>;
+    readonly amount: v.StringSchema<undefined>;
+    readonly payTo: v.StringSchema<undefined>;
+    readonly maxTimeoutSeconds: v.NumberSchema<undefined>;
+  }, undefined>, undefined>;
+  readonly resource: v.OptionalSchema<v.LooseObjectSchema<{
+    readonly url: v.StringSchema<undefined>;
+    readonly serviceName: v.SchemaWithFallback<v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>, undefined>;
+  }, undefined>, undefined>;
+}, undefined>;
+type X402PaymentRequired = v.InferOutput<typeof paymentRequiredSchema>;
+/**
+ * Decode a 402 response's `PAYMENT-REQUIRED` challenge. Returns undefined for
+ * a 402 that carries no decodable v2 challenge (not an x402 endpoint).
+ */
+declare function decodePaymentRequired(response: Response): X402PaymentRequired | undefined;
+/**
+ * Payment failure raised by this module; `reasons` carries the policy or
+ * decline detail when the server provided any, and subclasses mark the cases
+ * with a specific recovery path. Not every loop failure is one of these:
+ * a create-phase `ApiError` the loop does not absorb as a candidate skip
+ * and a "not-submitted" `IntentSubmitError` propagate unchanged.
+ */
+declare class X402PaymentError extends Error {
+  readonly reasons: readonly string[];
+  constructor(message: string, reasons?: readonly string[]);
+}
+/**
+ * Every payable candidate in the challenge targets a network the source
+ * account is not on, so nothing could be funded. Distinct from a generic
+ * non-payable requirement: the fix is to fund the payment from a wallet
+ * account on one of `requiredNetworks`, not to change policy. Consumers can
+ * name those networks (and, for a CLI, tell the user how to switch accounts).
+ */
+declare class X402NetworkMismatchError extends X402PaymentError {
+  readonly accountId: string;
+  readonly requiredNetworks: readonly string[];
+  constructor(accountId: string, requiredNetworks: readonly string[]);
+}
+/**
+ * The challenge's `payTo` is not a saved counterparty wallet rail, so the
+ * allowlist has nothing to authorize and the payment fails closed. The 402's
+ * `payTo` is attacker-controlled, so Catena never auto-adds it: the fix is a
+ * deliberate `create_counterparty` (itself policy-gated) for `payTo` on
+ * `network`, then a re-run. Consumers can name the recipient (and, for a CLI,
+ * print the exact counterparty-create command).
+ */
+declare class X402CounterpartyNotFoundError extends X402PaymentError {
+  readonly payTo: string;
+  readonly network: string;
+  /**
+   * The challenge's advertised service name, when present — a suggested
+   * counterparty name.
+   */
+  readonly serviceName: string | undefined;
+  constructor(payTo: string, network: string, serviceName?: string);
+}
+/**
+ * The payment exceeded a policy limit and is parked for a human approval.
+ * Not a decline: once an operator approves it in the console, re-running the
+ * same request (same endpoint, same price) consumes the approval and pays.
+ * `expiresAt` is when the pending approval self-expires.
+ */
+declare class X402ApprovalPendingError extends X402PaymentError {
+  readonly intentId: string;
+  readonly expiresAt: string | null;
+  constructor(intentId: string, reasons: readonly string[], expiresAt: string | null);
+}
+/**
+ * The paid retry failed AFTER the payment settled. The receipt is the
+ * caller's recovery handle: retry the request manually with its
+ * `paymentSignature` as the `PAYMENT-SIGNATURE` header (also re-readable via
+ * `getIntent(intentId)` at `data.x402.paymentSignature` while the
+ * authorization is valid) — re-running the whole loop would mint a second
+ * payment.
+ */
+declare class X402RetryFailedError extends X402PaymentError {
+  readonly receipt: X402PaymentReceipt;
+  constructor(receipt: X402PaymentReceipt, cause: unknown);
+}
+/**
+ * The submission failed after the intent was created with its outcome
+ * unknown — the server may have already claimed and settled (a response lost
+ * in transit is the canonical case). Re-running the loop would mint a second
+ * intent and risk a double-pay, so the caller must reconcile via
+ * `getIntent(intentId)`: if it completed, reuse
+ * `data.x402.paymentSignature` as the `PAYMENT-SIGNATURE` header; if
+ * processing, it is mid-settlement — keep polling. Pay again only once it is
+ * terminally blocked or failed.
+ */
+declare class X402SubmitInterruptedError extends X402PaymentError {
+  readonly intentId: string;
+  readonly requirements: X402PaymentRequirements;
+  constructor(intentId: string, requirements: X402PaymentRequirements, cause: unknown);
+}
+interface X402PaymentReceipt {
+  /**
+   * The Catena intent that settled the payment; pass to `getIntent`.
+   */
+  intentId: string;
+  /**
+   * Encoded value for the retry's `PAYMENT-SIGNATURE` header. Re-readable
+   * via `getIntent(intentId)` at `data.x402.paymentSignature` while the
+   * authorization is valid.
+   */
+  paymentSignature: string;
+  /**
+   * The challenge candidate that was paid.
+   */
+  requirements: X402PaymentRequirements;
+}
+/**
+ * Pay one decoded 402 challenge from `accountId` and return the
+ * `PAYMENT-SIGNATURE` header value. Tries the challenge's exact-scheme
+ * candidates in order, skipping ones Catena reports as unpayable (wrong
+ * network/asset); everything else — policy blocks, counterparty rejections,
+ * signing failures — surfaces as `X402PaymentError` (or the underlying
+ * `ApiError` / `IntentSubmitError`).
+ */
+declare function payX402Challenge(client: CatenaClient, args: {
+  accountId: string;
+  paymentRequired: X402PaymentRequired;
+  resource?: X402Resource;
+  /**
+   * Per-call ceiling in atomic USDC units (6 decimals; "1000000" = $1).
+   * The org policy's spend limits still govern server-side; this lets the
+   * caller refuse a price it never meant to accept, before any intent.
+   */
+  maxAtomicAmount?: bigint;
+}): Promise<X402PaymentReceipt>;
+interface X402FetchOptions {
+  /**
+   * Source wallet account the payments draw from.
+   */
+  accountId: string;
+  baseFetch?: FetchLike;
+  /**
+   * Per-call price ceiling in atomic USDC units (6 decimals). Challenges
+   * asking for more are refused before any intent is created.
+   */
+  maxAtomicAmount?: bigint;
+  /**
+   * Called after each successful payment, before the retry — for receipts,
+   * logging, or spend telemetry.
+   */
+  onPayment?: (receipt: X402PaymentReceipt) => void;
+}
+/**
+ * Wrap `fetch` so a v2 x402 402 is paid via Catena and retried once with the
+ * `PAYMENT-SIGNATURE` header. Non-402 responses (and 402s without a decodable
+ * challenge) pass through untouched. Throws `X402PaymentError` before paying
+ * when the request body cannot be replayed — pass bodies via the `init`
+ * argument as a string, `URLSearchParams`, Blob, ArrayBuffer, or typed
+ * array/DataView; a `Request` input must be bodiless. Payment failures surface
+ * as `X402PaymentError` (or a subclass documenting its recovery path); an
+ * `ApiError` the loop does not absorb as a candidate skip and a "not-submitted"
+ * `IntentSubmitError` propagate unchanged.
+ */
+declare function wrapFetchWithX402Payment(client: CatenaClient, options: X402FetchOptions): FetchLike;
+//#endregion
+export { X402ApprovalPendingError, X402CounterpartyNotFoundError, X402FetchOptions, X402NetworkMismatchError, X402PaymentError, X402PaymentReceipt, X402PaymentRequired, type X402PaymentRequirements, type X402Resource, X402RetryFailedError, X402SubmitInterruptedError, decodePaymentRequired, payX402Challenge, wrapFetchWithX402Payment };

package/dist/x402.mjs

@@ -0,0 +1,225 @@
+import { a as x402PaymentRequirementsSchema, n as IntentSubmitError, o as x402ResourceSchema, t as ApiError } from "./client-G-8NfBx_.mjs";
+import * as v from "valibot";
+//#region src/lib/assert-never.ts
+function assertNever(value) {
+	throw new Error(`Unhandled case: ${String(value)}`);
+}
+//#endregion
+//#region src/x402.ts
+const PAYMENT_REQUIRED_HEADERS = ["PAYMENT-REQUIRED", "X-Payment-Required"];
+const PAYMENT_SIGNATURE_HEADER = "PAYMENT-SIGNATURE";
+const PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE";
+const EVM_TX_HASH = /^0x[0-9a-fA-F]{64}$/;
+const EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const paymentResponseSchema = v.looseObject({
+	success: v.boolean(),
+	transaction: v.string()
+});
+const paymentRequiredSchema = v.looseObject({
+	x402Version: v.literal(2),
+	accepts: v.array(x402PaymentRequirementsSchema),
+	resource: v.optional(x402ResourceSchema)
+});
+const MAX_CANDIDATE_REQUIREMENTS = 5;
+const X402_NETWORK_MISMATCH_CODE = "x402_network_mismatch";
+const X402_COUNTERPARTY_RAIL_NOT_FOUND_CODE = "x402_counterparty_rail_not_found";
+const TRY_NEXT_REQUIREMENT_CODES = new Set([
+	"x402_requirement_not_payable",
+	X402_NETWORK_MISMATCH_CODE,
+	X402_COUNTERPARTY_RAIL_NOT_FOUND_CODE
+]);
+const NETWORK_LABELS = {
+	"eip155:8453": "Base",
+	"eip155:84532": "Base Sepolia"
+};
+function networkLabel(network) {
+	const label = Object.hasOwn(NETWORK_LABELS, network) ? NETWORK_LABELS[network] : void 0;
+	return label ? `${label} (${network})` : network;
+}
+function decodeBase64Json(value) {
+	const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+	const bytes = Uint8Array.from(atob(normalized), (char) => char.charCodeAt(0));
+	return JSON.parse(new TextDecoder().decode(bytes));
+}
+function decodePaymentRequired(response) {
+	const header = PAYMENT_REQUIRED_HEADERS.map((name) => response.headers.get(name)).find((value) => value !== null);
+	if (!header) return;
+	try {
+		const parsed = v.safeParse(paymentRequiredSchema, decodeBase64Json(header));
+		return parsed.success ? parsed.output : void 0;
+	} catch {
+		return;
+	}
+}
+async function reportSettlementHint(client, intentId, retried) {
+	try {
+		const header = retried.headers.get(PAYMENT_RESPONSE_HEADER);
+		if (!header) return;
+		const parsed = v.safeParse(paymentResponseSchema, decodeBase64Json(header));
+		if (!parsed.success || !parsed.output.success || !EVM_TX_HASH.test(parsed.output.transaction)) return;
+		await client.reportSettlement({
+			intentId,
+			txHash: parsed.output.transaction
+		});
+	} catch {}
+}
+var X402PaymentError = class extends Error {
+	reasons;
+	constructor(message, reasons = []) {
+		super(reasons.length > 0 ? `${message}: ${reasons.join("; ")}` : message);
+		this.name = "X402PaymentError";
+		this.reasons = reasons;
+	}
+};
+var X402NetworkMismatchError = class extends X402PaymentError {
+	accountId;
+	requiredNetworks;
+	constructor(accountId, requiredNetworks) {
+		super(`Account ${accountId} cannot fund this 402 challenge: it must be paid from a wallet account on ${requiredNetworks.map(networkLabel).join(" or ")}`);
+		this.name = "X402NetworkMismatchError";
+		this.accountId = accountId;
+		this.requiredNetworks = requiredNetworks;
+	}
+};
+var X402CounterpartyNotFoundError = class extends X402PaymentError {
+	payTo;
+	network;
+	serviceName;
+	constructor(payTo, network, serviceName) {
+		super(`This 402 pays ${payTo} on ${networkLabel(network)}, which is not a saved counterparty wallet rail; add it as a counterparty before paying`);
+		this.name = "X402CounterpartyNotFoundError";
+		this.payTo = payTo;
+		this.network = network;
+		this.serviceName = serviceName;
+	}
+};
+var X402ApprovalPendingError = class extends X402PaymentError {
+	intentId;
+	expiresAt;
+	constructor(intentId, reasons, expiresAt) {
+		super(`The payment is awaiting a human approval (intent ${intentId}); once an operator approves it, retry the request to complete the payment`, reasons);
+		this.name = "X402ApprovalPendingError";
+		this.intentId = intentId;
+		this.expiresAt = expiresAt;
+	}
+};
+var X402RetryFailedError = class extends X402PaymentError {
+	receipt;
+	constructor(receipt, cause) {
+		super(`The payment settled (intent ${receipt.intentId}) but the paid retry failed; retry the request with the PAYMENT-SIGNATURE header from the receipt (or getIntent("${receipt.intentId}") data.x402.paymentSignature) instead of paying again`);
+		this.name = "X402RetryFailedError";
+		this.receipt = receipt;
+		this.cause = cause;
+	}
+};
+var X402SubmitInterruptedError = class extends X402PaymentError {
+	intentId;
+	requirements;
+	constructor(intentId, requirements, cause) {
+		super(`The payment could not be confirmed (intent ${intentId}); check getIntent("${intentId}") — completed: reuse its data.x402.paymentSignature as the PAYMENT-SIGNATURE header; processing: poll until terminal; pay again only after blocked or failed`);
+		this.name = "X402SubmitInterruptedError";
+		this.intentId = intentId;
+		this.requirements = requirements;
+		this.cause = cause;
+	}
+};
+async function payX402Challenge(client, args) {
+	const exactCandidates = args.paymentRequired.accepts.filter((requirement) => requirement.scheme === "exact");
+	const candidates = exactCandidates.filter((requirement) => args.maxAtomicAmount === void 0 || /^\d+$/.test(requirement.amount) && BigInt(requirement.amount) <= args.maxAtomicAmount).slice(0, MAX_CANDIDATE_REQUIREMENTS);
+	if (candidates.length === 0) throw new X402PaymentError(exactCandidates.length > 0 && args.maxAtomicAmount !== void 0 ? "Every requirement in the 402 challenge costs more than the caller's maximum amount" : "The 402 challenge offers no exact-scheme requirement Catena can pay");
+	const resource = args.resource ?? args.paymentRequired.resource;
+	const skips = [];
+	for (const requirements of candidates) {
+		const receipt = await payRequirement(client, {
+			accountId: args.accountId,
+			requirements,
+			resource
+		}).catch((err) => {
+			if (err instanceof ApiError && err.code !== void 0 && TRY_NEXT_REQUIREMENT_CODES.has(err.code)) {
+				skips.push({
+					error: err,
+					requirement: requirements
+				});
+				return;
+			}
+			throw err;
+		});
+		if (receipt) return receipt;
+	}
+	if (skips.length > 0 && skips.every((skip) => skip.error.code === X402_NETWORK_MISMATCH_CODE)) throw new X402NetworkMismatchError(args.accountId, [...new Set(skips.map((skip) => skip.requirement.network))]);
+	if (skips.length > 0 && skips.every((skip) => skip.error.code === X402_COUNTERPARTY_RAIL_NOT_FOUND_CODE && skip.error.status === 404) && EVM_ADDRESS.test(skips[0].requirement.payTo)) throw new X402CounterpartyNotFoundError(skips[0].requirement.payTo, skips[0].requirement.network, resource?.serviceName);
+	const lastSkip = skips.at(-1);
+	throw new X402PaymentError("No requirement in the 402 challenge is payable from this account", lastSkip ? [lastSkip.error.message] : []);
+}
+const x402IntentDataSchema = v.object({ x402: v.object({ paymentSignature: v.string() }) });
+async function payRequirement(client, args) {
+	const intent = await client.submitIntent({
+		action: {
+			type: "x402",
+			accountId: args.accountId,
+			paymentRequirements: args.requirements,
+			...args.resource !== void 0 && { resource: args.resource }
+		},
+		idempotencyKey: crypto.randomUUID()
+	}).catch((err) => {
+		if (err instanceof IntentSubmitError && err.outcome === "unknown") throw new X402SubmitInterruptedError(err.intentId, args.requirements, err);
+		throw err;
+	});
+	if (intent.status === "completed") {
+		const data = v.safeParse(x402IntentDataSchema, intent.data);
+		if (data.success) return {
+			intentId: intent.id,
+			paymentSignature: data.output.x402.paymentSignature,
+			requirements: args.requirements
+		};
+		throw new X402PaymentError("The completed payment did not carry an x402 payment signature");
+	}
+	switch (intent.status) {
+		case "pending": throw new X402ApprovalPendingError(intent.id, intent.reasons, intent.expiresAt);
+		case "processing": throw new X402PaymentError(`The payment is still processing (intent ${intent.id}); this client cannot resume an in-flight x402 settlement`);
+		case "blocked":
+		case "failed": throw new X402PaymentError("Catena declined the payment", intent.reasons);
+	}
+	return assertNever(intent.status);
+}
+function isReplayable(input, init) {
+	if (init?.body !== void 0 && init.body !== null) {
+		if (typeof init.body !== "string" && !(init.body instanceof URLSearchParams) && !(init.body instanceof Blob) && !(init.body instanceof ArrayBuffer) && !ArrayBuffer.isView(init.body)) return false;
+	}
+	if (typeof Request !== "undefined" && input instanceof Request) return input.body === null && !input.bodyUsed;
+	return true;
+}
+function wrapFetchWithX402Payment(client, options) {
+	const baseFetch = (options.baseFetch ?? globalThis.fetch).bind(globalThis);
+	return async (input, init) => {
+		const response = await baseFetch(input, init);
+		if (response.status !== 402) return response;
+		const paymentRequired = decodePaymentRequired(response);
+		if (!paymentRequired) return response;
+		if (!isReplayable(input, init)) throw new X402PaymentError("The request body cannot be replayed after payment; buffer the body (string, Blob, or ArrayBuffer) before using the x402 fetch wrapper");
+		const receipt = await payX402Challenge(client, {
+			accountId: options.accountId,
+			paymentRequired,
+			...options.maxAtomicAmount !== void 0 && { maxAtomicAmount: options.maxAtomicAmount }
+		});
+		options.onPayment?.(receipt);
+		const headers = new Headers(typeof Request !== "undefined" && input instanceof Request ? input.headers : void 0);
+		new Headers(init?.headers).forEach((value, key) => {
+			headers.set(key, value);
+		});
+		headers.set(PAYMENT_SIGNATURE_HEADER, receipt.paymentSignature);
+		let retried;
+		try {
+			retried = await baseFetch(input, {
+				...init,
+				headers
+			});
+		} catch (err) {
+			throw new X402RetryFailedError(receipt, err);
+		}
+		reportSettlementHint(client, receipt.intentId, retried);
+		return retried;
+	};
+}
+//#endregion
+export { X402ApprovalPendingError, X402CounterpartyNotFoundError, X402NetworkMismatchError, X402PaymentError, X402RetryFailedError, X402SubmitInterruptedError, decodePaymentRequired, payX402Challenge, wrapFetchWithX402Payment };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@catena/sdk",
+  "version": "0.0.0-alpha-20260724191736",
+  "description": "Typed client SDK for the Catena agent API",
+  "homepage": "https://catena.com/",
+  "license": "Apache-2.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.mts",
+      "default": "./dist/client.mjs"
+    },
+    "./keypair": {
+      "types": "./dist/keypair.d.mts",
+      "default": "./dist/keypair.mjs"
+    },
+    "./x402": {
+      "types": "./dist/x402.d.mts",
+      "default": "./dist/x402.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "dependencies": {
+    "@turnkey/api-key-stamper": "0.6.7",
+    "valibot": "1.4.1"
+  },
+  "devDependencies": {
+    "publint": "0.3.21",
+    "tsdown": "0.22.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "gitHead": "1e4e40d0767efc5d927803fec08eaea24035017d",
+  "scripts": {
+    "build": "tsdown",
+    "clean": "git clean -xdf dist node_modules/.cache",
+    "publint": "pnpm run build && publint --pack pnpm --strict"
+  }
+}