@primitivedotdev/sdk 1.5.0 → 1.7.0

package/dist/x402/index.d.ts

@@ -132,6 +132,65 @@ interface X402PaymentPayload {
 }
 /** 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 {
@@ -184,9 +243,27 @@ interface X402SpendPolicy {
   /** Allowed payee org ids; null = any on-net payee, [] = deny all. */
   allowlist: string[] | null;
 }
-interface X402ChargeInput {
-  /** Amount in token base units (USDC has 6 decimals, so "10000" = 0.01). */
+/** A payment the org's spend policy refused (read shape). */
+interface X402DeclinedPayment {
+  id: string;
+  challenge_id: string | null;
+  counterparty_org: string | null;
+  network: string;
   amount: string;
+  reason: string;
+  declined_at: string;
+}
+interface X402ChargeInput {
+  /**
+   * 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;
   /** The org id allowed to pay this challenge (on-net binding). */
@@ -196,6 +273,11 @@ interface X402ChargeInput {
   resource?: string;
   /** Seconds until the challenge expires (default 1h). */
   expiresIn?: number;
+  /**
+   * Optional idempotency key. Retrying `charge()` with the same key returns the
+   * original challenge instead of creating a duplicate.
+   */
+  idempotencyKey?: string;
 }
 declare class X402Error extends Error {
   /** HTTP status, or 0 for a client-side / transport error that never reached the server. */
@@ -238,16 +320,25 @@ declare class X402Client {
    * address becomes (or updates to) the default payout destination for the
    * network. `charge()` resolves its `pay_to` from this directory, so a payee
    * must register before requesting payments.
+   *
+   * `org` is optional: when omitted it is resolved from your authenticated
+   * account, so most callers never need to supply it.
    */
   registerPayoutAddress(input: {
-    org: string;
+    org?: string;
     network?: string;
     issuedAt?: string;
+    label?: string;
   }, options: {
     signer: X402Signer;
   }): Promise<X402PayoutAddress>;
   /** List your org's registered payout addresses. */
   listPayoutAddresses(): Promise<X402PayoutAddress[]>;
+  /**
+   * List the most recent payments your org's spend policy declined (newest
+   * first). Use this to see why an outbound payment was refused.
+   */
+  listDeclinedPayments(): Promise<X402DeclinedPayment[]>;
   /** Read your org's spend policy (kill-switch + caps + allowlist). */
   getSpendPolicy(): Promise<X402SpendPolicy>;
   /**
@@ -260,4 +351,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, X402Error, X402PaymentPayload, X402PaymentRequirements, X402PayoutAddress, X402Receipt, X402Signer, X402SpendPolicy, buildPayoutRegistrationMessage, createX402Client, deriveEip3009Nonce, toPaymentPayload, transferWithAuthorizationTypedData };
+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 };

package/dist/x402/index.js

@@ -1,4 +1,4 @@
-import { concat, hexToBytes, keccak256, stringToBytes } from "viem";
+import { concat, getAddress, hexToBytes, keccak256, stringToBytes } from "viem";
 //#region src/x402/sign.ts
 /**
 * x402 client-side signing.
@@ -116,23 +116,97 @@ function toPaymentPayload(network, auth, signature) {
 		}
 	};
 }
+/**
+* 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.
+*/
+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.
+*/
+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?)`);
+	return {
+		validAfter,
+		validBefore
+	};
+}
+/**
+* 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.
+*/
+async function signInteractionPayment(params) {
+	const authorization = {
+		from: getAddress(params.payer),
+		to: getAddress(params.payTo),
+		value: params.amount,
+		validAfter: params.validAfter,
+		validBefore: params.validBefore,
+		nonce: deriveEip3009Nonce(params.nonceBinding)
+	};
+	return {
+		authorization,
+		signature: await params.sign(transferWithAuthorizationTypedData(params.domain, authorization))
+	};
+}
+/** The authorization nonce is 32 bytes rendered as a 0x-prefixed 64-char hex string. */
+const NONCE_HEX_RE = /^0x[0-9a-fA-F]{64}$/;
+/** A shape-valid EIP signature is 65 bytes (r,s,v) rendered as 130 hex chars. */
+const SIGNATURE_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
+/**
+* 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.
+*/
+function buildExactEvmPaymentPayload(params) {
+	if (params.network !== "base" && params.network !== "base-sepolia") throw new Error(`buildExactEvmPaymentPayload: unsupported network ${params.network}`);
+	if (!SIGNATURE_HEX_RE.test(params.signature)) throw new Error("buildExactEvmPaymentPayload: signature must be a 0x-prefixed 65-byte (130 hex char) EIP signature");
+	if (!NONCE_HEX_RE.test(params.authorization.nonce)) throw new Error("buildExactEvmPaymentPayload: authorization.nonce must be a 0x-prefixed 32-byte (64 hex char) value");
+	return toPaymentPayload(params.network, params.authorization, params.signature);
+}
 //#endregion
 //#region src/x402/client.ts
 const CHAIN_IDS = {
 	"base-sepolia": 84532,
 	base: 8453
 };
-const CLOCK_SKEW_SEC = 300;
-const SETTLEMENT_MARGIN_SEC = 300;
 const DEFAULT_BASE_URL = "https://api.primitive.dev";
 const CHARGE_INPUT_KEYS = {
 	amount: true,
+	amountUsdc: true,
 	network: true,
 	payerOrg: true,
 	description: true,
 	resource: true,
-	expiresIn: true
+	expiresIn: true,
+	idempotencyKey: true
 };
+function usdcToBaseUnits(human) {
+	const trimmed = human.trim();
+	if (!/^\d+(\.\d+)?$/.test(trimmed)) return null;
+	const [whole, frac = ""] = trimmed.split(".");
+	if (frac.length > 6) return null;
+	const base = BigInt(whole) * 1000000n + BigInt(frac.padEnd(6, "0"));
+	return base > 0n ? base.toString() : null;
+}
 var X402Error = class extends Error {
 	/** HTTP status, or 0 for a client-side / transport error that never reached the server. */
 	status;
@@ -163,7 +237,7 @@ function validateChallenge(c) {
 	if (!nb?.interaction_id || !nb.challenge_step_id || !nb.challenge_nonce) bad("nonce_binding");
 	const pr = c.payment_requirements;
 	if (!pr) bad("payment_requirements");
-	if (!pr.maxAmountRequired) bad("payment_requirements.maxAmountRequired");
+	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)");
@@ -189,7 +263,8 @@ var X402Client = class {
 				method,
 				headers: {
 					authorization: `Bearer ${this.#apiKey}`,
-					"content-type": "application/json"
+					"content-type": "application/json",
+					...init?.headers
 				},
 				body: body === void 0 ? void 0 : JSON.stringify(body),
 				signal
@@ -212,16 +287,18 @@ var X402Client = class {
 	/** Request a payment (payee side). Returns the challenge to hand to the payer. */
 	async charge(input) {
 		for (const key of Object.keys(input)) if (!(key in CHARGE_INPUT_KEYS)) throw new X402Error(`unknown charge() option "${key}"; expected one of: ${Object.keys(CHARGE_INPUT_KEYS).join(", ")}`, 0);
-		if (!input.amount || !/^[1-9][0-9]{0,38}$/.test(input.amount)) throw new X402Error("charge() requires `amount` as a positive integer string in token base units, e.g. \"10000\"", 0);
+		if (input.amount !== void 0 && input.amountUsdc !== void 0) throw new X402Error("charge() 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("charge() 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 = {
-			amount: input.amount,
+			amount,
 			network: input.network ?? "base-sepolia"
 		};
 		if (input.payerOrg) body.payer_org = input.payerOrg;
 		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/challenges", body);
+		return this.#request("POST", "/v1/x402/challenges", body, { headers: input.idempotencyKey ? { "idempotency-key": input.idempotencyKey } : void 0 });
 	}
 	/**
 	* Pay a challenge (payer side). Derives the interaction-bound authorization,
@@ -235,54 +312,75 @@ var X402Client = class {
 		const pr = challenge.payment_requirements;
 		if (pr.network !== challenge.network) throw new X402Error(`challenge network mismatch: ${challenge.network} vs payment_requirements ${pr.network}`, 0);
 		if (pr.scheme !== "exact") throw new X402Error(`unsupported payment scheme: ${pr.scheme}`, 0);
-		const nonce = deriveEip3009Nonce({
-			interactionId: challenge.nonce_binding.interaction_id,
-			challengeStepId: challenge.nonce_binding.challenge_step_id,
-			challengeNonce: challenge.nonce_binding.challenge_nonce
-		});
 		const nowSec = Math.floor(Date.now() / 1e3);
 		const expiresAtMs = Date.parse(challenge.expires_at);
 		if (Number.isNaN(expiresAtMs)) throw new X402Error(`challenge has an invalid expires_at: ${challenge.expires_at}`, 0);
 		const expiresAtSec = Math.floor(expiresAtMs / 1e3);
 		if (expiresAtSec <= nowSec) throw new X402Error(`challenge has already expired (expires_at ${challenge.expires_at}); not signing`, 0);
-		const validAfter = BigInt(nowSec - CLOCK_SKEW_SEC);
-		const validBefore = BigInt(expiresAtSec + SETTLEMENT_MARGIN_SEC);
-		const auth = {
-			from: options.signer.address,
-			to: pr.payTo,
-			value: BigInt(pr.maxAmountRequired),
+		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: challenge.nonce_binding.interaction_id,
+				challengeStepId: challenge.nonce_binding.challenge_step_id,
+				challengeNonce: challenge.nonce_binding.challenge_nonce
+			},
 			validAfter,
-			validBefore,
-			nonce
-		};
-		const signature = await options.signer.signTypedData(transferWithAuthorizationTypedData({
-			name: pr.extra.name,
-			version: pr.extra.version,
-			chainId,
-			verifyingContract: pr.asset
-		}, auth));
-		return this.#request("POST", `/v1/x402/challenges/${challenge.id}/pay`, { payment: toPaymentPayload(challenge.network, auth, signature) });
+			validBefore
+		});
+		return this.#request("POST", `/v1/x402/challenges/${challenge.id}/pay`, { payment: buildExactEvmPaymentPayload({
+			network: challenge.network,
+			authorization,
+			signature
+		}) });
 	}
 	/** Fetch a challenge by id (scoped to the challenger org that created it). */
 	async getChallenge(id) {
 		if (!id) throw new X402Error("getChallenge() requires a challenge id", 0);
 		return this.#request("GET", `/v1/x402/challenges/${encodeURIComponent(id)}`);
 	}
+	/** Resolve the caller's own organization id from the account endpoint. */
+	async #resolveOrgId() {
+		const account = await this.#request("GET", "/v1/account");
+		if (!account?.id) throw new X402Error("could not resolve your organization id from /v1/account; pass { org } explicitly", 0);
+		return account.id;
+	}
 	/**
 	* Register a payout address for your org (payee side). The signer proves
 	* control of its own address with an org-bound `personal_sign`; the proven
 	* address becomes (or updates to) the default payout destination for the
 	* network. `charge()` resolves its `pay_to` from this directory, so a payee
 	* must register before requesting payments.
+	*
+	* `org` is optional: when omitted it is resolved from your authenticated
+	* account, so most callers never need to supply it.
 	*/
 	async registerPayoutAddress(input, options) {
-		if (!input?.org) throw new X402Error("registerPayoutAddress() requires an org id", 0);
 		if (typeof options?.signer?.signMessage !== "function") throw new X402Error("registerPayoutAddress() requires a signer with signMessage (e.g. a viem LocalAccount)", 0);
+		const org = input.org ?? await this.#resolveOrgId();
 		const network = input.network ?? "base-sepolia";
 		const issuedAt = input.issuedAt ?? (/* @__PURE__ */ new Date()).toISOString();
 		const address = options.signer.address;
 		const message = buildPayoutRegistrationMessage({
-			org: input.org,
+			org,
 			address,
 			network,
 			issuedAt
@@ -292,13 +390,21 @@ var X402Client = class {
 			address,
 			network,
 			signature,
-			issued_at: issuedAt
+			issued_at: issuedAt,
+			...input.label !== void 0 ? { label: input.label } : {}
 		});
 	}
 	/** List your org's registered payout addresses. */
 	async listPayoutAddresses() {
 		return this.#request("GET", "/v1/x402/payout-addresses");
 	}
+	/**
+	* List the most recent payments your org's spend policy declined (newest
+	* first). Use this to see why an outbound payment was refused.
+	*/
+	async listDeclinedPayments() {
+		return this.#request("GET", "/v1/x402/declined-payments");
+	}
 	/** Read your org's spend policy (kill-switch + caps + allowlist). */
 	async getSpendPolicy() {
 		return this.#request("GET", "/v1/x402/spend-policy");
@@ -317,4 +423,4 @@ function createX402Client(options = {}) {
 	return new X402Client(options);
 }
 //#endregion
-export { TRANSFER_WITH_AUTHORIZATION_TYPES, X402Client, X402Error, buildPayoutRegistrationMessage, createX402Client, deriveEip3009Nonce, toPaymentPayload, transferWithAuthorizationTypedData };
+export { DEFAULT_MAX_WINDOW_SEC, TRANSFER_WITH_AUTHORIZATION_TYPES, X402Client, X402Error, buildExactEvmPaymentPayload, buildPayoutRegistrationMessage, computePaymentValidityWindow, createX402Client, deriveEip3009Nonce, signInteractionPayment, toPaymentPayload, transferWithAuthorizationTypedData };

package/package.json

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