primcli 1.14.0 → 1.14.2

package/README.md

@@ -73,6 +73,26 @@ primitive deliveries replay --id <delivery-id>
 
 Generated API commands remain available for compatibility and full schema parity, for example `primitive emails:list-emails` and `primitive sending:reply-to-email`.
 
+## Recipient routing
+
+Bind a recipient address to a destination so inbound mail resolves to a single
+endpoint. Pass `--function` to route an address to a function (its route-target
+endpoint is created in the same call, enabling per-address routing like
+`alice@acme.com -> functionA`), or `--endpoint` for an existing endpoint.
+
+```bash
+primitive routes add alice@acme.com --function <function-id>
+primitive routes add 'support+*@acme.com' --match wildcard --endpoint <endpoint-id>
+primitive routes list
+primitive routes test alice@acme.com          # preview where an address resolves, with the rule trace
+primitive routes update <route-id> --priority 5
+primitive routes reorder --set <route-id>=10 --set <other-id>=20
+primitive routes remove <route-id>
+```
+
+Recipient routing is gated by an organization entitlement; routes are inert
+until it is enabled.
+
 ## x402 payments
 
 The `primitive payments` command group drives non-custodial x402 USDC payments. One agent registers a payout address and requests a payment; the paying agent signs locally with its own wallet key and settles. The key never leaves your machine. Networks are `base` and `base-sepolia`. Amounts take a human USDC value (`--amount-usdc 0.01`) or token base units (`--amount 10000`, since USDC has 6 decimals). Your org is resolved automatically from your API key, so payout registration takes no org flag.

package/dist/{cli-config-B5hrwe8q.js → cli-config-C-7V83Qd.js}

@@ -1124,6 +1124,21 @@ function detectPrimitiveKeyEnvMisname(env = process.env) {
 	if ((primitiveKey?.length ?? 0) > 0 && (primitiveApiKey?.length ?? 0) === 0) return "PRIMITIVE_KEY is set but the CLI reads PRIMITIVE_API_KEY. Rename your env var, or re-run with PRIMITIVE_API_KEY=$PRIMITIVE_KEY.";
 	return null;
 }
+/**
+* True when a usable OAuth login session is saved on disk. Used by `pay-email`
+* to decide whether it can safely ignore an env-only `PRIMITIVE_API_KEY` in
+* favor of the payer's logged-in account (which owns the inbound challenge
+* inbox). Returns false when nothing is stored or the stored credential is
+* unreadable/legacy, so the caller falls back to whatever key did resolve
+* rather than silently dropping the user's only auth.
+*/
+function hasStoredCliLogin(configDir) {
+	try {
+		return loadCliCredentials(configDir) !== null;
+	} catch {
+		return false;
+	}
+}
 function resolveCliAuth(params) {
 	const apiKey = params.apiKey?.trim();
 	const apiBaseUrl = normalizeApiBaseUrl(params.apiBaseUrl);
@@ -1327,4 +1342,4 @@ function redactCliEnvironment(environment) {
 	};
 }
 //#endregion
-export { PrimitiveApiClient as A, saveCliCredentials as C, loadActiveChatState as D, deleteChatState as E, createConfig as M, loadChatConversationByLocalId as O, resolveCliAuth as S, chatStatePath as T, deleteCliCredentials as _, normalizeCliEnvironmentName as a, loadCliCredentials as b, resolveConfigEnvironment as c, validateCliHeaderName as d, validateCliHeaderValue as f, credentialsPath as g, credentialsLockPath as h, loadCliConfig as i, createClient as j, saveActiveChatState as k, saveCliConfig as l, cliAccessTokenExpiresAt as m, deleteCliConfig as n, redactCliEnvironment as o, acquireCliCredentialsLock as p, emptyCliConfig as r, removeCliEnvironment as s, DEFAULT_ENVIRONMENT as t, upsertCliEnvironment as u, deleteCliCredentialsLock as v, saveSignupCredentials as w, normalizeApiBaseUrl as x, detectPrimitiveKeyEnvMisname as y };
+export { saveActiveChatState as A, resolveCliAuth as C, deleteChatState as D, chatStatePath as E, createClient as M, createConfig as N, loadActiveChatState as O, normalizeApiBaseUrl as S, saveSignupCredentials as T, deleteCliCredentials as _, normalizeCliEnvironmentName as a, hasStoredCliLogin as b, resolveConfigEnvironment as c, validateCliHeaderName as d, validateCliHeaderValue as f, credentialsPath as g, credentialsLockPath as h, loadCliConfig as i, PrimitiveApiClient as j, loadChatConversationByLocalId as k, saveCliConfig as l, cliAccessTokenExpiresAt as m, deleteCliConfig as n, redactCliEnvironment as o, acquireCliCredentialsLock as p, emptyCliConfig as r, removeCliEnvironment as s, DEFAULT_ENVIRONMENT as t, upsertCliEnvironment as u, deleteCliCredentialsLock as v, saveCliCredentials as w, loadCliCredentials as x, detectPrimitiveKeyEnvMisname as y };

package/dist/oclif/index.js

@@ -1,4 +1,4 @@
-import { A as PrimitiveApiClient, C as saveCliCredentials, D as loadActiveChatState, E as deleteChatState, M as createConfig, O as loadChatConversationByLocalId, S as resolveCliAuth, T as chatStatePath, _ as deleteCliCredentials, a as normalizeCliEnvironmentName, b as loadCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, g as credentialsPath, h as credentialsLockPath, i as loadCliConfig, j as createClient, k as saveActiveChatState, l as saveCliConfig, m as cliAccessTokenExpiresAt, n as deleteCliConfig, o as redactCliEnvironment, p as acquireCliCredentialsLock, r as emptyCliConfig, s as removeCliEnvironment, u as upsertCliEnvironment, v as deleteCliCredentialsLock, w as saveSignupCredentials, x as normalizeApiBaseUrl, y as detectPrimitiveKeyEnvMisname } from "../cli-config-B5hrwe8q.js";
+import { A as saveActiveChatState, C as resolveCliAuth, D as deleteChatState, E as chatStatePath, M as createClient, N as createConfig, O as loadActiveChatState, S as normalizeApiBaseUrl, T as saveSignupCredentials, _ as deleteCliCredentials, a as normalizeCliEnvironmentName, b as hasStoredCliLogin, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, g as credentialsPath, h as credentialsLockPath, i as loadCliConfig, j as PrimitiveApiClient, k as loadChatConversationByLocalId, l as saveCliConfig, m as cliAccessTokenExpiresAt, n as deleteCliConfig, o as redactCliEnvironment, p as acquireCliCredentialsLock, r as emptyCliConfig, s as removeCliEnvironment, u as upsertCliEnvironment, v as deleteCliCredentialsLock, w as saveCliCredentials, x as loadCliCredentials, y as detectPrimitiveKeyEnvMisname } from "../cli-config-C-7V83Qd.js";
 import { Args, Command, Errors, Flags, ux } from "@oclif/core";
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -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
@@ -3606,6 +3607,7 @@ const openapiDocument = {
 					},
 					"400": { "$ref": "#/components/responses/ValidationError" },
 					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"403": { "$ref": "#/components/responses/Forbidden" },
 					"409": { "$ref": "#/components/responses/Conflict" }
 				}
 			}
@@ -3675,6 +3677,7 @@ const openapiDocument = {
 					},
 					"400": { "$ref": "#/components/responses/ValidationError" },
 					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"403": { "$ref": "#/components/responses/Forbidden" },
 					"404": { "$ref": "#/components/responses/NotFound" },
 					"409": { "$ref": "#/components/responses/Conflict" }
 				}
@@ -27465,7 +27468,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.
@@ -27785,6 +27861,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.`;
@@ -27899,6 +28118,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).
@@ -28207,7 +28491,153 @@ 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;
+}
+/**
+* Decide the api-key `pay-email` should authenticate its inbox reads with, given
+* the parsed flag value, whether `--api-key` was passed explicitly on the
+* command line (vs sourced from `PRIMITIVE_API_KEY`), and whether a logged-in
+* session exists. Returns the key to use, or `undefined` to fall through to the
+* stored login. See the block comment above for the precedence rationale.
+*/
+function resolvePayerInboxApiKey(params) {
+	if (params.apiKeyFlag !== void 0 && params.apiKeyFromEnvOnly && params.hasStoredLogin) return {
+		apiKey: void 0,
+		usedStoredLoginOverEnvKey: true
+	};
+	return {
+		apiKey: params.apiKeyFlag,
+		usedStoredLoginOverEnvKey: false
+	};
+}
 /** The exact part name + content type the inbound matcher requires. */
 const INTERACTION_PART_FILENAME = "interaction.json";
 const INTERACTION_PART_CONTENT_TYPE = "application/json";
@@ -28230,34 +28660,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({
@@ -28274,27 +28734,46 @@ 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({
-			apiKey: flags["api-key"],
+		const { flags, raw } = await this.parse(PaymentsPayEmailCommand);
+		const apiKeyFlagExplicit = raw.some((token) => token.type === "flag" && token.flag === "api-key");
+		const apiKeyFromEnvOnly = flags["api-key"] !== void 0 && !apiKeyFlagExplicit;
+		const { apiKey: effectiveApiKey, usedStoredLoginOverEnvKey } = resolvePayerInboxApiKey({
+			apiKeyFlag: flags["api-key"],
+			apiKeyFromEnvOnly,
+			hasStoredLogin: hasStoredCliLogin(this.config.configDir)
+		});
+		if (usedStoredLoginOverEnvKey) process.stderr.write("PRIMITIVE_API_KEY is set, but pay-email reads the inbound challenge from your logged-in account's inbox, so it is using your saved login for this command. Pass --api-key explicitly to override.\n");
+		const { apiClient, auth, baseUrlOverridden, requestConfig } = await createAuthenticatedCliApiClient({
+			apiKey: effectiveApiKey,
 			apiBaseUrl: flags["api-base-url"],
 			configDir: this.config.configDir
 		});
@@ -28304,22 +28783,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"] },
@@ -28332,6 +28795,7 @@ var PaymentsPayEmailCommand = class PaymentsPayEmailCommand extends Command {
 					...authFailureContext,
 					payload: errorPayload
 				});
+				if (extractErrorCode(errorPayload) === API_ERROR_CODES.notFound && auth.source === "flag-or-env") process.stderr.write("The inbound challenge email was not found for the org this API key belongs to. pay-email reads the challenge from the PAYER account's inbox: unset PRIMITIVE_API_KEY (or pass --api-key for the payer's org, or run `primitive signin` as the payer) and retry.\n");
 				process.exitCode = 1;
 				return;
 			}
@@ -28341,6 +28805,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: effectiveApiKey
+				});
+			} 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;
@@ -28354,6 +28843,7 @@ var PaymentsPayEmailCommand = class PaymentsPayEmailCommand extends Command {
 				process.exitCode = 1;
 				return;
 			}
+			const sendStartedAt = (/* @__PURE__ */ new Date()).toISOString();
 			const result = await sendEmail({
 				body: {
 					from,
@@ -28381,13 +28871,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;
 		});
 	}
 };
@@ -28674,6 +29191,434 @@ var ReplyCommand = class ReplyCommand extends Command {
 	}
 };
 //#endregion
+//#region src/oclif/commands/routes-add.ts
+function resolveCreateTarget(flags) {
+	if (flags.function) return { function_id: flags.function };
+	if (flags.endpoint) return { endpoint_id: flags.endpoint };
+	return { error: "Provide exactly one of --function (route to a function) or --endpoint (an existing endpoint)." };
+}
+var RoutesAddCommand = class RoutesAddCommand extends Command {
+	static description = `Create a recipient route binding an address pattern to a destination.
+
+  Provide exactly one of --function (route to a function; its route-target
+  endpoint is created in the same transaction) or --endpoint (an existing
+  endpoint). The match type defaults to exact; use --match wildcard for
+  patterns like 'support+*@acme.com'.`;
+	static summary = "Add a recipient route";
+	static examples = [
+		"<%= config.bin %> routes add alice@acme.com --function <fn-id>",
+		"<%= config.bin %> routes add 'support+*@acme.com' --match wildcard --function <fn-id>",
+		"<%= config.bin %> routes add billing@acme.com --endpoint <endpoint-id> --priority 10"
+	];
+	static args = { pattern: Args.string({
+		description: "Recipient address or wildcard pattern (e.g. alice@acme.com).",
+		required: true
+	}) };
+	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
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION }),
+		function: Flags.string({
+			description: "Function id to route this address to (its route-target endpoint is minted if needed). Mutually exclusive with --endpoint.",
+			exclusive: ["endpoint"]
+		}),
+		endpoint: Flags.string({
+			description: "Existing endpoint id to route to. Mutually exclusive with --function.",
+			exclusive: ["function"]
+		}),
+		match: Flags.string({
+			description: "Match type for the pattern. regex requires the Power plan and may be rejected if not enabled.",
+			options: [
+				"exact",
+				"wildcard",
+				"regex"
+			],
+			default: "exact"
+		}),
+		domain: Flags.string({ description: "Scope the route to this domain id (defaults to the pattern's domain)." }),
+		priority: Flags.integer({ description: "Evaluation order within a scope; lower is checked first." }),
+		disabled: Flags.boolean({ description: "Create the route disabled." })
+	};
+	async run() {
+		const { args, flags } = await this.parse(RoutesAddCommand);
+		const target = resolveCreateTarget(flags);
+		if ("error" in target) {
+			process.stderr.write(`${target.error}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await createRoute({
+				client: apiClient.client,
+				body: {
+					match_type: flags.match,
+					pattern: args.pattern,
+					...target,
+					...flags.domain ? { domain_id: flags.domain } : {},
+					...flags.priority != null ? { priority: flags.priority } : {},
+					...flags.disabled ? { enabled: false } : {}
+				},
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/routes-list.ts
+var RoutesListCommand = class RoutesListCommand extends Command {
+	static description = "List the org's recipient routes in evaluation order.";
+	static summary = "List recipient routes";
+	static examples = ["<%= config.bin %> routes list"];
+	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
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(RoutesListCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await listRoutes({
+				client: apiClient.client,
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/routes-remove.ts
+var RoutesRemoveCommand = class RoutesRemoveCommand extends Command {
+	static description = "Delete a recipient route by id. Mail matching its pattern then falls back to the domain or organization default.";
+	static summary = "Remove a recipient route";
+	static examples = ["<%= config.bin %> routes remove <route-id>"];
+	static args = { id: Args.string({
+		description: "Route id (UUID) to delete.",
+		required: true
+	}) };
+	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
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { args, flags } = await this.parse(RoutesRemoveCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await deleteRoute({
+				client: apiClient.client,
+				path: { id: args.id },
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/routes-reorder.ts
+function parseReorderUpdates(set) {
+	const updates = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const pair of set) {
+		const eq = pair.lastIndexOf("=");
+		const id = (eq >= 0 ? pair.slice(0, eq).trim() : "").toLowerCase();
+		const priority = eq >= 0 ? Number(pair.slice(eq + 1).trim()) : NaN;
+		if (!id || !Number.isInteger(priority) || priority < 0) return { error: `Invalid --set value "${pair}"; expected <route-id>=<priority> with a non-negative integer priority.` };
+		if (seen.has(id)) return { error: `Route ${id} appears more than once in --set; specify each route at most once.` };
+		seen.add(id);
+		updates.push({
+			id,
+			priority
+		});
+	}
+	return { updates };
+}
+var RoutesReorderCommand = class RoutesReorderCommand extends Command {
+	static description = `Set the priority of one or more recipient routes in a single call.
+
+  Priority controls evaluation order within a scope; lower is checked first.
+  Pass --set <route-id>=<priority> once per route you want to move.`;
+	static summary = "Reorder recipient routes";
+	static examples = ["<%= config.bin %> routes reorder --set <route-id>=10", "<%= config.bin %> routes reorder --set <id-a>=10 --set <id-b>=20"];
+	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
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION }),
+		set: Flags.string({
+			description: "A route and its new priority as <route-id>=<priority>. Repeatable.",
+			multiple: true,
+			required: true
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(RoutesReorderCommand);
+		const parsed = parseReorderUpdates(flags.set);
+		if ("error" in parsed) {
+			process.stderr.write(`${parsed.error}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const { updates } = parsed;
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await reorderRoutes({
+				client: apiClient.client,
+				body: { updates },
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/routes-test.ts
+var RoutesTestCommand = class RoutesTestCommand extends Command {
+	static description = `Simulate routing for a recipient address.
+
+  Shows the resolved destination and a trace of every rule evaluated (which
+  matched or missed, and why). Does not create or change anything.`;
+	static summary = "Simulate routing for a recipient";
+	static examples = ["<%= config.bin %> routes test alice@acme.com", "<%= config.bin %> routes test bounce@acme.com --event-type email.bounced"];
+	static args = { recipient: Args.string({
+		description: "Recipient address to simulate (e.g. alice@acme.com).",
+		required: true
+	}) };
+	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
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION }),
+		"event-type": Flags.string({ description: "Event type to model (defaults to email.received)." })
+	};
+	async run() {
+		const { args, flags } = await this.parse(RoutesTestCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await simulateRoute({
+				client: apiClient.client,
+				body: {
+					recipient: args.recipient,
+					...flags["event-type"] ? { event_type: flags["event-type"] } : {}
+				},
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/routes-update.ts
+function buildUpdateBody(flags) {
+	return {
+		...flags.match ? { match_type: flags.match } : {},
+		...flags.pattern ? { pattern: flags.pattern } : {},
+		...flags.endpoint ? { endpoint_id: flags.endpoint } : {},
+		...flags.domain ? { domain_id: flags.domain } : {},
+		...flags.priority != null ? { priority: flags.priority } : {},
+		...flags.enable ? { enabled: true } : {},
+		...flags.disable ? { enabled: false } : {}
+	};
+}
+var RoutesUpdateCommand = class RoutesUpdateCommand extends Command {
+	static description = `Update an existing recipient route.
+
+  Change the pattern, match type, target endpoint, domain scope, priority, or
+  enabled state. Provide at least one field; anything omitted is left as-is.`;
+	static summary = "Update a recipient route";
+	static examples = [
+		"<%= config.bin %> routes update <route-id> --priority 5",
+		"<%= config.bin %> routes update <route-id> --pattern alice@acme.com",
+		"<%= config.bin %> routes update <route-id> --disable"
+	];
+	static args = { id: Args.string({
+		description: "Route id (UUID) to update.",
+		required: true
+	}) };
+	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
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION }),
+		match: Flags.string({
+			description: "New match type for the pattern.",
+			options: [
+				"exact",
+				"wildcard",
+				"regex"
+			]
+		}),
+		pattern: Flags.string({ description: "New recipient address or wildcard pattern." }),
+		endpoint: Flags.string({ description: "New target endpoint id (UUID)." }),
+		domain: Flags.string({ description: "New domain scope id (UUID)." }),
+		priority: Flags.integer({ description: "New evaluation priority within a scope; lower is checked first." }),
+		enable: Flags.boolean({
+			description: "Enable the route.",
+			exclusive: ["disable"]
+		}),
+		disable: Flags.boolean({
+			description: "Disable the route.",
+			exclusive: ["enable"]
+		})
+	};
+	async run() {
+		const { args, flags } = await this.parse(RoutesUpdateCommand);
+		const body = buildUpdateBody(flags);
+		if (Object.keys(body).length === 0) {
+			process.stderr.write("Provide at least one field to update (--match, --pattern, --endpoint, --domain, --priority, --enable/--disable).\n");
+			process.exitCode = 1;
+			return;
+		}
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await updateRoute({
+				client: apiClient.client,
+				path: { id: args.id },
+				body,
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
 //#region src/oclif/commands/semantic-search.ts
 const DEFAULT_LIMIT$1 = 10;
 const MAX_LIMIT$1 = 100;
@@ -29992,6 +30937,12 @@ const COMMANDS = {
 	"functions:route-unset": FunctionsRouteUnsetCommand,
 	"functions:route-get": FunctionsRouteGetCommand,
 	"functions:routing-topology": FunctionsRoutingTopologyCommand,
+	"routes:add": RoutesAddCommand,
+	"routes:list": RoutesListCommand,
+	"routes:test": RoutesTestCommand,
+	"routes:update": RoutesUpdateCommand,
+	"routes:reorder": RoutesReorderCommand,
+	"routes:remove": RoutesRemoveCommand,
 	...Object.fromEntries(Object.entries(CANONICAL_OPERATION_ALIASES).map(([alias, target]) => {
 		const command = generatedCommands[target];
 		if (!command) throw new Error(`Missing generated command target for alias ${alias}`);
@@ -30005,7 +30956,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/dist/oclif/root-signup-hint.js

@@ -1,4 +1,4 @@
-import { c as resolveConfigEnvironment, i as loadCliConfig, x as normalizeApiBaseUrl } from "../cli-config-B5hrwe8q.js";
+import { S as normalizeApiBaseUrl, c as resolveConfigEnvironment, i as loadCliConfig } from "../cli-config-C-7V83Qd.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primcli",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "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,