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

package/dist/index.d.ts

@@ -0,0 +1,1176 @@
+/**
+ * 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;
+    });
+}
+
+/**
+ * The `fetch` implementation this client calls.
+ *
+ * Deliberately structural rather than `typeof globalThis.fetch`: an
+ * implementation whose signature differs slightly — notably `expo/fetch`,
+ * which React Native needs for a readable `response.body` — is then
+ * assignable without an `as unknown as` cast. Only string URLs are ever
+ * passed, so any `fetch` accepting something wider satisfies this.
+ */
+type FetchImpl = (input: string, init?: RequestInit) => Promise<Response>;
+
+interface PaymentOption {
+    /** Rail identifier the callback expects back as `paymentOption`. */
+    id: string;
+    /** Rail family, e.g. `lightning` or `arkade`. */
+    type: string;
+    /** The rail as a CAIP-19 asset id; `id` is still what the callback takes back. */
+    caip19Id?: string;
+    /** Whether the rail can currently be selected. */
+    available?: boolean;
+    /** Whether callback answers on this rail carry a LUD-21 `verify` URL; absent means unknown. */
+    verifiable?: boolean;
+    /** Minimum sendable amount on this rail. */
+    minSendable?: number;
+    /** Maximum sendable amount on this rail. */
+    maxSendable?: number;
+    /** CAIP-19 id of the token a token option is paid in; its CAIP-2 namespace is `type`.
+     *  Read token options through `tokenOptions`, which validates them. */
+    asset?: string;
+    /** The `units[]` code a token option is quoted in. */
+    unit?: string;
+    /** The third party the payer hands funds to on this option, e.g. "FixedFloat". */
+    provider?: string;
+}
+/**
+ * A unit the receiver prices in on the lightning rail (fiat or asset alongside
+ * the native `sat`/`msat`). Quoting a non-native unit is what produces the
+ * `paymentQuote` echoed on the invoice result.
+ */
+interface Unit {
+    /** Unit code the callback expects back as `unit`, e.g. `USD`. */
+    code: string;
+    /** Decimal places amounts in this unit are expressed with. */
+    decimals: number;
+    /** Human-readable unit name. */
+    name?: string;
+    /** Display symbol for the unit. */
+    symbol?: string;
+    /** Asset identifier backing the unit, for asset-denominated units. */
+    assetId?: string;
+    /** Minimum amount expressible in this unit, as a decimal string. */
+    minAmount?: string;
+    /** Maximum amount expressible in this unit, as a decimal string. */
+    maxAmount?: string;
+}
+/** An amount paired with the unit it is denominated in. */
+interface AmountObject {
+    /** Decimal amount string in `unit`. */
+    amount: string;
+    /** Unit code from `Unit.code`. */
+    unit: string;
+}
+/**
+ * The server's quote for a unit-converted payment: what was requested, what
+ * the payer pays, what the receiver gets, and the fee breakdown in between.
+ */
+interface PaymentQuote {
+    /** Quote identifier, when the server issues one. */
+    id?: string;
+    /** Expiry of the quote, when the server bounds it. */
+    expiresAt?: string;
+    /** Amount the payer asked to deliver. */
+    requested: AmountObject;
+    /** Amount the payer must actually pay. */
+    payment: AmountObject;
+    /** Amount the receiver will get after conversion. */
+    receive?: AmountObject;
+    /** Named fee legs making up the difference. */
+    fees?: {
+        name?: string;
+        amount: AmountObject;
+    }[];
+}
+/** An LUD-06 payRequest plus the `source` (URL and surface) it was fetched from. */
+interface PayRequest {
+    /** LUD-06 tag; `resolve` rejects anything that is not a payRequest. */
+    tag: "payRequest";
+    /** Callback URL the invoice request is built against. */
+    callback: string;
+    /** Minimum sendable amount in millisats. */
+    minSendable: number;
+    /** Maximum sendable amount in millisats. */
+    maxSendable: number;
+    /** JSON-encoded LUD-06 metadata array. */
+    metadata: string;
+    /** Maximum comment length in characters, when the receiver accepts one. */
+    commentAllowed?: number;
+    paymentOptions?: PaymentOption[];
+    units?: Unit[];
+    /** Where this payRequest came from; drives the rail guards downstream. */
+    source: {
+        url: string;
+        surface: "address" | "session";
+    };
+}
+/**
+ * Options for asking the callback for an invoice or payment destination.
+ * `amountSat` is sats and is converted to millisats on the wire.
+ */
+interface RequestInvoiceOptions {
+    /** Amount to pay in sats; converted to millisats on the wire. */
+    amountSat: number;
+    /** Optional payer comment, sent when the payRequest allows one. */
+    comment?: string;
+    paymentOption?: string;
+    /** Lightning rail only. */
+    unit?: string;
+}
+/**
+ * What the callback answered: either a BOLT11 invoice to pay, or a
+ * destination to pay on a non-lightning rail (e.g. an Arkade address).
+ */
+type InvoiceResult = Bolt11Result | DestinationResult;
+/**
+ * A BOLT11 invoice from the callback. `verify` is optional because the server
+ * omits it when the invoice's payment hash will not decode; `pollVerify`
+ * refuses a missing one instead of polling `undefined`.
+ */
+interface Bolt11Result {
+    /** Discriminant for the BOLT11 shape. */
+    kind: "bolt11";
+    /** The BOLT11 invoice to pay. */
+    pr: string;
+    /** Verify URL tracking settlement; absent when the server could not decode the payment hash. */
+    verify?: string;
+    /** LUD-XX verifyBatch: endpoint that batch-styles or streams settlement for a whole tracked set. */
+    verifyBatch?: string;
+    /** Rail the invoice was issued for, echoed back when one was selected. */
+    paymentOption?: string;
+    /** Quote for a unit-converted payment, when one was requested. */
+    paymentQuote?: PaymentQuote;
+}
+/**
+ * A non-BOLT11 destination from the callback: pay it on the selected rail and
+ * then track settlement through `verify`, exactly like the BOLT11 shape.
+ */
+interface DestinationResult {
+    /** Discriminant for the destination shape. */
+    kind: "destination";
+    /** The selected rail both sides settle on. */
+    paymentOption: string;
+    /** Where to pay on that rail, e.g. an Arkade address. */
+    paymentDestination?: string;
+    /** A memo the payment must carry. A wallet that cannot attach one must not pay. */
+    paymentDestinationTag?: string;
+    /** Wallet-executable instruction carrying the amount (BIP21, EIP-681, Solana Pay); none on Tron. */
+    paymentURI?: string;
+    /** What the payer actually pays on a rail priced in a token. Its `expiresAt` is the
+     *  payer's deadline: a token answer carries no top-level `expiresAt`. */
+    paymentQuote?: PaymentQuote;
+    /** Unix seconds after which the server stops attributing payments to this destination. */
+    expiresAt?: number;
+    /** The third party the payer hands funds to, e.g. "FixedFloat". */
+    provider?: string;
+    /** Verify URL tracking settlement; absent under the same conditions as the BOLT11 shape. */
+    verify?: string;
+    /** LUD-XX verifyBatch: batch/stream endpoint covering a whole tracked set. */
+    verifyBatch?: string;
+}
+/** The settlement state `pollVerify` resolves with, in either rail shape. */
+type VerifyStatus = Bolt11VerifyStatus | DestinationVerifyStatus;
+/** Settlement state of a BOLT11 payment: `preimage` is null until settled. */
+interface Bolt11VerifyStatus {
+    /** Discriminant for the BOLT11 shape. */
+    kind: "bolt11";
+    /** Whether the invoice has settled. */
+    settled: boolean;
+    /** Payment preimage once settled, null while pending. */
+    preimage: string | null;
+    /** The invoice this status belongs to. */
+    pr: string;
+}
+/** Settlement state of a destination-rail payment. */
+interface DestinationVerifyStatus {
+    /** Discriminant for the destination shape. */
+    kind: "destination";
+    /** Whether the payment has settled. */
+    settled: boolean;
+    /** The rail both sides settled on. */
+    paymentOption: string;
+    /** Where the payment landed, when the server reports it. */
+    paymentDestination?: string;
+    /** Server-assigned payment reference, when the server reports one. */
+    paymentReference?: string;
+}
+/**
+ * Tuning for `pollVerify`: how often to re-poll, how long to wait overall,
+ * what to report per poll, and how to abort early.
+ */
+interface PollVerifyOptions {
+    /** Milliseconds between polls; defaults to 1000. */
+    intervalMs?: number;
+    /** Overall deadline in milliseconds; defaults to 120000. */
+    timeoutMs?: number;
+    /** Called with every polled snapshot, including unsettled ones. */
+    onUpdate?: (s: VerifyStatus) => void;
+    /** Abort signal for caller-driven cancellation. */
+    signal?: AbortSignal;
+    /** The payment the verify URL was issued for — the callback's answer will do.
+     *  An answer about any other payment then fails instead of resolving. */
+    expect?: VerifyExpectation;
+}
+/** The invoice, or the rail and destination, a verify answer must be about. */
+type VerifyExpectation = Pick<Bolt11Result, "pr"> | Pick<DestinationResult, "paymentOption" | "paymentDestination">;
+/**
+ * One page of address payment activity: what was paid to one address, who it
+ * belongs to, and where to resume. nextSince is inclusive, so a client
+ * re-fetching from it dedupes on paymentHash/verifyId.
+ */
+interface PaymentPage {
+    /** Where the payments were earned: domain, full address (null when nameless), and handle. */
+    source: {
+        domain: string;
+        lightningAddress: string | null;
+        handle: string;
+    };
+    /** Activity entries, least recently changed first. */
+    payments: PaymentActivity[];
+    /** The last row's updatedAt (createdAt on older servers), or the request's since when empty. */
+    nextSince: number;
+}
+/**
+ * One payment to an address. The rail decides the shape: only the lightning
+ * rail carries a real payment hash, so the arkade rail is keyed by its
+ * verify id instead of overloading the hash field.
+ */
+type PaymentActivity = Bolt11Activity | DestinationActivity;
+/**
+ * A lightning-rail payment to the address. paymentHash is a real BOLT11
+ * payment hash here.
+ */
+interface Bolt11Activity {
+    /** Discriminant for the BOLT11 shape. */
+    kind: "bolt11";
+    /** Real BOLT11 payment hash. */
+    paymentHash: string;
+    /** The BOLT11 invoice handed to the payer. */
+    pr: string;
+    /** Payment preimage once settled, null while pending. */
+    preimage: string | null;
+    /** RFQ id when this was an offline swap, null for relay invoices. */
+    swapId: string | null;
+    /** Arkade txid of the claim that paid the covenant out to the owner — a swap
+     *  settles on a preimage, so this is the only txid their wallet holds. */
+    payoutReference: string | null;
+    /** 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;
+}
+/**
+ * A destination-rail (e.g. arkade/covenant) payment to the address. The
+ * server's paymentHash field holds a random verify id on this rail, so it
+ * is exposed as verifyId and there is no paymentHash here at all.
+ */
+interface DestinationActivity {
+    /** Discriminant for the destination shape. */
+    kind: "destination";
+    /** Opaque verify id minted by the server; NOT a payment hash. */
+    verifyId: string;
+    /** The rail both sides settled on. */
+    paymentOption: string;
+    /** Where the payment landed, when the server reports it. */
+    paymentDestination: string | null;
+    /** Attribution key for per-payment covenant addresses. */
+    covenantScript: string | null;
+    /** Arkade txid once observed, null until then. */
+    paymentReference: string | null;
+    /** Arkade txid that credited the owner's own address — the payment itself on
+     *  the static rail, the sweep on a covenant one. */
+    payoutReference: string | null;
+    /** 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;
+}
+
+/**
+ * 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. `paymentOption` and `unit` are rejected on a session payRequest that
+ * does not advertise them: a live session's callback would silently ignore them.
+ * `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;
+};
+
+/**
+ * What registering a LUD-16 lightning address needs. `token` owns the
+ * address: the server derives the session id from it and keys ownership off
+ * that id, so the same token lists and revokes what it registered.
+ */
+interface RegisterAddressRequest {
+    /** Token owning the address; doubles as the Bearer credential. */
+    token: string;
+    /** Desired username; server-assigned when omitted. */
+    username?: string;
+    /** Claim code binding the registration, on domains that issue one. */
+    claimCode?: string;
+    /** Receiving domain; the server default when omitted. */
+    domain?: string;
+    /** Sent as `X-API-Key` on domains that require one. */
+    apiKey?: string;
+    /** Registers a nameless receiver instead; mutually exclusive with `username`/`claimCode`. */
+    nameless?: boolean;
+}
+/** A freshly registered LUD-16 lightning address and how to reach it. */
+interface RegisteredAddress {
+    /** The `user@domain` address payers use; null for a nameless receiver. */
+    lightningAddress: string | null;
+    /** The bech32 LNURL encoding of the payRequest URL. */
+    lnurl: string;
+    /** Username part of the address; null for a nameless receiver. */
+    username: string | null;
+    /** The username, or the session id while nameless; changes on upgrade. */
+    handle: string;
+    /** Domain part of the address. */
+    domain: string;
+    /** Registration status reported by the server. */
+    status: string;
+    nameless: boolean;
+    sessionLnurl: string | null;
+}
+/** One address owned by a token, as listed by the server; same nullability as `RegisteredAddress`. */
+interface AddressListEntry {
+    username: string | null;
+    /** Domain part of the address. */
+    domain: string;
+    /** Registration status reported by the server. */
+    status: string;
+    /** Creation timestamp reported by the server. */
+    createdAt: number;
+    lightningAddress: string | null;
+    /** The bech32 LNURL encoding of the payRequest URL. */
+    lnurl: string;
+    handle: string;
+    nameless: boolean;
+    /** Survives a later upgrade to a name. */
+    sessionLnurl: string | null;
+}
+/** What a domain allows, discoverable before calling any of its routes. */
+interface DomainCapabilities {
+    domain: string;
+    allocationModes: string[];
+    usernameRules: {
+        minLen: number;
+        maxLen: number;
+        pattern: string;
+    };
+    requireApiKey: boolean;
+}
+/**
+ * What binding an Arkade identity to an address needs. `claimPublicKey` must
+ * be a compressed 33-byte key and is checked locally; the Arkade address
+ * itself is NOT validated client-side because that would need the SDK, which
+ * is deliberately not a dependency.
+ */
+interface RegisterArkadeIdentityRequest {
+    /** Token owning the address; sent as the Bearer credential. */
+    token: string;
+    /** Handle of the already-registered address. */
+    handle: string;
+    /** Arkade address receiving offline payments; validated server-side. */
+    arkadeAddress: string;
+    /** Compressed 33-byte public key: `02`/`03` prefix plus 64 hex chars. */
+    claimPublicKey: string;
+    /** Boarding address the onchain rail pays; omit it to leave a registered one alone. */
+    boardingAddress?: string;
+    /** Receiving domain; the server default when omitted. */
+    domain?: string;
+}
+/**
+ * Registers a LUD-16 lightning address owned by `req.token`.
+ *
+ * @param baseUrl - Server root, e.g. `https://lnurl.example.com`.
+ * @param req - Token, optional username/claimCode/domain, and optional API key.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns The registered address and how to reach it.
+ */
+declare function registerAddress(baseUrl: string, req: RegisterAddressRequest, fetchImpl: FetchImpl): Promise<RegisteredAddress>;
+/**
+ * Lists the LUD-16 addresses owned by a token.
+ *
+ * @param baseUrl - Server root, e.g. `https://lnurl.example.com`.
+ * @param token - Token whose addresses to list; sent as the Bearer credential.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns The addresses owned by the token.
+ */
+declare function listAddresses(baseUrl: string, token: string, fetchImpl: FetchImpl): Promise<AddressListEntry[]>;
+/** Upgrades a nameless receiver in place to a named one; everything handed out while nameless keeps working. */
+declare function upgradeAddress(baseUrl: string, req: {
+    token: string;
+    handle: string;
+    username?: string;
+    claimCode?: string;
+    domain?: string;
+}, fetchImpl: FetchImpl): Promise<RegisteredAddress>;
+declare function domainCapabilities(baseUrl: string, opts: {
+    domain?: string;
+} | undefined, fetchImpl: FetchImpl): Promise<DomainCapabilities>;
+/**
+ * Lists the payments made to one address owned by a token, oldest first.
+ *
+ * @param baseUrl - Server root, e.g. `https://lnurl.example.com`.
+ * @param token - Token owning the address; sent as the Bearer credential.
+ * @param handle - Handle of the address whose payments to list.
+ * @param opts - Optional domain, inclusive since cursor and page limit.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns The payment page with rail-discriminated activity entries.
+ */
+declare function listPayments(baseUrl: string, token: string, handle: string, opts: {
+    domain?: string;
+    since?: number;
+    limit?: number;
+} | undefined, fetchImpl: FetchImpl): Promise<PaymentPage>;
+/**
+ * Revokes one address owned by a token.
+ *
+ * @param baseUrl - Server root, e.g. `https://lnurl.example.com`.
+ * @param token - Token owning the address; sent as the Bearer credential.
+ * @param handle - Handle of the address to revoke.
+ * @param opts - Optional domain scoping the revocation.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns A promise settling when the server revokes the address.
+ */
+declare function revokeAddress(baseUrl: string, token: string, handle: string, opts: {
+    domain?: string;
+} | undefined, fetchImpl: FetchImpl): Promise<void>;
+/**
+ * Binds an Arkade identity to a registered address for offline receive.
+ *
+ * `claimPublicKey` must be a compressed 33-byte key and is rejected locally
+ * before any network call; the Arkade address itself is NOT validated
+ * client-side because that would need the SDK, which is deliberately not a
+ * dependency, so a malformed one fails server-side instead.
+ *
+ * `boardingAddress` is unvalidated for a stronger reason — it is a Bitcoin
+ * address on the operator's network, which this package cannot know — and
+ * omitting it sends no field, read server-side as "leave the onchain rail".
+ *
+ * @param baseUrl - Server root, e.g. `https://lnurl.example.com`.
+ * @param req - Token, handle, Arkade address, claim key, optional boarding address and domain.
+ * @param fetchImpl - The injected `fetch` implementation to call.
+ * @returns A promise settling when the server records the identity.
+ */
+declare function registerArkadeIdentity(baseUrl: string, req: RegisterArkadeIdentityRequest, fetchImpl: FetchImpl): Promise<void>;
+
+/**
+ * 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;
+}
+/**
+ * The persistence the sync loop needs. The package ships no implementation:
+ * IndexedDB does not exist in Node or React Native, so the consumer supplies
+ * the store — exactly as it already supplies `fetchImpl`. `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;
+
+/**
+ * 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>;
+    /**
+     * 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 { type AddressListEntry, type AmountObject, type BatchVerifyOptions, type Bolt11Activity, type Bolt11Result, type Bolt11VerifyStatus, type DestinationActivity, type DestinationResult, type DestinationVerifyStatus, type DomainCapabilities, type FetchImpl, type InvoiceResponder, type InvoiceResult, type LnurlClient, type LnurlClientOptions, LnurlError, type LnurlSession, type LnurlSurface, LnurlTimeoutError, LnurlTransportError, type OpenSessionOptions, type OpenVerifyBatchStreamOptions, type PayRequest, type PaymentActivity, type PaymentOption, type PaymentPage, type PaymentQuote, type PaymentSyncStore, type PaymentSyncTarget, type PollVerifyOptions, type RegisterAddressRequest, type RegisterArkadeIdentityRequest, type RegisteredAddress, type RequestInvoiceOptions, type SessionHandlers, type StoredPayment, type TokenAsset, type TokenOption, type TokenUnit, type Unit, type VerifyBatchResult, type VerifyBatchResultItem, type VerifyBatchStream, type VerifyBatchStreamHandlers, type VerifyExpectation, type VerifyStatus, batchVerify, browserPaymentStore, createLnurlClient, deriveSessionId, deriveSessionToken, deriveSessionTokenWithSigner, domainCapabilities, forgetStoredPayments, isLnAddress, isLnUrl, isTokenAddress, isValidLnUrl, listAddresses, listPayments, openSession, openVerifyBatchStream, pollVerify, registerAddress, registerArkadeIdentity, requestInvoice, resolve, revokeAddress, storedPayments, syncPayments, toPayRequestUrl, tokenOptions, upgradeAddress, verifyStatusIsFor };