@openreceive/node 0.2.1

package/dist/cli.js

@@ -0,0 +1,1009 @@
+import {
+  readLscConnectionsFromEnvironment,
+  redactSecrets
+} from "./chunk-6HALOJYF.js";
+
+// src/cli.ts
+import { formatInvalidNwcMessage, NwcUriParseError, parseNwcUri } from "@openreceive/core";
+
+// src/scaffold/index.ts
+import { createInterface } from "readline/promises";
+import { stdin as defaultStdin, stdout as defaultStdout } from "process";
+
+// src/scaffold/shared.ts
+import { paymentsDdlStatements } from "@openreceive/core";
+function assertPaymentsTableName(value, flag) {
+  const trimmed = value.trim();
+  if (!/^[a-z][a-z0-9_]*$/.test(trimmed)) {
+    throw new Error(`${flag} must be a lowercase SQL identifier.`);
+  }
+  return trimmed;
+}
+function isSqlite(options) {
+  return options.dialect === "sqlite";
+}
+function canonicalPaymentsDdlStatements(options) {
+  return paymentsDdlStatements({
+    dialect: options.dialect,
+    tableName: options.tableName,
+    metaTableName: options.metaTableName
+  });
+}
+
+// src/scaffold/types.ts
+var OPENRECEIVE_ORMS = ["prisma", "drizzle", "typeorm", "sequelize", "knex"];
+var OPENRECEIVE_DIALECTS = ["postgres", "sqlite"];
+
+// src/scaffold/parse-args.ts
+function parseScaffoldPaymentsArgv(argv) {
+  let help = false;
+  let interactive = false;
+  let orm;
+  let dialect;
+  let tableName;
+  let metaTableName;
+  let force = false;
+  let outDir = ".";
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === void 0) break;
+    if (arg === "-h" || arg === "--help") {
+      help = true;
+      continue;
+    }
+    if (arg === "--interactive" || arg === "-i") {
+      interactive = true;
+      continue;
+    }
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+    if (arg === "--orm") {
+      orm = readEnum(argv[++index], OPENRECEIVE_ORMS, "--orm");
+      continue;
+    }
+    if (arg.startsWith("--orm=")) {
+      orm = readEnum(arg.slice("--orm=".length), OPENRECEIVE_ORMS, "--orm");
+      continue;
+    }
+    if (arg === "--dialect") {
+      dialect = readEnum(argv[++index], OPENRECEIVE_DIALECTS, "--dialect");
+      continue;
+    }
+    if (arg.startsWith("--dialect=")) {
+      dialect = readEnum(arg.slice("--dialect=".length), OPENRECEIVE_DIALECTS, "--dialect");
+      continue;
+    }
+    if (arg === "--table-name") {
+      tableName = assertPaymentsTableName(
+        requiredValue(argv[++index], "--table-name"),
+        "--table-name"
+      );
+      continue;
+    }
+    if (arg.startsWith("--table-name=")) {
+      tableName = assertPaymentsTableName(arg.slice("--table-name=".length), "--table-name");
+      continue;
+    }
+    if (arg === "--meta-table-name") {
+      metaTableName = assertPaymentsTableName(
+        requiredValue(argv[++index], "--meta-table-name"),
+        "--meta-table-name"
+      );
+      continue;
+    }
+    if (arg.startsWith("--meta-table-name=")) {
+      metaTableName = assertPaymentsTableName(
+        arg.slice("--meta-table-name=".length),
+        "--meta-table-name"
+      );
+      continue;
+    }
+    if (arg === "--out-dir") {
+      outDir = requiredValue(argv[++index], "--out-dir");
+      continue;
+    }
+    if (arg.startsWith("--out-dir=")) {
+      outDir = arg.slice("--out-dir=".length);
+      if (!outDir) throw new Error("--out-dir requires a path.");
+      continue;
+    }
+    throw new Error(`Unexpected option: ${arg}`);
+  }
+  return {
+    help,
+    interactive,
+    partial: {
+      ...orm === void 0 ? {} : { orm },
+      ...dialect === void 0 ? {} : { dialect },
+      ...tableName === void 0 ? {} : { tableName },
+      ...metaTableName === void 0 ? {} : { metaTableName },
+      force,
+      outDir
+    }
+  };
+}
+function finalizeScaffoldOptions(partial) {
+  if (partial.orm === void 0) {
+    throw new Error(
+      "Missing --orm. Use --orm prisma|drizzle|typeorm|sequelize|knex, or run with --interactive."
+    );
+  }
+  return {
+    orm: partial.orm,
+    dialect: partial.dialect ?? "postgres",
+    tableName: assertPaymentsTableName(partial.tableName ?? "openreceive_payments", "--table-name"),
+    metaTableName: assertPaymentsTableName(
+      partial.metaTableName ?? "openreceive_meta",
+      "--meta-table-name"
+    ),
+    outDir: partial.outDir,
+    force: partial.force
+  };
+}
+function requiredValue(value, flag) {
+  if (value === void 0 || value.length === 0) {
+    throw new Error(`${flag} requires a value.`);
+  }
+  return value;
+}
+function readEnum(value, allowed, flag) {
+  const raw = requiredValue(value, flag);
+  if (allowed.includes(raw)) return raw;
+  throw new Error(`${flag} must be one of: ${allowed.join(", ")}.`);
+}
+
+// src/scaffold/orms/drizzle.ts
+import {
+  fulfillmentNote,
+  paymentsHashCheckSql,
+  paymentsIndexName,
+  paymentsStatusCheckSql
+} from "@openreceive/core";
+
+// src/scaffold/wiring-guide.ts
+import { fulfillmentNoteMarkdown, paymentsColumnNames, paymentsSeedSql } from "@openreceive/core";
+var PLACEHOLDER_NOTE = "Custom adapters receive SQL already written for their own dialect (`?` on sqlite, `$1`-style on postgres) \u2014 pass it to the driver verbatim \u2014 and must return SELECT rows as plain objects.";
+function wiringGuideMarkdown(options) {
+  const columnList = paymentsColumnNames().map((name) => `\`${name}\``).join(", ");
+  return `# OpenReceive payments wiring
+
+Generated for **${options.orm}** (${options.dialect}). This scaffold emits only the
+\`${options.tableName}\` + \`${options.metaTableName}\` schema/migration and this guide.
+The OpenReceive library owns the payment-attempt repository at runtime \u2014 commit
+locking, settlement write-once, the durable reconcile gate, and reconciliation
+state transitions all run inside \`@openreceive/http\`, never in generated or
+hand-written host code.
+
+## 1. Run the migration
+
+${migrationStep(options)}
+
+Keep every column: ${columnList}. The timestamp columns (\`paid_at\`,
+\`expires_at\`, \`created_at\`, \`updated_at\`, \`inserted_at\`) are
+unix-seconds integers, never datetime columns. \`inserted_at\` is stamped from the host's
+local clock and is what the per-IP rate limiter counts on
+(\`countAttemptsFromIp\`): dropping it silently disables DB-backed rate
+limiting. Keep the sibling \`${options.metaTableName}\` table (\`key\`, \`value\`,
+\`rev\`) too: it is the durable reconcile gate every worker on this database
+shares.
+
+## 2. Wire the host integration
+
+\`\`\`ts
+import { createHost } from "@openreceive/http";
+
+const host = createHost({ db, amountFor, onPaid });
+\`\`\`
+
+- \`amountFor(reference)\` returns the trusted amount \u2014 never a payer-supplied
+  value \u2014 or \`null\` for a 404.
+- \`onPaid\` fires for the first settled attempt for a reference only, so give
+  every order its own reference and never reuse one. Mark the order paid with
+  your own ORM:
+
+\`\`\`ts
+const onPaid = async ({ reference }) => {
+  ${onPaidUpdateLine(options)}
+};
+\`\`\`
+
+  \`onPaid\` also receives \`{ paymentHash, paidAt, query }\`. \`query\` runs
+  inside the settlement transaction \u2014 use it for transactional outbox rows or to
+  make the order update atomic with the payment record. Plain ORM calls are
+  fine: delivery is at-least-once and retried until \`onPaid\` succeeds, so make
+  it idempotent.
+
+The one-liner above is deliberately the simplest thing that works \u2014 see
+[section 3](#3-fulfilling-exactly-once) before shipping it.
+
+Pass the same \`host\` to your mounted HTTP adapter. No background process is
+needed: every mounted OpenReceive route runs an opportunistic, durably gated
+reconcile pass by default (\`opportunisticReconcile\`), so abandoned checkouts
+settle on any later OpenReceive call \u2014 serverless included.
+
+Optionally, for push settlement the moment the wallet reports
+\`payment_received\`, run the notifications worker as its own long-lived
+process; it listens for NWC-02 notifications AND reconciles periodically (the
+safety net for notifications missed while it was down):
+
+\`\`\`ts
+// worker.ts \u2014 run with: node worker.ts (e.g. a package.json "worker" script)
+import { startNotificationWorker } from "@openreceive/http";
+
+const worker = await startNotificationWorker({ service, host });
+process.once("SIGINT", () => void worker.stop());
+process.once("SIGTERM", () => void worker.stop());
+\`\`\`
+
+## 3. Fulfilling exactly once
+
+${fulfillmentNoteMarkdown(options.tableName)}
+
+In this project's terms, the guarded write goes inside \`onPaid\`:
+
+\`\`\`ts
+const onPaid = async ({ reference, paidAt, query }) => {
+  // \`query\` runs in OpenReceive's settlement transaction, so the order
+  // transition and the payment record commit or roll back together.
+  const claimed = await query(
+    ${guardedUpdateSql(options)},
+    [paidAt, reference],
+  );
+  if (claimed.length === 0) return; // someone else already fulfilled it
+  await shipOrder(reference);
+};
+\`\`\`
+
+## 4. What to pass as \`db\`
+
+${dbSection(options)}
+
+Never expose \`swap_data\` / \`swapData\` from application APIs, logs, or browser bundles.
+`;
+}
+function guardedUpdateSql(options) {
+  const [paidAt, reference] = isSqlite(options) ? ["?", "?"] : ["$1", "$2"];
+  return [
+    "`UPDATE orders",
+    `        SET state = 'paid', paid_at = ${paidAt}`,
+    `      WHERE id = ${reference}`,
+    "        AND state = 'awaiting_payment'",
+    "     RETURNING id`"
+  ].join("\n");
+}
+function onPaidUpdateLine(options) {
+  switch (options.orm) {
+    case "prisma":
+      return 'await prisma.order.update({ where: { id: reference }, data: { state: "paid" } });';
+    case "drizzle":
+      return 'await orm.update(orders).set({ state: "paid" }).where(eq(orders.id, reference));';
+    case "typeorm":
+      return 'await dataSource.getRepository(Order).update({ id: reference }, { state: "paid" });';
+    case "sequelize":
+      return 'await Order.update({ state: "paid" }, { where: { id: reference } });';
+    case "knex":
+      return 'await knex("orders").where({ id: reference }).update({ state: "paid" });';
+  }
+}
+function migrationStep(options) {
+  switch (options.orm) {
+    case "prisma":
+      return `Merge \`prisma/schema.openreceive.prisma\` (both models) into your Prisma schema,
+then run \`npx prisma migrate dev --create-only --name create_openreceive_tables\`.
+Prisma's schema language cannot express the canonical CHECK constraints or the
+\`schema_version\` seed row, so before applying the draft migration, add the
+statements from \`prisma/openreceive-constraints.sql\` to it (the file says
+how), then run \`npx prisma migrate dev\`.`;
+    case "drizzle":
+      return `Export \`payments\` and \`meta\` from
+\`src/db/openreceive-tables.ts\` in your Drizzle schema entrypoint, then run
+\`drizzle-kit generate\` and your usual migrate step. The schema carries both
+canonical CHECK constraints; the \`schema_version\` seed row cannot be expressed
+in schema, so also create a custom migration for it \u2014
+\`drizzle-kit generate --custom --name openreceive-seed\` \u2014 containing:
+
+\`\`\`sql
+${paymentsSeedSql(options.dialect, options.metaTableName)};
+\`\`\``;
+    case "typeorm":
+      return "Register `src/migrations/20260101000000-create-openreceive-tables.ts` in your DataSource `migrations` list, then run migrations through your usual workflow (for example `npx typeorm migration:run`). The migration executes the canonical OpenReceive DDL directly; no entity class is needed.";
+    case "sequelize":
+      return "Keep `migrations/20260101000000-create-openreceive-tables.cjs` in your sequelize-cli migrations folder, then run `npx sequelize-cli db:migrate`. The migration executes the canonical OpenReceive DDL directly; no model class is needed.";
+    case "knex":
+      return "Keep `db/migrations/20260101000000_create_openreceive_tables.mjs` in your Knex migrations directory, then run `npx knex migrate:latest`. The migration executes the canonical OpenReceive DDL directly.";
+  }
+}
+function dbSection(options) {
+  switch (options.orm) {
+    case "prisma":
+      return prismaDbSection(options);
+    case "drizzle":
+      return drizzleDbSection(options);
+    case "typeorm":
+      return typeOrmDbSection(options);
+    case "sequelize":
+      return sequelizeDbSection(options);
+    case "knex":
+      return knexDbSection(options);
+  }
+}
+function prismaDbSection(options) {
+  return `Prisma keeps its connection pool private, so it needs an adapter \u2014
+\`prismaDb\` is the shipped one. It routes each statement to
+\`$queryRawUnsafe\` or \`$executeRawUnsafe\` by whether it returns rows;
+hand-rolling that router is where custom Prisma adapters go wrong. Set the
+dialect to match your Prisma datasource provider. ${PLACEHOLDER_NOTE}
+
+\`\`\`ts
+import { PrismaClient } from "@prisma/client";
+import { prismaDb } from "@openreceive/http";
+
+const prisma = new PrismaClient();
+export const db = prismaDb(prisma, "${options.dialect}");
+\`\`\``;
+}
+function knexDbSection(options) {
+  return `Knex needs an adapter \u2014 \`knexDb\` is the shipped one, and it
+already handles the sqlite-versus-postgres difference in what \`raw\`
+returns. ${PLACEHOLDER_NOTE}
+
+\`\`\`ts
+import { knexDb } from "@openreceive/http";
+import { knex } from "./db.ts"; // your configured Knex instance
+
+export const db = knexDb(knex, "${options.dialect}");
+\`\`\``;
+}
+function typeOrmDbSection(options) {
+  return `TypeORM needs an adapter \u2014 \`typeOrmDb\` is the shipped one, built
+on \`dataSource.transaction\` + \`manager.query\`. ${PLACEHOLDER_NOTE}
+
+\`\`\`ts
+import { typeOrmDb } from "@openreceive/http";
+import { dataSource } from "./data-source.ts"; // your initialized DataSource
+
+export const db = typeOrmDb(dataSource, "${options.dialect}");
+\`\`\``;
+}
+function drizzleDbSection(options) {
+  const snippet = isSqlite(options) ? `\`\`\`ts
+import Database from "better-sqlite3"; // or DatabaseSync from "node:sqlite"
+import { drizzle } from "drizzle-orm/better-sqlite3"; // node:sqlite users: drizzle-orm/node-sqlite
+
+const sqlite = new Database("app.db");
+const orm = drizzle(sqlite);
+const host = createHost({ db: sqlite, amountFor, onPaid });
+\`\`\`` : `\`\`\`ts
+import { Pool } from "pg";
+import { drizzle } from "drizzle-orm/node-postgres";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const orm = drizzle(pool);
+const host = createHost({ db: pool, amountFor, onPaid });
+\`\`\``;
+  const handle = isSqlite(options) ? "the better-sqlite3 / `node:sqlite` Database" : "the `pg` Pool";
+  return `Pass the underlying driver handle you already give \`drizzle(...)\` \u2014
+${handle} \u2014 straight through as \`db\`. The library binds to the driver, so no
+adapter is needed.
+
+${snippet}`;
+}
+function sequelizeDbSection(options) {
+  return `Sequelize needs an adapter \u2014 \`sequelizeDb\` is the shipped one. It
+binds parameters through Sequelize's \`bind\` option and threads the managed
+transaction into every statement inside it, so settlement never runs outside
+the transaction. ${PLACEHOLDER_NOTE}
+
+\`\`\`ts
+import { sequelizeDb } from "@openreceive/http";
+import { sequelize } from "./db.ts"; // your configured Sequelize instance
+
+export const db = sequelizeDb(sequelize, "${options.dialect}");
+\`\`\``;
+}
+
+// src/scaffold/orms/drizzle.ts
+function renderDrizzleFiles(options) {
+  const sqlite = isSqlite(options);
+  const table = options.tableName;
+  const referenceLine = `reference: text("reference").notNull(),`;
+  const indexName = (suffix) => paymentsIndexName(table, suffix);
+  const constraints = [
+    `    uniqueIndex("${indexName("hash_uidx")}").on(table.paymentHash),`,
+    `    index("${indexName("reference_created_idx")}").on(table.reference, table.createdAt),`,
+    `    index("${indexName("status_created_idx")}").on(table.status, table.createdAt),`,
+    `    index("${indexName("client_ip_inserted_idx")}").on(table.clientIp, table.insertedAt),`,
+    // Both canonical CHECK constraints, so drizzle-kit migrations enforce the
+    // same row shape the library's repository relies on.
+    `    check("${indexName("status_check")}", sql\`${paymentsStatusCheckSql()}\`),`,
+    `    check("${indexName("hash_check")}", sql\`${paymentsHashCheckSql(options.dialect)}\`),`
+  ].join("\n");
+  const header = `// Generated by \`npx openreceive scaffold payments\` \u2014 schema only.
+// OpenReceive owns the payment-attempt repository at runtime
+// (createHost in @openreceive/http); these two tables exist so
+// \`drizzle-kit generate\` creates the canonical DDL. Keep every column and
+// CHECK constraint. Timestamps are unix-seconds integer columns, on purpose.
+// The schema_version seed row cannot be expressed here \u2014 the wiring guide's
+// migration step adds it as a custom migration.
+//
+${fulfillmentNote("// ", options.tableName)}
+import { sql } from "drizzle-orm";
+`;
+  const schema = sqlite ? `${header}import { check, index, integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
+
+export const payments = sqliteTable(
+  "${table}",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    ${referenceLine}
+    paymentHash: text("payment_hash").notNull(),
+    status: text("status").notNull().default("pending"),
+    statusReason: text("status_reason"),
+    paidAt: integer("paid_at"),
+    expiresAt: integer("expires_at").notNull(),
+    createdAt: integer("created_at").notNull(),
+    updatedAt: integer("updated_at").notNull(),
+    insertedAt: integer("inserted_at").notNull(),
+    checkoutData: text("checkout_data").notNull(),
+    swapData: text("swap_data"),
+    clientIp: text("client_ip"),
+  },
+  (table) => [
+${constraints}
+  ],
+);
+
+// The durable reconcile gate every worker on this database shares
+// (key/value/rev compare-and-set). Same host database, never a second one.
+export const meta = sqliteTable("${options.metaTableName}", {
+  key: text("key").primaryKey(),
+  value: text("value").notNull(),
+  rev: integer("rev").notNull().default(0),
+});
+` : `${header}import { ${pgImports()} } from "drizzle-orm/pg-core";
+
+export const payments = pgTable(
+  "${table}",
+  {
+    id: bigint("id", { mode: "number" }).primaryKey().generatedAlwaysAsIdentity(),
+    ${referenceLine}
+    paymentHash: text("payment_hash").notNull(),
+    status: text("status").notNull().default("pending"),
+    statusReason: text("status_reason"),
+    paidAt: bigint("paid_at", { mode: "number" }),
+    expiresAt: bigint("expires_at", { mode: "number" }).notNull(),
+    createdAt: bigint("created_at", { mode: "number" }).notNull(),
+    updatedAt: bigint("updated_at", { mode: "number" }).notNull(),
+    insertedAt: bigint("inserted_at", { mode: "number" }).notNull(),
+    checkoutData: text("checkout_data").notNull(),
+    swapData: text("swap_data"),
+    clientIp: text("client_ip"),
+  },
+  (table) => [
+${constraints}
+  ],
+);
+
+// The durable reconcile gate every worker on this database shares
+// (key/value/rev compare-and-set). Same host database, never a second one.
+export const meta = pgTable("${options.metaTableName}", {
+  key: text("key").primaryKey(),
+  value: text("value").notNull(),
+  rev: bigint("rev", { mode: "number" }).notNull().default(0),
+});
+`;
+  return [
+    { path: "src/db/openreceive-tables.ts", contents: schema },
+    { path: "OPENRECEIVE_PAYMENTS.md", contents: wiringGuideMarkdown(options) }
+  ];
+}
+function pgImports() {
+  return ["bigint", "check", "index", "pgTable", "text", "uniqueIndex"].join(", ");
+}
+
+// src/scaffold/orms/knex.ts
+import { fulfillmentNote as fulfillmentNote2 } from "@openreceive/core";
+function renderKnexFiles(options) {
+  const body = canonicalPaymentsDdlStatements(options).map((statement) => `  await knex.raw(\`${statement}\`);`).join("\n");
+  const migration = `/**
+ * Generated by \`npx openreceive scaffold payments\` \u2014 migration only.
+ * Executes the canonical OpenReceive DDL: \`${options.tableName}\` and the
+ * \`${options.metaTableName}\` reconcile gate, CHECK constraints and the
+ * schema_version seed row included. OpenReceive owns the payment-attempt
+ * repository at runtime (createHost in @openreceive/http), so no
+ * repository code is generated. Keep every column and constraint; timestamps
+ * are unix-seconds integer columns, on purpose.
+ *
+ * Dialect: ${options.dialect}
+ *
+${fulfillmentNote2(" * ", options.tableName)}
+ */
+
+/** @param {import("knex").Knex} knex */
+export async function up(knex) {
+${body}
+}
+
+/** @param {import("knex").Knex} knex */
+export async function down(knex) {
+  await knex.raw("DROP TABLE IF EXISTS ${options.metaTableName}");
+  await knex.raw("DROP TABLE IF EXISTS ${options.tableName}");
+}
+`;
+  return [
+    {
+      // .mjs: the migration uses ESM syntax, which a "type": "commonjs" host
+      // would reject in a .js file. Knex loads .mjs migrations natively.
+      path: "db/migrations/20260101000000_create_openreceive_tables.mjs",
+      contents: migration
+    },
+    { path: "OPENRECEIVE_PAYMENTS.md", contents: wiringGuideMarkdown(options) }
+  ];
+}
+
+// src/scaffold/orms/prisma.ts
+import {
+  fulfillmentNote as fulfillmentNote3,
+  paymentsHashCheckSql as paymentsHashCheckSql2,
+  paymentsIndexName as paymentsIndexName2,
+  paymentsSeedSql as paymentsSeedSql2,
+  paymentsStatusCheckSql as paymentsStatusCheckSql2
+} from "@openreceive/core";
+function renderPrismaFiles(options) {
+  const idField = isSqlite(options) ? "Int     @id @default(autoincrement())" : "BigInt  @id @default(autoincrement())";
+  const schema = `// Generated by \`npx openreceive scaffold payments\` \u2014 schema only.
+// OpenReceive owns the payment-attempt repository at runtime
+// (createHost in @openreceive/http); these two models exist so
+// \`prisma migrate\` creates the canonical tables. Keep every column.
+// Timestamps are unix-seconds integer columns (BigInt), on purpose.
+//
+// Prisma's schema language cannot express the canonical CHECK constraints or
+// the schema_version seed row: apply prisma/openreceive-constraints.sql as
+// described in OPENRECEIVE_PAYMENTS.md when creating the migration.
+//
+// Merge both models into your Prisma schema, then run:
+//   npx prisma migrate dev --create-only --name create_openreceive_tables
+//
+// Dialect: ${options.dialect}
+//
+${fulfillmentNote3("// ", options.tableName)}
+
+model OpenReceivePayment {
+  id           ${idField}
+  reference      String  @map("reference")
+  paymentHash  String  @unique @map("payment_hash")
+  status       String  @default("pending")
+  statusReason String? @map("status_reason")
+  paidAt       BigInt? @map("paid_at")
+  expiresAt    BigInt  @map("expires_at")
+  createdAt    BigInt  @map("created_at")
+  updatedAt    BigInt  @map("updated_at")
+  insertedAt   BigInt  @map("inserted_at")
+  checkoutData String  @map("checkout_data")
+  swapData     String? @map("swap_data")
+  clientIp     String? @map("client_ip")
+
+  @@index([reference, createdAt])
+  @@index([status, createdAt])
+  @@index([clientIp, insertedAt])
+  @@map("${options.tableName}")
+}
+
+// The durable reconcile gate every worker on this database shares (key/value/rev
+// compare-and-set). Same host database as ${options.tableName}.
+model OpenReceiveMeta {
+  key   String @id
+  value String
+  rev   BigInt @default(0)
+
+  @@map("${options.metaTableName}")
+}
+`;
+  return [
+    { path: "prisma/schema.openreceive.prisma", contents: schema },
+    { path: "prisma/openreceive-constraints.sql", contents: constraintsSql(options) },
+    { path: "OPENRECEIVE_PAYMENTS.md", contents: wiringGuideMarkdown(options) }
+  ];
+}
+function constraintsSql(options) {
+  const statusCheck = paymentsStatusCheckSql2();
+  const hashCheck = paymentsHashCheckSql2(options.dialect);
+  const seed = paymentsSeedSql2(options.dialect, options.metaTableName);
+  if (options.dialect === "postgres") {
+    return `-- Generated by \`npx openreceive scaffold payments\`.
+-- Prisma's schema language cannot express these; append this file to the draft
+-- migration created by \`npx prisma migrate dev --create-only\` before applying.
+ALTER TABLE "${options.tableName}" ADD CONSTRAINT "${paymentsIndexName2(options.tableName, "status_check")}" CHECK (${statusCheck});
+ALTER TABLE "${options.tableName}" ADD CONSTRAINT "${paymentsIndexName2(options.tableName, "hash_check")}" CHECK (${hashCheck});
+${seed};
+`;
+  }
+  return `-- Generated by \`npx openreceive scaffold payments\`.
+-- Prisma's schema language cannot express these, and sqlite cannot ALTER TABLE
+-- ... ADD CHECK. After \`npx prisma migrate dev --create-only\`, edit the draft
+-- migration: paste the two CHECK lines below into the
+-- CREATE TABLE "${options.tableName}" (...) column list, then append the INSERT.
+--
+--   CHECK (${statusCheck}),
+--   CHECK (${hashCheck})
+--
+${seed};
+`;
+}
+
+// src/scaffold/orms/sequelize.ts
+import { fulfillmentNote as fulfillmentNote4 } from "@openreceive/core";
+function renderSequelizeFiles(options) {
+  const body = canonicalPaymentsDdlStatements(options).map((statement) => `    await queryInterface.sequelize.query(\`${statement}\`);`).join("\n");
+  const migration = `"use strict";
+
+/**
+ * Generated by \`npx openreceive scaffold payments\` \u2014 migration only.
+ * Executes the canonical OpenReceive DDL: \`${options.tableName}\` and the
+ * \`${options.metaTableName}\` reconcile gate, CHECK constraints and the
+ * schema_version seed row included. OpenReceive owns the payment-attempt
+ * repository at runtime (createHost in @openreceive/http), so no
+ * model or repository code is generated. Keep every column and constraint;
+ * timestamps are unix-seconds integer columns, on purpose.
+ *
+ * Dialect: ${options.dialect}
+ *
+${fulfillmentNote4(" * ", options.tableName)}
+ */
+module.exports = {
+  async up(queryInterface) {
+${body}
+  },
+
+  async down(queryInterface) {
+    await queryInterface.sequelize.query("DROP TABLE IF EXISTS ${options.metaTableName}");
+    await queryInterface.sequelize.query("DROP TABLE IF EXISTS ${options.tableName}");
+  },
+};
+`;
+  return [
+    {
+      // .cjs: the migration uses module.exports, which a "type": "module" host
+      // would reject in a .js file. sequelize-cli loads .cjs migrations natively.
+      path: "migrations/20260101000000-create-openreceive-tables.cjs",
+      contents: migration
+    },
+    { path: "OPENRECEIVE_PAYMENTS.md", contents: wiringGuideMarkdown(options) }
+  ];
+}
+
+// src/scaffold/orms/typeorm.ts
+import { fulfillmentNote as fulfillmentNote5 } from "@openreceive/core";
+function renderTypeOrmFiles(options) {
+  const body = canonicalPaymentsDdlStatements(options).map((statement) => `    await queryRunner.query(\`${statement}\`);`).join("\n");
+  const migration = `// Generated by \`npx openreceive scaffold payments\` \u2014 migration only.
+// Executes the canonical OpenReceive DDL: \`${options.tableName}\` and the
+// \`${options.metaTableName}\` reconcile gate, both tables in this one migration.
+// OpenReceive owns the payment-attempt repository at runtime
+// (createHost in @openreceive/http), so there is no entity class to
+// register. Keep every column; timestamps are unix-seconds integer columns, on
+// purpose.
+//
+${fulfillmentNote5("// ", options.tableName)}
+import type { MigrationInterface, QueryRunner } from "typeorm";
+
+export class CreateOpenReceiveTables20260101000000 implements MigrationInterface {
+  name = "CreateOpenReceiveTables20260101000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+${body}
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query("DROP TABLE IF EXISTS ${options.metaTableName}");
+    await queryRunner.query("DROP TABLE IF EXISTS ${options.tableName}");
+  }
+}
+`;
+  return [
+    {
+      path: "src/migrations/20260101000000-create-openreceive-tables.ts",
+      contents: migration
+    },
+    { path: "OPENRECEIVE_PAYMENTS.md", contents: wiringGuideMarkdown(options) }
+  ];
+}
+
+// src/scaffold/render.ts
+function renderScaffoldPaymentsFiles(options) {
+  switch (options.orm) {
+    case "prisma":
+      return renderPrismaFiles(options);
+    case "drizzle":
+      return renderDrizzleFiles(options);
+    case "typeorm":
+      return renderTypeOrmFiles(options);
+    case "sequelize":
+      return renderSequelizeFiles(options);
+    case "knex":
+      return renderKnexFiles(options);
+  }
+}
+
+// src/scaffold/wizard.ts
+async function resolveScaffoldPaymentsOptions(input) {
+  const { partial } = input.parsed;
+  const wantsWizard = input.parsed.interactive || partial.orm === void 0 && input.canPrompt;
+  if (!wantsWizard) {
+    return finalizeScaffoldOptions(partial);
+  }
+  if (!input.canPrompt) {
+    throw new Error(
+      "Interactive scaffold requires a TTY. Pass --orm explicitly for non-interactive use."
+    );
+  }
+  const orm = partial.orm ?? await promptChoice(input.prompt, "ORM", OPENRECEIVE_ORMS, void 0);
+  const dialect = partial.dialect ?? await promptChoice(input.prompt, "SQL dialect", OPENRECEIVE_DIALECTS, "postgres");
+  const outDir = partial.outDir === "." ? await promptText(input.prompt, "Output directory", ".") : partial.outDir;
+  return {
+    orm,
+    dialect,
+    tableName: partial.tableName ?? "openreceive_payments",
+    metaTableName: partial.metaTableName ?? "openreceive_meta",
+    outDir,
+    force: partial.force
+  };
+}
+async function promptText(prompt, label, fallback) {
+  const answer = (await prompt(`${label} [${fallback}]: `)).trim();
+  return answer.length === 0 ? fallback : answer;
+}
+async function promptChoice(prompt, label, choices, fallback) {
+  const listed = choices.join(", ");
+  const suffix = fallback === void 0 ? "" : ` [${fallback}]`;
+  const answer = (await prompt(`${label} (${listed})${suffix}: `)).trim().toLowerCase();
+  const selected = answer.length === 0 ? fallback : answer;
+  if (selected !== void 0 && choices.includes(selected)) {
+    return selected;
+  }
+  throw new Error(`${label} must be one of: ${listed}.`);
+}
+
+// src/scaffold/write-files.ts
+import { mkdir, writeFile, access } from "fs/promises";
+import path from "path";
+async function writeScaffoldFiles(input) {
+  const root = path.resolve(input.cwd, input.outDir);
+  const planned = input.files.map((file) => ({
+    file,
+    absolute: path.join(root, file.path),
+    relative: path.relative(input.cwd, path.join(root, file.path))
+  }));
+  const existing = [];
+  for (const entry of planned) {
+    if (await exists(entry.absolute)) existing.push(entry.relative);
+  }
+  if (existing.length > 0 && !input.force) {
+    throw new Error(
+      `Refusing to overwrite existing files without --force:
+${existing.map((entry) => `  - ${entry}`).join("\n")}`
+    );
+  }
+  const written = [];
+  for (const entry of planned) {
+    await mkdir(path.dirname(entry.absolute), { recursive: true });
+    await writeFile(entry.absolute, entry.file.contents, "utf8");
+    written.push(entry.relative);
+  }
+  return { files: input.files, written };
+}
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/scaffold/index.ts
+var SCAFFOLD_PAYMENTS_HELP = `
+Usage: openreceive scaffold payments [options]
+
+Emits one schema/migration file for your ORM \u2014 openreceive_payments and the
+openreceive_meta reconcile gate together \u2014 plus an OPENRECEIVE_PAYMENTS.md
+wiring guide, nothing else. OpenReceive owns the
+payment-attempt repository logic (locking, settlement write-once,
+reconciliation) at runtime; the generated files never contain it.
+OpenReceive never opens a database connection or runs migrations.
+
+Options:
+  --orm <name>              prisma | drizzle | typeorm | sequelize | knex
+  --dialect <name>          postgres | sqlite (default: postgres)
+  --table-name <name>       Payment attempts table (default: openreceive_payments)
+  --meta-table-name <name>  Reconcile-gate table (default: openreceive_meta)
+  --out-dir <path>          Output root (default: .)
+  --force                   Overwrite existing generated files
+  -i, --interactive         Ask for missing options (default on TTY when --orm omitted)
+  -h, --help                Show this help
+
+Examples:
+  npx openreceive scaffold payments
+  npx openreceive scaffold payments --orm prisma
+  npx openreceive scaffold payments --orm knex --dialect sqlite
+  npx openreceive scaffold payments --orm drizzle --dialect sqlite --out-dir ./backend
+`.trim();
+async function runScaffoldPayments(input) {
+  const parsed = parseScaffoldPaymentsArgv(input.argv);
+  if (parsed.help) {
+    input.stdout.write(`${SCAFFOLD_PAYMENTS_HELP}
+`);
+    return 0;
+  }
+  const canPrompt = input.isTTY ?? Boolean(
+    input.stdin?.isTTY ?? defaultStdin.isTTY
+  );
+  const prompt = input.prompt ?? createReadlinePrompt(input);
+  const options = await resolveScaffoldPaymentsOptions({
+    parsed,
+    canPrompt,
+    prompt
+  });
+  finalizeScaffoldOptions(options);
+  printPlan(input.stdout, options);
+  const files = renderScaffoldPaymentsFiles(options);
+  const result = await writeScaffoldFiles({
+    cwd: input.cwd,
+    outDir: options.outDir,
+    force: options.force,
+    files
+  });
+  printSummary(input.stdout, options, result);
+  return 0;
+}
+function printPlan(stdout, options) {
+  stdout.write("OpenReceive scaffold payments\n");
+  stdout.write(`  orm:          ${options.orm}
+`);
+  stdout.write(`  dialect:      ${options.dialect}
+`);
+  stdout.write(`  tables:       ${options.tableName}, ${options.metaTableName}
+`);
+  stdout.write(`  out-dir:      ${options.outDir}
+`);
+  if (options.dialect === "sqlite") {
+    stdout.write(
+      "  note:         SQLite uses a single-writer transaction (no Postgres row locks)\n"
+    );
+  }
+  stdout.write("\nWriting files\u2026\n");
+}
+function printSummary(stdout, options, result) {
+  for (const file of result.written) {
+    stdout.write(`  wrote ${file}
+`);
+  }
+  stdout.write("\nDone.\n");
+  stdout.write("Next:\n");
+  stdout.write("  1. Read OPENRECEIVE_PAYMENTS.md\n");
+  stdout.write(`  2. Run the schema/migration through your normal ${options.orm} workflow
+`);
+  stdout.write(
+    "  3. Wire createHost({ db, amountFor, onPaid }) \u2014\n     OpenReceive owns the repository logic at runtime; settlement piggybacks\n     on mounted routes by default (no background process needed)\n"
+  );
+  stdout.write(
+    "  4. Make onPaid idempotent if anything OTHER than OpenReceive can also\n     fulfill an order \u2014 the generated files show the guarded UPDATE\n"
+  );
+}
+function createReadlinePrompt(input) {
+  return async (question) => {
+    const rl = createInterface({
+      input: input.stdin ?? defaultStdin,
+      output: defaultStdout,
+      terminal: input.isTTY ?? true
+    });
+    try {
+      return await rl.question(question);
+    } finally {
+      rl.close();
+    }
+  };
+}
+
+// src/cli.ts
+var HELP = `
+Usage: openreceive <command> [options]
+
+Commands:
+  doctor              Validate server configuration (Node, NWC_URI, swap providers).
+  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.
+`.trim();
+async function runCli(options) {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const [command = "help", ...args] = options.argv;
+  try {
+    if (["help", "--help", "-h"].includes(command)) {
+      stdout.write(`${HELP}
+`);
+      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 });
+    }
+    if (command === "scaffold") {
+      const [target = "help", ...scaffoldArgs] = args;
+      if (target === "help" || target === "--help" || target === "-h") {
+        stdout.write(`${SCAFFOLD_PAYMENTS_HELP}
+`);
+        return 0;
+      }
+      if (target !== "payments") {
+        throw new Error(`Unknown scaffold target: ${target}. Only "payments" is supported.`);
+      }
+      return await runScaffoldPayments({
+        argv: scaffoldArgs,
+        cwd,
+        stdout,
+        stderr,
+        stdin: options.stdin,
+        isTTY: options.isTTY,
+        prompt: options.prompt
+      });
+    }
+    stderr.write(`Unknown OpenReceive command: ${command}
+
+${HELP}
+`);
+    return 1;
+  } catch (error) {
+    stderr.write(`${safeErrorMessage(error)}
+`);
+    return 1;
+  }
+}
+function runDiagnostics(input) {
+  const nwc = input.env.NWC_URI?.trim();
+  let nwcError;
+  try {
+    if (nwc) parseNwcUri(nwc);
+  } catch (error) {
+    nwcError = error instanceof NwcUriParseError ? new Error(formatInvalidNwcMessage({ reason: error.description })) : error;
+  }
+  let lscConnections = 0;
+  let lscError;
+  try {
+    lscConnections = readLscConnectionsFromEnvironment(input.env).length;
+  } catch (error) {
+    lscError = error;
+  }
+  const lines = [
+    `OpenReceive ${input.command}`,
+    `node: ${process.version}`,
+    `cwd: ${input.cwd}`,
+    "storage: payment-attempt rows live in the host database (no separate store)",
+    `NWC_URI: ${nwcError === void 0 ? nwc ? "present-redacted" : "missing" : safeErrorMessage(nwcError)}`,
+    `LSC_URI connections: ${lscError === void 0 ? lscConnections : safeErrorMessage(lscError)}`
+  ];
+  input.stdout.write(`${lines.join("\n")}
+`);
+  if (input.command === "debug-report") return 0;
+  return nwcError !== void 0 || !nwc || lscError !== void 0 ? 1 : 0;
+}
+function safeErrorMessage(error) {
+  if (error instanceof Error) return redactSecrets(error.message);
+  if (typeof error === "string") return redactSecrets(error);
+  return "OpenReceive command failed.";
+}
+export {
+  finalizeScaffoldOptions,
+  parseScaffoldPaymentsArgv,
+  renderScaffoldPaymentsFiles,
+  runCli,
+  runScaffoldPayments
+};