@primitivedotdev/sdk 1.7.0 → 1.8.0

package/dist/{webhook-CwjCyFv-.js → webhook-CiIPtegj.js}

@@ -8132,6 +8132,94 @@ function verifyDownloadToken(params) {
 	return { valid: true };
 }
 //#endregion
+//#region src/webhook/events.ts
+/**
+* The five first-party email events (subject = an email).
+*/
+const EMAIL_EVENT_TYPES = [
+	"email.received",
+	"email.bounced",
+	"email.tls_report",
+	"email.dmarc_report",
+	"email.dmarc_failure"
+];
+/**
+* The two x402 settlement-notification events (subject = a payment). Emitted for
+* both the synthetic API pay flow and the email-native settle path.
+*/
+const PAYMENT_EVENT_TYPES = ["payment.settled", "payment.failed"];
+/**
+* The interaction step events (subject = an interaction). One event per accepted
+* protocol step, named `interaction.<protocolShort>.<suffix>`.
+*
+* The x402 slice covers the payment lifecycle a payee/payer cares about; the ack
+* slice covers the acknowledgement protocols.
+*/
+const INTERACTION_EVENT_TYPES = [
+	"interaction.ack.acked",
+	"interaction.ack.canceled",
+	"interaction.ack.expired",
+	"interaction.ack.received",
+	"interaction.ack.requested",
+	"interaction.x402.challenge",
+	"interaction.x402.declined",
+	"interaction.x402.expired",
+	"interaction.x402.payment",
+	"interaction.x402.rejected",
+	"interaction.x402.settled",
+	"interaction.x402.verify_timeout"
+];
+/**
+* The full enumerated catalog of every current webhook event type: the five
+* email.*, the two payment.*, and every interaction.<protocol>.<suffix>.
+*/
+const WEBHOOK_EVENT_TYPES = [
+	...EMAIL_EVENT_TYPES,
+	...PAYMENT_EVENT_TYPES,
+	...INTERACTION_EVENT_TYPES
+];
+const WEBHOOK_EVENT_TYPE_SET = new Set(WEBHOOK_EVENT_TYPES);
+/** True if `eventType` is a known current catalog value. */
+function isKnownWebhookEventType(eventType) {
+	return eventType != null && WEBHOOK_EVENT_TYPE_SET.has(eventType);
+}
+function eventName(event) {
+	if (typeof event !== "object" || event === null) return void 0;
+	const value = event.event;
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* Type guard for the `email.received` event. Confirms the discriminator AND
+* that the body validates against the canonical schema, so a payload that names
+* itself `email.received` but is malformed does not narrow.
+*/
+function isEmailReceivedEvent(event) {
+	if (eventName(event) !== "email.received") return false;
+	try {
+		validateEmailReceivedEvent(event);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Type guard for any `payment.*` event. */
+function isPaymentEvent(event) {
+	const name = eventName(event);
+	return name === "payment.settled" || name === "payment.failed";
+}
+/** Type guard for the `payment.settled` event. */
+function isPaymentSettledEvent(event) {
+	return eventName(event) === "payment.settled";
+}
+/** Type guard for the `payment.failed` event. */
+function isPaymentFailedEvent(event) {
+	return eventName(event) === "payment.failed";
+}
+/** Type guard for any `interaction.x402.*` event. */
+function isInteractionX402Event(event) {
+	return eventName(event)?.startsWith("interaction.x402.") ?? false;
+}
+//#endregion
 //#region src/webhook/encoding.ts
 /**
 * Buffer encoding utilities
@@ -10014,40 +10102,52 @@ const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/
 * }
 * ```
 */
-function parseWebhookEvent(input) {
+function parseWebhookEvent(input, eventType) {
 	if (input === null) throw new WebhookPayloadError("PAYLOAD_NULL", "Received null instead of webhook payload", "Check that your request body variable is defined.");
 	if (input === void 0) throw new WebhookPayloadError("PAYLOAD_UNDEFINED", "Received undefined instead of webhook payload", "Make sure you're passing the request body to parseWebhookEvent()");
 	if (Array.isArray(input)) throw new WebhookPayloadError("PAYLOAD_IS_ARRAY", "Received array instead of webhook payload object", "Webhook payloads must be objects, not arrays.");
 	if (typeof input !== "object") throw new WebhookPayloadError("PAYLOAD_WRONG_TYPE", `Received ${typeof input} instead of webhook payload object`, "Webhook payloads must be objects.");
 	const obj = input;
-	if (!("event" in obj) || typeof obj.event !== "string") throw new WebhookPayloadError("PAYLOAD_MISSING_EVENT", "Missing 'event' field in payload", "This doesn't look like a Primitive webhook payload.");
-	switch (obj.event) {
+	const resolvedEvent = typeof eventType === "string" && eventType || (typeof obj.event === "string" ? obj.event : void 0);
+	if (!resolvedEvent) throw new WebhookPayloadError("PAYLOAD_MISSING_EVENT", "Missing event discriminator: no X-Webhook-Event header and no 'event' field in payload", "Pass the X-Webhook-Event header (the canonical discriminator) or call handleWebhookEvent, which reads it for you.");
+	switch (resolvedEvent) {
 		case "email.received": return validateEmailReceivedEvent(input);
-		default: return input;
+		case "payment.settled":
+		case "payment.failed": return {
+			...obj,
+			event: resolvedEvent
+		};
+		default:
+			if (isKnownWebhookEventType(resolvedEvent)) return {
+				...obj,
+				event: resolvedEvent
+			};
+			return {
+				...obj,
+				event: resolvedEvent
+			};
 	}
 }
 /**
-* Type guard to check if a webhook event is an EmailReceivedEvent.
-*
-* @example
-* ```typescript
-* const event = parseWebhookEvent(payload);
-* if (isEmailReceivedEvent(event)) {
-*   // TypeScript knows event is EmailReceivedEvent
-*   console.log(event.email.headers.subject);
-* }
-* ```
+* The header that names the webhook event for ALL event families
+* (`email.*`, `payment.*`, `interaction.*`). It is the primary discriminator
+* the parser keys on, because the stored body is sent verbatim with no envelope.
 */
-function isEmailReceivedEvent(event) {
-	if (typeof event !== "object" || event === null || !("event" in event) || event.event !== "email.received") return false;
-	try {
-		validateEmailReceivedEvent(event);
-		return true;
-	} catch {
-		return false;
-	}
-}
+const WEBHOOK_EVENT_HEADER = "X-Webhook-Event";
 const SIGNATURE_HEADER_NAMES = ["primitive-signature", "mymx-signature"];
+/**
+* Read the `X-Webhook-Event` header value (case-insensitive). Returns null when
+* the header is absent.
+*/
+function getEventHeader(headers) {
+	if (headers instanceof Headers) return headers.get("x-webhook-event");
+	const obj = headers;
+	const key = Object.keys(obj).find((k) => k.toLowerCase() === "x-webhook-event");
+	if (!key) return null;
+	const value = obj[key];
+	if (Array.isArray(value)) return value[0] ?? null;
+	return value ?? null;
+}
 const STANDARD_WEBHOOKS_HEADER_NAMES = [
 	"webhook-signature",
 	"webhook-id",
@@ -10160,7 +10260,7 @@ function getStandardWebhooksHeaders(headers) {
 * });
 * ```
 */
-function handleWebhook(options) {
+function verifyWebhookRequest(options) {
 	const { body, headers, secret, toleranceSeconds } = options;
 	const swHeaders = getStandardWebhooksHeaders(headers);
 	if (swHeaders) verifyStandardWebhooksSignature({
@@ -10177,7 +10277,36 @@ function handleWebhook(options) {
 		secret,
 		toleranceSeconds
 	});
-	return validateEmailReceivedEvent(parseJsonBody(body));
+}
+/**
+* Verify, then parse any webhook event into a typed value.
+*
+* Unlike {@link handleWebhook}, this returns the full {@link WebhookEvent}
+* union, so it handles `payment.*` and `interaction.x402.*` events in addition
+* to `email.*`. The flow is:
+*
+* 1. Verify the signature over the RAW body (works for every event family).
+* 2. Parse the JSON body.
+* 3. Classify on the `X-Webhook-Event` HEADER (the primary discriminator),
+*    returning a typed event for known types and an UnknownEvent for the rest.
+*
+* @example
+* ```typescript
+* const event = handleWebhookEvent({ body, headers, secret });
+* if (isPaymentSettledEvent(event)) {
+*   // typed PaymentSettledEvent
+* } else if (isInteractionX402Event(event)) {
+*   // typed interaction.x402.* event
+* }
+* ```
+*/
+function handleWebhookEvent(options) {
+	verifyWebhookRequest(options);
+	return parseWebhookEvent(parseJsonBody(options.body), getEventHeader(options.headers));
+}
+function handleWebhook(options) {
+	verifyWebhookRequest(options);
+	return validateEmailReceivedEvent(parseJsonBody(options.body));
 }
 function receive(input, options) {
 	if (input instanceof Request) return receiveFromRequest(input, options);
@@ -10364,4 +10493,4 @@ function verifyRawEmailDownload(downloaded, event) {
 	return buffer;
 }
 //#endregion
-export { PRIMITIVE_CONFIRMED_HEADER as A, STANDARD_WEBHOOK_ID_HEADER as C, verifyStandardWebhooksSignature as D, signStandardWebhooksPayload as E, verifyDownloadToken as F, safeValidateEmailReceivedEvent as I, validateEmailReceivedEvent as L, signWebhookPayload as M, verifyWebhookSignature as N, LEGACY_CONFIRMED_HEADER as O, generateDownloadToken as P, emailReceivedEventJsonSchema as S, STANDARD_WEBHOOK_TIMESTAMP_HEADER as T, DmarcResult as _, isDownloadExpired as a, ParsedStatus as b, parseWebhookEvent as c, WEBHOOK_VERSION as d, validateEmailAuth as f, DmarcPolicy as g, DkimResult as h, handleWebhook as i, PRIMITIVE_SIGNATURE_HEADER as j, LEGACY_SIGNATURE_HEADER as k, receive as l, AuthVerdict as m, decodeRawEmail as n, isEmailReceivedEvent as o, AuthConfidence as p, getDownloadTimeRemaining as r, isRawIncluded as s, confirmedHeaders as t, verifyRawEmailDownload as u, EventType as v, STANDARD_WEBHOOK_SIGNATURE_HEADER as w, SpfResult as x, ForwardVerdict as y };
+export { LEGACY_CONFIRMED_HEADER as A, isEmailReceivedEvent as B, SpfResult as C, STANDARD_WEBHOOK_TIMESTAMP_HEADER as D, STANDARD_WEBHOOK_SIGNATURE_HEADER as E, verifyWebhookSignature as F, isPaymentSettledEvent as G, isKnownWebhookEventType as H, EMAIL_EVENT_TYPES as I, safeValidateEmailReceivedEvent as J, generateDownloadToken as K, INTERACTION_EVENT_TYPES as L, PRIMITIVE_CONFIRMED_HEADER as M, PRIMITIVE_SIGNATURE_HEADER as N, signStandardWebhooksPayload as O, signWebhookPayload as P, PAYMENT_EVENT_TYPES as R, ParsedStatus as S, STANDARD_WEBHOOK_ID_HEADER as T, isPaymentEvent as U, isInteractionX402Event as V, isPaymentFailedEvent as W, validateEmailReceivedEvent as Y, DkimResult as _, getEventHeader as a, EventType as b, isDownloadExpired as c, receive as d, verifyRawEmailDownload as f, AuthVerdict as g, AuthConfidence as h, getDownloadTimeRemaining as i, LEGACY_SIGNATURE_HEADER as j, verifyStandardWebhooksSignature as k, isRawIncluded as l, validateEmailAuth as m, confirmedHeaders as n, handleWebhook as o, WEBHOOK_VERSION as p, verifyDownloadToken as q, decodeRawEmail as r, handleWebhookEvent as s, WEBHOOK_EVENT_HEADER as t, parseWebhookEvent as u, DmarcPolicy as v, emailReceivedEventJsonSchema as w, ForwardVerdict as x, DmarcResult as y, WEBHOOK_EVENT_TYPES as z };

package/dist/x402/index.d.ts

@@ -130,6 +130,62 @@ interface X402PaymentPayload {
     };
   };
 }
+/**
+ * The protocol the email-native payment interaction runs (`x402.payment/1`).
+ * The payer's reply carries the `payment` step of this protocol.
+ */
+declare const X402_INTERACTION_PROTOCOL = "x402.payment";
+declare const X402_INTERACTION_PROTOCOL_VERSION = 1;
+/**
+ * The interaction.json envelope for one step of an email-carried interaction.
+ * The payer's `payment` step is sent as an `interaction.json` MIME attachment
+ * in the reply; the platform parses this envelope, validates the step against
+ * the `x402.payment` protocol, and re-verifies the embedded payment.
+ */
+interface InteractionEnvelope<P = unknown> {
+  interaction_version: 1;
+  /** The thread id (`uuid@domain`) the step belongs to. */
+  interaction_id: string;
+  protocol: string;
+  protocol_version: number;
+  /** The protocol step name (e.g. `"payment"`). */
+  step: string;
+  /** This step's id (a fresh UUID). */
+  step_id: string;
+  /** The id of the step this one answers (the challenge step), or null. */
+  prev_step_id: string | null;
+  expires_at: string | null;
+  payload: P;
+}
+/** The `payload` of an `x402.payment` `payment` step: the signed x402 payload. */
+interface X402PaymentStepPayload {
+  payment: X402PaymentPayload;
+}
+/**
+ * A built, signed payment-step envelope plus its canonical JSON bytes. The
+ * caller attaches `json` as the `interaction.json` part of the reply email; the
+ * platform reads `envelope` back from those exact bytes.
+ */
+interface BuiltPaymentStep {
+  envelope: InteractionEnvelope<X402PaymentStepPayload>;
+  /** The canonical interaction.json body (what to attach to the reply). */
+  json: string;
+}
+/**
+ * Build the section-2.3 interaction.json envelope for a `payment` step. Pure: no
+ * I/O. `payment` is the signed exact-EVM payload (from
+ * `buildExactEvmPaymentPayload`); `prevStepId` is the challenge step id this
+ * payment answers, and `stepId` is a fresh UUID for the payment step. Returns
+ * the envelope and its canonical JSON, so the bytes the platform reads back are
+ * exactly the ones produced here.
+ */
+declare function buildPaymentStepEnvelope(params: {
+  /** The thread id (`uuid@domain`). */interactionId: string; /** A fresh UUID identifying this payment step. */
+  stepId: string; /** The challenge step id this payment answers. */
+  prevStepId: string;
+  payment: X402PaymentPayload; /** Optional ISO-8601 step expiry. */
+  expiresAt?: string | null;
+}): BuiltPaymentStep;
 /** Assemble the wire payload from a signed authorization. */
 declare function toPaymentPayload(network: string, auth: TransferAuthorization, signature: Hex): X402PaymentPayload;
 /**
@@ -218,6 +274,33 @@ interface X402Challenge {
   payment_requirements: X402PaymentRequirements;
   expires_at: string;
 }
+/** The nonce binding the payer hashes into the EIP-3009 nonce. */
+interface X402NonceBinding {
+  interaction_id: string;
+  challenge_step_id: string;
+  challenge_nonce: string;
+}
+/**
+ * The challenge details carried inside an email-native challenge: what the
+ * payer needs to sign and pay. Distinct from the synthetic `X402Challenge` in
+ * that it has no top-level `id`/`amount`; everything is in the nested objects.
+ */
+interface X402EmailChallengeDetails {
+  payment_requirements: X402PaymentRequirements;
+  nonce_binding: X402NonceBinding;
+  expires_at: string;
+}
+/**
+ * The result of issuing an email-native challenge (`createEmailChallenge`).
+ * `interaction_id` is the real email thread id (`uuid@domain`) the payment is
+ * bound to. Hand the whole object to the payer; the payer calls
+ * `payEmailChallenge` with it to build the signed payment step.
+ */
+interface X402EmailChallenge {
+  interaction_id: string;
+  challenge_id: string;
+  challenge: X402EmailChallengeDetails;
+}
 interface X402Receipt {
   id: string;
   status: string;
@@ -279,6 +362,34 @@ interface X402ChargeInput {
    */
   idempotencyKey?: string;
 }
+interface X402EmailChargeInput {
+  /** Your sending address (the payee / funds receiver). */
+  from: string;
+  /** The payer's email address the challenge is sent to. */
+  to: string;
+  /**
+   * Amount in token base units (USDC has 6 decimals, so "10000" = 0.01).
+   * Provide exactly one of `amount` or `amountUsdc`.
+   */
+  amount?: string;
+  /**
+   * Amount as human USDC (e.g. "0.01"), converted to base units for you.
+   * Provide exactly one of `amount` or `amountUsdc`.
+   */
+  amountUsdc?: string;
+  /** Defaults to "base-sepolia". */
+  network?: string;
+  description?: string;
+  /** A URL identifying the thing being paid for. */
+  resource?: string;
+  /** Seconds until the challenge expires (default 1h). */
+  expiresIn?: number;
+  /**
+   * Optional idempotency key. Retrying `createEmailChallenge()` with the same
+   * key returns the original challenge without sending a second email.
+   */
+  idempotencyKey?: string;
+}
 declare class X402Error extends Error {
   /** HTTP status, or 0 for a client-side / transport error that never reached the server. */
   readonly status: number;
@@ -305,6 +416,30 @@ declare class X402Client {
   constructor(options?: X402ClientOptions);
   /** Request a payment (payee side). Returns the challenge to hand to the payer. */
   charge(input: X402ChargeInput): Promise<X402Challenge>;
+  /**
+   * Issue a payment challenge over an email thread (payee side). Sends the
+   * challenge as an email from `from` to `to` and binds the payment to that
+   * thread. Returns the challenge (including the real `interaction_id`); deliver
+   * it to the payer, who calls `payEmailChallenge` to build the signed payment.
+   *
+   * Provide exactly one of `amount` (base units) or `amountUsdc` (human USDC).
+   */
+  createEmailChallenge(input: X402EmailChargeInput): Promise<X402EmailChallenge>;
+  /**
+   * Build the signed payment step for an email-native challenge (payer side).
+   * Given a received `X402EmailChallenge` and the caller's signer, this derives
+   * the interaction-bound authorization, signs it locally, and returns the
+   * signed `interaction.json` payment-step envelope plus its canonical JSON
+   * bytes. It does NOT send anything.
+   *
+   * The caller sends `result.json` back as an `interaction.json` attachment on a
+   * reply to the challenge email (e.g. via the SDK's `send` / `reply`); the
+   * platform reads the envelope from those exact bytes, re-derives the bound
+   * nonce, and settles.
+   */
+  payEmailChallenge(challenge: X402EmailChallenge, options: {
+    signer: X402Signer;
+  }): Promise<BuiltPaymentStep>;
   /**
    * Pay a challenge (payer side). Derives the interaction-bound authorization,
    * signs it locally with the caller's key, and submits it for settlement.
@@ -351,4 +486,4 @@ declare class X402Client {
 }
 declare function createX402Client(options?: X402ClientOptions): X402Client;
 //#endregion
-export { DEFAULT_MAX_WINDOW_SEC, NonceBinding, PayoutRegistrationMessageInput, TRANSFER_WITH_AUTHORIZATION_TYPES, TokenDomain, TransferAuthorization, TransferWithAuthorizationTypedData, X402Challenge, X402ChargeInput, X402Client, X402ClientOptions, X402DeclinedPayment, X402Error, X402Network, X402PaymentPayload, X402PaymentRequirements, X402PayoutAddress, X402Receipt, X402Signer, X402SpendPolicy, buildExactEvmPaymentPayload, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };
+export { BuiltPaymentStep, DEFAULT_MAX_WINDOW_SEC, InteractionEnvelope, NonceBinding, PayoutRegistrationMessageInput, TRANSFER_WITH_AUTHORIZATION_TYPES, TokenDomain, TransferAuthorization, TransferWithAuthorizationTypedData, X402Challenge, X402ChargeInput, X402Client, X402ClientOptions, X402DeclinedPayment, X402EmailChallenge, X402EmailChallengeDetails, X402EmailChargeInput, X402Error, X402Network, X402NonceBinding, X402PaymentPayload, X402PaymentRequirements, X402PaymentStepPayload, X402PayoutAddress, X402Receipt, X402Signer, X402SpendPolicy, X402_INTERACTION_PROTOCOL, X402_INTERACTION_PROTOCOL_VERSION, buildExactEvmPaymentPayload, buildPaymentStepEnvelope, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };

package/dist/x402/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser runtime modules.",
   "type": "module",
   "module": "./dist/index.js",