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

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

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>;

export { createGuardedWallet, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, findX402LightningRequirements, issueL402Macaroon, makeL402AuthenticateHeader, parseL402, parseL402Authorization, verifyL402Macaroon };
export type { MacaroonPayload, Wallet };