@cryptonly/x402-express 0.0.0-stage → 0.6.0

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+<img src="https://raw.githubusercontent.com/cryptonly-net/.github/main/profile/assets/header-banner.svg" alt="Cryptonly" width="100%" />
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+
+# Cryptonly x402 for Express
+
+Accept x402 payments in Express, with Cryptonly as the facilitator.
+
+[Website](https://cryptonly.net) · [Documentation](https://docs.cryptonly.net/guides/x402/) · [Contact](https://cryptonly.net/contact/)
+
+</div>
+
+---
+
+Cryptonly verifies and settles each payment, and pays the network fee. Payments go straight to your wallet. Your prices live in the Cryptonly dashboard, so a price change needs no deploy.
+
+You need a Cryptonly API key with the `x402.verify` and `x402.settle` scopes. The [quickstart](https://docs.cryptonly.net/guides/x402/quickstart/) covers getting one.
+
+## Install
+
+```bash
+npm install @cryptonly/x402-express @x402/core @x402/express @x402/evm express
+```
+
+## Use
+
+```ts
+import express from 'express';
+import { cryptonlyPaymentMiddleware } from '@cryptonly/x402-express';
+
+const app = express();
+app.get('/health', (_req, res) => res.send('ok')); // free routes go first
+
+const payments = cryptonlyPaymentMiddleware({ apiKey: process.env.CRYPTONLY_API_KEY! });
+app.use(payments);
+
+// Priced in the dashboard as GET /weather/:city
+app.get('/weather/:city', (req, res) => {
+  res.json({ city: req.params.city, temperatureC: 21 });
+});
+
+await payments.ready(); // fails at startup if the prices can't load
+app.listen(4021);
+```
+
+It reloads your prices every minute and fails closed, so a paid route is never served for free:
+
+- Until the first load succeeds, every request through it gets `503` with `Retry-After`. This happens with a bad key, an inactive account or no payout wallet.
+- If a later reload fails, it keeps the last good prices and logs a warning.
+
+The buyer is charged only when the handler succeeds. A `4xx`/`5xx` response or a thrown error cancels the payment.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `apiKey` | required | Your Cryptonly API key. |
+| `sandbox` | `false` | Use the sandbox. |
+| `baseUrl` | production | Another API origin. Takes precedence over `sandbox`. |
+| `refreshIntervalMs` | `60000` | How often to reload prices. `0` turns it off. |
+| `retryAfterMs` | `5000` | After a failed first load, how long to answer `503` before the next try. |
+| `schemes` | `[new ExactEvmScheme()]` | Schemes for Base. |
+| `svmSchemes` | `[new ExactSvmScheme()]` if `@x402/svm` is installed | Schemes for Solana. |
+| `logger` | `console` | Gets reload failures and skipped routes. |
+| `paywallConfig` | — | Passed to the stock `paymentMiddleware`. |
+| `createMiddleware` | stock `paymentMiddleware` | Builds the inner middleware, for example to add hooks. |
+
+The middleware also has `ready()`, `refresh()`, `routes()` and `close()`.
+
+On NestJS, use [`@cryptonly/x402-nestjs`](https://www.npmjs.com/package/@cryptonly/x402-nestjs) for decorators. This middleware also works there, applied with `consumer.apply(payments).forRoutes(...)`.
+
+## Solana
+
+Install `@x402/svm` and `@solana/kit`, and add a Solana payout wallet in the dashboard. Solana prices then work with no other change.
+
+## Sandbox
+
+Pass `sandbox: true` and use a key from your [sandbox account](https://docs.cryptonly.net/guides/sandbox-environment/). The sandbox settles on Base Sepolia (`eip155:84532`) and Solana Devnet.
+
+## Learn more
+
+- [x402 quickstart](https://docs.cryptonly.net/guides/x402/quickstart/)
+- [Discovery](https://docs.cryptonly.net/guides/x402/discovery/): list your endpoints for AI agents
+- [Reference](https://docs.cryptonly.net/guides/x402/reference/): key scopes, limits and reason codes
+
+## License
+
+[MIT](https://github.com/cryptonly-net/x402/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import type { NextFunction, Request, Response } from 'express';
+import type { RoutesConfig } from '@x402/core/server';
+import type { SchemeNetworkServer } from '@x402/core/types';
+import { type PaywallConfig } from '@x402/express';
+import { type CryptonlyFacilitatorClient, type X402Config, type X402Logger, type X402RouteSourceOptions } from '@cryptonly/x402';
+/** An Express middleware. */
+export type ExpressMiddleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+/** What {@link InnerMiddlewareFactory} gets besides the routes. */
+export type InnerMiddlewareContext = {
+    config: X402Config;
+    facilitator: CryptonlyFacilitatorClient;
+    /** Registered on the account's EVM network. */
+    schemes: readonly SchemeNetworkServer[];
+    /** Registered on each Solana network of the account. */
+    svmSchemes: readonly SchemeNetworkServer[];
+    paywallConfig?: PaywallConfig;
+};
+/**
+ * Builds the payment middleware for one set of routes. The default is the
+ * stock `paymentMiddleware` from `@x402/express` over a fresh
+ * `x402ResourceServer`; replace it to add hooks, or in tests.
+ */
+export type InnerMiddlewareFactory = (routes: RoutesConfig, context: InnerMiddlewareContext) => ExpressMiddleware;
+/** Logger used for refresh failures and skipped resources. */
+export type CryptonlyMiddlewareLogger = X402Logger;
+/** Options for {@link cryptonlyPaymentMiddleware}. */
+export type CryptonlyPaymentMiddlewareOptions = X402RouteSourceOptions & {
+    /** Passed to the stock `paymentMiddleware` for the browser paywall. */
+    paywallConfig?: PaywallConfig;
+    /** Builds the inner middleware. See {@link InnerMiddlewareFactory}. */
+    createMiddleware?: InnerMiddlewareFactory;
+};
+/** The middleware returned by {@link cryptonlyPaymentMiddleware}. */
+export type CryptonlyPaymentMiddleware = ((req: Request, res: Response, next: NextFunction) => Promise<void>) & {
+    /**
+     * Loads the configuration now (if not loaded yet) and starts refreshing.
+     * Rejects when the first load fails. Await it before `listen` to fail
+     * fast at startup.
+     */
+    ready(): Promise<void>;
+    /** Reloads the configuration now. Resolves `true` when the routes changed. */
+    refresh(): Promise<boolean>;
+    /** The routes in use, or `undefined` before the first successful load. */
+    routes(): RoutesConfig | undefined;
+    /** Stops refreshing. The last routes stay in use. */
+    close(): void;
+};
+/** The default {@link InnerMiddlewareFactory}: stock `@x402/express`. */
+export declare const stockPaymentMiddleware: InnerMiddlewareFactory;
+/**
+ * Express middleware whose paid routes and prices come from the Cryptonly
+ * dashboard (`GET /x402/config`), refreshed every minute, so a price change
+ * reaches production without a deploy.
+ *
+ * - The configuration loads on the first request (or on `ready()`), once.
+ * - Each refresh rebuilds the stock `@x402/express` middleware only when the
+ *   routes changed. A failed refresh keeps the last good routes.
+ * - Until a first load succeeds, every request through it answers 503
+ *   (fail closed): paid endpoints are never served for free. Mount it after
+ *   health checks and other free routes.
+ *
+ * @example
+ * ```ts
+ * import { cryptonlyPaymentMiddleware } from '@cryptonly/x402-express';
+ *
+ * app.use(cryptonlyPaymentMiddleware({ apiKey: process.env.CRYPTONLY_API_KEY! }));
+ * app.get('/weather', (req, res) => res.json({ temperatureC: 21 }));
+ * ```
+ */
+export declare function cryptonlyPaymentMiddleware(options: CryptonlyPaymentMiddlewareOptions): CryptonlyPaymentMiddleware;
+export { fetchX402Config, routesFromConfig } from '@cryptonly/x402';
+export type { X402Config } from '@cryptonly/x402';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAIL,KAAK,0BAA0B,EAC/B,KAAK,UAAU,EACf,KAAK,UAAU,EAEf,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAEzB,6BAA6B;AAC7B,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,mEAAmE;AACnE,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,0BAA0B,CAAC;IACxC,+CAA+C;IAC/C,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,wDAAwD;IACxD,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC3C,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,sBAAsB,KAC5B,iBAAiB,CAAC;AAEvB,8DAA8D;AAC9D,MAAM,MAAM,yBAAyB,GAAG,UAAU,CAAC;AAEnD,sDAAsD;AACtD,MAAM,MAAM,iCAAiC,GAAG,sBAAsB,GAAG;IACvE,uEAAuE;IACvE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,0BAA0B,GAAG,CAAC,CACxC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,KACf,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG;IACpB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,8EAA8E;IAC9E,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,MAAM,IAAI,YAAY,GAAG,SAAS,CAAC;IACnC,qDAAqD;IACrD,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,EAAE,sBAQlC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iCAAiC,GACzC,0BAA0B,CAmC5B;AAED,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routesFromConfig = exports.fetchX402Config = exports.stockPaymentMiddleware = void 0;
+exports.cryptonlyPaymentMiddleware = cryptonlyPaymentMiddleware;
+const express_1 = require("@x402/express");
+const x402_1 = require("@cryptonly/x402");
+/** The default {@link InnerMiddlewareFactory}: stock `@x402/express`. */
+const stockPaymentMiddleware = (routes, { config, facilitator, schemes, svmSchemes, paywallConfig }) => (0, express_1.paymentMiddleware)(routes, (0, x402_1.createResourceServer)(config, facilitator, schemes, svmSchemes), paywallConfig);
+exports.stockPaymentMiddleware = stockPaymentMiddleware;
+/**
+ * Express middleware whose paid routes and prices come from the Cryptonly
+ * dashboard (`GET /x402/config`), refreshed every minute, so a price change
+ * reaches production without a deploy.
+ *
+ * - The configuration loads on the first request (or on `ready()`), once.
+ * - Each refresh rebuilds the stock `@x402/express` middleware only when the
+ *   routes changed. A failed refresh keeps the last good routes.
+ * - Until a first load succeeds, every request through it answers 503
+ *   (fail closed): paid endpoints are never served for free. Mount it after
+ *   health checks and other free routes.
+ *
+ * @example
+ * ```ts
+ * import { cryptonlyPaymentMiddleware } from '@cryptonly/x402-express';
+ *
+ * app.use(cryptonlyPaymentMiddleware({ apiKey: process.env.CRYPTONLY_API_KEY! }));
+ * app.get('/weather', (req, res) => res.json({ temperatureC: 21 }));
+ * ```
+ */
+function cryptonlyPaymentMiddleware(options) {
+    const createMiddleware = options.createMiddleware ?? exports.stockPaymentMiddleware;
+    const source = (0, x402_1.createX402RouteSource)(options, (routes, config) => createMiddleware(routes, {
+        config,
+        facilitator: source.facilitator,
+        schemes: source.schemes,
+        svmSchemes: source.svmSchemes,
+        ...(options.paywallConfig ? { paywallConfig: options.paywallConfig } : {}),
+    }));
+    const middleware = async (req, res, next) => {
+        if (!source.current()) {
+            try {
+                await source.ready();
+            }
+            catch {
+                if (!res.headersSent) {
+                    res.setHeader('Retry-After', String(Math.ceil(source.retryAfterMs / 1000)));
+                    res.status(503).json(x402_1.X402_CONFIG_UNAVAILABLE);
+                }
+                return;
+            }
+        }
+        await source.current().value(req, res, next);
+    };
+    return Object.assign(middleware, {
+        ready: source.ready,
+        refresh: source.refresh,
+        routes: () => source.current()?.routes,
+        close: source.close,
+    });
+}
+var x402_2 = require("@cryptonly/x402");
+Object.defineProperty(exports, "fetchX402Config", { enumerable: true, get: function () { return x402_2.fetchX402Config; } });
+Object.defineProperty(exports, "routesFromConfig", { enumerable: true, get: function () { return x402_2.routesFromConfig; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAyGA,gEAqCC;AA3ID,2CAAsE;AACtE,0CASyB;AA6DzB,yEAAyE;AAClE,MAAM,sBAAsB,GAA2B,CAC5D,MAAM,EACN,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,EAC3D,EAAE,CACF,IAAA,2BAAiB,EACf,MAAM,EACN,IAAA,2BAAoB,EAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,CAAC,EAC9D,aAAa,CACd,CAAC;AARS,QAAA,sBAAsB,0BAQ/B;AAEJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,0BAA0B,CACxC,OAA0C;IAE1C,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,8BAAsB,CAAC;IAC5E,MAAM,MAAM,GAAuC,IAAA,4BAAqB,EACtE,OAAO,EACP,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CACjB,gBAAgB,CAAC,MAAM,EAAE;QACvB,MAAM;QACN,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC,CACL,CAAC;IAEF,MAAM,UAAU,GAAG,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QAC3E,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YACtB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;oBACrB,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;oBAC5E,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,8BAAuB,CAAC,CAAC;gBAChD,CAAC;gBACD,OAAO;YACT,CAAC;QACH,CAAC;QACD,MAAM,MAAM,CAAC,OAAO,EAAG,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE;QAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM;QACtC,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC,CAAC;AACL,CAAC;AAED,wCAAoE;AAA3D,uGAAA,eAAe,OAAA;AAAE,wGAAA,gBAAgB,OAAA"}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@cryptonly/x402-express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "description": "Express middleware for x402 payments with Cryptonly as the facilitator; prices come from the Cryptonly dashboard.",
+  "license": "MIT",
+  "private": false,
+  "type": "commonjs",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cryptonly-net/x402.git",
+    "directory": "typescript/packages/x402-express"
+  },
+  "homepage": "https://github.com/cryptonly-net/x402/tree/main/typescript/packages/x402-express#readme",
+  "bugs": {
+    "url": "https://github.com/cryptonly-net/x402/issues"
+  },
+  "keywords": [
+    "cryptonly",
+    "x402",
+    "facilitator",
+    "payments",
+    "express",
+    "middleware"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cryptonly/x402": "0.6.0"
+  },
+  "peerDependencies": {
+    "@x402/core": "^2",
+    "@x402/evm": "^2",
+    "@x402/express": "^2",
+    "@x402/extensions": "^2",
+    "@x402/svm": "^2",
+    "express": "^4 || ^5"
+  },
+  "peerDependenciesMeta": {
+    "@x402/extensions": {
+      "optional": true
+    },
+    "@x402/svm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@x402/core": "^2.28.0",
+    "@x402/evm": "^2.28.0",
+    "@x402/extensions": "^2.28.0",
+    "@x402/svm": "^2.28.0",
+    "@x402/express": "^2.28.0",
+    "@types/express": "^5.0.6",
+    "express": "^5.3.0",
+    "@nestjs/common": "11.1.11",
+    "@nestjs/core": "11.1.11",
+    "@nestjs/platform-express": "11.1.11",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2"
+  }
+}