@openreceive/node 0.4.3 → 0.4.6

package/README.md

@@ -1,7 +1,50 @@
 # @openreceive/node
 
-The OpenReceive Node service: receive-only NWC wallet client, checkout/swap service, pricing, and the `openreceive` CLI.
+Accept Bitcoin Lightning payments directly into a wallet you control from
+your Node.js application. This package connects to your receive-only Nostr
+Wallet Connect (NWC) wallet, creates invoices, checks settlement, and provides
+the swap service and command-line tools.
+
+OpenReceive supports optional swaps from **USDT, USDC, SOL, and ETH** through
+a configured swap provider. The provider converts the payment to **BTC over
+Lightning**, which settles into the merchant's connected wallet. Available
+assets and networks depend on the provider; swaps are optional.
+
+## Install
 
 This package is ESM-only and requires Node >= 22.
 
+```sh
+npm install @openreceive/node
+```
+
+Start with the [integration quickstart](https://github.com/openreceive/openreceive/blob/master/docs/guides/quickstart-node.md)
+and the [payment storage guide](https://github.com/openreceive/openreceive/blob/master/docs/guides/storage.md).
+
 Part of [OpenReceive](https://openreceive.org). Start with the [Node quickstart](https://github.com/openreceive/openreceive/blob/master/docs/guides/quickstart-node.md); the full API is in the [API reference](https://github.com/openreceive/openreceive/blob/master/docs/guides/api-reference.md).
+
+## Choose your integration
+
+For a web checkout, install `@openreceive/express`, `@openreceive/fastify`, or
+`@openreceive/next`. They use this service and add payment persistence,
+authorization, and mounted routes. For a custom Node.js host, compose the
+service with `@openreceive/http`.
+
+Use this package directly when you need the service or its types as part of
+that integration. The service does not persist payment attempts on its own.
+The normal HTTP integration records them in your existing database before
+exposing payment instructions.
+
+- **Connect your wallet:** set `NWC_URI` on the server to a receive-only NWC
+  connection. Startup checks reject spend-capable connections by default.
+- **Enable optional swaps:** configure your provider through `LSC_URI_PRIMARY`
+  and optionally `LSC_URI_BACKUP`.
+- **Keep your business logic:** the host controls orders, prices,
+  authorization, and fulfillment.
+
+## Guides
+
+- [Environment and wallet configuration](https://github.com/openreceive/openreceive/blob/master/docs/guides/environment-variables.md)
+- [Optional swaps](https://github.com/openreceive/openreceive/blob/master/docs/guides/automated-swaps.md)
+- [Test with a fake wallet](https://github.com/openreceive/openreceive/blob/master/docs/guides/host-testing.md)
+- [Deploy and reconcile payments](https://github.com/openreceive/openreceive/blob/master/docs/guides/deploying.md)

package/dist/{chunk-LWN4JJ24.js → chunk-65UPROSE.js}

@@ -177,6 +177,7 @@ import {
   compact,
   formatSpendCapabilityRefusedMessage,
   formatSpendCapabilityWarningMessage,
+  OPENRECEIVE_NWC_NOTIFICATION_TYPES,
   OpenReceiveError as OpenReceiveError2,
   parseNwcUri
 } from "@openreceive/core";
@@ -186,6 +187,8 @@ import {
   OPENRECEIVE_MAX_AMOUNT_MSATS,
   OPENRECEIVE_MIN_AMOUNT_MSATS,
   OPENRECEIVE_NWC_METADATA_MAX_BYTES,
+  OPENRECEIVE_NWC_REQUIRED_RECEIVE_METHODS,
+  OPENRECEIVE_NWC_SPEND_METHODS,
   nonEmptyString,
   recordOrEmpty
 } from "@openreceive/core";
@@ -194,13 +197,8 @@ import {
 var HEX_64 = /^[0-9a-fA-F]{64}$/;
 
 // src/nwc/normalize.ts
-var REQUIRED_RECEIVE_METHODS = ["make_invoice", "list_transactions"];
-var SPEND_METHODS = [
-  "pay_invoice",
-  "multi_pay_invoice",
-  "pay_keysend",
-  "multi_pay_keysend"
-];
+var REQUIRED_RECEIVE_METHODS = OPENRECEIVE_NWC_REQUIRED_RECEIVE_METHODS;
+var SPEND_METHODS = OPENRECEIVE_NWC_SPEND_METHODS;
 function summarizeWalletCapabilities(connection, rawInfo, rawServiceInfo) {
   const unwrappedInfo = unwrapNwcResult(rawInfo);
   const info = recordOrEmpty(unwrappedInfo);
@@ -541,6 +539,7 @@ function delay(milliseconds) {
 }
 
 // src/alby-nwc.ts
+var NOTIFICATION_TYPES = new Set(OPENRECEIVE_NWC_NOTIFICATION_TYPES);
 var AlbyNwcReceiveClient = class {
   /**
    * Safe, loggable view of the connection (wallet pubkey, relays, lud16, and
@@ -829,7 +828,7 @@ var AlbyNwcReceiveClient = class {
       "debug",
       "nwc.notifications.subscribe.requested",
       "Subscribing to NWC-02 payment_received notifications.",
-      { notification_types: ["payment_received"] }
+      { notification_types: OPENRECEIVE_NWC_NOTIFICATION_TYPES }
     );
     let subscription;
     try {
@@ -837,7 +836,7 @@ var AlbyNwcReceiveClient = class {
         client,
         (rawNotification) => {
           const notification = normalizeNwcNotification(rawNotification);
-          if (notification.type !== "payment_received") return;
+          if (!NOTIFICATION_TYPES.has(notification.type)) return;
           this.#log(
             "debug",
             "nwc.notifications.received",
@@ -852,7 +851,7 @@ var AlbyNwcReceiveClient = class {
           } catch {
           }
         },
-        ["payment_received"]
+        [...OPENRECEIVE_NWC_NOTIFICATION_TYPES]
       );
     } catch (error) {
       const normalized = normalizeNwcWalletError(error);
@@ -941,7 +940,7 @@ function createNwcReceiveClient(options) {
   return new AlbyNwcReceiveClient(options);
 }
 
-// src/swap/assets.ts
+// src/generated/swap-tables.ts
 var OPENRECEIVE_SWAP_PAY_IN_ASSETS = [
   "SOL_SOL",
   "USDT_TRON",
@@ -951,7 +950,7 @@ var OPENRECEIVE_SWAP_PAY_IN_ASSETS = [
   "USDT_ETH",
   "USDC_ETH"
 ];
-var ASSET_INFO = {
+var OPENRECEIVE_SWAP_ASSET_INFO = {
   SOL_SOL: {
     pay_in_asset: "SOL_SOL",
     label: "SOL",
@@ -1002,6 +1001,37 @@ var ASSET_INFO = {
     network: "ETH"
   }
 };
+var OPENRECEIVE_SWAP_PROVIDER_STATES = [
+  "creating_provider_order",
+  "awaiting_deposit",
+  "confirming",
+  "exchanging",
+  "paying_invoice",
+  "completed",
+  "expired",
+  "refund_required",
+  "refund_pending",
+  "refunded",
+  "attention",
+  "failed"
+];
+var OPENRECEIVE_SWAP_STATE_TABLE = {
+  creating_provider_order: { phase: "preparing", terminal: false },
+  awaiting_deposit: { phase: "awaiting_deposit", terminal: false },
+  confirming: { phase: "processing", terminal: false },
+  exchanging: { phase: "processing", terminal: false },
+  paying_invoice: { phase: "processing", terminal: false },
+  completed: { phase: "settling", terminal: false },
+  expired: { phase: "terminal", terminal: true },
+  refund_required: { phase: "refund", terminal: false },
+  refund_pending: { phase: "refund", terminal: false },
+  refunded: { phase: "terminal", terminal: true },
+  attention: { phase: "attention", terminal: true },
+  failed: { phase: "terminal", terminal: true }
+};
+
+// src/swap/assets.ts
+var ASSET_INFO = OPENRECEIVE_SWAP_ASSET_INFO;
 function isSwapPayInAsset(value) {
   return typeof value === "string" && OPENRECEIVE_SWAP_PAY_IN_ASSETS.includes(value);
 }
@@ -1408,6 +1438,124 @@ function readFixedFloatCurrencies(data) {
 
 // src/swap/fixedfloat-orders.ts
 import { recordOrEmpty as recordOrEmpty5 } from "@openreceive/core";
+
+// src/generated/swap-state-table.ts
+var OPENRECEIVE_SWAP_STATUS_ROWS = [
+  {
+    status: "DONE",
+    refund_tx_present: true,
+    choice: "any",
+    state: "refunded",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "FINISHED",
+    refund_tx_present: true,
+    choice: "any",
+    state: "refunded",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "NEW",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "awaiting_deposit",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "PENDING",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "confirming",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "EXCHANGE",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "exchanging",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "WITHDRAW",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "paying_invoice",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "DONE",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "completed",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "EXPIRED",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "expired",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "EMERGENCY",
+    refund_tx_present: true,
+    choice: "REFUND",
+    state: "refunded",
+    refund_reason_from_emergency: true
+  },
+  {
+    status: "EMERGENCY",
+    refund_tx_present: "any",
+    choice: "REFUND",
+    state: "refund_pending",
+    refund_reason_from_emergency: true
+  },
+  {
+    status: "EMERGENCY",
+    refund_tx_present: "any",
+    choice: "EXCHANGE",
+    state: "attention",
+    attention_reason: "provider_reported_emergency",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "EMERGENCY",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "refund_required",
+    refund_reason_from_emergency: true
+  },
+  {
+    status: "*",
+    status_contains: "FAIL",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "failed",
+    refund_reason_from_emergency: false
+  },
+  {
+    status: "*",
+    refund_tx_present: "any",
+    choice: "any",
+    state: "attention",
+    attention_reason: "provider_status_unrecognized",
+    refund_reason_from_emergency: false
+  }
+];
+var OPENRECEIVE_SWAP_EMERGENCY_STATUS_ALIASES = {
+  OVER: "MORE",
+  OVERPAID: "MORE"
+};
+var OPENRECEIVE_SWAP_REFUND_REASON_ROWS = [
+  { all_of: ["LESS", "EXPIRED"], refund_reason: "underpaid_and_late" },
+  { all_of: ["MORE", "EXPIRED"], refund_reason: "overpaid_and_late" },
+  { all_of: ["LESS"], refund_reason: "underpaid" },
+  { all_of: ["MORE"], refund_reason: "overpaid" },
+  { all_of: ["EXPIRED"], refund_reason: "late_deposit" }
+];
+
+// src/swap/fixedfloat-orders.ts
 function normalizeFixedFloatOrder(data, input) {
   const fields = extractFixedFloatOrderFields(recordOrEmpty5(data), input);
   const { attention, attention_reason } = fields.status;
@@ -1492,58 +1640,28 @@ function extractFixedFloatOrderFields(record, input) {
 }
 function normalizeFixedFloatStatus(status, emergency, refundTxId) {
   const normalized = status.toUpperCase();
-  if (refundTxId !== void 0 && (normalized === "DONE" || normalized === "FINISHED")) {
-    return { state: "refunded" };
-  }
-  if (normalized === "NEW") return { state: "awaiting_deposit" };
-  if (normalized === "PENDING") return { state: "confirming" };
-  if (normalized === "EXCHANGE") return { state: "exchanging" };
-  if (normalized === "WITHDRAW") return { state: "paying_invoice" };
-  if (normalized === "DONE") return { state: "completed" };
-  if (normalized === "EXPIRED") return { state: "expired" };
-  if (normalized === "EMERGENCY") {
-    const choice = optionalStringField(emergency, "choice")?.toUpperCase();
-    const emergencyStatuses = optionalStringArrayField(emergency, "status").map(
-      (item) => item.toUpperCase()
-    );
-    const refundReason = refundReasonFromEmergencyStatuses(emergencyStatuses);
-    if (choice === "REFUND" && refundTxId !== void 0) {
-      return {
-        state: "refunded",
-        ...refundReason === void 0 ? {} : { refund_reason: refundReason }
-      };
-    }
-    if (choice === "REFUND") {
-      return {
-        state: "refund_pending",
-        ...refundReason === void 0 ? {} : { refund_reason: refundReason }
-      };
-    }
-    if (choice === "EXCHANGE") {
-      return {
-        state: "attention",
-        attention: true,
-        attention_reason: "provider_reported_emergency"
-      };
-    }
-    return {
-      state: "refund_required",
-      ...refundReason === void 0 ? {} : { refund_reason: refundReason }
-    };
-  }
-  if (normalized.includes("FAIL")) return { state: "failed" };
-  return { state: "attention", attention: true, attention_reason: "provider_status_unrecognized" };
+  const refundTxPresent = refundTxId !== void 0;
+  const choice = optionalStringField(emergency, "choice")?.toUpperCase();
+  const row = OPENRECEIVE_SWAP_STATUS_ROWS.find(
+    (candidate) => (candidate.status === "*" ? candidate.status_contains === void 0 || normalized.includes(candidate.status_contains) : candidate.status === normalized) && (candidate.refund_tx_present === "any" || candidate.refund_tx_present === refundTxPresent) && (candidate.choice === "any" || (choice === void 0 ? candidate.choice === "absent" : candidate.choice === choice))
+  );
+  const refundReason = row.refund_reason_from_emergency ? refundReasonFromEmergencyStatuses(optionalStringArrayField(emergency, "status")) : void 0;
+  return {
+    state: row.state,
+    ...row.attention_reason === void 0 ? {} : { attention: true, attention_reason: row.attention_reason },
+    ...refundReason === void 0 ? {} : { refund_reason: refundReason }
+  };
 }
 function refundReasonFromEmergencyStatuses(statuses) {
-  const less = statuses.includes("LESS");
-  const more = statuses.includes("MORE") || statuses.includes("OVER") || statuses.includes("OVERPAID");
-  const expired = statuses.includes("EXPIRED");
-  if (less && expired) return "underpaid_and_late";
-  if (more && expired) return "overpaid_and_late";
-  if (less) return "underpaid";
-  if (more) return "overpaid";
-  if (expired) return "late_deposit";
-  return void 0;
+  const present = new Set(
+    statuses.map((item) => {
+      const upper = item.toUpperCase();
+      return OPENRECEIVE_SWAP_EMERGENCY_STATUS_ALIASES[upper] ?? upper;
+    })
+  );
+  return OPENRECEIVE_SWAP_REFUND_REASON_ROWS.find(
+    (row) => row.all_of.every((item) => present.has(item))
+  )?.refund_reason;
 }
 function isRefundPathState(state) {
   return state === "refund_required" || state === "refund_pending" || state === "refunded";
@@ -2418,6 +2536,8 @@ export {
   HEX_64,
   createNwcReceiveClient,
   OPENRECEIVE_SWAP_PAY_IN_ASSETS,
+  OPENRECEIVE_SWAP_PROVIDER_STATES,
+  OPENRECEIVE_SWAP_STATE_TABLE,
   isSwapPayInAsset,
   listSwapAssetInfo,
   TransientSwapCache,

package/dist/cli.js

@@ -2,7 +2,7 @@ import {
   createNwcReceiveClient,
   readLscConnectionsFromEnvironment,
   redactSecrets
-} from "./chunk-LWN4JJ24.js";
+} from "./chunk-65UPROSE.js";
 
 // src/cli.ts
 import { existsSync } from "fs";

package/dist/index.d.ts

@@ -148,7 +148,18 @@ declare class AlbyNwcReceiveClient implements ReceiveNwcClient {
 declare function createNwcReceiveClient(options: AlbyNwcReceiveClientOptions): AlbyNwcReceiveClient;
 
 declare const OPENRECEIVE_SWAP_PAY_IN_ASSETS: readonly ["SOL_SOL", "USDT_TRON", "USDT_SOL", "USDC_SOL", "ETH_ETH", "USDT_ETH", "USDC_ETH"];
-type SwapPayInAsset = (typeof OPENRECEIVE_SWAP_PAY_IN_ASSETS)[number];
+type GeneratedSwapPayInAsset = (typeof OPENRECEIVE_SWAP_PAY_IN_ASSETS)[number];
+declare const OPENRECEIVE_SWAP_PROVIDER_STATES: readonly ["creating_provider_order", "awaiting_deposit", "confirming", "exchanging", "paying_invoice", "completed", "expired", "refund_required", "refund_pending", "refunded", "attention", "failed"];
+type GeneratedSwapProviderState = (typeof OPENRECEIVE_SWAP_PROVIDER_STATES)[number];
+type GeneratedSwapPhase = "preparing" | "awaiting_deposit" | "processing" | "settling" | "terminal" | "refund" | "attention";
+declare const OPENRECEIVE_SWAP_ATTENTION_REASONS: readonly ["provider_reported_emergency", "provider_status_unrecognized", "provider_completed_without_wallet_settlement"];
+type GeneratedSwapAttentionReason = (typeof OPENRECEIVE_SWAP_ATTENTION_REASONS)[number];
+declare const OPENRECEIVE_SWAP_REFUND_REASONS: readonly ["underpaid", "overpaid", "late_deposit", "underpaid_and_late", "overpaid_and_late"];
+type GeneratedSwapRefundReason = (typeof OPENRECEIVE_SWAP_REFUND_REASONS)[number];
+declare const OPENRECEIVE_SWAP_AVAILABILITY_REASONS: readonly ["provider_unconfigured", "amount_too_small", "amount_too_large", "pair_temporarily_unavailable", "region_unsupported", "provider_rate_limited", "provider_unreachable"];
+type GeneratedSwapAvailabilityReason = (typeof OPENRECEIVE_SWAP_AVAILABILITY_REASONS)[number];
+
+type SwapPayInAsset = GeneratedSwapPayInAsset;
 
 interface SwapCacheResolveOptions<T> {
     readonly refreshSeconds: number;
@@ -169,15 +180,16 @@ declare class TransientSwapCache {
     resolve<T>(key: string, options: SwapCacheResolveOptions<T>): Promise<T>;
 }
 
-type SwapProviderState = "creating_provider_order" | "awaiting_deposit" | "confirming" | "exchanging" | "paying_invoice" | "completed" | "expired" | "refund_required" | "refund_pending" | "refunded" | "attention" | "failed";
-type SwapAvailabilityReason = "provider_unconfigured" | "amount_too_small" | "amount_too_large" | "pair_temporarily_unavailable" | "region_unsupported" | "provider_rate_limited" | "provider_unreachable";
+type SwapProviderState = GeneratedSwapProviderState;
+type SwapAvailabilityReason = GeneratedSwapAvailabilityReason;
 /**
  * Why a swap attempt entered the `attention` state and needs human/support review.
  * Every code path that sets `attention: true` records one of these so a dashboard or
- * runbook can branch on the cause instead of a bare boolean. See the "Attention"
- * section of docs/internal/swap-operations.md for the per-reason operator runbook.
+ * runbook can branch on the cause instead of a bare boolean. The FixedFloat status
+ * mapping that produces them is pinned by spec/test-vectors/swap-state.json;
+ * `provider_completed_without_wallet_settlement` is reserved and not emitted yet.
  */
-type SwapAttentionReason = "provider_completed_without_wallet_settlement" | "provider_order_creation_stale" | "provider_order_creation_failed" | "provider_order_creation_needs_reconcile" | "provider_reported_emergency" | "provider_status_unrecognized" | "provider_order_expires_after_shadow_invoice";
+type SwapAttentionReason = GeneratedSwapAttentionReason;
 /**
  * Why a swap attempt entered the refund path (`refund_required` → `refunded`).
  * Mapped from FixedFloat `emergency.status` (LESS / MORE / EXPIRED). An overpay
@@ -185,7 +197,7 @@ type SwapAttentionReason = "provider_completed_without_wallet_settlement" | "pro
  * fixed-amount bolt11, so there is nothing to exchange the surplus into and
  * `choice=EXCHANGE` is not a path this client takes.
  */
-type SwapRefundReason = "underpaid" | "overpaid" | "late_deposit" | "underpaid_and_late" | "overpaid_and_late";
+type SwapRefundReason = GeneratedSwapRefundReason;
 interface SwapQuote {
     readonly pay_amount?: string;
     readonly minimum_pay_amount?: string;
@@ -407,8 +419,12 @@ declare function fixedFloatCompatibleSwapProvider(options: FixedFloatCompatibleS
  * - `refund`           — a refund is required, staged, or in flight.
  * - `attention`        — needs operator/support review (funds may be stuck).
  * - `terminal`         — the attempt is over and will not change (expired/refunded/failed).
+ *
+ * The state → phase/terminal table itself is kernel vocabulary
+ * (spec/data/kernel-tables.json) generated into every engine; this module adds the
+ * payer-facing copy, which only the JS checkout renders.
  */
-type SwapPhase = "preparing" | "awaiting_deposit" | "processing" | "settling" | "refund" | "attention" | "terminal";
+type SwapPhase = GeneratedSwapPhase;
 interface SwapStateInfo {
     /** The provider state this describes. */
     readonly state: SwapProviderState;

package/dist/index.js

@@ -1,6 +1,8 @@
 import {
   HEX_64,
   OPENRECEIVE_SWAP_PAY_IN_ASSETS,
+  OPENRECEIVE_SWAP_PROVIDER_STATES,
+  OPENRECEIVE_SWAP_STATE_TABLE,
   ReceiveCheckoutValidationError,
   TransientSwapCache,
   WalletPreflightError,
@@ -17,7 +19,7 @@ import {
   summarizeReconcilePass,
   summarizeSwapProviderApiRequest,
   summarizeSwapProviderApiResponse
-} from "./chunk-LWN4JJ24.js";
+} from "./chunk-65UPROSE.js";
 
 // src/index.ts
 import { OpenReceiveError as OpenReceiveError2 } from "@openreceive/core";
@@ -778,92 +780,65 @@ function toSafeInteger(value, field) {
 import { isValidSwapAddressForPayInAsset } from "@openreceive/core";
 
 // src/swap/state.ts
-var OPENRECEIVE_SWAP_STATES = {
+var SWAP_STATE_COPY = {
   creating_provider_order: {
-    state: "creating_provider_order",
     label: "Preparing payment address",
-    detail: "Creating a payment address.",
-    phase: "preparing",
-    terminal: false
+    detail: "Creating a payment address."
   },
   awaiting_deposit: {
-    state: "awaiting_deposit",
     label: "Waiting for your payment",
-    detail: "Send exactly the amount shown below.",
-    phase: "awaiting_deposit",
-    terminal: false
+    detail: "Send exactly the amount shown below."
   },
   confirming: {
-    state: "confirming",
     label: "Confirming payment",
-    detail: "Your payment was detected and is confirming on-chain.",
-    phase: "processing",
-    terminal: false
+    detail: "Your payment was detected and is confirming on-chain."
   },
   exchanging: {
-    state: "exchanging",
     label: "Converting payment",
-    detail: "Your payment is confirmed and being converted. This usually finishes within a minute.",
-    phase: "processing",
-    terminal: false
+    detail: "Your payment is confirmed and being converted. This usually finishes within a minute."
   },
   paying_invoice: {
-    state: "paying_invoice",
     label: "Finalizing checkout",
-    detail: "The provider is sending the Lightning payment. This usually takes a few seconds.",
-    phase: "processing",
-    terminal: false
+    detail: "The provider is sending the Lightning payment. This usually takes a few seconds."
   },
   completed: {
-    state: "completed",
     label: "Finalizing checkout",
-    detail: "The provider is sending the Lightning payment. This usually takes a few seconds.",
-    phase: "settling",
-    terminal: false
+    detail: "The provider is sending the Lightning payment. This usually takes a few seconds."
   },
   expired: {
-    state: "expired",
     label: "Expired",
-    detail: "No payment was received before the payment window closed.",
-    phase: "terminal",
-    terminal: true
+    detail: "No payment was received before the payment window closed."
   },
   refund_required: {
-    state: "refund_required",
     label: "Refund needed",
-    detail: "Enter an address you control to request a refund.",
-    phase: "refund",
-    terminal: false
+    detail: "Enter an address you control to request a refund."
   },
   refund_pending: {
-    state: "refund_pending",
     label: "Refund pending",
-    detail: "Your refund request has been sent.",
-    phase: "refund",
-    terminal: false
+    detail: "Your refund request has been sent."
   },
   refunded: {
-    state: "refunded",
     label: "Refunded",
-    detail: "The provider reports the refund was sent.",
-    phase: "terminal",
-    terminal: true
+    detail: "The provider reports the refund was sent."
   },
   attention: {
-    state: "attention",
     label: "Needs attention",
-    detail: "This payment needs support review.",
-    phase: "attention",
-    terminal: true
+    detail: "This payment needs support review."
   },
   failed: {
-    state: "failed",
     label: "Failed",
-    detail: "This payment address can no longer be used.",
-    phase: "terminal",
-    terminal: true
+    detail: "This payment address can no longer be used."
   }
 };
+function swapStateInfo(state) {
+  const { phase, terminal } = OPENRECEIVE_SWAP_STATE_TABLE[state];
+  return { state, ...SWAP_STATE_COPY[state], phase, terminal };
+}
+var OPENRECEIVE_SWAP_STATES = Object.freeze(
+  Object.fromEntries(
+    OPENRECEIVE_SWAP_PROVIDER_STATES.map((state) => [state, swapStateInfo(state)])
+  )
+);
 
 // src/swap/weight-budget.ts
 import { compact as compact3 } from "@openreceive/core";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openreceive/node",
-  "version": "0.4.3",
-  "description": "The OpenReceive Node service: receive-only NWC wallet client, checkout and swap service, pricing, and the openreceive CLI.",
+  "version": "0.4.6",
+  "description": "Accept Bitcoin Lightning payments in Node.js with your own wallet and optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
     "lightning",
@@ -17,7 +17,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@getalby/sdk": "^8.0.3",
-    "@openreceive/core": "0.4.3"
+    "@openreceive/core": "0.4.6"
   },
   "bin": {
     "openreceive": "./bin/openreceive.mjs"

package/skills/integrate-openreceive/SKILL.md

@@ -5,7 +5,8 @@ description: >
   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).
+  openreceive-rails gem), or when connecting a BTCPay Server store to a
+  receive-only NWC wallet with the OpenReceive plugin.
 license: MIT
 ---
 
@@ -23,15 +24,25 @@ code** (`NWC_URI`).
 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)
+   - Node, Express: [references/node.md](references/node.md)
+   - Node, Fastify: [references/fastify.md](references/fastify.md)
+   - Node, Next.js App Router: [references/next.md](references/next.md)
    - Rails: [references/rails.md](references/rails.md)
+   - Django: [references/django.md](references/django.md)
+   - Laravel: [references/laravel.md](references/laravel.md)
+   - WordPress + WooCommerce: [references/woocommerce.md](references/woocommerce.md) — the packaged gateway and merchant settings.
+   - BTCPay Server: [references/btcpay.md](references/btcpay.md) — a plugin,
+     configured in BTCPay's store UI or Greenfield API; no application code,
+     no npm packages, no gem. The rest of this file is about the library.
 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`.
+Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
+Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:
+`npm install @openreceive/next @openreceive/react`. Swap the UI package (`vue`,
+`svelte`, `angular`, `elements`) for the frontend the app already has. Install
+(Rails): `bundle add openreceive-rails`.
 
 ## The three server objects