@cryptonly/x402-fastify 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,91 @@
-# 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 Fastify
+
+Accept x402 payments in Fastify, 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-fastify @x402/core @x402/fastify @x402/evm fastify
+```
+
+## Use
+
+```ts
+import Fastify from 'fastify';
+import { cryptonlyPayments } from '@cryptonly/x402-fastify';
+
+const app = Fastify();
+app.get('/health', async () => 'ok');
+
+// Paid routes go in the plugin's scope.
+await app.register(async (paid) => {
+  await paid.register(cryptonlyPayments, { apiKey: process.env.CRYPTONLY_API_KEY! });
+
+  // Priced in the dashboard as GET /weather/:city
+  paid.get('/weather/:city', async (request) => {
+    const { city } = request.params as { city: string };
+    return { city, temperatureC: 21 };
+  });
+
+  await paid.cryptonlyX402.ready(); // fails at startup if the prices can't load
+});
+
+await app.listen({ port: 4021 });
+```
+
+`cryptonlyPayments` gates every route in the scope it is registered in. Register it at the root to cover the whole app. Routes the dashboard doesn't price pass through.
+
+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` reply 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 `@x402/fastify` hooks. |
+
+`app.cryptonlyX402` has `ready()`, `refresh()`, `routes()` and `close()`. `app.close()` stops the refresh.
+
+## 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,56 @@
+import type { FastifyPluginAsync } from 'fastify';
+import { type RoutesConfig } from '@x402/core/server';
+import { type PaywallConfig } from '@x402/fastify';
+import { type X402RouteSourceOptions } from '@cryptonly/x402';
+/** Options for {@link cryptonlyPayments}. */
+export type CryptonlyPaymentsOptions = X402RouteSourceOptions & {
+    /** Passed to the stock `@x402/fastify` hooks for the browser paywall. */
+    paywallConfig?: PaywallConfig;
+};
+/** What {@link cryptonlyPayments} decorates the instance with, as `app.cryptonlyX402`. */
+export type CryptonlyX402 = {
+    /**
+     * 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. Called on `app.close()`. */
+    close(): void;
+};
+declare module 'fastify' {
+    interface FastifyInstance {
+        cryptonlyX402: CryptonlyX402;
+    }
+}
+/**
+ * Fastify plugin 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
+ *   `app.cryptonlyX402.ready()`), once.
+ * - Each refresh rebuilds the stock `@x402/fastify` hooks only when the
+ *   routes changed. A failed refresh keeps the last good routes.
+ * - Until a first load succeeds, every request in its scope answers 503
+ *   (fail closed): paid endpoints are never served for free. Register it in
+ *   the scope of the paid routes, or at the root to cover every route.
+ *
+ * @example
+ * ```ts
+ * import Fastify from 'fastify';
+ * import { cryptonlyPayments } from '@cryptonly/x402-fastify';
+ *
+ * const app = Fastify();
+ * await app.register(cryptonlyPayments, { apiKey: process.env.CRYPTONLY_API_KEY! });
+ * app.get('/weather/:city', async (request) => ({ temperatureC: 21 }));
+ * ```
+ */
+export declare const cryptonlyPayments: FastifyPluginAsync<CryptonlyPaymentsOptions>;
+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,EAEV,kBAAkB,EAGnB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAmC,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EAKL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAEzB,6CAA6C;AAC7C,MAAM,MAAM,wBAAwB,GAAG,sBAAsB,GAAG;IAC9D,yEAAyE;IACzE,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;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,8EAA8E;IAC9E,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAEF,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,aAAa,EAAE,aAAa,CAAC;KAC9B;CACF;AAoFD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,8CAG5B,CAAC;AAEH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routesFromConfig = exports.fetchX402Config = exports.cryptonlyPayments = void 0;
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const server_1 = require("@x402/core/server");
+const fastify_1 = require("@x402/fastify");
+const x402_1 = require("@cryptonly/x402");
+const HOOKS = Symbol('cryptonlyX402Hooks');
+/**
+ * Runs the stock `paymentMiddlewareFromHTTPServer` against a stand-in
+ * instance and keeps the hooks it adds. They keep their per-request state on
+ * the request, so the real hooks can hand each request to the set in use.
+ */
+function stockHooks(httpServer, paywallConfig) {
+    const hooks = {};
+    const capture = {
+        decorateRequest: () => capture,
+        addHook: (name, hook) => {
+            hooks[name] = hook;
+            return capture;
+        },
+    };
+    (0, fastify_1.paymentMiddlewareFromHTTPServer)(capture, httpServer, paywallConfig);
+    if (!hooks.onRequest || !hooks.onSend || !hooks.onError) {
+        throw new Error('@x402/fastify did not register its onRequest, onSend and onError hooks');
+    }
+    return hooks;
+}
+const plugin = async (app, options) => {
+    const source = (0, x402_1.createX402RouteSource)(options, (routes, config) => stockHooks(new server_1.x402HTTPResourceServer((0, x402_1.createResourceServer)(config, source.facilitator, source.schemes, source.svmSchemes), routes), options.paywallConfig));
+    // The stock hooks' per-request state, declared once on the real instance.
+    app.decorateRequest('x402Context', undefined);
+    app.decorateRequest('x402RawGuard', undefined);
+    app.decorate('cryptonlyX402', {
+        ready: source.ready,
+        refresh: source.refresh,
+        routes: () => source.current()?.routes,
+        close: source.close,
+    });
+    app.addHook('onRequest', async (request, reply) => {
+        if (!source.current()) {
+            try {
+                await source.ready();
+            }
+            catch {
+                reply.header('Retry-After', String(Math.ceil(source.retryAfterMs / 1000)));
+                return reply.status(503).send(x402_1.X402_CONFIG_UNAVAILABLE);
+            }
+        }
+        // Pinned so that a refresh mid-request can't mix two route sets.
+        const hooks = source.current().value;
+        request[HOOKS] = hooks;
+        return hooks.onRequest(request, reply);
+    });
+    app.addHook('onSend', async (request, reply, payload) => {
+        const hooks = request[HOOKS];
+        return hooks ? hooks.onSend(request, reply, payload) : payload;
+    });
+    app.addHook('onError', async (request, reply, error) => {
+        await request[HOOKS]?.onError(request, reply, error);
+    });
+    app.addHook('onClose', async () => {
+        source.close();
+    });
+};
+/**
+ * Fastify plugin 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
+ *   `app.cryptonlyX402.ready()`), once.
+ * - Each refresh rebuilds the stock `@x402/fastify` hooks only when the
+ *   routes changed. A failed refresh keeps the last good routes.
+ * - Until a first load succeeds, every request in its scope answers 503
+ *   (fail closed): paid endpoints are never served for free. Register it in
+ *   the scope of the paid routes, or at the root to cover every route.
+ *
+ * @example
+ * ```ts
+ * import Fastify from 'fastify';
+ * import { cryptonlyPayments } from '@cryptonly/x402-fastify';
+ *
+ * const app = Fastify();
+ * await app.register(cryptonlyPayments, { apiKey: process.env.CRYPTONLY_API_KEY! });
+ * app.get('/weather/:city', async (request) => ({ temperatureC: 21 }));
+ * ```
+ */
+exports.cryptonlyPayments = (0, fastify_plugin_1.default)(plugin, {
+    fastify: '5.x',
+    name: '@cryptonly/x402-fastify',
+});
+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":"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"}

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@cryptonly/x402-fastify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Fastify plugin 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-fastify"
+  },
+  "homepage": "https://github.com/cryptonly-net/x402/tree/main/typescript/packages/x402-fastify#readme",
+  "bugs": {
+    "url": "https://github.com/cryptonly-net/x402/issues"
+  },
+  "keywords": [
+    "cryptonly",
+    "x402",
+    "facilitator",
+    "payments",
+    "fastify",
+    "plugin"
+  ],
+  "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.5.0",
+    "fastify-plugin": "^5.1.0"
+  },
+  "peerDependencies": {
+    "@x402/core": "^2",
+    "@x402/evm": "^2",
+    "@x402/fastify": "^2",
+    "@x402/extensions": "^2",
+    "@x402/svm": "^2",
+    "fastify": "^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/fastify": "^2.28.0",
+    "fastify": "^5.12.7"
+  }
+}