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

package/README.md

@@ -1,3 +1,362 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @arkade-os/lnurl-client
+
+Full-duplex client for the lnurl-server protocol: payer (`resolve`, `requestInvoice`, `pollVerify`) and receiver (sessions, settled reporting, address and Arkade-identity registration).
+
+## Install
+
+```sh
+pnpm add @arkade-os/lnurl-client
+```
+
+The SDK is an optional peer: `>=0.5.0-rc.0` (0.5.0 release candidates and stable 0.5+ releases). The main entry point needs no SDK; `/arkade` uses the SDK installed by your app.
+
+Runtime dependencies are `@scure/base` and `@noble/hashes` - nothing else is pulled in, and the package never imports the server, so app bundles stay free of `express` and `sqlite`.
+
+## With an Arkade wallet
+
+If you hold an `@arkade-os/sdk` wallet, start here. `arkadeLnurl` takes the wallet and the server root and does the rest - token derivation, claiming the address, binding the identity, the sync loop, and the send rails:
+
+```ts
+import { arkadeLnurl } from '@arkade-os/lnurl-client/arkade'
+import { browserPaymentStore } from '@arkade-os/lnurl-client'
+
+const lnurl = arkadeLnurl({ wallet, baseUrl: 'https://lnurl.example.com', store: browserPaymentStore() })
+
+// Receive: claims the name AND binds the identity, which is what makes the
+// address advertise any paymentOptions at all. Omit the name for a
+// server-assigned one, or pass `{ nameless: true }` for no address at all -
+// just the stable `lnurl` below.
+const rx = await lnurl.claim({ username: 'alice' })   // rx.lightningAddress === 'alice@lnurl.example.com'
+await rx.sync()                                       // pull the server's own records
+
+// Send: the router already knows how to pay a Lightning address.
+const [best] = await lnurl.options('bob@example.com', 1000)
+const handle = await (await best.quote()).send()
+```
+
+`wallet.identity` supplies the signing, so nothing else is passed in. The token is derived once and memoised - it signs twice on first use to prove the signer is deterministic, and a second call costs nothing. `claim` and `owned` return a `Receiver`, scoped to one address:
+
+| you want | call |
+| --- | --- |
+| what this domain allows | `capabilities()` |
+| the address this wallet already owns here | `owned()` |
+| claim a name (or none) and bind the identity | `claim(opts?)` |
+| its `user@domain`, or `undefined` when nameless | `receiver.lightningAddress` |
+| an LNURL for a QR | `receiver.lnurl` |
+| its own payRequest | `receiver.payRequest()` |
+| one page of the server's records | `receiver.payments(opts)` |
+| everything new, into your store | `receiver.sync()` |
+| name a nameless receiver in place | `receiver.upgrade(opts?)` |
+| rank the ways to pay a target | `options(target, amountSat)` |
+| the router itself | `router()` |
+
+**`payRequest()` fetches once per 30 s.** Every call on one `Receiver` within that window shares a single fetch, in flight or done, so a screen asking on every amount change costs one GET; a failed fetch is not kept. `claim` and `upgrade` retire it at once, even when they fail; a change made anywhere else - another device, the operator - shows within 30 s. `createLnurlClient().resolve(receiver.lnurl)` always asks the server.
+
+`capabilities()` reads what a domain allows before you call it - `{ domain, allocationModes, usernameRules, requireApiKey }` - so onboarding can offer only the modes actually enabled instead of guessing and hitting `forbidden_mode`. A domain requiring an operator-reserved name takes a `claimCode` the same way on either call below: `claim({ username: 'alice', claimCode })`.
+
+**Nameless, and upgrading later.** `claim({ nameless: true })` returns a `Receiver` with no lightning address at all - offline receive, rails and payment sync all work off its stable `lnurl` alone. `receiver.upgrade({ username: 'alice' })` (or `{ username, claimCode }` for a reserved name) names it in place: the wallet keeps its history and the same `lnurl` keeps paying it, but the upgrade **publicly links** that LNURL to the new name. To keep them unlinked instead, call `lnurl.claim({ username: 'alice' })` on the side - a second, separate named address (counted against the domain's per-wallet limit) with no connection to the nameless one.
+
+Paying needs no address of your own, so the router is available separately - `arkadePaymentRouter({ wallet, lightning })` returns the SDK router with the LNURL rails registered, which is what makes `route()` accept a Lightning address instead of throwing `no rail for`.
+
+Receiving accepts a `LnurlWallet`: only `identity.signMessage`, `identity.compressedPublicKey`, `getAddress`, and `getBoardingAddress` are required. It does not require the SDK's concrete `Wallet` class. For sending, the default adapter expects a full SDK spending wallet. Custom wallets can pass a `LnurlPaymentRouter` as `router` to either `arkadeLnurl` or `arkadePaymentRouter`; the adapter registers the LNURL rails on that router. `LnurlPaymentRouter` requires only `use`, `remove`, `options`, and `route`, without the SDK class's private members. SDK rails and router data types remain part of the `/arkade` contract.
+
+CI checks the client against SDK `0.5.0-rc.0` and `0.5.0-rc.19` in isolated installs, independent of the server's SDK pin. Run the same types, tests, build, and consumer checks with `node scripts/check-client-sdk-compat.mjs <sdk-version>` from the repository root.
+
+Everything below is the surface these are built on; reach for it when the facade does not fit.
+
+## Payer
+
+`createLnurlClient()` with no `baseUrl` covers payer-only use: `resolve`, `requestInvoice` and `pollVerify` talk to whatever host the address or LNURL points at.
+
+```ts
+import { createLnurlClient } from "@arkade-os/lnurl-client";
+
+const payer = createLnurlClient();
+
+const payRequest = await payer.resolve("alice@example.com"); // or an lnurl bech32 string
+const invoice = await payer.requestInvoice(payRequest, { amountSat: 50 });
+
+// Pay invoice.pr through your own Lightning path, then wait for settlement:
+if (invoice.kind === "bolt11" && invoice.verify) {
+  const status = await payer.pollVerify(invoice.verify, { timeoutMs: 120_000, intervalMs: 1_000, expect: invoice });
+  if (status.kind === "bolt11" && status.settled) {
+    console.log("settled, preimage:", status.preimage);
+  }
+}
+```
+
+A settled bolt11 status is only returned when `SHA256(preimage)` equals the payment hash in `pr`. Anything else — a wrong preimage, or a `pr` that cannot be decoded — is rejected rather than reported as settled.
+
+That proves the answer's own `pr`, not that it is the invoice you are watching. Pass the callback's answer as `expect` and an answer about any other payment — another invoice with its genuine preimage, a destination status, another destination — fails with `LnurlError` instead. lnurl rails record the same value on their quotes as `lnurlQuoteMeta(quote).expect`; for batched or streamed answers, `verifyStatusIsFor(status, expect)` is the same check.
+
+`requestInvoice` takes `amountSat` plus an optional `comment`. It also accepts `paymentOption` and `unit`, except on a session payRequest that does not advertise them (a live session's); a nameless receiver's session LNURL advertises both. The amount is range-checked locally before anything hits the wire.
+
+**Rails can carry different amounts, so check the option you selected.** A covenant destination is bounded by dust and VTXO shape, a solver-mediated swap by whatever the solver quotes — so an entry in `paymentOptions` may publish its own `minSendable`/`maxSendable`, and those win over the top-level pair when you select it. The top-level pair describes the rail you get by sending no `paymentOption` at all. `requestInvoice` applies that rule for you; apply it yourself if you build the callback URL by hand, or you will reject amounts the rail would have accepted.
+
+### Many pending invoices: verifyBatch
+
+When the callback also returns `verifyBatch` ([LUD-XX, lnurl/luds#299](https://github.com/lnurl/luds/pull/299)), one request covers every pending invoice at that endpoint:
+
+```ts
+const { results } = await payer.batchVerify(invoice.verifyBatch, pendingVerifyUrls);
+// results[url] is { kind: "verify", status } or { kind: "error", reason }, one per URL you sent
+
+const stream = payer.openVerifyBatchStream(
+  { verifyBatchUrl: invoice.verifyBatch, verifyUrls: pendingVerifyUrls },
+  { onUpdate: (url, status) => { /* snapshot first, then live settlements */ }, onClose: () => { /* reopen if still pending */ } },
+);
+stream.update([newVerifyUrl], [settledVerifyUrl]); // grow or shrink the set without reconnecting
+```
+
+`batchVerify` splits the set and retries when the server answers `414`/`431`. The stream falls back to the one-shot snapshot when the server does not stream (including a `406`), and closing is final: reopening is the caller's job.
+
+### Token options
+
+A payRequest may offer a token on another chain (an lnurl-server with FixedFloat deposits, say): an option whose `type` is a CAIP-2 namespace, with a CAIP-19 `asset`, a `unit` naming a `units[]` entry, and the `provider` the payer hands the tokens to. Read them with `tokenOptions`, which accepts exactly what the BTCPay LNURLVerify plugin accepts:
+
+```ts
+import { tokenOptions } from "@arkade-os/lnurl-client";
+
+for (const option of tokenOptions(payRequest)) {
+  const answer = await payer.requestInvoice(payRequest, { amountSat: 10_000, paymentOption: option.id });
+  if (answer.kind !== "destination") continue;
+  // answer.paymentURI (EIP-681 or Solana Pay; absent on Tron), answer.paymentDestination,
+  // answer.paymentQuote.payment = { amount: base units, unit: option.unit.code },
+  // answer.paymentQuote.expiresAt = the payer's deadline (ISO 8601)
+}
+```
+
+`requestInvoice` refuses a token answer for another option, one whose destination is not an address on the token's chain, and one that quotes no whole amount of the token. The amount you request is still sats: what the receiver is paid before the swap's fee.
+
+## Receiver
+
+Receiver and management calls need `baseUrl`. `deriveSessionToken` turns a wallet private key and a domain into a stable session token; opening a session with the same token reconnects the same session id.
+
+```ts
+import { createLnurlClient, deriveSessionToken } from "@arkade-os/lnurl-client";
+
+const receiver = createLnurlClient({ baseUrl: "https://lnurl.example.com" });
+const token = deriveSessionToken("<wallet-private-key-hex>", "example.com");
+
+const session = await receiver.openSession({ token }, {
+  onInvoiceRequest: async ({ amountMsat }, respond) => {
+    const pr = await makeInvoice(amountMsat); // injected invoice provider: your Lightning node
+    await respond.answerInvoice(pr);           // or: await respond.rejectInvoice(reason)
+  },
+});
+
+// session.lnurl is what payers resolve. Once your node reports the invoice settled:
+await session.reportSettled("<preimage-hex>");
+session.close();
+```
+
+### Deriving the token without handing over your key
+
+A library should not need your private key, so there are two ways to derive the token and **they produce the same value** — a wallet can move between them without losing its addresses:
+
+```ts
+import { deriveSessionToken, deriveSessionTokenWithSigner } from '@arkade-os/lnurl-client'
+
+// Preferred: the key never leaves the wallet.
+const token = await deriveSessionTokenWithSigner(
+  (msg, type) => identity.signMessage(msg, type),   // @arkade-os/ts-sdk Identity
+  'example.com',
+)
+
+// Equivalent, for callers that already hold raw key material:
+const same = deriveSessionToken('<private-key-hex>', 'example.com')
+```
+
+They agree because the token is `sha256` of a **deterministic ECDSA signature** over `sha256("lnurl-session:<domain>")` — a pure function of key and message — and `deriveSessionToken` simply performs that signature itself.
+
+**It must be ECDSA, and the function passes the type for you.** BIP-340 schnorr is randomised unless given an explicit aux, which `Identity.signMessage` does not expose — and schnorr is its *default*. A schnorr signature is also 64 bytes, exactly like compact ECDSA, so nothing about the returned bytes reveals the mistake; it would simply mint a new token on every call and silently orphan the address. `deriveSessionTokenWithSigner` therefore signs twice and throws if the results differ, rather than trusting the wiring.
+
+**The token is per-domain, and that is a security property, not bookkeeping.** It is a bearer credential: the server receives it and stores it (encrypted, but a server it is stored on can read it). Were it derived from the private key alone, the same credential would authenticate its holder at *every* lnurl-server the user has ever used — so one malicious or breached server could call `registerArkadeIdentity` on a different server and repoint the victim's receive address, which the covenant would then faithfully pay. Binding the domain into the derivation makes a token minted for `example.com` useless at `other.com`.
+
+Two consequences worth planning for:
+
+- A wallet using several servers holds **several tokens**, one per domain. Derive per domain rather than caching one.
+- The server cannot enforce this — it sees an opaque token and cannot tell which domain produced it — so the protection holds only for clients that derive this way.
+
+Derive the token from wallet key material rather than generating a random one you then have to persist: losing it loses the address, since the server identifies the owner by `sha256` of the token bytes and has no other record of who you are.
+
+`deriveSessionId(token)` computes that session id locally — the same value the server derives — which is useful for asserting a reconnect resumed the session you expected rather than trusting the id echoed back to you.
+
+## Validating input
+
+Exported standalone, because a UI validates what a user pasted or scanned before it has a client or a `baseUrl`:
+
+```ts
+import { isValidLnUrl, isLnAddress, isLnUrl, toPayRequestUrl } from '@arkade-os/lnurl-client'
+
+isValidLnUrl('alice@example.com')   // true  — either form
+isValidLnUrl('LNURL1DP68…')         // true
+isValidLnUrl('not an lnurl')        // false
+
+toPayRequestUrl('alice@example.com')
+// → { url: 'https://example.com/.well-known/lnurlp/alice', surface: 'address' }
+```
+
+`isLnAddress` and `isLnUrl` test one form each; `isValidLnUrl` accepts either. All are shape checks only — they never touch the network, so a well-formed but unregistered address passes here and fails at `resolve`.
+
+`toPayRequestUrl` also reports the **surface**. A live `session` LNURL takes an amount and a comment and nothing else, so `requestInvoice` rejects rail options on a session payRequest that advertises none, rather than letting the server ignore them silently. A nameless receiver's session LNURL serves its address, `paymentOptions` and units included, and is paid like one.
+
+Mixed-case LNURLs are rejected per BIP-173 — bech32 forbids mixed case so that case-mangling in transit cannot slip past the checksum. All-uppercase, which is what QR codes carry, decodes normally.
+
+## Lightning addresses
+
+A LUD-16 address (`alice@example.com`) is payable whether or not the wallet is online. Registering one is what unlocks the offline rails — without it a payer can only reach a live session.
+
+**The token is the credential for everything here.** The server derives the address's owner from it (`sha256` of the token bytes), so the same token that opens a session also owns the addresses registered with it. Losing it loses the address; leaking it hands someone else control of where payments go. Derive it from wallet key material with `deriveSessionToken` rather than generating a fresh random one you then have to store.
+
+All calls in this section need `baseUrl`.
+
+```ts
+import { createLnurlClient, deriveSessionToken } from '@arkade-os/lnurl-client'
+
+const client = createLnurlClient({ baseUrl: 'https://lnurl.example.com' })
+// Per-domain: this token authenticates at example.com and nowhere else.
+const token = deriveSessionToken('<wallet-private-key-hex>', 'example.com')
+
+const address = await client.registerAddress({ token, username: 'alice' })
+// → { lightningAddress: 'alice@example.com', lnurl: 'LNURL1…', username, domain, status }
+
+const mine = await client.listAddresses(token)
+// → [{ username, domain, status, createdAt, lightningAddress, lnurl }]
+
+await client.revokeAddress(token, 'alice')
+```
+
+`username` is optional — omit it and the server allocates one, subject to the domain's policy. Some domains require an API key to register; pass it as `apiKey` and it is sent as `X-API-Key`. Both `revokeAddress` and `registerArkadeIdentity` take an optional `domain` when the server hosts several.
+
+### Offline receive
+
+Binding an Arkade identity to an address is what lets payments arrive while the wallet is closed — the server takes a solver-mediated swap or a covenant destination on its behalf, and the funds are constrained to pay only the address you register here.
+
+```ts
+await client.registerArkadeIdentity({
+  token,
+  username: 'alice',
+  arkadeAddress: 'ark1…',
+  claimPublicKey: '02…',      // compressed 33-byte key, validated locally
+  boardingAddress: 'bc1…',    // optional: adds the onchain rail
+})
+```
+
+**Call it again to update it.** The server overwrites, so re-registering is how you point an address at a new Arkade address or claim key; there is no separate update call.
+
+`boardingAddress` is the one exception to that overwrite: register it and the address advertises an `onchain` payment option paying it, omit it and an already-registered one is left alone — so a later identity update does not silently withdraw the rail. It is sent unvalidated, unlike `claimPublicKey`, because it is an ordinary Bitcoin address on whatever network the operator runs and this package cannot know which. Payers get no `verify` URL on that rail: nothing server-side observes Bitcoin, so those payments never settle there and a URL could only ever answer "not yet".
+
+### With the Arkade SDK
+
+The main entry point stays free of `@arkade-os/sdk`, because the payer half of this package has nothing to do with Arkade and a checkout page should not pull the SDK and its Expo peers to ask an address for an invoice. A receiver already has the SDK, so the Arkade-aware helpers live behind a subpath with the SDK as an **optional peer dependency**:
+
+```ts
+import { arkadeIdentityRequest, deriveSessionTokenForIdentity } from '@arkade-os/lnurl-client/arkade'
+
+// The key never leaves the wallet, and ECDSA is chosen for you.
+const token = await deriveSessionTokenForIdentity(identity, 'example.com')
+
+// Validates the Arkade address and derives claimPublicKey from the identity.
+// boardingAddress is optional here too, and passed through unchecked.
+await client.registerArkadeIdentity(
+  await arkadeIdentityRequest({ identity, arkadeAddress, token, username: 'alice' }),
+)
+```
+
+Three things this buys over doing it by hand:
+
+- **`isArkadeAddress` decodes locally.** Without the SDK a malformed address is only caught server-side, a round trip later.
+- **`deriveSessionTokenForIdentity` pins ECDSA.** Schnorr is `Identity.signMessage`'s default and is randomised, which would mint a fresh token on every call and orphan the address — and a schnorr signature is 64 bytes exactly like compact ECDSA, so nothing about the bytes reveals the mistake.
+- **`claimPublicKeyOf` derives the compressed key** in the form the server validates, instead of leaving the caller to extract and hex-encode it.
+
+Not yet covered: verifying on-chain that a settled destination payment actually paid the registered address. `StoredPayment` carries `paymentReference` and `covenantScript` for exactly that check, but performing it needs an indexer and is not implemented here — a consumer still trusts the server's word that a payment happened.
+
+### Payment activity
+
+`listPayments` is a sync source, not just a list: it exists so a wallet that was offline can recover receives it never witnessed, which for the offline rails is every one of them.
+
+`syncPayments` drives it for you across every address you hold — paging, cursors, retry and per-server isolation — writing through a store you supply:
+
+```ts
+import { createLnurlClient, syncPayments } from '@arkade-os/lnurl-client'
+
+const { synced, failures } = await syncPayments(
+  [{ baseUrl: 'https://lnurl.example.com', token, username: 'alice', domain: 'example.com' }],
+  { client: (baseUrl) => createLnurlClient({ baseUrl }), store: myStore },
+)
+```
+
+**`browserPaymentStore()` is the only storage shipped, and it is `localStorage`** — synchronous, a few megabytes, and it rewrites every record per upsert. Fine for a demo, wrong past that, and absent entirely in Node and React Native. Anything real supplies its own store, the same injection the package uses for `fetchImpl`:
+
+```ts
+interface PaymentSyncStore {
+  upsert(records: StoredPayment[]): Promise<void>  // keyed by record.key; overwrite, never append
+  readWatermark(baseUrl: string, lightningAddress: string): Promise<number | undefined>
+  writeWatermark(baseUrl: string, lightningAddress: string, since: number): Promise<void>  // may move backwards; store verbatim
+}
+```
+
+`client` is a factory, not a client, because a client is pinned to one `baseUrl`. Sharing one across targets would send every target's bearer token to whichever server that client was built for.
+
+A target that fails lands in `failures` while the others keep syncing, and its watermark stays put — so a transient outage cannot silently skip the payments that arrived during it.
+
+These matter for correctness. `syncPayments` handles them all; you must handle them yourself if you drive `listPayments` directly:
+
+- **`page.source`** carries `{ domain, lightningAddress }`. Store it with each entry: a wallet holding addresses on several servers needs it to attribute them, and the deduplication key is `(baseUrl, identifier)` — identifiers are unique per server, not globally.
+- **`nextSince` is inclusive**, so the boundary row comes back on the next sync. Upsert rather than insert. An exclusive cursor would silently drop payments sharing a millisecond, which is why it works this way.
+- **A creation-ordered cursor cannot track settlement.** `settled` mutates long after a row is created, so a cursor parked at the newest `createdAt` never re-reads an older row that settles later — the wallet shows it pending forever. The server now pages on `updatedAt`, which lists a row again whenever it changes, but older servers page on `createdAt`. For those, `syncPayments` persists the oldest row still waiting to settle instead, and reaches at most one page back so a row nothing will ever settle — an `onchain` destination, which nothing server-side watches, or an invoice nobody paid — costs one extra page per sync rather than re-paging your whole history.
+- **Switch on `kind`, never on the presence of a payment hash.** On the arkade rail the server's own record has no payment hash — the identifier is an opaque verify id — which is why `DestinationActivity` calls it `verifyId` and has no `paymentHash` property at all.
+- **A full page need not advance the cursor.** `nextSince` is the last row's `updatedAt` (`createdAt` on older servers), so if a whole page shares one millisecond the next request returns that same page. Stop and report rather than loop; `syncPayments` fails that target with a terminal `LnurlError`.
+
+### Activity resolvers
+
+`@arkade-os/lnurl-client/arkade` also exports `lnurlActivityResolver(payments)` and `sentActivityResolver(sends)`, `ActivityResolver`s that label an `ArkTransaction` with the LNURL payment or send it corresponds to. Both take a getter rather than a store: storage — where `payments`/`sends` come from, and where a completed send is recorded (`mergeSentPayment` computes the merge; writing it is yours) — stays entirely with the caller.
+
+## Errors
+
+Two shapes, both surfaced as `LnurlError`:
+
+- LUD-06 endpoints answer HTTP 200 carrying `{ status: "ERROR", reason }`.
+- Management endpoints answer a real status code carrying `{ error, code? }` (for example 409 with `USERNAME_TAKEN`).
+- Rate limits mix the two: HTTP 429 with the `{ status: "ERROR" }` body.
+
+`LnurlError` carries `reason`, optional `httpStatus` and `code`, and `retryable`, which is true if and only if `httpStatus === 429`. Everything else is terminal - do not retry it into a different answer.
+
+`LnurlTransportError` means the request or the stream itself failed (network down, unreadable SSE body). `LnurlTimeoutError` means `pollVerify` ran past `timeoutMs`; its `lastSnapshot` holds the last verify status seen.
+
+## Transport
+
+The receiver session is POST-SSE over `fetch`: `openSession` POSTs a JSON body to `/lnurl/session` and reads the event stream from `response.body`.
+
+**It is not `EventSource`, and cannot be.** `EventSource` is GET-only and carries neither a request body nor headers, while this protocol needs both — the session token goes in the POST body, and the invoice and settled calls are Bearer-authed. That is a property of the server's endpoint rather than a choice this package makes. The practical cost is that reconnect and backoff are implemented here instead of inherited from the platform.
+
+The only requirement is therefore a `fetch` whose `Response` exposes a readable `response.body`. `openSession` throws `LnurlTransportError` immediately when it does not, rather than hanging.
+
+### React Native / Expo
+
+React Native's global `fetch` does **not** expose a readable `response.body`, so inject [`expo/fetch`](https://docs.expo.dev/versions/latest/sdk/expo/#fetch), which does. This is the same approach `@arkade-os/ts-sdk` takes for its own SSE streams.
+
+```ts
+import { fetch as expoFetch } from 'expo/fetch'
+import { createLnurlClient } from '@arkade-os/lnurl-client'
+
+const client = createLnurlClient({
+  baseUrl: 'https://lnurl.example.com',
+  fetchImpl: expoFetch,
+})
+```
+
+No cast is needed: `FetchImpl` is a structural signature — `(input: string, init?: RequestInit) => Promise<Response>` — rather than `typeof globalThis.fetch`, so any conforming implementation is assignable. The same seam takes an instrumented fetch, one that adds headers, or a test double:
+
+```ts
+const client = createLnurlClient({
+  baseUrl: 'https://lnurl.example.com',
+  fetchImpl: (url, init) =>
+    fetch(url, { ...init, headers: { ...init?.headers, 'X-App': 'wallet' } }),
+})
+```
+
+Passing nothing resolves `globalThis.fetch` **per call** rather than binding it once, so a client constructed at module scope still picks up a fetch installed later — a mock in a test, a polyfill, or a service worker.
+
+The payer surface (`resolve`, `requestInvoice`, `pollVerify`) is plain request/response and works anywhere `fetch` exists, streaming or not.

package/dist/arkade.d.ts

@@ -0,0 +1,258 @@
+import { PaymentRail, RouteQuote, PaymentRequest, RouterPreferences, PaymentOption, ActivityResolver } from '@arkade-os/sdk';
+import { VerifyExpectation, LnurlClient, DomainCapabilities, PayRequest, PaymentPage, PaymentSyncStore, StoredPayment } from './index.js';
+
+declare const LNURL_ARKADE_RAIL = "lnurl-arkade";
+declare const LNURL_LIGHTNING_RAIL = "lnurl-lightning";
+/** What an lnurl rail records on its quote, under `meta.lnurl`. */
+interface LnurlQuoteMeta {
+    /** The LNURL or Lightning address the quote pays, as the payer entered it. */
+    target: string;
+    /** The inner rail that pays it. */
+    via: string;
+    verify?: string;
+    verifyBatch?: string;
+    /** What `verify` answers must be about: pass it as `pollVerify`'s `expect`. */
+    expect?: VerifyExpectation;
+}
+/** The lnurl meta of a quote, or undefined for a quote no lnurl rail made. */
+declare function lnurlQuoteMeta(quote: RouteQuote): LnurlQuoteMeta | undefined;
+interface LnurlRailDeps {
+    /** Payer surface only; needs no `baseUrl`. */
+    client: LnurlClient;
+    /** Pays the Arkade destination the callback returns — normally `arkRail()`. */
+    arkade: PaymentRail;
+    /** Pays the BOLT11 the callback returns — normally `solverLightningRail(...)`.
+     *  Omit it and no lightning rail is registered, rather than one that cannot pay. */
+    lightning?: PaymentRail;
+    comment?: string;
+    /** How long one target's payRequest is reused across `available()`/`quote()`. */
+    ttlMs?: number;
+}
+/**
+ * Both rails for one client, sharing one resolve.
+ *
+ * Returned together because the sharing is the point: `options()` calls
+ * `available()` on every matching rail, and separate factories would each
+ * fetch the same payRequest.
+ */
+declare function lnurlRails(deps: LnurlRailDeps): PaymentRail[];
+
+declare function arkadePaymentRouter(opts: {
+    wallet: LnurlWallet;
+    router?: LnurlPaymentRouter;
+    lightning?: PaymentRail;
+    client?: LnurlClient;
+    comment?: string;
+}): LnurlPaymentRouter;
+
+/** The wallet-shaped facade: what a receiver holding an `@arkade-os/sdk` wallet
+ *  would otherwise wire by hand. The low-level surface stays exported beneath it. */
+
+interface LnurlWallet {
+    readonly identity: ArkadeSigner;
+    getAddress(): Promise<string>;
+    getBoardingAddress(): Promise<string>;
+}
+interface LnurlPaymentRouter {
+    use(rail: PaymentRail): this;
+    remove(id: string): this;
+    options(req: PaymentRequest, prefs?: RouterPreferences): Promise<PaymentOption[]>;
+    route(req: PaymentRequest, prefs?: RouterPreferences): Promise<RouteQuote>;
+}
+/** The 1023 limit is LUD-01's, not bech32's default 90. */
+declare function encodeLnurl(url: string): string;
+/** A wallet supplies the signer and both addresses. Without one — a script, a
+ *  test, a server holding only a key — name them; only sending needs a wallet. */
+type ArkadeLnurlSource = {
+    wallet: LnurlWallet;
+    router?: LnurlPaymentRouter;
+    identity?: never;
+    arkadeAddress?: never;
+} | {
+    wallet?: never;
+    router?: never;
+    identity: ArkadeSigner;
+    arkadeAddress: string;
+    boardingAddress?: string;
+};
+type ArkadeLnurlOptions = ArkadeLnurlSource & ArkadeLnurlConfig;
+interface ArkadeLnurlConfig {
+    baseUrl: string;
+    /** Defaults to `baseUrl`'s hostname, as the server derives it: a LUD-16
+     *  domain cannot carry a port. */
+    domain?: string;
+    store?: PaymentSyncStore;
+    lightningRail?: PaymentRail;
+    client?: LnurlClient;
+}
+/** A claim code is checked only against the reserved name it unlocks, so it never travels alone. */
+type NameOptions = {
+    username?: string;
+    claimCode?: never;
+} | {
+    username: string;
+    claimCode: string;
+};
+/** `nameless` is mutually exclusive with `username`/`claimCode` at the type
+ *  level, matching the server's 400 `invalid_username` on combining them. */
+type ClaimOptions = (NameOptions & {
+    nameless?: never;
+}) | {
+    nameless: true;
+    username?: never;
+    claimCode?: never;
+};
+/** One claimed or listed address, holding everything scoped to it. */
+interface Receiver {
+    readonly handle: string;
+    /** `user@domain`; undefined for a nameless receiver. */
+    readonly lightningAddress: string | undefined;
+    /** For a QR. The session LNURL when flagged (survives {@link upgrade}), else `.well-known`. */
+    readonly lnurl: string;
+    /** Addressed through `baseUrl`, not the LUD-16 domain, which drops the port.
+     *  One fetch answers every call for 30 s, or until a write through this facade
+     *  (`claim`, `upgrade`); `resolve(lnurl)` always asks the server. */
+    payRequest(): Promise<PayRequest>;
+    payments(opts?: {
+        since?: number;
+        limit?: number;
+    }): Promise<PaymentPage>;
+    sync(): Promise<{
+        synced: number;
+        failures: unknown[];
+    }>;
+    /** Names a nameless receiver in place; everything handed out while nameless
+     *  keeps working. Does not re-bind the Arkade identity, already on the row. */
+    upgrade(opts?: NameOptions): Promise<Receiver>;
+}
+interface ArkadeLnurl {
+    /** Derived once; signs twice on the first call, nothing on later ones. */
+    token(): Promise<string>;
+    capabilities(): Promise<DomainCapabilities>;
+    /** Registers an address — named, random or nameless per `opts` — and binds
+     *  the identity. Until the bind lands the address advertises no
+     *  `paymentOptions` at all, so offline receive does not exist. */
+    claim(opts?: ClaimOptions): Promise<Receiver>;
+    owned(): Promise<Receiver | undefined>;
+    router(): LnurlPaymentRouter;
+    options(target: string, amountSat: number, prefs?: RouterPreferences): Promise<PaymentOption[]>;
+}
+/** Ordered so the Arkade leg outranks the Lightning one for the same address:
+ *  it delivers the full amount with no counterparty. */
+declare const DEFAULT_RAIL_PRIORITY: string[];
+declare function arkadeLnurl(opts: ArkadeLnurlOptions): ArkadeLnurl;
+
+/** Namespaced so it cannot clobber the SDK's own resolvers. */
+declare const LNURL_RESOLVER_ID = "lnurl:payments";
+declare const SENT_RESOLVER_ID = "lnurl:sends";
+declare const LNURL_GROUP_PREFIX = "lnurl:";
+declare const SENT_GROUP_PREFIX = "sent:";
+declare const railOf: (p: StoredPayment) => string;
+declare function absorbedPaymentKey(activityId: string): string | undefined;
+/** What a wallet knows about a payment it made. Nothing else does: the server
+ *  that recorded a send was the recipient's, so its record is theirs, not ours. */
+interface SentPayment {
+    /** Arkade txid — the join key to the wallet's own activity row. */
+    txid: string;
+    /** What the user typed: a Lightning address, an LNURL, or a bare address. */
+    target: string;
+    railId: string;
+    amountSat: number;
+    feeSat: number;
+    createdAt: number;
+    swapId?: string;
+    preimage?: string;
+    /** The LUD-21 verify URL and LUD-XX verifyBatch endpoint the quote carried, kept so a
+     *  confirmation still pending when the app closes can be resumed. */
+    verify?: string;
+    verifyBatch?: string;
+    /** Set once the receiver's LUD-21 verify answers, where a rail hands one out. */
+    receiverConfirmed?: boolean;
+}
+/** What to keep on file after a completed send: `incoming` replaces the record
+ *  sharing its txid, so a later verify result updates that row rather than
+ *  duplicating it. Storage — reading the existing set, writing the result — is
+ *  the caller's. */
+declare function mergeSentPayment(existing: SentPayment[], incoming: SentPayment): SentPayment[];
+/** Labels a payment this wallet MADE, from what it recorded at send time. Joined
+ *  on the rail's txid, never inferred from amount and timing as an incoming quote
+ *  may be: naming a recipient the money did not go to is worse than naming none. */
+declare function sentActivityResolver(sends: () => SentPayment[]): ActivityResolver;
+/** Joined on `payoutReference`, never `paymentReference`: the latter is what the
+ *  service observed, which on two of the three rails is an output this wallet
+ *  never holds. */
+declare function lnurlActivityResolver(payments: () => StoredPayment[]): ActivityResolver;
+
+/** The slice of `@arkade-os/sdk`'s `Identity` these helpers need. */
+interface ArkadeSigner {
+    signMessage(message: Uint8Array, signatureType: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    compressedPublicKey(): Promise<Uint8Array>;
+}
+/**
+ * True when `address` decodes as an Arkade address.
+ *
+ * The core package deliberately cannot do this — decoding needs the SDK — so
+ * without this helper a malformed address is only caught server-side, a round
+ * trip later.
+ *
+ * @param address - Bech32m Arkade address.
+ * @returns Whether it decodes.
+ */
+declare function isArkadeAddress(address: string): boolean;
+/**
+ * Derives the session token from an `Identity`, signing with ECDSA.
+ *
+ * Prefer this over calling {@link deriveSessionTokenWithSigner} yourself: it
+ * pins the signature type. Schnorr is `Identity.signMessage`'s default and is
+ * randomised without an explicit aux, which would mint a fresh token per call
+ * and orphan the address — and a schnorr signature is 64 bytes exactly like a
+ * compact ECDSA one, so nothing about the bytes reveals the mistake.
+ *
+ * Produces the same token as `deriveSessionToken(privateKeyHex, domain)`.
+ *
+ * **Signs twice**, inherited from {@link deriveSessionTokenWithSigner}, to
+ * prove the signer is deterministic before a token derived from it is used as
+ * an address's identity. Free for a software key; an `Identity` backed by a
+ * device that prompts will prompt twice, once per call. Derive once per domain
+ * and hold the result for the session rather than calling it per request.
+ *
+ * @param identity - Anything with `@arkade-os/sdk`'s `signMessage`.
+ * @param domain - The LUD-16 domain this token is for.
+ * @returns The session token as hex, valid only at that domain.
+ */
+declare function deriveSessionTokenForIdentity(identity: ArkadeSigner, domain: string): Promise<string>;
+/**
+ * The identity's compressed public key as hex — the `claimPublicKey` that
+ * `registerArkadeIdentity` wants, in the form the server validates.
+ *
+ * @param identity - Anything with `@arkade-os/sdk`'s `compressedPublicKey`.
+ * @returns 66-hex-char compressed key.
+ */
+declare function claimPublicKeyOf(identity: ArkadeSigner): Promise<string>;
+/**
+ * Builds the `registerArkadeIdentity` request from an `Identity`, validating the
+ * Arkade address before it reaches the wire.
+ *
+ * An optional `boardingAddress` registers the onchain rail in the same call,
+ * unchecked: it is a Bitcoin address on a network this helper cannot know.
+ *
+ * @param params - The identity, its Arkade address, the owning token and handle.
+ * @returns The request body to hand to `registerArkadeIdentity`.
+ */
+declare function arkadeIdentityRequest(params: {
+    identity: ArkadeSigner;
+    arkadeAddress: string;
+    token: string;
+    handle: string;
+    boardingAddress?: string;
+    domain?: string;
+}): Promise<{
+    token: string;
+    handle: string;
+    arkadeAddress: string;
+    claimPublicKey: string;
+    boardingAddress?: string;
+    domain?: string;
+}>;
+
+export { type ArkadeLnurl, type ArkadeLnurlConfig, type ArkadeLnurlOptions, type ArkadeLnurlSource, type ArkadeSigner, type ClaimOptions, DEFAULT_RAIL_PRIORITY, LNURL_ARKADE_RAIL, LNURL_GROUP_PREFIX, LNURL_LIGHTNING_RAIL, LNURL_RESOLVER_ID, type LnurlPaymentRouter, type LnurlQuoteMeta, type LnurlRailDeps, type LnurlWallet, type NameOptions, type Receiver, SENT_GROUP_PREFIX, SENT_RESOLVER_ID, type SentPayment, absorbedPaymentKey, arkadeIdentityRequest, arkadeLnurl, arkadePaymentRouter, claimPublicKeyOf, deriveSessionTokenForIdentity, encodeLnurl, isArkadeAddress, lnurlActivityResolver, lnurlQuoteMeta, lnurlRails, mergeSentPayment, railOf, sentActivityResolver };