@openreceive/node 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,774 @@
+import { WalletCapabilitySummary, ReceiveNwcClient, NwcTransaction, ParsedNwcConnection, RedactedNwcConnection, MakeInvoiceRequest, MakeInvoiceResult, ListTransactionsRequest, ListTransactionsResult, ErrorCode, ErrorBody, RateQuote, SourcedPriceProvider, SimplePriceFetch, PaidPayment, PaymentCheck, BtcFiatRateMapWithSource, MoneyAmount, CachedPriceFeed } from '@openreceive/core';
+export { ErrorBody, ErrorCode, NwcTransaction, OpenReceiveError, PaidPayment, PaymentCheck, RateQuote, ReceiveNwcClient } from '@openreceive/core';
+
+/**
+ * Everything that reaches a wallet: the compatible-client shape OpenReceive
+ * accepts, method dispatch across naming conventions, the lazily loaded
+ * @getalby/sdk client, and subscription teardown.
+ */
+interface AlbyNwcCompatibleClient {
+    getInfo?: () => Promise<unknown>;
+    get_info?: () => Promise<unknown>;
+    getWalletServiceInfo?: () => Promise<unknown>;
+    makeInvoice?: (request: Record<string, unknown>) => Promise<unknown>;
+    make_invoice?: (request: Record<string, unknown>) => Promise<unknown>;
+    listTransactions?: (request: Record<string, unknown>) => Promise<unknown>;
+    list_transactions?: (request: Record<string, unknown>) => Promise<unknown>;
+    subscribeNotifications?: (callback: (notification: unknown) => void, notificationTypes?: string[]) => unknown;
+    close?: () => Promise<void> | void;
+}
+
+/**
+ * NWC failure normalization: the wallet-error alias table and the walk that
+ * turns any client's thrown shape into a canonical `OpenReceiveError`.
+ * Pure functions over already-thrown values — no transport, no wallet calls.
+ */
+
+type WalletPreflightErrorCode = "missing_required_method" | "spend_capability_advertised" | "unsupported_encryption" | "wallet_unavailable";
+declare class WalletPreflightError extends Error {
+    readonly code: WalletPreflightErrorCode;
+    readonly summary?: WalletCapabilitySummary;
+    constructor(code: WalletPreflightErrorCode, message: string, summary?: WalletCapabilitySummary);
+}
+declare class ReceiveCheckoutValidationError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * NIP-47 request building, request validation, and reply normalization.
+ *
+ * Everything here is a pure function over a value the wallet already returned,
+ * so every accept/degrade/skip rule is testable without a relay. Reply handling
+ * is deliberately tolerant per field: the wallet is trusted, and one quirky row
+ * must never fail a reconciliation scan.
+ */
+
+/**
+ * Normalized NWC-02 wallet notification. `transaction` is the notification
+ * payload normalized exactly like a `list_transactions` row, so a settled
+ * `payment_received` can settle its matching pending attempt directly —
+ * notifications are authenticated wallet data. Logging still surfaces only
+ * the type and the payment hash, never the payload.
+ */
+interface NwcWalletNotification {
+    readonly type: string;
+    readonly payment_hash?: string;
+    readonly transaction?: NwcTransaction;
+}
+/**
+ * A wallet client that also supports NWC-02 notifications. Declared rather than
+ * duck-typed: both concrete clients (Alby, testkit) implement it, and core's
+ * ReceiveNwcClient stays the minimum receive contract for custom clients that
+ * only poll.
+ */
+interface NotifyingReceiveNwcClient extends ReceiveNwcClient {
+    subscribeNotifications?(handler: (notification: NwcWalletNotification) => void): Promise<() => Promise<void> | void>;
+}
+
+/**
+ * The receive-only NWC client OpenReceive drives a wallet with.
+ *
+ * Only the client itself lives here — the transport, the reply normalization,
+ * and the error table are separate modules so each is testable without a relay:
+ * - `./nwc/transport.ts` — wallet dispatch and the lazily loaded @getalby/sdk client.
+ * - `./nwc/normalize.ts` — request building, validation, reply normalization.
+ * - `./nwc/errors.ts` — preflight/validation errors and the wallet-error table.
+ */
+
+type NwcWalletNotificationHandler = (notification: NwcWalletNotification) => void;
+type NwcNotificationUnsubscribe = () => Promise<void> | void;
+type AlbyNwcClientFactory = (connection: ParsedNwcConnection) => Promise<AlbyNwcCompatibleClient> | AlbyNwcCompatibleClient;
+type NwcEndpointLogLevel = "debug" | "info" | "warn" | "error";
+interface NwcEndpointLogEntry {
+    readonly level: NwcEndpointLogLevel;
+    readonly event: string;
+    readonly message: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Server-side hook invoked every time the receive client hits an NWC wallet
+ * endpoint (get_info / make_invoice / list_transactions). Structurally
+ * compatible with the node service's Logger so the same sink can be
+ * reused. The hook must never throw — failures are swallowed so diagnostics can
+ * never change receive-checkout behavior.
+ */
+type NwcEndpointLogger = (entry: NwcEndpointLogEntry) => void;
+interface AlbyNwcReceiveClientOptions {
+    connectionString: string;
+    client?: AlbyNwcCompatibleClient;
+    clientFactory?: AlbyNwcClientFactory;
+    requirePreflight?: boolean;
+    logger?: NwcEndpointLogger;
+    /**
+     * Explicit override: boot even when the connection advertises spend methods
+     * such as `pay_invoice` — in `get_info.methods`, or in the kind-13194 info
+     * event when the client exposes no `get_info`. Defaults to `false`, which
+     * makes preflight fail closed on a spend-capable connection.
+     */
+    allowSpendCapableWallet?: boolean;
+    /**
+     * Pause after warning that the info event advertises spend methods (override
+     * path only). Defaults to `0`: a library must not stall a host's boot. A CLI
+     * with a human at the terminal passes {@link SPEND_CAPABILITY_WARNING_DELAY_MS}
+     * so the warning can be read before output scrolls on.
+     */
+    spendCapabilityWarningDelayMs?: number;
+    /** Sink for the spend-capability warning (override path only). Defaults to `console.error`. */
+    spendCapabilityWarning?: (message: string) => void;
+}
+declare class AlbyNwcReceiveClient implements ReceiveNwcClient {
+    #private;
+    /**
+     * 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.
+     */
+    readonly connection: RedactedNwcConnection;
+    constructor(options: AlbyNwcReceiveClientOptions);
+    preflight(): Promise<WalletCapabilitySummary>;
+    makeInvoice(request: MakeInvoiceRequest): Promise<MakeInvoiceResult>;
+    listTransactions(request: ListTransactionsRequest): Promise<ListTransactionsResult>;
+    /**
+     * 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.
+     */
+    subscribeNotifications(handler: NwcWalletNotificationHandler): Promise<NwcNotificationUnsubscribe>;
+    close(): Promise<void>;
+    private ensurePreflight;
+    private getClient;
+}
+declare function createNwcReceiveClient(options: AlbyNwcReceiveClientOptions): AlbyNwcReceiveClient;
+
+declare const OPENRECEIVE_SWAP_PAY_IN_ASSETS: readonly ["SOL_SOL", "USDT_TRON", "USDT_SOL", "USDC_SOL", "ETH_ETH", "USDT_ETH", "USDC_ETH"];
+type SwapPayInAsset = (typeof OPENRECEIVE_SWAP_PAY_IN_ASSETS)[number];
+
+interface SwapCacheResolveOptions<T> {
+    readonly refreshSeconds: number;
+    readonly maxStaleSeconds: number;
+    readonly claimSeconds?: number;
+    readonly serveStaleOnFailure?: boolean;
+    readonly fetch: () => Promise<T>;
+    readonly serialize: (value: T) => string;
+    readonly deserialize: (value: string) => T;
+}
+interface TransientSwapCacheOptions {
+    readonly warn?: (message: string, fields?: Record<string, unknown>) => void;
+}
+/** Disposable, process-local provider catalog/rate cache. It has no storage adapter. */
+declare class TransientSwapCache {
+    #private;
+    constructor(clock: () => number, options?: TransientSwapCacheOptions);
+    resolve<T>(key: string, options: SwapCacheResolveOptions<T>): Promise<T>;
+}
+
+type SwapProviderState = "creating_provider_order" | "awaiting_deposit" | "confirming" | "exchanging" | "paying_invoice" | "completed" | "expired" | "refund_required" | "refund_pending" | "refunded" | "attention" | "failed";
+type SwapAvailabilityReason = "provider_unconfigured" | "amount_too_small" | "amount_too_large" | "pair_temporarily_unavailable" | "region_unsupported" | "provider_rate_limited" | "provider_unreachable";
+/**
+ * Why a swap attempt entered the `attention` state and needs human/support review.
+ * Every code path that sets `attention: true` records one of these so a dashboard or
+ * runbook can branch on the cause instead of a bare boolean. See the "Attention"
+ * section of docs/internal/swap-operations.md for the per-reason operator runbook.
+ */
+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.
+ */
+type SwapRefundReason = "underpaid" | "late_deposit" | "underpaid_and_late";
+interface SwapQuote {
+    readonly pay_amount?: string;
+    readonly minimum_pay_amount?: string;
+    readonly maximum_pay_amount?: string;
+    /** Invoice-side (Lightning receive) limits in msats, when the provider reports them. */
+    readonly minimum_invoice_amount_msats?: number;
+    readonly maximum_invoice_amount_msats?: number;
+    readonly pay_asset: SwapPayInAsset;
+    readonly available: boolean;
+    readonly unavailable_reason?: SwapAvailabilityReason;
+    readonly unavailable_message?: string;
+    readonly provider: string;
+}
+interface SwapProviderAsset {
+    readonly pay_asset: SwapPayInAsset;
+    readonly available?: boolean;
+    readonly unavailable_reason?: SwapAvailabilityReason;
+    readonly unavailable_message?: string;
+    readonly minimum_pay_amount?: string;
+    readonly maximum_pay_amount?: string;
+    readonly minimum_invoice_amount_msats?: number;
+    readonly maximum_invoice_amount_msats?: number;
+}
+/**
+ * Fiat equivalents that explain why the payer sends more crypto than the cart total.
+ * Sourced from the provider's own quote (e.g. FixedFloat `from.usd` / `to.usd`). The
+ * swap fee the payer absorbs is `pay_in_fiat` − `payout_fiat` (exchange spread plus
+ * network fees, which the provider bakes into the deposit amount). All values are
+ * decimal strings so hosts can round-trip them exactly when retaining an audit snapshot.
+ */
+interface SwapFee {
+    /** Fiat currency the equivalents are expressed in, e.g. "USD". */
+    readonly currency: string;
+    /** Fiat value of the crypto the payer must send (provider `from.usd`). */
+    readonly pay_in_fiat: string;
+    /** Fiat value delivered to the merchant — the cart total (provider `to.usd`). */
+    readonly payout_fiat: string;
+}
+interface SwapOrder {
+    readonly provider: string;
+    readonly provider_order_id: string;
+    readonly provider_token: string;
+    readonly pay_in_asset: SwapPayInAsset;
+    readonly deposit_address: string;
+    readonly deposit_memo?: string;
+    readonly deposit_amount: string;
+    readonly expires_at: number;
+    readonly state: SwapProviderState;
+    readonly deposit_tx_id?: string;
+    readonly payout_tx_id?: string;
+    readonly refund_tx_id?: string;
+    readonly attention?: boolean;
+    readonly attention_reason?: SwapAttentionReason;
+    /**
+     * Why a refund is needed, when the attempt is on the refund path. Mapped from
+     * FixedFloat `emergency.status` (LESS / EXPIRED).
+     */
+    readonly refund_reason?: SwapRefundReason;
+    /**
+     * Amount actually received on the deposit tx (`from.tx.amount`), when known.
+     * Compared with `deposit_amount` to explain underpayment.
+     */
+    readonly deposit_received_amount?: string;
+    /**
+     * Provider-reported refund amount excluding the network fee (`back.amount`).
+     */
+    readonly refund_amount?: string;
+    /**
+     * FixedFloat `emergency.repeat`: a second deposit hit the same provider order.
+     * Extra funds may sit at the provider while the attempt looks like a normal
+     * refund/attention path — surface this so operators can reconcile.
+     */
+    readonly emergency_repeat?: boolean;
+    readonly fee?: SwapFee;
+    readonly raw?: unknown;
+}
+/**
+ * A single raw provider API response, surfaced for server-side observability.
+ * Carries the HTTP status and the parsed `{code, msg, data}` envelope. Emitted
+ * through the service's sanitizing log sink, so any nested secret (e.g. a
+ * FixedFloat order token) is redacted before it reaches a log line.
+ */
+interface SwapProviderApiResponseLog {
+    readonly provider: string;
+    readonly path: string;
+    readonly status: number;
+    readonly ok: boolean;
+    readonly code: unknown;
+    readonly msg: unknown;
+    readonly data: unknown;
+}
+/**
+ * A single outbound provider API request, surfaced for server-side observability
+ * alongside {@link SwapProviderApiResponseLog}. Carries the request path and body.
+ * Emitted through the service's sanitizing log sink, so any secret in the body
+ * (e.g. a FixedFloat order token on status/refund calls) is redacted; provider
+ * auth headers are never included here.
+ */
+interface SwapProviderApiRequestLog {
+    readonly provider: string;
+    readonly path: string;
+    readonly body: unknown;
+}
+interface SwapProvider {
+    readonly name: string;
+    /**
+     * Attach a disposable process-local cache for provider catalogs and quotes.
+     */
+    attachSwapCache?(cache: TransientSwapCache): void;
+    /**
+     * Attach a sink for outbound provider API requests, mirroring
+     * {@link attachApiResponseLogger}. The
+     * service routes entries through its sanitizing log sink, so secrets in the body
+     * are redacted. Providers that make no remote calls may omit this.
+     */
+    attachApiRequestLogger?(log: (entry: SwapProviderApiRequestLog) => void): void;
+    /**
+     * Attach a sink for raw provider API responses. The service routes entries through
+     * its sanitizing log sink, so nested secrets are redacted. Providers that make no
+     * remote calls may omit this.
+     */
+    attachApiResponseLogger?(log: (entry: SwapProviderApiResponseLog) => void): void;
+    /**
+     * Attach a process-local request weight guard for this provider.
+     * Providers that do not hit a weight-budgeted API may omit this.
+     */
+    attachWeightBudget?(budget: {
+        reserve(path: string): Promise<void>;
+        markRateLimited(): Promise<void>;
+    }): void;
+    supportedPayInAssets(): Promise<Set<SwapPayInAsset>>;
+    payInAssetCatalog?(): Promise<readonly SwapProviderAsset[]>;
+    invoiceExpirySeconds?(input: {
+        readonly payInAsset: SwapPayInAsset;
+    }): number;
+    quote(input: {
+        readonly payInAsset: SwapPayInAsset;
+        readonly invoiceAmountMsats: number;
+    }): Promise<SwapQuote>;
+    createSwap(input: {
+        readonly payInAsset: SwapPayInAsset;
+        readonly bolt11: string;
+        readonly invoiceAmountMsats: number;
+    }): Promise<SwapOrder>;
+    getStatus(order: SwapOrder): Promise<SwapOrder>;
+    requestRefund(order: SwapOrder, refundAddress: string): Promise<void>;
+}
+
+declare const LSC_URI_PROTOCOL: "lightning+swapconnect:";
+interface LscConnection {
+    readonly uriProtocol: typeof LSC_URI_PROTOCOL;
+    readonly baseUrl: string;
+    readonly providerId: string;
+    readonly key: string;
+    readonly secret: string;
+}
+interface FormatLscUriInput {
+    readonly baseUrl: string;
+    readonly key: string;
+    readonly secret: string;
+}
+interface CreateLscSwapProvidersOptions {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly now?: () => number;
+}
+declare function formatLscUri(input: FormatLscUriInput): string;
+
+declare class ServiceError extends Error {
+    readonly status: number;
+    readonly code: ErrorCode;
+    readonly body: ErrorBody;
+    constructor(status: number, body: ErrorBody);
+}
+
+/**
+ * The FixedFloat-compatible SwapProvider: option defaults and validation, the
+ * provider id, and the assembly that routes every SwapProvider call through the
+ * signed transport, the `/ccies` resolution and XML rates index held in the
+ * transient cache, and the order / quote normalizers beside this file.
+ */
+
+interface FixedFloatProviderOptions {
+    readonly key: string;
+    readonly secret: string;
+    readonly baseUrl?: string;
+    readonly lightningCcy?: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly now?: () => number;
+    /** TTL for the disposable `/ccies` currency catalog cache. */
+    readonly cacheSeconds?: number;
+    /**
+     * TTL for the process-local public XML rates cache (`/rates/fixed.xml`). Defaults to
+     * {@link SWAP_RATES_REFRESH_SECONDS}. Shared only within the current process.
+     */
+    readonly ratesCacheSeconds?: number;
+    readonly requestTimeoutMs?: number;
+    readonly invoiceExpirySeconds?: number;
+    readonly depositWindowSeconds?: number;
+    readonly settlementSlaSeconds?: number;
+    readonly invoiceExpiryMarginSeconds?: number;
+}
+interface FixedFloatCompatibleSwapProviderOptions extends FixedFloatProviderOptions {
+    readonly id: string;
+}
+declare function fixedFloatProvider(options: FixedFloatProviderOptions): SwapProvider;
+declare function fixedFloatCompatibleSwapProvider(options: FixedFloatCompatibleSwapProviderOptions): SwapProvider;
+
+/**
+ * Coarse lifecycle bucket for a swap attempt's `provider_state`. Twelve provider
+ * states collapse into these seven phases so a UI can branch on "what should the
+ * payer see / do now" without hardcoding every state:
+ *
+ * - `preparing`        — the deposit address is still being created.
+ * - `awaiting_deposit` — show the deposit address/amount; the payer must send funds.
+ * - `processing`       — funds seen; the provider is confirming/converting/paying.
+ * - `settling`         — provider reports done, but OpenReceive has NOT settled the
+ *                        order yet. Never render this as "Paid": the wallet sweep is
+ *                        the settlement authority (see automated-swaps.md).
+ * - `refund`           — a refund is required, staged, or in flight.
+ * - `attention`        — needs operator/support review (funds may be stuck).
+ * - `terminal`         — the attempt is over and will not change (expired/refunded/failed).
+ */
+type SwapPhase = "preparing" | "awaiting_deposit" | "processing" | "settling" | "refund" | "attention" | "terminal";
+interface SwapStateInfo {
+    /** The provider state this describes. */
+    readonly state: SwapProviderState;
+    /** Short, payer-facing status label, e.g. "Waiting for your payment". */
+    readonly label: string;
+    /** One-sentence payer-facing explanation of what is happening. */
+    readonly detail: string;
+    /** Coarse lifecycle bucket for UI branching. */
+    readonly phase: SwapPhase;
+    /**
+     * Whether the attempt is over and will not transition again. Terminal states stop
+     * being polled by the backend; a UI should stop refreshing this attempt.
+     */
+    readonly terminal: boolean;
+}
+/**
+ * The canonical catalog of every swap `provider_state`, its payer-facing copy, its
+ * coarse {@link SwapPhase}, and whether it is terminal. This is the single
+ * source of truth the built-in checkout element and custom UIs should both read from.
+ *
+ * Settlement-safety invariant: `completed` is deliberately NON-terminal and lives in
+ * the `settling` phase. Provider completion is not payment — OpenReceive only marks an
+ * order paid when the wallet sweep sees a settled transaction.
+ */
+declare const OPENRECEIVE_SWAP_STATES: Readonly<Record<SwapProviderState, SwapStateInfo>>;
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface LogEvent {
+    readonly level: LogLevel;
+    readonly event: string;
+    readonly message: string;
+    readonly [key: string]: unknown;
+}
+type EventHandler = (event: LogEvent) => void;
+/** Same signature as {@link EventHandler}; kept as the `logger` option's name. */
+type Logger = EventHandler;
+interface LoggingOptions {
+    /**
+     * Opt into the rotating file logger. Default `false`: a library must not
+     * create files in the host's working directory unasked. Console logging is
+     * unaffected.
+     */
+    readonly enabled?: boolean;
+    readonly directory?: string;
+    readonly filename?: string;
+    readonly maxFileSizeMb?: number;
+    readonly maxFiles?: number;
+    /**
+     * Minimum level for the built-in console and file loggers.
+     * When omitted, both read `LOG_LEVEL` (`DEBUG`|`INFO`|`WARN`|`ERROR`, default `INFO`).
+     */
+    readonly level?: LogLevel;
+    /**
+     * Attach the built-in console logger.
+     * Default: `true` when no custom `logger` is supplied; `false` when a custom
+     * `logger` is supplied (set `true` to keep both).
+     */
+    readonly console?: boolean;
+    /** Console prefix, e.g. `openreceive:my-app`. Default `openreceive`. */
+    readonly prefix?: string;
+}
+interface NodeOptions {
+    readonly client: NotifyingReceiveNwcClient;
+    readonly priceProviders?: readonly SourcedPriceProvider[];
+    readonly priceCurrencies?: readonly string[];
+    readonly swap?: SwapOptions;
+    readonly onEvent?: EventHandler;
+    readonly logger?: Logger;
+    readonly logging?: LoggingOptions;
+    readonly clock?: () => number;
+}
+interface CreateOpenReceiveOptions extends Omit<NodeOptions, "client"> {
+    readonly client?: NotifyingReceiveNwcClient;
+    /** Explicit override. Normal applications read the receive-only URI from NWC_URI. */
+    readonly nwc?: string;
+    /** Environment source for NWC_URI, LSC_URI_PRIMARY, and LSC_URI_BACKUP. Defaults to process.env. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly priceFetch?: SimplePriceFetch;
+    /**
+     * Explicit override: boot even when the wallet advertises spend methods such
+     * as `pay_invoice`. Defaults to `false` (preflight fails closed). Also
+     * settable via `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true`.
+     */
+    readonly allowSpendCapableWallet?: boolean;
+}
+type CreateCheckoutAmount = {
+    readonly sats: number | string;
+    readonly currency?: never;
+    readonly value?: never;
+} | {
+    readonly currency: string;
+    readonly value: string;
+    readonly sats?: never;
+};
+interface CreateCheckoutRequest {
+    readonly reference: string;
+    readonly amount: CreateCheckoutAmount;
+    readonly memo?: string;
+    readonly descriptionHash?: string;
+    readonly metadata?: Record<string, unknown>;
+    /**
+     * Requested invoice expiry in seconds (default 600). Ignored on the swap
+     * path, where the provider-mandated shadow-invoice expiry always wins.
+     */
+    readonly expirySeconds?: number;
+}
+/**
+ * The minted invoice — the service-level view of the OpenAPI `Checkout` object
+ * (the HTTP handler serializes it to the snake_case wire shape,
+ * `WireCheckout`).
+ */
+interface Checkout {
+    readonly reference: string;
+    readonly paymentHash: string;
+    readonly bolt11: string;
+    readonly amountMsats: number;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+    readonly fiatQuote: RateQuote | null;
+}
+interface ReconcilePaymentsRequest {
+    readonly attempts: readonly {
+        readonly paymentHash: string;
+        readonly createdAt: number;
+    }[];
+    readonly until?: number;
+    readonly overlapSeconds?: number;
+    /** Page cap per wallet-history walk; bounds request-path (opportunistic) passes. */
+    readonly maxPages?: number;
+}
+type NodeSettlementActionInput = PaidPayment;
+type NodeSettlementActionHook = (input: NodeSettlementActionInput) => Promise<void> | void;
+/**
+ * One NWC-02 wallet notification: its type, the payment hash when present, and
+ * the payload normalized exactly like a `list_transactions` row. Notifications
+ * are authenticated wallet data — a `transaction` that satisfies the
+ * settlement rule (`settled_at` or a settled state; never a preimage alone)
+ * may settle its matching pending attempt directly. Logging only ever surfaces
+ * the type and the payment hash.
+ */
+interface WalletNotification {
+    readonly type: string;
+    readonly payment_hash?: string;
+    readonly transaction?: NwcTransaction;
+}
+type WalletNotificationHandler = (notification: WalletNotification) => void;
+interface SwapOptions {
+    /**
+     * The provider every catalog, quote, and create goes to while it answers.
+     * Omitted (the normal case), providers come from `LSC_URI_PRIMARY` and
+     * `LSC_URI_BACKUP` in `env`.
+     */
+    readonly provider?: SwapProvider;
+    /**
+     * Consulted in order only when `provider` (or an earlier failover) throws —
+     * a network or API failure. Never used to fill in an asset a healthy
+     * provider simply does not list. Requires `provider`.
+     */
+    readonly failoverProviders?: readonly SwapProvider[];
+}
+interface SwapQuoteRequest {
+    readonly amount: CreateCheckoutAmount;
+    readonly payInAsset: SwapPayInAsset | string;
+}
+/**
+ * Service-level swap quote, camelCase like every other service result (the
+ * HTTP handler converts to the snake_case wire shape).
+ */
+interface SwapQuoteResult {
+    readonly provider: string;
+    readonly payAsset: SwapPayInAsset;
+    readonly available: boolean;
+    readonly payAmount?: string;
+    readonly minimumPayAmount?: string;
+    readonly maximumPayAmount?: string;
+    /** Invoice-side (Lightning receive) limits in msats, when reported. */
+    readonly minimumInvoiceAmountMsats?: number;
+    readonly maximumInvoiceAmountMsats?: number;
+    readonly unavailableReason?: string;
+    readonly unavailableMessage?: string;
+}
+interface ListSwapOptionsRequest {
+    /** Host-owned invoice amount in millisatoshis. */
+    readonly amountMsats: number;
+}
+interface SwapPaymentMethod {
+    readonly payInAsset: SwapPayInAsset;
+    readonly label: string;
+    readonly networkLabel: string;
+    readonly provider: string;
+    readonly available: boolean;
+    readonly unavailableReason?: string;
+    readonly unavailableMessage?: string;
+    readonly payAmount?: string;
+    readonly minimumPayAmount?: string;
+    readonly maximumPayAmount?: string;
+    readonly minimumInvoiceAmountMsats?: number;
+    readonly maximumInvoiceAmountMsats?: number;
+}
+interface ListSwapOptionsResult {
+    readonly enabled: boolean;
+    readonly options: readonly SwapPaymentMethod[];
+}
+interface CreateSwapRequest extends CreateCheckoutRequest {
+    readonly payInAsset: SwapPayInAsset | string;
+}
+interface GetSwapRequest {
+    readonly reference: string;
+    readonly paymentHash: string;
+    readonly swapData: SwapData;
+}
+interface SwapRefundRequest extends GetSwapRequest {
+    readonly refundAddress: string;
+}
+/** Server-only provider recovery state persisted by the host application. */
+interface SwapData {
+    readonly version: 1;
+    readonly providerOrder: SwapOrder;
+}
+interface PublicSwap {
+    readonly paymentHash: string;
+    readonly reference: string;
+    readonly provider: string;
+    readonly payInAsset: SwapPayInAsset;
+    readonly depositAddress: string;
+    readonly depositMemo?: string;
+    readonly depositAmount: string;
+    readonly providerState: SwapProviderState;
+    readonly providerExpiresAt: number;
+    readonly depositTxId?: string;
+    readonly payoutTxId?: string;
+    readonly refundTxId?: string;
+    readonly refundReason?: string;
+    readonly refundAmount?: string;
+    readonly attention?: boolean;
+    /** Why the attempt needs an operator, when `attention` is set. */
+    readonly attentionReason?: string;
+    /**
+     * Amount actually received on the deposit transaction, when the provider
+     * reports it. The payer UI compares it with `depositAmount` to explain an
+     * underpayment ("you sent X but Y was required").
+     */
+    readonly depositReceivedAmount?: string;
+    /**
+     * A second deposit hit the same provider order. Extra funds may sit at the
+     * provider while the attempt looks like an ordinary refund path.
+     */
+    readonly emergencyRepeat?: boolean;
+    /** Provider-side order reference, shown to the payer for support. */
+    readonly providerOrderId?: string;
+    /**
+     * Fiat equivalents explaining why the payer sends more than the cart total.
+     * Never a price authority — the invoice amount is.
+     */
+    readonly fee?: SwapFee;
+}
+interface SwapCheckout extends PublicSwap {
+    readonly checkout: Checkout;
+    /** Sensitive host-only state. Never serialize this into a browser response. */
+    readonly swapData: SwapData;
+}
+interface ListRatesRequest {
+    readonly currencies?: readonly string[];
+}
+interface OpenReceive {
+    readonly priceCurrencies: readonly string[];
+    /** Resolve amount_msats without minting a Lightning invoice or committing an attempt. */
+    prepareCheckout(input: {
+        readonly amount: CreateCheckoutAmount;
+    }): Promise<{
+        readonly amountMsats: number;
+        readonly fiatQuote: RateQuote | null;
+    }>;
+    createCheckout(input: CreateCheckoutRequest): Promise<Checkout>;
+    reconcilePayments(input: ReconcilePaymentsRequest): Promise<readonly PaymentCheck[]>;
+    /**
+     * Opt-in NWC-02 notifications: subscribe to wallet `payment_received`
+     * notifications. Notifications are authenticated wallet data — a payload
+     * that satisfies the settlement rule settles its matching pending attempt
+     * directly; anything less only wakes a batched wallet scan
+     * (`reconcilePayments`). Polling remains the safety net for notifications
+     * missed while offline. Direct settlement assumes the NWC client binds
+     * notification decryption to the connection's wallet pubkey (the bundled
+     * SDK does). Resolves to an unsubscribe function; rejects with an
+     * OpenReceiveError of code `UNSUPPORTED_METHOD` when the wallet client does
+     * not support notifications.
+     */
+    subscribeWalletNotifications?(handler: WalletNotificationHandler): Promise<() => Promise<void> | void>;
+    quoteSwap(input: SwapQuoteRequest): Promise<SwapQuoteResult>;
+    listSwapOptions(input: ListSwapOptionsRequest): Promise<ListSwapOptionsResult>;
+    createSwap(input: CreateSwapRequest): Promise<SwapCheckout>;
+    getSwap(input: GetSwapRequest): Promise<PublicSwap>;
+    refundSwap(input: SwapRefundRequest): Promise<PublicSwap>;
+    listRates(input?: ListRatesRequest): Promise<BtcFiatRateMapWithSource["rates"]>;
+    quoteRates(input: {
+        readonly fiat: MoneyAmount;
+    }): Promise<RateQuote>;
+    close(): Promise<void>;
+}
+
+declare function createPriceFeed(options: {
+    currencies: readonly string[];
+    fetch?: SimplePriceFetch;
+    clock?: () => number;
+    cacheSeconds?: number;
+    /** Environment for the URL override vars. Defaults to process.env. */
+    env?: Readonly<Record<string, string | undefined>>;
+}): CachedPriceFeed;
+
+type ConfigErrorCode = "MISSING_NWC" | "INVALID_NWC" | "WALLET_PREFLIGHT_FAILED" | "INVALID_PRICE_CURRENCIES";
+declare class ConfigError extends Error {
+    readonly code: ConfigErrorCode;
+    readonly hint: string;
+    readonly cause?: unknown;
+    constructor(input: {
+        readonly code: ConfigErrorCode;
+        readonly message: string;
+        readonly hint: string;
+        readonly cause?: unknown;
+    });
+}
+
+declare function createOpenReceive(supplied?: CreateOpenReceiveOptions): Promise<OpenReceive>;
+
+declare function sanitizeEvent(entry: LogEvent): LogEvent;
+
+interface RequireNwcFromEnvironmentOptions {
+    /** Environment object to read. Defaults to `process.env`. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Subject phrase for the missing-NWC message. Default `"OpenReceive"`. */
+    readonly subject?: string;
+}
+/**
+ * Read and validate the receive-only connection string in `NWC_URI`.
+ * Throws an `Error` with a host-facing message when missing or invalid.
+ */
+declare function readNwcFromEnvironment(options?: RequireNwcFromEnvironmentOptions): string;
+
+interface CreateConsoleLoggerOptions {
+    /** Prefix before the event, e.g. `openreceive:my-app`. Default `openreceive`. */
+    readonly prefix?: string;
+    /**
+     * Minimum level to emit. Default: `LOG_LEVEL` from the environment, or `info`.
+     * Accepts the same values as `LOG_LEVEL` (`DEBUG` | `INFO` | `WARN` | `ERROR`).
+     */
+    readonly minLevel?: LogLevel | string;
+    readonly console?: Pick<Console, "debug" | "info" | "warn" | "error" | "log">;
+    /** Clock for the leading ISO timestamp. Default `() => new Date()`. */
+    readonly now?: () => Date;
+}
+type AppConsoleLogger = (event: string, message: string, fields?: Record<string, unknown>, level?: LogLevel) => void;
+interface CreateAppConsoleLoggerOptions {
+    /** Prefix before the event, e.g. `hello-fruit:node-express:server`. */
+    readonly prefix: string;
+    /**
+     * Minimum level to emit. Default: `LOG_LEVEL` from the environment, or `info`.
+     */
+    readonly minLevel?: LogLevel | string;
+    readonly console?: Pick<Console, "debug" | "info" | "warn" | "error" | "log">;
+    readonly now?: () => Date;
+}
+/** Ad-hoc `(event, message, fields?, level?)` console logger for host app routes. */
+declare function createAppConsoleLogger(options: CreateAppConsoleLoggerOptions): AppConsoleLogger;
+
+export { type AlbyNwcReceiveClientOptions, type AppConsoleLogger, type Checkout, ConfigError, type CreateAppConsoleLoggerOptions, type CreateCheckoutAmount, type CreateCheckoutRequest, type CreateConsoleLoggerOptions, type CreateLscSwapProvidersOptions, type CreateOpenReceiveOptions, type CreateSwapRequest, type EventHandler, type FixedFloatCompatibleSwapProviderOptions, type FixedFloatProviderOptions, type FormatLscUriInput, type GetSwapRequest, type ListRatesRequest, type ListSwapOptionsRequest, type ListSwapOptionsResult, type LogEvent, type LogLevel, type Logger, type LoggingOptions, type LscConnection, type NodeSettlementActionHook, type NodeSettlementActionInput, type NwcEndpointLogEntry, type NwcEndpointLogLevel, type NwcEndpointLogger, type NwcNotificationUnsubscribe, OPENRECEIVE_SWAP_PAY_IN_ASSETS, OPENRECEIVE_SWAP_STATES, type OpenReceive, type PublicSwap, ReceiveCheckoutValidationError, type ReconcilePaymentsRequest, type RequireNwcFromEnvironmentOptions, ServiceError, type SwapAttentionReason, type SwapCheckout, type SwapData, type SwapOptions, type SwapOrder, type SwapPayInAsset, type SwapPaymentMethod, type SwapProvider, type SwapProviderAsset, type SwapProviderState, type SwapQuote, type SwapQuoteRequest, type SwapQuoteResult, type SwapRefundRequest, type WalletNotification, type WalletNotificationHandler, WalletPreflightError, type WalletPreflightErrorCode, createAppConsoleLogger, createNwcReceiveClient, createOpenReceive, createPriceFeed, fixedFloatCompatibleSwapProvider, fixedFloatProvider, formatLscUri, readNwcFromEnvironment, sanitizeEvent };