x402z-server 0.1.2 → 0.1.4

package/README.md

@@ -58,11 +58,11 @@ const server = await createX402zServer({
       accepts: buildAcceptsFromConfigs(allowedPayments),
       description: "Demo content",
       mimeType: "text/plain",
+      onPaid: async () => ({
+        body: "demo content from server",
+      }),
     },
   },
-  onPaid: async () => ({
-    body: "demo content from server",
-  }),
 });
 
 server.listen(8080);
@@ -76,7 +76,10 @@ server.listen(8080);
 - `confidential.signer`: signer used to decrypt transfer amounts
 - `confidential.relayer`: FHEVM relayer instance used for decryption
 - `routes`: map of `METHOD /path` to payment requirements
-- `onPaid`: handler for successful payment (returns response body + optional headers)
+- `routes["METHOD /path"].onRequest`: optional pre-payment hook; return a response to short-circuit
+- `routes["METHOD /path"].onPaid`: handler for successful payment (returns response body + optional headers)
+  - `onPaid` receives `{ paymentRequirements, settleHeaders, request }`
+  - `request` includes `method`, `path`, `url`, and normalized `headers`
 
 ## Examples
 
@@ -101,9 +104,9 @@ const server = await createX402zServer({
       ],
       description: "Exact USDC payment demo",
       mimeType: "text/plain",
+      onPaid: async () => ({ body: "paid content" }),
     },
   },
-  onPaid: async () => ({ body: "paid content" }),
 });
 
 server.listen(8090);

package/dist/index.d.mts

@@ -60,19 +60,41 @@ type X402zRouteAccept = {
 type NoScheme = {
     scheme?: never;
 };
-type X402zRouteOptions = NoScheme & {
-    accepts: X402zRouteAccept[];
-    description: string;
-    mimeType: string;
-};
 type X402zRouteHandler = (args: {
     paymentRequirements: PaymentRequirements;
     settleHeaders: Record<string, string>;
+    request: {
+        method: string;
+        path: string;
+        url: string;
+        headers: Record<string, string>;
+    };
 }) => Promise<{
     status?: number;
     headers?: Record<string, string>;
     body: string;
 }>;
+type X402zRequestHandler = (args: {
+    method: string;
+    path: string;
+    url: string;
+    headers: Record<string, string>;
+}) => Promise<{
+    status?: number;
+    headers?: Record<string, string>;
+    body: string;
+} | void> | {
+    status?: number;
+    headers?: Record<string, string>;
+    body: string;
+} | void;
+type X402zRouteOptions = NoScheme & {
+    accepts: X402zRouteAccept[];
+    description: string;
+    mimeType: string;
+    onRequest?: X402zRequestHandler;
+    onPaid: X402zRouteHandler;
+};
 type X402zBaseServerOptions = {
     facilitatorUrl: string;
     debug?: boolean;
@@ -101,7 +123,6 @@ type X402zConfidentialServerConfig = {
 } & NoScheme;
 type X402zServerOptions = X402zBaseServerOptions & {
     routes: Record<string, X402zRouteOptions>;
-    onPaid: X402zRouteHandler;
     confidential?: X402zConfidentialServerConfig;
 } & NoScheme;
 declare function createX402zServer(config: X402zServerOptions): Promise<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>>;

package/dist/index.d.ts

@@ -60,19 +60,41 @@ type X402zRouteAccept = {
 type NoScheme = {
     scheme?: never;
 };
-type X402zRouteOptions = NoScheme & {
-    accepts: X402zRouteAccept[];
-    description: string;
-    mimeType: string;
-};
 type X402zRouteHandler = (args: {
     paymentRequirements: PaymentRequirements;
     settleHeaders: Record<string, string>;
+    request: {
+        method: string;
+        path: string;
+        url: string;
+        headers: Record<string, string>;
+    };
 }) => Promise<{
     status?: number;
     headers?: Record<string, string>;
     body: string;
 }>;
+type X402zRequestHandler = (args: {
+    method: string;
+    path: string;
+    url: string;
+    headers: Record<string, string>;
+}) => Promise<{
+    status?: number;
+    headers?: Record<string, string>;
+    body: string;
+} | void> | {
+    status?: number;
+    headers?: Record<string, string>;
+    body: string;
+} | void;
+type X402zRouteOptions = NoScheme & {
+    accepts: X402zRouteAccept[];
+    description: string;
+    mimeType: string;
+    onRequest?: X402zRequestHandler;
+    onPaid: X402zRouteHandler;
+};
 type X402zBaseServerOptions = {
     facilitatorUrl: string;
     debug?: boolean;
@@ -101,7 +123,6 @@ type X402zConfidentialServerConfig = {
 } & NoScheme;
 type X402zServerOptions = X402zBaseServerOptions & {
     routes: Record<string, X402zRouteOptions>;
-    onPaid: X402zRouteHandler;
     confidential?: X402zConfidentialServerConfig;
 } & NoScheme;
 declare function createX402zServer(config: X402zServerOptions): Promise<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>>;

package/dist/index.js

@@ -354,6 +354,35 @@ async function createX402zServer(config) {
     const adapter = buildAdapter(req);
     const method = adapter.getMethod();
     const path = adapter.getPath();
+    const routeKey = `${method} ${path}`;
+    const routeConfig = config.routes[routeKey];
+    if (routeConfig?.onRequest) {
+      const headers = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value === void 0) continue;
+        headers[key.toLowerCase()] = Array.isArray(value) ? value.join(",") : value;
+      }
+      const response = await routeConfig.onRequest({
+        method,
+        path,
+        url: adapter.getUrl(),
+        headers
+      });
+      if (response) {
+        const status = response.status ?? 200;
+        const responseHeaders = {
+          ...response.headers ?? {}
+        };
+        if (!responseHeaders["Content-Type"] && !responseHeaders["content-type"]) {
+          responseHeaders["Content-Type"] = "text/plain";
+        }
+        sendText(res, status, responseHeaders, response.body);
+        if (debugEnabled) {
+          console.debug(`[server] ${method} ${path} -> ${status} (onRequest)`);
+        }
+        return;
+      }
+    }
     const paymentHeader = adapter.getHeader("payment-signature") ?? adapter.getHeader("x402-payment") ?? adapter.getHeader("x-payment");
     if (debugEnabled) {
       console.debug(`[server] ${method} ${path}`);
@@ -470,9 +499,28 @@ async function createX402zServer(config) {
         }
       }
       const settleHeaders = settle.headers ?? {};
-      const payload = await config.onPaid({
+      if (!routeConfig) {
+        res.writeHead(500, { ...corsHeaders, "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "route_config_missing" }));
+        if (debugEnabled) {
+          console.debug(`[server] ${method} ${path} -> 500 route_config_missing`);
+        }
+        return;
+      }
+      const headers = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value === void 0) continue;
+        headers[key.toLowerCase()] = Array.isArray(value) ? value.join(",") : value;
+      }
+      const payload = await routeConfig.onPaid({
         paymentRequirements: result.paymentRequirements,
-        settleHeaders
+        settleHeaders,
+        request: {
+          method,
+          path,
+          url: adapter.getUrl(),
+          headers
+        }
       });
       const status = payload.status ?? 200;
       const responseHeaders = {

package/dist/index.mjs

@@ -318,6 +318,35 @@ async function createX402zServer(config) {
     const adapter = buildAdapter(req);
     const method = adapter.getMethod();
     const path = adapter.getPath();
+    const routeKey = `${method} ${path}`;
+    const routeConfig = config.routes[routeKey];
+    if (routeConfig?.onRequest) {
+      const headers = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value === void 0) continue;
+        headers[key.toLowerCase()] = Array.isArray(value) ? value.join(",") : value;
+      }
+      const response = await routeConfig.onRequest({
+        method,
+        path,
+        url: adapter.getUrl(),
+        headers
+      });
+      if (response) {
+        const status = response.status ?? 200;
+        const responseHeaders = {
+          ...response.headers ?? {}
+        };
+        if (!responseHeaders["Content-Type"] && !responseHeaders["content-type"]) {
+          responseHeaders["Content-Type"] = "text/plain";
+        }
+        sendText(res, status, responseHeaders, response.body);
+        if (debugEnabled) {
+          console.debug(`[server] ${method} ${path} -> ${status} (onRequest)`);
+        }
+        return;
+      }
+    }
     const paymentHeader = adapter.getHeader("payment-signature") ?? adapter.getHeader("x402-payment") ?? adapter.getHeader("x-payment");
     if (debugEnabled) {
       console.debug(`[server] ${method} ${path}`);
@@ -434,9 +463,28 @@ async function createX402zServer(config) {
         }
       }
       const settleHeaders = settle.headers ?? {};
-      const payload = await config.onPaid({
+      if (!routeConfig) {
+        res.writeHead(500, { ...corsHeaders, "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "route_config_missing" }));
+        if (debugEnabled) {
+          console.debug(`[server] ${method} ${path} -> 500 route_config_missing`);
+        }
+        return;
+      }
+      const headers = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value === void 0) continue;
+        headers[key.toLowerCase()] = Array.isArray(value) ? value.join(",") : value;
+      }
+      const payload = await routeConfig.onPaid({
         paymentRequirements: result.paymentRequirements,
-        settleHeaders
+        settleHeaders,
+        request: {
+          method,
+          path,
+          url: adapter.getUrl(),
+          headers
+        }
       });
       const status = payload.status ?? 200;
       const responseHeaders = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402z-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",