@catena/sdk 0.0.0-bootstrap.0 → 0.1.0

package/dist/x402.mjs

@@ -0,0 +1,221 @@
+import { C as extractRelayableOffer, S as x402ResourceSchema, b as x402CredentialFromIntentData, n as IntentSubmitError, t as ApiError, w as extractRelayableReceipt, x as x402PaymentRequirementsSchema } from "./client-CHZMO00P.mjs";
+import { a as assertNever, i as isReplayableFetchRequest, n as reportSettlementHint$1, r as fetchRetryHeaders, t as EVM_TRANSACTION_HASH_PATTERN } from "./settlement-report-CT3EbtLL.mjs";
+import * as v from "valibot";
+//#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_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const paymentResponseSchema = v.looseObject({
+	success: v.boolean(),
+	transaction: v.string(),
+	extensions: v.optional(v.unknown())
+});
+const paymentRequiredSchema = v.looseObject({
+	x402Version: v.literal(2),
+	accepts: v.array(x402PaymentRequirementsSchema),
+	resource: v.optional(x402ResourceSchema),
+	extensions: v.optional(v.unknown())
+});
+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_TRANSACTION_HASH_PATTERN.test(parsed.output.transaction)) return;
+		const receipt = extractRelayableReceipt(parsed.output.extensions);
+		await reportSettlementHint$1(client, intentId, parsed.output.transaction, receipt);
+	} catch {}
+}
+var X402PaymentError = class extends Error {
+	reasons;
+	constructor(message, reasons = [], options = {}) {
+		super(reasons.length > 0 && (options.appendReasonsToMessage ?? true) ? `${message}: ${reasons.join("; ")}` : message);
+		this.name = "X402PaymentError";
+		this.reasons = reasons;
+	}
+};
+var X402NetworkMismatchError = class extends X402PaymentError {
+	accountId;
+	requiredNetworks;
+	constructor(accountId, requiredNetworks, reasons = []) {
+		super(`Account ${accountId} cannot fund this 402 challenge: it must be paid from a wallet account on ${requiredNetworks.map(networkLabel).join(" or ")}`, reasons, { appendReasonsToMessage: false });
+		this.name = "X402NetworkMismatchError";
+		this.accountId = accountId;
+		this.requiredNetworks = requiredNetworks;
+	}
+};
+var X402CounterpartyNotFoundError = class extends X402PaymentError {
+	payTo;
+	network;
+	serviceName;
+	constructor(payTo, network, serviceName, reasons = []) {
+		super(`This 402 pays ${payTo} on ${networkLabel(network)}, which is not a saved counterparty wallet rail; add it as a counterparty before paying`, reasons, { appendReasonsToMessage: false });
+		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 post-payment continuation failed; retry the request with the PAYMENT-SIGNATURE header from the receipt (or getIntent("${receipt.intentId}") data.paymentCredential.value) instead of paying again`);
+		this.name = "X402RetryFailedError";
+		this.receipt = receipt;
+		this.cause = cause;
+	}
+};
+async function preservePaymentReceipt(receipt, operation) {
+	try {
+		return await operation();
+	} catch (err) {
+		throw new X402RetryFailedError(receipt, err);
+	}
+}
+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.paymentCredential.value 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,
+			signedOffer: extractRelayableOffer(args.paymentRequired.extensions, requirements)
+		}).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;
+	}
+	const counterpartySkips = skips.filter((skip) => skip.error.code === X402_COUNTERPARTY_RAIL_NOT_FOUND_CODE);
+	const mismatchSkips = skips.filter((skip) => skip.error.code === X402_NETWORK_MISMATCH_CODE);
+	const otherSkips = skips.filter((skip) => skip.error.code !== X402_COUNTERPARTY_RAIL_NOT_FOUND_CODE && skip.error.code !== X402_NETWORK_MISMATCH_CODE);
+	const reasons = [...new Set([
+		...counterpartySkips,
+		...mismatchSkips,
+		...otherSkips
+	].map((skip) => skip.error.message))];
+	const unsaved = counterpartySkips.find((skip) => skip.error.status === 404 && EVM_ADDRESS.test(skip.requirement.payTo));
+	if (unsaved) throw new X402CounterpartyNotFoundError(unsaved.requirement.payTo, unsaved.requirement.network, resource?.serviceName, reasons);
+	if (mismatchSkips.length > 0 && counterpartySkips.length === 0) throw new X402NetworkMismatchError(args.accountId, [...new Set(mismatchSkips.map((skip) => skip.requirement.network))], reasons);
+	throw new X402PaymentError("No requirement in the 402 challenge is payable from this account", reasons);
+}
+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 },
+			...args.signedOffer !== void 0 && { signedOffer: args.signedOffer }
+		},
+		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 paymentSignature = x402CredentialFromIntentData(intent.data);
+		if (paymentSignature !== void 0) return {
+			intentId: intent.id,
+			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 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 (!isReplayableFetchRequest(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 }
+		});
+		await preservePaymentReceipt(receipt, () => options.onPayment?.(receipt));
+		const headers = fetchRetryHeaders(input, init);
+		headers.set(PAYMENT_SIGNATURE_HEADER, receipt.paymentSignature);
+		const retried = await preservePaymentReceipt(receipt, () => baseFetch(input, {
+			...init,
+			headers
+		}));
+		reportSettlementHint(client, receipt.intentId, retried);
+		return retried;
+	};
+}
+//#endregion
+export { X402ApprovalPendingError, X402CounterpartyNotFoundError, X402NetworkMismatchError, X402PaymentError, X402RetryFailedError, X402SubmitInterruptedError, decodePaymentRequired, payX402Challenge, wrapFetchWithX402Payment };

package/package.json

@@ -1,9 +1,68 @@
 {
   "name": "@catena/sdk",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Bootstrap placeholder for Catena SDK trusted publishing setup.",
+  "version": "0.1.0",
+  "description": "Typed client SDK for the Catena agent API",
+  "homepage": "https://catena.com/",
   "license": "Apache-2.0",
   "files": [
-    "README.md"
-  ]
-}
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.mts",
+      "default": "./dist/client.mjs"
+    },
+    "./keypair": {
+      "types": "./dist/keypair.d.mts",
+      "default": "./dist/keypair.mjs"
+    },
+    "./mpp": {
+      "types": "./dist/mpp.d.mts",
+      "default": "./dist/mpp.mjs"
+    },
+    "./x402": {
+      "types": "./dist/x402.d.mts",
+      "default": "./dist/x402.mjs"
+    },
+    "./viem": {
+      "types": "./dist/viem.d.mts",
+      "default": "./dist/viem.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@turnkey/api-key-stamper": "0.6.12",
+    "valibot": "1.4.2"
+  },
+  "devDependencies": {
+    "mppx": "0.9.0",
+    "publint": "0.3.23",
+    "tsdown": "0.22.14",
+    "viem": "2.55.17"
+  },
+  "peerDependencies": {
+    "mppx": "0.9.0",
+    "viem": "^2.21.0"
+  },
+  "peerDependenciesMeta": {
+    "mppx": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "gitHead": "1399d4f6d848c75a28aa8819cf05e47c36ee31b6",
+  "scripts": {
+    "build": "tsdown",
+    "clean": "git clean -xdf dist node_modules/.cache",
+    "publint": "pnpm run build && publint --pack pnpm --strict",
+    "verify:pack": "pnpm run publint && tsx bin/verify-pack.ts"
+  }
+}