@4mica/x402 1.0.0 → 1.0.1

package/README.md

@@ -277,20 +277,6 @@ const client = new x402Client()
 const fetchWithPayment = wrapFetchWithPayment(fetch, client);
 ```
 
-## V2 Validation Policy Notes
-
-For x402 V2 requests, include validation policy metadata in `paymentRequirements.extra`:
-
-- `validationRegistryAddress`
-- `validatorAddress`
-- `validatorAgentId`
-- `minValidationScore`
-- optional `requiredValidationTag`
-
-`validationChainId` is optional. When omitted, the underlying 4mica SDK derives the
-`validation_chain_id` from the CAIP-2 `network` value (for example, `eip155:1`).
-If `validationChainId` is provided, it must match that network chain id.
-
 ## Complete Example
 
 ### Server

package/demo/src/deposit.ts

@@ -2,8 +2,6 @@ import 'dotenv/config'
 import { privateKeyToAccount } from 'viem/accounts'
 import { Client, ConfigBuilder } from '@4mica/sdk'
 
-const USDC_ADDRESS = '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238'
-
 async function main() {
   const privateKey = process.env.PRIVATE_KEY
   if (!privateKey || !privateKey.startsWith('0x')) {

package/dist/client/scheme.js

@@ -49,9 +49,21 @@ export class FourMicaEvmScheme {
             };
         }
         else if (x402Version === 2) {
+            const resourcePayload = paymentRequirements.extra &&
+                typeof paymentRequirements.extra === 'object' &&
+                'resource' in paymentRequirements.extra &&
+                typeof paymentRequirements.extra.resource === 'object' &&
+                paymentRequirements.extra.resource !== null
+                ? paymentRequirements.extra.resource
+                : {};
+            const resource = {
+                url: String(resourcePayload.url ?? ''),
+                description: String(resourcePayload.description ?? ''),
+                mimeType: String(resourcePayload.mimeType ?? ''),
+            };
             const paymentRequired = {
                 x402Version: 2,
-                resource: { url: '', description: '', mimeType: '' },
+                resource,
                 accepts: [paymentRequirements],
             };
             const signed = await x402Flow.signPaymentV2(paymentRequired, paymentRequirements, this.signer.address);

package/dist/server/express/index.js

@@ -2,11 +2,14 @@ import { x402HTTPResourceServer, x402ResourceServer, } from '@x402/core/server';
 import { ExpressAdapter } from './adapter.js';
 import { FourMicaEvmScheme, SUPPORTED_NETWORKS } from '../scheme.js';
 import { FourMicaFacilitatorClient } from '../facilitator.js';
+function getHTTPServerInternals(httpServer) {
+    return httpServer;
+}
 function registerNetworkServers(httpServer, tabEndpoint) {
     const schemeServer = new FourMicaEvmScheme(tabEndpoint);
+    const server = getHTTPServerInternals(httpServer);
     SUPPORTED_NETWORKS.forEach((network) => {
-        ;
-        httpServer.ResourceServer.register(network, schemeServer);
+        server.ResourceServer.register(network, schemeServer);
     });
 }
 function checkIfBazaarNeeded(routes) {
@@ -17,6 +20,13 @@ function checkIfBazaarNeeded(routes) {
         return !!(routeConfig.extensions && 'bazaar' in routeConfig.extensions);
     });
 }
+function isOpenTabHttpError(error) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    const candidate = error;
+    return typeof candidate.status === 'number' && 'response' in candidate;
+}
 /**
  * Express payment middleware for x402 protocol (direct HTTP server instance).
  *
@@ -57,12 +67,12 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
     // Dynamically register bazaar extension if routes declare it and not already registered
     // Skip if pre-registered (e.g., in serverless environments where static imports are used)
     let bazaarPromise = null;
-    if (checkIfBazaarNeeded(httpServer.routesConfig) &&
-        !httpServer.ResourceServer.hasExtension('bazaar')) {
+    const httpServerInternals = getHTTPServerInternals(httpServer);
+    if (checkIfBazaarNeeded(httpServerInternals.routesConfig) &&
+        !httpServerInternals.ResourceServer.hasExtension('bazaar')) {
         bazaarPromise = import('@x402/extensions/bazaar')
             .then(({ bazaarResourceServerExtension }) => {
-            ;
-            httpServer.ResourceServer.registerExtension(bazaarResourceServerExtension);
+            httpServerInternals.ResourceServer.registerExtension(bazaarResourceServerExtension);
         })
             .catch((err) => {
             console.error('Failed to load bazaar extension:', err);
@@ -82,9 +92,8 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
                     return res.json(openTabResponse);
                 }
                 catch (error) {
-                    if (error instanceof Error && 'status' in error) {
-                        const openTabError = error;
-                        return res.status(openTabError.status).json(openTabError.response);
+                    if (isOpenTabHttpError(error)) {
+                        return res.status(error.status).json(error.response);
                     }
                     console.error('Failed to open tab:', error);
                     return res.status(500).json({
@@ -126,7 +135,7 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
             case 'no-payment-required':
                 // No payment needed, proceed directly to the route handler
                 return next();
-            case 'payment-error':
+            case 'payment-error': {
                 // Payment required but not provided or invalid
                 const { response } = result;
                 res.status(response.status);
@@ -140,7 +149,8 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
                     res.json(response.body || {});
                 }
                 return;
-            case 'payment-verified':
+            }
+            case 'payment-verified': {
                 // Payment is valid, need to wrap response for settlement
                 const { paymentPayload, paymentRequirements } = result;
                 // Intercept and buffer all core methods that can commit response to client
@@ -256,6 +266,7 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
                     bufferedCalls = [];
                 }
                 return;
+            }
         }
     };
 }

package/dist/server/facilitator.d.ts

@@ -1,5 +1,5 @@
 import { FacilitatorConfig, HTTPFacilitatorClient } from '@x402/core/server';
-import { Network, PaymentRequirements } from '@x402/core/types';
+import { Network, PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
 export interface OpenTabRequest {
     userAddress: string;
     recipientAddress: string;
@@ -16,6 +16,16 @@ export interface OpenTabResponse {
     ttlSeconds: number;
     nextReqId: string;
 }
+export interface CertificateResponse {
+    claims: string;
+    signature: string;
+}
+export type FourMicaSettleResponse = SettleResponse & {
+    certificate?: CertificateResponse;
+    txHash?: string;
+    networkId?: string;
+    error?: string;
+};
 export declare class OpenTabError extends Error {
     readonly status: number;
     readonly response: OpenTabResponse;
@@ -24,6 +34,7 @@ export declare class OpenTabError extends Error {
 export declare class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
     constructor(config?: FacilitatorConfig);
     openTab(userAddress: string, paymentRequirements: PaymentRequirements, ttlSeconds?: number): Promise<OpenTabResponse>;
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<FourMicaSettleResponse>;
     /**
      * Helper to convert objects to JSON-safe format.
      * Handles BigInt and other non-JSON types.

package/dist/server/facilitator.js

@@ -39,6 +39,28 @@ export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
         }
         throw new Error(`Facilitator openTab failed (${response.status}): ${JSON.stringify(data)}`);
     }
+    async settle(paymentPayload, paymentRequirements) {
+        let headers = {
+            'Content-Type': 'application/json',
+        };
+        const authHeaders = await this.createAuthHeaders('settle');
+        headers = { ...headers, ...authHeaders.headers };
+        const response = await fetch(`${this.url}/settle`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(this.safeJson({
+                x402Version: paymentPayload.x402Version,
+                paymentPayload,
+                paymentRequirements,
+            })),
+        });
+        const data = (await response.json());
+        const normalized = normalizeSettleResponse(data, paymentRequirements);
+        if (!response.ok || !normalized.success) {
+            throw new Error(`Facilitator settle failed (${response.status}): ${normalized.errorReason ?? normalized.error ?? 'unknown error'}`);
+        }
+        return normalized;
+    }
     /**
      * Helper to convert objects to JSON-safe format.
      * Handles BigInt and other non-JSON types.
@@ -50,3 +72,55 @@ export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
         return JSON.parse(JSON.stringify(obj, (_, value) => (typeof value === 'bigint' ? value.toString() : value)));
     }
 }
+function normalizeSettleResponse(payload, requirements) {
+    const transaction = String(payload.transaction ??
+        payload.transactionHash ??
+        payload.txHash ??
+        payload.tx_hash ??
+        payload.hash ??
+        '');
+    const network = String(payload.network ?? payload.networkId ?? payload.network_id ?? requirements.network);
+    const errorReason = typeof payload.errorReason === 'string'
+        ? payload.errorReason
+        : typeof payload.error_reason === 'string'
+            ? payload.error_reason
+            : typeof payload.error === 'string'
+                ? payload.error
+                : typeof payload.message === 'string'
+                    ? payload.message
+                    : undefined;
+    const certificate = payload.certificate &&
+        typeof payload.certificate === 'object' &&
+        typeof payload.certificate.claims === 'string' &&
+        typeof payload.certificate.signature === 'string'
+        ? {
+            claims: payload.certificate.claims,
+            signature: payload.certificate.signature,
+        }
+        : undefined;
+    return {
+        success: Boolean(payload.success ?? errorReason === undefined),
+        errorReason,
+        payer: typeof payload.payer === 'string'
+            ? payload.payer
+            : typeof payload.userAddress === 'string'
+                ? payload.userAddress
+                : typeof payload.user_address === 'string'
+                    ? payload.user_address
+                    : undefined,
+        transaction,
+        network,
+        certificate,
+        txHash: typeof payload.txHash === 'string'
+            ? payload.txHash
+            : typeof payload.tx_hash === 'string'
+                ? payload.tx_hash
+                : transaction || undefined,
+        networkId: typeof payload.networkId === 'string'
+            ? payload.networkId
+            : typeof payload.network_id === 'string'
+                ? payload.network_id
+                : network,
+        error: typeof payload.error === 'string' ? payload.error : undefined,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4mica/x402",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "TypeScript x402 utilities for interacting with the 4Mica payment network",
   "license": "MIT",

package/src/server/express/index.ts

@@ -36,10 +36,26 @@ interface TabConfig {
   ttlSeconds?: number
 }
 
+interface ResourceServerInternals {
+  register: (network: Network, server: SchemeNetworkServer) => unknown
+  hasExtension: (extension: string) => boolean
+  registerExtension: (extension: unknown) => unknown
+}
+
+interface HTTPServerInternals {
+  ResourceServer: ResourceServerInternals
+  routesConfig: RoutesConfig
+}
+
+function getHTTPServerInternals(httpServer: x402HTTPResourceServer): HTTPServerInternals {
+  return httpServer as unknown as HTTPServerInternals
+}
+
 function registerNetworkServers(httpServer: x402HTTPResourceServer, tabEndpoint: string) {
   const schemeServer = new FourMicaEvmScheme(tabEndpoint)
+  const server = getHTTPServerInternals(httpServer)
   SUPPORTED_NETWORKS.forEach((network) => {
-    ;(httpServer as any).ResourceServer.register(network, schemeServer)
+    server.ResourceServer.register(network, schemeServer)
   })
 }
 
@@ -53,6 +69,20 @@ function checkIfBazaarNeeded(routes: RoutesConfig): boolean {
   })
 }
 
+interface OpenTabHttpError {
+  status: number
+  response: unknown
+}
+
+function isOpenTabHttpError(error: unknown): error is OpenTabHttpError {
+  if (typeof error !== 'object' || error === null) {
+    return false
+  }
+
+  const candidate = error as { status?: unknown; response?: unknown }
+  return typeof candidate.status === 'number' && 'response' in candidate
+}
+
 /**
  * Configuration for registering a payment scheme with a specific network
  */
@@ -118,13 +148,14 @@ export function paymentMiddlewareFromHTTPServer(
   // Dynamically register bazaar extension if routes declare it and not already registered
   // Skip if pre-registered (e.g., in serverless environments where static imports are used)
   let bazaarPromise: Promise<void> | null = null
+  const httpServerInternals = getHTTPServerInternals(httpServer)
   if (
-    checkIfBazaarNeeded((httpServer as any).routesConfig) &&
-    !(httpServer as any).ResourceServer.hasExtension('bazaar')
+    checkIfBazaarNeeded(httpServerInternals.routesConfig) &&
+    !httpServerInternals.ResourceServer.hasExtension('bazaar')
   ) {
     bazaarPromise = import('@x402/extensions/bazaar')
       .then(({ bazaarResourceServerExtension }) => {
-        ;(httpServer as any).ResourceServer.registerExtension(bazaarResourceServerExtension)
+        httpServerInternals.ResourceServer.registerExtension(bazaarResourceServerExtension)
       })
       .catch((err) => {
         console.error('Failed to load bazaar extension:', err)
@@ -150,9 +181,8 @@ export function paymentMiddlewareFromHTTPServer(
           // Return the response
           return res.json(openTabResponse)
         } catch (error) {
-          if (error instanceof Error && 'status' in error) {
-            const openTabError = error as any
-            return res.status(openTabError.status).json(openTabError.response)
+          if (isOpenTabHttpError(error)) {
+            return res.status(error.status).json(error.response)
           }
           console.error('Failed to open tab:', error)
           return res.status(500).json({
@@ -200,7 +230,7 @@ export function paymentMiddlewareFromHTTPServer(
         // No payment needed, proceed directly to the route handler
         return next()
 
-      case 'payment-error':
+      case 'payment-error': {
         // Payment required but not provided or invalid
         const { response } = result
         res.status(response.status)
@@ -213,8 +243,9 @@ export function paymentMiddlewareFromHTTPServer(
           res.json(response.body || {})
         }
         return
+      }
 
-      case 'payment-verified':
+      case 'payment-verified': {
         // Payment is valid, need to wrap response for settlement
         const { paymentPayload, paymentRequirements } = result
 
@@ -346,6 +377,7 @@ export function paymentMiddlewareFromHTTPServer(
           bufferedCalls = []
         }
         return
+      }
     }
   }
 }

package/tests/client-scheme.test.ts

@@ -24,9 +24,7 @@ describe('FourMicaEvmScheme', () => {
       signPaymentV2,
     } as never)
 
-    const scheme = await FourMicaEvmScheme.create(
-      privateKeyToAccount(`0x${'11'.repeat(32)}`)
-    )
+    const scheme = await FourMicaEvmScheme.create(privateKeyToAccount(`0x${'11'.repeat(32)}`))
 
     const requirements = {
       scheme: '4mica-credit',
@@ -84,9 +82,7 @@ describe('FourMicaEvmScheme', () => {
       signPaymentV2: vi.fn(),
     } as never)
 
-    const scheme = await FourMicaEvmScheme.create(
-      privateKeyToAccount(`0x${'11'.repeat(32)}`)
-    )
+    const scheme = await FourMicaEvmScheme.create(privateKeyToAccount(`0x${'11'.repeat(32)}`))
 
     await expect(
       scheme.createPaymentPayload(3, {