@openreceive/fastify 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenReceive contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @openreceive/fastify
+
+Fastify adapter for `@openreceive/http`.
+
+This package is ESM-only and requires Node >= 22.
+
+The all-in-one form is the happy path: register the plugin with the order
+hooks and a database handle, and it builds the service and host itself.
+
+```ts
+import { openReceiveFastify } from "@openreceive/fastify";
+
+await fastify.register(openReceiveFastify, {
+  wallet: { nwc: process.env.NWC_URI! }, // receive-only; your app refuses to start otherwise
+  storage: {
+    db, // pg Pool/Client, node:sqlite, better-sqlite3, or a custom adapter
+    onPaid: async ({ reference, query }) => {
+      // Host SQL reaches your driver VERBATIM: `?` on sqlite as shown,
+      // `$1` on postgres. Nothing rewrites placeholders.
+      await query("UPDATE orders SET state = 'paid' WHERE id = ?", [reference]);
+    },
+  },
+  amountFor: (reference) => orders.find(reference)?.amount ?? null, // null → 404
+  authorize: ({ resource }) => orders.viewerOwns(resource.reference),
+  prefix: "/openreceive",
+});
+```
+
+`onPaid` runs inside the settlement transaction, only for the order's first
+settled attempt. Do the order update (or insert an outbox row) through the
+supplied `query`: a plain ORM call commits on its own connection, so it would
+survive a rolled-back settlement — settlement side effects belong on `query`.
+Delivery is at-least-once and retried until `onPaid` succeeds, so make it
+idempotent, and keep it to database writes: an email or webhook sent from here
+survives a rolled-back settlement and goes out again on the retry. Flag the
+order and drain it from your own worker after commit.
+
+The library-owned repository commits a payment-attempt row in the host's
+existing database before payer instructions are returned, and settlement
+piggybacks on the mounted routes by default through the durable
+`openreceive_meta` gate (`opportunisticReconcile` disables or tunes it);
+`startNotificationWorker` is the optional worker process. Behind a
+reverse proxy, the `trustProxyIpHeader` option attributes `rateLimiting`
+client IPs from a proxy-set header. OpenReceive never requires a separate
+database or Redis.
+
+## Advanced: composed form
+
+Construct the pieces yourself (shared service, custom repository, tests) and
+pass them in. `createHost` is the persistence step: it owns the
+`openreceive_payments` rows — per-reference commit locking, write-once settlement,
+and the reconciliation state machine.
+
+Composing needs `@openreceive/http` and `@openreceive/node` as direct
+dependencies of your app — they are transitive dependencies of this adapter, so
+under pnpm or any strict-resolution install, importing them without adding them
+fails:
+
+```sh
+npm install @openreceive/http @openreceive/node
+```
+
+```ts
+import { openReceiveFastify } from "@openreceive/fastify";
+import { createHost } from "@openreceive/http";
+import { createOpenReceive } from "@openreceive/node";
+
+const service = await createOpenReceive(); // reads NWC_URI
+
+const host = createHost({
+  db,
+  amountFor: (reference) => orders.find(reference)?.amount ?? null, // null → 404
+  onPaid: async ({ reference, query }) => {
+    await query("UPDATE orders SET state = 'paid' WHERE id = ?", [reference]);
+  },
+});
+
+await fastify.register(openReceiveFastify, { service, authorize, host, prefix: "/openreceive" });
+```
+
+This package re-exports only the curated `@openreceive/http` surface: the
+handler/stack factories, the error surface, the notification worker, the
+options/context/hook types, and the generated `Wire*` wire body
+types. Host-integration internals — `createHost`, the SQL payment
+repository, the reconcile gate, the rate-limit helpers — live only in
+`@openreceive/http`; import them from there when composing your own host
+(`npm run check:public-api` pins both surfaces).

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { CreateHttpHandlerOptions, CreateStackOptions } from '@openreceive/http';
+export * from '@openreceive/http/adapter-surface';
+
+/** Minimal structural view of the Fastify surface this adapter uses. */
+interface FastifyRequestLike {
+    readonly method: string;
+    readonly headers: Record<string, string | string[] | undefined>;
+    readonly body?: unknown;
+    readonly raw: {
+        url?: string;
+    };
+    /** Scheme, honoring Fastify's trustProxy setting (https behind TLS/proxy). */
+    readonly protocol?: string;
+}
+interface FastifyReplyLike {
+    code(statusCode: number): FastifyReplyLike;
+    header(key: string, value: string): FastifyReplyLike;
+    send(payload: string): unknown;
+    /** Invokes the app's not-found handler for paths this plugin does not own. */
+    callNotFound?(): unknown;
+}
+interface FastifyInstanceLike {
+    all(path: string, handler: (request: FastifyRequestLike, reply: FastifyReplyLike) => Promise<unknown>): unknown;
+    /** Fastify lifecycle hook; used to close an all-in-one stack with the app. */
+    addHook?(name: "onClose", hook: () => Promise<void>): unknown;
+    /** Accumulated register prefix for this instance (from register's `{ prefix }`). */
+    readonly prefix?: string;
+}
+interface FastifyAdapterExtras {
+    /**
+     * Opt-in client-IP attribution for `rateLimiting` behind a reverse proxy:
+     * by default the limiter reads `request.ip`, which is the proxy's address
+     * when Fastify's trustProxy is not configured — every payer would then share
+     * one budget. Only safe when YOUR reverse proxy sets the header (a
+     * direct-to-origin client can forge it). `true` reads the first hop of
+     * `x-forwarded-for`; a string names another header (e.g. `"cf-connecting-ip"`).
+     */
+    readonly trustProxyIpHeader?: boolean | string;
+}
+interface FastifyHandlerOptions extends CreateHttpHandlerOptions, FastifyAdapterExtras {
+}
+/** All-in-one form: host hooks + `wallet` + `storage`; the plugin builds service and host. */
+interface FastifyStackOptions extends CreateStackOptions, FastifyAdapterExtras {
+}
+/**
+ * Two forms: the all-in-one happy path (host hooks + `wallet` + `storage`; the
+ * plugin builds the service and host and closes the owned service on app close
+ * — no background process, settlement is opportunistic) or the composed
+ * `{ service, host, authorize }` form.
+ */
+type FastifyOptions = FastifyHandlerOptions | FastifyStackOptions;
+/** Fastify plugin serving the OpenReceive routes. Register it with a `prefix`. */
+declare function openReceiveFastify(fastify: FastifyInstanceLike, options: FastifyOptions, done?: (error?: Error) => void): void;
+/**
+ * Map a host/service error onto a Fastify JSON reply.
+ * Returns `true` when handled; `false` when the caller should rethrow.
+ */
+declare function sendHostRouteError(reply: FastifyReplyLike, error: unknown): boolean;
+
+export { type FastifyHandlerOptions, type FastifyInstanceLike, type FastifyOptions, type FastifyReplyLike, type FastifyRequestLike, type FastifyStackOptions, openReceiveFastify, sendHostRouteError };

package/dist/index.js

@@ -0,0 +1,103 @@
+// src/index.ts
+import {
+  createHttpHandler,
+  createStack,
+  createProxyRateLimitingConfig,
+  createRequestId,
+  errorResponse,
+  isStackOptions,
+  mapHostRouteError,
+  HttpError,
+  isUnderPrefix,
+  webRequest
+} from "@openreceive/http";
+export * from "@openreceive/http/adapter-surface";
+function openReceiveFastify(fastify, options, done) {
+  const instancePrefix = normalizeFastifyPrefix(fastify.prefix);
+  const effectivePrefix = resolveHandlerPrefix(instancePrefix, options.prefix);
+  let handler;
+  if (isStackOptions(options)) {
+    const { trustProxyIpHeader, ...stackOptions } = options;
+    const stack = createStack({
+      ...stackOptions,
+      ...effectivePrefix,
+      ...createProxyRateLimitingConfig(stackOptions.rateLimiting, trustProxyIpHeader)
+    });
+    handler = stack.handler;
+    fastify.addHook?.("onClose", () => stack.close());
+  } else {
+    const { trustProxyIpHeader, ...handlerOptions } = options;
+    handler = createHttpHandler({
+      ...handlerOptions,
+      ...effectivePrefix,
+      ...createProxyRateLimitingConfig(handlerOptions.rateLimiting, trustProxyIpHeader)
+    });
+  }
+  fastify.all("/*", async (request, reply) => {
+    const relativeUrl = stripInstancePrefix(request.raw.url ?? "/", instancePrefix);
+    const pathname = relativeUrl.split("?")[0];
+    if (!isUnderPrefix(pathname, handler.prefix) && reply.callNotFound !== void 0) {
+      return reply.callNotFound();
+    }
+    const response = await respond(handler, request, relativeUrl);
+    reply.code(response.status);
+    response.headers.forEach((value, key) => {
+      reply.header(key, value);
+    });
+    return reply.send(await response.text());
+  });
+  done?.();
+}
+function sendHostRouteError(reply, error) {
+  const mapped = mapHostRouteError(error);
+  if (mapped === null) return false;
+  reply.code(mapped.status).header("content-type", "application/json; charset=utf-8").send(JSON.stringify(mapped.body));
+  return true;
+}
+function resolveHandlerPrefix(instancePrefix, optionsPrefix) {
+  if (instancePrefix === "") return {};
+  const registerPrefix = normalizeFastifyPrefix(optionsPrefix);
+  if (registerPrefix === "") return {};
+  if (instancePrefix.endsWith(registerPrefix)) return { prefix: "/" };
+  throw new TypeError(
+    `openReceiveFastify got prefix "${registerPrefix}" but the instance is registered under "${instancePrefix}". Pass the prefix at register() \u2014 fastify.register(openReceiveFastify, { prefix, ... }) \u2014 so the route scope and the handler agree.`
+  );
+}
+function stripInstancePrefix(url, instancePrefix) {
+  if (instancePrefix === "") return url;
+  if (url === instancePrefix) return "/";
+  if (url.startsWith(`${instancePrefix}/`)) return url.slice(instancePrefix.length);
+  if (url.startsWith(`${instancePrefix}?`)) return `/${url.slice(instancePrefix.length)}`;
+  throw new Error(
+    `openReceiveFastify is registered under prefix "${instancePrefix}" but received a request for "${url}". Register the plugin on the instance that serves these routes, or pass the prefix at register() so Fastify scopes the routes to it.`
+  );
+}
+function normalizeFastifyPrefix(prefix) {
+  if (prefix === void 0) return "";
+  const trimmed = prefix.trim();
+  if (trimmed === "") return "";
+  const value = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const withoutTrailing = value.length > 1 && value.endsWith("/") ? value.slice(0, -1) : value;
+  return withoutTrailing === "/" ? "" : withoutTrailing;
+}
+async function respond(handler, request, url) {
+  try {
+    return await handler(toWebRequest(request, url), { native: request });
+  } catch (error) {
+    if (error instanceof HttpError) return errorResponse(error, createRequestId());
+    throw error;
+  }
+}
+function toWebRequest(request, url) {
+  return webRequest({
+    method: request.method,
+    headers: request.headers,
+    url,
+    protocol: request.protocol,
+    parsedBody: request.body
+  });
+}
+export {
+  openReceiveFastify,
+  sendHostRouteError
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@openreceive/fastify",
+  "version": "0.2.1",
+  "description": "Fastify plugin for the OpenReceive checkout HTTP handler.",
+  "keywords": [
+    "bitcoin",
+    "lightning",
+    "payments",
+    "nwc",
+    "bolt11",
+    "openreceive",
+    "fastify",
+    "checkout"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@openreceive/http": "0.2.1"
+  },
+  "peerDependencies": {
+    "fastify": "^4.0.0 || ^5.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --target es2022 --out-dir dist",
+    "prepack": "npm run build"
+  },
+  "license": "MIT",
+  "author": "OpenReceive <info@openreceive.org>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openreceive/openreceive.git",
+    "directory": "packages/js/fastify"
+  },
+  "bugs": {
+    "url": "https://github.com/openreceive/openreceive/issues"
+  },
+  "homepage": "https://openreceive.org",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}