npm - @okxweb3/app-x402-express - Versions diffs - 0.1.2 - Mend

@okxweb3/app-x402-express 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,174 @@
+# @okxweb3/app-x402-express
+Express middleware for the x402 Payment Protocol. Adds x402 payment requirements to Express.js applications.
+## Installation
+```bash
+npm install @okxweb3/app-x402-express
+```
+## Quick Start
+```typescript
+import express from "express";
+import { paymentMiddleware, x402ResourceServer } from "@okxweb3/app-x402-express";
+import { ExactEvmScheme } from "@okxweb3/app-x402-evm/exact/server";
+import { OKXFacilitatorClient } from "@okxweb3/app-x402-core";
+const app = express();
+const facilitatorClient = new OKXFacilitatorClient();
+const resourceServer = new x402ResourceServer(facilitatorClient)
+  .register("eip155:196", new ExactEvmScheme());
+app.use(
+  paymentMiddleware(
+    {
+      "GET /protected-route": {
+        accepts: {
+          scheme: "exact",
+          price: "$0.10",
+          network: "eip155:196",
+          payTo: "0xYourAddress",
+        },
+        description: "Access to premium content",
+      },
+    },
+    resourceServer,
+  ),
+);
+app.get("/protected-route", (req, res) => {
+  res.json({ message: "Premium content" });
+});
+app.listen(3000);
+```
+## API Reference
+### paymentMiddleware
+```typescript
+function paymentMiddleware(
+  routes: RoutesConfig,
+  server: x402ResourceServer,
+  paywallConfig?: PaywallConfig,
+  paywall?: PaywallProvider,
+  syncFacilitatorOnStart?: boolean,
+): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+```
+Creates Express middleware that:
+1. Checks if the incoming request matches a protected route
+2. Validates payment headers if required
+3. Returns payment instructions (402 status) if payment is missing or invalid
+4. Processes the request if payment is valid
+5. Handles settlement after successful response
+#### Parameters
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `routes` | Yes | Route configurations for protected endpoints |
+| `server` | Yes | Pre-configured `x402ResourceServer` instance |
+| `paywallConfig` | No | Configuration for the built-in paywall UI shown to browser visitors (`Accept: text/html` + `Mozilla` UA). Ignored for API/SDK clients. |
+| `paywall` | No | Custom `PaywallProvider` that overrides the default HTML generator. Only used for browser visitors. |
+| `syncFacilitatorOnStart` | No | Whether to sync with facilitator on startup (default: `true`) |
+### Paywall
+When an unpaid request comes from a web browser (`Accept` header contains `text/html` **and** `User-Agent` contains `Mozilla`), the middleware returns an HTML paywall page instead of a JSON 402. API/SDK clients are unaffected — they continue to receive JSON 402 with the `PAYMENT-REQUIRED` header.
+`paywallConfig` lets you brand the built-in paywall:
+```typescript
+import { paymentMiddleware, PaywallConfig } from "@okxweb3/app-x402-express";
+const paywallConfig: PaywallConfig = {
+  appName: "My App",
+  appLogo: "https://example.com/logo.png",
+  currentUrl: "https://example.com/protected",
+  testnet: false,
+};
+app.use(paymentMiddleware(routes, resourceServer, paywallConfig));
+```
+`paywall` lets you fully replace the HTML generator:
+```typescript
+import { paymentMiddleware, PaywallProvider } from "@okxweb3/app-x402-express";
+const customPaywall: PaywallProvider = {
+  generateHtml(paymentRequired, config) {
+    return `<!DOCTYPE html><html>... your UI ...</html>`;
+  },
+};
+app.use(paymentMiddleware(routes, resourceServer, undefined, customPaywall));
+```
+You can also set a per-route HTML template via `RouteConfig.customPaywallHtml`, which takes precedence over both `paywall` and the default generator.
+If you don't need a browser paywall (machine-to-machine APIs only), leave both `paywallConfig` and `paywall` as `undefined` — the paywall code path is never reached for non-browser clients.
+### setSettlementOverrides
+```typescript
+function setSettlementOverrides(res: Response, overrides: SettlementOverrides): void;
+```
+Set settlement overrides on the response for partial settlement.
+### Route Configuration
+```typescript
+const routes: RoutesConfig = {
+  "GET /api/protected": {
+    accepts: {
+      scheme: "exact",
+      price: "$0.10",
+      network: "eip155:196",
+      payTo: "0xYourAddress",
+      maxTimeoutSeconds: 60,
+    },
+    description: "Premium API access",
+  },
+};
+app.use(paymentMiddleware(routes, resourceServer));
+```
+### Multiple Protected Routes
+```typescript
+app.use(
+  paymentMiddleware(
+    {
+      "GET /api/premium/*": {
+        accepts: {
+          scheme: "exact",
+          price: "$1.00",
+          network: "eip155:196",
+          payTo: "0xYourAddress",
+        },
+        description: "Premium API access",
+      },
+      "GET /api/data": {
+        accepts: {
+          scheme: "exact",
+          price: "$0.50",
+          network: "eip155:196",
+          payTo: "0xYourAddress",
+          maxTimeoutSeconds: 120,
+        },
+        description: "Data endpoint access",
+      },
+    },
+    resourceServer,
+  ),
+);
+```

package/dist/cjs/index.d.ts ADDED Viewed

@@ -0,0 +1,176 @@
+import { HTTPAdapter, RoutesConfig, x402ResourceServer, PaywallConfig, PaywallProvider, FacilitatorClient, x402HTTPResourceServer, SettlementOverrides } from '@okxweb3/app-x402-core/server';
+export { PaywallConfig, PaywallProvider, RouteConfigurationError, RouteValidationError, SETTLEMENT_OVERRIDES_HEADER, SettlementOverrides, x402HTTPResourceServer, x402ResourceServer } from '@okxweb3/app-x402-core/server';
+import { Network, SchemeNetworkServer } from '@okxweb3/app-x402-core/types';
+export { Network, PaymentPayload, PaymentRequired, PaymentRequirements, SchemeNetworkServer } from '@okxweb3/app-x402-core/types';
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Express adapter implementation
+ */
+declare class ExpressAdapter implements HTTPAdapter {
+    private req;
+    /**
+     * Creates a new ExpressAdapter instance.
+     *
+     * @param req - The Express request object
+     */
+    constructor(req: Request);
+    /**
+     * Gets a header value from the request.
+     *
+     * @param name - The header name
+     * @returns The header value or undefined
+     */
+    getHeader(name: string): string | undefined;
+    /**
+     * Gets the HTTP method of the request.
+     *
+     * @returns The HTTP method
+     */
+    getMethod(): string;
+    /**
+     * Gets the path of the request.
+     *
+     * @returns The request path
+     */
+    getPath(): string;
+    /**
+     * Gets the full URL of the request.
+     *
+     * @returns The full request URL
+     */
+    getUrl(): string;
+    /**
+     * Gets the Accept header from the request.
+     *
+     * @returns The Accept header value or empty string
+     */
+    getAcceptHeader(): string;
+    /**
+     * Gets the User-Agent header from the request.
+     *
+     * @returns The User-Agent header value or empty string
+     */
+    getUserAgent(): string;
+    /**
+     * Gets all query parameters from the request URL.
+     *
+     * @returns Record of query parameter key-value pairs
+     */
+    getQueryParams(): Record<string, string | string[]>;
+    /**
+     * Gets a specific query parameter by name.
+     *
+     * @param name - The query parameter name
+     * @returns The query parameter value(s) or undefined
+     */
+    getQueryParam(name: string): string | string[] | undefined;
+    /**
+     * Gets the parsed request body.
+     * Requires express.json() or express.urlencoded() middleware.
+     *
+     * @returns The parsed request body
+     */
+    getBody(): unknown;
+}
+/**
+ * Set settlement overrides on the response for partial settlement.
+ * The middleware will extract these before settlement and strip the header from the client response.
+ *
+ * @param res - Express response object
+ * @param overrides - Settlement overrides (e.g., { amount: "500" } for partial settlement)
+ */
+declare function setSettlementOverrides(res: Response, overrides: SettlementOverrides): void;
+/**
+ * Configuration for registering a payment scheme with a specific network
+ */
+interface SchemeRegistration {
+    /**
+     * The network identifier (e.g., 'eip155:196', 'eip155:196')
+     */
+    network: Network;
+    /**
+     * The scheme server implementation for this network
+     */
+    server: SchemeNetworkServer;
+}
+/**
+ * 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 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 "@okxweb3/app-x402-express";
+ *
+ * const resourceServer = new x402ResourceServer(facilitatorClient)
+ *   .register(NETWORK, new ExactEvmScheme())
+ *
+ * const httpServer = new x402HTTPResourceServer(resourceServer, routes)
+ *   .onProtectedRequest(requestHook);
+ *
+ * app.use(paymentMiddlewareFromHTTPServer(httpServer));
+ * ```
+ */
+declare function paymentMiddlewareFromHTTPServer(httpServer: x402HTTPResourceServer, paywallConfig?: PaywallConfig, paywall?: PaywallProvider, syncFacilitatorOnStart?: boolean): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * 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 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 "@okxweb3/app-x402-express";
+ *
+ * const server = new x402ResourceServer(myFacilitatorClient)
+ *   .register(NETWORK, new ExactEvmScheme());
+ *
+ * app.use(paymentMiddleware(routes, server, paywallConfig));
+ * ```
+ */
+declare function paymentMiddleware(routes: RoutesConfig, server: x402ResourceServer, paywallConfig?: PaywallConfig, paywall?: PaywallProvider, syncFacilitatorOnStart?: boolean): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * 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 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 "@okxweb3/app-x402-express";
+ *
+ * app.use(paymentMiddlewareFromConfig(
+ *   routes,
+ *   myFacilitatorClient,
+ *   [{ network: "eip155:196", server: evmSchemeServer }],
+ *   paywallConfig
+ * ));
+ * ```
+ */
+declare function paymentMiddlewareFromConfig(routes: RoutesConfig, facilitatorClients?: FacilitatorClient | FacilitatorClient[], schemes?: SchemeRegistration[], paywallConfig?: PaywallConfig, paywall?: PaywallProvider, syncFacilitatorOnStart?: boolean): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+export { ExpressAdapter, type SchemeRegistration, paymentMiddleware, paymentMiddlewareFromConfig, paymentMiddlewareFromHTTPServer, setSettlementOverrides };

package/dist/cjs/index.js ADDED Viewed

@@ -0,0 +1,357 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ExpressAdapter: () => ExpressAdapter,
+  RouteConfigurationError: () => import_server3.RouteConfigurationError,
+  SETTLEMENT_OVERRIDES_HEADER: () => import_server3.SETTLEMENT_OVERRIDES_HEADER,
+  paymentMiddleware: () => paymentMiddleware,
+  paymentMiddlewareFromConfig: () => paymentMiddlewareFromConfig,
+  paymentMiddlewareFromHTTPServer: () => paymentMiddlewareFromHTTPServer,
+  setSettlementOverrides: () => setSettlementOverrides,
+  x402HTTPResourceServer: () => import_server2.x402HTTPResourceServer,
+  x402ResourceServer: () => import_server2.x402ResourceServer
+});
+module.exports = __toCommonJS(src_exports);
+var import_server = require("@okxweb3/app-x402-core/server");
+// src/adapter.ts
+var ExpressAdapter = class {
+  /**
+   * Creates a new ExpressAdapter instance.
+   *
+   * @param req - The Express request object
+   */
+  constructor(req) {
+    this.req = req;
+  }
+  /**
+   * Gets a header value from the request.
+   *
+   * @param name - The header name
+   * @returns The header value or undefined
+   */
+  getHeader(name) {
+    const value = this.req.header(name);
+    return Array.isArray(value) ? value[0] : value;
+  }
+  /**
+   * Gets the HTTP method of the request.
+   *
+   * @returns The HTTP method
+   */
+  getMethod() {
+    return this.req.method;
+  }
+  /**
+   * Gets the path of the request.
+   *
+   * @returns The request path
+   */
+  getPath() {
+    return this.req.path;
+  }
+  /**
+   * Gets the full URL of the request.
+   *
+   * @returns The full request URL
+   */
+  getUrl() {
+    return `${this.req.protocol}://${this.req.headers.host}${this.req.originalUrl}`;
+  }
+  /**
+   * Gets the Accept header from the request.
+   *
+   * @returns The Accept header value or empty string
+   */
+  getAcceptHeader() {
+    return this.req.header("Accept") || "";
+  }
+  /**
+   * Gets the User-Agent header from the request.
+   *
+   * @returns The User-Agent header value or empty string
+   */
+  getUserAgent() {
+    return this.req.header("User-Agent") || "";
+  }
+  /**
+   * Gets all query parameters from the request URL.
+   *
+   * @returns Record of query parameter key-value pairs
+   */
+  getQueryParams() {
+    return this.req.query;
+  }
+  /**
+   * Gets a specific query parameter by name.
+   *
+   * @param name - The query parameter name
+   * @returns The query parameter value(s) or undefined
+   */
+  getQueryParam(name) {
+    const value = this.req.query[name];
+    return value;
+  }
+  /**
+   * Gets the parsed request body.
+   * Requires express.json() or express.urlencoded() middleware.
+   *
+   * @returns The parsed request body
+   */
+  getBody() {
+    return this.req.body;
+  }
+};
+// src/index.ts
+var import_server2 = require("@okxweb3/app-x402-core/server");
+var import_server3 = require("@okxweb3/app-x402-core/server");
+function setSettlementOverrides(res, overrides) {
+  res.setHeader(import_server.SETTLEMENT_OVERRIDES_HEADER, JSON.stringify(overrides));
+}
+function sendFacilitatorError(res, error) {
+  res.status(502).json({ error: error.message });
+}
+function paymentMiddlewareFromHTTPServer(httpServer, paywallConfig, paywall, syncFacilitatorOnStart = true) {
+  if (paywall) {
+    httpServer.registerPaywallProvider(paywall);
+  }
+  let initPromise = syncFacilitatorOnStart ? httpServer.initialize() : null;
+  let isInitialized = false;
+  async function initializeHttpServer() {
+    if (!syncFacilitatorOnStart || isInitialized) {
+      return;
+    }
+    if (!initPromise) {
+      initPromise = httpServer.initialize();
+    }
+    try {
+      await initPromise;
+      isInitialized = true;
+    } catch (error) {
+      initPromise = null;
+      throw error;
+    }
+  }
+  return async (req, res, next) => {
+    const adapter = new ExpressAdapter(req);
+    const context = {
+      adapter,
+      path: req.path,
+      method: req.method,
+      paymentHeader: adapter.getHeader("payment-signature") || adapter.getHeader("x-payment")
+    };
+    if (!httpServer.requiresPayment(context)) {
+      return next();
+    }
+    if (syncFacilitatorOnStart && !isInitialized) {
+      try {
+        await initializeHttpServer();
+      } catch (error) {
+        const facilitatorError = (0, import_server.getFacilitatorResponseError)(error);
+        if (facilitatorError) {
+          sendFacilitatorError(res, facilitatorError);
+          return;
+        }
+        return next(error);
+      }
+    }
+    let result;
+    try {
+      result = await httpServer.processHTTPRequest(context, paywallConfig);
+    } catch (error) {
+      if (error instanceof import_server.FacilitatorResponseError) {
+        sendFacilitatorError(res, error);
+        return;
+      }
+      return next(error);
+    }
+    switch (result.type) {
+      case "no-payment-required":
+        return next();
+      case "payment-error":
+        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":
+        const { paymentPayload, paymentRequirements, declaredExtensions } = result;
+        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;
+        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]);
+            endCalled();
+            return res;
+          }
+          return originalEnd(...args);
+        };
+        res.flushHeaders = function() {
+          if (!settled) {
+            bufferedCalls.push(["flushHeaders", []]);
+            return;
+          }
+          return originalFlushHeaders();
+        };
+        next();
+        await endPromise;
+        if (res.statusCode >= 400) {
+          settled = true;
+          res.writeHead = originalWriteHead;
+          res.write = originalWrite;
+          res.end = originalEnd;
+          res.flushHeaders = originalFlushHeaders;
+          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 responseBody = Buffer.concat(
+            bufferedCalls.flatMap(
+              ([m, args]) => (m === "write" || m === "end") && args[0] ? [Buffer.from(args[0])] : []
+            )
+          );
+          const overridesHeaderValue = res.getHeader(import_server.SETTLEMENT_OVERRIDES_HEADER);
+          const responseHeaders = {};
+          if (overridesHeaderValue) {
+            responseHeaders[import_server.SETTLEMENT_OVERRIDES_HEADER] = String(overridesHeaderValue);
+            res.removeHeader(import_server.SETTLEMENT_OVERRIDES_HEADER);
+          }
+          const settleResult = await httpServer.processSettlement(
+            paymentPayload,
+            paymentRequirements,
+            declaredExtensions,
+            { request: context, responseBody, responseHeaders }
+          );
+          if (!settleResult.success) {
+            bufferedCalls = [];
+            const { response: response2 } = settleResult;
+            Object.entries(response2.headers).forEach(([key, value]) => {
+              res.setHeader(key, value);
+            });
+            if (response2.isHtml) {
+              res.status(response2.status).send(response2.body);
+            } else {
+              res.status(response2.status).json(response2.body ?? {});
+            }
+            return;
+          }
+          Object.entries(settleResult.headers).forEach(([key, value]) => {
+            res.setHeader(key, value);
+          });
+        } catch (error) {
+          if (error instanceof import_server.FacilitatorResponseError) {
+            bufferedCalls = [];
+            sendFacilitatorError(res, error);
+            return;
+          }
+          console.error(error);
+          bufferedCalls = [];
+          res.status(402).json({});
+          return;
+        } finally {
+          settled = true;
+          res.writeHead = originalWriteHead;
+          res.write = originalWrite;
+          res.end = originalEnd;
+          res.flushHeaders = originalFlushHeaders;
+          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;
+    }
+  };
+}
+function paymentMiddleware(routes, server, paywallConfig, paywall, syncFacilitatorOnStart = true) {
+  const httpServer = new import_server.x402HTTPResourceServer(server, routes);
+  return paymentMiddlewareFromHTTPServer(
+    httpServer,
+    paywallConfig,
+    paywall,
+    syncFacilitatorOnStart
+  );
+}
+function paymentMiddlewareFromConfig(routes, facilitatorClients, schemes, paywallConfig, paywall, syncFacilitatorOnStart = true) {
+  const ResourceServer = new import_server.x402ResourceServer(facilitatorClients);
+  if (schemes) {
+    schemes.forEach(({ network, server: schemeServer }) => {
+      ResourceServer.register(network, schemeServer);
+    });
+  }
+  return paymentMiddleware(routes, ResourceServer, paywallConfig, paywall, syncFacilitatorOnStart);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExpressAdapter,
+  RouteConfigurationError,
+  SETTLEMENT_OVERRIDES_HEADER,
+  paymentMiddleware,
+  paymentMiddlewareFromConfig,
+  paymentMiddlewareFromHTTPServer,
+  setSettlementOverrides,
+  x402HTTPResourceServer,
+  x402ResourceServer
+});
+//# sourceMappingURL=index.js.map