x402z-client 0.1.0 → 0.1.2

package/README.md

@@ -26,7 +26,7 @@ const account = privateKeyToAccount("0x...");
 const relayer = await createRelayer(SepoliaConfig);
 
 const client = createX402zClient({
-  schemePreference: ["erc7984-mind-v1"],
+  preferredMethods: ["erc7984-mind-v1.CONFIDENTIAL_USDC.sepolia"] as const,
   signer: {
     address: account.address,
     signTypedData: account.signTypedData,
@@ -41,10 +41,37 @@ console.log(paid.response.status);
 `createX402zClient` builds the confidential payment input automatically using the
 `confidential.batcherAddress` provided by the server’s payment requirements.
 
+## Choosing Payment Methods (Client)
+
+The client picks the **first** preferred method that matches the server’s `accepts` list
+by `scheme + network + asset`.
+
+You can specify preferred methods in two ways:
+
+1) **Name string** (scheme + token + network alias):
+```ts
+preferredMethods: ["exact.USDC.base", "erc7984-mind-v1.CONFIDENTIAL_USDC.sepolia"] as const
+```
+
+2) **Config entry** (from `SCHEME_CONFIG`):
+```ts
+import { SCHEME_CONFIG } from "x402z-scheme-config";
+
+preferredMethods: [
+  SCHEME_CONFIG.exact.USDC.base,
+  SCHEME_CONFIG["erc7984-mind-v1"].CONFIDENTIAL_USDC.sepolia,
+]
+```
+
+If `preferredMethods` is omitted, the client defaults to `SCHEME_CONFIG_NAMES`
+(all known methods, in order).
+
 ## API
 
 - `createX402zClient(config)`
-  - `schemePreference` (required): ordered list of schemes to try (e.g. `["erc7984-mind-v1", "exact"]`)
+  - `preferredMethods` (optional): ordered list of preferred methods.
+    - Name form: `"exact.USDC.base"` (matches scheme/token/network alias from `x402z-scheme-config`).
+    - Config form: `SCHEME_CONFIG.exact.USDC.base`.
   - `signer` (required): signer used for both exact and confidential schemes
   - `relayer` (required when using `erc7984-mind-v1`): Zama relayer instance used to build encrypted inputs
   - `fetch` (optional): custom fetch implementation
@@ -63,7 +90,7 @@ import { privateKeyToAccount } from "viem/accounts";
 
 const account = privateKeyToAccount("0x...");
 const client = createX402zClient({
-  schemePreference: ["exact"],
+  preferredMethods: ["exact.USDC.sepolia"] as const,
   signer: account,
 });
 
@@ -91,6 +118,7 @@ Exports:
 Types:
 - `X402zClientSchemeOptions`: scheme config for client registration.
 - `X402zClientRegistrationOptions`: registration options for the scheme.
+- `PreferredPaymentMethod`: preferred payment method selector (object form or scheme-config name string).
 - `X402zClientOptions`: options for `createX402zClient`.
 - `X402zConfidentialClientOptions`: options for confidential payments.
 - `X402zExactClientOptions`: options for exact payments.

package/dist/index.d.mts

@@ -4,6 +4,7 @@ import { ClientEvmSigner } from '@x402/evm';
 import { ConfidentialPaymentInput, RelayerInstance } from 'x402z-shared';
 import { x402Client, SelectPaymentRequirements, PaymentPolicy } from '@x402/core/client';
 export { AfterPaymentCreationHook, BeforePaymentCreationHook, OnPaymentCreationFailureHook, PaymentCreatedContext, PaymentCreationContext, PaymentCreationFailureContext, PaymentPolicy, SchemeRegistration, SelectPaymentRequirements, x402Client, x402ClientConfig, x402HTTPClient } from '@x402/core/client';
+import { SchemeConfigName, ExactTokenConfig, ConfidentialTokenConfig } from 'x402z-scheme-config';
 
 type X402zClientSchemeOptions = {
     signer: ClientEvmSigner;
@@ -31,13 +32,13 @@ declare function registerX402zEvmClientScheme(client: x402Client, config: X402zC
 
 declare function buildPaymentInput(relayer: RelayerInstance, requirements: PaymentRequirements, amount: number): Promise<ConfidentialPaymentInput>;
 
-type Scheme = "exact" | "erc7984-mind-v1";
+type PreferredPaymentMethod = SchemeConfigName | ExactTokenConfig | ConfidentialTokenConfig;
 type BaseClientOptions = {
     fetch?: typeof fetch;
     debug?: boolean;
 };
 type X402zClientOptions = {
-    schemePreference: Scheme[];
+    preferredMethods?: readonly PreferredPaymentMethod[];
     signer: ClientEvmSigner;
     relayer?: RelayerInstance;
     networks?: Network[];
@@ -47,7 +48,7 @@ type X402zClientOptions = {
     hashEncryptedAmountInput?: X402zClientSchemeOptions["hashEncryptedAmountInput"];
     clock?: X402zClientSchemeOptions["clock"];
     onPaymentSelected?: (info: {
-        scheme: Scheme;
+        method: PreferredPaymentMethod;
         requirements: PaymentRequirements;
     }) => void;
 } & BaseClientOptions;
@@ -65,4 +66,4 @@ type X402zClient = {
 };
 declare function createX402zClient(config: X402zClientOptions): X402zClient;
 
-export { type PayOptions, type PayResult, type X402zClientOptions, type X402zClientRegistrationOptions, type X402zClientSchemeOptions, X402zEvmClientScheme, buildPaymentInput, createX402zClient, registerX402zEvmClientScheme };
+export { type PayOptions, type PayResult, type PreferredPaymentMethod, type X402zClient, type X402zClientOptions, type X402zClientRegistrationOptions, type X402zClientSchemeOptions, X402zEvmClientScheme, buildPaymentInput, createX402zClient, registerX402zEvmClientScheme };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { ClientEvmSigner } from '@x402/evm';
 import { ConfidentialPaymentInput, RelayerInstance } from 'x402z-shared';
 import { x402Client, SelectPaymentRequirements, PaymentPolicy } from '@x402/core/client';
 export { AfterPaymentCreationHook, BeforePaymentCreationHook, OnPaymentCreationFailureHook, PaymentCreatedContext, PaymentCreationContext, PaymentCreationFailureContext, PaymentPolicy, SchemeRegistration, SelectPaymentRequirements, x402Client, x402ClientConfig, x402HTTPClient } from '@x402/core/client';
+import { SchemeConfigName, ExactTokenConfig, ConfidentialTokenConfig } from 'x402z-scheme-config';
 
 type X402zClientSchemeOptions = {
     signer: ClientEvmSigner;
@@ -31,13 +32,13 @@ declare function registerX402zEvmClientScheme(client: x402Client, config: X402zC
 
 declare function buildPaymentInput(relayer: RelayerInstance, requirements: PaymentRequirements, amount: number): Promise<ConfidentialPaymentInput>;
 
-type Scheme = "exact" | "erc7984-mind-v1";
+type PreferredPaymentMethod = SchemeConfigName | ExactTokenConfig | ConfidentialTokenConfig;
 type BaseClientOptions = {
     fetch?: typeof fetch;
     debug?: boolean;
 };
 type X402zClientOptions = {
-    schemePreference: Scheme[];
+    preferredMethods?: readonly PreferredPaymentMethod[];
     signer: ClientEvmSigner;
     relayer?: RelayerInstance;
     networks?: Network[];
@@ -47,7 +48,7 @@ type X402zClientOptions = {
     hashEncryptedAmountInput?: X402zClientSchemeOptions["hashEncryptedAmountInput"];
     clock?: X402zClientSchemeOptions["clock"];
     onPaymentSelected?: (info: {
-        scheme: Scheme;
+        method: PreferredPaymentMethod;
         requirements: PaymentRequirements;
     }) => void;
 } & BaseClientOptions;
@@ -65,4 +66,4 @@ type X402zClient = {
 };
 declare function createX402zClient(config: X402zClientOptions): X402zClient;
 
-export { type PayOptions, type PayResult, type X402zClientOptions, type X402zClientRegistrationOptions, type X402zClientSchemeOptions, X402zEvmClientScheme, buildPaymentInput, createX402zClient, registerX402zEvmClientScheme };
+export { type PayOptions, type PayResult, type PreferredPaymentMethod, type X402zClient, type X402zClientOptions, type X402zClientRegistrationOptions, type X402zClientSchemeOptions, X402zEvmClientScheme, buildPaymentInput, createX402zClient, registerX402zEvmClientScheme };

package/dist/index.js

@@ -150,8 +150,29 @@ var import_http = require("@x402/core/http");
 var import_client2 = require("@x402/evm/exact/client");
 var import_viem2 = require("viem");
 var import_x402z_shared3 = require("x402z-shared");
-function filterPaymentRequired(paymentRequired, scheme) {
-  const accepts = paymentRequired.accepts.filter((requirement) => requirement.scheme === scheme);
+var import_x402z_scheme_config = require("x402z-scheme-config");
+function resolvePreferredMethod(method) {
+  if (typeof method !== "string") {
+    return method;
+  }
+  const config = (0, import_x402z_scheme_config.getSchemeConfigByName)(method);
+  if (!config) {
+    throw new Error(`Unknown preferred method: ${method}`);
+  }
+  return config;
+}
+function matchesMethod(requirements, method) {
+  const resolved = resolvePreferredMethod(method);
+  const scheme = (0, import_x402z_scheme_config.isConfidentialTokenConfig)(resolved) ? "erc7984-mind-v1" : "exact";
+  if (requirements.scheme !== scheme) return false;
+  if (requirements.network !== resolved.network) return false;
+  if (requirements.asset && requirements.asset?.toLowerCase() !== resolved.asset.toLowerCase()) return false;
+  return true;
+}
+function filterPaymentRequired(paymentRequired, method) {
+  const accepts = paymentRequired.accepts.filter(
+    (requirement) => matchesMethod(requirement, method)
+  );
   return { ...paymentRequired, accepts };
 }
 function createExactPayer(config, debugEnabled) {
@@ -242,7 +263,7 @@ function createX402zClient(config) {
   if (!fetchFn) {
     throw new Error("fetch is not available; provide a fetch implementation");
   }
-  const schemePreference = config.schemePreference?.length ? config.schemePreference : ["exact"];
+  const preferredMethods = config.preferredMethods?.length ? [...config.preferredMethods] : import_x402z_scheme_config.SCHEME_CONFIG_NAMES;
   const exactPayer = createExactPayer(
     {
       signer: config.signer,
@@ -274,27 +295,26 @@ function createX402zClient(config) {
       (name) => initial.headers.get(name),
       await initial.json().catch(() => ({}))
     );
-    const supportedSchemes = new Set(
-      paymentRequired.accepts.map((accept) => accept.scheme)
-    );
-    const selectedScheme = schemePreference.find(
-      (scheme) => supportedSchemes.has(scheme)
+    const selectedMethod = preferredMethods.find(
+      (method) => paymentRequired.accepts.some(
+        (requirement) => matchesMethod(requirement, method)
+      )
     );
-    if (!selectedScheme) {
-      throw new Error("No preferred schemes are supported by payment requirements");
+    if (!selectedMethod) {
+      throw new Error("No preferred payment methods are supported by payment requirements");
     }
-    const filteredRequirements = filterPaymentRequired(paymentRequired, selectedScheme);
+    const filteredRequirements = filterPaymentRequired(paymentRequired, selectedMethod);
     if (filteredRequirements.accepts.length === 0) {
-      throw new Error(`Missing ${selectedScheme} payment requirements`);
+      throw new Error("Missing payment requirements for selected method");
     }
     let headersResult;
     let confidentialRequirements;
     const selectedRequirements = filteredRequirements.accepts[0];
     config.onPaymentSelected?.({
-      scheme: selectedScheme,
+      method: selectedMethod,
       requirements: selectedRequirements
     });
-    if (selectedScheme === "exact") {
+    if (selectedRequirements.scheme === "exact") {
       headersResult = await exactPayer.buildHeaders(filteredRequirements);
     } else {
       if (!confidentialPayer) {

package/dist/index.mjs

@@ -126,8 +126,29 @@ import { isAddress } from "viem";
 import {
   createEncryptedAmountInput as createEncryptedAmountInput2
 } from "x402z-shared";
-function filterPaymentRequired(paymentRequired, scheme) {
-  const accepts = paymentRequired.accepts.filter((requirement) => requirement.scheme === scheme);
+import { getSchemeConfigByName, SCHEME_CONFIG_NAMES, isConfidentialTokenConfig } from "x402z-scheme-config";
+function resolvePreferredMethod(method) {
+  if (typeof method !== "string") {
+    return method;
+  }
+  const config = getSchemeConfigByName(method);
+  if (!config) {
+    throw new Error(`Unknown preferred method: ${method}`);
+  }
+  return config;
+}
+function matchesMethod(requirements, method) {
+  const resolved = resolvePreferredMethod(method);
+  const scheme = isConfidentialTokenConfig(resolved) ? "erc7984-mind-v1" : "exact";
+  if (requirements.scheme !== scheme) return false;
+  if (requirements.network !== resolved.network) return false;
+  if (requirements.asset && requirements.asset?.toLowerCase() !== resolved.asset.toLowerCase()) return false;
+  return true;
+}
+function filterPaymentRequired(paymentRequired, method) {
+  const accepts = paymentRequired.accepts.filter(
+    (requirement) => matchesMethod(requirement, method)
+  );
   return { ...paymentRequired, accepts };
 }
 function createExactPayer(config, debugEnabled) {
@@ -218,7 +239,7 @@ function createX402zClient(config) {
   if (!fetchFn) {
     throw new Error("fetch is not available; provide a fetch implementation");
   }
-  const schemePreference = config.schemePreference?.length ? config.schemePreference : ["exact"];
+  const preferredMethods = config.preferredMethods?.length ? [...config.preferredMethods] : SCHEME_CONFIG_NAMES;
   const exactPayer = createExactPayer(
     {
       signer: config.signer,
@@ -250,27 +271,26 @@ function createX402zClient(config) {
       (name) => initial.headers.get(name),
       await initial.json().catch(() => ({}))
     );
-    const supportedSchemes = new Set(
-      paymentRequired.accepts.map((accept) => accept.scheme)
-    );
-    const selectedScheme = schemePreference.find(
-      (scheme) => supportedSchemes.has(scheme)
+    const selectedMethod = preferredMethods.find(
+      (method) => paymentRequired.accepts.some(
+        (requirement) => matchesMethod(requirement, method)
+      )
     );
-    if (!selectedScheme) {
-      throw new Error("No preferred schemes are supported by payment requirements");
+    if (!selectedMethod) {
+      throw new Error("No preferred payment methods are supported by payment requirements");
     }
-    const filteredRequirements = filterPaymentRequired(paymentRequired, selectedScheme);
+    const filteredRequirements = filterPaymentRequired(paymentRequired, selectedMethod);
     if (filteredRequirements.accepts.length === 0) {
-      throw new Error(`Missing ${selectedScheme} payment requirements`);
+      throw new Error("Missing payment requirements for selected method");
     }
     let headersResult;
     let confidentialRequirements;
     const selectedRequirements = filteredRequirements.accepts[0];
     config.onPaymentSelected?.({
-      scheme: selectedScheme,
+      method: selectedMethod,
       requirements: selectedRequirements
     });
-    if (selectedScheme === "exact") {
+    if (selectedRequirements.scheme === "exact") {
       headersResult = await exactPayer.buildHeaders(filteredRequirements);
     } else {
       if (!confidentialPayer) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402z-client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -15,10 +15,11 @@
     }
   },
   "dependencies": {
-    "@x402/core": "^2.0.0",
-    "@x402/evm": "^2.0.0",
+    "@x402/core": "^2.2.0",
+    "@x402/evm": "^2.2.0",
     "viem": "^2.39.3",
-    "x402z-shared": "0.1.0"
+    "x402z-shared": "0.1.2",
+    "x402z-scheme-config": "0.1.2"
   },
   "devDependencies": {
     "jest": "^29.7.0",