x402z-client-web 0.0.9

package/README.md

@@ -0,0 +1,49 @@
+# x402z-client-web
+
+Browser helpers for the erc7984-mind-v1 x402 scheme.
+
+## Install
+
+```bash
+pnpm add x402z-client-web x402z-shared-web
+```
+
+## Folder map
+
+- `src/http/`: HTTP client helpers
+- `src/scheme/`: scheme implementation + registration
+- `src/index.ts`: public exports
+
+## Usage (Browser)
+
+```ts
+import { createX402zClient } from "x402z-client-web";
+import { SepoliaConfig } from "x402z-shared-web";
+
+const client = await createX402zClient({
+  signer: {
+    address: "0x...",
+    signTypedData: async args =>
+      window.ethereum.request({ method: "eth_signTypedData_v4", params: [args] }),
+  },
+  relayerConfig: { ...SepoliaConfig, network: window.ethereum },
+});
+
+const response = await client.pay("https://example.com/demo");
+console.log(response.status);
+```
+
+`createX402zClient` builds the confidential payment input automatically using the
+`confidential.batcherAddress` provided by the server’s payment requirements.
+
+## API
+
+- `createX402zClient(config)`
+  - `signer` (required): EIP-712 signer for x402 payloads
+  - `relayerConfig` (required): relayer instance config (browser)
+  - `fetch` (optional): custom fetch implementation
+- `client.pay(url, options?)`: performs the 402 handshake and retries with payment headers
+
+## Notes
+
+- Scheme name: `erc7984-mind-v1`

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import { ConfidentialPaymentInput, RelayerSdkModule, initSDK, RelayerInstance } from 'x402z-shared-web';
+export { ConfidentialRequirementsExtra, RelayerInstance } from 'x402z-shared-web';
+import { x402Client } from '@x402/core/client';
+import { PaymentRequirements, SchemeNetworkClient, PaymentPayload, Network } from '@x402/core/types';
+export * from '@x402/core/types';
+import { ClientEvmSigner } from '@x402/evm';
+
+type X402zClientSchemeOptions = {
+    signer: ClientEvmSigner;
+    buildPayment: (requirements: PaymentRequirements) => ConfidentialPaymentInput | Promise<ConfidentialPaymentInput>;
+    eip712?: {
+        name: string;
+        version: string;
+    };
+    hashEncryptedAmountInput?: (encryptedAmountInput: `0x${string}`) => `0x${string}`;
+    clock?: () => number;
+};
+declare class X402zEvmClientScheme implements SchemeNetworkClient {
+    private readonly config;
+    readonly scheme = "erc7984-mind-v1";
+    private readonly hashFn;
+    private readonly clock;
+    constructor(config: X402zClientSchemeOptions);
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "x402Version" | "payload">>;
+}
+
+type X402zClientRegistrationOptions = X402zClientSchemeOptions & {
+    networks?: Network[];
+};
+declare function registerX402zEvmClientScheme(client: x402Client, config: X402zClientRegistrationOptions): x402Client;
+
+type X402zClientOptions = Omit<X402zClientRegistrationOptions, "buildPayment"> & {
+    relayerSdk?: RelayerSdkModule;
+    relayerConfig: unknown;
+    initSdkParams?: Parameters<typeof initSDK>[0];
+    fetch?: typeof fetch;
+    debug?: boolean;
+};
+type PayOptions = {
+    headers?: Record<string, string>;
+};
+type X402zClient = {
+    relayer: RelayerInstance;
+    pay: (url: string, options?: PayOptions) => Promise<Response>;
+};
+declare function createX402zClient(config: X402zClientOptions): Promise<X402zClient>;
+
+export { type PayOptions, type X402zClient, type X402zClientOptions, type X402zClientRegistrationOptions, type X402zClientSchemeOptions, X402zEvmClientScheme, createX402zClient, registerX402zEvmClientScheme };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { ConfidentialPaymentInput, RelayerSdkModule, initSDK, RelayerInstance } from 'x402z-shared-web';
+export { ConfidentialRequirementsExtra, RelayerInstance } from 'x402z-shared-web';
+import { x402Client } from '@x402/core/client';
+import { PaymentRequirements, SchemeNetworkClient, PaymentPayload, Network } from '@x402/core/types';
+export * from '@x402/core/types';
+import { ClientEvmSigner } from '@x402/evm';
+
+type X402zClientSchemeOptions = {
+    signer: ClientEvmSigner;
+    buildPayment: (requirements: PaymentRequirements) => ConfidentialPaymentInput | Promise<ConfidentialPaymentInput>;
+    eip712?: {
+        name: string;
+        version: string;
+    };
+    hashEncryptedAmountInput?: (encryptedAmountInput: `0x${string}`) => `0x${string}`;
+    clock?: () => number;
+};
+declare class X402zEvmClientScheme implements SchemeNetworkClient {
+    private readonly config;
+    readonly scheme = "erc7984-mind-v1";
+    private readonly hashFn;
+    private readonly clock;
+    constructor(config: X402zClientSchemeOptions);
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "x402Version" | "payload">>;
+}
+
+type X402zClientRegistrationOptions = X402zClientSchemeOptions & {
+    networks?: Network[];
+};
+declare function registerX402zEvmClientScheme(client: x402Client, config: X402zClientRegistrationOptions): x402Client;
+
+type X402zClientOptions = Omit<X402zClientRegistrationOptions, "buildPayment"> & {
+    relayerSdk?: RelayerSdkModule;
+    relayerConfig: unknown;
+    initSdkParams?: Parameters<typeof initSDK>[0];
+    fetch?: typeof fetch;
+    debug?: boolean;
+};
+type PayOptions = {
+    headers?: Record<string, string>;
+};
+type X402zClient = {
+    relayer: RelayerInstance;
+    pay: (url: string, options?: PayOptions) => Promise<Response>;
+};
+declare function createX402zClient(config: X402zClientOptions): Promise<X402zClient>;
+
+export { type PayOptions, type X402zClient, type X402zClientOptions, type X402zClientRegistrationOptions, type X402zClientSchemeOptions, X402zEvmClientScheme, createX402zClient, registerX402zEvmClientScheme };

package/dist/index.js

@@ -0,0 +1,220 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  X402zEvmClientScheme: () => X402zEvmClientScheme,
+  createX402zClient: () => createX402zClient,
+  registerX402zEvmClientScheme: () => registerX402zEvmClientScheme
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/http/client.ts
+var import_client = require("@x402/core/client");
+var import_http = require("@x402/core/http");
+var import_viem2 = require("viem");
+var import_x402z_shared_web2 = require("x402z-shared-web");
+
+// src/scheme/scheme.ts
+var import_viem = require("viem");
+var import_x402z_shared_web = require("x402z-shared-web");
+var ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+var DECIMAL_POINT = ".";
+function normalizeIntegerAmount(value, fallback) {
+  const normalized = (0, import_x402z_shared_web.normalizeAmount)(value);
+  if (!normalized.includes(DECIMAL_POINT)) {
+    return normalized;
+  }
+  const fallbackNormalized = (0, import_x402z_shared_web.normalizeAmount)(fallback);
+  if (fallbackNormalized.includes(DECIMAL_POINT)) {
+    throw new Error(`Invalid amount: ${normalized}`);
+  }
+  return fallbackNormalized;
+}
+var X402zEvmClientScheme = class {
+  constructor(config) {
+    this.config = config;
+    this.scheme = "erc7984-mind-v1";
+    this.hashFn = config.hashEncryptedAmountInput ?? import_x402z_shared_web.hashEncryptedAmountInput;
+    this.clock = config.clock ?? (() => Math.floor(Date.now() / 1e3));
+  }
+  async createPaymentPayload(x402Version, paymentRequirements) {
+    const input = await this.config.buildPayment(paymentRequirements);
+    const extra = paymentRequirements.extra;
+    const eip712 = extra?.eip712 ?? this.config.eip712;
+    if (!eip712?.name || !eip712?.version) {
+      throw new Error("Missing EIP-712 domain parameters (name, version) in requirements or config");
+    }
+    const now = this.clock();
+    const validAfter = input.validAfter ?? Math.max(0, now - 60);
+    const validBefore = input.validBefore ?? now + paymentRequirements.maxTimeoutSeconds;
+    const nonce = input.nonce ?? (0, import_x402z_shared_web.createNonce)();
+    const maxClearAmount = normalizeIntegerAmount(
+      input.maxClearAmount ?? extra?.confidential?.maxClearAmount ?? paymentRequirements.amount,
+      paymentRequirements.amount
+    );
+    const resourceHash = input.resourceHash ?? extra?.confidential?.resourceHash ?? ZERO_BYTES32;
+    const authorization = {
+      holder: this.config.signer.address,
+      payee: (0, import_viem.getAddress)(paymentRequirements.payTo),
+      maxClearAmount,
+      resourceHash,
+      validAfter: (0, import_x402z_shared_web.normalizeAmount)(validAfter),
+      validBefore: (0, import_x402z_shared_web.normalizeAmount)(validBefore),
+      nonce,
+      encryptedAmountHash: this.hashFn(input.encryptedAmountInput)
+    };
+    const chainId = parseInt(paymentRequirements.network.split(":")[1]);
+    const signature = await this.config.signer.signTypedData({
+      domain: {
+        name: eip712.name,
+        version: eip712.version,
+        chainId,
+        verifyingContract: (0, import_viem.getAddress)(paymentRequirements.asset)
+      },
+      types: import_x402z_shared_web.confidentialPaymentTypes,
+      primaryType: "ConfidentialPayment",
+      message: {
+        holder: (0, import_viem.getAddress)(authorization.holder),
+        payee: (0, import_viem.getAddress)(authorization.payee),
+        maxClearAmount: BigInt(authorization.maxClearAmount),
+        resourceHash: authorization.resourceHash,
+        validAfter: BigInt(authorization.validAfter),
+        validBefore: BigInt(authorization.validBefore),
+        nonce: authorization.nonce,
+        encryptedAmountHash: authorization.encryptedAmountHash
+      }
+    });
+    const payload = {
+      authorization,
+      signature,
+      encryptedAmountInput: input.encryptedAmountInput,
+      inputProof: input.inputProof
+    };
+    return {
+      x402Version,
+      payload
+    };
+  }
+};
+
+// src/scheme/register.ts
+function registerX402zEvmClientScheme(client, config) {
+  if (config.networks && config.networks.length > 0) {
+    for (const network of config.networks) {
+      client.register(network, new X402zEvmClientScheme(config));
+    }
+    return client;
+  }
+  client.register("eip155:*", new X402zEvmClientScheme(config));
+  return client;
+}
+
+// src/http/client.ts
+async function createX402zClient(config) {
+  const { fetch: fetchOverride, ...registerConfig } = config;
+  const fetchFn = fetchOverride ?? globalThis.fetch;
+  const debugEnabled = config.debug ?? false;
+  if (!fetchFn) {
+    throw new Error("fetch is not available; provide a fetch implementation");
+  }
+  if (config.relayerSdk) {
+    (0, import_x402z_shared_web2.configureRelayerSdk)(config.relayerSdk);
+  }
+  await (0, import_x402z_shared_web2.initSDK)(config.initSdkParams);
+  const relayer = await (0, import_x402z_shared_web2.createRelayer)(config.relayerConfig);
+  const buildPayment = async (requirements) => {
+    if (!(0, import_viem2.isAddress)(requirements.asset)) {
+      throw new Error(`Invalid TOKEN_ADDRESS from requirements: ${requirements.asset}`);
+    }
+    const extra = requirements.extra;
+    const batcherAddress = extra?.confidential?.batcherAddress;
+    if (!batcherAddress) {
+      throw new Error("Missing confidential.batcherAddress in payment requirements");
+    }
+    if (debugEnabled) {
+      console.debug("[x402z-client] encrypt input", {
+        tokenAddress: requirements.asset,
+        batcherAddress,
+        amount: requirements.amount
+      });
+    }
+    const encrypted = await (0, import_x402z_shared_web2.createEncryptedAmountInput)(
+      relayer,
+      requirements.asset,
+      batcherAddress,
+      Number(requirements.amount)
+    );
+    return {
+      encryptedAmountInput: encrypted.handle,
+      inputProof: encrypted.inputProof
+    };
+  };
+  const client = new import_client.x402Client();
+  registerX402zEvmClientScheme(client, {
+    ...registerConfig,
+    buildPayment
+  });
+  const httpClient = new import_http.x402HTTPClient(client);
+  return {
+    relayer,
+    async pay(url, options) {
+      const initial = await fetchFn(url, { headers: options?.headers });
+      if (initial.status !== 402) {
+        return initial;
+      }
+      const paymentRequired = httpClient.getPaymentRequiredResponse(
+        (name) => initial.headers.get(name),
+        await initial.json().catch(() => ({}))
+      );
+      const payload = await httpClient.createPaymentPayload(paymentRequired);
+      const payHeaders = httpClient.encodePaymentSignatureHeader(payload);
+      if (debugEnabled) {
+        console.debug("[x402z-client] payment payload", payload);
+        console.debug("[x402z-client] payment headers", payHeaders);
+      }
+      const mergedHeaders = { ...options?.headers ?? {}, ...payHeaders };
+      const paidResponse = await fetchFn(url, { headers: mergedHeaders });
+      if (debugEnabled) {
+        try {
+          const body = await paidResponse.clone().text();
+          console.debug("[x402z-client] response", {
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            body
+          });
+        } catch (error) {
+          console.debug("[x402z-client] response", {
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            body: "<unavailable>"
+          });
+        }
+      }
+      return paidResponse;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  X402zEvmClientScheme,
+  createX402zClient,
+  registerX402zEvmClientScheme
+});

package/dist/index.mjs

@@ -0,0 +1,201 @@
+// src/http/client.ts
+import { x402Client } from "@x402/core/client";
+import { x402HTTPClient } from "@x402/core/http";
+import { isAddress } from "viem";
+import {
+  configureRelayerSdk,
+  createEncryptedAmountInput,
+  createRelayer,
+  initSDK
+} from "x402z-shared-web";
+
+// src/scheme/scheme.ts
+import { getAddress } from "viem";
+import {
+  confidentialPaymentTypes,
+  createNonce,
+  hashEncryptedAmountInput,
+  normalizeAmount
+} from "x402z-shared-web";
+var ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+var DECIMAL_POINT = ".";
+function normalizeIntegerAmount(value, fallback) {
+  const normalized = normalizeAmount(value);
+  if (!normalized.includes(DECIMAL_POINT)) {
+    return normalized;
+  }
+  const fallbackNormalized = normalizeAmount(fallback);
+  if (fallbackNormalized.includes(DECIMAL_POINT)) {
+    throw new Error(`Invalid amount: ${normalized}`);
+  }
+  return fallbackNormalized;
+}
+var X402zEvmClientScheme = class {
+  constructor(config) {
+    this.config = config;
+    this.scheme = "erc7984-mind-v1";
+    this.hashFn = config.hashEncryptedAmountInput ?? hashEncryptedAmountInput;
+    this.clock = config.clock ?? (() => Math.floor(Date.now() / 1e3));
+  }
+  async createPaymentPayload(x402Version, paymentRequirements) {
+    const input = await this.config.buildPayment(paymentRequirements);
+    const extra = paymentRequirements.extra;
+    const eip712 = extra?.eip712 ?? this.config.eip712;
+    if (!eip712?.name || !eip712?.version) {
+      throw new Error("Missing EIP-712 domain parameters (name, version) in requirements or config");
+    }
+    const now = this.clock();
+    const validAfter = input.validAfter ?? Math.max(0, now - 60);
+    const validBefore = input.validBefore ?? now + paymentRequirements.maxTimeoutSeconds;
+    const nonce = input.nonce ?? createNonce();
+    const maxClearAmount = normalizeIntegerAmount(
+      input.maxClearAmount ?? extra?.confidential?.maxClearAmount ?? paymentRequirements.amount,
+      paymentRequirements.amount
+    );
+    const resourceHash = input.resourceHash ?? extra?.confidential?.resourceHash ?? ZERO_BYTES32;
+    const authorization = {
+      holder: this.config.signer.address,
+      payee: getAddress(paymentRequirements.payTo),
+      maxClearAmount,
+      resourceHash,
+      validAfter: normalizeAmount(validAfter),
+      validBefore: normalizeAmount(validBefore),
+      nonce,
+      encryptedAmountHash: this.hashFn(input.encryptedAmountInput)
+    };
+    const chainId = parseInt(paymentRequirements.network.split(":")[1]);
+    const signature = await this.config.signer.signTypedData({
+      domain: {
+        name: eip712.name,
+        version: eip712.version,
+        chainId,
+        verifyingContract: getAddress(paymentRequirements.asset)
+      },
+      types: confidentialPaymentTypes,
+      primaryType: "ConfidentialPayment",
+      message: {
+        holder: getAddress(authorization.holder),
+        payee: getAddress(authorization.payee),
+        maxClearAmount: BigInt(authorization.maxClearAmount),
+        resourceHash: authorization.resourceHash,
+        validAfter: BigInt(authorization.validAfter),
+        validBefore: BigInt(authorization.validBefore),
+        nonce: authorization.nonce,
+        encryptedAmountHash: authorization.encryptedAmountHash
+      }
+    });
+    const payload = {
+      authorization,
+      signature,
+      encryptedAmountInput: input.encryptedAmountInput,
+      inputProof: input.inputProof
+    };
+    return {
+      x402Version,
+      payload
+    };
+  }
+};
+
+// src/scheme/register.ts
+function registerX402zEvmClientScheme(client, config) {
+  if (config.networks && config.networks.length > 0) {
+    for (const network of config.networks) {
+      client.register(network, new X402zEvmClientScheme(config));
+    }
+    return client;
+  }
+  client.register("eip155:*", new X402zEvmClientScheme(config));
+  return client;
+}
+
+// src/http/client.ts
+async function createX402zClient(config) {
+  const { fetch: fetchOverride, ...registerConfig } = config;
+  const fetchFn = fetchOverride ?? globalThis.fetch;
+  const debugEnabled = config.debug ?? false;
+  if (!fetchFn) {
+    throw new Error("fetch is not available; provide a fetch implementation");
+  }
+  if (config.relayerSdk) {
+    configureRelayerSdk(config.relayerSdk);
+  }
+  await initSDK(config.initSdkParams);
+  const relayer = await createRelayer(config.relayerConfig);
+  const buildPayment = async (requirements) => {
+    if (!isAddress(requirements.asset)) {
+      throw new Error(`Invalid TOKEN_ADDRESS from requirements: ${requirements.asset}`);
+    }
+    const extra = requirements.extra;
+    const batcherAddress = extra?.confidential?.batcherAddress;
+    if (!batcherAddress) {
+      throw new Error("Missing confidential.batcherAddress in payment requirements");
+    }
+    if (debugEnabled) {
+      console.debug("[x402z-client] encrypt input", {
+        tokenAddress: requirements.asset,
+        batcherAddress,
+        amount: requirements.amount
+      });
+    }
+    const encrypted = await createEncryptedAmountInput(
+      relayer,
+      requirements.asset,
+      batcherAddress,
+      Number(requirements.amount)
+    );
+    return {
+      encryptedAmountInput: encrypted.handle,
+      inputProof: encrypted.inputProof
+    };
+  };
+  const client = new x402Client();
+  registerX402zEvmClientScheme(client, {
+    ...registerConfig,
+    buildPayment
+  });
+  const httpClient = new x402HTTPClient(client);
+  return {
+    relayer,
+    async pay(url, options) {
+      const initial = await fetchFn(url, { headers: options?.headers });
+      if (initial.status !== 402) {
+        return initial;
+      }
+      const paymentRequired = httpClient.getPaymentRequiredResponse(
+        (name) => initial.headers.get(name),
+        await initial.json().catch(() => ({}))
+      );
+      const payload = await httpClient.createPaymentPayload(paymentRequired);
+      const payHeaders = httpClient.encodePaymentSignatureHeader(payload);
+      if (debugEnabled) {
+        console.debug("[x402z-client] payment payload", payload);
+        console.debug("[x402z-client] payment headers", payHeaders);
+      }
+      const mergedHeaders = { ...options?.headers ?? {}, ...payHeaders };
+      const paidResponse = await fetchFn(url, { headers: mergedHeaders });
+      if (debugEnabled) {
+        try {
+          const body = await paidResponse.clone().text();
+          console.debug("[x402z-client] response", {
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            body
+          });
+        } catch (error) {
+          console.debug("[x402z-client] response", {
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            body: "<unavailable>"
+          });
+        }
+      }
+      return paidResponse;
+    }
+  };
+}
+export {
+  X402zEvmClientScheme,
+  createX402zClient,
+  registerX402zEvmClientScheme
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "x402z-client-web",
+  "version": "0.0.9",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@x402/core": "^2.0.0",
+    "@x402/evm": "^2.0.0",
+    "viem": "^2.39.3",
+    "x402z-shared-web": "0.0.9"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "@types/jest": "^29.5.12"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "jest --config jest.config.cjs --passWithNoTests"
+  }
+}