@x402kit/middleware 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# @x402-kit/middleware
+
+> One-line Express middleware for HTTP 402 payment gating on Stacks — monetize any API route with STX micropayments.
+
+[![npm version](https://img.shields.io/npm/v/@x402-kit/middleware)](https://www.npmjs.com/package/@x402-kit/middleware)
+[![license](https://img.shields.io/npm/l/@x402-kit/middleware)](./LICENSE)
+
+## Overview
+
+`@x402-kit/middleware` wraps the [x402-stacks](https://www.npmjs.com/package/x402-stacks) protocol into a single Express middleware call. Define per-route STX prices in a config object, and every matching request is automatically gated behind an HTTP 402 payment flow — receipt verification, replay protection, and all.
+
+## Installation
+
+```bash
+npm install @x402-kit/middleware
+```
+
+> **Peer dependency:** requires `express` ≥ 4.
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import { x402Paywall } from '@x402-kit/middleware';
+
+const app = express();
+
+app.use(x402Paywall({
+  prices: {
+    '/premium': '0.01 STX',
+    '/data':    '0.05 STX',
+  },
+  payTo: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
+  network: 'testnet',
+}));
+
+app.get('/premium', (req, res) => {
+  res.json({ message: 'Paid premium content' });
+});
+
+app.get('/data', (req, res) => {
+  res.json({ data: [1, 2, 3] });
+});
+
+app.get('/', (req, res) => {
+  res.send('Free homepage — no payment required');
+});
+
+app.listen(3000, () => console.log('Listening on :3000'));
+```
+
+Any request to `/premium` or `/data` will receive an HTTP 402 response unless a valid payment receipt is provided. Routes not listed in `prices` pass through normally.
+
+## API Reference
+
+### `x402Paywall(options): express.RequestHandler`
+
+Returns an Express middleware function.
+
+#### `X402Options`
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `prices` | `Record<string, string>` | ✅ | — | Map of route paths to STX price strings (e.g. `'0.01 STX'`) |
+| `payTo` | `string` | ✅ | — | Stacks address that receives payments |
+| `network` | `'mainnet' \| 'testnet'` | — | `'testnet'` | Stacks network to use |
+| `facilitatorUrl` | `string` | — | `'https://facilitator.stacksx402.xyz'` | URL of the x402 facilitator service |
+
+### How It Works
+
+1. An incoming request hits the middleware.
+2. The middleware checks if the request path has a price defined in `prices`.
+3. **If yes** — it delegates to the `x402-stacks` `paymentMiddleware`, which returns an HTTP 402 with payment instructions or validates the payment receipt attached to the request.
+4. **If no** — the request passes through to the next handler untouched.
+
+```
+Client Request
+     │
+     ▼
+x402Paywall middleware
+     │
+     ├── Path in prices? ──▶ paymentMiddleware (x402-stacks)
+     │                            │
+     │                            ├── Valid receipt? → next()
+     │                            └── No receipt?    → 402 response
+     │
+     └── Path NOT in prices? ──▶ next()
+```
+
+## Examples
+
+### Per-endpoint pricing
+
+```typescript
+app.use(x402Paywall({
+  prices: {
+    '/api/sentiment':  '0.001 STX',  // cheap
+    '/api/summarize':  '0.01 STX',   // moderate
+    '/api/train':      '1.00 STX',   // expensive
+  },
+  payTo: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
+  network: 'mainnet',
+}));
+```
+
+### Custom facilitator
+
+```typescript
+app.use(x402Paywall({
+  prices: { '/data': '0.01 STX' },
+  payTo: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
+  facilitatorUrl: 'https://my-facilitator.example.com',
+}));
+```
+
+### With existing middleware stack
+
+```typescript
+app.use(cors());
+app.use(express.json());
+app.use(x402Paywall({
+  prices: { '/premium': '0.01 STX' },
+  payTo: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
+}));
+// Routes defined below are gated
+```
+
+## Requirements
+
+- **Node.js** ≥ 18
+- **Express** ≥ 4
+- **x402-stacks** ≥ 2 (installed automatically)
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@x402-kit/cli`](https://www.npmjs.com/package/@x402-kit/cli) | Scaffold tool for generating x402-kit projects |
+| [`@x402-kit/agent-client`](https://www.npmjs.com/package/@x402-kit/agent-client) | Autonomous agent client that pays for API access automatically |
+| [`x402-stacks`](https://www.npmjs.com/package/x402-stacks) | Core x402 protocol SDK for Stacks |
+
+## Contributing
+
+Contributions are welcome! Please see the [main repository](https://github.com/x402-kit/x402-kit) for development setup and guidelines.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { Request, Response, NextFunction } from 'express';
+export interface X402Options {
+    prices: Record<string, string>;
+    payTo: string;
+    network?: 'mainnet' | 'testnet';
+    facilitatorUrl?: string;
+}
+/**
+ * x402Paywall middleware for Express.
+ * Protects routes based on the provided prices map.
+ */
+export declare function x402Paywall(options: X402Options): (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>> | undefined;

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.x402Paywall = x402Paywall;
+const x402_stacks_1 = require("x402-stacks");
+/**
+ * x402Paywall middleware for Express.
+ * Protects routes based on the provided prices map.
+ */
+function x402Paywall(options) {
+    const { prices, payTo, network = 'testnet', facilitatorUrl = 'https://facilitator.stacksx402.xyz' } = options;
+    // Pre-calculate microSTX prices to avoid parsing on every request
+    const microPrices = {};
+    for (const [path, priceStr] of Object.entries(prices)) {
+        const amount = parseFloat(priceStr.split(' ')[0]);
+        microPrices[path] = (0, x402_stacks_1.STXtoMicroSTX)(amount);
+    }
+    return (req, res, next) => {
+        const amount = microPrices[req.path];
+        if (amount !== undefined) {
+            // Use x402-stacks paymentMiddleware for the specific amount
+            return (0, x402_stacks_1.paymentMiddleware)({
+                amount,
+                payTo,
+                network,
+                facilitatorUrl
+            })(req, res, next);
+        }
+        // No price defined for this route, proceed
+        next();
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAcA,kCA0BC;AAvCD,6CAA+D;AAS/D;;;GAGG;AACH,SAAgB,WAAW,CAAC,OAAoB;IAC9C,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,EAAE,cAAc,GAAG,oCAAoC,EAAE,GAAG,OAAO,CAAC;IAE9G,kEAAkE;IAClE,MAAM,WAAW,GAAoC,EAAE,CAAC;IACxD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD,WAAW,CAAC,IAAI,CAAC,GAAG,IAAA,2BAAa,EAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACzD,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAErC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,4DAA4D;YAC5D,OAAO,IAAA,+BAAiB,EAAC;gBACvB,MAAM;gBACN,KAAK;gBACL,OAAO;gBACP,cAAc;aACf,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QACrB,CAAC;QAED,2CAA2C;QAC3C,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@x402kit/middleware",
+  "version": "0.1.0",
+  "description": "One-line Express middleware for HTTP 402 payment gating on Stacks — monetize any API route with STX micropayments",
+  "license": "MIT",
+  "author": "x402-kit contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/x402-kit/x402-kit.git",
+    "directory": "packages/middleware"
+  },
+  "homepage": "https://github.com/x402-kit/x402-kit#readme",
+  "bugs": {
+    "url": "https://github.com/x402-kit/x402-kit/issues"
+  },
+  "keywords": [
+    "x402",
+    "stacks",
+    "http-402",
+    "express",
+    "middleware",
+    "payments",
+    "paywall",
+    "api-monetization",
+    "micropayments",
+    "web3",
+    "blockchain",
+    "stx"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "dependencies": {
+    "x402-stacks": "^2.0.1"
+  },
+  "devDependencies": {
+    "express": "^4.18.2",
+    "@types/express": "^4.17.25",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  }
+}