primcli 1.13.3 → 1.14.1

package/dist/oclif/index.js

@@ -7,6 +7,7 @@ import process$1 from "node:process";
 import { createInterface } from "node:readline/promises";
 import { hostname } from "node:os";
 import { spawn } from "node:child_process";
+import { gunzipSync } from "node:zlib";
 import { concat, getAddress, hexToBytes, keccak256, stringToBytes } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 //#region \0rolldown/runtime.js
@@ -8974,56 +8975,25 @@ const openapiDocument = {
 					"consecutive_fails"
 				]
 			},
-			"CreateHttpEndpointInput": {
+			"CreateEndpointInput": {
 				"type": "object",
 				"additionalProperties": false,
 				"properties": {
 					"kind": {
 						"type": "string",
-						"enum": ["http"],
+						"enum": ["http", "function"],
 						"default": "http",
-						"description": "Deliver to a webhook URL."
+						"description": "http: deliver to a webhook URL (provide url). function: invoke a Primitive Function (provide function_id, omit url)."
 					},
 					"url": {
 						"type": "string",
 						"minLength": 1,
-						"description": "The webhook URL to deliver events to."
-					},
-					"enabled": {
-						"type": "boolean",
-						"default": true,
-						"description": "Whether the endpoint is active"
-					},
-					"domain_id": {
-						"type": ["string", "null"],
-						"format": "uuid",
-						"description": "Restrict to emails from a specific domain"
-					},
-					"rules": {
-						"type": "object",
-						"description": "Endpoint-specific filtering rules"
-					},
-					"is_route_target": {
-						"type": "boolean",
-						"default": false,
-						"description": "Create this endpoint as a route-target: reachable only via an\nexplicit recipient route, never a domain's default destination, and\nexempt from the one-endpoint-per-domain rule.\n"
-					}
-				},
-				"required": ["url"]
-			},
-			"CreateFunctionEndpointInput": {
-				"type": "object",
-				"additionalProperties": false,
-				"properties": {
-					"kind": {
-						"type": "string",
-						"enum": ["function"],
-						"description": "Invoke a Primitive Function."
+						"description": "The webhook URL to deliver events to. Required when kind is http; omit for function endpoints."
 					},
 					"function_id": {
 						"type": "string",
 						"format": "uuid",
-						"description": "The Function to invoke."
+						"description": "The Function to invoke. Required when kind is function."
 					},
 					"enabled": {
 						"type": "boolean",
@@ -9044,17 +9014,6 @@ const openapiDocument = {
 						"default": false,
 						"description": "Create this endpoint as a route-target: reachable only via an\nexplicit recipient route, never a domain's default destination, and\nexempt from the one-endpoint-per-domain rule.\n"
 					}
-				},
-				"required": ["kind", "function_id"]
-			},
-			"CreateEndpointInput": {
-				"oneOf": [{ "$ref": "#/components/schemas/CreateHttpEndpointInput" }, { "$ref": "#/components/schemas/CreateFunctionEndpointInput" }],
-				"discriminator": {
-					"propertyName": "kind",
-					"mapping": {
-						"http": "#/components/schemas/CreateHttpEndpointInput",
-						"function": "#/components/schemas/CreateFunctionEndpointInput"
-					}
 				}
 			},
 			"UpdateEndpointInput": {
@@ -13369,83 +13328,43 @@ const operationManifest = [
 		"pathParams": [],
 		"queryParams": [],
 		"requestSchema": {
-			"oneOf": [{
-				"type": "object",
-				"additionalProperties": false,
-				"properties": {
-					"kind": {
-						"type": "string",
-						"enum": ["http"],
-						"default": "http",
-						"description": "Deliver to a webhook URL."
-					},
-					"url": {
-						"type": "string",
-						"minLength": 1,
-						"description": "The webhook URL to deliver events to."
-					},
-					"enabled": {
-						"type": "boolean",
-						"default": true,
-						"description": "Whether the endpoint is active"
-					},
-					"domain_id": {
-						"type": ["string", "null"],
-						"format": "uuid",
-						"description": "Restrict to emails from a specific domain"
-					},
-					"rules": {
-						"type": "object",
-						"description": "Endpoint-specific filtering rules"
-					},
-					"is_route_target": {
-						"type": "boolean",
-						"default": false,
-						"description": "Create this endpoint as a route-target: reachable only via an\nexplicit recipient route, never a domain's default destination, and\nexempt from the one-endpoint-per-domain rule.\n"
-					}
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"kind": {
+					"type": "string",
+					"enum": ["http", "function"],
+					"default": "http",
+					"description": "http: deliver to a webhook URL (provide url). function: invoke a Primitive Function (provide function_id, omit url)."
 				},
-				"required": ["url"]
-			}, {
-				"type": "object",
-				"additionalProperties": false,
-				"properties": {
-					"kind": {
-						"type": "string",
-						"enum": ["function"],
-						"description": "Invoke a Primitive Function."
-					},
-					"function_id": {
-						"type": "string",
-						"format": "uuid",
-						"description": "The Function to invoke."
-					},
-					"enabled": {
-						"type": "boolean",
-						"default": true,
-						"description": "Whether the endpoint is active"
-					},
-					"domain_id": {
-						"type": ["string", "null"],
-						"format": "uuid",
-						"description": "Restrict to emails from a specific domain"
-					},
-					"rules": {
-						"type": "object",
-						"description": "Endpoint-specific filtering rules"
-					},
-					"is_route_target": {
-						"type": "boolean",
-						"default": false,
-						"description": "Create this endpoint as a route-target: reachable only via an\nexplicit recipient route, never a domain's default destination, and\nexempt from the one-endpoint-per-domain rule.\n"
-					}
+				"url": {
+					"type": "string",
+					"minLength": 1,
+					"description": "The webhook URL to deliver events to. Required when kind is http; omit for function endpoints."
 				},
-				"required": ["kind", "function_id"]
-			}],
-			"discriminator": {
-				"propertyName": "kind",
-				"mapping": {
-					"http": "#/components/schemas/CreateHttpEndpointInput",
-					"function": "#/components/schemas/CreateFunctionEndpointInput"
+				"function_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "The Function to invoke. Required when kind is function."
+				},
+				"enabled": {
+					"type": "boolean",
+					"default": true,
+					"description": "Whether the endpoint is active"
+				},
+				"domain_id": {
+					"type": ["string", "null"],
+					"format": "uuid",
+					"description": "Restrict to emails from a specific domain"
+				},
+				"rules": {
+					"type": "object",
+					"description": "Endpoint-specific filtering rules"
+				},
+				"is_route_target": {
+					"type": "boolean",
+					"default": false,
+					"description": "Create this endpoint as a route-target: reachable only via an\nexplicit recipient route, never a domain's default destination, and\nexempt from the one-endpoint-per-domain rule.\n"
 				}
 			}
 		},
@@ -23864,8 +23783,8 @@ const PRIMITIVE_TEAM_AUTHOR = {
 	name: "Primitive Team",
 	url: "https://primitive.dev"
 };
-const SDK_VERSION_RANGE = "^1.13.3";
-const CLI_VERSION_RANGE = "^1.13.3";
+const SDK_VERSION_RANGE = "^1.14.0";
+const CLI_VERSION_RANGE = "^1.14.0";
 const ESBUILD_VERSION_RANGE = "^0.27.0";
 function renderHandler() {
 	return `// env.PRIMITIVE_API_KEY, env.PRIMITIVE_WEBHOOK_SECRET, and
@@ -27547,7 +27466,80 @@ var X402Error = class extends Error {
 		this.retryAfter = options?.retryAfter ?? null;
 	}
 };
-new RegExp(`^${/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.source.slice(1, -1)}@[^\\s@]+$`, "i");
+/** A UUID, as carried by `interaction_id`'s local part and the step ids. */
+const EXTRACT_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 EXTRACT_WIRE_ID_RE = new RegExp(`^${EXTRACT_UUID_RE.source.slice(1, -1)}@[^\\s@]+$`, "i");
+/**
+* Parse the bytes of an inbound `interaction.json` MIME part into a typed
+* {@link X402EmailChallenge} ready for {@link X402Client.payEmailChallenge}.
+*
+* A payer receives the x402 challenge as an `interaction.json` attachment on an
+* inbound email (filename `interaction.json`, content type `application/json`).
+* This validates the envelope (the strict snake_case wire shape, that it is the
+* `x402.payment` `challenge` step, and that the embedded payload carries the
+* fields a payer signs over) and re-assembles the nonce binding from the
+* envelope's `interaction_id` + `step_id` + the payload's `challenge_nonce`, so
+* the caller never has to hand-parse the part.
+*
+* Accepts the part body as a UTF-8 string, a `Uint8Array`/`Buffer`, or an
+* already-parsed envelope object. Throws {@link X402Error} (status 0) on any
+* malformed or non-challenge part.
+*
+* The resulting `challenge_id` is empty: the platform's private challenge id is
+* not carried on the wire, and `payEmailChallenge` does not need it (it binds to
+* the `interaction_id` and the challenge step id).
+*/
+function parseEmailChallengeFromPart(part) {
+	const bad = (field) => {
+		throw new X402Error(`interaction.json part is not a valid x402 challenge: ${field}`, 0);
+	};
+	let envelope;
+	if (typeof part === "string" || part instanceof Uint8Array) {
+		const text = typeof part === "string" ? part : new TextDecoder().decode(part);
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch (cause) {
+			throw new X402Error(`interaction.json part is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`, 0, void 0, { cause });
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) bad("envelope (expected a JSON object)");
+		envelope = parsed;
+	} else if (part && typeof part === "object" && !Array.isArray(part) && !(part instanceof Uint8Array)) envelope = part;
+	else return bad("envelope (expected JSON bytes, a string, or an object)");
+	if (envelope.interaction_version !== 1) bad("interaction_version (expected 1)");
+	const interactionId = envelope.interaction_id;
+	if (typeof interactionId !== "string" || !EXTRACT_WIRE_ID_RE.test(interactionId)) bad("interaction_id (expected uuid@domain)");
+	if (envelope.protocol !== "x402.payment") bad(`protocol (expected "${X402_INTERACTION_PROTOCOL}")`);
+	if (envelope.protocol_version !== 1) bad(`protocol_version (expected 1)`);
+	if (envelope.step !== "challenge") bad(`step (expected "challenge", got "${String(envelope.step)}")`);
+	const stepId = envelope.step_id;
+	if (typeof stepId !== "string" || !EXTRACT_UUID_RE.test(stepId)) bad("step_id (expected a uuid)");
+	const expiresAt = envelope.expires_at;
+	if (typeof expiresAt !== "string" || !expiresAt) bad("expires_at (expected an ISO-8601 timestamp on the challenge step)");
+	const payload = envelope.payload;
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) bad("payload (expected an object)");
+	const p = payload;
+	const challengeNonce = p.challenge_nonce;
+	if (typeof challengeNonce !== "string" || !/^[0-9a-f]{64}$/.test(challengeNonce)) bad("payload.challenge_nonce (expected 64 lowercase hex chars)");
+	const paymentRequirements = p.payment_requirements;
+	if (!paymentRequirements || typeof paymentRequirements !== "object" || Array.isArray(paymentRequirements)) bad("payload.payment_requirements (expected an object)");
+	const challenge = {
+		interaction_id: interactionId,
+		challenge_id: "",
+		challenge: {
+			payment_requirements: paymentRequirements,
+			nonce_binding: {
+				interaction_id: interactionId,
+				challenge_step_id: stepId,
+				challenge_nonce: challengeNonce
+			},
+			expires_at: expiresAt
+		}
+	};
+	validateEmailChallenge(challenge);
+	return challenge;
+}
 /**
 * Assert a challenge is fully hydrated before signing, so a missing field fails
 * with a named X402Error instead of an opaque viem/BigInt error mid-sign.
@@ -27867,6 +27859,149 @@ function createX402Client(options = {}) {
 	return new X402Client(options);
 }
 //#endregion
+//#region src/oclif/commands/payments-email-challenge.ts
+/** The exact attachment part name the x402 challenge travels in. */
+const INTERACTION_PART_FILENAME$1 = "interaction.json";
+/** Content type the challenge attachment is sent with. */
+const INTERACTION_PART_CONTENT_TYPE$1 = "application/json";
+/**
+* Strip a leading `<digits>_` part-index prefix from an archive entry's
+* basename. The attachments archive names each member `<part_index>_<filename>`,
+* so `0_interaction.json` -> `interaction.json`.
+*/
+function stripPartIndexPrefix(basename) {
+	return basename.replace(/^\d+_/, "");
+}
+/**
+* Resolve the exact archive entry name for the challenge attachment from email
+* attachment metadata. Returns the matching entry's `tar_path` (e.g.
+* `0_interaction.json`), or null when no `interaction.json` attachment is
+* described. Prefers an exact `filename === "interaction.json"` match; falls back
+* to a single `application/json` part when the filename is absent.
+*/
+function interactionTarPathFromMeta(attachments) {
+	if (!attachments || attachments.length === 0) return null;
+	const chosen = attachments.find((a) => a.filename === "interaction.json") ?? attachments.find((a) => a.content_type === INTERACTION_PART_CONTENT_TYPE$1);
+	if (!chosen) return null;
+	if (chosen.tar_path) return chosen.tar_path;
+	if (typeof chosen.part_index === "number" && chosen.filename) return `${chosen.part_index}_${chosen.filename}`;
+	return chosen.filename ?? null;
+}
+/** Build the attachments-archive URL for an inbound email id. */
+function attachmentsArchiveUrl(baseUrl, emailId) {
+	return `${baseUrl.replace(/\/$/, "")}/emails/${encodeURIComponent(emailId)}/attachments.tar.gz`;
+}
+/**
+* Minimal POSIX (ustar) tar reader: yield each regular-file entry's name and
+* bytes. We avoid a third-party tar dependency because the published CLI bundles
+* everything (the tarball-isolation check forbids unexpected runtime deps) and a
+* tar archive of email attachments is a flat list of small regular files, which
+* the base format already covers.
+*
+* Tar layout: a sequence of 512-byte records. Each file is one 512-byte header
+* followed by ceil(size/512) data records. Two consecutive all-zero headers mark
+* the end. The header's name is at offset 0 (100 bytes), size at offset 124 (12
+* bytes, octal), and the type flag at offset 156 ('0' or '\0' = regular file).
+* GNU long names (type 'L') and the ustar `prefix` field are handled so a longer
+* path still resolves; other special types are skipped.
+*/
+function* readTarEntries(buffer) {
+	const BLOCK = 512;
+	let offset = 0;
+	let longName = null;
+	const readString = (start, length) => {
+		const slice = buffer.subarray(start, start + length);
+		let end = slice.indexOf(0);
+		if (end === -1) end = slice.length;
+		return new TextDecoder().decode(slice.subarray(0, end));
+	};
+	while (offset + BLOCK <= buffer.length) {
+		const header = buffer.subarray(offset, offset + BLOCK);
+		if (header.every((byte) => byte === 0)) break;
+		const sizeField = readString(offset + 124, 12).trim();
+		const size = sizeField ? Number.parseInt(sizeField, 8) : 0;
+		const safeSize = Number.isFinite(size) && size >= 0 ? size : 0;
+		const typeFlag = String.fromCharCode(header[156] ?? 0);
+		const dataStart = offset + BLOCK;
+		const dataEnd = dataStart + safeSize;
+		if (typeFlag === "L") longName = readString(dataStart, safeSize).replace(/\0+$/, "");
+		else if (typeFlag === "0" || typeFlag === "\0") {
+			const name = longName ?? (() => {
+				const prefix = readString(offset + 345, 155);
+				const base = readString(offset, 100);
+				return prefix ? `${prefix}/${base}` : base;
+			})();
+			longName = null;
+			yield {
+				name,
+				bytes: buffer.subarray(dataStart, dataEnd)
+			};
+		} else longName = null;
+		offset = dataStart + Math.ceil(safeSize / BLOCK) * BLOCK;
+	}
+}
+/**
+* Pull the `interaction.json` bytes out of a gzipped tar attachments archive.
+* Returns null when the archive has no such member (e.g. the inbound email is
+* not an x402 challenge).
+*
+* When `tarPath` is given (the exact entry name from the email's attachment
+* metadata, e.g. `0_interaction.json`), the member is matched by that exact name
+* first. As a fallback (and when no `tarPath` is supplied), the member is matched
+* by basename after stripping any leading `<digits>_` part-index prefix, so both
+* `0_interaction.json` and a bare `interaction.json` resolve, and a leading
+* directory in the archive path does not hide it.
+*/
+function interactionJsonFromArchive(gzipped, tarPath) {
+	const tar = gunzipSync(gzipped);
+	const wantedBase = tarPath ? tarPath.split("/").pop() ?? tarPath : null;
+	for (const entry of readTarEntries(tar)) {
+		const base = entry.name.split("/").pop() ?? entry.name;
+		if (wantedBase && base === wantedBase) return entry.bytes;
+		if (!wantedBase && stripPartIndexPrefix(base) === "interaction.json") return entry.bytes;
+	}
+	if (wantedBase) {
+		for (const entry of readTarEntries(tar)) if (stripPartIndexPrefix(entry.name.split("/").pop() ?? entry.name) === "interaction.json") return entry.bytes;
+	}
+	return null;
+}
+/**
+* Fetch an inbound email's attachments archive and return the raw
+* `interaction.json` bytes, or null when the email carries no such part.
+*
+* Mirrors the direct-fetch + bearer-auth pattern the zone-file download command
+* uses: the typed SDK client returns the archive as a Blob, which is awkward to
+* decompress; a plain fetch hands us an ArrayBuffer directly. `fetchImpl` is
+* injectable so tests can stub the network boundary.
+*/
+async function fetchInteractionJsonBytes(params) {
+	const response = await (params.fetchImpl ?? fetch)(attachmentsArchiveUrl(params.baseUrl, params.emailId), { headers: {
+		...params.headers ?? {},
+		...params.apiKey ? { authorization: `Bearer ${params.apiKey}` } : {}
+	} });
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		throw new Error(`Could not download attachments for inbound email ${params.emailId}: HTTP ${response.status}${text.trim() ? ` ${text.trim().slice(0, 200)}` : ""}`);
+	}
+	return interactionJsonFromArchive(new Uint8Array(await response.arrayBuffer()), interactionTarPathFromMeta(params.attachments));
+}
+/**
+* Derive the signable {@link X402EmailChallenge} from an inbound payment-request
+* email's `interaction.json` attachment. This is the auto-derive path behind
+* `pay-email --in-reply-to <id>` (with no `--challenge`) and
+* `challenge-from-email`: download the part, then reshape the wire envelope into
+* the challenge object via the SDK's canonical `parseEmailChallengeFromPart`.
+*
+* Throws a descriptive error when the email has no `interaction.json` part (so a
+* non-challenge email gives a clear message instead of a confusing signer crash)
+* or when the part is not a valid x402 challenge envelope (the SDK validator).
+*/
+async function deriveEmailChallengeFromInbound(params) {
+	const bytes = await fetchInteractionJsonBytes(params);
+	if (!bytes) throw new Error(`Inbound email ${params.emailId} has no ${INTERACTION_PART_FILENAME$1} attachment, so it is not an x402 payment request. Pass --challenge / --challenge-file if you have the challenge from another source.`);
+	return parseEmailChallengeFromPart(bytes);
+}
+//#endregion
 //#region src/oclif/commands/payments-shared.ts
 const PRIVATE_KEY_ENV = "PRIMITIVE_X402_PRIVATE_KEY";
 const PRIVATE_KEY_FLAG_DESCRIPTION = `Hex private key (0x-prefixed) of the wallet that signs. Prefer the ${PRIVATE_KEY_ENV} environment variable so the key is not exposed in shell history or the process list. The key is used locally to sign and never sent to Primitive.`;
@@ -27981,6 +28116,71 @@ function reportX402Error(error, ctx) {
 	});
 }
 //#endregion
+//#region src/oclif/commands/payments-challenge-from-email.ts
+var PaymentsChallengeFromEmailCommand = class PaymentsChallengeFromEmailCommand extends Command {
+	static description = `Derive and print the email x402 challenge object from a received payment-request email.
+
+  A payer receives an x402 payment request as an email carrying an
+  \`interaction.json\` attachment (the wire envelope). The signing commands,
+  however, take the challenge object the payee's \`create-email-challenge\` API
+  returns, which has a different field layout. This command downloads the inbound
+  email's \`interaction.json\` attachment and reshapes it into that challenge
+  object, printing it to stdout.
+
+  Use it when you want the challenge as a portable artifact (e.g. to feed
+  \`pay-email-step\` for offline signing, or an SDK \`payEmailChallenge\` call).
+  For the simple one-shot, prefer \`pay-email --in-reply-to <id>\`, which derives
+  the challenge internally and needs no intermediate file.
+
+      primitive payments challenge-from-email --id <inbound-id> > challenge.json
+      primitive payments challenge-from-email --id <inbound-id> \\
+        | primitive payments pay-email-step > interaction.json`;
+	static summary = "Print the email x402 challenge object derived from a received payment-request email";
+	static examples = ["<%= config.bin %> payments challenge-from-email --id <inbound-email-id>", "<%= config.bin %> payments challenge-from-email --id <inbound-email-id> | <%= config.bin %> payments pay-email-step > interaction.json"];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		id: Flags.string({
+			description: "Id of the inbound payment-request email whose interaction.json attachment carries the challenge.",
+			required: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(PaymentsChallengeFromEmailCommand);
+		const { auth, baseUrlOverridden, requestConfig } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			try {
+				const challenge = await deriveEmailChallengeFromInbound({
+					baseUrl: auth.apiBaseUrl,
+					emailId: flags.id,
+					apiKey: auth.apiKey,
+					headers: requestConfig.headers
+				});
+				this.log(JSON.stringify(challenge, null, 2));
+			} catch (error) {
+				reportX402Error(error, {
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir
+				});
+				process.exitCode = 1;
+			}
+		});
+	}
+};
+//#endregion
 //#region src/oclif/commands/payments-charge.ts
 var PaymentsChargeCommand = class PaymentsChargeCommand extends Command {
 	static description = `Request an x402 payment by creating a challenge (payee side).
@@ -28289,7 +28489,136 @@ var PaymentsPayEmailStepCommand = class PaymentsPayEmailStepCommand extends Comm
 	}
 };
 //#endregion
+//#region src/oclif/commands/payments-settlement.ts
+/** The human-readable notice describing the async-settlement model. */
+const settlementWaitNotice = "Note: the payment has been SENT, but x402 settlement is asynchronous. --wait only confirms email delivery (SMTP 250), not on-chain settlement. The settle_tx hash arrives in a follow-up x402 settlement interaction email from the payee. Use --wait-settle to poll for it.";
+/** The steps a payer has already seen / sent, so a matching later step is the receipt. */
+const NON_RECEIPT_STEPS = new Set(["challenge", "payment"]);
+/**
+* Best-effort extraction of a `settle_tx` from a receipt envelope. The exact
+* receipt wire shape is owned by the platform and not pinned in the SDK, so we
+* do not assert a rigid schema: we look for a `settle_tx` string at the top
+* level or one level into `payload` (the two places interaction envelopes carry
+* step data). Returns null when absent; the caller always prints the full
+* envelope regardless, so a miss never hides data.
+*/
+function extractSettleTx(envelope) {
+	const top = envelope.settle_tx;
+	if (typeof top === "string" && top) return top;
+	const payload = envelope.payload;
+	if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+		const nested = payload.settle_tx;
+		if (typeof nested === "string" && nested) return nested;
+	}
+	return null;
+}
+/**
+* Parse interaction.json bytes into an envelope object, or null when the bytes
+* are not a JSON object (so a non-interaction attachment is simply skipped).
+*/
+function parseInteractionEnvelope(bytes) {
+	let parsed;
+	try {
+		parsed = JSON.parse(new TextDecoder().decode(bytes));
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+	return parsed;
+}
+/**
+* True when a downloaded interaction.json envelope is the settlement receipt for
+* the interaction we paid: same `interaction_id`, and a step the payer has not
+* already produced/received (i.e. not `challenge` / `payment`). Matching on the
+* confirmed interaction_id keeps this correct without depending on the exact
+* receipt step name, which the platform owns.
+*/
+function isSettlementReceiptFor(envelope, interactionId) {
+	if (envelope.interaction_id !== interactionId) return false;
+	const step = envelope.step;
+	if (typeof step === "string" && NON_RECEIPT_STEPS.has(step)) return false;
+	return true;
+}
+/**
+* Poll the inbox for the x402 settlement interaction email that answers the
+* payment we just sent, and return it once found. Returns null on timeout.
+*
+* Searches inbound mail from the payee (with attachments) received since the
+* send, downloads each candidate's interaction.json, and matches it by
+* interaction_id via {@link isSettlementReceiptFor}. Network access is via the
+* injected api client (search) plus a plain fetch for the attachment archive,
+* mirroring how the rest of the payments surface reads attachments; `fetchImpl`
+* is injectable for tests.
+*/
+async function pollForSettlementInteraction(params) {
+	const deadline = params.timeoutSeconds === 0 ? null : Date.now() + params.timeoutSeconds * 1e3;
+	const checked = /* @__PURE__ */ new Set();
+	while (deadline === null || Date.now() < deadline) {
+		let cursor = null;
+		let receipt = null;
+		let drained = false;
+		while (!drained) {
+			const page = await fetchEmailSearchPage({
+				apiClient: params.apiClient,
+				cursor,
+				filters: {
+					from: params.payeeFrom,
+					hasAttachment: true
+				},
+				pageSize: 50,
+				since: params.since
+			});
+			if (!page.ok) break;
+			for (const row of page.rows) {
+				if (checked.has(row.id)) continue;
+				let bytes;
+				try {
+					bytes = await fetchInteractionJsonBytes({
+						baseUrl: params.baseUrl,
+						emailId: row.id,
+						apiKey: params.apiKey,
+						headers: params.headers,
+						fetchImpl: params.fetchImpl
+					});
+				} catch {
+					continue;
+				}
+				if (!bytes) continue;
+				const envelope = parseInteractionEnvelope(bytes);
+				if (!envelope) continue;
+				checked.add(row.id);
+				if (isSettlementReceiptFor(envelope, params.interactionId)) {
+					receipt = {
+						emailId: row.id,
+						envelope,
+						settleTx: extractSettleTx(envelope)
+					};
+					break;
+				}
+			}
+			if (receipt) break;
+			const nextCursor = page.cursor;
+			if (!nextCursor || nextCursor === cursor || page.rows.length === 0) drained = true;
+			else cursor = nextCursor;
+		}
+		if (receipt) return receipt;
+		if (deadline !== null && Date.now() >= deadline) break;
+		await sleep$1(params.intervalSeconds * 1e3);
+	}
+	return null;
+}
+//#endregion
 //#region src/oclif/commands/payments-pay-email.ts
+/**
+* True when none of the explicit challenge sources are present (no --challenge,
+* no --challenge-file, and stdin is an interactive TTY rather than a pipe). In
+* that case `pay-email` auto-derives the challenge from the inbound email's
+* interaction.json attachment. We treat a TTY stdin as "no challenge piped" so
+* the one-shot does not block on readFileSync(0) waiting for the user to paste.
+*/
+function shouldDeriveChallenge(flags) {
+	return flags.challenge === void 0 && flags["challenge-file"] === void 0;
+}
 /** The exact part name + content type the inbound matcher requires. */
 const INTERACTION_PART_FILENAME = "interaction.json";
 const INTERACTION_PART_CONTENT_TYPE = "application/json";
@@ -28312,34 +28641,64 @@ function emailDetailFromEnvelope(data) {
 	return data?.data ?? null;
 }
 var PaymentsPayEmailCommand = class PaymentsPayEmailCommand extends Command {
-	static description = `Pay an email-native x402 challenge in one step: sign it and send the signed interaction.json in-thread.
+	static description = `Pay an email-native x402 challenge in one step: sign it and send the signed interaction.json.
 
-  Reads the email challenge the payee issued (the JSON from
-  \`payments create-email-challenge\`), derives and signs the interaction-bound
-  EIP-3009 authorization locally with your wallet key (read from
-  ${PRIVATE_KEY_ENV} by default), and sends the signed \`interaction.json\`
-  attached as an \`application/json\` part. The key never leaves your machine.
+  THE ONE-COMMAND PAYER FLOW. You received a payment-request email carrying an
+  \`interaction.json\` attachment. Run:
 
-  This is the recommended payer path. It replaces the two-step
-  \`pay-email-step\` + \`send --attachment interaction.json\` dance: no manual
-  address or threading wrangling. Use \`pay-email-step\` only when you need the
-  signed bytes as a portable artifact without sending.
+      <%= config.bin %> payments pay-email --in-reply-to <inbound-email-id>
 
-  --in-reply-to is the id of the inbound challenge email you received. It is
-  fetched to derive the recipient (the payee, from the inbound's sender) and the
-  From (you, the payer, from the inbound's recipient). The outgoing send does
-  NOT thread under the challenge: threading would trigger the send endpoint's
-  parent-thread dedup and the payment would never settle. The interaction
-  associates by interaction_id instead. Pass --from only to override the derived
-  payer From.
+  with your wallet key in ${PRIVATE_KEY_ENV}, and this command auto-derives the
+  challenge from that inbound email's attachment, signs the interaction-bound
+  EIP-3009 authorization locally, and sends the signed \`interaction.json\` back
+  to the payee. The key never leaves your machine. You do NOT need --challenge or
+  --challenge-file: with just --in-reply-to the challenge is derived for you.
 
-  Provide the challenge inline with --challenge, from a file with
-  --challenge-file, or piped on stdin.`;
-	static summary = "Sign an email x402 challenge and send the signed interaction.json in-thread (one step)";
+  THE CHALLENGE OBJECT (only needed for the --challenge / --challenge-file
+  override). \`--challenge\` expects the object the PAYEE's
+  \`create-email-challenge\` API returns, NOT the inbound email's
+  \`interaction.json\` attachment (those are different shapes). Its fields are:
+
+      {
+        "interaction_id": "<uuid@domain>",     // the email thread id
+        "challenge": {
+          "payment_requirements": { ... },     // scheme, network, payTo, asset, ...
+          "nonce_binding": {
+            "interaction_id": "<uuid@domain>",  // must equal the outer interaction_id
+            "challenge_step_id": "<uuid>",      // the challenge step id
+            "challenge_nonce": "<64 hex chars>"
+          },
+          "expires_at": "<ISO-8601>"
+        }
+      }
+
+  As a real payer you usually have only the inbound email's attachment, whose
+  layout differs (top-level \`step\`, \`step_id\`, \`expires_at\`, and a nested
+  \`payload.payment_requirements\` / \`payload.challenge_nonce\`). You do NOT
+  reshape it by hand: omit --challenge and let --in-reply-to derive it, or run
+  \`payments challenge-from-email --id <inbound-id>\` to print the correctly
+  shaped challenge object. Pass --challenge / --challenge-file only when you have
+  the payee-side challenge from another source; it is used as-is and overrides
+  the auto-derive.
+
+  SETTLEMENT IS ASYNC. --wait only confirms the receiving MTA accepted the
+  message (SMTP 250); it does NOT confirm on-chain settlement. The \`settle_tx\`
+  hash arrives later in a follow-up inbound x402 settlement interaction email
+  from the payee. Use --wait-settle to poll for that settlement email after
+  sending and surface the receipt.
+
+  ADDRESSING. --in-reply-to is the inbound challenge email's id. It is fetched to
+  derive the recipient (the payee, from the inbound's sender) and the From (you,
+  the payer, from the inbound's recipient). The outgoing send does NOT thread
+  under the challenge: threading would trigger the send endpoint's parent-thread
+  dedup and the payment would never settle. The interaction associates by
+  interaction_id instead. Pass --from only to override the derived payer From.`;
+	static summary = "Sign an email x402 challenge and send the signed interaction.json (one step; derives the challenge from --in-reply-to)";
 	static examples = [
+		"<%= config.bin %> payments pay-email --in-reply-to <inbound-email-id>",
+		"<%= config.bin %> payments pay-email --in-reply-to <inbound-email-id> --wait-settle",
 		"<%= config.bin %> payments pay-email --challenge-file challenge.json --in-reply-to <inbound-email-id>",
-		"cat challenge.json | <%= config.bin %> payments pay-email --in-reply-to <inbound-email-id> --wait",
-		"<%= config.bin %> payments pay-email --challenge-file challenge.json --in-reply-to <inbound-email-id> --from 'Payer <payer@your-domain.example>'"
+		"<%= config.bin %> payments pay-email --in-reply-to <inbound-email-id> --from 'Payer <payer@your-domain.example>'"
 	];
 	static flags = {
 		"api-key": Flags.string({
@@ -28356,26 +28715,37 @@ var PaymentsPayEmailCommand = class PaymentsPayEmailCommand extends Command {
 			env: PRIVATE_KEY_ENV
 		}),
 		challenge: Flags.string({
-			description: "The email challenge object as a JSON string.",
+			description: "OVERRIDE: the payee-side email challenge object (the create-email-challenge response shape, NOT the inbound interaction.json attachment) as a JSON string. Optional: omit it and the challenge is auto-derived from the --in-reply-to email's attachment.",
 			exclusive: ["challenge-file"]
 		}),
 		"challenge-file": Flags.string({
-			description: "Path to a file containing the email challenge JSON.",
+			description: "OVERRIDE: path to a file containing the payee-side email challenge JSON (the create-email-challenge response shape). Optional: omit it and the challenge is auto-derived from the --in-reply-to email's attachment.",
 			exclusive: ["challenge"]
 		}),
 		"in-reply-to": Flags.string({
-			description: "Id of the inbound challenge email you received. It is fetched to derive the payee recipient and the payer From. The outgoing send is not threaded under the challenge; the payment associates by interaction_id.",
+			description: "Id of the inbound challenge email you received. With no --challenge / --challenge-file, its interaction.json attachment is downloaded and reshaped into the challenge to sign. It is also fetched to derive the payee recipient and the payer From. The outgoing send is not threaded under the challenge; the payment associates by interaction_id.",
 			required: true
 		}),
 		from: Flags.string({ description: "Optional From header override. Defaults to the inbound's recipient (the payer the challenge was addressed to)." }),
 		body: Flags.string({ description: `Plain-text body. The signed authorization travels in the interaction.json attachment; this is the human-readable accompanying note. Defaults to "${DEFAULT_BODY_TEXT}".` }),
-		wait: Flags.boolean({ description: "Block until the receiving MTA returns an outcome. Without --wait, the call returns once Primitive has accepted the message for delivery." }),
+		wait: Flags.boolean({ description: "Block until the receiving MTA returns a delivery outcome (SMTP 250). This confirms email DELIVERY only, NOT on-chain settlement. Without --wait, the call returns once Primitive has accepted the message for delivery." }),
+		"wait-settle": Flags.boolean({ description: "After sending, poll the inbox for the follow-up x402 settlement interaction email from the payee and print the settlement receipt (including settle_tx when present). Settlement is async, so this can take a while; tune with --settle-timeout / --settle-interval." }),
+		"settle-timeout": Flags.integer({
+			default: 180,
+			description: "With --wait-settle: seconds to wait for the settlement email before giving up (0 waits forever).",
+			min: 0
+		}),
+		"settle-interval": Flags.integer({
+			default: 5,
+			description: "With --wait-settle: seconds between settlement-email polls.",
+			min: 1
+		}),
 		json: Flags.boolean({ description: "Print a JSON object with the signed interaction step and the send result." }),
 		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
 	};
 	async run() {
 		const { flags } = await this.parse(PaymentsPayEmailCommand);
-		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+		const { apiClient, auth, baseUrlOverridden, requestConfig } = await createAuthenticatedCliApiClient({
 			apiKey: flags["api-key"],
 			apiBaseUrl: flags["api-base-url"],
 			configDir: this.config.configDir
@@ -28386,22 +28756,6 @@ var PaymentsPayEmailCommand = class PaymentsPayEmailCommand extends Command {
 			configDir: this.config.configDir
 		};
 		await runWithTiming(flags.time, async () => {
-			let built;
-			try {
-				built = await signEmailChallenge({
-					challenge: readEmailChallenge({
-						inline: flags.challenge,
-						file: flags["challenge-file"]
-					}),
-					privateKey: flags["private-key"] ?? "",
-					resolvedApiBaseUrl: auth.apiBaseUrl,
-					apiKey: flags["api-key"]
-				});
-			} catch (error) {
-				reportX402Error(error, authFailureContext);
-				process.exitCode = 1;
-				return;
-			}
 			const inboundResult = await getEmail({
 				client: apiClient.client,
 				path: { id: flags["in-reply-to"] },
@@ -28423,6 +28777,31 @@ var PaymentsPayEmailCommand = class PaymentsPayEmailCommand extends Command {
 				process.exitCode = 1;
 				return;
 			}
+			let built;
+			try {
+				let challenge;
+				if (shouldDeriveChallenge(flags)) challenge = await deriveEmailChallengeFromInbound({
+					baseUrl: auth.apiBaseUrl,
+					emailId: flags["in-reply-to"],
+					apiKey: auth.apiKey,
+					headers: requestConfig.headers,
+					attachments: inbound.parsed?.attachments
+				});
+				else challenge = readEmailChallenge({
+					inline: flags.challenge,
+					file: flags["challenge-file"]
+				});
+				built = await signEmailChallenge({
+					challenge,
+					privateKey: flags["private-key"] ?? "",
+					resolvedApiBaseUrl: auth.apiBaseUrl,
+					apiKey: flags["api-key"]
+				});
+			} catch (error) {
+				reportX402Error(error, authFailureContext);
+				process.exitCode = 1;
+				return;
+			}
 			const payeeTo = inbound.from_email;
 			const derivedPayerFrom = inbound.to_email || inbound.recipient;
 			const from = flags.from ?? derivedPayerFrom;
@@ -28436,6 +28815,7 @@ var PaymentsPayEmailCommand = class PaymentsPayEmailCommand extends Command {
 				process.exitCode = 1;
 				return;
 			}
+			const sendStartedAt = (/* @__PURE__ */ new Date()).toISOString();
 			const result = await sendEmail({
 				body: {
 					from,
@@ -28463,13 +28843,40 @@ var PaymentsPayEmailCommand = class PaymentsPayEmailCommand extends Command {
 			if (replayed) writeIdempotentReplayBannerIfReplay(sent, { write: (chunk) => {
 				process.stderr.write(chunk);
 			} });
+			let settlement = null;
+			if (flags["wait-settle"] && !replayed && payeeTo) {
+				process.stderr.write("Payment sent. Waiting for the x402 settlement interaction email (settlement is async)...\n");
+				settlement = await pollForSettlementInteraction({
+					apiClient,
+					baseUrl: auth.apiBaseUrl,
+					apiKey: auth.apiKey,
+					headers: requestConfig.headers,
+					interactionId: built.envelope.interaction_id,
+					payeeFrom: payeeTo,
+					since: sendStartedAt,
+					timeoutSeconds: flags["settle-timeout"],
+					intervalSeconds: flags["settle-interval"]
+				});
+				if (settlement) process.stderr.write(settlement.settleTx ? `Settled. settle_tx: ${settlement.settleTx}\n` : "Settlement interaction received (no settle_tx field present; full receipt below).\n");
+				else process.stderr.write("Timed out waiting for the x402 settlement interaction email. The payment was sent; the settle_tx will arrive in a follow-up x402 settlement interaction email from the payee. Re-run with --wait-settle, or check your inbox for an x402 settlement message.\n");
+			}
 			if (flags.json) this.log(JSON.stringify({
 				interaction: built.envelope,
 				sent,
-				idempotent_replay: replayed
+				idempotent_replay: replayed,
+				...flags["wait-settle"] ? { settlement: settlement ? {
+					email_id: settlement.emailId,
+					settle_tx: settlement.settleTx,
+					receipt: settlement.envelope
+				} : null } : {}
 			}, null, 2));
-			else this.log(JSON.stringify(sent, null, 2));
+			else {
+				this.log(JSON.stringify(sent, null, 2));
+				if (!flags["wait-settle"]) process.stderr.write(`${settlementWaitNotice}\n`);
+				else if (settlement) this.log(JSON.stringify(settlement.envelope, null, 2));
+			}
 			if (replayed) process.exitCode = 1;
+			else if (flags["wait-settle"] && !settlement) process.exitCode = 1;
 		});
 	}
 };
@@ -30087,7 +30494,8 @@ const COMMANDS = {
 	"payments:pay-challenge": PaymentsPayCommand,
 	"payments:pay": PaymentsPayCommand,
 	"payments:pay-email": PaymentsPayEmailCommand,
-	"payments:pay-email-step": PaymentsPayEmailStepCommand
+	"payments:pay-email-step": PaymentsPayEmailStepCommand,
+	"payments:challenge-from-email": PaymentsChallengeFromEmailCommand
 };
 //#endregion
 export { CANONICAL_OPERATION_ALIASES, COMMANDS, lookupOperation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primcli",
-  "version": "1.13.3",
+  "version": "1.14.1",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,