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

package/dist/addresses-CPAzIbJ_.d.ts

@@ -0,0 +1,514 @@
+/**
+ * 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;
+    /** Smallest quotable amount, in the unit's smallest denomination (an integer string). */
+    minAmount?: string;
+    /** Largest quotable amount, in the unit's smallest denomination (an integer string). */
+    maxAmount?: string;
+}
+/** An amount in one of a payRequest's `units`: `amount` is in that unit's smallest denomination. */
+interface UnitAmount {
+    unit: string;
+    amount: number;
+}
+/** What a payment was asked for in a unit, as recorded with it: `amount` in the
+ *  unit's smallest denomination, `decimals` to read it ("500", 2 is 5.00). */
+interface QuotedAmount {
+    amount: string;
+    unit: string;
+    decimals: number;
+}
+/** An amount paired with the unit it is denominated in. */
+interface AmountObject {
+    /** Integer string in the smallest denomination of `unit` (cents for USD, millisats for `msat`). */
+    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: an
+ * amount in sats, or (lightning rail only) an amount in one of the payRequest's
+ * `units`, which the receiver quotes to millisats.
+ */
+type RequestInvoiceOptions = {
+    /** Optional payer comment, sent when the payRequest allows one. */
+    comment?: string;
+    paymentOption?: string;
+} & ({
+    /** Amount to pay in sats; converted to millisats on the wire. */
+    amountSat: number;
+    unit?: undefined;
+    amount?: undefined;
+} | {
+    /** A `units[]` code, e.g. `USD`. */
+    unit: string;
+    /** In the unit's smallest denomination: `500` is $5.00 in a 2-decimal USD. */
+    amount: number;
+    amountSat?: undefined;
+});
+/**
+ * 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;
+    /** What the payer asked to pay in a LUD-XX unit; absent when they paid in sats. */
+    quote?: QuotedAmount;
+}
+/**
+ * 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;
+    /** What the payer asked to pay in a LUD-XX unit; absent when they paid in sats. */
+    quote?: QuotedAmount;
+}
+
+interface HdReceiveConfig {
+    version: 1;
+    descriptor: string;
+    serverPubKey: string;
+    hrp: "ark" | "tark";
+    exitDelay: {
+        type: "seconds" | "blocks";
+        value: number;
+    };
+}
+interface HdReceiveAllocation {
+    id: number;
+    index: number;
+    descriptor: string;
+    arkadeAddress: string;
+    claimPublicKey: string;
+    hd: HdReceiveConfig;
+    createdAt: number;
+}
+interface HdReceiveAllocationPage {
+    allocations: HdReceiveAllocation[];
+    nextAfter: number;
+}
+/**
+ * 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.
+ */
+type RegisterArkadeIdentityRequest = {
+    /** Token owning the address; sent as the Bearer credential. */
+    token: string;
+    /** Handle of the already-registered address. */
+    handle: string;
+    domain?: 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;
+    hd?: never;
+} | {
+    hd: HdReceiveConfig;
+    arkadeAddress?: never;
+    claimPublicKey?: never;
+    boardingAddress?: never;
+});
+/**
+ * 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>;
+declare function listHdAllocations(baseUrl: string, token: string, handle: string, opts: {
+    domain?: string;
+    after?: number;
+    limit?: number;
+} | undefined, fetchImpl: FetchImpl): Promise<HdReceiveAllocationPage>;
+
+export { type AddressListEntry as A, type Bolt11Activity as B, type DomainCapabilities as D, type FetchImpl as F, type HdReceiveAllocationPage as H, type InvoiceResult as I, type PayRequest as P, type QuotedAmount as Q, type RequestInvoiceOptions as R, type UnitAmount as U, type VerifyExpectation as V, type PaymentPage as a, type HdReceiveConfig as b, type HdReceiveAllocation as c, type PollVerifyOptions as d, type VerifyStatus as e, type DestinationResult as f, type RegisterAddressRequest as g, type RegisteredAddress as h, type RegisterArkadeIdentityRequest as i, type AmountObject as j, type Bolt11Result as k, type Bolt11VerifyStatus as l, type DestinationActivity as m, type DestinationVerifyStatus as n, type PaymentActivity as o, type PaymentOption as p, type PaymentQuote as q, type Unit as r, domainCapabilities as s, listAddresses as t, listHdAllocations as u, listPayments as v, registerAddress as w, registerArkadeIdentity as x, revokeAddress as y, upgradeAddress as z };