@nevermined-io/payments 1.1.18 → 1.4.0

package/dist/x402/token.js

@@ -25,41 +25,47 @@ export class X402TokenAPI extends BasePaymentsAPI {
         return new X402TokenAPI(options);
     }
     /**
-     * Create a permission and get an X402 access token for the given plan.
+     * Create a delegation and get an X402 access token for the given plan.
      *
-     * This token allows the agent to verify and settle permissions on behalf
-     * of the subscriber. The token contains cryptographically signed session keys
-     * that delegate specific permissions (order, burn) to the agent.
+     * This token allows the agent to verify and settle delegations on behalf
+     * of the subscriber.
+     *
+     * For erc4337 scheme, you must pass `tokenOptions.delegationConfig` with either:
+     * - `delegationId` to reuse an existing delegation, or
+     * - `spendingLimitCents` + `durationSecs` to auto-create a new one.
      *
      * @param planId - The unique identifier of the payment plan
-     * @param agentId - The unique identifier of the AI agent (optional). If provided, permissions are restricted to that specific agent.
-     * @param redemptionLimit - Maximum number of interactions/redemptions allowed (optional)
-     * @param orderLimit - Maximum spend limit in token units (wei) for ordering (optional)
-     * @param expiration - Expiration date in ISO 8601 format, e.g. "2025-02-01T10:00:00Z" (optional)
+     * @param agentId - The unique identifier of the AI agent (optional)
+     * @param tokenOptions - Options controlling scheme and delegation behavior (optional)
      * @returns A promise that resolves to an object containing:
      *   - accessToken: The X402 access token string
-     *   - Additional metadata about the token
      *
      * @throws PaymentsError if the request fails
      *
      * @example
      * ```typescript
-     * import { Payments } from '@nevermined-io/payments'
-     *
-     * const payments = Payments.getInstance({
-     *   nvmApiKey: 'nvm:subscriber-key',
-     *   environment: 'sandbox'
+     * // Pattern A — auto-create delegation
+     * const result = await payments.x402.getX402AccessToken(planId, agentId, {
+     *   delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }
      * })
      *
-     * const result = await payments.x402.getX402AccessToken(planId, agentId)
-     * const token = result.accessToken
+     * // Pattern B — reuse existing delegation
+     * const result = await payments.x402.getX402AccessToken(planId, agentId, {
+     *   delegationConfig: { delegationId: 'existing-delegation-uuid' }
+     * })
      * ```
      */
-    async getX402AccessToken(planId, agentId, redemptionLimit, orderLimit, expiration, tokenOptions) {
+    async getX402AccessToken(planId, agentId, tokenOptions) {
         const urlPath = API_URL_CREATE_PERMISSION;
         const url = new URL(urlPath, this.environment.backend);
         const scheme = tokenOptions?.scheme ?? 'nvm:erc4337';
         const network = tokenOptions?.network ?? getDefaultNetwork(scheme, this.environmentName);
+        // Validate delegationConfig is provided — the backend requires it for token generation
+        if (!tokenOptions?.delegationConfig) {
+            throw PaymentsError.validation(`delegationConfig is required for ${scheme} token generation. ` +
+                'Provide delegationConfig.delegationId to reuse an existing delegation, ' +
+                'or delegationConfig.spendingLimitCents + durationSecs to auto-create one.');
+        }
         // Build x402-aligned request body
         const body = {
             accepted: {
@@ -71,31 +77,15 @@ export class X402TokenAPI extends BasePaymentsAPI {
                 },
             },
         };
-        // Add delegation config for card-delegation scheme
-        if (scheme === 'nvm:card-delegation' && tokenOptions?.delegationConfig) {
+        // Add delegation config for both erc4337 and card-delegation schemes
+        if (tokenOptions?.delegationConfig) {
             body.delegationConfig = tokenOptions.delegationConfig;
         }
-        // Add session key config if any options are provided (erc4337 only)
-        if (scheme === 'nvm:erc4337') {
-            const sessionKeyConfig = {};
-            if (redemptionLimit !== undefined) {
-                sessionKeyConfig.redemptionLimit = redemptionLimit;
-            }
-            if (orderLimit !== undefined) {
-                sessionKeyConfig.orderLimit = orderLimit;
-            }
-            if (expiration !== undefined) {
-                sessionKeyConfig.expiration = expiration;
-            }
-            if (Object.keys(sessionKeyConfig).length > 0) {
-                body.sessionKeyConfig = sessionKeyConfig;
-            }
-        }
         const options = this.getBackendHTTPOptions('POST', body);
         try {
             const response = await fetch(url, options);
             if (!response.ok) {
-                let errorMessage = 'Failed to create X402 permission';
+                let errorMessage = 'Failed to create X402 delegation token';
                 try {
                     const errorData = await response.json();
                     errorMessage = errorData.message || errorMessage;
@@ -111,7 +101,7 @@ export class X402TokenAPI extends BasePaymentsAPI {
             if (error instanceof PaymentsError) {
                 throw error;
             }
-            throw PaymentsError.internal(`Network error while creating X402 permission: ${error instanceof Error ? error.message : String(error)}`);
+            throw PaymentsError.internal(`Network error while creating X402 delegation token: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
 }

package/dist/x402/token.js.map

@@ -1 +1 @@
-{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,EAAoC,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAExF;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAuB;QACxC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,KAAK,CAAC,kBAAkB,CACtB,MAAc,EACd,OAAgB,EAChB,eAAwB,EACxB,UAAmB,EACnB,UAAmB,EACnB,YAA+B;QAE/B,MAAM,OAAO,GAAG,yBAAyB,CAAA;QACzC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAEtD,MAAM,MAAM,GAAG,YAAY,EAAE,MAAM,IAAI,aAAa,CAAA;QACpD,MAAM,OAAO,GAAG,YAAY,EAAE,OAAO,IAAI,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,CAAA;QAExF,kCAAkC;QAClC,MAAM,IAAI,GAAwB;YAChC,QAAQ,EAAE;gBACR,MAAM;gBACN,OAAO;gBACP,MAAM;gBACN,KAAK,EAAE;oBACL,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;iBAC5B;aACF;SACF,CAAA;QAED,mDAAmD;QACnD,IAAI,MAAM,KAAK,qBAAqB,IAAI,YAAY,EAAE,gBAAgB,EAAE,CAAC;YACvE,IAAI,CAAC,gBAAgB,GAAG,YAAY,CAAC,gBAAgB,CAAA;QACvD,CAAC;QAED,oEAAoE;QACpE,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;YAC7B,MAAM,gBAAgB,GAAwB,EAAE,CAAA;YAChD,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;gBAClC,gBAAgB,CAAC,eAAe,GAAG,eAAe,CAAA;YACpD,CAAC;YACD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,gBAAgB,CAAC,UAAU,GAAG,UAAU,CAAA;YAC1C,CAAC;YACD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,gBAAgB,CAAC,UAAU,GAAG,UAAU,CAAA;YAC1C,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC7C,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAA;YAC1C,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAExD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC1C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,YAAY,GAAG,kCAAkC,CAAA;gBACrD,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;oBACvC,YAAY,GAAG,SAAS,CAAC,OAAO,IAAI,YAAY,CAAA;gBAClD,CAAC;gBAAC,MAAM,CAAC;oBACP,4BAA4B;gBAC9B,CAAC;gBACD,MAAM,aAAa,CAAC,QAAQ,CAAC,GAAG,YAAY,UAAU,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAA;YAC3E,CAAC;YACD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,MAAM,KAAK,CAAA;YACb,CAAC;YACD,MAAM,aAAa,CAAC,QAAQ,CAC1B,iDAAiD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC1G,CAAA;QACH,CAAC;IACH,CAAC;CACF","sourcesContent":["/**\n * X402 Token Generation API.\n *\n * Provides X402 access token generation functionality for subscribers.\n * Tokens are used to authorize payment verification and settlement.\n */\n\nimport { BasePaymentsAPI } from '../api/base-payments.js'\nimport { API_URL_CREATE_PERMISSION } from '../api/nvm-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, X402TokenOptions, getDefaultNetwork } from '../common/types.js'\n\n/**\n * X402 Token API for generating access tokens.\n *\n * Handles X402 access token generation for subscribers to authorize\n * payment operations with AI agents.\n */\nexport class X402TokenAPI extends BasePaymentsAPI {\n  /**\n   * Get a singleton instance of the X402TokenAPI class.\n   *\n   * @param options - The options to initialize the API\n   * @returns The instance of the X402TokenAPI class\n   */\n  static getInstance(options: PaymentOptions): X402TokenAPI {\n    return new X402TokenAPI(options)\n  }\n\n  /**\n   * Create a permission and get an X402 access token for the given plan.\n   *\n   * This token allows the agent to verify and settle permissions on behalf\n   * of the subscriber. The token contains cryptographically signed session keys\n   * that delegate specific permissions (order, burn) to the agent.\n   *\n   * @param planId - The unique identifier of the payment plan\n   * @param agentId - The unique identifier of the AI agent (optional). If provided, permissions are restricted to that specific agent.\n   * @param redemptionLimit - Maximum number of interactions/redemptions allowed (optional)\n   * @param orderLimit - Maximum spend limit in token units (wei) for ordering (optional)\n   * @param expiration - Expiration date in ISO 8601 format, e.g. \"2025-02-01T10:00:00Z\" (optional)\n   * @returns A promise that resolves to an object containing:\n   *   - accessToken: The X402 access token string\n   *   - Additional metadata about the token\n   *\n   * @throws PaymentsError if the request fails\n   *\n   * @example\n   * ```typescript\n   * import { Payments } from '@nevermined-io/payments'\n   *\n   * const payments = Payments.getInstance({\n   *   nvmApiKey: 'nvm:subscriber-key',\n   *   environment: 'sandbox'\n   * })\n   *\n   * const result = await payments.x402.getX402AccessToken(planId, agentId)\n   * const token = result.accessToken\n   * ```\n   */\n  async getX402AccessToken(\n    planId: string,\n    agentId?: string,\n    redemptionLimit?: number,\n    orderLimit?: string,\n    expiration?: string,\n    tokenOptions?: X402TokenOptions,\n  ): Promise<{ accessToken: string;[key: string]: any }> {\n    const urlPath = API_URL_CREATE_PERMISSION\n    const url = new URL(urlPath, this.environment.backend)\n\n    const scheme = tokenOptions?.scheme ?? 'nvm:erc4337'\n    const network = tokenOptions?.network ?? getDefaultNetwork(scheme, this.environmentName)\n\n    // Build x402-aligned request body\n    const body: Record<string, any> = {\n      accepted: {\n        scheme,\n        network,\n        planId,\n        extra: {\n          ...(agentId && { agentId }),\n        },\n      },\n    }\n\n    // Add delegation config for card-delegation scheme\n    if (scheme === 'nvm:card-delegation' && tokenOptions?.delegationConfig) {\n      body.delegationConfig = tokenOptions.delegationConfig\n    }\n\n    // Add session key config if any options are provided (erc4337 only)\n    if (scheme === 'nvm:erc4337') {\n      const sessionKeyConfig: Record<string, any> = {}\n      if (redemptionLimit !== undefined) {\n        sessionKeyConfig.redemptionLimit = redemptionLimit\n      }\n      if (orderLimit !== undefined) {\n        sessionKeyConfig.orderLimit = orderLimit\n      }\n      if (expiration !== undefined) {\n        sessionKeyConfig.expiration = expiration\n      }\n      if (Object.keys(sessionKeyConfig).length > 0) {\n        body.sessionKeyConfig = sessionKeyConfig\n      }\n    }\n\n    const options = this.getBackendHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Failed to create X402 permission'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.internal(`${errorMessage} (HTTP ${response.status})`)\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.internal(\n        `Network error while creating X402 permission: ${error instanceof Error ? error.message : String(error)}`,\n      )\n    }\n  }\n}\n"]}
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,EAAoC,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAExF;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAuB;QACxC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,KAAK,CAAC,kBAAkB,CACtB,MAAc,EACd,OAAgB,EAChB,YAA+B;QAE/B,MAAM,OAAO,GAAG,yBAAyB,CAAA;QACzC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAEtD,MAAM,MAAM,GAAG,YAAY,EAAE,MAAM,IAAI,aAAa,CAAA;QACpD,MAAM,OAAO,GAAG,YAAY,EAAE,OAAO,IAAI,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,CAAA;QAExF,uFAAuF;QACvF,IAAI,CAAC,YAAY,EAAE,gBAAgB,EAAE,CAAC;YACpC,MAAM,aAAa,CAAC,UAAU,CAC5B,oCAAoC,MAAM,qBAAqB;gBAC7D,yEAAyE;gBACzE,2EAA2E,CAC9E,CAAA;QACH,CAAC;QAED,kCAAkC;QAClC,MAAM,IAAI,GAAwB;YAChC,QAAQ,EAAE;gBACR,MAAM;gBACN,OAAO;gBACP,MAAM;gBACN,KAAK,EAAE;oBACL,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;iBAC5B;aACF;SACF,CAAA;QAED,qEAAqE;QACrE,IAAI,YAAY,EAAE,gBAAgB,EAAE,CAAC;YACnC,IAAI,CAAC,gBAAgB,GAAG,YAAY,CAAC,gBAAgB,CAAA;QACvD,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAExD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC1C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,YAAY,GAAG,wCAAwC,CAAA;gBAC3D,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;oBACvC,YAAY,GAAG,SAAS,CAAC,OAAO,IAAI,YAAY,CAAA;gBAClD,CAAC;gBAAC,MAAM,CAAC;oBACP,4BAA4B;gBAC9B,CAAC;gBACD,MAAM,aAAa,CAAC,QAAQ,CAAC,GAAG,YAAY,UAAU,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAA;YAC3E,CAAC;YACD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,MAAM,KAAK,CAAA;YACb,CAAC;YACD,MAAM,aAAa,CAAC,QAAQ,CAC1B,uDAAuD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAChH,CAAA;QACH,CAAC;IACH,CAAC;CACF","sourcesContent":["/**\n * X402 Token Generation API.\n *\n * Provides X402 access token generation functionality for subscribers.\n * Tokens are used to authorize payment verification and settlement.\n */\n\nimport { BasePaymentsAPI } from '../api/base-payments.js'\nimport { API_URL_CREATE_PERMISSION } from '../api/nvm-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, X402TokenOptions, getDefaultNetwork } from '../common/types.js'\n\n/**\n * X402 Token API for generating access tokens.\n *\n * Handles X402 access token generation for subscribers to authorize\n * payment operations with AI agents.\n */\nexport class X402TokenAPI extends BasePaymentsAPI {\n  /**\n   * Get a singleton instance of the X402TokenAPI class.\n   *\n   * @param options - The options to initialize the API\n   * @returns The instance of the X402TokenAPI class\n   */\n  static getInstance(options: PaymentOptions): X402TokenAPI {\n    return new X402TokenAPI(options)\n  }\n\n  /**\n   * Create a delegation and get an X402 access token for the given plan.\n   *\n   * This token allows the agent to verify and settle delegations on behalf\n   * of the subscriber.\n   *\n   * For erc4337 scheme, you must pass `tokenOptions.delegationConfig` with either:\n   * - `delegationId` to reuse an existing delegation, or\n   * - `spendingLimitCents` + `durationSecs` to auto-create a new one.\n   *\n   * @param planId - The unique identifier of the payment plan\n   * @param agentId - The unique identifier of the AI agent (optional)\n   * @param tokenOptions - Options controlling scheme and delegation behavior (optional)\n   * @returns A promise that resolves to an object containing:\n   *   - accessToken: The X402 access token string\n   *\n   * @throws PaymentsError if the request fails\n   *\n   * @example\n   * ```typescript\n   * // Pattern A — auto-create delegation\n   * const result = await payments.x402.getX402AccessToken(planId, agentId, {\n   *   delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }\n   * })\n   *\n   * // Pattern B — reuse existing delegation\n   * const result = await payments.x402.getX402AccessToken(planId, agentId, {\n   *   delegationConfig: { delegationId: 'existing-delegation-uuid' }\n   * })\n   * ```\n   */\n  async getX402AccessToken(\n    planId: string,\n    agentId?: string,\n    tokenOptions?: X402TokenOptions,\n  ): Promise<{ accessToken: string; [key: string]: any }> {\n    const urlPath = API_URL_CREATE_PERMISSION\n    const url = new URL(urlPath, this.environment.backend)\n\n    const scheme = tokenOptions?.scheme ?? 'nvm:erc4337'\n    const network = tokenOptions?.network ?? getDefaultNetwork(scheme, this.environmentName)\n\n    // Validate delegationConfig is provided — the backend requires it for token generation\n    if (!tokenOptions?.delegationConfig) {\n      throw PaymentsError.validation(\n        `delegationConfig is required for ${scheme} token generation. ` +\n          'Provide delegationConfig.delegationId to reuse an existing delegation, ' +\n          'or delegationConfig.spendingLimitCents + durationSecs to auto-create one.',\n      )\n    }\n\n    // Build x402-aligned request body\n    const body: Record<string, any> = {\n      accepted: {\n        scheme,\n        network,\n        planId,\n        extra: {\n          ...(agentId && { agentId }),\n        },\n      },\n    }\n\n    // Add delegation config for both erc4337 and card-delegation schemes\n    if (tokenOptions?.delegationConfig) {\n      body.delegationConfig = tokenOptions.delegationConfig\n    }\n\n    const options = this.getBackendHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Failed to create X402 delegation token'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.internal(`${errorMessage} (HTTP ${response.status})`)\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.internal(\n        `Network error while creating X402 delegation token: ${error instanceof Error ? error.message : String(error)}`,\n      )\n    }\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevermined-io/payments",
-  "version": "1.1.18",
+  "version": "1.4.0",
   "description": "Typescript SDK to interact with the Nevermined Payments Protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -40,22 +40,22 @@
   "scripts": {
     "clean": "rm -rf ./dist/ ./doc/ ./.nyc_output",
     "build": "tsc",
-    "build:all": "yarn build && yarn cli:build",
+    "build:all": "pnpm build && pnpm cli:build",
     "lint": "eslint ./src",
     "test": "jest --verbose --config ./tests/jest.config.json",
     "test:unit": "jest --verbose --config ./tests/jest.config.json --testPathPattern=tests/unit",
     "test:integration": "jest --verbose --config ./tests/jest.config.json --testPathPattern=tests/integration",
-    "test:e2e": "jest --verbose --config ./tests/jest.config.json --testPathPattern=tests/e2e --runInBand",
+    "test:e2e": "jest --verbose --config ./tests/jest.e2e.config.cjs --testPathPattern=tests/e2e --runInBand",
     "format": "prettier --check ./src",
-    "prepublishOnly": "yarn build",
+    "prepublishOnly": "pnpm build",
     "doc": "typedoc --out docs ./src",
-    "cli:build": "cd cli && yarn build",
-    "cli:dev": "cd cli && yarn dev",
-    "cli:test": "cd cli && yarn test",
-    "cli:install": "cd cli && yarn install"
+    "cli:build": "cd cli && pnpm build",
+    "cli:dev": "cd cli && pnpm dev",
+    "cli:test": "cd cli && pnpm test",
+    "cli:install": "cd cli && pnpm install"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.65.0",
+    "@anthropic-ai/sdk": "^0.91.1",
     "@aws-sdk/client-bedrock-runtime": "^3.972.0",
     "@babel/core": "^7.27.4",
     "@babel/preset-env": "^7.27.2",
@@ -76,19 +76,19 @@
     "eslint-config-nevermined": "^0.3.0",
     "eslint-config-next": "^15.1.5",
     "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-tsdoc": "^0.2.17",
+    "eslint-plugin-tsdoc": "^0.5.2",
     "jest": "^29.7.0",
     "langchain": "^0.3.37",
     "openai": "^6.2.0",
     "prettier": "^3.2.5",
     "source-map-support": "^0.5.21",
     "supertest": "^7.1.4",
-    "together-ai": "^0.22.0",
+    "together-ai": "^0.39.0",
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
     "tslib": "^2.6.2",
-    "typedoc": "0.25.13",
+    "typedoc": "0.28.19",
     "typescript": "^5.3.3"
   },
   "peerDependencies": {
@@ -111,8 +111,8 @@
     "@a2a-js/sdk": "^0.3.4",
     "@helicone/helpers": "^1.6.0",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
-    "@traceloop/node-server-sdk": "^0.14.6",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
+    "@traceloop/node-server-sdk": "^0.26.0",
     "axios": "^1.13.1",
     "express": "4.21.2",
     "jose": "^5.2.4",
@@ -121,12 +121,14 @@
     "zod": "^4.0.17",
     "zod-to-json-schema": "^3.25.0"
   },
-  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
-  "resolutions": {
-    "qs": ">=6.14.1",
-    "jws": ">=4.0.1",
-    "js-yaml": ">=4.1.1",
-    "@langchain/core": ">=0.3.80",
-    "@smithy/config-resolver": ">=4.4.0"
+  "packageManager": "pnpm@10.33.0",
+  "pnpm": {
+    "overrides": {
+      "qs": ">=6.14.1",
+      "jws": ">=4.0.1",
+      "js-yaml": ">=4.1.1",
+      "@langchain/core": ">=0.3.80",
+      "@smithy/config-resolver": ">=4.4.0"
+    }
   }
 }

package/dist/x402/visa-facilitator-api.d.ts

@@ -1,150 +0,0 @@
-/**
- * Visa Facilitator API — verifies and settles payments via the Visa x402 backend.
- *
- * Unlike the base FacilitatorAPI (which sends JSON bodies to the NVM backend),
- * the Visa flow uses the PAYMENT-SIGNATURE HTTP header to transport a base64-encoded
- * PaymentPayload to the Visa backend's /verify and /settle endpoints.
- *
- * @example
- * ```typescript
- * import { Payments } from '@nevermined-io/payments'
- *
- * const payments = Payments.getInstance({
- *   nvmApiKey: 'your-nvm-api-key',
- *   environment: 'sandbox',
- *   scheme: 'visa',
- * })
- *
- * const paymentRequired = buildVisaPaymentRequired({
- *   amount: '2.00',
- *   asset: 'USD',
- *   payTo: 'merchant-id',
- *   endpoint: '/tools/random-article',
- * })
- *
- * // The PAYMENT-SIGNATURE header from the client request
- * const paymentSignature = req.headers['payment-signature'] as string
- *
- * const verification = await payments.facilitator.verifyPermissions({
- *   paymentRequired,
- *   x402AccessToken: paymentSignature,
- * })
- *
- * if (verification.isValid) {
- *   const settlement = await payments.facilitator.settlePermissions({
- *     paymentRequired,
- *     x402AccessToken: paymentSignature,
- *   })
- * }
- * ```
- */
-import { FacilitatorAPI } from './facilitator-api.js';
-import type { VerifyPermissionsParams, VerifyPermissionsResult, SettlePermissionsParams, SettlePermissionsResult, X402Resource } from './facilitator-api.js';
-import { PaymentOptions } from '../common/types.js';
-/**
- * Visa-specific extra fields in PaymentRequirements
- */
-export interface VisaPaymentExtra {
-    /** Visa Token Service provisioned token ID */
-    vProvisionedTokenID: string;
-    /** VIC instruction ID from mandate creation */
-    instructionId: string;
-    /** Maximum number of times this payment can be used */
-    maxUsage: number;
-    /** Merchant name */
-    merchantName?: string;
-    /** Merchant URL */
-    merchantUrl?: string;
-    /** Merchant country code */
-    merchantCountryCode?: string;
-}
-/**
- * Visa payment requirements (x402 v2 with scheme: "visa")
- */
-export interface VisaPaymentRequirements {
-    scheme: 'visa';
-    network: 'visa:vts';
-    amount: string;
-    asset: string;
-    payTo: string;
-    maxTimeoutSeconds: number;
-    extra: VisaPaymentExtra;
-}
-/**
- * Visa-specific PaymentRequired response
- */
-export interface VisaPaymentRequired {
-    x402Version: 2;
-    error?: string;
-    resource: X402Resource;
-    accepts: VisaPaymentRequirements[];
-    extensions?: Record<string, unknown>;
-}
-/**
- * Visa verify response
- */
-export interface VisaVerifyResponse {
-    isValid: boolean;
-    payer?: string;
-    invalidReason?: string;
-    remainingUsage?: number;
-}
-/**
- * Visa settlement response
- */
-export interface VisaSettlementResponse {
-    success: boolean;
-    transaction: string;
-    network: 'visa:vts';
-    payer?: string;
-    errorReason?: string;
-}
-export declare const VISA_X402_HEADERS: {
-    readonly PAYMENT_REQUIRED: "PAYMENT-REQUIRED";
-    readonly PAYMENT_SIGNATURE: "PAYMENT-SIGNATURE";
-    readonly PAYMENT_RESPONSE: "PAYMENT-RESPONSE";
-};
-/**
- * Build a Visa-flavored X402PaymentRequired object.
- *
- * This is the Visa counterpart of `buildPaymentRequired` (which builds NVM-flavored ones).
- */
-export declare function buildVisaPaymentRequired(options: {
-    amount: string;
-    asset?: string;
-    payTo: string;
-    endpoint?: string;
-    description?: string;
-    maxTimeoutSeconds?: number;
-    merchantName?: string;
-    merchantUrl?: string;
-    merchantCountryCode?: string;
-}): VisaPaymentRequired;
-/**
- * Visa Facilitator API — sends PAYMENT-SIGNATURE header to the Visa backend
- * for verify and settle operations.
- */
-export declare class VisaFacilitatorAPI extends FacilitatorAPI {
-    protected visaBackendUrl: string;
-    constructor(options: PaymentOptions);
-    static getInstance(options: PaymentOptions): VisaFacilitatorAPI;
-    /**
-     * Verify a Visa payment authorization.
-     *
-     * Sends the base64-encoded PaymentPayload as a PAYMENT-SIGNATURE header
-     * to the Visa backend's POST /verify endpoint.
-     *
-     * @param params - contains x402AccessToken, the base64-encoded PaymentPayload from the client
-     */
-    verifyPermissions(params: VerifyPermissionsParams): Promise<VerifyPermissionsResult>;
-    /**
-     * Settle a Visa payment transaction.
-     *
-     * Sends the base64-encoded PaymentPayload as a PAYMENT-SIGNATURE header
-     * to the Visa backend's POST /settle endpoint.
-     *
-     * @param params - contains x402AccessToken, the base64-encoded PaymentPayload from the client
-     */
-    settlePermissions(params: SettlePermissionsParams): Promise<SettlePermissionsResult>;
-}
-//# sourceMappingURL=visa-facilitator-api.d.ts.map

package/dist/x402/visa-facilitator-api.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"visa-facilitator-api.d.ts","sourceRoot":"","sources":["../../src/x402/visa-facilitator-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACb,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAOnD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,mBAAmB,EAAE,MAAM,CAAA;IAC3B,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAA;IAChB,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4BAA4B;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,UAAU,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,iBAAiB,EAAE,MAAM,CAAA;IACzB,KAAK,EAAE,gBAAgB,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,CAAC,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,YAAY,CAAA;IACtB,OAAO,EAAE,uBAAuB,EAAE,CAAA;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,UAAU,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAMD,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAA;AAMV;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B,GAAG,mBAAmB,CAsCtB;AAMD;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,SAAS,CAAC,cAAc,EAAE,MAAM,CAAA;gBAEpB,OAAO,EAAE,cAAc;WAKnB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,kBAAkB;IAIxE;;;;;;;OAOG;IACY,iBAAiB,CAC9B,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,CAAC;IA6CnC;;;;;;;OAOG;IACY,iBAAiB,CAC9B,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,CAAC;CA8CpC"}

package/dist/x402/visa-facilitator-api.js

@@ -1,206 +0,0 @@
-/**
- * Visa Facilitator API — verifies and settles payments via the Visa x402 backend.
- *
- * Unlike the base FacilitatorAPI (which sends JSON bodies to the NVM backend),
- * the Visa flow uses the PAYMENT-SIGNATURE HTTP header to transport a base64-encoded
- * PaymentPayload to the Visa backend's /verify and /settle endpoints.
- *
- * @example
- * ```typescript
- * import { Payments } from '@nevermined-io/payments'
- *
- * const payments = Payments.getInstance({
- *   nvmApiKey: 'your-nvm-api-key',
- *   environment: 'sandbox',
- *   scheme: 'visa',
- * })
- *
- * const paymentRequired = buildVisaPaymentRequired({
- *   amount: '2.00',
- *   asset: 'USD',
- *   payTo: 'merchant-id',
- *   endpoint: '/tools/random-article',
- * })
- *
- * // The PAYMENT-SIGNATURE header from the client request
- * const paymentSignature = req.headers['payment-signature'] as string
- *
- * const verification = await payments.facilitator.verifyPermissions({
- *   paymentRequired,
- *   x402AccessToken: paymentSignature,
- * })
- *
- * if (verification.isValid) {
- *   const settlement = await payments.facilitator.settlePermissions({
- *     paymentRequired,
- *     x402AccessToken: paymentSignature,
- *   })
- * }
- * ```
- */
-import { FacilitatorAPI } from './facilitator-api.js';
-import { PaymentsError } from '../common/payments.error.js';
-import { VisaBackendUrls } from '../environments.js';
-// ---------------------------------------------------------------------------
-// Visa x402 header names
-// ---------------------------------------------------------------------------
-export const VISA_X402_HEADERS = {
-    PAYMENT_REQUIRED: 'PAYMENT-REQUIRED',
-    PAYMENT_SIGNATURE: 'PAYMENT-SIGNATURE',
-    PAYMENT_RESPONSE: 'PAYMENT-RESPONSE',
-};
-// ---------------------------------------------------------------------------
-// Helper: build a Visa PaymentRequired
-// ---------------------------------------------------------------------------
-/**
- * Build a Visa-flavored X402PaymentRequired object.
- *
- * This is the Visa counterpart of `buildPaymentRequired` (which builds NVM-flavored ones).
- */
-export function buildVisaPaymentRequired(options) {
-    const { amount, asset = 'USD', payTo, endpoint = '', description, maxTimeoutSeconds = 3600, merchantName, merchantUrl, merchantCountryCode, } = options;
-    return {
-        x402Version: 2,
-        resource: {
-            url: endpoint,
-            ...(description && { description }),
-        },
-        accepts: [
-            {
-                scheme: 'visa',
-                network: 'visa:vts',
-                amount,
-                asset,
-                payTo,
-                maxTimeoutSeconds,
-                extra: {
-                    vProvisionedTokenID: '',
-                    instructionId: '',
-                    maxUsage: 1,
-                    ...(merchantName && { merchantName }),
-                    ...(merchantUrl && { merchantUrl }),
-                    ...(merchantCountryCode && { merchantCountryCode }),
-                },
-            },
-        ],
-    };
-}
-// ---------------------------------------------------------------------------
-// VisaFacilitatorAPI
-// ---------------------------------------------------------------------------
-/**
- * Visa Facilitator API — sends PAYMENT-SIGNATURE header to the Visa backend
- * for verify and settle operations.
- */
-export class VisaFacilitatorAPI extends FacilitatorAPI {
-    constructor(options) {
-        super(options);
-        this.visaBackendUrl = VisaBackendUrls[this.environmentName];
-    }
-    static getInstance(options) {
-        return new VisaFacilitatorAPI(options);
-    }
-    /**
-     * Verify a Visa payment authorization.
-     *
-     * Sends the base64-encoded PaymentPayload as a PAYMENT-SIGNATURE header
-     * to the Visa backend's POST /verify endpoint.
-     *
-     * @param params - contains x402AccessToken, the base64-encoded PaymentPayload from the client
-     */
-    async verifyPermissions(params) {
-        const { x402AccessToken } = params;
-        const url = new URL('verify', this.visaBackendUrl);
-        try {
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    [VISA_X402_HEADERS.PAYMENT_SIGNATURE]: x402AccessToken,
-                },
-            });
-            if (!response.ok) {
-                let errorMessage = 'Visa payment verification failed';
-                try {
-                    const errorData = await response.json();
-                    errorMessage = errorData.invalidReason || errorData.message || errorMessage;
-                }
-                catch {
-                    // Use default error message
-                }
-                throw PaymentsError.fromBackend(errorMessage, {
-                    message: errorMessage,
-                    code: `HTTP ${response.status}`,
-                });
-            }
-            const visaResult = await response.json();
-            // Map Visa response to the standard VerifyPermissionsResult shape
-            return {
-                isValid: visaResult.isValid,
-                payer: visaResult.payer,
-                invalidReason: visaResult.invalidReason,
-            };
-        }
-        catch (error) {
-            if (error instanceof PaymentsError) {
-                throw error;
-            }
-            throw PaymentsError.fromBackend('Network error during Visa payment verification', {
-                message: error instanceof Error ? error.message : String(error),
-                code: 'network_error',
-            });
-        }
-    }
-    /**
-     * Settle a Visa payment transaction.
-     *
-     * Sends the base64-encoded PaymentPayload as a PAYMENT-SIGNATURE header
-     * to the Visa backend's POST /settle endpoint.
-     *
-     * @param params - contains x402AccessToken, the base64-encoded PaymentPayload from the client
-     */
-    async settlePermissions(params) {
-        const { x402AccessToken } = params;
-        const url = new URL('settle', this.visaBackendUrl);
-        try {
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    [VISA_X402_HEADERS.PAYMENT_SIGNATURE]: x402AccessToken,
-                },
-            });
-            if (!response.ok) {
-                let errorMessage = 'Visa payment settlement failed';
-                try {
-                    const errorData = await response.json();
-                    errorMessage = errorData.errorReason || errorData.message || errorMessage;
-                }
-                catch {
-                    // Use default error message
-                }
-                throw PaymentsError.fromBackend(errorMessage, {
-                    message: errorMessage,
-                    code: `HTTP ${response.status}`,
-                });
-            }
-            const visaResult = await response.json();
-            // Map Visa response to the standard SettlePermissionsResult shape
-            return {
-                success: visaResult.success,
-                transaction: visaResult.transaction,
-                network: visaResult.network,
-                payer: visaResult.payer,
-                errorReason: visaResult.errorReason,
-            };
-        }
-        catch (error) {
-            if (error instanceof PaymentsError) {
-                throw error;
-            }
-            throw PaymentsError.fromBackend('Network error during Visa payment settlement', {
-                message: error instanceof Error ? error.message : String(error),
-                code: 'network_error',
-            });
-        }
-    }
-}
-//# sourceMappingURL=visa-facilitator-api.js.map

package/dist/x402/visa-facilitator-api.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"visa-facilitator-api.js","sourceRoot":"","sources":["../../src/x402/visa-facilitator-api.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Visa Facilitator API — verifies and settles payments via the Visa x402 backend.\n *\n * Unlike the base FacilitatorAPI (which sends JSON bodies to the NVM backend),\n * the Visa flow uses the PAYMENT-SIGNATURE HTTP header to transport a base64-encoded\n * PaymentPayload to the Visa backend's /verify and /settle endpoints.\n *\n * @example\n * ```typescript\n * import { Payments } from '@nevermined-io/payments'\n *\n * const payments = Payments.getInstance({\n *   nvmApiKey: 'your-nvm-api-key',\n *   environment: 'sandbox',\n *   scheme: 'visa',\n * })\n *\n * const paymentRequired = buildVisaPaymentRequired({\n *   amount: '2.00',\n *   asset: 'USD',\n *   payTo: 'merchant-id',\n *   endpoint: '/tools/random-article',\n * })\n *\n * // The PAYMENT-SIGNATURE header from the client request\n * const paymentSignature = req.headers['payment-signature'] as string\n *\n * const verification = await payments.facilitator.verifyPermissions({\n *   paymentRequired,\n *   x402AccessToken: paymentSignature,\n * })\n *\n * if (verification.isValid) {\n *   const settlement = await payments.facilitator.settlePermissions({\n *     paymentRequired,\n *     x402AccessToken: paymentSignature,\n *   })\n * }\n * ```\n */\n\nimport { FacilitatorAPI } from './facilitator-api.js'\nimport type {\n  VerifyPermissionsParams,\n  VerifyPermissionsResult,\n  SettlePermissionsParams,\n  SettlePermissionsResult,\n  X402Resource,\n} from './facilitator-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions } from '../common/types.js'\nimport { VisaBackendUrls } from '../environments.js'\n\n// ---------------------------------------------------------------------------\n// Visa-specific x402 types\n// ---------------------------------------------------------------------------\n\n/**\n * Visa-specific extra fields in PaymentRequirements\n */\nexport interface VisaPaymentExtra {\n  /** Visa Token Service provisioned token ID */\n  vProvisionedTokenID: string\n  /** VIC instruction ID from mandate creation */\n  instructionId: string\n  /** Maximum number of times this payment can be used */\n  maxUsage: number\n  /** Merchant name */\n  merchantName?: string\n  /** Merchant URL */\n  merchantUrl?: string\n  /** Merchant country code */\n  merchantCountryCode?: string\n}\n\n/**\n * Visa payment requirements (x402 v2 with scheme: \"visa\")\n */\nexport interface VisaPaymentRequirements {\n  scheme: 'visa'\n  network: 'visa:vts'\n  amount: string\n  asset: string\n  payTo: string\n  maxTimeoutSeconds: number\n  extra: VisaPaymentExtra\n}\n\n/**\n * Visa-specific PaymentRequired response\n */\nexport interface VisaPaymentRequired {\n  x402Version: 2\n  error?: string\n  resource: X402Resource\n  accepts: VisaPaymentRequirements[]\n  extensions?: Record<string, unknown>\n}\n\n/**\n * Visa verify response\n */\nexport interface VisaVerifyResponse {\n  isValid: boolean\n  payer?: string\n  invalidReason?: string\n  remainingUsage?: number\n}\n\n/**\n * Visa settlement response\n */\nexport interface VisaSettlementResponse {\n  success: boolean\n  transaction: string\n  network: 'visa:vts'\n  payer?: string\n  errorReason?: string\n}\n\n// ---------------------------------------------------------------------------\n// Visa x402 header names\n// ---------------------------------------------------------------------------\n\nexport const VISA_X402_HEADERS = {\n  PAYMENT_REQUIRED: 'PAYMENT-REQUIRED',\n  PAYMENT_SIGNATURE: 'PAYMENT-SIGNATURE',\n  PAYMENT_RESPONSE: 'PAYMENT-RESPONSE',\n} as const\n\n// ---------------------------------------------------------------------------\n// Helper: build a Visa PaymentRequired\n// ---------------------------------------------------------------------------\n\n/**\n * Build a Visa-flavored X402PaymentRequired object.\n *\n * This is the Visa counterpart of `buildPaymentRequired` (which builds NVM-flavored ones).\n */\nexport function buildVisaPaymentRequired(options: {\n  amount: string\n  asset?: string\n  payTo: string\n  endpoint?: string\n  description?: string\n  maxTimeoutSeconds?: number\n  merchantName?: string\n  merchantUrl?: string\n  merchantCountryCode?: string\n}): VisaPaymentRequired {\n  const {\n    amount,\n    asset = 'USD',\n    payTo,\n    endpoint = '',\n    description,\n    maxTimeoutSeconds = 3600,\n    merchantName,\n    merchantUrl,\n    merchantCountryCode,\n  } = options\n\n  return {\n    x402Version: 2,\n    resource: {\n      url: endpoint,\n      ...(description && { description }),\n    },\n    accepts: [\n      {\n        scheme: 'visa',\n        network: 'visa:vts',\n        amount,\n        asset,\n        payTo,\n        maxTimeoutSeconds,\n        extra: {\n          vProvisionedTokenID: '',\n          instructionId: '',\n          maxUsage: 1,\n          ...(merchantName && { merchantName }),\n          ...(merchantUrl && { merchantUrl }),\n          ...(merchantCountryCode && { merchantCountryCode }),\n        },\n      },\n    ],\n  }\n}\n\n// ---------------------------------------------------------------------------\n// VisaFacilitatorAPI\n// ---------------------------------------------------------------------------\n\n/**\n * Visa Facilitator API — sends PAYMENT-SIGNATURE header to the Visa backend\n * for verify and settle operations.\n */\nexport class VisaFacilitatorAPI extends FacilitatorAPI {\n  protected visaBackendUrl: string\n\n  constructor(options: PaymentOptions) {\n    super(options)\n    this.visaBackendUrl = VisaBackendUrls[this.environmentName]\n  }\n\n  static override getInstance(options: PaymentOptions): VisaFacilitatorAPI {\n    return new VisaFacilitatorAPI(options)\n  }\n\n  /**\n   * Verify a Visa payment authorization.\n   *\n   * Sends the base64-encoded PaymentPayload as a PAYMENT-SIGNATURE header\n   * to the Visa backend's POST /verify endpoint.\n   *\n   * @param params - contains x402AccessToken, the base64-encoded PaymentPayload from the client\n   */\n  override async verifyPermissions(\n    params: VerifyPermissionsParams,\n  ): Promise<VerifyPermissionsResult> {\n    const { x402AccessToken } = params\n    const url = new URL('verify', this.visaBackendUrl)\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          [VISA_X402_HEADERS.PAYMENT_SIGNATURE]: x402AccessToken,\n        },\n      })\n\n      if (!response.ok) {\n        let errorMessage = 'Visa payment verification failed'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.invalidReason || errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.fromBackend(errorMessage, {\n          message: errorMessage,\n          code: `HTTP ${response.status}`,\n        })\n      }\n\n      const visaResult: VisaVerifyResponse = await response.json()\n\n      // Map Visa response to the standard VerifyPermissionsResult shape\n      return {\n        isValid: visaResult.isValid,\n        payer: visaResult.payer,\n        invalidReason: visaResult.invalidReason,\n      }\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.fromBackend('Network error during Visa payment verification', {\n        message: error instanceof Error ? error.message : String(error),\n        code: 'network_error',\n      })\n    }\n  }\n\n  /**\n   * Settle a Visa payment transaction.\n   *\n   * Sends the base64-encoded PaymentPayload as a PAYMENT-SIGNATURE header\n   * to the Visa backend's POST /settle endpoint.\n   *\n   * @param params - contains x402AccessToken, the base64-encoded PaymentPayload from the client\n   */\n  override async settlePermissions(\n    params: SettlePermissionsParams,\n  ): Promise<SettlePermissionsResult> {\n    const { x402AccessToken } = params\n    const url = new URL('settle', this.visaBackendUrl)\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          [VISA_X402_HEADERS.PAYMENT_SIGNATURE]: x402AccessToken,\n        },\n      })\n\n      if (!response.ok) {\n        let errorMessage = 'Visa payment settlement failed'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.errorReason || errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.fromBackend(errorMessage, {\n          message: errorMessage,\n          code: `HTTP ${response.status}`,\n        })\n      }\n\n      const visaResult: VisaSettlementResponse = await response.json()\n\n      // Map Visa response to the standard SettlePermissionsResult shape\n      return {\n        success: visaResult.success,\n        transaction: visaResult.transaction,\n        network: visaResult.network,\n        payer: visaResult.payer,\n        errorReason: visaResult.errorReason,\n      }\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.fromBackend('Network error during Visa payment settlement', {\n        message: error instanceof Error ? error.message : String(error),\n        code: 'network_error',\n      })\n    }\n  }\n}\n"]}