@primitivedotdev/sdk 1.7.0 → 1.9.0

package/dist/x402/index.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { concat, getAddress, hexToBytes, keccak256, stringToBytes } from "viem";
 //#region src/x402/sign.ts
 /**
@@ -97,6 +98,44 @@ function buildPayoutRegistrationMessage(input) {
 		`issued: ${input.issuedAt}`
 	].join("\n");
 }
+/**
+* The protocol the email-native payment interaction runs (`x402.payment/1`).
+* The payer's reply carries the `payment` step of this protocol.
+*/
+const X402_INTERACTION_PROTOCOL = "x402.payment";
+const X402_INTERACTION_PROTOCOL_VERSION = 1;
+/** A UUID (used for `interaction_id`'s local part and the step ids). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** An interaction id is `uuid@domain`. */
+const WIRE_ID_RE = new RegExp(`^${UUID_RE.source.slice(1, -1)}@[^\\s@]+$`, "i");
+/**
+* Build the section-2.3 interaction.json envelope for a `payment` step. Pure: no
+* I/O. `payment` is the signed exact-EVM payload (from
+* `buildExactEvmPaymentPayload`); `prevStepId` is the challenge step id this
+* payment answers, and `stepId` is a fresh UUID for the payment step. Returns
+* the envelope and its canonical JSON, so the bytes the platform reads back are
+* exactly the ones produced here.
+*/
+function buildPaymentStepEnvelope(params) {
+	if (!WIRE_ID_RE.test(params.interactionId)) throw new Error("buildPaymentStepEnvelope: interactionId must be uuid@domain");
+	if (!UUID_RE.test(params.stepId)) throw new Error("buildPaymentStepEnvelope: stepId must be a uuid");
+	if (!UUID_RE.test(params.prevStepId)) throw new Error("buildPaymentStepEnvelope: prevStepId must be a uuid");
+	const envelope = {
+		interaction_version: 1,
+		interaction_id: params.interactionId,
+		protocol: X402_INTERACTION_PROTOCOL,
+		protocol_version: 1,
+		step: "payment",
+		step_id: params.stepId,
+		prev_step_id: params.prevStepId,
+		expires_at: params.expiresAt ?? null,
+		payload: { payment: params.payment }
+	};
+	return {
+		envelope,
+		json: JSON.stringify(envelope)
+	};
+}
 /** Assemble the wire payload from a signed authorization. */
 function toPaymentPayload(network, auth, signature) {
 	return {
@@ -184,6 +223,15 @@ function buildExactEvmPaymentPayload(params) {
 }
 //#endregion
 //#region src/x402/client.ts
+/**
+* x402 agent-to-agent payments.
+*
+* `charge()` (payee) asks for a payment; `pay()` (payer) signs and settles it
+* with the customer's own key. The signing is local and non-custodial; the key
+* never leaves the caller. The server resolves the real payee address, verifies
+* every signed field against its own records, and enforces the spend policy, so
+* the SDK's job is just: derive the bound authorization, sign, and submit.
+*/
 const CHAIN_IDS = {
 	"base-sepolia": 84532,
 	base: 8453
@@ -199,6 +247,17 @@ const CHARGE_INPUT_KEYS = {
 	expiresIn: true,
 	idempotencyKey: true
 };
+const EMAIL_CHARGE_INPUT_KEYS = {
+	from: true,
+	to: true,
+	amount: true,
+	amountUsdc: true,
+	network: true,
+	description: true,
+	resource: true,
+	expiresIn: true,
+	idempotencyKey: true
+};
 function usdcToBaseUnits(human) {
 	const trimmed = human.trim();
 	if (!/^\d+(\.\d+)?$/.test(trimmed)) return null;
@@ -235,13 +294,37 @@ function validateChallenge(c) {
 	if (!c.expires_at) bad("expires_at");
 	const nb = c.nonce_binding;
 	if (!nb?.interaction_id || !nb.challenge_step_id || !nb.challenge_nonce) bad("nonce_binding");
-	const pr = c.payment_requirements;
+	validatePaymentRequirements(c.payment_requirements, bad);
+}
+/** Validate the x402 PaymentRequirements shared by both challenge shapes. */
+function validatePaymentRequirements(pr, bad) {
 	if (!pr) bad("payment_requirements");
 	if (!/^[1-9][0-9]{0,38}$/.test(pr.maxAmountRequired ?? "")) bad("payment_requirements.maxAmountRequired (expected a positive integer string in token base units)");
 	if (!/^0x[0-9a-fA-F]{40}$/.test(pr.payTo ?? "")) bad("payment_requirements.payTo (expected a 0x address)");
 	if (!/^0x[0-9a-fA-F]{40}$/.test(pr.asset ?? "")) bad("payment_requirements.asset (expected a 0x address)");
 	if (!pr.extra?.name || !pr.extra.version) bad("payment_requirements.extra (name/version)");
 }
+/**
+* Assert an email-native challenge is fully hydrated before signing, so a
+* missing field fails with a named X402Error instead of an opaque error
+* mid-sign. The interaction_id and the challenge step id (the nonce binding's
+* fields) drive both the bound nonce and the payment-step envelope, so they are
+* checked here.
+*/
+function validateEmailChallenge(c) {
+	const bad = (field) => {
+		throw new X402Error(`email challenge is missing or malformed: ${field}`, 0);
+	};
+	if (!c || typeof c !== "object") bad("email challenge");
+	if (!c.interaction_id) bad("interaction_id");
+	const ch = c.challenge;
+	if (!ch || typeof ch !== "object") bad("challenge");
+	if (!ch.expires_at) bad("challenge.expires_at");
+	const nb = ch.nonce_binding;
+	if (!nb?.interaction_id || !nb.challenge_step_id || !nb.challenge_nonce) bad("challenge.nonce_binding");
+	if (nb.interaction_id !== c.interaction_id) bad("interaction_id (mismatch with challenge.nonce_binding.interaction_id)");
+	validatePaymentRequirements(ch.payment_requirements, bad);
+}
 var X402Client = class {
 	#apiKey;
 	#baseUrl;
@@ -301,6 +384,99 @@ var X402Client = class {
 		return this.#request("POST", "/v1/x402/challenges", body, { headers: input.idempotencyKey ? { "idempotency-key": input.idempotencyKey } : void 0 });
 	}
 	/**
+	* Issue a payment challenge over an email thread (payee side). Sends the
+	* challenge as an email from `from` to `to` and binds the payment to that
+	* thread. Returns the challenge (including the real `interaction_id`); deliver
+	* it to the payer, who calls `payEmailChallenge` to build the signed payment.
+	*
+	* Provide exactly one of `amount` (base units) or `amountUsdc` (human USDC).
+	*/
+	async createEmailChallenge(input) {
+		for (const key of Object.keys(input)) if (!(key in EMAIL_CHARGE_INPUT_KEYS)) throw new X402Error(`unknown createEmailChallenge() option "${key}"; expected one of: ${Object.keys(EMAIL_CHARGE_INPUT_KEYS).join(", ")}`, 0);
+		if (!input.from) throw new X402Error("createEmailChallenge() requires `from`", 0);
+		if (!input.to) throw new X402Error("createEmailChallenge() requires `to`", 0);
+		if (input.amount !== void 0 && input.amountUsdc !== void 0) throw new X402Error("createEmailChallenge() takes exactly one of `amount` (base units) or `amountUsdc` (human USDC), not both", 0);
+		const amount = input.amountUsdc !== void 0 ? usdcToBaseUnits(input.amountUsdc) : input.amount ?? null;
+		if (!amount || !/^[1-9][0-9]{0,38}$/.test(amount)) throw new X402Error("createEmailChallenge() requires `amount` as a positive integer string in token base units (e.g. \"10000\"), or `amountUsdc` as a positive USDC amount with at most 6 decimals (e.g. \"0.01\")", 0);
+		const body = {
+			from: input.from,
+			to: input.to,
+			amount,
+			network: input.network ?? "base-sepolia"
+		};
+		if (input.description) body.description = input.description;
+		if (input.resource) body.resource = input.resource;
+		if (input.expiresIn !== void 0) body.expires_in = input.expiresIn;
+		return this.#request("POST", "/v1/x402/email-challenges", body, { headers: input.idempotencyKey ? { "idempotency-key": input.idempotencyKey } : void 0 });
+	}
+	/**
+	* Build the signed payment step for an email-native challenge (payer side).
+	* Given a received `X402EmailChallenge` and the caller's signer, this derives
+	* the interaction-bound authorization, signs it locally, and returns the
+	* signed `interaction.json` payment-step envelope plus its canonical JSON
+	* bytes. It does NOT send anything.
+	*
+	* The caller sends `result.json` back as an `interaction.json` attachment on a
+	* reply to the challenge email (e.g. via the SDK's `send` / `reply`); the
+	* platform reads the envelope from those exact bytes, re-derives the bound
+	* nonce, and settles.
+	*/
+	async payEmailChallenge(challenge, options) {
+		if (!options?.signer?.address || typeof options.signer.signTypedData !== "function") throw new X402Error("payEmailChallenge() requires options.signer with { address, signTypedData } (e.g. a viem LocalAccount)", 0);
+		validateEmailChallenge(challenge);
+		const details = challenge.challenge;
+		const pr = details.payment_requirements;
+		const network = pr.network;
+		const chainId = CHAIN_IDS[network];
+		if (chainId === void 0) throw new X402Error(`unsupported network: ${network}`, 0);
+		if (pr.scheme !== "exact") throw new X402Error(`unsupported payment scheme: ${pr.scheme}`, 0);
+		const nowSec = Math.floor(Date.now() / 1e3);
+		const expiresAtMs = Date.parse(details.expires_at);
+		if (Number.isNaN(expiresAtMs)) throw new X402Error(`challenge has an invalid expires_at: ${details.expires_at}`, 0);
+		const expiresAtSec = Math.floor(expiresAtMs / 1e3);
+		if (expiresAtSec <= nowSec) throw new X402Error(`challenge has already expired (expires_at ${details.expires_at}); not signing`, 0);
+		let validAfter;
+		let validBefore;
+		try {
+			({validAfter, validBefore} = computePaymentValidityWindow({
+				challengeExpiresAtSec: expiresAtSec,
+				nowSec
+			}));
+		} catch (cause) {
+			throw new X402Error(cause instanceof Error ? cause.message : String(cause), 0, void 0, { cause });
+		}
+		const { authorization, signature } = await signInteractionPayment({
+			sign: (typedData) => options.signer.signTypedData(typedData),
+			payer: options.signer.address,
+			domain: {
+				name: pr.extra.name,
+				version: pr.extra.version,
+				chainId,
+				verifyingContract: pr.asset
+			},
+			payTo: pr.payTo,
+			amount: BigInt(pr.maxAmountRequired),
+			nonceBinding: {
+				interactionId: details.nonce_binding.interaction_id,
+				challengeStepId: details.nonce_binding.challenge_step_id,
+				challengeNonce: details.nonce_binding.challenge_nonce
+			},
+			validAfter,
+			validBefore
+		});
+		const payment = buildExactEvmPaymentPayload({
+			network,
+			authorization,
+			signature
+		});
+		return buildPaymentStepEnvelope({
+			interactionId: challenge.interaction_id,
+			stepId: randomUUID(),
+			prevStepId: details.nonce_binding.challenge_step_id,
+			payment
+		});
+	}
+	/**
 	* Pay a challenge (payer side). Derives the interaction-bound authorization,
 	* signs it locally with the caller's key, and submits it for settlement.
 	*/
@@ -423,4 +599,4 @@ function createX402Client(options = {}) {
 	return new X402Client(options);
 }
 //#endregion
-export { DEFAULT_MAX_WINDOW_SEC, TRANSFER_WITH_AUTHORIZATION_TYPES, X402Client, X402Error, buildExactEvmPaymentPayload, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };
+export { DEFAULT_MAX_WINDOW_SEC, TRANSFER_WITH_AUTHORIZATION_TYPES, X402Client, X402Error, X402_INTERACTION_PROTOCOL, X402_INTERACTION_PROTOCOL_VERSION, buildExactEvmPaymentPayload, buildPaymentStepEnvelope, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser runtime modules.",
   "type": "module",
   "module": "./dist/index.js",
@@ -93,7 +93,7 @@
   "dependencies": {
     "ajv": "^8.17.1",
     "mailparser": "^3.9.0",
-    "nodemailer": "^8.0.7",
+    "nodemailer": "^9.0.1",
     "sanitize-html": "^2.14.0",
     "tar-stream": "^3.1.8",
     "validator": "^13.15.35",