@openreceive/node 0.3.2 → 0.3.3

package/dist/{chunk-SDCOJGCF.js → chunk-ZYS6QECW.js}

@@ -1,3 +1,946 @@
+// src/nwc/errors.ts
+import {
+  isErrorCode,
+  isRetryableErrorCode,
+  OpenReceiveError
+} from "@openreceive/core";
+var WalletPreflightError = class extends Error {
+  code;
+  summary;
+  constructor(code, message, summary) {
+    super(message);
+    this.name = "WalletPreflightError";
+    this.code = code;
+    this.summary = summary;
+  }
+};
+var ReceiveCheckoutValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReceiveCheckoutValidationError";
+  }
+};
+var NWC_ERROR_CODE_ALIASES = {
+  ABORT_ERROR: "TIMEOUT",
+  BAD_REQUEST: "INVALID_REQUEST",
+  CONNECTION_ERROR: "WALLET_UNAVAILABLE",
+  EXPIRED: "INVOICE_EXPIRED",
+  FETCH_ERROR: "WALLET_UNAVAILABLE",
+  FORBIDDEN: "RESTRICTED",
+  INVOICE_NOT_FOUND: "NOT_FOUND",
+  INVALID_PARAMETER: "INVALID_REQUEST",
+  INVALID_PARAMETERS: "INVALID_REQUEST",
+  INVALID_PARAMS: "INVALID_REQUEST",
+  METHOD_NOT_FOUND: "UNSUPPORTED_METHOD",
+  NETWORK_ERROR: "WALLET_UNAVAILABLE",
+  NIP47_NETWORK_ERROR: "WALLET_UNAVAILABLE",
+  NOSTR_NETWORK_ERROR: "WALLET_UNAVAILABLE",
+  NOT_AUTHORIZED: "UNAUTHORIZED",
+  NOT_SUPPORTED: "UNSUPPORTED_METHOD",
+  NOTFOUND: "NOT_FOUND",
+  PERMISSION_DENIED: "RESTRICTED",
+  RELAY_CONNECTION_ERROR: "WALLET_UNAVAILABLE",
+  REQUEST_TIMEOUT: "TIMEOUT",
+  SERVICE_UNAVAILABLE: "WALLET_UNAVAILABLE",
+  TIMED_OUT: "TIMEOUT",
+  TIMEOUT_ERROR: "TIMEOUT",
+  UNKNOWN_METHOD: "UNSUPPORTED_METHOD",
+  UNSUPPORTED: "UNSUPPORTED_METHOD",
+  UNSUPPORTED_ENCRYPTION_MODE: "UNSUPPORTED_ENCRYPTION",
+  WALLET_OFFLINE: "WALLET_UNAVAILABLE",
+  WALLET_UNREACHABLE: "WALLET_UNAVAILABLE"
+};
+var OPENRECEIVE_ERROR_MESSAGES = {
+  NOT_IMPLEMENTED: "NWC wallet service does not implement this method.",
+  RESTRICTED: "NWC wallet service restricted this request.",
+  UNAUTHORIZED: "NWC wallet service rejected authorization.",
+  FORBIDDEN: "The host application did not authorize this request.",
+  RATE_LIMITED: "NWC wallet service rate limited this request.",
+  QUOTA_EXCEEDED: "NWC wallet service quota was exceeded.",
+  INTERNAL: "NWC wallet service returned an internal error.",
+  UNSUPPORTED_ENCRYPTION: "NWC wallet service does not support the required encryption mode.",
+  OTHER: "NWC wallet service returned an unknown error.",
+  NOT_FOUND: "NWC wallet service could not find the requested resource.",
+  TIMEOUT: "NWC wallet service request timed out.",
+  INVALID_REQUEST: "OpenReceive sent an invalid NWC wallet request.",
+  WALLET_UNAVAILABLE: "NWC wallet service is unavailable.",
+  INVOICE_EXPIRED: "NWC wallet reported that the invoice is expired.",
+  UNSUPPORTED_METHOD: "NWC wallet service does not support the requested method.",
+  CONFLICT: "NWC wallet service reported a conflicting request."
+};
+function normalizeNwcWalletError(error) {
+  if (error instanceof OpenReceiveError) return error;
+  const records = collectErrorRecords(error);
+  const code = knownErrorCode(error) ?? errorCodeFromRecords(records) ?? (typeof error === "string" ? normalizeNwcErrorCode(error) : void 0) ?? "OTHER";
+  const message = errorMessageFromRecords(records, error, code);
+  const retryable = firstBooleanField(records, ["retryable"]) ?? isRetryableErrorCode(code);
+  const requestId = firstStringField(records, ["request_id", "requestId"]);
+  const details = firstRecordField(records, ["details"]);
+  const body = {
+    code,
+    message,
+    retryable,
+    ...requestId === void 0 ? {} : { request_id: requestId },
+    ...details === void 0 ? {} : { details }
+  };
+  return new OpenReceiveError(body, { cause: error });
+}
+function knownErrorCode(error) {
+  if (error instanceof ReceiveCheckoutValidationError) {
+    return "INVALID_REQUEST";
+  }
+  if (error instanceof WalletPreflightError) {
+    if (error.code === "missing_required_method") return "UNSUPPORTED_METHOD";
+    if (error.code === "spend_capability_advertised") return "RESTRICTED";
+    if (error.code === "unsupported_encryption") return "UNSUPPORTED_ENCRYPTION";
+    return "WALLET_UNAVAILABLE";
+  }
+  return void 0;
+}
+function errorCodeFromRecords(records) {
+  for (const record of records) {
+    const directCode = normalizeNwcErrorCode(record.code) ?? normalizeNwcErrorCode(record.error_code) ?? normalizeNwcErrorCode(record.errorCode) ?? normalizeNwcErrorCode(record.type);
+    if (directCode !== void 0 && directCode !== "OTHER") return directCode;
+    const nameCode = normalizeNwcErrorCode(record.name);
+    if (nameCode !== void 0 && nameCode !== "OTHER") return nameCode;
+    if (directCode !== void 0) return directCode;
+  }
+  return void 0;
+}
+function normalizeNwcErrorCode(value) {
+  if (typeof value !== "string" || value.trim().length === 0) return void 0;
+  const normalized = normalizeNwcErrorCodeText(value);
+  return NWC_ERROR_CODE_ALIASES[normalized] ?? (isErrorCode(normalized) ? normalized : void 0);
+}
+function normalizeNwcErrorCodeText(value) {
+  return value.trim().replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
+}
+function errorMessageFromRecords(records, error, code) {
+  const message = firstStringField(records, ["message", "description", "reason"]);
+  if (message !== void 0 && normalizeNwcErrorCode(message) !== code) {
+    return message;
+  }
+  if (typeof error === "string" && normalizeNwcErrorCode(error) === void 0) {
+    const trimmed = error.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  return OPENRECEIVE_ERROR_MESSAGES[code];
+}
+function collectErrorRecords(value) {
+  const records = [];
+  collectErrorRecordsInto(value, records, /* @__PURE__ */ new Set());
+  return records;
+}
+function collectErrorRecordsInto(value, records, seen) {
+  if (typeof value !== "object" || value === null || seen.has(value)) return;
+  seen.add(value);
+  const record = value;
+  records.push(record);
+  for (const key of ["error", "result", "cause", "data"]) {
+    collectErrorRecordsInto(record[key], records, seen);
+  }
+}
+function firstStringField(records, fields) {
+  for (const record of records) {
+    for (const field of fields) {
+      const value = record[field];
+      if (typeof value === "string" && value.trim().length > 0) {
+        return value;
+      }
+    }
+  }
+  return void 0;
+}
+function firstBooleanField(records, fields) {
+  for (const record of records) {
+    for (const field of fields) {
+      const value = record[field];
+      if (typeof value === "boolean") return value;
+    }
+  }
+  return void 0;
+}
+function firstRecordField(records, fields) {
+  for (const record of records) {
+    for (const field of fields) {
+      const value = record[field];
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+      }
+    }
+  }
+  return void 0;
+}
+
+// src/alby-nwc.ts
+import {
+  compact,
+  formatSpendCapabilityRefusedMessage,
+  formatSpendCapabilityWarningMessage,
+  OpenReceiveError as OpenReceiveError2,
+  parseNwcUri
+} from "@openreceive/core";
+
+// src/nwc/normalize.ts
+import {
+  OPENRECEIVE_MAX_AMOUNT_MSATS,
+  OPENRECEIVE_MIN_AMOUNT_MSATS,
+  OPENRECEIVE_NWC_METADATA_MAX_BYTES,
+  nonEmptyString,
+  recordOrEmpty
+} from "@openreceive/core";
+
+// src/hex.ts
+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"
+];
+function summarizeWalletCapabilities(connection, rawInfo, rawServiceInfo) {
+  const unwrappedInfo = unwrapNwcResult(rawInfo);
+  const info = recordOrEmpty(unwrappedInfo);
+  const serviceInfo = rawServiceInfo === void 0 ? void 0 : recordOrEmpty(unwrapNwcResult(rawServiceInfo));
+  const methods = normalizeStringList(
+    info.methods ?? info.capabilities ?? info.supported_methods ?? info.supportedMethods ?? (typeof unwrappedInfo === "string" ? unwrappedInfo : void 0)
+  ).map(normalizeNwcMethodName);
+  const encryption = chooseEncryptionMode(
+    normalizeStringList(
+      serviceInfo?.encryption ?? serviceInfo?.encryptions ?? info.encryption ?? info.encryptions
+    )
+  );
+  const spendMethods = spendMethodsIn(methods);
+  const missingMethods = REQUIRED_RECEIVE_METHODS.filter((method) => !methods.includes(method));
+  const warnings = spendMethods.map(
+    (method) => `Wallet advertises spend method '${method}'; OpenReceive checkout will not expose it.`
+  );
+  return {
+    walletPubkey: connection.walletPubkey,
+    relays: [...connection.relays],
+    methods,
+    encryption,
+    spendCapabilityAdvertised: spendMethods.length > 0,
+    receiveCheckoutReady: missingMethods.length === 0,
+    warnings
+  };
+}
+function spendMethodsIn(methods) {
+  return methods.filter(
+    (method) => SPEND_METHODS.includes(method)
+  );
+}
+function toNip47MakeInvoiceParams(request) {
+  const params = {
+    amount: toSafeNumber(request.amount_msats, "amount_msats")
+  };
+  if (request.description !== void 0) params.description = request.description;
+  if (request.description_hash !== void 0) {
+    params.description_hash = request.description_hash;
+  }
+  if (request.expiry !== void 0) params.expiry = request.expiry;
+  if (request.metadata !== void 0) params.metadata = request.metadata;
+  return params;
+}
+function toNip47ListTransactionsParams(request) {
+  const params = {};
+  if (request.from !== void 0) params.from = request.from;
+  if (request.until !== void 0) params.until = request.until;
+  if (request.limit !== void 0) params.limit = request.limit;
+  if (request.offset !== void 0) params.offset = request.offset;
+  if (request.unpaid !== void 0) params.unpaid = request.unpaid;
+  if (request.type !== void 0) params.type = request.type;
+  return params;
+}
+function validateMakeInvoiceRequest(request) {
+  if (request.amount_msats < OPENRECEIVE_MIN_AMOUNT_MSATS) {
+    throw new ReceiveCheckoutValidationError("amount_msats must be at least 1000");
+  }
+  if (request.amount_msats > OPENRECEIVE_MAX_AMOUNT_MSATS) {
+    throw new ReceiveCheckoutValidationError("amount_msats exceeds JSON safe integer boundary");
+  }
+  if (request.description !== void 0 && request.description_hash !== void 0) {
+    throw new ReceiveCheckoutValidationError(
+      "At most one of description or description_hash may be present"
+    );
+  }
+  if (request.description_hash !== void 0 && !HEX_64.test(request.description_hash)) {
+    throw new ReceiveCheckoutValidationError("description_hash must be 64 hex characters");
+  }
+  if (request.metadata !== void 0) {
+    const metadataBytes = byteLength(JSON.stringify(request.metadata));
+    if (metadataBytes > OPENRECEIVE_NWC_METADATA_MAX_BYTES) {
+      throw new ReceiveCheckoutValidationError(
+        `metadata must serialize below ${OPENRECEIVE_NWC_METADATA_MAX_BYTES} bytes`
+      );
+    }
+  }
+}
+function validateListTransactionsRequest(request) {
+  validateOptionalNonNegativeInteger(request.from, "from");
+  validateOptionalNonNegativeInteger(request.until, "until");
+  validateOptionalNonNegativeInteger(request.offset, "offset");
+  if (request.limit !== void 0 && (!Number.isSafeInteger(request.limit) || request.limit <= 0)) {
+    throw new ReceiveCheckoutValidationError("limit must be a positive safe integer");
+  }
+  if (request.from !== void 0 && request.until !== void 0 && request.from > request.until) {
+    throw new ReceiveCheckoutValidationError("from must be less than or equal to until");
+  }
+  if (request.type !== void 0 && request.type !== "incoming" && request.type !== "outgoing") {
+    throw new ReceiveCheckoutValidationError("type must be incoming or outgoing");
+  }
+}
+function validateOptionalNonNegativeInteger(value, field) {
+  if (value === void 0) return;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new ReceiveCheckoutValidationError(`${field} must be a non-negative safe integer`);
+  }
+}
+function normalizeMakeInvoiceResult(rawResult) {
+  const result = recordOrEmpty(unwrapNwcResult(rawResult));
+  const invoice = requiredString(result.invoice, "invoice");
+  const paymentHash = requiredString(result.payment_hash ?? result.paymentHash, "payment_hash");
+  if (!HEX_64.test(paymentHash)) {
+    throw new TypeError("payment_hash must be 64 hex characters");
+  }
+  const amountMsats = toBigInt(result.amount_msats ?? result.amount, "amount_msats");
+  const createdAt = parseOptionalInteger(result.created_at ?? result.createdAt, "created_at");
+  const expiresAt = parseOptionalInteger(result.expires_at ?? result.expiresAt, "expires_at");
+  return {
+    invoice,
+    payment_hash: paymentHash,
+    amount_msats: amountMsats,
+    ...createdAt === void 0 ? {} : { created_at: createdAt },
+    ...expiresAt === void 0 ? {} : { expires_at: expiresAt }
+  };
+}
+function normalizeListTransactionsResult(rawResult) {
+  const unwrapped = unwrapNwcResult(rawResult);
+  const result = recordOrEmpty(unwrapped);
+  let rawTransactions;
+  if (Array.isArray(result.transactions)) {
+    rawTransactions = result.transactions;
+  } else if (Array.isArray(unwrapped)) {
+    rawTransactions = unwrapped;
+  } else if ((unwrapped === void 0 || unwrapped === null || typeof unwrapped === "object") && Object.keys(result).length === 0) {
+    rawTransactions = [];
+  } else {
+    throw new TypeError("list_transactions returned an unrecognized result shape");
+  }
+  const transactions = [];
+  let skippedRows = 0;
+  for (const rawTransaction of rawTransactions) {
+    try {
+      transactions.push(normalizeNwcTransaction(rawTransaction));
+    } catch {
+      skippedRows += 1;
+    }
+  }
+  if (transactions.length === 0 && skippedRows > 0) {
+    throw new TypeError("list_transactions returned no usable rows");
+  }
+  return { transactions, skippedRows };
+}
+function normalizeNwcTransaction(rawTransaction) {
+  const result = recordOrEmpty(rawTransaction);
+  const normalized = {};
+  const type = normalizeTransactionType(result.type);
+  if (type !== void 0) normalized.type = type;
+  const invoice = nonEmptyString(result.invoice);
+  if (invoice !== void 0) normalized.invoice = invoice;
+  const paymentHash = nonEmptyString(result.payment_hash ?? result.paymentHash);
+  if (paymentHash !== void 0) {
+    if (!/^[0-9a-fA-F]{64}$/.test(paymentHash)) {
+      throw new TypeError("payment_hash must be 64 hexadecimal characters");
+    }
+    normalized.payment_hash = paymentHash;
+  }
+  if (result.amount_msats !== void 0 || result.amount !== void 0) {
+    normalized.amount_msats = toBigInt(result.amount_msats ?? result.amount, "amount_msats");
+  }
+  const transactionState = normalizeTransactionState(
+    result.transaction_state ?? result.transactionState ?? result.state
+  ) ?? (result.settled === true || result.paid === true ? "settled" : void 0);
+  if (transactionState !== void 0) {
+    normalized.transaction_state = transactionState;
+  }
+  const createdAt = optionalUnixSeconds(result.created_at ?? result.createdAt, "created_at");
+  if (createdAt !== void 0) normalized.created_at = createdAt;
+  const expiresAt = optionalUnixSeconds(result.expires_at ?? result.expiresAt, "expires_at");
+  if (expiresAt !== void 0) normalized.expires_at = expiresAt;
+  const settledAt = optionalUnixSeconds(result.settled_at ?? result.settledAt, "settled_at");
+  if (settledAt !== void 0) normalized.settled_at = settledAt;
+  const preimage = nonEmptyString(result.preimage);
+  if (preimage !== void 0) normalized.preimage = preimage;
+  const description = nonEmptyString(result.description);
+  if (description !== void 0) normalized.description = description;
+  const descriptionHash = nonEmptyString(result.description_hash ?? result.descriptionHash);
+  if (descriptionHash !== void 0) normalized.description_hash = descriptionHash;
+  if (result.fees_paid !== void 0 || result.feesPaid !== void 0) {
+    normalized.fees_paid_msats = toBigInt(result.fees_paid ?? result.feesPaid, "fees_paid");
+  }
+  return normalized;
+}
+function normalizeNwcNotification(rawNotification) {
+  const record = recordOrEmpty(rawNotification);
+  const type = typeof record.notification_type === "string" ? record.notification_type : typeof record.notificationType === "string" ? record.notificationType : typeof record.type === "string" ? record.type : "unknown";
+  const payload = recordOrEmpty(record.notification);
+  let transaction;
+  if (Object.keys(payload).length > 0) {
+    try {
+      transaction = normalizeNwcTransaction(payload);
+    } catch {
+    }
+  }
+  const rawHash = payload.payment_hash ?? payload.paymentHash ?? record.payment_hash ?? record.paymentHash;
+  const paymentHash = typeof rawHash === "string" && rawHash.length > 0 ? rawHash : transaction?.payment_hash;
+  return {
+    type,
+    ...paymentHash === void 0 ? {} : { payment_hash: paymentHash },
+    ...transaction === void 0 ? {} : { transaction }
+  };
+}
+function chooseEncryptionMode(encryptionModes) {
+  const normalized = encryptionModes.map((mode) => mode.toLowerCase().replace(/[- ]/g, "_"));
+  if (normalized.includes("nip44_v2") || normalized.includes("nip44") || normalized.includes("nip_44")) {
+    return "nip44_v2";
+  }
+  if (normalized.length === 0 || normalized.includes("nip04") || normalized.includes("nip_04")) {
+    return "nip04";
+  }
+  return void 0;
+}
+function normalizeStringList(value) {
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(/[,\s]+/).map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+}
+function normalizeNwcMethodName(value) {
+  return value.trim().replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+}
+function normalizeTransactionState(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.toLowerCase();
+  if (normalized === "pending" || normalized === "settled" || normalized === "expired" || normalized === "failed" || normalized === "accepted") {
+    return normalized;
+  }
+  return void 0;
+}
+function normalizeTransactionType(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.toLowerCase();
+  if (normalized === "incoming" || normalized === "outgoing") return normalized;
+  return void 0;
+}
+function parseOptionalInteger(value, fieldName) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`${fieldName} must be a non-negative safe integer`);
+  }
+  return value;
+}
+function optionalUnixSeconds(value, fieldName) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new TypeError(`${fieldName} must be a non-negative number of Unix seconds`);
+  }
+  return Math.floor(value);
+}
+function requiredString(value, fieldName) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${fieldName} must be a non-empty string`);
+  }
+  return value;
+}
+function toBigInt(value, fieldName) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isSafeInteger(value)) {
+    return BigInt(value);
+  }
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) {
+    return BigInt(value);
+  }
+  throw new TypeError(`${fieldName} must be an integer`);
+}
+function toSafeNumber(value, fieldName) {
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new ReceiveCheckoutValidationError(`${fieldName} exceeds JSON safe integer boundary`);
+  }
+  return Number(value);
+}
+function byteLength(value) {
+  return new TextEncoder().encode(value).length;
+}
+function unwrapNwcResult(value) {
+  const record = recordOrEmpty(value);
+  return record.result ?? value;
+}
+
+// src/nwc/transport.ts
+import { createRequire } from "module";
+import { pathToFileURL } from "url";
+import { recordOrEmpty as recordOrEmpty2 } from "@openreceive/core";
+var require2 = createRequire(import.meta.url);
+async function callRequiredMethod(client, names, request) {
+  for (const name of names) {
+    const method = client[name];
+    if (typeof method === "function") {
+      return await method.call(
+        client,
+        request
+      );
+    }
+  }
+  throw new WalletPreflightError(
+    "wallet_unavailable",
+    `NWC client does not expose ${names.join(" or ")}.`
+  );
+}
+async function createDefaultAlbyNwcClient(connectionString) {
+  ensureNodeWebSocket();
+  const dynamicImport = new Function("specifier", "return import(specifier)");
+  const namespace = recordOrEmpty2(
+    await dynamicImport(pathToFileURL(require2.resolve("@getalby/sdk/nwc")).href)
+  );
+  const Constructor = namespace.NWCClient;
+  if (typeof Constructor !== "function") {
+    throw new WalletPreflightError(
+      "wallet_unavailable",
+      "@getalby/sdk/nwc did not expose NWCClient."
+    );
+  }
+  const NWCClientConstructor = Constructor;
+  return new NWCClientConstructor({
+    nostrWalletConnectUrl: connectionString
+  });
+}
+function ensureNodeWebSocket() {
+  if (globalThis.WebSocket !== void 0) return;
+  throw new WalletPreflightError(
+    "wallet_unavailable",
+    "OpenReceive requires Node 22 or newer with the built-in WebSocket API."
+  );
+}
+async function closeNwcNotificationSubscription(subscription) {
+  if (typeof subscription !== "function") {
+    throw new TypeError("NWC subscribeNotifications must resolve to an unsubscribe function.");
+  }
+  await subscription();
+}
+function delay(milliseconds) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+  });
+}
+
+// src/alby-nwc.ts
+var AlbyNwcReceiveClient = class {
+  /**
+   * Safe, loggable view of the connection (wallet pubkey, relays, lud16, and
+   * the secret-redacted URI). The parsed connection with the client secret is
+   * deliberately private: `console.log(client)` or host error serialization
+   * must never leak the secret.
+   */
+  connection;
+  #connection;
+  #connectionString;
+  #client;
+  #clientPromise;
+  #clientFactory;
+  #preflightSummary;
+  #preflightPromise;
+  #requirePreflight;
+  #logger;
+  #allowSpendCapableWallet;
+  #spendCapabilityWarningDelayMs;
+  #spendCapabilityWarning;
+  #closed = false;
+  constructor(options) {
+    this.#connectionString = options.connectionString;
+    this.#connection = parseNwcUri(options.connectionString);
+    this.connection = {
+      walletPubkey: this.#connection.walletPubkey,
+      relays: [...this.#connection.relays],
+      ...this.#connection.lud16 === void 0 ? {} : { lud16: this.#connection.lud16 },
+      redacted: this.#connection.redacted
+    };
+    this.#client = options.client;
+    this.#clientFactory = options.clientFactory;
+    this.#requirePreflight = options.requirePreflight ?? true;
+    this.#logger = options.logger;
+    this.#allowSpendCapableWallet = options.allowSpendCapableWallet ?? false;
+    this.#spendCapabilityWarningDelayMs = options.spendCapabilityWarningDelayMs ?? 0;
+    this.#spendCapabilityWarning = options.spendCapabilityWarning ?? ((message) => {
+      if (this.#logger === void 0) console.error(message);
+      else this.#log("error", "nwc.spend_capability_warning", message);
+    });
+  }
+  #log(level, event, message, fields = {}) {
+    if (this.#logger === void 0) return;
+    try {
+      this.#logger({
+        level,
+        event,
+        message,
+        wallet_pubkey: this.connection.walletPubkey,
+        ...fields
+      });
+    } catch {
+    }
+  }
+  async preflight() {
+    const client = await this.getClient();
+    const hasGetInfo = typeof client.getInfo === "function" || typeof client.get_info === "function";
+    const hasInfoEvent = typeof client.getWalletServiceInfo === "function";
+    const rawInfo = hasGetInfo || !hasInfoEvent ? await this.#fetchWalletInfo(
+      "get_info",
+      () => callRequiredMethod(client, ["getInfo", "get_info"], {})
+    ) : void 0;
+    const rawServiceInfo = hasInfoEvent ? await this.#fetchWalletInfo(
+      "info_event",
+      () => client.getWalletServiceInfo()
+    ) : void 0;
+    if (rawInfo === void 0) {
+      this.#log(
+        "warn",
+        "nwc.info_event.methods_fallback",
+        "NWC client exposes no get_info; proving receive-only from the service-wide info event (kind 13194) rather than this connection's own method list."
+      );
+    }
+    const summary = summarizeWalletCapabilities(
+      this.#connection,
+      rawInfo ?? rawServiceInfo,
+      rawServiceInfo
+    );
+    this.#log("debug", "nwc.preflight.summarized", "NWC wallet capabilities summarized.", {
+      methods_source: rawInfo === void 0 ? "info_event" : "get_info",
+      methods: summary.methods,
+      encryption: summary.encryption,
+      receive_checkout_ready: summary.receiveCheckoutReady,
+      spend_capability_advertised: summary.spendCapabilityAdvertised
+    });
+    if (!summary.receiveCheckoutReady) {
+      throw new WalletPreflightError(
+        "missing_required_method",
+        "NWC wallet must advertise make_invoice and list_transactions for receive checkout.",
+        summary
+      );
+    }
+    if (summary.encryption !== "nip04" && summary.encryption !== "nip44_v2") {
+      throw new WalletPreflightError(
+        "unsupported_encryption",
+        "NWC wallet must support NIP-04 or NIP-44 v2 encryption.",
+        summary
+      );
+    }
+    if (summary.spendCapabilityAdvertised) {
+      const spendMethods = spendMethodsIn(summary.methods);
+      if (!this.#allowSpendCapableWallet) {
+        this.#log(
+          "error",
+          "nwc.spend_capability_advertised",
+          "NWC connection advertises send-payment methods; refusing to boot without an explicit override.",
+          { methods: spendMethods }
+        );
+        throw new WalletPreflightError(
+          "spend_capability_advertised",
+          formatSpendCapabilityRefusedMessage({ spendMethods }),
+          summary
+        );
+      }
+      const warning = formatSpendCapabilityWarningMessage({
+        spendMethods
+      });
+      this.#log(
+        "error",
+        "nwc.spend_capability_advertised",
+        "NWC connection advertises send-payment methods; continuing because the spend-capable override is set.",
+        { methods: spendMethods }
+      );
+      try {
+        this.#spendCapabilityWarning(warning);
+      } catch {
+      }
+      if (this.#spendCapabilityWarningDelayMs > 0) {
+        await delay(this.#spendCapabilityWarningDelayMs);
+      }
+    }
+    this.#preflightSummary = summary;
+    return summary;
+  }
+  async makeInvoice(request) {
+    await this.ensurePreflight();
+    validateMakeInvoiceRequest(request);
+    this.#log(
+      "debug",
+      "nwc.make_invoice.requested",
+      "Calling NWC wallet make_invoice.",
+      compact({
+        method: "make_invoice",
+        // String form: msats above 2^53 would silently round through Number().
+        amount_msats: request.amount_msats.toString(),
+        expiry: request.expiry,
+        has_description: request.description !== void 0,
+        has_description_hash: request.description_hash !== void 0
+      })
+    );
+    const startedAt = Date.now();
+    let rawResult;
+    try {
+      rawResult = await callRequiredMethod(
+        await this.getClient(),
+        ["makeInvoice", "make_invoice"],
+        toNip47MakeInvoiceParams(request)
+      );
+    } catch (error) {
+      const normalized = normalizeNwcWalletError(error);
+      this.#log("error", "nwc.make_invoice.failed", "NWC wallet make_invoice failed.", {
+        method: "make_invoice",
+        duration_ms: Date.now() - startedAt,
+        error_code: normalized.code,
+        error_message: normalized.message
+      });
+      throw normalized;
+    }
+    let result;
+    try {
+      result = normalizeMakeInvoiceResult(rawResult);
+    } catch (error) {
+      const normalized = normalizeNwcWalletError(error);
+      this.#log("error", "nwc.make_invoice.failed", "NWC wallet make_invoice failed.", {
+        method: "make_invoice",
+        duration_ms: Date.now() - startedAt,
+        error_code: normalized.code,
+        error_message: normalized.message
+      });
+      throw normalized;
+    }
+    this.#log("debug", "nwc.make_invoice.completed", "NWC wallet make_invoice completed.", {
+      method: "make_invoice",
+      duration_ms: Date.now() - startedAt,
+      payment_hash: result.payment_hash,
+      amount_msats: result.amount_msats.toString()
+    });
+    return result;
+  }
+  async listTransactions(request) {
+    await this.ensurePreflight();
+    validateListTransactionsRequest(request);
+    this.#log(
+      "debug",
+      "nwc.list_transactions.requested",
+      "Calling NWC wallet list_transactions.",
+      compact({
+        method: "list_transactions",
+        from: request.from,
+        until: request.until,
+        limit: request.limit,
+        offset: request.offset,
+        unpaid: request.unpaid,
+        type: request.type
+      })
+    );
+    const startedAt = Date.now();
+    let rawResult;
+    try {
+      rawResult = await callRequiredMethod(
+        await this.getClient(),
+        ["listTransactions", "list_transactions"],
+        toNip47ListTransactionsParams(request)
+      );
+    } catch (error) {
+      const normalized = normalizeNwcWalletError(error);
+      this.#log("error", "nwc.list_transactions.failed", "NWC wallet list_transactions failed.", {
+        method: "list_transactions",
+        duration_ms: Date.now() - startedAt,
+        error_code: normalized.code,
+        error_message: normalized.message
+      });
+      throw normalized;
+    }
+    let result;
+    try {
+      result = normalizeListTransactionsResult(rawResult);
+    } catch (error) {
+      const normalized = normalizeNwcWalletError(error);
+      this.#log("error", "nwc.list_transactions.failed", "NWC wallet list_transactions failed.", {
+        method: "list_transactions",
+        duration_ms: Date.now() - startedAt,
+        error_code: normalized.code,
+        error_message: normalized.message
+      });
+      throw normalized;
+    }
+    if (result.skippedRows > 0) {
+      this.#log(
+        "warn",
+        "nwc.list_transactions.rows_skipped",
+        "Skipped wallet transaction rows that could not be normalized.",
+        {
+          method: "list_transactions",
+          skipped_count: result.skippedRows
+        }
+      );
+    }
+    this.#log(
+      "debug",
+      "nwc.list_transactions.completed",
+      "NWC wallet list_transactions completed.",
+      {
+        method: "list_transactions",
+        duration_ms: Date.now() - startedAt,
+        transaction_count: result.transactions.length
+      }
+    );
+    return {
+      transactions: result.transactions,
+      ...result.skippedRows === 0 ? {} : { skippedRows: result.skippedRows }
+    };
+  }
+  /**
+   * Opt-in NWC-02 notification subscription, limited to `payment_received`.
+   * Notifications are authenticated wallet data: the handler receives the
+   * payload normalized like a `list_transactions` row so a payload satisfying
+   * the settlement rule can settle its pending attempt directly, while
+   * anything less only wakes reconciliation. Direct settlement assumes the
+   * client binds notification decryption to the connection's wallet pubkey
+   * (the bundled @getalby/sdk does). Resolves to an unsubscribe function.
+   * Throws an OpenReceiveError with code `UNSUPPORTED_METHOD` when the
+   * underlying wallet client does not support NWC notifications.
+   */
+  async subscribeNotifications(handler) {
+    const client = await this.getClient();
+    const subscribe = client.subscribeNotifications;
+    if (typeof subscribe !== "function") {
+      throw new OpenReceiveError2({
+        code: "UNSUPPORTED_METHOD",
+        message: "NWC wallet client does not support NWC notifications (subscribeNotifications). Keep polling reconciliation.",
+        retryable: false
+      });
+    }
+    this.#log(
+      "debug",
+      "nwc.notifications.subscribe.requested",
+      "Subscribing to NWC-02 payment_received notifications.",
+      { notification_types: ["payment_received"] }
+    );
+    let subscription;
+    try {
+      subscription = await subscribe.call(
+        client,
+        (rawNotification) => {
+          const notification = normalizeNwcNotification(rawNotification);
+          if (notification.type !== "payment_received") return;
+          this.#log(
+            "debug",
+            "nwc.notifications.received",
+            "NWC payment_received notification received.",
+            compact({
+              notification_type: notification.type,
+              payment_hash: notification.payment_hash
+            })
+          );
+          try {
+            handler(notification);
+          } catch {
+          }
+        },
+        ["payment_received"]
+      );
+    } catch (error) {
+      const normalized = normalizeNwcWalletError(error);
+      this.#log(
+        "error",
+        "nwc.notifications.subscribe.failed",
+        "NWC notification subscription failed.",
+        { error_code: normalized.code, error_message: normalized.message }
+      );
+      throw normalized;
+    }
+    this.#log(
+      "info",
+      "nwc.notifications.subscribe.completed",
+      "Subscribed to NWC-02 payment_received notifications; polling reconciliation remains the safety net."
+    );
+    return async () => {
+      await closeNwcNotificationSubscription(subscription);
+      this.#log(
+        "info",
+        "nwc.notifications.unsubscribed",
+        "Unsubscribed from NWC-02 wallet notifications."
+      );
+    };
+  }
+  async #fetchWalletInfo(source, call) {
+    const method = source === "get_info" ? "get_info" : "getWalletServiceInfo";
+    const label = source === "get_info" ? "get_info" : "info event (kind 13194)";
+    this.#log("debug", `nwc.${source}.requested`, `Fetching NWC wallet ${label}.`, { method });
+    const startedAt = Date.now();
+    try {
+      const raw = await call();
+      this.#log("debug", `nwc.${source}.completed`, `NWC wallet ${label} loaded.`, {
+        method,
+        duration_ms: Date.now() - startedAt
+      });
+      return raw;
+    } catch (error) {
+      const normalized = normalizeNwcWalletError(error);
+      this.#log("error", `nwc.${source}.failed`, `NWC wallet ${label} fetch failed.`, {
+        method,
+        duration_ms: Date.now() - startedAt,
+        error_code: normalized.code,
+        error_message: normalized.message
+      });
+      throw normalized;
+    }
+  }
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    const client = this.#client ?? await this.#clientPromise?.catch(() => void 0);
+    this.#client = void 0;
+    this.#clientPromise = void 0;
+    await client?.close?.();
+  }
+  async ensurePreflight() {
+    if (!this.#requirePreflight || this.#preflightSummary !== void 0) return;
+    this.#preflightPromise ??= this.preflight();
+    try {
+      await this.#preflightPromise;
+    } catch (error) {
+      this.#preflightPromise = void 0;
+      throw error;
+    }
+  }
+  async getClient() {
+    if (this.#closed) {
+      throw new Error("OpenReceive NWC receive client is closed; create a new client.");
+    }
+    if (this.#client !== void 0) return this.#client;
+    this.#clientPromise ??= (async () => {
+      const client = this.#clientFactory !== void 0 ? await this.#clientFactory(this.#connection) : await createDefaultAlbyNwcClient(this.#connectionString);
+      this.#client = client;
+      return client;
+    })();
+    try {
+      return await this.#clientPromise;
+    } catch (error) {
+      this.#clientPromise = void 0;
+      throw error;
+    }
+  }
+};
+function createNwcReceiveClient(options) {
+  return new AlbyNwcReceiveClient(options);
+}
+
 // src/swap/assets.ts
 var OPENRECEIVE_SWAP_PAY_IN_ASSETS = [
   "SOL_SOL",
@@ -92,13 +1035,13 @@ function isLightningNetwork(value) {
 }
 
 // src/swap/fixedfloat.ts
-import { ceilDiv as ceilDiv2, OPENRECEIVE_SATS_PER_BTC as OPENRECEIVE_SATS_PER_BTC2, recordOrEmpty as recordOrEmpty4, unixSeconds } from "@openreceive/core";
+import { ceilDiv as ceilDiv2, OPENRECEIVE_SATS_PER_BTC as OPENRECEIVE_SATS_PER_BTC2, recordOrEmpty as recordOrEmpty6, unixSeconds } from "@openreceive/core";
 
 // src/swap/fixedfloat-currencies.ts
-import { recordOrEmpty as recordOrEmpty2 } from "@openreceive/core";
+import { recordOrEmpty as recordOrEmpty4 } from "@openreceive/core";
 
 // src/swap/fixedfloat-fields.ts
-import { recordOrEmpty } from "@openreceive/core";
+import { recordOrEmpty as recordOrEmpty3 } from "@openreceive/core";
 function optionalCoercedString(value) {
   if (typeof value === "string" && value.length > 0) return value;
   if (typeof value === "number" && Number.isFinite(value)) return String(value);
@@ -111,7 +1054,7 @@ function optionalStringField(record, field) {
 function optionalNestedString(value, path) {
   let current = value;
   for (const key of path) {
-    current = recordOrEmpty(current)[key];
+    current = recordOrEmpty3(current)[key];
   }
   return optionalCoercedString(current);
 }
@@ -127,7 +1070,7 @@ function optionalStringArrayField(record, field) {
   const string = optionalCoercedString(value);
   return string === void 0 ? [] : [string];
 }
-function requiredString(value, field) {
+function requiredString2(value, field) {
   const string = optionalCoercedString(value);
   if (string === void 0) {
     throw new Error(`FixedFloat response missing ${field}.`);
@@ -442,11 +1385,11 @@ function fixedFloatRatePairKeys(resolution) {
   return keys;
 }
 function readFixedFloatCurrencies(data) {
-  const record = recordOrEmpty2(data);
+  const record = recordOrEmpty4(data);
   const items = Array.isArray(data) ? data : Array.isArray(record.ccies) ? record.ccies : Array.isArray(record.currencies) ? record.currencies : [];
   const currencies = [];
   for (const item of items) {
-    const record2 = recordOrEmpty2(item);
+    const record2 = recordOrEmpty4(item);
     const code = optionalStringField(record2, "code") ?? optionalStringField(record2, "ticker");
     const coin = optionalStringField(record2, "coin") ?? optionalStringField(record2, "currency") ?? optionalStringField(record2, "symbol");
     const network = optionalStringField(record2, "network") ?? optionalStringField(record2, "chain") ?? optionalStringField(record2, "networkName") ?? optionalStringField(record2, "name");
@@ -464,9 +1407,9 @@ function readFixedFloatCurrencies(data) {
 }
 
 // src/swap/fixedfloat-orders.ts
-import { recordOrEmpty as recordOrEmpty3 } from "@openreceive/core";
+import { recordOrEmpty as recordOrEmpty5 } from "@openreceive/core";
 function normalizeFixedFloatOrder(data, input) {
-  const fields = extractFixedFloatOrderFields(recordOrEmpty3(data), input);
+  const fields = extractFixedFloatOrderFields(recordOrEmpty5(data), input);
   const { attention, attention_reason } = fields.status;
   return {
     provider: input.provider,
@@ -498,7 +1441,7 @@ function readFixedFloatOrderFee(record) {
   return { currency: "USD", pay_in_fiat: payInFiat, payout_fiat: payoutFiat };
 }
 function requiredOrderField(record, field, fallback, label) {
-  return optionalStringField(record, field) ?? fallback ?? requiredString(record[field], label);
+  return optionalStringField(record, field) ?? fallback ?? requiredString2(record[field], label);
 }
 function requiredExpiresAt(expiresAt) {
   if (expiresAt === void 0) {
@@ -516,8 +1459,8 @@ function persistedStatus(fallback) {
 }
 function extractFixedFloatOrderFields(record, input) {
   const fallback = input.fallback;
-  const from = recordOrEmpty3(record.from);
-  const emergency = recordOrEmpty3(record.emergency);
+  const from = recordOrEmpty5(record.from);
+  const emergency = recordOrEmpty5(record.emergency);
   const refundTxId = optionalNestedString(record, ["back", "tx", "id"]) ?? optionalNestedString(record, ["refund", "tx", "id"]) ?? fallback?.refund_tx_id;
   const rawStatus = optionalStringField(record, "status");
   const status = rawStatus === void 0 && fallback !== void 0 ? persistedStatus(fallback) : normalizeFixedFloatStatus(rawStatus ?? "NEW", emergency, refundTxId);
@@ -532,7 +1475,7 @@ function extractFixedFloatOrderFields(record, input) {
     // body the one we already persisted stands. A create body without either is
     // a provider contract break, not something to paper over with now + 10min.
     expiresAt: requiredExpiresAt(
-      readUnixSeconds(recordOrEmpty3(record.time).expiration) ?? fallback?.expires_at
+      readUnixSeconds(recordOrEmpty5(record.time).expiration) ?? fallback?.expires_at
     ),
     depositMemo: optionalStringField(from, "tag") ?? fallback?.deposit_memo,
     depositTxId: optionalNestedString(record, ["from", "tx", "id"]) ?? fallback?.deposit_tx_id,
@@ -1064,7 +2007,7 @@ var FixedFloatProvider = class {
         direction: "to",
         amount: amountMsatsToBtcString(invoiceAmountMsats)
       });
-      return readFixedFloatOrderFee(recordOrEmpty4(data));
+      return readFixedFloatOrderFee(recordOrEmpty6(data));
     } catch {
       return void 0;
     }
@@ -1175,7 +2118,7 @@ function amountMsatsToBtcString(amountMsats) {
 }
 
 // src/lsc-uri.ts
-import { compact } from "@openreceive/core";
+import { compact as compact2 } from "@openreceive/core";
 var LSC_URI_PROTOCOL = "lightning+swapconnect:";
 var LSC_ENV_NAMES = ["LSC_URI_PRIMARY", "LSC_URI_BACKUP"];
 var LSC_QUERY_PARAMETERS = /* @__PURE__ */ new Set(["key", "secret"]);
@@ -1264,7 +2207,7 @@ function readLscConnectionsFromEnvironment(environment = process.env) {
 function createLscSwapProvidersFromEnvironment(environment = process.env, options = {}) {
   return readLscConnectionsFromEnvironment(environment).map(
     (connection) => fixedFloatCompatibleSwapProvider(
-      compact({
+      compact2({
         id: connection.providerId,
         baseUrl: connection.baseUrl,
         key: connection.key,
@@ -1314,7 +2257,7 @@ function providerIdFromUri(uri) {
 }
 
 // src/service/logging.ts
-import { compact as compact2, isRecord } from "@openreceive/core";
+import { compact as compact3, isRecord } from "@openreceive/core";
 function emitLog(options, level, event, message, fields = {}) {
   emitEvent(options, {
     level,
@@ -1375,7 +2318,7 @@ function redactSecrets(value) {
 }
 function summarizeSwapProviderApiRequest(entry) {
   const body = isRecord(entry.body) ? entry.body : void 0;
-  return compact2({
+  return compact3({
     provider: entry.provider,
     path: entry.path,
     reference: optionalLogString(body?.id),
@@ -1460,6 +2403,10 @@ function optionalLogNumber(value) {
 }
 
 export {
+  WalletPreflightError,
+  ReceiveCheckoutValidationError,
+  HEX_64,
+  createNwcReceiveClient,
   OPENRECEIVE_SWAP_PAY_IN_ASSETS,
   isSwapPayInAsset,
   listSwapAssetInfo,