@bsv/message-box-client/dist/types/src/PeerPayClient.d.ts

A client for P2P messaging and payments

/**
 * PeerPayClient
 *
 * Extends `MessageBoxClient` to enable Bitcoin payments using the MetaNet identity system.
 *
 * This client handles payment token creation, message transmission over HTTP/WebSocket,
 * payment reception (including acceptance and rejection logic), and listing of pending payments.
 *
 * It uses authenticated and encrypted message transmission to ensure secure payment flows
 * between identified peers on the BSV network.
 */
import { MessageBoxClient } from './MessageBoxClient.js';
import { WalletInterface, AtomicBEEF, Base64String, OriginatorDomainNameStringUnder250Bytes } from '@bsv/sdk';
export declare const STANDARD_PAYMENT_MESSAGEBOX = "payment_inbox";
/**
 * Configuration options for initializing PeerPayClient.
 */
export interface PeerPayClientConfig {
    messageBoxHost?: string;
    walletClient: WalletInterface;
    enableLogging?: boolean;
    originator?: OriginatorDomainNameStringUnder250Bytes;
}
/**
 * Represents the parameters required to initiate a payment.
 */
export interface PaymentParams {
    recipient: string;
    amount: number;
}
/**
 * Represents a structured payment token.
 */
export interface PaymentToken {
    customInstructions: {
        derivationPrefix: Base64String;
        derivationSuffix: Base64String;
    };
    transaction: AtomicBEEF;
    amount: number;
}
/**
 * Represents an incoming payment received via MessageBox.
 */
export interface IncomingPayment {
    messageId: string;
    sender: string;
    token: PaymentToken;
}
/**
 * PeerPayClient enables peer-to-peer Bitcoin payments using MessageBox.
 */
export declare class PeerPayClient extends MessageBoxClient {
    private readonly peerPayWalletClient;
    private _authFetchInstance?;
    constructor(config: PeerPayClientConfig);
    private get authFetchInstance();
    /**
     * Generates a valid payment token for a recipient.
     *
     * This function derives a unique public key for the recipient, constructs a P2PKH locking script,
     * and creates a payment action with the specified amount.
     *
     * @param {PaymentParams} payment - The payment details.
     * @param {string} payment.recipient - The recipient's identity key.
     * @param {number} payment.amount - The amount in satoshis to send.
     * @returns {Promise<PaymentToken>} A valid payment token containing transaction details.
     * @throws {Error} If the recipient's public key cannot be derived.
     */
    createPaymentToken(payment: PaymentParams): Promise<PaymentToken>;
    /**
     * Sends Bitcoin to a PeerPay recipient.
     *
     * This function validates the payment details and delegates the transaction
     * to `sendLivePayment` for processing.
     *
     * @param {PaymentParams} payment - The payment details.
     * @param {string} payment.recipient - The recipient's identity key.
     * @param {number} payment.amount - The amount in satoshis to send.
     * @param {string} [hostOverride] - Optional host override for the message box server.
     * @returns {Promise<any>} Resolves with the payment result.
     * @throws {Error} If the recipient is missing or the amount is invalid.
     */
    sendPayment(payment: PaymentParams, hostOverride?: string): Promise<any>;
    /**
     * Sends Bitcoin to a PeerPay recipient over WebSockets.
     *
     * This function generates a payment token and transmits it over WebSockets
     * using `sendLiveMessage`. The recipient's identity key is explicitly included
     * to ensure proper message routing.
     *
     * @param {PaymentParams} payment - The payment details.
     * @param {string} payment.recipient - The recipient's identity key.
     * @param {number} payment.amount - The amount in satoshis to send.
     * @param {string} [overrideHost] - Optional host override for WebSocket connection.
     * @returns {Promise<void>} Resolves when the payment has been sent.
     * @throws {Error} If payment token generation fails.
     */
    sendLivePayment(payment: PaymentParams, overrideHost?: string): Promise<void>;
    /**
     * Listens for incoming Bitcoin payments over WebSockets.
     *
     * This function listens for messages in the standard payment message box and
     * converts incoming `PeerMessage` objects into `IncomingPayment` objects
     * before invoking the `onPayment` callback.
     *
     * @param {Object} obj - The configuration object.
     * @param {Function} obj.onPayment - Callback function triggered when a payment is received.
     * @param {string} [obj.overrideHost] - Optional host override for WebSocket connection.
     * @returns {Promise<void>} Resolves when the listener is successfully set up.
     */
    listenForLivePayments({ onPayment, overrideHost, }: {
        onPayment: (payment: IncomingPayment) => void;
        overrideHost?: string;
    }): Promise<void>;
    /**
     * Accepts an incoming Bitcoin payment and moves it into the default wallet basket.
     *
     * This function processes a received payment by submitting it for internalization
     * using the wallet client's `internalizeAction` method. The payment details
     * are extracted from the `IncomingPayment` object.
     *
     * @param {IncomingPayment} payment - The payment object containing transaction details.
     * @returns {Promise<any>} Resolves with the payment result if successful.
     * @throws {Error} If payment processing fails.
     */
    acceptPayment(payment: IncomingPayment): Promise<any>;
    /**
     * Rejects an incoming Bitcoin payment by refunding it to the sender, minus a fee.
     *
     * If the payment amount is too small (less than 1000 satoshis after deducting the fee),
     * the payment is simply acknowledged and ignored. Otherwise, the function first accepts
     * the payment, then sends a new transaction refunding the sender.
     *
     * @param {IncomingPayment} payment - The payment object containing transaction details.
     * @returns {Promise<void>} Resolves when the payment is either acknowledged or refunded.
     */
    rejectPayment(payment: IncomingPayment): Promise<void>;
    /**
     * Retrieves a list of incoming Bitcoin payments from the message box.
     *
     * This function queries the message box for new messages and transforms
     * them into `IncomingPayment` objects by extracting relevant fields.
     *
     * @param {string} [overrideHost] - Optional host override to list payments from
     * @returns {Promise<IncomingPayment[]>} Resolves with an array of pending payments.
     */
    listIncomingPayments(overrideHost?: string): Promise<IncomingPayment[]>;
}
//# sourceMappingURL=PeerPayClient.d.ts.map