@primitivedotdev/sdk 1.22.1 → 1.24.0

package/dist/x402/index.d.ts

@@ -1,294 +1,5 @@
-import { Address, Hex } from "viem";
+import { C as toPaymentPayload, S as signInteractionPayment, _ as buildExactEvmPaymentPayload, a as NonceBinding, b as computePaymentValidityWindow, c as TokenDomain, d as X402Network, f as X402PaymentPayload, g as X402_INTERACTION_PROTOCOL_VERSION, h as X402_INTERACTION_PROTOCOL, i as InteractionEnvelope, l as TransferAuthorization, m as X402Signer, n as DEFAULT_MAX_WINDOW_SEC, o as PayoutRegistrationMessageInput, p as X402PaymentStepPayload, r as DEFAULT_MIN_SETTLEMENT_HEADROOM_SEC, s as TRANSFER_WITH_AUTHORIZATION_TYPES, t as BuiltPaymentStep, u as TransferWithAuthorizationTypedData, v as buildPaymentStepEnvelope, w as transferWithAuthorizationTypedData, x as deriveEip3009Nonce, y as buildPayoutRegistrationMessage } from "../sign-m3ZStnNw.js";
 
-//#region src/x402/sign.d.ts
-interface NonceBinding {
-  /** The interaction id, including its `@domain`. Lowercased before hashing. */
-  interactionId: string;
-  /** The challenge step id (a UUID). Lowercased before hashing. */
-  challengeStepId: string;
-  /** The challenger's per-challenge random nonce: 64 lowercase hex chars. */
-  challengeNonce: string;
-}
-/**
- * Derive the EIP-3009 nonce bound to a specific interaction step:
- *
- *   keccak256( utf8(lower(interaction_id)) || 0x00
- *            || utf8(lower(challenge_step_id)) || 0x00
- *            || hexdecode(challenge_nonce) )
- *
- * The `0x00` separators pin the field boundaries (undelimited concatenation of
- * variable-length strings is collision-ambiguous), and the challenge nonce is
- * decoded to its 32 raw bytes before hashing. The platform recomputes this and
- * rejects a mismatch.
- */
-declare function deriveEip3009Nonce(input: NonceBinding): Hex;
-/**
- * The EIP-3009 `TransferWithAuthorization` EIP-712 type. The field order and
- * types are part of the on-chain contract and MUST NOT change.
- */
-declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
-  readonly TransferWithAuthorization: readonly [{
-    readonly name: "from";
-    readonly type: "address";
-  }, {
-    readonly name: "to";
-    readonly type: "address";
-  }, {
-    readonly name: "value";
-    readonly type: "uint256";
-  }, {
-    readonly name: "validAfter";
-    readonly type: "uint256";
-  }, {
-    readonly name: "validBefore";
-    readonly type: "uint256";
-  }, {
-    readonly name: "nonce";
-    readonly type: "bytes32";
-  }];
-};
-/**
- * The token's EIP-712 domain. `name`/`version` MUST be the actual token's domain
- * params (Base mainnet USDC reports `name: "USD Coin"`, Base Sepolia `"USDC"`;
- * both `version: "2"`); they come from the challenge's payment requirements
- * `extra`. A wrong name/version produces a signature the verifier rejects.
- */
-interface TokenDomain {
-  name: string;
-  version: string;
-  chainId: number;
-  verifyingContract: Address;
-}
-interface TransferAuthorization {
-  from: Address;
-  to: Address;
-  /** Token base units (USDC has 6 decimals), as a bigint. */
-  value: bigint;
-  validAfter: bigint;
-  validBefore: bigint;
-  nonce: Hex;
-}
-interface TransferWithAuthorizationTypedData {
-  domain: {
-    name: string;
-    version: string;
-    chainId: number;
-    verifyingContract: Address;
-  };
-  types: typeof TRANSFER_WITH_AUTHORIZATION_TYPES;
-  primaryType: "TransferWithAuthorization";
-  message: TransferAuthorization;
-}
-declare function transferWithAuthorizationTypedData(domain: TokenDomain, auth: TransferAuthorization): TransferWithAuthorizationTypedData;
-/**
- * A customer-held signer. A viem `LocalAccount` satisfies this directly; any
- * key source (hardware wallet, injected provider) can be adapted. The key never
- * leaves the caller.
- */
-interface X402Signer {
-  address: Address;
-  signTypedData(typedData: TransferWithAuthorizationTypedData): Promise<Hex>;
-  /**
-   * `personal_sign` over a UTF-8 string. Only needed for
-   * `registerPayoutAddress()` (the ownership proof); a viem `LocalAccount`
-   * provides it directly.
-   */
-  signMessage?(args: {
-    message: string;
-  }): Promise<Hex>;
-}
-interface PayoutRegistrationMessageInput {
-  /** The org id the address is being authorized for. Bound into the signature. */
-  org: string;
-  /** The payout address (the signer's own address). Lowercased in the message. */
-  address: string;
-  network: string;
-  /** ISO-8601 timestamp; the server enforces a freshness window against replay. */
-  issuedAt: string;
-}
-/**
- * Build the payout-address ownership message. This MUST be byte-identical to the
- * platform's `buildPayoutRegistrationMessage`, or registration fails the
- * ownership proof. The org id is in the signed bytes, so a captured signature
- * can never register the address under a different org.
- */
-declare function buildPayoutRegistrationMessage(input: PayoutRegistrationMessageInput): string;
-/** The x402 wire payload (validated server-side against the x402 schema). */
-interface X402PaymentPayload {
-  x402Version: 1;
-  scheme: "exact";
-  network: string;
-  payload: {
-    signature: Hex;
-    authorization: {
-      from: Address;
-      to: Address;
-      value: string;
-      validAfter: string;
-      validBefore: string;
-      nonce: Hex;
-    };
-  };
-}
-/**
- * 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;
-/**
- * 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. */
-  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;
-  /**
-   * 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;
-};
-/** 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 {
   scheme: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "1.22.1",
+  "version": "1.24.0",
   "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser runtime modules.",
   "type": "module",
   "module": "./dist/index.js",
@@ -50,6 +50,11 @@
       "types": "./dist/payloads/index.d.ts",
       "import": "./dist/payloads/index.js",
       "default": "./dist/payloads/index.js"
+    },
+    "./interactions": {
+      "types": "./dist/interactions/index.d.ts",
+      "import": "./dist/interactions/index.js",
+      "default": "./dist/interactions/index.js"
     }
   },
   "sideEffects": false,
@@ -61,13 +66,13 @@
     "generate:types": "tsx scripts/generate-types.ts",
     "generate:validator": "tsx scripts/generate-validator.ts",
     "generate": "pnpm --filter @primitivedotdev/api-core generate && pnpm generate:schema && pnpm generate:types && pnpm generate:validator",
-    "build": "pnpm generate && NODE_OPTIONS=\"--max-old-space-size=4096\" tsdown",
+    "build": "pnpm generate && NODE_OPTIONS=\"--max-old-space-size=6144\" tsdown",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "pnpm generate && tsc --noEmit -p tsconfig.typecheck.json",
-    "lint": "biome check --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/x402 src/openapi/index.ts src/payloads tests/",
-    "lint:fix": "biome check --write --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/x402 src/openapi/index.ts src/payloads tests/",
+    "lint": "biome check --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/x402 src/openapi/index.ts src/payloads src/interactions tests/",
+    "lint:fix": "biome check --write --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/x402 src/openapi/index.ts src/payloads src/interactions tests/",
     "prepublishOnly": "pnpm build"
   },
   "keywords": [
@@ -97,9 +102,9 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "mailparser": "^3.9.0",
-    "nodemailer": "^9.0.1",
-    "sanitize-html": "^2.14.0",
+    "mailparser": "^3.9.14",
+    "nodemailer": "^9.1.1",
+    "sanitize-html": "^2.17.5",
     "tar-stream": "^3.1.8",
     "validator": "^13.15.35",
     "viem": "^2.21.0"
@@ -114,13 +119,13 @@
     "@types/sanitize-html": "^2.13.0",
     "@types/tar-stream": "^3.1.4",
     "@types/validator": "^13.15.10",
-    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "^0.27.0",
     "json-schema-to-typescript": "^15.0.4",
     "tsdown": "^0.21.10",
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",
     "vite": "^8.0.8",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.11"
   }
 }