@arkade-os/lnurl-client 0.0.0-stage → 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,796 @@
+import { d as PollVerifyOptions, F as FetchImpl, e as VerifyStatus, P as PayRequest, R as RequestInvoiceOptions, I as InvoiceResult, V as VerifyExpectation, Q as QuotedAmount, f as DestinationResult, g as RegisterAddressRequest, h as RegisteredAddress, D as DomainCapabilities, A as AddressListEntry, i as RegisterArkadeIdentityRequest, H as HdReceiveAllocationPage, a as PaymentPage } from './addresses-CPAzIbJ_.js';
+export { j as AmountObject, B as Bolt11Activity, k as Bolt11Result, l as Bolt11VerifyStatus, m as DestinationActivity, n as DestinationVerifyStatus, c as HdReceiveAllocation, b as HdReceiveConfig, o as PaymentActivity, p as PaymentOption, q as PaymentQuote, r as Unit, U as UnitAmount, s as domainCapabilities, t as listAddresses, u as listHdAllocations, v as listPayments, w as registerAddress, x as registerArkadeIdentity, y as revokeAddress, z as upgradeAddress } from './addresses-CPAzIbJ_.js';
+
+/**
+ * The single error type for expected LNURL failures.
+ *
+ * It unifies the server's two wire shapes: the LUD-06 protocol shape
+ * (`HTTP 200` carrying `{ status: "ERROR", reason }`) and the management
+ * shape (a real status code carrying `{ error, code? }`). Either way the
+ * caller keeps a `reason`, plus the `httpStatus` and `code` when the wire
+ * carried them.
+ *
+ * `retryable` is true if and only if `httpStatus === 429`: rate limiting is
+ * the one failure worth retrying, everything else is terminal.
+ */
+declare class LnurlError extends Error {
+    /** Human-readable failure reason, taken from the wire `reason`/`error` field. */
+    readonly reason: string;
+    /** HTTP status when the failure came with one; absent for LUD-06 bodies answered at HTTP 200. */
+    readonly httpStatus?: number;
+    /** Machine-readable server code, when the management surface sent one. */
+    readonly code?: string;
+    /** True if and only if `httpStatus === 429`; every other failure is terminal. */
+    readonly retryable: boolean;
+    /**
+     * Creates an `LnurlError`.
+     *
+     * @param reason - Human-readable failure reason, also used as the message.
+     * @param opts - Optional `httpStatus` and `code` captured from the response.
+     */
+    constructor(reason: string, opts?: {
+        httpStatus?: number;
+        code?: string;
+    });
+}
+/**
+ * Thrown when the request itself never completed: the injected `fetch`
+ * rejected, or the body could not be read as JSON. The original failure is
+ * preserved as `cause`. Protocol and rate-limit failures never surface here;
+ * they become `LnurlError`.
+ */
+declare class LnurlTransportError extends Error {
+    /**
+     * Creates an `LnurlTransportError`.
+     *
+     * @param message - Short description of which transport step failed.
+     * @param opts - Optional `cause` carrying the original thrown value.
+     */
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `pollVerify` outlasts its deadline without seeing a settled
+ * invoice. `lastSnapshot` carries the most recent verify state so the caller
+ * can resume, display, or log it instead of starting blind.
+ */
+declare class LnurlTimeoutError extends Error {
+    /** The most recent verify snapshot seen before the deadline, when one was seen. */
+    readonly lastSnapshot?: unknown;
+    /**
+     * Creates an `LnurlTimeoutError`.
+     *
+     * @param message - Short description including the timeout that elapsed.
+     * @param opts - Optional `lastSnapshot` with the latest verify state.
+     */
+    constructor(message: string, opts?: {
+        lastSnapshot?: unknown;
+    });
+}
+
+/**
+ * Fetches the payRequest for a lightning address or bech32 LNURL.
+ *
+ * The returned payRequest carries its `source` (URL plus `address`/`session`
+ * surface) so `requestInvoice` can key its rail guards off it. Anything whose
+ * `tag` is not `payRequest` is rejected: this client only pays.
+ *
+ * @param input - A lightning address or bech32 LNURL.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns The payRequest with its fetch source attached.
+ */
+declare function resolve(input: string, fetchImpl: FetchImpl): Promise<PayRequest>;
+/**
+ * Asks the payRequest callback for an invoice or payment destination.
+ *
+ * `amountSat` is sats and is converted to millisats on the wire; it is
+ * range-checked locally against the payRequest bounds before any network
+ * call. With `unit` and `amount` instead, the receiver quotes the amount to
+ * millisats and the invoice must match that quote. `paymentOption` is rejected
+ * on a session payRequest that does not advertise options: a live session's
+ * callback would silently ignore it.
+ * `verify` on the result is optional: the server omits it when the BOLT11
+ * payment hash will not decode.
+ *
+ * @param payRequest - The payRequest from `resolve`, with its source attached.
+ * @param opts - `amountSat` plus optional comment, rail and unit selection.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns A BOLT11 invoice or a destination to pay on the selected rail.
+ */
+declare function requestInvoice(payRequest: PayRequest, opts: RequestInvoiceOptions, fetchImpl: FetchImpl): Promise<InvoiceResult>;
+/**
+ * Whether a verify answer is about `expected`: a BOLT11 status for the same payment
+ * hash, or a destination status on the same rail and, when both name one, the same
+ * destination. The preimage check alone only proves the answer's own invoice.
+ */
+declare function verifyStatusIsFor(status: VerifyStatus, expected: VerifyExpectation): boolean;
+/**
+ * Polls a verify URL until the payment settles, the deadline passes, or the
+ * caller aborts.
+ *
+ * `verify` is optional on a callback response (the server omits it when the
+ * BOLT11 payment hash will not decode), so there is no polling without a URL
+ * and an empty one is rejected. A `{ status: "ERROR" }` body at HTTP 200 is
+ * terminal, not a retry: unknown payment hashes report `Not found` that way.
+ * Every snapshot, settled or not, goes to `onUpdate`; an overrun throws
+ * `LnurlTimeoutError` with the last snapshot attached.
+ *
+ * @param verifyUrl - The verify URL from the invoice result.
+ * @param opts - Optional interval, timeout, per-poll callback and abort signal.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns The settled verify status.
+ */
+declare function pollVerify(verifyUrl: string, opts: PollVerifyOptions | undefined, fetchImpl: FetchImpl): Promise<VerifyStatus>;
+
+/** One entry of the batch endpoint's `results` map, keyed by the verify URL. */
+type VerifyBatchResultItem = {
+    kind: "verify";
+    status: VerifyStatus;
+} | {
+    kind: "error";
+    reason: string;
+};
+interface VerifyBatchResult {
+    /** One entry per presented verify URL, keyed by the exact string the caller presented. */
+    results: Record<string, VerifyBatchResultItem>;
+}
+interface BatchVerifyOptions {
+    /** Abort the whole call. */
+    signal?: AbortSignal;
+}
+/**
+ * One-shot LUD-XX verifyBatch snapshot: N invoice statuses on one GET.
+ *
+ * `verifyBatchUrl` is the endpoint advertised alongside the verify URLs in the
+ * callback response; callers group pending invoices by that URL and issue one
+ * request per group. The `verify` URLs themselves are opaque and passed whole.
+ * A per-item error (`{status:"ERROR", reason}` inside `results`) is data, not a
+ * transport failure, so it is represented rather than thrown; a malformed
+ * request carries the top-level error shape and still throws.
+ */
+declare function batchVerify(verifyBatchUrl: string, verifyUrls: readonly string[], opts?: BatchVerifyOptions, fetchImpl?: FetchImpl): Promise<VerifyBatchResult>;
+interface OpenVerifyBatchStreamOptions {
+    /** The endpoint from the callback response's `verifyBatch` field. */
+    verifyBatchUrl: string;
+    /** Verify URLs pending at open; the endpoint covers exactly this set at first. */
+    verifyUrls: readonly string[];
+    /** Abort from the caller's side, triggering a clean close. */
+    signal?: AbortSignal;
+}
+interface VerifyBatchStreamHandlers {
+    /** Every verify-answer frame: the initial snapshot burst and later settlements. */
+    onUpdate?: (url: string, status: VerifyStatus) => void;
+    /** One call per removed URL; nothing further arrives for it. */
+    onRemoved?: (url: string) => void;
+    /** A stream failure other than a close the user initiated. */
+    onError?: (err: Error) => void;
+    /** Stream ended, cleanly or in failure. */
+    onClose?: () => void;
+}
+interface VerifyBatchStream {
+    /** The server's session for this stream; undefined until the session frame lands. */
+    readonly sessionId: string | undefined;
+    /**
+     * Adds and removes tracked verify URLs while the connection stays open. Each
+     * added URL is answered with one snapshot frame; each removed one with one
+     * `removed` frame. Throws when the stream has already ended.
+     */
+    update(verifyUrlsToAdd: readonly string[], verifyUrlsToRemove?: readonly string[]): void;
+    /** Ends the stream locally; safe to call more than once. */
+    close(): void;
+}
+/**
+ * Opens an LUD-XX verifyBatch stream on one connection: the endpoint reads the
+ * presented set, emits the snapshot burst, then pushes settlements live.
+ *
+ * A service without streaming answers the same request with the one-shot JSON
+ * snapshot (per LUD-01 the header is ignored, only 406 reaches a rejection):
+ * that body is still the current settlement state, so it is delivered through
+ * `onUpdate` before `onClose` and the caller falls back to polling.
+ */
+declare function openVerifyBatchStream(opts: OpenVerifyBatchStreamOptions, handlers: VerifyBatchStreamHandlers, fetchImpl?: FetchImpl): VerifyBatchStream;
+
+/**
+ * Options for opening a receiver session. Without a `token` the session is
+ * ephemeral: its id is random and dies with the socket, so there is nothing
+ * to reconnect to. Pass a token-derived `token` for a resumable session.
+ */
+interface OpenSessionOptions {
+    /** Reusable token a session id is derived from; enables reconnect. */
+    token?: string;
+    /** Abort signal tearing down the stream and any pending reconnect wait. */
+    signal?: AbortSignal;
+    /** `false` disables reconnect; otherwise `{ maxAttempts?, baseDelayMs? }` with exponential backoff. */
+    reconnect?: false | {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+    };
+}
+/**
+ * The two answers to a payer's invoice request, each `POST`ing to
+ * `/lnurl/session/:id/invoice` with the session Bearer token: either the
+ * BOLT11 invoice the payer should pay, or a rejection reason.
+ */
+interface InvoiceResponder {
+    /**
+     * Answers the invoice request with a BOLT11 invoice.
+     *
+     * @param pr - The BOLT11 invoice the payer should pay.
+     * @returns A promise settling when the server accepts the invoice.
+     */
+    answerInvoice(pr: string): Promise<void>;
+    /**
+     * Rejects the invoice request with a payer-visible reason.
+     *
+     * @param reason - Why the request is refused.
+     * @returns A promise settling when the server accepts the rejection.
+     */
+    rejectInvoice(reason: string): Promise<void>;
+}
+/**
+ * Callbacks driving a receiver session. Only `onInvoiceRequest` is required:
+ * without it there is no way to mint the invoice each payer waits for.
+ */
+interface SessionHandlers {
+    /**
+     * Called per payer invoice request; answer via `respond`.
+     *
+     * @param req - The requested `amountMsat` plus the payer `comment`, when one was sent.
+     * @param respond - Answers or rejects this specific request.
+     * @returns Nothing, or a promise whose rejection routes to `onError`.
+     */
+    onInvoiceRequest(req: {
+        amountMsat: number;
+        comment?: string;
+    }, respond: InvoiceResponder): void | Promise<void>;
+    /** Called with the parsed body of each `invoice_settled` frame. */
+    onSettled?(data: Record<string, unknown>): void;
+    /** Called with transport, parse and request failures; never throws back. */
+    onError?(err: Error): void;
+    /** Called with the 1-based count before each reconnect attempt. */
+    onReconnect?(attempt: number): void;
+}
+/**
+ * A live receiver session: the LNURL to display plus settlement reporting.
+ * Invoice creation stays caller-side: the client never holds keys or funds,
+ * it only ferries the payer's request to the caller's invoice provider.
+ */
+interface LnurlSession {
+    /** Server-assigned session id, also the ownership key for LUD-16 addresses. */
+    readonly sessionId: string;
+    /** The LNURL to encode (QR, bech32) for payers. */
+    readonly lnurl: string;
+    /** Token owning this session; sent as the Bearer credential. */
+    readonly token: string;
+    /** Whether `close()` has been called. */
+    readonly closed: boolean;
+    /**
+     * Reports local settlement of an invoice for this session.
+     *
+     * Only valid while the session is connected: the server authenticates it
+     * against its live in-memory session map, so a dropped session must
+     * reconnect first or this is a 401.
+     *
+     * @param preimage - The payment preimage proving settlement.
+     * @returns A promise settling when the server records it.
+     */
+    reportSettled(preimage: string): Promise<void>;
+    /**
+     * Closes the session: stops reconnects and cancels the stream reader so an
+     * idle stream does not hang.
+     */
+    close(): void;
+}
+/**
+ * Opens a receiver session as POST-SSE over `fetch`, not `EventSource`.
+ *
+ * `EventSource` is GET-only and carries neither a JSON body nor an auth
+ * header, while the endpoint requires a `POST` with an optional `{ token }`
+ * body. The promise resolves on the first `session_created` frame carrying
+ * `{ sessionId, lnurl, token }`, not on the HTTP 200. Reconnect only happens
+ * when a `token` was supplied, because an ephemeral session id is random and
+ * dies with the socket; a 409 (id held by a different token) never retries.
+ * A null response body fails loudly instead of hanging.
+ *
+ * @param baseUrl - Server root, e.g. `https://lnurl.example.com`.
+ * @param opts - Optional token, abort signal and reconnect policy.
+ * @param handlers - Invoice, settlement, error and reconnect callbacks.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns The opened session once `session_created` arrives.
+ */
+declare function openSession(baseUrl: string, opts: OpenSessionOptions, handlers: SessionHandlers, fetchImpl: FetchImpl): Promise<LnurlSession>;
+
+/**
+ * Derives the session token from a raw private key.
+ *
+ * Produces exactly the same token as {@link deriveSessionTokenWithSigner},
+ * because it performs the same deterministic ECDSA signature itself — so a
+ * wallet can move between the two without losing ownership of its addresses.
+ *
+ * Prefer the signer form where an `Identity` is available: this one requires
+ * the caller to hand over key material, which a library should not need.
+ *
+ * @param privateKeyHex - Private key as a hex string.
+ * @param domain - The LUD-16 domain this token is for.
+ * @returns The session token as a hex string, valid only at that domain.
+ */
+declare function deriveSessionToken(privateKeyHex: string, domain: string): string;
+/**
+ * Derives the session token from a signer, so the private key never leaves the
+ * wallet. `@arkade-os/ts-sdk`'s `Identity` satisfies this structurally:
+ *
+ * ```ts
+ * const token = await deriveSessionTokenWithSigner(
+ *   (msg, type) => identity.signMessage(msg, type),
+ *   'example.com',
+ * )
+ * ```
+ *
+ * **ECDSA specifically, and the type is passed for you.** BIP-340 schnorr is
+ * randomised unless an explicit aux is supplied, which `Identity.signMessage`
+ * does not expose — and schnorr is its *default* signature type. A schnorr
+ * signature is also 64 bytes, exactly like a compact ECDSA one, so nothing
+ * about the returned bytes reveals the mistake. A non-deterministic signer
+ * would mint a fresh token on every call and silently orphan the address, so
+ * this signs twice and compares rather than trusting the caller to have wired
+ * it correctly.
+ *
+ * @param signMessage - Signs a digest; called with `"ecdsa"` by this function.
+ * @param domain - The LUD-16 domain this token is for.
+ * @returns The session token as a hex string, identical to the key-derived one.
+ */
+declare function deriveSessionTokenWithSigner(signMessage: (message: Uint8Array, signatureType: "ecdsa") => Promise<Uint8Array>, domain: string): Promise<string>;
+/**
+ * Derives the session id from a token: the first 32 hex chars of
+ * `sha256(hexDecode(token))`, hashing the token's bytes, not its hex string.
+ *
+ * Must agree with the server's derivation (`src/session-token.ts`): the id is
+ * both the live session key and the ownership key for registered LUD-16
+ * lightning addresses, so a mismatch would orphan addresses and sessions.
+ *
+ * @param tokenHex - Session token as a hex string.
+ * @returns The 32-hex-char session id.
+ */
+declare function deriveSessionId(tokenHex: string): string;
+
+type LnurlSurface = "address" | "session";
+/**
+ * Reports whether the input looks like a lightning address (`user@domain`).
+ *
+ * This is a shape check only; it never touches the network, so a well-formed
+ * but unregistered address still returns true here and fails at `resolve`.
+ *
+ * @param input - The raw user input to test.
+ * @returns True when the input has the `user@domain` shape.
+ */
+declare function isLnAddress(input: string): boolean;
+/**
+ * Reports whether the input is a bech32 LNURL that decodes to an http(s) URL.
+ *
+ * Decoded with an explicit 1023 limit because real LNURLs exceed bech32's
+ * 90-char default; mixed case is rejected per BIP-173, while an all-uppercase
+ * LNURL (what QR codes carry) still decodes fine.
+ *
+ * @param input - The raw user input to test.
+ * @returns True when the input is a well-formed LNURL.
+ */
+declare function isLnUrl(input: string): boolean;
+/**
+ * Reports whether the input is payable input of either shape: a lightning
+ * address or a bech32 LNURL.
+ *
+ * @param input - The raw user input to test.
+ * @returns True for a lightning address or a well-formed LNURL.
+ */
+declare function isValidLnUrl(input: string): boolean;
+/**
+ * Maps user input to the payRequest URL plus the surface it belongs to.
+ *
+ * A lightning address resolves against `https://domain/.well-known/lnurlp/user`
+ * with a lowercased username; a bech32 LNURL carries its own URL. The surface
+ * is `address` for `/.well-known/lnurlp/` URLs and `session` otherwise, which
+ * is what the payer rail guards are keyed off.
+ *
+ * @param input - A lightning address or bech32 LNURL.
+ * @returns The payRequest `url` and its `surface`.
+ */
+declare function toPayRequestUrl(input: string): {
+    url: string;
+    surface: LnurlSurface;
+};
+
+/**
+ * One synced payment row, keyed by server plus server-local identifier.
+ * Identifiers are unique per server, not globally, so the key scopes them.
+ */
+interface StoredPayment {
+    /** `${baseUrl}|${identifier}` — identifiers are unique per server, not globally. */
+    key: string;
+    /** Server root the payment was synced from. */
+    baseUrl: string;
+    /** Domain serving the address, taken from the page source. */
+    domain: string;
+    /** Full `user@domain` address, taken from the page source; null when nameless. */
+    lightningAddress: string | null;
+    /** The username, or the session id while nameless, taken from the page source. */
+    handle: string;
+    /** paymentHash for bolt11, verifyId for destination. */
+    identifier: string;
+    /** Which rail the payment arrived on. */
+    kind: "bolt11" | "destination";
+    /** Whether the payment has settled. */
+    settled: boolean;
+    /** Agreed amount in millisats, when recorded. */
+    amountMsat: number | null;
+    /** Creation timestamp in milliseconds. */
+    createdAt: number;
+    /** Settlement timestamp in milliseconds, null while pending. */
+    settledAt: number | null;
+    /** RFQ id when a bolt11 payment was an offline swap, null otherwise. */
+    swapId: string | null;
+    /** Arkade txid once observed on a destination payment, null otherwise. */
+    paymentReference: string | null;
+    /** Arkade txid that credited the owner's own address, on any rail — the one
+     *  their wallet can match against its own transaction history. */
+    payoutReference: string | null;
+    /** Preimage once a bolt11 payment settled; null while pending and on the
+     * destination rail, which has no invoice to prove. */
+    preimage: string | null;
+    /** The rail a destination payment settled on, e.g. `arkade`. Null on the
+     * bolt11 rail, where `kind` already says which rail it was. */
+    paymentOption: string | null;
+    /** Per-payment covenant script when the server derived one, else null. The
+     * attribution key for concurrent covenant payments, and what a consumer
+     * verifying the payment on-chain has to match against. */
+    covenantScript: string | null;
+    /** What the payer asked to pay in a LUD-XX unit; absent when they paid in sats. */
+    quote?: QuotedAmount;
+}
+/**
+ * The persistence the sync loop needs. Applications can wrap their own backends
+ * with createLnurlPaymentRepository, or use browserPaymentStore for a small demo.
+ * IndexedDB does not exist in Node or React Native. `upsert` is a
+ * primitive rather than read-then-write so a database-backed store can do it
+ * in one statement instead of loading every record on every sync.
+ */
+interface PaymentSyncStore {
+    /** Insert or replace by `record.key`. MUST overwrite, never append. */
+    upsert(records: StoredPayment[]): Promise<void>;
+    /** Last good inclusive cursor for one address, undefined when never synced. */
+    readWatermark(baseUrl: string, lightningAddress: string): Promise<number | undefined>;
+    /** Persists the inclusive cursor after a page is upserted; it moves backwards. */
+    writeWatermark(baseUrl: string, lightningAddress: string, since: number): Promise<void>;
+}
+/**
+ * One address to sync: where it lives and whose payments to list.
+ */
+interface PaymentSyncTarget {
+    /** Server root serving the address. */
+    baseUrl: string;
+    /** Token owning the address; sent as the Bearer credential. */
+    token: string;
+    /** The username, or the session id while nameless; the sync watermark is keyed off it. */
+    handle: string;
+    /** Domain part of the address. */
+    domain: string;
+}
+/**
+ * Syncs payment activity for every target into the consumer-supplied store.
+ *
+ * Each target paginates while a page comes back full
+ * (`payments.length === limit`); a short page ends that target. The watermark
+ * is written only after a page is successfully upserted, so a target that fails
+ * wholly keeps its old cursor. It holds the oldest row still waiting to settle,
+ * not the newest `createdAt`, because `settled` mutates after a row is created;
+ * it reaches one page back at most, so a row nothing will ever settle costs one
+ * extra page per sync rather than re-paging the history. Pagination itself still
+ * walks `nextSince` forward. `nextSince` is inclusive, so the boundary row is
+ * deliberately re-fetched and the store's key-overwrite absorbs it — the loop
+ * itself never dedupes. Only `LnurlError.retryable` (HTTP 429) is retried;
+ * anything else is terminal. A full page that leaves the cursor where it was
+ * fails that target instead of re-fetching itself forever. A failing target is
+ * collected into `failures` and the loop continues with the next one; this
+ * function never throws.
+ *
+ * `client` is a factory rather than a single client because a client is pinned
+ * to one `baseUrl`, while targets may live on different servers. Sharing one
+ * would send every target's bearer token to whichever server that client was
+ * built for:
+ *
+ * ```ts
+ * await syncPayments(targets, {
+ *   client: (baseUrl) => createLnurlClient({ baseUrl }),
+ *   store,
+ * })
+ * ```
+ *
+ * @param targets - Addresses to sync, each bound to its serving baseUrl.
+ * @param opts - Builds the client for one server, the store to write to, and an optional page limit.
+ * @returns `synced` counts every row upserted, including rows a target stored
+ *          on earlier pages before failing on a later one — so it always
+ *          matches what is in the store. Such a target also appears in
+ *          `failures`, meaning a non-zero `synced` and a failure can coexist.
+ */
+declare function syncPayments(targets: PaymentSyncTarget[], opts: {
+    client: (baseUrl: string) => Pick<LnurlClient, "listPayments">;
+    store: PaymentSyncStore;
+    limit?: number;
+}): Promise<{
+    synced: number;
+    failures: {
+        baseUrl: string;
+        error: unknown;
+    }[];
+}>;
+
+/** A CAIP-19 asset id, split. Its CAIP-2 prefix is the chain. */
+interface TokenAsset {
+    id: string;
+    chainId: string;
+    namespace: string;
+    chainReference: string;
+    assetNamespace: string;
+    reference: string;
+}
+/** A `units[]` entry a token option is quoted in. */
+interface TokenUnit {
+    code: string;
+    decimals: number;
+    name?: string;
+}
+/** A payment option for a token on a non-Bitcoin chain, as `tokenOptions` accepts one. */
+interface TokenOption {
+    id: string;
+    asset: TokenAsset;
+    unit: TokenUnit;
+    /** False only when the payRequest says the option is down right now. */
+    available: boolean;
+    verifiable?: boolean;
+    minSendable?: number;
+    maxSendable?: number;
+    /** The third party the payer hands the token to, e.g. "FixedFloat". */
+    provider?: string;
+}
+/** True when `address` is a recipient on chains of the given CAIP-2 namespace. */
+declare function isTokenAddress(namespace: string, address: string): boolean;
+/**
+ * The payRequest's token options, parsed exactly as the BTCPay LNURLVerify plugin parses
+ * them (TokenOption.cs), so a wallet and a checkout agree on what is on offer.
+ *
+ * An option is dropped when its `asset` is not a CAIP-19 id of a namespace a payment can
+ * be built for, when its `type` is not that namespace, when its `unit` names no `units[]`
+ * entry, and, with every option sharing it, when its `id` is not unique.
+ */
+declare function tokenOptions(payRequest: Pick<PayRequest, "paymentOptions" | "units">): TokenOption[];
+
+/** A `PaymentSyncStore` over `localStorage`. Synchronous, a few megabytes, and it
+ *  rewrites every record per upsert — back a real wallet with IndexedDB instead. */
+declare function browserPaymentStore(prefix?: string): PaymentSyncStore;
+/** Everything synced for one address, newest first. A nameless receiver has no
+ *  lightning address to match on, so name it by `{ domain, handle }` instead. */
+declare function storedPayments(address: string | {
+    domain: string;
+    handle: string;
+}, prefix?: string): StoredPayment[];
+declare function forgetStoredPayments(prefix?: string): void;
+
+interface ReceiverConfirmation {
+    /** Defaults to verifyUrl; distinct sends can share a verify endpoint. */
+    key?: string;
+    verifyUrl: string;
+    verifyBatch?: string;
+    expect?: VerifyExpectation;
+    onSettled: (status: VerifyStatus) => void;
+    onError: (err: Error) => void;
+    /** Original send time in milliseconds, so resuming preserves its deadline. */
+    startedAt?: number;
+    timeoutMs?: number;
+}
+interface PendingConfirmations {
+    add(confirmation: ReceiverConfirmation): void;
+    forget(): void;
+}
+declare const CONFIRMATION_TIMEOUT_MS = 180000;
+declare function createPendingConfirmations(client?: Pick<LnurlClient, "pollVerify" | "batchVerify">): PendingConfirmations;
+
+interface LnurlPaymentStore {
+    read(): Promise<StoredPayment[]>;
+    /** Insert or replace by key, leaving records absent from the batch untouched. */
+    write(records: StoredPayment[]): Promise<void>;
+    clear(): Promise<void>;
+}
+interface LnurlPaymentWatermarkStore {
+    read(baseUrl: string, lightningAddress: string): Promise<number | undefined>;
+    write(baseUrl: string, lightningAddress: string, since: number): Promise<void>;
+    clear(): Promise<void>;
+}
+interface LnurlPaymentRepository extends PaymentSyncStore {
+    all(): Promise<StoredPayment[]>;
+    /** Explicit purge; use clearLnurlPaymentsForReset to close and drain writers first. */
+    clear(): Promise<void>;
+    closeWrites(): void;
+    reopenWrites(): void;
+    writesClosed(): boolean;
+    writesSettled(): Promise<void>;
+}
+declare function createLnurlPaymentRepository(payments: LnurlPaymentStore, watermarks: LnurlPaymentWatermarkStore): LnurlPaymentRepository;
+declare function clearLnurlPaymentsForReset(repository: LnurlPaymentRepository): Promise<void>;
+
+/** `amount` in a unit's smallest denomination, as a decimal: ("500", 2) reads "5.00". */
+declare function formatUnitAmount(amount: string | number, decimals: number): string;
+/** A typed decimal in a unit's smallest denomination: ("5.5", 2) is 550. Undefined for
+ *  anything that is not a plain positive decimal, or has more places than the unit. */
+declare function parseUnitAmount(text: string, decimals: number): number | undefined;
+
+interface TokenQuote {
+    optionId: string;
+    destination: string;
+    baseUnits: string;
+    amount: string;
+    value: string;
+    /** Quote deadline in Unix milliseconds. */
+    expiresAt: number;
+    paymentDestinationTag?: string;
+}
+/** Validates the token answer and keeps only an instruction that pays its exact quote. */
+declare function payableTokenUri(token: TokenOption, answer: DestinationResult): string;
+/** Normalizes an expiring token quote without applying a wallet's minimum lifetime or price policy. */
+declare function normalizeTokenQuote(token: TokenOption, answer: DestinationResult, nowMs?: number): TokenQuote;
+
+/**
+ * Options for `createLnurlClient`. Everything is optional: payer-only
+ * callers omit `baseUrl` entirely and inject nothing when the global `fetch`
+ * will do.
+ */
+interface LnurlClientOptions {
+    /**
+     * Server root, needed ONLY for receiver/management calls (`openSession`,
+     * `registerAddress`, `listAddresses`, `revokeAddress`,
+     * `registerArkadeIdentity`). The payer surface is host-agnostic — an
+     * address resolves against its own domain and a bech32 LNURL against its
+     * decoded URL — so `createLnurlClient()` with no argument is valid for
+     * payer-only use. Those methods throw `LnurlError` when it is missing.
+     */
+    baseUrl?: string;
+    /**
+     * `fetch` implementation to call. Defaults to resolving `globalThis.fetch`
+     * per call, not once at construction, so a client built at module scope
+     * still sees a fetch installed later (mock, polyfill, service worker).
+     */
+    fetchImpl?: FetchImpl;
+}
+/**
+ * The single facade both roles use: host-agnostic payer calls plus
+ * `baseUrl`-bound receiver/management calls sharing one `fetch`.
+ */
+interface LnurlClient {
+    /**
+     * Fetches the payRequest for a lightning address or bech32 LNURL.
+     *
+     * @param input - A lightning address or bech32 LNURL.
+     * @returns The payRequest with its fetch source attached.
+     */
+    resolve(input: string): Promise<PayRequest>;
+    /**
+     * Asks the payRequest callback for an invoice or payment destination.
+     *
+     * @param payRequest - The payRequest from `resolve`.
+     * @param opts - `amountSat` plus optional comment, rail and unit selection.
+     * @returns A BOLT11 invoice or a destination to pay on the selected rail.
+     */
+    requestInvoice(payRequest: PayRequest, opts: RequestInvoiceOptions): Promise<InvoiceResult>;
+    /**
+     * Polls a verify URL until the payment settles, the deadline passes, or the
+     * caller aborts.
+     *
+     * @param verifyUrl - The verify URL from the invoice result.
+     * @param opts - Optional interval, timeout, per-poll callback and abort signal.
+     * @returns The settled verify status.
+     */
+    pollVerify(verifyUrl: string, opts?: PollVerifyOptions): Promise<VerifyStatus>;
+    /**
+     * One-shot LUD-XX verifyBatch: N invoice statuses on one GET.
+     *
+     * @param verifyBatchUrl - The endpoint advertised next to the verify URLs.
+     * @param verifyUrls - The verify URLs currently pending, grouped by endpoint.
+     * @param opts - Optional abort signal and `fetch` override.
+     */
+    batchVerify(verifyBatchUrl: string, verifyUrls: readonly string[], opts?: BatchVerifyOptions & {
+        fetchImpl?: FetchImpl;
+    }): Promise<VerifyBatchResult>;
+    /**
+     * Opens a receiver session as POST-SSE; resolves on `session_created`.
+     * Requires `baseUrl`.
+     *
+     * @param opts - Optional token, abort signal and reconnect policy.
+     * @param handlers - Invoice, settlement, error and reconnect callbacks.
+     * @returns The opened session once `session_created` arrives.
+     */
+    openSession(opts: OpenSessionOptions, handlers: SessionHandlers): Promise<LnurlSession>;
+    /**
+     * LUD-XX verifyBatch stream: snapshot burst first, then live settlements, and
+     * in-place tracked-set updates without reopening the connection.
+     *
+     * @param opts - Endpoint plus the initially pending verify URLs.
+     * @param handlers - Frame, removal and close callbacks.
+     */
+    openVerifyBatchStream(opts: OpenVerifyBatchStreamOptions & {
+        fetchImpl?: FetchImpl;
+    }, handlers: VerifyBatchStreamHandlers): VerifyBatchStream;
+    /**
+     * Registers a LUD-16 lightning address. Requires `baseUrl`.
+     *
+     * @param req - Token, optional username/claimCode/domain, and optional API key.
+     * @returns The registered address and how to reach it.
+     */
+    registerAddress(req: RegisterAddressRequest): Promise<RegisteredAddress>;
+    upgradeAddress(req: {
+        token: string;
+        handle: string;
+        username?: string;
+        claimCode?: string;
+        domain?: string;
+    }): Promise<RegisteredAddress>;
+    domainCapabilities(opts?: {
+        domain?: string;
+    }): Promise<DomainCapabilities>;
+    /**
+     * Lists the LUD-16 addresses owned by a token. Requires `baseUrl`.
+     *
+     * @param token - Token whose addresses to list.
+     * @returns The addresses owned by the token.
+     */
+    listAddresses(token: string): Promise<AddressListEntry[]>;
+    /**
+     * Revokes one address owned by a token. Requires `baseUrl`.
+     *
+     * @param token - Token owning the address.
+     * @param handle - Handle of the address to revoke.
+     * @param opts - Optional domain scoping the revocation.
+     * @returns A promise settling when the server revokes the address.
+     */
+    revokeAddress(token: string, handle: string, opts?: {
+        domain?: string;
+    }): Promise<void>;
+    /**
+     * Binds an Arkade identity to a registered address. Requires `baseUrl`.
+     *
+     * @param req - Token, handle, Arkade address, claim key, optional boarding address and domain.
+     * @returns A promise settling when the server records the identity.
+     */
+    registerArkadeIdentity(req: RegisterArkadeIdentityRequest): Promise<void>;
+    listHdAllocations(token: string, handle: string, opts?: {
+        domain?: string;
+        after?: number;
+        limit?: number;
+    }): Promise<HdReceiveAllocationPage>;
+    /**
+     * Lists the payments made to one address owned by a token. Requires `baseUrl`.
+     *
+     * @param token - Token owning the address.
+     * @param handle - Handle of the address whose payments to list.
+     * @param opts - Optional domain, inclusive since cursor and page limit.
+     * @returns The payment page with rail-discriminated activity entries.
+     */
+    listPayments(token: string, handle: string, opts?: {
+        domain?: string;
+        since?: number;
+        limit?: number;
+    }): Promise<PaymentPage>;
+}
+/**
+ * Creates the client both roles share.
+ *
+ * `baseUrl` is receiver-side state only: the payer surface resolves against
+ * the address domain or the decoded LNURL, so payer-only callers pass nothing
+ * and only the receiver/management methods demand it. The default `fetch`
+ * resolves `globalThis.fetch` per call, not once at construction, so a client
+ * built at module scope still sees a fetch installed later.
+ *
+ * @param opts - Optional `baseUrl` and `fetchImpl`.
+ * @returns A client sharing one resolved `fetch` across both roles.
+ */
+declare function createLnurlClient(opts?: LnurlClientOptions): LnurlClient;
+
+export { AddressListEntry, type BatchVerifyOptions, CONFIRMATION_TIMEOUT_MS, DestinationResult, DomainCapabilities, FetchImpl, HdReceiveAllocationPage, type InvoiceResponder, InvoiceResult, type LnurlClient, type LnurlClientOptions, LnurlError, type LnurlPaymentRepository, type LnurlPaymentStore, type LnurlPaymentWatermarkStore, type LnurlSession, type LnurlSurface, LnurlTimeoutError, LnurlTransportError, type OpenSessionOptions, type OpenVerifyBatchStreamOptions, PayRequest, PaymentPage, type PaymentSyncStore, type PaymentSyncTarget, type PendingConfirmations, PollVerifyOptions, QuotedAmount, type ReceiverConfirmation, RegisterAddressRequest, RegisterArkadeIdentityRequest, RegisteredAddress, RequestInvoiceOptions, type SessionHandlers, type StoredPayment, type TokenAsset, type TokenOption, type TokenQuote, type TokenUnit, type VerifyBatchResult, type VerifyBatchResultItem, type VerifyBatchStream, type VerifyBatchStreamHandlers, VerifyExpectation, VerifyStatus, batchVerify, browserPaymentStore, clearLnurlPaymentsForReset, createLnurlClient, createLnurlPaymentRepository, createPendingConfirmations, deriveSessionId, deriveSessionToken, deriveSessionTokenWithSigner, forgetStoredPayments, formatUnitAmount, isLnAddress, isLnUrl, isTokenAddress, isValidLnUrl, normalizeTokenQuote, openSession, openVerifyBatchStream, parseUnitAmount, payableTokenUri, pollVerify, requestInvoice, resolve, storedPayments, syncPayments, toPayRequestUrl, tokenOptions, verifyStatusIsFor };