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

package/dist/arkade.d.ts

@@ -0,0 +1,333 @@
+import { U as UnitAmount, V as VerifyExpectation, Q as QuotedAmount, D as DomainCapabilities, P as PayRequest, a as PaymentPage, H as HdReceiveAllocationPage, b as HdReceiveConfig } from './addresses-CPAzIbJ_.js';
+export { c as HdReceiveAllocation } from './addresses-CPAzIbJ_.js';
+import { PaymentRequest, PaymentRail, RouteQuote, RouterPreferences, PaymentOption, ActivityResolver, PaymentHandle } from '@arkade-os/sdk';
+import { LnurlClient, PaymentSyncStore, StoredPayment, PendingConfirmations } 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;
+    /** What was asked for in a unit, when the payment was priced in one. */
+    quote?: QuotedAmount;
+}
+/** The SDK's request, plus an amount in one of the target's `units` instead of sats.
+ *  The router hands every rail the same object, so only the lnurl rails read it. */
+type LnurlPaymentRequest = PaymentRequest & {
+    unitAmount?: UnitAmount;
+};
+/** 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: LnurlPaymentRequest, prefs?: RouterPreferences): Promise<PaymentOption[]>;
+    route(req: LnurlPaymentRequest, 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;
+    hd?: HdReceiveConfig;
+} | {
+    wallet?: never;
+    router?: never;
+    identity: ArkadeSigner;
+    arkadeAddress: string;
+    boardingAddress?: string;
+    hd?: never;
+} | {
+    wallet?: never;
+    router?: never;
+    identity: ArkadeSigner;
+    hd: HdReceiveConfig;
+    arkadeAddress?: never;
+    boardingAddress?: never;
+};
+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>;
+    allocations(opts?: {
+        after?: number;
+        limit?: number;
+    }): Promise<HdReceiveAllocationPage>;
+    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;
+    /** `amount` is sats, or an amount in one of the target's `units`, e.g. `{ unit: "USD", amount: 500 }`. */
+    options(target: string, amount: number | UnitAmount, 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;
+
+/** "5.00 USD": how a quoted amount reads in an activity row. */
+declare const quotedLabel: (q: QuotedAmount) => string;
+/** 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;
+    expect?: VerifyExpectation;
+    /** Set once the receiver's LUD-21 verify answers, where a rail hands one out. */
+    receiverConfirmed?: boolean;
+    /** What the payer asked to pay in a LUD-XX unit; absent when they paid in sats. */
+    quote?: QuotedAmount;
+}
+/** 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;
+
+interface LnurlSentPaymentStore {
+    read(): SentPayment[];
+    write(records: SentPayment[]): void;
+}
+interface LnurlSendTrackerOptions {
+    onError(error: unknown): void;
+    confirmations?: PendingConfirmations;
+}
+interface LnurlSendTracker {
+    all(): SentPayment[];
+    record(handle: PaymentHandle, quote: RouteQuote, target: string): () => void;
+    watch(txid: string, verify: string, verifyBatch?: string, startedAt?: number, expect?: VerifyExpectation): void;
+    resume(): void;
+    mark(txid: string, confirmed: boolean): void;
+    forget(): void;
+}
+/** Shared send bookkeeping over the application's synchronous persistence. */
+declare function createLnurlSendTracker(store: LnurlSentPaymentStore, options: LnurlSendTrackerOptions): LnurlSendTracker;
+
+type LnurlRailType = "lightning" | "arkade" | "onchain";
+declare function lnurlRailLimits(payRequest: PayRequest): {
+    type: string;
+    min: number;
+    max: number;
+}[];
+declare function resolveLnurlRails(receiver: Pick<Receiver, "payRequest">, amountSat: number, rails: readonly LnurlRailType[], own: {
+    arkade: string;
+    onchain: string;
+}, client?: Pick<LnurlClient, "requestInvoice">): Promise<PromiseSettledResult<string>[]>;
+
+interface ReceiverBootstrapOptions {
+    /** Discovery does not allocate a receiver unless explicitly enabled. */
+    autoClaimNameless?: boolean;
+}
+type ReceiverBootstrapResult = {
+    kind: "ready";
+    receiver: Receiver;
+    claimed: boolean;
+    capabilities?: DomainCapabilities;
+    capabilitiesError?: unknown;
+} | {
+    kind: "onboarding";
+    capabilities: DomainCapabilities;
+};
+declare function bootstrapReceiver(facade: Pick<ArkadeLnurl, "owned" | "capabilities" | "claim">, opts?: ReceiverBootstrapOptions): Promise<ReceiverBootstrapResult>;
+declare function claimOrAdopt(facade: Pick<ArkadeLnurl, "owned" | "claim">, opts?: ClaimOptions): Promise<Receiver>;
+
+/** 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, HdReceiveAllocationPage, HdReceiveConfig, LNURL_ARKADE_RAIL, LNURL_GROUP_PREFIX, LNURL_LIGHTNING_RAIL, LNURL_RESOLVER_ID, type LnurlPaymentRequest, type LnurlPaymentRouter, type LnurlQuoteMeta, type LnurlRailDeps, type LnurlRailType, type LnurlSendTracker, type LnurlSendTrackerOptions, type LnurlSentPaymentStore, type LnurlWallet, type NameOptions, type Receiver, type ReceiverBootstrapOptions, type ReceiverBootstrapResult, SENT_GROUP_PREFIX, SENT_RESOLVER_ID, type SentPayment, absorbedPaymentKey, arkadeIdentityRequest, arkadeLnurl, arkadePaymentRouter, bootstrapReceiver, claimOrAdopt, claimPublicKeyOf, createLnurlSendTracker, deriveSessionTokenForIdentity, encodeLnurl, isArkadeAddress, lnurlActivityResolver, lnurlQuoteMeta, lnurlRailLimits, lnurlRails, mergeSentPayment, quotedLabel, railOf, resolveLnurlRails, sentActivityResolver };