@primitivedotdev/sdk 1.10.0 → 1.12.0

package/dist/x402/index.d.ts

@@ -197,12 +197,32 @@ declare function toPaymentPayload(network: string, auth: TransferAuthorization,
  */
 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.
+ * Minimum headroom between now and `validBefore`. The platform rejects a
+ * payment whose authorization is about to expire (it needs SMTP + DKIM + verify
+ * + settle latency to clear), so a `validBefore` less than this far in the
+ * future is a guaranteed-to-fail signature. The default window is minutes; this
+ * 60s floor is the absolute minimum the band tolerates.
+ */
+declare const DEFAULT_MIN_SETTLEMENT_HEADROOM_SEC = 60;
+/**
+ * Compute the EIP-3009 validity window for a payment, landing inside the band
+ * the platform accepts. `validBefore` governs on-chain validity, so it MUST
+ * stay far enough in the future to settle (>= `minHeadroomSec`) yet not so far
+ * that the total window exceeds the `maxWindowSec` cap; `validAfter` is set
+ * generously in the past for clock skew.
+ *
+ * Both ends of that band are payer landmines: a too-tight `validBefore` (low
+ * headroom, e.g. a near-expired challenge) is rejected for being about to
+ * expire, and a too-wide window (far-future expiry) is rejected as
+ * "authorization window too wide". By default this clamps the computed window
+ * into the band so a caller who does not override always gets a signable
+ * window.
+ *
+ * If the caller passes an explicit `validBeforeSec` or `validAfterSec`, that is
+ * an intent to pin the bound: when it falls outside the band this throws a
+ * specific error naming which bound was violated (rather than silently signing
+ * a doomed authorization), unless `clamp` is left enabled, in which case the
+ * pinned value is clamped into the band like the computed one.
  */
 declare function computePaymentValidityWindow(params: {
   /** The challenge's expires_at, unix seconds. */challengeExpiresAtSec: number; /** Current time, unix seconds. */
@@ -210,6 +230,27 @@ declare function computePaymentValidityWindow(params: {
   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;
+  /**
+   * Minimum `validBefore - nowSec`. Default 60s. A signature with less headroom
+   * cannot clear the SMTP+DKIM+settle latency and the platform rejects it.
+   */
+  minHeadroomSec?: number;
+  /**
+   * Explicit override for `validBefore` (unix seconds). When omitted it is
+   * derived from `challengeExpiresAtSec + settlementMarginSec`.
+   */
+  validBeforeSec?: number;
+  /**
+   * Explicit override for `validAfter` (unix seconds). When omitted it is
+   * derived from `nowSec - clockSkewSec`.
+   */
+  validAfterSec?: number;
+  /**
+   * When true (the default), an out-of-band window is clamped into the accepted
+   * band instead of throwing. Set `false` to reject a caller-pinned override
+   * that is out of band with a specific error rather than silently moving it.
+   */
+  clamp?: boolean;
 }): {
   validAfter: bigint;
   validBefore: bigint;
@@ -401,6 +442,27 @@ declare class X402Error extends Error {
     retryAfter?: string | null;
   });
 }
+/**
+ * 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).
+ */
+declare function parseEmailChallengeFromPart(part: string | Uint8Array | Record<string, unknown>): X402EmailChallenge;
 interface X402ClientOptions {
   /** API key. Defaults to `process.env.PRIMITIVE_API_KEY`. */
   apiKey?: string;
@@ -486,4 +548,4 @@ declare class X402Client {
 }
 declare function createX402Client(options?: X402ClientOptions): X402Client;
 //#endregion
-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 };
+export { BuiltPaymentStep, DEFAULT_MAX_WINDOW_SEC, DEFAULT_MIN_SETTLEMENT_HEADROOM_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, parseEmailChallengeFromPart, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };

package/dist/x402/index.js

@@ -164,24 +164,55 @@ function toPaymentPayload(network, auth, signature) {
 */
 const DEFAULT_MAX_WINDOW_SEC = 1440 * 60;
 /**
-* 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.
+* Minimum headroom between now and `validBefore`. The platform rejects a
+* payment whose authorization is about to expire (it needs SMTP + DKIM + verify
+* + settle latency to clear), so a `validBefore` less than this far in the
+* future is a guaranteed-to-fail signature. The default window is minutes; this
+* 60s floor is the absolute minimum the band tolerates.
+*/
+const DEFAULT_MIN_SETTLEMENT_HEADROOM_SEC = 60;
+/**
+* Compute the EIP-3009 validity window for a payment, landing inside the band
+* the platform accepts. `validBefore` governs on-chain validity, so it MUST
+* stay far enough in the future to settle (>= `minHeadroomSec`) yet not so far
+* that the total window exceeds the `maxWindowSec` cap; `validAfter` is set
+* generously in the past for clock skew.
+*
+* Both ends of that band are payer landmines: a too-tight `validBefore` (low
+* headroom, e.g. a near-expired challenge) is rejected for being about to
+* expire, and a too-wide window (far-future expiry) is rejected as
+* "authorization window too wide". By default this clamps the computed window
+* into the band so a caller who does not override always gets a signable
+* window.
+*
+* If the caller passes an explicit `validBeforeSec` or `validAfterSec`, that is
+* an intent to pin the bound: when it falls outside the band this throws a
+* specific error naming which bound was violated (rather than silently signing
+* a doomed authorization), unless `clamp` is left enabled, in which case the
+* pinned value is clamped into the band like the computed one.
 */
 function computePaymentValidityWindow(params) {
 	const margin = params.settlementMarginSec ?? 300;
 	const skew = params.clockSkewSec ?? 300;
-	const validBefore = BigInt(params.challengeExpiresAtSec + margin);
-	const validAfter = BigInt(params.nowSec - skew);
-	if (validBefore <= validAfter) throw new Error("invalid validity window: validBefore must be after validAfter (challenge already expired?)");
-	const maxWindow = BigInt(params.maxWindowSec ?? 86400);
-	if (validBefore - validAfter > maxWindow) throw new Error(`invalid validity window: total window exceeds the ${maxWindow}s cap (challenge expiry too far out?)`);
+	const maxWindow = params.maxWindowSec ?? 86400;
+	const minHeadroom = params.minHeadroomSec ?? 60;
+	const clamp = params.clamp ?? true;
+	if (maxWindow < minHeadroom) throw new Error(`invalid validity window config: maxWindowSec (${maxWindow}) is smaller than minHeadroomSec (${minHeadroom})`);
+	const validAfter = params.validAfterSec !== void 0 ? params.validAfterSec : params.nowSec - skew;
+	const rawValidBefore = params.validBeforeSec !== void 0 ? params.validBeforeSec : params.challengeExpiresAtSec + margin;
+	const floor = params.nowSec + minHeadroom;
+	const ceiling = validAfter + maxWindow;
+	const tooTight = rawValidBefore < floor;
+	const tooWide = rawValidBefore > ceiling;
+	if (!clamp && params.validBeforeSec !== void 0) {
+		if (tooTight) throw new Error(`invalid validity window: validBefore (${rawValidBefore}) is below the minimum settlement headroom (must be >= now + ${minHeadroom}s = ${floor}); the authorization would be rejected as about to expire`);
+		if (tooWide) throw new Error(`invalid validity window: validBefore (${rawValidBefore}) exceeds the ${maxWindow}s window cap (must be <= validAfter + ${maxWindow}s = ${ceiling}); the authorization window is too wide`);
+	}
+	const bandedValidBefore = tooTight ? floor : tooWide ? ceiling : rawValidBefore;
+	if (bandedValidBefore <= validAfter) throw new Error("invalid validity window: validBefore must be after validAfter (challenge already expired or validAfter pinned too late?)");
 	return {
-		validAfter,
-		validBefore
+		validAfter: BigInt(validAfter),
+		validBefore: BigInt(bandedValidBefore)
 	};
 }
 /**
@@ -280,6 +311,80 @@ var X402Error = class extends Error {
 		this.retryAfter = options?.retryAfter ?? null;
 	}
 };
+/** 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.
@@ -599,4 +704,4 @@ function createX402Client(options = {}) {
 	return new X402Client(options);
 }
 //#endregion
-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 };
+export { DEFAULT_MAX_WINDOW_SEC, DEFAULT_MIN_SETTLEMENT_HEADROOM_SEC, TRANSFER_WITH_AUTHORIZATION_TYPES, X402Client, X402Error, X402_INTERACTION_PROTOCOL, X402_INTERACTION_PROTOCOL_VERSION, buildExactEvmPaymentPayload, buildPaymentStepEnvelope, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, parseEmailChallengeFromPart, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };

package/package.json

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