@openreceive/node 0.3.1 → 0.3.3

package/dist/cli.d.ts

@@ -48,6 +48,15 @@ declare function runScaffoldPayments(input: RunScaffoldPaymentsInput): Promise<n
 interface CliIo {
     write(message: string): void;
 }
+/** The two doctor probe methods a wallet client must answer. */
+interface DoctorWalletClient {
+    preflight(): Promise<{
+        readonly methods: readonly string[];
+        readonly spendCapabilityAdvertised: boolean;
+        readonly warnings: readonly string[];
+    }>;
+    close(): Promise<void>;
+}
 interface CliOptions {
     readonly argv: readonly string[];
     readonly env?: NodeJS.ProcessEnv;
@@ -57,7 +66,16 @@ interface CliOptions {
     readonly stdin?: NodeJS.ReadableStream;
     readonly isTTY?: boolean;
     readonly prompt?: (question: string) => Promise<string>;
+    /**
+     * Testing seam for `doctor`: builds the wallet client the relay probe uses.
+     * Defaults to the real NWC client.
+     */
+    readonly walletClientFactory?: (options: {
+        connectionString: string;
+        allowSpendCapableWallet: boolean;
+        spendCapabilityWarning: (message: string) => void;
+    }) => DoctorWalletClient;
 }
 declare function runCli(options: CliOptions): Promise<number>;
 
-export { type CliIo, type CliOptions, finalizeScaffoldOptions, parseScaffoldPaymentsArgv, renderScaffoldPaymentsFiles, runCli, runScaffoldPayments };
+export { type CliIo, type CliOptions, type DoctorWalletClient, finalizeScaffoldOptions, parseScaffoldPaymentsArgv, renderScaffoldPaymentsFiles, runCli, runScaffoldPayments };

package/dist/cli.js

@@ -1,10 +1,20 @@
 import {
+  createNwcReceiveClient,
   readLscConnectionsFromEnvironment,
   redactSecrets
-} from "./chunk-6HALOJYF.js";
+} from "./chunk-ZYS6QECW.js";
 
 // src/cli.ts
-import { formatInvalidNwcMessage, NwcUriParseError, parseNwcUri } from "@openreceive/core";
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import path2 from "path";
+import { pathToFileURL } from "url";
+import {
+  formatInvalidNwcMessage,
+  NwcUriParseError,
+  OPENRECEIVE_NWC_CODE_HELP_URL,
+  parseNwcUri
+} from "@openreceive/core";
 
 // src/scaffold/index.ts
 import { createInterface } from "readline/promises";
@@ -912,13 +922,26 @@ var HELP = `
 Usage: openreceive <command> [options]
 
 Commands:
-  doctor              Validate server configuration (Node, NWC_URI, swap providers).
+  doctor              Validate server configuration: Node, NWC_URI, swap
+                      providers, and a receive-only wallet probe over the relay.
+                      --db and --url extend the checks; exits 1 on problems.
   debug-report        Print the same diagnostics as a redacted support report
                       (alias of doctor; always exits 0).
   scaffold payments   Emit the openreceive_payments + openreceive_meta migration and wiring guide for your ORM.
 
 Options:
   -h, --help           Show this help.
+
+Doctor options:
+  --db <target>             Also check the payment tables exist: a SQLite file
+                            path, or a postgres:// / mysql:// URL (the matching
+                            driver is loaded from this project's node_modules).
+  --url <base-url>          Also check the OpenReceive routes answer on a
+                            running app, e.g. --url http://localhost:3000.
+  --prefix <path>           Route prefix for --url (default /openreceive).
+  --table-name <name>       Payments table for --db (default openreceive_payments).
+  --meta-table-name <name>  Reconcile-gate table for --db (default openreceive_meta).
+  --offline                 Skip the wallet relay probe.
 `.trim();
 async function runCli(options) {
   const stdout = options.stdout ?? process.stdout;
@@ -933,8 +956,14 @@ async function runCli(options) {
       return 0;
     }
     if (command === "doctor" || command === "debug-report") {
-      if (args.length > 0) throw new Error(`Unexpected option: ${args[0]}`);
-      return runDiagnostics({ command, env, cwd, stdout });
+      return await runDiagnostics({
+        command,
+        flags: parseDiagnosticsArgv(args),
+        env,
+        cwd,
+        stdout,
+        walletClientFactory: options.walletClientFactory
+      });
     }
     if (command === "scaffold") {
       const [target = "help", ...scaffoldArgs] = args;
@@ -967,8 +996,42 @@ ${HELP}
     return 1;
   }
 }
-function runDiagnostics(input) {
-  const nwc = input.env.NWC_URI?.trim();
+function parseDiagnosticsArgv(args) {
+  const flags = {
+    db: void 0,
+    url: void 0,
+    prefix: "/openreceive",
+    tableName: "openreceive_payments",
+    metaTableName: "openreceive_meta",
+    offline: false
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const valueFor = (name) => {
+      const value = args[index + 1];
+      if (value === void 0 || value.startsWith("--")) {
+        throw new Error(`${name} needs a value. See \`openreceive --help\`.`);
+      }
+      index += 1;
+      return value;
+    };
+    if (arg === "--db") flags.db = valueFor("--db");
+    else if (arg === "--url") flags.url = valueFor("--url");
+    else if (arg === "--prefix") flags.prefix = valueFor("--prefix");
+    else if (arg === "--table-name") flags.tableName = valueFor("--table-name");
+    else if (arg === "--meta-table-name") flags.metaTableName = valueFor("--meta-table-name");
+    else if (arg === "--offline") flags.offline = true;
+    else throw new Error(`Unexpected option: ${arg}. See \`openreceive --help\`.`);
+  }
+  if (!flags.prefix.startsWith("/")) flags.prefix = `/${flags.prefix}`;
+  return flags;
+}
+var WALLET_PROBE_TIMEOUT_MS = 1e4;
+var HTTP_PROBE_TIMEOUT_MS = 5e3;
+var SPEND_OVERRIDE_TRUE = /* @__PURE__ */ new Set(["1", "true", "yes"]);
+async function runDiagnostics(input) {
+  const { flags, env } = input;
+  const nwc = env.NWC_URI?.trim();
   let nwcError;
   try {
     if (nwc) parseNwcUri(nwc);
@@ -978,7 +1041,7 @@ function runDiagnostics(input) {
   let lscConnections = 0;
   let lscError;
   try {
-    lscConnections = readLscConnectionsFromEnvironment(input.env).length;
+    lscConnections = readLscConnectionsFromEnvironment(env).length;
   } catch (error) {
     lscError = error;
   }
@@ -990,10 +1053,211 @@ function runDiagnostics(input) {
     `NWC_URI: ${nwcError === void 0 ? nwc ? "present-redacted" : "missing" : safeErrorMessage(nwcError)}`,
     `LSC_URI connections: ${lscError === void 0 ? lscConnections : safeErrorMessage(lscError)}`
   ];
+  let failed = nwcError !== void 0 || !nwc || lscError !== void 0;
+  if (nwc && nwcError === void 0 && !flags.offline) {
+    const wallet = await probeWallet({
+      nwc,
+      env,
+      walletClientFactory: input.walletClientFactory
+    });
+    failed = failed || !wallet.ok;
+    lines.push(...wallet.lines);
+  } else if (flags.offline) {
+    lines.push("wallet: probe skipped (--offline)");
+  } else {
+    lines.push("wallet: probe skipped (no parseable NWC_URI to probe)");
+  }
+  if (flags.db === void 0) {
+    lines.push(
+      "database: skipped \u2014 pass --db <sqlite file | postgres:// | mysql:// URL> to check the payment tables exist"
+    );
+  } else {
+    const database = await checkDatabaseMigrated({ ...flags, db: flags.db, cwd: input.cwd });
+    failed = failed || !database.ok;
+    lines.push(...database.lines);
+  }
+  if (flags.url === void 0) {
+    lines.push(
+      "routes: skipped \u2014 pass --url http://localhost:3000 to check the OpenReceive routes answer"
+    );
+  } else {
+    const routes = await checkRoutesMounted({ url: flags.url, prefix: flags.prefix });
+    failed = failed || !routes.ok;
+    lines.push(...routes.lines);
+  }
   input.stdout.write(`${lines.join("\n")}
 `);
   if (input.command === "debug-report") return 0;
-  return nwcError !== void 0 || !nwc || lscError !== void 0 ? 1 : 0;
+  return failed ? 1 : 0;
+}
+async function probeWallet(input) {
+  const allowSpendCapableWallet = SPEND_OVERRIDE_TRUE.has(
+    input.env.OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC?.trim().toLowerCase() ?? ""
+  );
+  const overrideWarnings = [];
+  const factory = input.walletClientFactory ?? ((options) => createNwcReceiveClient(options));
+  const client = factory({
+    connectionString: input.nwc,
+    allowSpendCapableWallet,
+    spendCapabilityWarning: (message) => overrideWarnings.push(message)
+  });
+  let timer;
+  try {
+    const summary = await Promise.race([
+      client.preflight(),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new Error(
+              `no relay answered within ${WALLET_PROBE_TIMEOUT_MS / 1e3}s. Check the network and the wss relay in the NWC code, or rerun with --offline to skip the probe.`
+            )
+          );
+        }, WALLET_PROBE_TIMEOUT_MS);
+        timer.unref?.();
+      })
+    ]);
+    if (summary.spendCapabilityAdvertised) {
+      return {
+        ok: false,
+        lines: [
+          `wallet: reachable but SPEND-CAPABLE (override active). A leaked code can drain this wallet \u2014 mint a receive-only code: ${OPENRECEIVE_NWC_CODE_HELP_URL}`,
+          ...summary.warnings.map((warning) => `wallet: ${warning}`)
+        ]
+      };
+    }
+    return {
+      ok: true,
+      lines: [
+        `wallet: reachable, receive-only (${summary.methods.join(", ")})`,
+        ...summary.warnings.map((warning) => `wallet: ${warning}`)
+      ]
+    };
+  } catch (error) {
+    return { ok: false, lines: [`wallet: ${safeErrorMessage(error)}`] };
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+    try {
+      await client.close();
+    } catch {
+    }
+  }
+}
+async function checkDatabaseMigrated(input) {
+  const fix = `run \`npx openreceive scaffold payments --orm <your orm>\` and apply the emitted migration through your normal workflow \u2014 https://openreceive.org/guides/storage.md`;
+  try {
+    const present = await listPresentTables(input);
+    const missing = [input.tableName, input.metaTableName].filter(
+      (table) => !present.includes(table)
+    );
+    if (missing.length === 0) {
+      return {
+        ok: true,
+        lines: [`database: ${input.tableName} and ${input.metaTableName} present`]
+      };
+    }
+    return {
+      ok: false,
+      lines: [`database: ${missing.join(" and ")} missing \u2014 the migration has not run; ${fix}`]
+    };
+  } catch (error) {
+    return { ok: false, lines: [`database: ${safeErrorMessage(error)}`] };
+  }
+}
+async function listPresentTables(input) {
+  const tables = [input.tableName, input.metaTableName];
+  if (/^postgres(ql)?:/.test(input.db)) {
+    const pg = await importFromHostProject("pg", input.cwd);
+    const client = new pg.Client({
+      connectionString: input.db,
+      connectionTimeoutMillis: HTTP_PROBE_TIMEOUT_MS
+    });
+    await client.connect();
+    try {
+      const result = await client.query(
+        "SELECT to_regclass($1) AS a, to_regclass($2) AS b",
+        tables
+      );
+      const row = result.rows[0] ?? {};
+      return tables.filter((_, index) => row[index === 0 ? "a" : "b"] !== null);
+    } finally {
+      await client.end();
+    }
+  }
+  if (/^mysql:/.test(input.db)) {
+    const mysql = await importFromHostProject("mysql2/promise", input.cwd);
+    const connection = await mysql.createConnection(input.db);
+    try {
+      const [rows] = await connection.query(
+        "SELECT table_name AS name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name IN (?, ?)",
+        tables
+      );
+      return rows.map((row) => String(row.name));
+    } finally {
+      await connection.end();
+    }
+  }
+  const sqlitePath = path2.isAbsolute(input.db) ? input.db : path2.join(input.cwd, input.db);
+  if (!existsSync(sqlitePath)) {
+    throw new Error(
+      `no SQLite database at ${sqlitePath}. Pass the file your app opens, or a postgres:// / mysql:// URL.`
+    );
+  }
+  const { DatabaseSync } = await import("sqlite");
+  const database = new DatabaseSync(sqlitePath, { readOnly: true });
+  try {
+    const rows = database.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (?, ?)").all(...tables);
+    return rows.map((row) => row.name);
+  } finally {
+    database.close();
+  }
+}
+async function importFromHostProject(specifier, cwd) {
+  let resolved;
+  try {
+    resolved = createRequire(path2.join(cwd, "package.json")).resolve(specifier);
+  } catch {
+    throw new Error(
+      `this database needs the ${JSON.stringify(specifier.split("/")[0])} driver, which is not installed here. Install it (\`npm install ${specifier.split("/")[0]}\`) or point --db at the SQLite file directly.`
+    );
+  }
+  const mod = await import(pathToFileURL(resolved).href);
+  return mod.default ?? mod;
+}
+async function checkRoutesMounted(input) {
+  const base = input.url.replace(/\/+$/, "");
+  const prefix = input.prefix.replace(/\/+$/, "");
+  const probe = `${base}${prefix}/__doctor-probe__`;
+  const fix = `mount the router (\`app.use(openreceive)\` \u2014 https://openreceive.org/guides/quickstart-node.md), or pass --prefix if it is mounted somewhere other than ${prefix}`;
+  let response;
+  try {
+    response = await fetch(probe, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(HTTP_PROBE_TIMEOUT_MS)
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      lines: [
+        `routes: could not reach ${base} (${safeErrorMessage(error)}) \u2014 is the app running at that URL?`
+      ]
+    };
+  }
+  let body;
+  try {
+    body = JSON.parse(await response.text());
+  } catch {
+    body = void 0;
+  }
+  const message = typeof body === "object" && body !== null && "message" in body ? String(body.message) : "";
+  if (message.startsWith("No OpenReceive route matched")) {
+    return { ok: true, lines: [`routes: OpenReceive router answering at ${base}${prefix}`] };
+  }
+  return {
+    ok: false,
+    lines: [
+      `routes: nothing OpenReceive answered at ${base}${prefix} (HTTP ${response.status}) \u2014 ${fix}`
+    ]
+  };
 }
 function safeErrorMessage(error) {
   if (error instanceof Error) return redactSecrets(error.message);

package/dist/index.d.ts

@@ -180,10 +180,12 @@ type SwapAvailabilityReason = "provider_unconfigured" | "amount_too_small" | "am
 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";
 /**
  * Why a swap attempt entered the refund path (`refund_required` → `refunded`).
- * Mapped from FixedFloat `emergency.status` (LESS / EXPIRED). Overpay (MORE/OVER)
- * goes to `attention`, not here.
+ * Mapped from FixedFloat `emergency.status` (LESS / MORE / EXPIRED). An overpay
+ * refunds the WHOLE deposit like every other emergency: the payout is a
+ * 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" | "late_deposit" | "underpaid_and_late";
+type SwapRefundReason = "underpaid" | "overpaid" | "late_deposit" | "underpaid_and_late" | "overpaid_and_late";
 interface SwapQuote {
     readonly pay_amount?: string;
     readonly minimum_pay_amount?: string;
@@ -239,7 +241,7 @@ interface SwapOrder {
     readonly attention_reason?: SwapAttentionReason;
     /**
      * Why a refund is needed, when the attempt is on the refund path. Mapped from
-     * FixedFloat `emergency.status` (LESS / EXPIRED).
+     * FixedFloat `emergency.status` (LESS / MORE / EXPIRED).
      */
     readonly refund_reason?: SwapRefundReason;
     /**