@primitivedotdev/sdk 1.6.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,8 +130,123 @@ 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;
+/**
+ * Absolute ceiling on the total signed window (validBefore - validAfter). A
+ * signed EIP-3009 authorization stays settleable on-chain until validBefore
+ * regardless of the interaction state, so an unbounded window is a standing
+ * "funds committed" risk. The real window is minutes; this 24h cap is the hard
+ * safety ceiling, enforced so a caller-supplied window cannot bypass it.
+ */
+declare const DEFAULT_MAX_WINDOW_SEC: number;
+/**
+ * Compute the EIP-3009 validity window for a payment. `validBefore` is the
+ * value that governs on-chain validity, so it MUST cover the challenge's
+ * `expires_at` plus a settlement margin; `validAfter` is set generously in the
+ * past for clock skew. The total window is hard-capped at `maxWindowSec` so
+ * neither a far-future `challengeExpiresAtSec` nor a widened margin can produce
+ * a window the platform verifier would later reject.
+ */
+declare function computePaymentValidityWindow(params: {
+  /** The challenge's expires_at, unix seconds. */challengeExpiresAtSec: number; /** Current time, unix seconds. */
+  nowSec: number; /** Headroom past expiry for verify+settle to complete. Default 5 min. */
+  settlementMarginSec?: number; /** How far in the past to set validAfter for clock skew. Default 5 min. */
+  clockSkewSec?: number; /** Hard ceiling on validBefore - validAfter. Default 24h. */
+  maxWindowSec?: number;
+}): {
+  validAfter: bigint;
+  validBefore: bigint;
+};
+/** The x402 named networks supported in v1 (testnet first). */
+type X402Network = "base-sepolia" | "base";
+/**
+ * The interaction-aware signer: derive the bound nonce, assemble the
+ * authorization, and sign it. This is the one piece a stock x402 signer cannot
+ * do (it generates the nonce internally with no injection point), so the payer
+ * side needs this Primitive-provided helper. The key never leaves the caller.
+ */
+declare function signInteractionPayment(params: {
+  /** Sign EIP-712 typed data with the caller's own key. */sign: (typedData: TransferWithAuthorizationTypedData) => Promise<Hex>; /** Payer (from) address. */
+  payer: Address;
+  domain: TokenDomain; /** Recipient (the challenger's payTo). */
+  payTo: Address; /** Amount in token base units. */
+  amount: bigint; /** Inputs that derive the interaction-bound EIP-3009 nonce. */
+  nonceBinding: NonceBinding;
+  validAfter: bigint;
+  validBefore: bigint;
+}): Promise<{
+  authorization: TransferAuthorization;
+  signature: Hex;
+}>;
+/**
+ * Assemble (and validate) the exact-EVM x402 wire payload from an
+ * interaction-bound, locally-signed authorization. The numeric authorization
+ * fields are decimal strings in the wire schema, so the bigints are stringified
+ * here; the nonce passes through as hex. Validation rejects a malformed nonce or
+ * signature loudly rather than emitting a payload the platform will reject.
+ */
+declare function buildExactEvmPaymentPayload(params: {
+  network: X402Network;
+  authorization: TransferAuthorization;
+  signature: Hex;
+}): X402PaymentPayload;
 //#endregion
 //#region src/x402/client.d.ts
 interface X402PaymentRequirements {
@@ -159,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;
@@ -220,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;
@@ -246,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.
@@ -292,4 +486,4 @@ declare class X402Client {
 }
 declare function createX402Client(options?: X402ClientOptions): X402Client;
 //#endregion
-export { NonceBinding, PayoutRegistrationMessageInput, TRANSFER_WITH_AUTHORIZATION_TYPES, TokenDomain, TransferAuthorization, TransferWithAuthorizationTypedData, X402Challenge, X402ChargeInput, X402Client, X402ClientOptions, X402DeclinedPayment, X402Error, X402PaymentPayload, X402PaymentRequirements, X402PayoutAddress, X402Receipt, X402Signer, X402SpendPolicy, buildPayoutRegistrationMessage, createX402Client, deriveEip3009Nonce, 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 };