@openreceive/http 0.3.2 → 0.3.3

package/dist/adapter-surface.js

@@ -7,7 +7,7 @@ import {
   isServiceErrorShape,
   mapHostRouteError,
   startNotificationWorker
-} from "./chunk-EZAV3TC3.js";
+} from "./chunk-YASZ4HDW.js";
 export {
   HostError,
   HttpError,

package/dist/{chunk-EZAV3TC3.js → chunk-YASZ4HDW.js}

@@ -464,6 +464,14 @@ var RECONCILE_GATE_CAS_RETRIES = 6;
 var META_CLOCK_SKEW_SECONDS = 60;
 var SCHEMA_VERSION_META_KEY = "schema_version";
 var OPENRECEIVE_RECONCILE_BATCH_SIZE = 200;
+function isMissingTableError(error, dialect) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (dialect === "postgres") {
+    const code = error?.code;
+    return code === "42P01" || /relation .+ does not exist/i.test(message);
+  }
+  return /no such table/i.test(message);
+}
 function parseClaimedAt(value) {
   try {
     const parsed = JSON.parse(String(value));
@@ -511,8 +519,11 @@ function createSqlPayments(db, options = {}) {
         );
         const value = rows[0]?.value;
         stored = value === void 0 ? void 0 : Number(asString(value, "value"));
-      } catch {
-        return;
+      } catch (error) {
+        if (!isMissingTableError(error, adapter.dialect)) return;
+        throw new TypeError(
+          `The ${metaTable} table does not exist \u2014 the OpenReceive tables have not been migrated in this database. Run \`npx openreceive scaffold payments --orm <your orm>\` and apply the emitted migration through your normal workflow (or execute paymentsSchemaSql(dialect) directly for bare drivers). https://openreceive.org/guides/storage.md`
+        );
       }
       if (stored === void 0 || !Number.isInteger(stored)) return;
       if (stored > OPENRECEIVE_PAYMENTS_SCHEMA_VERSION) {
@@ -785,11 +796,13 @@ function warnFailure(event, prefix, error) {
 }
 function createHost(options) {
   if (options?.amountFor === void 0) {
-    throw new TypeError("OpenReceive host requires amountFor.");
+    throw new TypeError(
+      'OpenReceive host requires amountFor \u2014 the host owns prices. Pass amountFor(reference) returning the amount to charge (for example { currency: "USD", value: "9.99" }), or null for an unknown reference. https://openreceive.org/guides/api-reference.md#createhost'
+    );
   }
   if (options.onPaid === void 0) {
     throw new TypeError(
-      "OpenReceive host requires onPaid (per-reference settlement context in db mode; the raw settlement event in custom repository mode)."
+      "OpenReceive host requires onPaid (per-reference settlement context in db mode; the raw settlement event in custom repository mode). Pass onPaid to fulfill the order \u2014 it runs exactly once per reference. https://openreceive.org/guides/api-reference.md#onpaid"
     );
   }
   let payments;
@@ -806,20 +819,28 @@ function createHost(options) {
     };
   } else {
     if (options.payments?.listForReference === void 0) {
-      throw new TypeError("OpenReceive host requires db or payments.listForReference.");
+      throw new TypeError(
+        "OpenReceive host requires db or payments.listForReference. Pass db (your database handle; the library owns the openreceive tables in it), or a complete custom PaymentRepository. https://openreceive.org/guides/storage.md"
+      );
     }
     if (options.payments.commitAttempt === void 0) {
-      throw new TypeError("OpenReceive host requires payments.commitAttempt.");
+      throw new TypeError(
+        "OpenReceive host requires payments.commitAttempt \u2014 the attempt write committed before payer instructions are exposed. Implement it, or pass db to use the built-in SQL repository. https://openreceive.org/guides/storage.md"
+      );
     }
     if (options.payments.listReconcilableAttempts === void 0) {
-      throw new TypeError("OpenReceive host requires payments.listReconcilableAttempts.");
+      throw new TypeError(
+        "OpenReceive host requires payments.listReconcilableAttempts \u2014 the pending-attempt batch reconciliation scans. Implement it, or pass db to use the built-in SQL repository. https://openreceive.org/guides/storage.md"
+      );
     }
     if (options.payments.recordReconciliation === void 0) {
-      throw new TypeError("OpenReceive host requires payments.recordReconciliation.");
+      throw new TypeError(
+        "OpenReceive host requires payments.recordReconciliation \u2014 how a scan outcome (settled/expired/attention) is written back. Implement it, or pass db to use the built-in SQL repository. https://openreceive.org/guides/storage.md"
+      );
     }
     if (typeof options.payments.recordSettlement !== "function") {
       throw new TypeError(
-        "OpenReceive host requires payments.recordSettlement (the write-once settlement claim)."
+        "OpenReceive host requires payments.recordSettlement (the write-once settlement claim). Implement it, or pass db to use the built-in SQL repository. https://openreceive.org/guides/storage.md"
       );
     }
     payments = options.payments;
@@ -1419,7 +1440,7 @@ function createIpRateLimit(config = {}) {
   const count = config.countAttemptsFromIp;
   if (count === void 0) {
     throw new TypeError(
-      "rateLimiting requires persistent counting. Implement countAttemptsFromIp on the payment repository (the built-in SQL repository already does), pass countAttemptsFromIp in the rateLimiting config, or disable rateLimiting and use a custom rateLimitHook backed by your own store. There is deliberately no in-memory fallback: per-process counts reset on restart and multiply per instance behind a load balancer."
+      "rateLimiting requires persistent counting. Implement countAttemptsFromIp on the payment repository (the built-in SQL repository already does), pass countAttemptsFromIp in the rateLimiting config, or disable rateLimiting and use a custom rateLimitHook backed by your own store. There is deliberately no in-memory fallback: per-process counts reset on restart and multiply per instance behind a load balancer. https://openreceive.org/guides/rate-limiting.md"
     );
   }
   const message = config.message ?? DEFAULT_MESSAGE;
@@ -1434,7 +1455,7 @@ function createIpRateLimit(config = {}) {
       if (!warnedUnattributable) {
         warnedUnattributable = true;
         console.warn(
-          "[openreceive] rateLimiting allowed a request with no attributable client IP (fail-open). If every request logs no IP, the adapter is not supplying one and rate limiting is inactive \u2014 see the rate limiting guide."
+          "[openreceive] rateLimiting allowed a request with no attributable client IP (fail-open). If every request logs no IP, the adapter is not supplying one and rate limiting is inactive \u2014 see https://openreceive.org/guides/rate-limiting.md"
         );
       }
       return true;
@@ -1521,19 +1542,31 @@ function tooManyAttempts(message) {
 
 // src/handler.ts
 function createHttpHandler(options) {
-  if (options?.service === void 0) throw new TypeError("HTTP handler requires service.");
+  if (options?.service === void 0) {
+    throw new TypeError(
+      "HTTP handler requires service: pass the wallet service built by createOpenReceive(). https://openreceive.org/guides/api-reference.md#createopenreceive"
+    );
+  }
   if (options.authorize === void 0) {
-    throw new TypeError("HTTP handler requires authorize; authentication belongs to the host.");
+    throw new TypeError(
+      "HTTP handler requires authorize; authentication belongs to the host. Pass an authorize hook that checks the payer's session may act on context.resource.reference. https://openreceive.org/guides/authorization.md"
+    );
+  }
+  if (options.host === void 0) {
+    throw new TypeError(
+      "HTTP handler requires host: build it with createHost({ amountFor, onPaid, db }) and pass it beside service and authorize. https://openreceive.org/guides/api-reference.md#createhost"
+    );
   }
-  if (options.host === void 0) throw new TypeError("HTTP handler requires host.");
   if (options.rateLimiting !== void 0 && options.rateLimiting !== false && options.rateLimitHook !== void 0) {
-    throw new TypeError("Pass either rateLimiting or a custom rateLimitHook, not both.");
+    throw new TypeError(
+      "Pass either rateLimiting or a custom rateLimitHook, not both: rateLimiting is the built-in per-IP limiter, rateLimitHook replaces it with your own policy. https://openreceive.org/guides/rate-limiting.md"
+    );
   }
   const rateLimit = options.rateLimitHook ?? resolveRateLimiting(options);
   const reconcile = options.opportunisticReconcile === false ? void 0 : typeof options.opportunisticReconcile === "object" ? options.opportunisticReconcile : {};
   if (reconcile !== void 0 && typeof options.host.payments.claimReconcileGate !== "function") {
     throw new TypeError(
-      "Opportunistic reconcile (on by default) requires payments.claimReconcileGate \u2014 a durable compare-and-set gate shared by every worker (the built-in SQL repository implements it over openreceive_meta). Implement it on the custom repository, or pass opportunisticReconcile: false and run your own settlement worker."
+      "Opportunistic reconcile (on by default) requires payments.claimReconcileGate \u2014 a durable compare-and-set gate shared by every worker (the built-in SQL repository implements it over openreceive_meta). Implement it on the custom repository, or pass opportunisticReconcile: false and run your own settlement worker. https://openreceive.org/guides/storage.md"
     );
   }
   const rawExtractClientIp = (typeof options.rateLimiting === "object" ? options.rateLimiting.ip : void 0) ?? resolveClientIp;
@@ -1830,7 +1863,11 @@ async function enforceRateLimit(runtime, action, request, resource, native) {
 }
 async function enforceAuthorize(runtime, action, request, resource, native) {
   if (!await runtime.authorize({ action, request, resource, native })) {
-    throw new HttpError(403, "FORBIDDEN", "Not authorized for this action.");
+    throw new HttpError(
+      403,
+      "FORBIDDEN",
+      "Not authorized for this action. The application's authorize hook denied it; if this is unexpected, check that the payer's session reaches the checkout routes. https://openreceive.org/guides/authorization.md"
+    );
   }
 }
 async function persistCheckoutAttempt(runtime, input) {
@@ -2205,7 +2242,7 @@ function isStackOptions(options) {
     return true;
   }
   throw new TypeError(
-    "OpenReceive composed options require host: pass { service, host, authorize }, or use the all-in-one form with wallet/storage/amountFor."
+    "OpenReceive composed options require host: pass { service, host, authorize } (host built by createHost), or use the all-in-one form with wallet/storage/amountFor. https://openreceive.org/guides/api-reference.md#framework-adapters"
   );
 }
 

package/dist/index.js

@@ -34,7 +34,7 @@ import {
   startReconciler,
   typeOrmDb,
   webRequest
-} from "./chunk-EZAV3TC3.js";
+} from "./chunk-YASZ4HDW.js";
 export {
   HostError,
   HttpError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/http",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Framework-neutral (Web Request/Response) HTTP handler for OpenReceive checkout that builds on @openreceive/node and requires its Node runtime: request routing, host integration, and payment-attempt persistence.",
   "keywords": [
     "bitcoin",
@@ -17,8 +17,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@openreceive/core": "0.3.2",
-    "@openreceive/node": "0.3.2"
+    "@openreceive/core": "0.3.3",
+    "@openreceive/node": "0.3.3"
   },
   "exports": {
     ".": {
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/debug-openreceive-payment/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: debug-openreceive-payment
+description: >
+  Diagnose a failing OpenReceive integration. Use when an OpenReceive-powered
+  checkout misbehaves: the server refuses to boot, checkout routes return 403,
+  404, 409, or 5xx, a paid invoice never settles, a swap refund seems
+  unreachable, or the checkout UI renders nothing.
+license: MIT
+---
+
+# Debug an OpenReceive payment
+
+Work top-down: configuration, then the request, then settlement. Every guide
+URL below is raw markdown — fetch it when the step needs it.
+
+## 1. Run the doctor first
+
+```sh
+npx openreceive doctor                     # Node version, NWC_URI, swap config, wallet probe
+npx openreceive doctor --db <db>           # + are openreceive_payments/openreceive_meta migrated?
+npx openreceive doctor --url http://localhost:3000   # + are the routes actually mounted?
+```
+
+Each failing line states its own fix. `npx openreceive debug-report` prints the
+same diagnostics redacted, always exit 0 — safe to share.
+
+## 2. Boot failures
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `MISSING_NWC` / "needs a receive-only NWC code" | `NWC_URI` is not in the server process env. A `.env` file alone is not enough — something must load it (`dotenv/config`, Next auto-load). Get a code: https://openreceive.org/get_a_nwc_code_to_receive_payments |
+| `INVALID_NWC` / "not a valid NWC code" | The value is malformed (must be `nostr+walletconnect://` with 64-hex pubkey and secret, ≥1 `wss` relay). Re-copy it from the wallet. |
+| "NOT receive-only" / spend methods advertised | The wallet minted a spend-capable code; OpenReceive fails closed because a leak would drain the wallet. Mint a receive-only code. Overriding (`allowSpendCapableWallet` / `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC`) is a last resort. |
+| Wallet preflight failed (methods/encryption) | The wallet must advertise `make_invoice` + `list_transactions` and NIP-04 or NIP-44 v2. Use a compatible wallet. |
+| "The openreceive_meta table does not exist" / raw `no such table: openreceive_payments` | The migration was never applied. Node: `npx openreceive scaffold payments --orm <yours>`, then run the emitted migration through the app's normal workflow. Rails: `bin/rails generate openreceive:install`, then `bin/rails db:migrate`. https://openreceive.org/guides/storage.md |
+| "requires amountFor / onPaid / authorize / host" | The factory is missing a required hook — see the host contract in https://openreceive.org/guides/api-reference.md |
+
+## 3. Request-time errors from the routes
+
+| Status | Meaning | Where to look |
+| --- | --- | --- |
+| 403 FORBIDDEN | Your own `authorize` hook denied it, or the request looked cross-site. Check the session/cookie actually reaches the checkout routes. https://openreceive.org/guides/authorization.md |
+| 404 NOT_FOUND | `amountFor` returned `null` (unknown reference), or the `payment_hash` does not belong to that reference. |
+| 409 CONFLICT | **Normal state, not a bug**: the reference already settled, or an unpaid checkout for that method is already live. Show it as order state; never retry-loop. |
+| 503 retryable | The host hook failed while persisting the attempt (instructions withheld), or the wallet is unavailable. Read the server log for the underlying error. |
+| Framework 404 / HTML error page | The router is not mounted, or mounted at a different prefix than the UI's `prefix` prop. `doctor --url` distinguishes these. |
+
+## 4. Paid but never settles
+
+- Settlement is opportunistic: any OpenReceive request runs one reconcile pass
+  through a durable gate (min 2s between wallet scans, stretched by invoice
+  age). A quiet server settles on the next request — or run the optional
+  notification worker. No timer is missing; that is the design.
+- An unpaid attempt closes only after a successful wallet scan at/after expiry
+  plus a 900s grace constant — a local clock alone never closes one. `expired`
+  arriving "late" is correct.
+- `onPaid` runs once per reference, first settled attempt only, inside the
+  settlement transaction. If your fulfillment did not run, check whether the
+  guarded `UPDATE … WHERE` matched zero rows (already transitioned).
+  https://openreceive.org/guides/storage.md
+
+## 5. Swaps and refunds
+
+- A deposit that arrives short or late becomes `refund_required`; the payer
+  claims it on a second visit. That needs a per-order URL you serve
+  (`/checkout/:reference`, `syncUrl` on the drop-ins). Keep the
+  `payment_hash`: `POST /swaps/status` reopens the attempt with no expiry
+  window, while re-picking the coin mints a new deposit after ~30 minutes.
+- Refunds exist only for swap deposits from `refund_required`. There is **no
+  Lightning refund** — the wallet cannot spend. Do not chase one.
+  https://openreceive.org/guides/swap-refunds.md
+
+## 6. Checkout UI shows nothing
+
+- The components require `prefix` — the exact base path the routes are mounted
+  at (`"/openreceive"` unless you changed it).
+- Import the stylesheet (`@openreceive/react/styles.css` or the elements
+  sheet).
+- "invoice must not be an NWC connection string" means a server secret leaked
+  into a browser payload — stop and fix the server response; never render it.
+  https://openreceive.org/guides/frontend-checkout.md
+
+## Still stuck
+
+The full route/option/error reference:
+https://openreceive.org/guides/api-reference.md · machine-readable contract:
+https://openreceive.org/openapi.yaml · library bug reports:
+https://openreceive.org/contact

package/skills/integrate-openreceive/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: integrate-openreceive
+description: >
+  Integrate OpenReceive inbound Bitcoin Lightning payments into an application.
+  Use when adding Bitcoin, Lightning, or crypto checkout to a Node.js, Express,
+  Fastify, Next.js, Rails, React, Vue, Svelte, Angular, or plain-HTML
+  application with OpenReceive (the @openreceive/* npm packages or the
+  openreceive-rails gem).
+license: MIT
+---
+
+# Integrate OpenReceive
+
+OpenReceive is a payment library that runs inside the application you are
+editing. It mounts HTTP routes there, issues Lightning invoices against a
+wallet the merchant already controls, and calls back into your code when one
+settles. There is no OpenReceive account and no API key; funds land directly in
+the merchant's wallet. The one required credential is a **receive-only NWC
+code** (`NWC_URI`).
+
+## Pick the stack, then follow its directions
+
+1. Identify the server stack of the application you are in.
+2. Open the matching reference — it is complete (quickstart inlined) and needs
+   no network access:
+   - Node (Express / Fastify / Next.js): [references/node.md](references/node.md)
+   - Rails: [references/rails.md](references/rails.md)
+3. Follow its **Step 0** first: confirm `NWC_URI` is set in the server
+   environment before writing code. Never print the value; never invent a
+   placeholder.
+
+Install (Node): `npm install @openreceive/express @openreceive/react` — swap
+the adapter (`fastify`, `next`) and UI package (`vue`, `svelte`, `angular`,
+`elements`) for the stack. Install (Rails): `bundle add openreceive-rails`.
+
+## The three server objects
+
+| Object | Built with | Talks to |
+| --- | --- | --- |
+| Wallet client | `createOpenReceive()` | the merchant's wallet — mints invoices, reads settlement, holds the NWC code |
+| Host | `createHost()` | your database — your hooks plus the `openreceive_payments` table |
+| HTTP routes | `openReceiveExpress()` / `openReceiveFastify()` / `openReceiveNext()` / the Rails engine | the browser — mounted at `/openreceive` by default |
+
+The quickstart's one-factory form (`openReceiveExpress({ wallet, storage,
+amountFor, authorize })`) builds all three; compose them separately only for a
+shared wallet client or a custom repository. The checkout UI
+(`<Checkout reference={...} prefix="/openreceive" />`) is the optional fourth
+piece.
+
+## The host contract: authorize, amountFor, onPaid
+
+Your application keeps orders, users, prices, and fulfillment. Three hooks are
+the entire bridge — wire them to the models this app already has, never to
+copied demo models:
+
+- `amountFor(reference)` — the authoritative price, read from your own data.
+  Return `{ currency, value, description }` with `value` a **decimal string**
+  (never a float, never payer input), or `null` when there is nothing to pay
+  for. The `reference` is your order id: one per thing you fulfill, created
+  before checkout, kept across retries, never reused.
+- `authorize({ action, request, resource })` — your own access check, run on
+  every request. `resource.reference` is a claim the payer made, not proof;
+  read a real session.
+- `onPaid({ reference, paidAt, query })` — fulfillment, run once per reference
+  inside the settlement transaction, only for the first settled attempt. Use
+  the provided `query`, not your ORM's other connection, and guard the
+  transition (`UPDATE … WHERE state = 'awaiting_payment'`).
+
+## 409 is a state, not a failure
+
+The library serializes attempts per reference. A create that returns **409
+CONFLICT** is normal checkout flow: the reference already settled, or an unpaid
+checkout for that payment method is already in progress. Surface it as order
+state; do not retry-loop it, and do not build an idempotency store around it —
+that serialization is the library's job. (A hook failure while persisting an
+attempt is a **503 retryable**, deliberately distinct.)
+
+## Secrets
+
+`NWC_URI` and `LSC_URI_*` are server-only. Never put them in browser code,
+logs, assets, or tests. Boot fails closed if the NWC code advertises spend
+methods such as `pay_invoice` — mint a receive-only code
+(https://openreceive.org/get_a_nwc_code_to_receive_payments) instead of
+overriding.
+
+## Database tables
+
+```sh
+npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex
+```
+
+emits the `openreceive_payments` + `openreceive_meta` migration for THIS app's
+database (Rails: `bin/rails generate openreceive:install`); run it through the
+app's normal migration workflow. The tables sit beside your models — no
+relations to them, no separate database, no Redis.
+
+## Verify, and test without a real wallet
+
+`npx openreceive doctor` checks the configuration and says what to fix.
+
+For tests, inject a fake wallet at the stable seams — `client` on
+`createOpenReceive` (any object with `preflight`, `makeInvoice`,
+`listTransactions`) or `config.nwc_client` in Rails — plus
+`StaticPriceProvider` for fiat pricing without a network. Your routes,
+persistence, reconcile, and `onPaid` then run the production code paths.
+Details: https://openreceive.org/guides/host-testing.md
+
+## Deeper documentation
+
+Fetch on demand — each URL is raw markdown:
+https://openreceive.org/guides/authorization.md ·
+https://openreceive.org/guides/storage.md ·
+https://openreceive.org/guides/api-reference.md ·
+https://openreceive.org/guides/security.md ·
+https://openreceive.org/openapi.yaml (the normative HTTP contract) ·
+https://openreceive.org/llms.txt (the full index)