@getalby/lightning-tools/dist/types/index.d.ts

Collection of helpful building blocks and tools to develop Bitcoin Lightning web apps

import * as _webbtc_webln_types from '@webbtc/webln-types';
import { WebLNProvider, SendPaymentResponse } from '@webbtc/webln-types';

type InvoiceArgs = {
    pr: string;
    verify?: string;
    preimage?: string;
    successAction?: SuccessAction;
};
type SuccessAction = {
    tag: "message";
    message: string;
} | {
    tag: "url";
    description: string;
    url: string;
};

declare const fromHexString: (hexString: string) => Uint8Array<ArrayBuffer>;
type DecodedInvoice = {
    paymentHash: string;
    satoshi: number;
    millisatoshi: number;
    amountRaw: string;
    timestamp: number;
    expiry: number | undefined;
    description: string | undefined;
};
declare const decodeInvoice: (paymentRequest: string) => DecodedInvoice | null;
declare function validatePreimage(preimage: string, paymentHash: string): boolean;

declare class Invoice {
    paymentRequest: string;
    paymentHash: string;
    preimage: string | null;
    verify: string | null;
    satoshi: number;
    millisatoshi: number;
    amountRaw: string;
    expiry: number | undefined;
    timestamp: number;
    createdDate: Date;
    expiryDate: Date | undefined;
    description: string | null;
    successAction: SuccessAction | null;
    constructor(args: InvoiceArgs);
    isPaid(): Promise<boolean>;
    validatePreimage(preimage: string): boolean;
    verifyPayment(): Promise<boolean>;
    hasExpired(): boolean;
}

type LnUrlRawData = {
    tag: string;
    callback: string;
    minSendable: number;
    maxSendable: number;
    metadata: string;
    payerData?: LUD18ServicePayerData;
    commentAllowed?: number;
    allowsNostr?: boolean;
};
type LnUrlPayResponse = {
    callback: string;
    fixed: boolean;
    min: number;
    max: number;
    domain?: string;
    metadata: Array<Array<string>>;
    metadataHash: string;
    identifier: string;
    email: string;
    description: string;
    image: string;
    commentAllowed?: number;
    rawData: LnUrlRawData;
    allowsNostr: boolean;
    payerData?: LUD18ServicePayerData;
};
type LUD18ServicePayerData = Partial<{
    name: {
        mandatory: boolean;
    };
    pubkey: {
        mandatory: boolean;
    };
    identifier: {
        mandatory: boolean;
    };
    email: {
        mandatory: boolean;
    };
    auth: {
        mandatory: boolean;
        k1: string;
    };
}> & Record<string, unknown>;
type LUD18PayerData = Partial<{
    name?: string;
    pubkey?: string;
    identifier?: string;
    email?: string;
    auth?: {
        key: string;
        sig: string;
    };
}> & Record<string, unknown>;
type NostrResponse = {
    names: Record<string, string>;
    relays: Record<string, string[]>;
};
type Event = {
    id?: string;
    kind: number;
    pubkey?: string;
    content: string;
    tags: string[][];
    created_at: number;
    sig?: string;
};
type ZapArgs = {
    satoshi: number;
    comment?: string;
    relays: string[];
    p?: string;
    e?: string;
};
type NostrProvider = {
    getPublicKey(): Promise<string>;
    signEvent(event: Event & {
        pubkey: string;
        id: string;
    }): Promise<Event>;
};
type ZapOptions = {
    nostr?: NostrProvider;
};
type RequestInvoiceArgs = {
    satoshi: number;
    comment?: string;
    payerdata?: LUD18PayerData;
};
type KeysendResponse = {
    customKey: string;
    customValue: string;
    destination: string;
};
type KeySendRawData = {
    tag: string;
    status: string;
    customData?: {
        customKey?: string;
        customValue?: string;
    }[];
    pubkey: string;
};

declare const parseKeysendResponse: (data: KeySendRawData) => KeysendResponse;
declare function generateZapEvent({ satoshi, comment, p, e, relays }: ZapArgs, options?: ZapOptions): Promise<Event>;
declare function validateEvent(event: Event): boolean;
declare function serializeEvent(evt: Event): string;
declare function getEventHash(event: Event): string;
declare function parseNostrResponse(nostrData: NostrResponse, username: string | undefined): readonly [NostrResponse, string | undefined, string[] | undefined];
declare const isUrl: (url: string | null) => url is string;
declare const isValidAmount: ({ amount, min, max, }: {
    amount: number;
    min: number;
    max: number;
}) => boolean;
declare const parseLnUrlPayResponse: (data: LnUrlRawData) => Promise<LnUrlPayResponse>;

type BoostOptions = {
    webln?: unknown;
};
type BoostArguments = {
    destination: string;
    customKey?: string;
    customValue?: string;
    amount?: number;
    boost: Boost;
};
type WeblnBoostParams = {
    destination: string;
    amount: number;
    customRecords: Record<string, string>;
};
type Boost = {
    action: string;
    value_msat: number;
    value_msat_total: number;
    app_name: string;
    app_version: string;
    feedId: string;
    podcast: string;
    episode: string;
    ts: number;
    name: string;
    sender_name: string;
};

declare const sendBoostagram: (args: BoostArguments, options?: BoostOptions) => Promise<_webbtc_webln_types.SendPaymentResponse>;

declare const LN_ADDRESS_REGEX: RegExp;
declare const DEFAULT_PROXY = "https://api.getalby.com/lnurl";
type LightningAddressOptions = {
    proxy?: string | false;
    webln?: WebLNProvider;
};
declare class LightningAddress {
    address: string;
    options: LightningAddressOptions;
    username: string | undefined;
    domain: string | undefined;
    pubkey: string | undefined;
    lnurlpData: LnUrlPayResponse | undefined;
    keysendData: KeysendResponse | undefined;
    nostrData: NostrResponse | undefined;
    nostrPubkey: string | undefined;
    nostrRelays: string[] | undefined;
    webln: WebLNProvider | undefined;
    constructor(address: string, options?: LightningAddressOptions);
    parse(): void;
    getWebLN(): any;
    fetch(): Promise<void>;
    fetchWithProxy(): Promise<void>;
    fetchWithoutProxy(): Promise<void>;
    fetchLnurlData(): Promise<void>;
    fetchKeysendData(): Promise<void>;
    fetchNostrData(): Promise<void>;
    lnurlpUrl(): string;
    keysendUrl(): string;
    nostrUrl(): string;
    generateInvoice(params: Record<string, string>): Promise<Invoice>;
    requestInvoice(args: RequestInvoiceArgs): Promise<Invoice>;
    boost(boost: Boost, amount?: number): Promise<SendPaymentResponse>;
    zapInvoice({ satoshi, comment, relays, e }: ZapArgs, options?: ZapOptions): Promise<Invoice>;
    zap(args: ZapArgs, options?: ZapOptions): Promise<SendPaymentResponse>;
    private parseLnUrlPayResponse;
    private parseKeysendResponse;
    private parseNostrResponse;
}

interface Wallet {
    payInvoice(args: {
        invoice: string;
    }): Promise<{
        preimage: string;
    }>;
}
declare function createGuardedWallet(wallet: Wallet, maxAmountSats: number): Wallet;

declare const fetch402: (url: string, fetchArgs: RequestInit, options: {
    wallet: Wallet;
    maxAmount?: number;
}) => Promise<Response>;

declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options: {
    wallet: Wallet;
}) => Promise<Response>;

interface WwwAuthenticatePayload {
    token: string;
    invoice: string;
    [key: string]: string;
}
/**
 * Client: parse "www-authenticate" header from server response
 * @param input
 * @returns details from the header value (token or macaroon, invoice)
 */
declare const parseL402: (input: string) => WwwAuthenticatePayload;

type MacaroonPayload<T> = T & {
    paymentHash: string;
};
declare function issueL402Macaroon<T extends Record<string, unknown>>(secret: string, paymentHash: string, params?: T): Promise<string>;
declare function verifyL402Macaroon<T = unknown>(secret: string, token: string): Promise<MacaroonPayload<T>>;

/**
 * Server: create a WWW-Authenticate header for a given macaroon and invoice
 * @param args the macaroon/token and invoice generated for the client's request
 * @returns the header value
 */
declare const makeL402AuthenticateHeader: (args: {
    token?: string;
    invoice: string;
}) => string;
/**
 * Server: parse "authorization" header sent from client
 * @param input value from authorization header
 * @returns the macaroon and preimage
 */
declare function parseL402Authorization(input: string): {
    token: string;
    preimage: string;
} | null;

interface X402Requirements {
    scheme: string;
    network: string;
    extra: {
        invoice: string;
        paymentMethod?: string;
        [key: string]: unknown;
    };
    [key: string]: unknown;
}

/**
 * Probe a PAYMENT-REQUIRED header for a lightning-payable offer without
 * throwing. Returns the matching requirements, or null if the header has no
 * lightning entry (e.g. USDC-only endpoints) or is malformed. Used by the
 * top-level fetch402 dispatcher to decide whether to attempt payment or hand
 * the 402 back to the caller.
 */
declare const findX402LightningRequirements: (x402Header: string) => X402Requirements | null;
declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: {
    wallet: Wallet;
}) => Promise<Response>;

/**
 * Fetch a resource protected by the draft-lightning-charge-00 payment
 * authentication protocol.
 *
 * On a `402 Payment Required` response that carries a
 * `WWW-Authenticate: Payment method="lightning" intent="charge" …` header
 * the function pays the embedded BOLT11 invoice and retries with the
 * resulting preimage as the credential.
 *
 * Note: lightning-charge uses consume-once challenge semantics – each
 * challenge embeds a fresh invoice, so paid credentials cannot be reused.
 * The `store` option is accepted for API consistency but is not used.
 */
declare const fetchWithMpp: (url: string, fetchArgs: RequestInit, options: {
    wallet: Wallet;
}) => Promise<Response>;

interface FiatCurrency {
    code: string;
    name: string;
    symbol: string;
    priority: number;
}
declare const getFiatCurrencies: () => Promise<FiatCurrency[]>;
declare const getFiatBtcRate: (currency: string) => Promise<number>;
declare const getFiatValue: ({ satoshi, currency, }: {
    satoshi: number | string;
    currency: string;
}) => Promise<number>;
declare const getSatoshiValue: ({ amount, currency, }: {
    amount: number | string;
    currency: string;
}) => Promise<number>;
declare const getFormattedFiatValue: ({ satoshi, currency, locale, }: {
    satoshi: number | string;
    currency: string;
    locale: string;
}) => Promise<string>;

export { DEFAULT_PROXY, Invoice, LN_ADDRESS_REGEX, LightningAddress, createGuardedWallet, decodeInvoice, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, findX402LightningRequirements, fromHexString, generateZapEvent, getEventHash, getFiatBtcRate, getFiatCurrencies, getFiatValue, getFormattedFiatValue, getSatoshiValue, isUrl, isValidAmount, issueL402Macaroon, makeL402AuthenticateHeader, parseKeysendResponse, parseL402, parseL402Authorization, parseLnUrlPayResponse, parseNostrResponse, sendBoostagram, serializeEvent, validateEvent, validatePreimage, verifyL402Macaroon };
export type { Boost, BoostArguments, BoostOptions, Event, FiatCurrency, InvoiceArgs, KeySendRawData, KeysendResponse, LUD18PayerData, LUD18ServicePayerData, LnUrlPayResponse, LnUrlRawData, MacaroonPayload, NostrProvider, NostrResponse, RequestInvoiceArgs, SuccessAction, Wallet, WeblnBoostParams, ZapArgs, ZapOptions };