@x402x/client 0.2.0

package/dist/index.cjs

@@ -0,0 +1,705 @@
+'use strict';
+
+var core = require('@x402x/core');
+var viem = require('viem');
+var actions = require('viem/actions');
+var react = require('react');
+var wagmi = require('wagmi');
+
+// src/client.ts
+
+// src/errors.ts
+var X402ClientError = class _X402ClientError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "X402ClientError";
+    Object.setPrototypeOf(this, _X402ClientError.prototype);
+  }
+};
+var NetworkError = class _NetworkError extends X402ClientError {
+  constructor(message, code) {
+    super(message, code);
+    this.name = "NetworkError";
+    Object.setPrototypeOf(this, _NetworkError.prototype);
+  }
+};
+var SigningError = class _SigningError extends X402ClientError {
+  constructor(message, code) {
+    super(message, code);
+    this.name = "SigningError";
+    Object.setPrototypeOf(this, _SigningError.prototype);
+  }
+};
+var FacilitatorError = class _FacilitatorError extends X402ClientError {
+  constructor(message, code, statusCode, response) {
+    super(message, code);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "FacilitatorError";
+    Object.setPrototypeOf(this, _FacilitatorError.prototype);
+  }
+};
+var TransactionError = class _TransactionError extends X402ClientError {
+  constructor(message, code, txHash) {
+    super(message, code);
+    this.txHash = txHash;
+    this.name = "TransactionError";
+    Object.setPrototypeOf(this, _TransactionError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends X402ClientError {
+  constructor(message, code) {
+    super(message, code);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+function generateSalt() {
+  const randomBytes = crypto.getRandomValues(new Uint8Array(32));
+  return `0x${Array.from(randomBytes).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+function normalizeAddress(address, name = "address") {
+  if (!address || typeof address !== "string") {
+    throw new ValidationError(`${name} is required`);
+  }
+  try {
+    return viem.getAddress(address);
+  } catch (error) {
+    throw new ValidationError(
+      `${name} is not a valid Ethereum address: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+  }
+}
+function validateAddress(address, name) {
+  if (!address || typeof address !== "string") {
+    throw new ValidationError(`${name} is required`);
+  }
+  if (!viem.isAddress(address)) {
+    throw new ValidationError(`${name} must be a valid Ethereum address`);
+  }
+}
+function validateHex(hex, name, expectedLength) {
+  if (!hex || typeof hex !== "string") {
+    throw new ValidationError(`${name} is required`);
+  }
+  if (!hex.startsWith("0x")) {
+    throw new ValidationError(`${name} must start with 0x`);
+  }
+  if (!/^0x[0-9a-fA-F]*$/.test(hex)) {
+    throw new ValidationError(`${name} must be a valid hex string`);
+  }
+  if (expectedLength !== void 0) {
+    const actualLength = (hex.length - 2) / 2;
+    if (actualLength !== expectedLength) {
+      throw new ValidationError(
+        `${name} must be ${expectedLength} bytes, got ${actualLength} bytes`
+      );
+    }
+  }
+}
+function validateAmount(amount, name) {
+  if (amount === null || amount === void 0 || amount === "") {
+    throw new ValidationError(`${name} is required`);
+  }
+  const amountStr = typeof amount === "number" ? amount.toString() : amount;
+  if (typeof amountStr !== "string" || amountStr.trim() === "") {
+    throw new ValidationError(`${name} must be a non-empty string`);
+  }
+  if (!/^\d+$/.test(amountStr)) {
+    throw new ValidationError(
+      `${name} must be a positive integer string (atomic units). Use parseDefaultAssetAmount() from @x402x/core to convert USD amounts.`
+    );
+  }
+  try {
+    const atomicAmount = BigInt(amountStr);
+    if (atomicAmount < 0n) {
+      throw new ValidationError(`${name} cannot be negative`);
+    }
+    if (atomicAmount === 0n) {
+      throw new ValidationError(`${name} cannot be zero`);
+    }
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      throw error;
+    }
+    throw new ValidationError(
+      `${name} is not a valid amount: ${error instanceof Error ? error.message : "Invalid format"}`
+    );
+  }
+}
+function formatFacilitatorUrl(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+function calculateTimeWindow(maxTimeoutSeconds = 300) {
+  const now = Math.floor(Date.now() / 1e3);
+  return {
+    validAfter: (now - 600).toString(),
+    // 10 minutes before
+    validBefore: (now + maxTimeoutSeconds).toString()
+  };
+}
+
+// src/core/prepare.ts
+async function queryFacilitatorFee(facilitatorUrl, network, hook, hookData = "0x") {
+  try {
+    return await core.calculateFacilitatorFee(facilitatorUrl, network, hook, hookData);
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new FacilitatorError(
+        `Failed to query facilitator fee: ${error.message}`,
+        "FEE_QUERY_FAILED"
+      );
+    }
+    throw new FacilitatorError("Failed to query facilitator fee: Unknown error", "UNKNOWN_ERROR");
+  }
+}
+async function prepareSettlement(params) {
+  validateAddress(params.hook, "hook");
+  validateHex(params.hookData, "hookData");
+  validateAddress(params.payTo, "payTo");
+  validateAmount(params.amount, "amount");
+  const atomicAmount = params.amount;
+  if (params.customSalt) {
+    validateHex(params.customSalt, "customSalt", 32);
+  }
+  const from = params.wallet.account?.address;
+  if (!from) {
+    throw new ValidationError("Wallet client must have an account");
+  }
+  const networkConfig = params.networkConfig || core.getNetworkConfig(params.network);
+  if (!networkConfig) {
+    throw new NetworkError(
+      `Network '${params.network}' is not supported. Please provide custom networkConfig.`
+    );
+  }
+  const asset = params.asset || networkConfig.defaultAsset.address;
+  validateAddress(asset, "asset");
+  const salt = params.customSalt || generateSalt();
+  let facilitatorFee = params.facilitatorFee || "0";
+  if (!params.facilitatorFee && params.facilitatorUrl) {
+    try {
+      const feeEstimate = await queryFacilitatorFee(
+        params.facilitatorUrl,
+        params.network,
+        params.hook,
+        params.hookData
+        // Pass hookData for accurate fee calculation
+      );
+      if (!feeEstimate.hookAllowed) {
+        throw new ValidationError(
+          `Hook ${params.hook} is not allowed on network ${params.network}.`
+        );
+      }
+      facilitatorFee = feeEstimate.facilitatorFee;
+    } catch (error) {
+      console.warn(
+        `[x402x] Failed to query facilitator fee, using 0. This may cause settlement to fail. Error: ${error instanceof Error ? error.message : "Unknown"}`
+      );
+      facilitatorFee = "0";
+    }
+  }
+  const timeWindow = params.validAfter && params.validBefore ? { validAfter: params.validAfter, validBefore: params.validBefore } : calculateTimeWindow(300);
+  const totalAmount = (BigInt(atomicAmount) + BigInt(facilitatorFee)).toString();
+  const commitment = core.calculateCommitment({
+    chainId: networkConfig.chainId,
+    hub: networkConfig.settlementRouter,
+    asset,
+    from,
+    value: totalAmount,
+    validAfter: timeWindow.validAfter,
+    validBefore: timeWindow.validBefore,
+    salt,
+    payTo: params.payTo,
+    facilitatorFee,
+    hook: params.hook,
+    hookData: params.hookData
+  });
+  return {
+    network: params.network,
+    networkConfig,
+    asset,
+    from,
+    amount: atomicAmount,
+    validAfter: timeWindow.validAfter,
+    validBefore: timeWindow.validBefore,
+    salt,
+    payTo: params.payTo,
+    facilitatorFee,
+    hook: params.hook,
+    hookData: params.hookData,
+    commitment
+  };
+}
+var AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+async function signAuthorization(wallet, settlement) {
+  try {
+    if (!wallet.account) {
+      throw new SigningError("Wallet client must have an account");
+    }
+    const domain = {
+      name: settlement.networkConfig.defaultAsset.eip712.name,
+      version: settlement.networkConfig.defaultAsset.eip712.version,
+      chainId: settlement.networkConfig.chainId,
+      verifyingContract: viem.getAddress(settlement.asset)
+    };
+    const totalAmount = BigInt(settlement.amount) + BigInt(settlement.facilitatorFee);
+    const message = {
+      from: viem.getAddress(settlement.from),
+      to: viem.getAddress(settlement.networkConfig.settlementRouter),
+      value: totalAmount,
+      validAfter: BigInt(settlement.validAfter),
+      validBefore: BigInt(settlement.validBefore),
+      nonce: settlement.commitment
+      // Use commitment as nonce
+    };
+    console.log("[x402x/client] EIP-712 Message for signing:", {
+      from: message.from,
+      to: message.to,
+      value: message.value.toString(),
+      validAfter: message.validAfter.toString(),
+      validBefore: message.validBefore.toString(),
+      nonce: message.nonce
+    });
+    const signature = await actions.signTypedData(wallet, {
+      account: wallet.account,
+      domain,
+      types: AUTHORIZATION_TYPES,
+      primaryType: "TransferWithAuthorization",
+      message
+    });
+    const authorization = {
+      from: settlement.from,
+      to: settlement.networkConfig.settlementRouter,
+      value: totalAmount.toString(),
+      // Use total amount (business + fee)
+      validAfter: settlement.validAfter,
+      validBefore: settlement.validBefore,
+      nonce: settlement.commitment
+    };
+    return {
+      settlement,
+      signature,
+      authorization
+    };
+  } catch (error) {
+    if (error instanceof SigningError) {
+      throw error;
+    }
+    if (error instanceof Error) {
+      if (error.message.includes("User rejected")) {
+        throw new SigningError("User rejected the signing request", "USER_REJECTED");
+      }
+      if (error.message.includes("account")) {
+        throw new SigningError("Wallet account not available", "NO_ACCOUNT");
+      }
+      throw new SigningError(`Failed to sign authorization: ${error.message}`, "SIGNING_FAILED");
+    }
+    throw new SigningError("Failed to sign authorization: Unknown error", "UNKNOWN_ERROR");
+  }
+}
+async function settle(facilitatorUrl, signed, timeout = 3e4) {
+  try {
+    const paymentPayload = {
+      x402Version: 1,
+      scheme: "exact",
+      network: signed.settlement.network,
+      // Network type compatibility
+      payload: {
+        signature: signed.signature,
+        authorization: {
+          from: signed.authorization.from,
+          to: signed.authorization.to,
+          value: signed.authorization.value,
+          validAfter: signed.authorization.validAfter,
+          validBefore: signed.authorization.validBefore,
+          nonce: signed.authorization.nonce
+        }
+      }
+    };
+    const paymentRequirements = {
+      scheme: "exact",
+      network: signed.settlement.network,
+      // Network type compatibility
+      maxAmountRequired: signed.settlement.amount,
+      asset: signed.settlement.asset,
+      payTo: signed.settlement.networkConfig.settlementRouter,
+      maxTimeoutSeconds: 300,
+      // 5 minutes
+      // Required by x402 protocol (even though not used in serverless mode)
+      // In the future, the x402 v2 will remove the resource field from the payment requirements
+      // (https://github.com/coinbase/x402/pull/446)
+      resource: "https://x402x.dev/serverless",
+      // Placeholder for serverless mode
+      description: "x402x Serverless Settlement",
+      mimeType: "application/json",
+      extra: {
+        name: signed.settlement.networkConfig.defaultAsset.eip712.name,
+        version: signed.settlement.networkConfig.defaultAsset.eip712.version,
+        settlementRouter: signed.settlement.networkConfig.settlementRouter,
+        salt: signed.settlement.salt,
+        payTo: signed.settlement.payTo,
+        facilitatorFee: signed.settlement.facilitatorFee,
+        hook: signed.settlement.hook,
+        hookData: signed.settlement.hookData
+      }
+    };
+    paymentPayload.paymentRequirements = paymentRequirements;
+    const result = await core.settle(facilitatorUrl, paymentPayload, paymentRequirements, timeout);
+    return {
+      success: result.success,
+      transaction: result.transaction,
+      network: result.network || signed.settlement.network,
+      payer: result.payer || signed.settlement.from,
+      errorReason: result.errorReason
+    };
+  } catch (error) {
+    if (error instanceof FacilitatorError) {
+      throw error;
+    }
+    if (error instanceof Error) {
+      throw new FacilitatorError(`Failed to settle payment: ${error.message}`, "SETTLEMENT_ERROR");
+    }
+    throw new FacilitatorError("Failed to settle payment: Unknown error", "UNKNOWN_ERROR");
+  }
+}
+
+// src/client.ts
+var DEFAULT_FACILITATOR_URL = "https://facilitator.x402x.dev";
+var X402Client = class {
+  /**
+   * Create a new X402Client instance
+   *
+   * @param config - Client configuration
+   * @throws NetworkError if network is unsupported
+   * @throws ValidationError if configuration is invalid
+   */
+  constructor(config) {
+    if (!config.wallet) {
+      throw new ValidationError("wallet is required");
+    }
+    if (!config.network) {
+      throw new ValidationError("network is required");
+    }
+    this.config = {
+      ...config,
+      facilitatorUrl: config.facilitatorUrl || DEFAULT_FACILITATOR_URL,
+      timeout: config.timeout || 3e4,
+      confirmationTimeout: config.confirmationTimeout || 6e4
+    };
+  }
+  /**
+   * Execute a settlement transaction
+   *
+   * This is the main method that orchestrates the entire settlement flow:
+   * 1. Validates parameters
+   * 2. Prepares settlement data (queries fee if needed)
+   * 3. Signs EIP-3009 authorization
+   * 4. Submits to facilitator
+   * 5. Optionally waits for transaction confirmation
+   *
+   * @param params - Execution parameters
+   * @param waitForConfirmation - Whether to wait for transaction confirmation (default: true)
+   * @returns Execution result with transaction hash and optional receipt
+   *
+   * @throws ValidationError if parameters are invalid
+   * @throws NetworkError if network is unsupported
+   * @throws SigningError if user rejects signing
+   * @throws FacilitatorError if facilitator request fails
+   * @throws TransactionError if transaction fails
+   *
+   * @example Simple transfer (uses TransferHook by default)
+   * ```typescript
+   * import { parseDefaultAssetAmount } from '@x402x/core';
+   *
+   * // Convert USD amount to atomic units
+   * const atomicAmount = parseDefaultAssetAmount('1', 'base-sepolia'); // '1000000'
+   *
+   * const result = await client.execute({
+   *   amount: atomicAmount, // Must be atomic units
+   *   payTo: '0x...'
+   * });
+   * console.log('Transaction:', result.txHash);
+   * ```
+   *
+   * @example Custom hook
+   * ```typescript
+   * import { parseDefaultAssetAmount } from '@x402x/core';
+   *
+   * const atomicAmount = parseDefaultAssetAmount('5', 'base-sepolia'); // '5000000'
+   *
+   * const result = await client.execute({
+   *   hook: '0x...',
+   *   hookData: '0x...',
+   *   amount: atomicAmount, // Must be atomic units
+   *   payTo: '0x...'
+   * });
+   * ```
+   */
+  async execute(params, waitForConfirmation = false) {
+    const hook = params.hook ? normalizeAddress(params.hook, "hook") : core.TransferHook.getAddress(this.config.network);
+    const payTo = normalizeAddress(params.payTo, "payTo");
+    const hookData = params.hookData || "0x";
+    if (params.hookData) {
+      validateHex(params.hookData, "hookData");
+    }
+    validateAmount(params.amount, "amount");
+    const settlement = await prepareSettlement({
+      wallet: this.config.wallet,
+      network: this.config.network,
+      hook,
+      hookData,
+      asset: params.asset,
+      amount: params.amount,
+      payTo,
+      facilitatorFee: params.facilitatorFee,
+      customSalt: params.customSalt,
+      validAfter: params.validAfter,
+      validBefore: params.validBefore,
+      networkConfig: this.config.networkConfig,
+      facilitatorUrl: this.config.facilitatorUrl
+    });
+    const signed = await signAuthorization(this.config.wallet, settlement);
+    const settleResult = await settle(this.config.facilitatorUrl, signed, this.config.timeout);
+    let receipt;
+    if (waitForConfirmation) {
+      receipt = await this.waitForTransaction(settleResult.transaction);
+    }
+    return {
+      txHash: settleResult.transaction,
+      network: settleResult.network,
+      payer: settleResult.payer,
+      receipt,
+      settlement
+    };
+  }
+  /**
+   * Calculate facilitator fee for a hook with optional hook data
+   *
+   * Queries the facilitator for the recommended fee based on current gas prices
+   * and hook gas usage. The returned fee includes a safety margin to ensure
+   * settlement will succeed.
+   *
+   * @param hook - Hook contract address
+   * @param hookData - Optional encoded hook parameters (default: '0x')
+   * @returns Fee calculation result from facilitator
+   *
+   * @throws FacilitatorError if query fails
+   *
+   * @example
+   * ```typescript
+   * const fee = await client.calculateFee('0x...', '0x');
+   * console.log('Facilitator fee:', fee.facilitatorFee);
+   * console.log('Fee in USD:', fee.facilitatorFeeUSD);
+   * console.log('Valid for:', fee.validitySeconds, 'seconds');
+   * ```
+   */
+  async calculateFee(hook, hookData = "0x") {
+    const normalizedHook = normalizeAddress(hook, "hook");
+    validateHex(hookData, "hookData");
+    try {
+      return await core.calculateFacilitatorFee(
+        this.config.facilitatorUrl,
+        this.config.network,
+        normalizedHook,
+        hookData
+      );
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new FacilitatorError(
+          `Failed to calculate facilitator fee: ${error.message}`,
+          "FEE_QUERY_FAILED"
+        );
+      }
+      throw new FacilitatorError(
+        "Failed to calculate facilitator fee: Unknown error",
+        "UNKNOWN_ERROR"
+      );
+    }
+  }
+  /**
+   * Wait for transaction confirmation
+   *
+   * @param txHash - Transaction hash to wait for
+   * @returns Transaction receipt
+   *
+   * @throws TransactionError if transaction fails or times out
+   *
+   * @example
+   * ```typescript
+   * const receipt = await client.waitForTransaction('0x...');
+   * console.log('Status:', receipt.status);
+   * ```
+   */
+  async waitForTransaction(txHash) {
+    const publicClient = this.config.wallet;
+    if (typeof publicClient.waitForTransactionReceipt !== "function") {
+      throw new Error(
+        "Wallet client does not support waitForTransactionReceipt. Please use a viem PublicClient or WalletClient with public actions."
+      );
+    }
+    try {
+      const receipt = await publicClient.waitForTransactionReceipt({
+        hash: txHash,
+        timeout: this.config.confirmationTimeout
+      });
+      if (receipt.status !== "success") {
+        throw new Error(`Transaction failed with status: ${receipt.status}`);
+      }
+      return receipt;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to confirm transaction: ${error.message}`);
+      }
+      throw new Error("Failed to confirm transaction: Unknown error");
+    }
+  }
+  /**
+   * Get the network name
+   */
+  get network() {
+    return this.config.network;
+  }
+  /**
+   * Get the facilitator URL
+   */
+  get facilitatorUrl() {
+    return this.config.facilitatorUrl;
+  }
+  /**
+   * Get the wallet client
+   */
+  get wallet() {
+    return this.config.wallet;
+  }
+};
+var CHAIN_ID_TO_NETWORK = {
+  84532: "base-sepolia",
+  8453: "base",
+  196: "x-layer",
+  1952: "x-layer-testnet"
+};
+function useX402Client(config) {
+  const { data: walletClient } = wagmi.useWalletClient();
+  const { isConnected } = wagmi.useAccount();
+  const chainId = wagmi.useChainId();
+  return react.useMemo(() => {
+    if (!isConnected || !walletClient) {
+      return null;
+    }
+    const network = config?.network || CHAIN_ID_TO_NETWORK[chainId];
+    if (!network) {
+      console.warn(
+        `[x402x] Unknown chainId ${chainId}. Please provide network name explicitly in config.`
+      );
+      return null;
+    }
+    try {
+      const extendedWallet = walletClient.extend(viem.publicActions);
+      return new X402Client({
+        wallet: extendedWallet,
+        network,
+        facilitatorUrl: config?.facilitatorUrl,
+        networkConfig: config?.networkConfig,
+        timeout: config?.timeout,
+        confirmationTimeout: config?.confirmationTimeout
+      });
+    } catch (error) {
+      console.error("[x402x] Failed to create X402Client:", error);
+      return null;
+    }
+  }, [
+    isConnected,
+    walletClient,
+    chainId,
+    config?.network,
+    config?.facilitatorUrl,
+    config?.networkConfig,
+    config?.timeout,
+    config?.confirmationTimeout
+  ]);
+}
+function useExecute(config) {
+  const client = useX402Client(config);
+  const [status, setStatus] = react.useState("idle");
+  const [error, setError] = react.useState(null);
+  const [result, setResult] = react.useState(null);
+  const execute = react.useCallback(
+    async (params, waitForConfirmation = true) => {
+      if (!client) {
+        throw new Error("X402Client not available. Please connect your wallet.");
+      }
+      setStatus("preparing");
+      setError(null);
+      setResult(null);
+      try {
+        const executeResult = await client.execute(params, waitForConfirmation);
+        setStatus("success");
+        setResult(executeResult);
+        return executeResult;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error("Unknown error");
+        setStatus("error");
+        setError(error2);
+        throw error2;
+      }
+    },
+    [client]
+  );
+  const reset = react.useCallback(() => {
+    setStatus("idle");
+    setError(null);
+    setResult(null);
+  }, []);
+  return {
+    execute,
+    status,
+    error,
+    result,
+    reset,
+    isExecuting: ["preparing", "signing", "submitting", "confirming"].includes(status),
+    isSuccess: status === "success",
+    isError: status === "error"
+  };
+}
+
+Object.defineProperty(exports, "AmountError", {
+  enumerable: true,
+  get: function () { return core.AmountError; }
+});
+Object.defineProperty(exports, "formatDefaultAssetAmount", {
+  enumerable: true,
+  get: function () { return core.formatDefaultAssetAmount; }
+});
+Object.defineProperty(exports, "parseDefaultAssetAmount", {
+  enumerable: true,
+  get: function () { return core.parseDefaultAssetAmount; }
+});
+exports.DEFAULT_FACILITATOR_URL = DEFAULT_FACILITATOR_URL;
+exports.FacilitatorError = FacilitatorError;
+exports.NetworkError = NetworkError;
+exports.SigningError = SigningError;
+exports.TransactionError = TransactionError;
+exports.ValidationError = ValidationError;
+exports.X402Client = X402Client;
+exports.X402ClientError = X402ClientError;
+exports.calculateTimeWindow = calculateTimeWindow;
+exports.formatFacilitatorUrl = formatFacilitatorUrl;
+exports.generateSalt = generateSalt;
+exports.normalizeAddress = normalizeAddress;
+exports.prepareSettlement = prepareSettlement;
+exports.settle = settle;
+exports.signAuthorization = signAuthorization;
+exports.useExecute = useExecute;
+exports.useX402Client = useX402Client;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map