@4mica/x402 0.1.0

package/dist/server/express/index.js

@@ -0,0 +1,340 @@
+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 registerNetworkServers(httpServer, tabEndpoint) {
+    const schemeServer = new FourMicaEvmScheme(tabEndpoint);
+    SUPPORTED_NETWORKS.forEach((network) => {
+        ;
+        httpServer.ResourceServer.register(network, schemeServer);
+    });
+}
+function checkIfBazaarNeeded(routes) {
+    if ('accepts' in routes) {
+        return !!(routes.extensions && 'bazaar' in routes.extensions);
+    }
+    return Object.values(routes).some((routeConfig) => {
+        return !!(routeConfig.extensions && 'bazaar' in routeConfig.extensions);
+    });
+}
+/**
+ * Express payment middleware for x402 protocol (direct HTTP server instance).
+ *
+ * Use this when you need to configure HTTP-level hooks.
+ *
+ * @param httpServer - Pre-configured x402HTTPResourceServer instance
+ * @param tabConfig - Configuration for payment tab handling (endpoint URL and TTL)
+ * @param paywallConfig - Optional configuration for the built-in paywall UI
+ * @param paywall - Optional custom paywall provider (overrides default)
+ * @param syncFacilitatorOnStart - Whether to sync with the facilitator on startup (defaults to true)
+ * @returns Express middleware handler
+ *
+ * @example
+ * ```typescript
+ * import { paymentMiddlewareFromHTTPServer, x402ResourceServer, x402HTTPResourceServer } from "@x402/express";
+ *
+ * const resourceServer = new x402ResourceServer(facilitatorClient)
+ *   .register(NETWORK, new ExactEvmScheme())
+ *
+ * const httpServer = new x402HTTPResourceServer(resourceServer, routes)
+ *   .onProtectedRequest(requestHook);
+ *
+ * app.use(paymentMiddlewareFromHTTPServer(
+ *   httpServer,
+ *   { advertisedEndpoint: "https://api.example.com/x402/tab" },
+ * )); * ```
+ */
+export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallConfig, paywall, syncFacilitatorOnStart = true) {
+    const facilitatorClient = new FourMicaFacilitatorClient();
+    registerNetworkServers(httpServer, tabConfig.advertisedEndpoint);
+    // Register custom paywall provider if provided
+    if (paywall) {
+        httpServer.registerPaywallProvider(paywall);
+    }
+    // Store initialization promise (not the result)
+    // httpServer.initialize() fetches facilitator support and validates routes
+    let initPromise = syncFacilitatorOnStart ? httpServer.initialize() : null;
+    // 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')) {
+        bazaarPromise = import('@x402/extensions/bazaar')
+            .then(({ bazaarResourceServerExtension }) => {
+            ;
+            httpServer.ResourceServer.registerExtension(bazaarResourceServerExtension);
+        })
+            .catch((err) => {
+            console.error('Failed to load bazaar extension:', err);
+        });
+    }
+    return async (req, res, next) => {
+        // Check if this request is for the tab opening endpoint
+        try {
+            const advertisedUrl = new URL(tabConfig.advertisedEndpoint);
+            if (req.path === advertisedUrl.pathname) {
+                // Parse the request body
+                const { userAddress, paymentRequirements } = req.body;
+                try {
+                    // Call the facilitator to open the tab
+                    const openTabResponse = await facilitatorClient.openTab(userAddress, paymentRequirements, tabConfig.ttlSeconds);
+                    // Return the response
+                    return res.json(openTabResponse);
+                }
+                catch (error) {
+                    if (error instanceof Error && 'status' in error) {
+                        const openTabError = error;
+                        return res.status(openTabError.status).json(openTabError.response);
+                    }
+                    console.error('Failed to open tab:', error);
+                    return res.status(500).json({
+                        error: 'Failed to open tab',
+                        details: error instanceof Error ? error.message : 'Unknown error',
+                    });
+                }
+            }
+        }
+        catch (urlError) {
+            console.error('Invalid advertisedEndpoint URL:', urlError);
+        }
+        // Create adapter and context
+        const adapter = new ExpressAdapter(req);
+        const context = {
+            adapter,
+            path: req.path,
+            method: req.method,
+            paymentHeader: adapter.getHeader('payment-signature') || adapter.getHeader('x-payment'),
+        };
+        // Check if route requires payment before initializing facilitator
+        if (!httpServer.requiresPayment(context)) {
+            return next();
+        }
+        // Only initialize when processing a protected route
+        if (initPromise) {
+            await initPromise;
+            initPromise = null; // Clear after first await
+        }
+        // Await bazaar extension loading if needed
+        if (bazaarPromise) {
+            await bazaarPromise;
+            bazaarPromise = null;
+        }
+        // Process payment requirement check
+        const result = await httpServer.processHTTPRequest(context, paywallConfig);
+        // Handle the different result types
+        switch (result.type) {
+            case 'no-payment-required':
+                // No payment needed, proceed directly to the route handler
+                return next();
+            case 'payment-error':
+                // Payment required but not provided or invalid
+                const { response } = result;
+                res.status(response.status);
+                Object.entries(response.headers).forEach(([key, value]) => {
+                    res.setHeader(key, value);
+                });
+                if (response.isHtml) {
+                    res.send(response.body);
+                }
+                else {
+                    res.json(response.body || {});
+                }
+                return;
+            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
+                const originalWriteHead = res.writeHead.bind(res);
+                const originalWrite = res.write.bind(res);
+                const originalEnd = res.end.bind(res);
+                const originalFlushHeaders = res.flushHeaders.bind(res);
+                let bufferedCalls = [];
+                let settled = false;
+                // Create a promise that resolves when the handler finishes and calls res.end()
+                let endCalled;
+                const endPromise = new Promise((resolve) => {
+                    endCalled = resolve;
+                });
+                res.writeHead = function (...args) {
+                    if (!settled) {
+                        bufferedCalls.push(['writeHead', args]);
+                        return res;
+                    }
+                    return originalWriteHead(...args);
+                };
+                res.write = function (...args) {
+                    if (!settled) {
+                        bufferedCalls.push(['write', args]);
+                        return true;
+                    }
+                    return originalWrite(...args);
+                };
+                res.end = function (...args) {
+                    if (!settled) {
+                        bufferedCalls.push(['end', args]);
+                        // Signal that the handler has finished
+                        endCalled();
+                        return res;
+                    }
+                    return originalEnd(...args);
+                };
+                res.flushHeaders = function () {
+                    if (!settled) {
+                        bufferedCalls.push(['flushHeaders', []]);
+                        return;
+                    }
+                    return originalFlushHeaders();
+                };
+                // Proceed to the next middleware or route handler
+                next();
+                // Wait for the handler to actually call res.end() before checking status
+                await endPromise;
+                // If the response from the protected route is >= 400, do not settle payment
+                if (res.statusCode >= 400) {
+                    settled = true;
+                    res.writeHead = originalWriteHead;
+                    res.write = originalWrite;
+                    res.end = originalEnd;
+                    res.flushHeaders = originalFlushHeaders;
+                    // Replay all buffered calls in order
+                    for (const [method, args] of bufferedCalls) {
+                        if (method === 'writeHead')
+                            originalWriteHead(...args);
+                        else if (method === 'write')
+                            originalWrite(...args);
+                        else if (method === 'end')
+                            originalEnd(...args);
+                        else if (method === 'flushHeaders')
+                            originalFlushHeaders();
+                    }
+                    bufferedCalls = [];
+                    return;
+                }
+                try {
+                    const settleResult = await httpServer.processSettlement(paymentPayload, paymentRequirements);
+                    // If settlement fails, return an error and do not send the buffered response
+                    if (!settleResult.success) {
+                        bufferedCalls = [];
+                        res.status(402).json({
+                            error: 'Settlement failed',
+                            details: settleResult.errorReason,
+                        });
+                        return;
+                    }
+                    // Settlement succeeded - add headers to response
+                    Object.entries(settleResult.headers).forEach(([key, value]) => {
+                        res.setHeader(key, value);
+                    });
+                }
+                catch (error) {
+                    console.error(error);
+                    // If settlement fails, don't send the buffered response
+                    bufferedCalls = [];
+                    res.status(402).json({
+                        error: 'Settlement failed',
+                        details: error instanceof Error ? error.message : 'Unknown error',
+                    });
+                    return;
+                }
+                finally {
+                    settled = true;
+                    res.writeHead = originalWriteHead;
+                    res.write = originalWrite;
+                    res.end = originalEnd;
+                    res.flushHeaders = originalFlushHeaders;
+                    // Replay all buffered calls in order
+                    for (const [method, args] of bufferedCalls) {
+                        if (method === 'writeHead')
+                            originalWriteHead(...args);
+                        else if (method === 'write')
+                            originalWrite(...args);
+                        else if (method === 'end')
+                            originalEnd(...args);
+                        else if (method === 'flushHeaders')
+                            originalFlushHeaders();
+                    }
+                    bufferedCalls = [];
+                }
+                return;
+        }
+    };
+}
+/**
+ * Express payment middleware for x402 protocol (direct server instance).
+ *
+ * Use this when you want to pass a pre-configured x402ResourceServer instance.
+ * This provides more flexibility for testing, custom configuration, and reusing
+ * server instances across multiple middlewares.
+ *
+ * @param routes - Route configurations for protected endpoints
+ * @param server - Pre-configured x402ResourceServer instance
+ * @param tabConfig - Configuration for payment tab handling (endpoint URL and TTL)
+ * @param paywallConfig - Optional configuration for the built-in paywall UI
+ * @param paywall - Optional custom paywall provider (overrides default)
+ * @param syncFacilitatorOnStart - Whether to sync with the facilitator on startup (defaults to true)
+ * @returns Express middleware handler
+ *
+ * @example
+ * ```typescript
+ * import { paymentMiddleware } from "@x402/express";
+ *
+ * const server = new x402ResourceServer(myFacilitatorClient)
+ *   .register(NETWORK, new ExactEvmScheme());
+ *
+ * app.use(paymentMiddleware(
+ *   routes,
+ *   server,
+ *   { advertisedEndpoint: "https://api.example.com/x402/tab" },
+ * ));
+ * ```
+ */
+export function paymentMiddleware(routes, server, tabConfig, paywallConfig, paywall, syncFacilitatorOnStart = true) {
+    // Create the x402 HTTP server instance with the resource server
+    const httpServer = new x402HTTPResourceServer(server, routes);
+    return paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallConfig, paywall, syncFacilitatorOnStart);
+}
+/**
+ * Express payment middleware for x402 protocol (configuration-based).
+ *
+ * Use this when you want to quickly set up middleware with simple configuration.
+ * This function creates and configures the x402ResourceServer internally.
+ *
+ * @param routes - Route configurations for protected endpoints
+ * @param tabConfig - Configuration for payment tab handling
+ * @param facilitatorClients - Optional facilitator client(s) for payment processing
+ * @param schemes - Optional array of scheme registrations for server-side payment processing
+ * @param paywallConfig - Optional configuration for the built-in paywall UI
+ * @param paywall - Optional custom paywall provider (overrides default)
+ * @param syncFacilitatorOnStart - Whether to sync with the facilitator on startup (defaults to true)
+ * @returns Express middleware handler
+ *
+ * @example
+ * ```typescript
+ * import { paymentMiddlewareFromConfig } from "@x402/express";
+ *
+ * app.use(paymentMiddlewareFromConfig(
+ *   routes,
+ *   { advertisedEndpoint: "https://api.example.com/x402/tab" },
+ * ));
+ * ```
+ */
+export function paymentMiddlewareFromConfig(routes, tabConfig, facilitatorClients, schemes, paywallConfig, paywall, syncFacilitatorOnStart = true) {
+    const facilitators = facilitatorClients
+        ? Array.isArray(facilitatorClients)
+            ? facilitatorClients
+            : [facilitatorClients]
+        : [];
+    if (!facilitators.some((c) => c instanceof FourMicaFacilitatorClient)) {
+        facilitators.push(new FourMicaFacilitatorClient());
+    }
+    const ResourceServer = new x402ResourceServer(facilitators);
+    if (schemes) {
+        schemes.forEach(({ network, server: schemeServer }) => {
+            ResourceServer.register(network, schemeServer);
+        });
+    }
+    // Use the direct paymentMiddleware with the configured server
+    // Note: paymentMiddleware handles dynamic bazaar registration
+    return paymentMiddleware(routes, ResourceServer, tabConfig, paywallConfig, paywall, syncFacilitatorOnStart);
+}
+export { ExpressAdapter } from './adapter.js';

package/dist/server/facilitator.d.ts

@@ -0,0 +1,35 @@
+import { FacilitatorConfig, HTTPFacilitatorClient } from '@x402/core/server';
+import { Network, PaymentRequirements } from '@x402/core/types';
+export interface OpenTabRequest {
+    userAddress: string;
+    recipientAddress: string;
+    network?: Network;
+    erc20Token?: string;
+    ttlSeconds?: number;
+}
+export interface OpenTabResponse {
+    tabId: string;
+    userAddress: string;
+    recipientAddress: string;
+    assetAddress: string;
+    startTimestamp: number;
+    ttlSeconds: number;
+    nextReqId: string;
+}
+export declare class OpenTabError extends Error {
+    readonly status: number;
+    readonly response: OpenTabResponse;
+    constructor(status: number, response: OpenTabResponse);
+}
+export declare class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
+    constructor(config?: FacilitatorConfig);
+    openTab(userAddress: string, paymentRequirements: PaymentRequirements, ttlSeconds?: number): Promise<OpenTabResponse>;
+    /**
+     * Helper to convert objects to JSON-safe format.
+     * Handles BigInt and other non-JSON types.
+     *
+     * @param obj - The object to convert
+     * @returns The JSON-safe representation of the object
+     */
+    private safeJson;
+}

package/dist/server/facilitator.js

@@ -0,0 +1,52 @@
+import { HTTPFacilitatorClient } from '@x402/core/server';
+const DEFAULT_FACILITATOR_URL = 'https://x402.4mica.xyz';
+export class OpenTabError extends Error {
+    constructor(status, response) {
+        super(`OpenTab failed with status ${status}`);
+        this.status = status;
+        this.response = response;
+        this.name = 'OpenTabError';
+    }
+}
+export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
+    constructor(config) {
+        super({ ...config, url: config?.url ?? DEFAULT_FACILITATOR_URL });
+    }
+    async openTab(userAddress, paymentRequirements, ttlSeconds) {
+        let headers = {
+            'Content-Type': 'application/json',
+        };
+        const authHeaders = await this.createAuthHeaders('tabs');
+        headers = { ...headers, ...authHeaders.headers };
+        const response = await fetch(`${this.url}/tabs`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(this.safeJson({
+                userAddress,
+                recipientAddress: paymentRequirements.payTo,
+                network: paymentRequirements.network,
+                erc20Token: paymentRequirements.asset,
+                ttlSeconds,
+            })),
+        });
+        const data = await response.json();
+        if (typeof data === 'object' && data !== null && 'tabId' in data) {
+            const openTabResponse = data;
+            if (!response.ok) {
+                throw new OpenTabError(response.status, openTabResponse);
+            }
+            return openTabResponse;
+        }
+        throw new Error(`Facilitator openTab failed (${response.status}): ${JSON.stringify(data)}`);
+    }
+    /**
+     * Helper to convert objects to JSON-safe format.
+     * Handles BigInt and other non-JSON types.
+     *
+     * @param obj - The object to convert
+     * @returns The JSON-safe representation of the object
+     */
+    safeJson(obj) {
+        return JSON.parse(JSON.stringify(obj, (_, value) => (typeof value === 'bigint' ? value.toString() : value)));
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,6 @@
+export * from './facilitator.js';
+export * from './scheme.js';
+export { x402ResourceServer, x402HTTPResourceServer } from '@x402/core/server';
+export type { PaywallProvider, PaywallConfig } from '@x402/core/server';
+export { RouteConfigurationError } from '@x402/core/server';
+export type { RouteValidationError } from '@x402/core/server';

package/dist/server/index.js

@@ -0,0 +1,4 @@
+export * from './facilitator.js';
+export * from './scheme.js';
+export { x402ResourceServer, x402HTTPResourceServer } from '@x402/core/server';
+export { RouteConfigurationError } from '@x402/core/server';

package/dist/server/scheme.d.ts

@@ -0,0 +1,93 @@
+import { AssetAmount, Network, PaymentRequirements, Price, SchemeNetworkServer, MoneyParser } from '@x402/core/types';
+export declare const SUPPORTED_NETWORKS: Network[];
+/**
+ * EVM server implementation for the 4mica payment scheme.
+ */
+export declare class FourMicaEvmScheme implements SchemeNetworkServer {
+    readonly advertisedTabEndpoint: string;
+    readonly scheme = "4mica-credit";
+    private moneyParsers;
+    constructor(advertisedTabEndpoint: string);
+    /**
+     * Register a custom money parser in the parser chain.
+     * Multiple parsers can be registered - they will be tried in registration order.
+     * Each parser receives a decimal amount (e.g., 1.50 for $1.50).
+     * If a parser returns null, the next parser in the chain will be tried.
+     * The default parser is always the final fallback.
+     *
+     * @param parser - Custom function to convert amount to AssetAmount (or null to skip)
+     * @returns The server instance for chaining
+     *
+     * @example
+     * evmServer.registerMoneyParser(async (amount, network) => {
+     *   // Custom conversion logic
+     *   if (amount > 100) {
+     *     // Use different token for large amounts
+     *     return { amount: (amount * 1e18).toString(), asset: "0xCustomToken" };
+     *   }
+     *   return null; // Use next parser
+     * });
+     */
+    registerMoneyParser(parser: MoneyParser): FourMicaEvmScheme;
+    /**
+     * Parses a price into an asset amount.
+     * If price is already an AssetAmount, returns it directly.
+     * If price is Money (string | number), parses to decimal and tries custom parsers.
+     * Falls back to default conversion if all custom parsers return null.
+     *
+     * @param price - The price to parse
+     * @param network - The network to use
+     * @returns Promise that resolves to the parsed asset amount
+     */
+    parsePrice(price: Price, network: Network): Promise<AssetAmount>;
+    /**
+     * Build payment requirements for this scheme/network combination
+     *
+     * @param paymentRequirements - The base payment requirements
+     * @param supportedKind - The supported kind from facilitator (unused)
+     * @param supportedKind.x402Version - The x402 version
+     * @param supportedKind.scheme - The logical payment scheme
+     * @param supportedKind.network - The network identifier in CAIP-2 format
+     * @param supportedKind.extra - Optional extra metadata regarding scheme/network implementation details
+     * @param extensionKeys - Extension keys supported by the facilitator (unused)
+     * @returns Payment requirements ready to be sent to clients
+     */
+    enhancePaymentRequirements(paymentRequirements: PaymentRequirements, supportedKind: {
+        x402Version: number;
+        scheme: string;
+        network: Network;
+        extra?: Record<string, unknown>;
+    }, extensionKeys: string[]): Promise<PaymentRequirements>;
+    /**
+     * Parse Money (string | number) to a decimal number.
+     * Handles formats like "$1.50", "1.50", 1.50, etc.
+     *
+     * @param money - The money value to parse
+     * @returns Decimal number
+     */
+    private parseMoneyToDecimal;
+    /**
+     * Default money conversion implementation.
+     * Converts decimal amount to the default stablecoin on the specified network.
+     *
+     * @param amount - The decimal amount (e.g., 1.50)
+     * @param network - The network to use
+     * @returns The parsed asset amount in the default stablecoin
+     */
+    private defaultMoneyConversion;
+    /**
+     * Convert decimal amount to token units (e.g., 0.10 -> 100000 for 6-decimal tokens)
+     *
+     * @param decimalAmount - The decimal amount to convert
+     * @param decimals - The number of decimals for the token
+     * @returns The token amount as a string
+     */
+    private convertToTokenAmount;
+    /**
+     * Get the default asset info for a network (typically USDC)
+     *
+     * @param network - The network to get asset info for
+     * @returns The asset information including address, name, version, and decimals
+     */
+    private getDefaultAsset;
+}