@bsv/message-box-client 1.1.7 → 1.1.8

package/dist/types/src/MessageBoxClient.d.ts

@@ -0,0 +1,441 @@
+/**
+ * @file MessageBoxClient.ts
+ * @description
+ * Provides the `MessageBoxClient` class — a secure client library for sending and receiving messages
+ * via a Message Box Server over HTTP and WebSocket. Messages are authenticated, optionally encrypted,
+ * and routed using identity-based addressing based on BRC-2/BRC-42/BRC-43 protocols.
+ *
+ * Core Features:
+ * - Authenticated message transport using identity keys
+ * - Deterministic message ID generation via HMAC (BRC-2)
+ * - AES-256-GCM encryption using ECDH shared secrets derived via BRC-42/BRC-43
+ * - Support for sending messages to self (`counterparty: 'self'`)
+ * - Live message streaming using WebSocket rooms
+ * - Optional plaintext messaging with `skipEncryption`
+ * - Overlay host discovery and advertisement broadcasting via SHIP
+ * - MessageBox-based organization and acknowledgment system
+ *
+ * See BRC-2 for details on the encryption scheme: https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0002.md
+ *
+ * @module MessageBoxClient
+ * @author Project Babbage
+ * @license Open BSV License
+ */
+import { AuthFetch, BEEF, LockingScript, HexString } from '@bsv/sdk';
+import { AuthSocketClient } from '@bsv/authsocket-client';
+import { AcknowledgeMessageParams, ListMessagesParams, MessageBoxClientOptions, PeerMessage, SendMessageParams, SendMessageResponse } from './types.js';
+interface AdvertisementToken {
+    host: string;
+    txid: HexString;
+    outputIndex: number;
+    lockingScript: LockingScript;
+    beef: BEEF;
+}
+/**
+ * @class MessageBoxClient
+ * @description
+ * A secure client for sending and receiving authenticated, encrypted messages
+ * through a MessageBox server over HTTP and WebSocket.
+ *
+ * Core Features:
+ * - Identity-authenticated message transport (BRC-2)
+ * - AES-256-GCM end-to-end encryption with BRC-42/BRC-43 key derivation
+ * - HMAC-based message ID generation for deduplication
+ * - Live WebSocket messaging with room-based subscription management
+ * - Overlay network discovery and host advertisement broadcasting (SHIP protocol)
+ * - Fallback to HTTP messaging when WebSocket is unavailable
+ *
+ * **Important:**
+ * The MessageBoxClient automatically calls `await init()` if needed.
+ * Manual initialization is optional but still supported.
+ *
+ * You may call `await init()` manually for explicit control, but you can also use methods
+ * like `sendMessage()` or `listenForLiveMessages()` directly — the client will initialize itself
+ * automatically if not yet ready.
+ *
+ * @example
+ * const client = new MessageBoxClient({ walletClient, enableLogging: true })
+ * await client.init() // <- Required before using the client
+ * await client.sendMessage({ recipient, messageBox: 'payment_inbox', body: 'Hello world' })
+ */
+export declare class MessageBoxClient {
+    private host;
+    readonly authFetch: AuthFetch;
+    private readonly walletClient;
+    private socket?;
+    private myIdentityKey?;
+    private readonly joinedRooms;
+    private readonly lookupResolver;
+    private readonly networkPreset;
+    private initialized;
+    /**
+     * @constructor
+     * @param {Object} options - Initialization options for the MessageBoxClient.
+     * @param {string} [options.host] - The base URL of the MessageBox server. If omitted, defaults to mainnet/testnet hosts.
+     * @param {WalletClient} options.walletClient - Wallet instance used for authentication, signing, and encryption.
+     * @param {boolean} [options.enableLogging=false] - Whether to enable detailed debug logging to the console.
+     * @param {'local' | 'mainnet' | 'testnet'} [options.networkPreset='mainnet'] - Overlay network preset used for routing and advertisement lookup.
+     *
+     * @description
+     * Constructs a new MessageBoxClient.
+     *
+     * **Note:**
+     * Passing a `host` during construction sets the default server.
+     * If you do not manually call `await init()`, the client will automatically initialize itself on first use.
+     *
+     * @example
+     * const client = new MessageBoxClient({
+     *   host: 'https://messagebox.example',
+     *   walletClient,
+     *   enableLogging: true,
+     *   networkPreset: 'testnet'
+     * })
+     * await client.init()
+     */
+    constructor(options?: MessageBoxClientOptions);
+    /**
+     * @method init
+     * @async
+     * @param {string} [targetHost] - Optional host to set or override the default host.
+     * @returns {Promise<void>}
+     *
+     * @description
+     * Initializes the MessageBoxClient by setting or anointing a MessageBox host.
+     *
+     * - If the client was constructed with a host, it uses that unless a different targetHost is provided.
+     * - If no prior advertisement exists for the identity key and host, it automatically broadcasts a new advertisement.
+     * - After calling init(), the client becomes ready to send, receive, and acknowledge messages.
+     *
+     * This method can be called manually for explicit control,
+     * but will be automatically invoked if omitted.
+     * @throws {Error} If no valid host is provided, or anointing fails.
+     *
+     * @example
+     * const client = new MessageBoxClient({ host: 'https://mybox.example', walletClient })
+     * await client.init()
+     * await client.sendMessage({ recipient, messageBox: 'inbox', body: 'Hello' })
+     */
+    init(targetHost?: string): Promise<void>;
+    /**
+     * @method assertInitialized
+     * @private
+     * @description
+     * Ensures that the MessageBoxClient has completed initialization before performing sensitive operations
+     * like sending, receiving, or acknowledging messages.
+     *
+     * If the client is not yet initialized, it will automatically call `await init()` to complete setup.
+     *
+     * Used automatically by all public methods that require initialization.
+     */
+    private assertInitialized;
+    /**
+     * @method getJoinedRooms
+     * @returns {Set<string>} A set of currently joined WebSocket room IDs
+     * @description
+     * Returns a live list of WebSocket rooms the client is subscribed to.
+     * Useful for inspecting state or ensuring no duplicates are joined.
+     */
+    getJoinedRooms(): Set<string>;
+    /**
+   * @method getIdentityKey
+   * @returns {Promise<string>} The identity public key of the user
+   * @description
+   * Returns the client's identity key, used for signing, encryption, and addressing.
+   * If not already loaded, it will fetch and cache it.
+   */
+    getIdentityKey(): Promise<string>;
+    /**
+     * @property testSocket
+     * @readonly
+     * @returns {AuthSocketClient | undefined} The internal WebSocket client (or undefined if not connected).
+     * @description
+     * Exposes the underlying Authenticated WebSocket client used for live messaging.
+     * This is primarily intended for debugging, test frameworks, or direct inspection.
+     *
+     * Note: Do not interact with the socket directly unless necessary.
+     * Use the provided `sendLiveMessage`, `listenForLiveMessages`, and related methods.
+     */
+    get testSocket(): ReturnType<typeof AuthSocketClient> | undefined;
+    /**
+     * @method initializeConnection
+     * @async
+     * @returns {Promise<void>}
+     * @description
+     * Establishes an authenticated WebSocket connection to the configured MessageBox server.
+     * Enables live message streaming via room-based channels tied to identity keys.
+     *
+     * This method:
+     * 1. Retrieves the user’s identity key if not already set
+     * 2. Initializes a secure AuthSocketClient WebSocket connection
+     * 3. Authenticates the connection using the identity key
+     * 4. Waits up to 5 seconds for authentication confirmation
+     *
+     * If authentication fails or times out, the connection is rejected.
+     *
+     * @throws {Error} If the identity key is unavailable or authentication fails
+     *
+     * @example
+     * const mb = new MessageBoxClient({ walletClient })
+     * await mb.initializeConnection()
+     * // WebSocket is now ready for use
+     */
+    initializeConnection(): Promise<void>;
+    /**
+     * @method resolveHostForRecipient
+     * @async
+     * @param {string} identityKey - The public identity key of the intended recipient.
+     * @returns {Promise<string>} - A fully qualified host URL for the recipient's MessageBox server.
+     *
+     * @description
+     * Attempts to resolve the most recently anointed MessageBox host for the given identity key
+     * using the BSV overlay network and the `ls_messagebox` LookupResolver.
+     *
+     * If no advertisements are found, or if resolution fails, the client will fall back
+     * to its own configured `host`. This allows seamless operation in both overlay and non-overlay environments.
+     *
+     * This method guarantees a non-null return value and should be used directly when routing messages.
+     *
+     * @example
+     * const host = await resolveHostForRecipient('028d...') // → returns either overlay host or this.host
+     */
+    resolveHostForRecipient(identityKey: string): Promise<string>;
+    /**
+     * Core lookup: ask the LookupResolver (optionally filtered by host),
+     * decode every PushDrop output, and collect all the host URLs you find.
+     *
+     * @param identityKey  the recipient’s public key
+     * @param host?        if passed, only look for adverts anointed at that host
+     * @returns            0-length array if nothing valid was found
+     */
+    queryAdvertisements(identityKey?: string, host?: string): Promise<AdvertisementToken[]>;
+    /**
+     * @method joinRoom
+     * @async
+     * @param {string} messageBox - The name of the WebSocket room to join (e.g., "payment_inbox").
+     * @returns {Promise<void>}
+     *
+     * @description
+     * Joins a WebSocket room that corresponds to the user’s identity key and the specified message box.
+     * This is required to receive real-time messages via WebSocket for a specific type of communication.
+     *
+     * If the WebSocket connection is not already established, this method will first initialize the connection.
+     * It also ensures the room is only joined once, and tracks all joined rooms in an internal set.
+     *
+     * Room ID format: `${identityKey}-${messageBox}`
+     *
+     * @example
+     * await client.joinRoom('payment_inbox')
+     * // Now listening for real-time messages in room '028d...-payment_inbox'
+     */
+    joinRoom(messageBox: string): Promise<void>;
+    /**
+     * @method listenForLiveMessages
+     * @async
+     * @param {Object} params - Configuration for the live message listener.
+     * @param {function} params.onMessage - A callback function that will be triggered when a new message arrives.
+     * @param {string} params.messageBox - The messageBox name (e.g., `payment_inbox`) to listen for.
+     * @returns {Promise<void>}
+     *
+     * @description
+     * Subscribes the client to live messages over WebSocket for a specific messageBox.
+     *
+     * This method:
+     * - Ensures the WebSocket connection is initialized and authenticated.
+     * - Joins the correct room formatted as `${identityKey}-${messageBox}`.
+     * - Listens for messages broadcast to the room.
+     * - Automatically attempts to parse and decrypt message bodies.
+     * - Emits the final message (as a `PeerMessage`) to the supplied `onMessage` handler.
+     *
+     * If the incoming message is encrypted, the client decrypts it using AES-256-GCM via
+     * ECDH shared secrets derived from identity keys as defined in [BRC-2](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0002.md).
+     * Messages sent by the client to itself are decrypted using `counterparty = 'self'`.
+     *
+     * @example
+     * await client.listenForLiveMessages({
+     *   messageBox: 'payment_inbox',
+     *   onMessage: (msg) => console.log('Received live message:', msg)
+     * })
+     */
+    listenForLiveMessages({ onMessage, messageBox }: {
+        onMessage: (message: PeerMessage) => void;
+        messageBox: string;
+    }): Promise<void>;
+    /**
+     * @method sendLiveMessage
+     * @async
+     * @param {SendMessageParams} param0 - The message parameters including recipient, box name, body, and options.
+     * @returns {Promise<SendMessageResponse>} A success response with the generated messageId.
+     *
+     * @description
+     * Sends a message in real time using WebSocket with authenticated delivery and overlay fallback.
+     *
+     * This method:
+     * - Ensures the WebSocket connection is open and joins the correct room.
+     * - Derives a unique message ID using an HMAC of the message body and counterparty identity key.
+     * - Encrypts the message body using AES-256-GCM based on the ECDH shared secret between derived keys, per [BRC-2](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0002.md),
+     *   unless `skipEncryption` is explicitly set to `true`.
+     * - Sends the message to a WebSocket room in the format `${recipient}-${messageBox}`.
+     * - Waits for acknowledgment (`sendMessageAck-${roomId}`).
+     * - If no acknowledgment is received within 10 seconds, falls back to `sendMessage()` over HTTP.
+     *
+     * This hybrid delivery strategy ensures reliability in both real-time and offline-capable environments.
+     *
+     * @throws {Error} If message validation fails, HMAC generation fails, or both WebSocket and HTTP fail to deliver.
+     *
+     * @example
+     * await client.sendLiveMessage({
+     *   recipient: '028d...',
+     *   messageBox: 'payment_inbox',
+     *   body: { amount: 1000 }
+     * })
+     */
+    sendLiveMessage({ recipient, messageBox, body, messageId, skipEncryption }: SendMessageParams): Promise<SendMessageResponse>;
+    /**
+     * @method leaveRoom
+     * @async
+     * @param {string} messageBox - The name of the WebSocket room to leave (e.g., `payment_inbox`).
+     * @returns {Promise<void>}
+     *
+     * @description
+     * Leaves a previously joined WebSocket room associated with the authenticated identity key.
+     * This helps reduce unnecessary message traffic and memory usage.
+     *
+     * If the WebSocket is not connected or the identity key is missing, the method exits gracefully.
+     *
+     * @example
+     * await client.leaveRoom('payment_inbox')
+     */
+    leaveRoom(messageBox: string): Promise<void>;
+    /**
+     * @method disconnectWebSocket
+     * @async
+     * @returns {Promise<void>} Resolves when the WebSocket connection is successfully closed.
+     *
+     * @description
+     * Gracefully disconnects the WebSocket connection to the MessageBox server.
+     * This should be called when the client is shutting down, logging out, or no longer
+     * needs real-time communication to conserve system resources.
+     *
+     * @example
+     * await client.disconnectWebSocket()
+     */
+    disconnectWebSocket(): Promise<void>;
+    /**
+     * @method sendMessage
+     * @async
+     * @param {SendMessageParams} message - Contains recipient, messageBox name, message body, optional messageId, and skipEncryption flag.
+     * @param {string} [overrideHost] - Optional host to override overlay resolution (useful for testing or private routing).
+     * @returns {Promise<SendMessageResponse>} - Resolves with `{ status, messageId }` on success.
+     *
+     * @description
+     * Sends a message over HTTP to a recipient's messageBox. This method:
+     *
+     * - Derives a deterministic `messageId` using an HMAC of the message body and recipient key.
+     * - Encrypts the message body using AES-256-GCM, derived from a shared secret using BRC-2-compliant key derivation and ECDH, unless `skipEncryption` is set to true.
+     * - Automatically resolves the host via overlay LookupResolver unless an override is provided.
+     * - Authenticates the request using the current identity key with `AuthFetch`.
+     *
+     * This is the fallback mechanism for `sendLiveMessage` when WebSocket delivery fails.
+     * It is also used for message types that do not require real-time delivery.
+     *
+     * @throws {Error} If validation, encryption, HMAC, or network request fails.
+     *
+     * @example
+     * await client.sendMessage({
+     *   recipient: '03abc...',
+     *   messageBox: 'notifications',
+     *   body: { type: 'ping' }
+     * })
+     */
+    sendMessage(message: SendMessageParams, overrideHost?: string): Promise<SendMessageResponse>;
+    /**
+     * @method anointHost
+     * @async
+     * @param {string} host - The full URL of the server you want to designate as your MessageBox host (e.g., "https://mybox.com").
+     * @returns {Promise<{ txid: string }>} - The transaction ID of the advertisement broadcast to the overlay network.
+     *
+     * @description
+     * Broadcasts a signed overlay advertisement using a PushDrop output under the `tm_messagebox` topic.
+     * This advertisement announces that the specified `host` is now authorized to receive and route
+     * messages for the sender’s identity key.
+     *
+     * The broadcasted message includes:
+     * - The identity key
+     * - The chosen host URL
+     *
+     * This is essential for enabling overlay-based message delivery via SHIP and LookupResolver.
+     * The recipient’s host must advertise itself for message routing to succeed in a decentralized manner.
+     *
+     * @throws {Error} If the URL is invalid, the PushDrop creation fails, or the overlay broadcast does not succeed.
+     *
+     * @example
+     * const { txid } = await client.anointHost('https://my-messagebox.io')
+     */
+    anointHost(host: string): Promise<{
+        txid: string;
+    }>;
+    /**
+     * @method revokeHostAdvertisement
+     * @async
+     * @param {AdvertisementToken} advertisementToken - The advertisement token containing the messagebox host to revoke.
+     * @returns {Promise<{ txid: string }>} - The transaction ID of the revocation broadcast to the overlay network.
+     *
+     * @description
+     * Broadcasts a signed revocation transaction indicating the advertisement token should be removed
+     * and no longer tracked by lookup services.
+     *
+     * @example
+     * const { txid } = await client.revokeHost('https://my-messagebox.io')
+     */
+    revokeHostAdvertisement(advertisementToken: AdvertisementToken): Promise<{
+        txid: string;
+    }>;
+    /**
+     * @method listMessages
+     * @async
+     * @param {ListMessagesParams} params - Contains the name of the messageBox to read from.
+     * @returns {Promise<PeerMessage[]>} - Returns an array of decrypted `PeerMessage` objects.
+     *
+     * @description
+     * Retrieves all messages from the specified `messageBox` assigned to the current identity key.
+     * Unless a host override is provided, messages are fetched from the resolved overlay host (via LookupResolver) or the default host if no advertisement is found.
+     *
+     * Each message is:
+     * - Parsed and, if encrypted, decrypted using AES-256-GCM via BRC-2-compliant ECDH key derivation and symmetric encryption.
+     * - Returned as a normalized `PeerMessage` with readable string body content.
+     *
+     * Decryption automatically derives a shared secret using the sender’s identity key and the receiver’s child private key.
+     * If the sender is the same as the recipient, the `counterparty` is set to `'self'`.
+     *
+     * @throws {Error} If no messageBox is specified, the request fails, or the server returns an error.
+     *
+     * @example
+     * const messages = await client.listMessages({ messageBox: 'inbox' })
+     * messages.forEach(msg => console.log(msg.sender, msg.body))
+     */
+    listMessages({ messageBox, host }: ListMessagesParams): Promise<PeerMessage[]>;
+    /**
+     * @method acknowledgeMessage
+     * @async
+     * @param {AcknowledgeMessageParams} params - An object containing an array of message IDs to acknowledge.
+     * @returns {Promise<string>} - A string indicating the result, typically `'success'`.
+     *
+     * @description
+     * Notifies the MessageBox server(s) that one or more messages have been
+     * successfully received and processed by the client. Once acknowledged, these messages are removed
+     * from the recipient's inbox on the server(s).
+     *
+     * This operation is essential for proper message lifecycle management and prevents duplicate
+     * processing or delivery.
+     *
+     * Acknowledgment supports providing a host override, or will use overlay routing to find the appropriate server the received the given message.
+     *
+     * @throws {Error} If the message ID array is missing or empty, or if the request to the server fails.
+     *
+     * @example
+     * await client.acknowledgeMessage({ messageIds: ['msg123', 'msg456'] })
+     */
+    acknowledgeMessage({ messageIds, host }: AcknowledgeMessageParams): Promise<string>;
+}
+export {};
+//# sourceMappingURL=MessageBoxClient.d.ts.map

package/dist/types/src/MessageBoxClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageBoxClient.d.ts","sourceRoot":"","sources":["../../../src/MessageBoxClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAEL,SAAS,EAMT,IAAI,EACJ,aAAa,EACb,SAAS,EACV,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEzD,OAAO,EAAE,wBAAwB,EAAoB,kBAAkB,EAAE,uBAAuB,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAKzK,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,SAAS,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,aAAa,CAAA;IAC5B,IAAI,EAAE,IAAI,CAAA;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAQ;IACpB,SAAgB,SAAS,EAAE,SAAS,CAAA;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,MAAM,CAAC,CAAqC;IACpD,OAAO,CAAC,aAAa,CAAC,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAC/D,OAAO,CAAC,WAAW,CAAQ;IAE3B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;gBACS,OAAO,GAAE,uBAA4B;IA4BjD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,IAAI,CAAC,UAAU,GAAE,MAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BzD;;;;;;;;;;OAUG;YACW,iBAAiB;IAM/B;;;;;;OAMG;IACI,cAAc,IAAI,GAAG,CAAC,MAAM,CAAC;IAIpC;;;;;;KAMC;IACY,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAiB9C;;;;;;;;;;OAUG;IACH,IAAW,UAAU,IAAI,UAAU,CAAC,OAAO,gBAAgB,CAAC,GAAG,SAAS,CAEvE;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmF3C;;;;;;;;;;;;;;;;;OAiBG;IACG,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUnE;;;;;;;OAOG;IACG,mBAAmB,CACvB,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA0ChC;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BjD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,qBAAqB,CAAC,EAC1B,SAAS,EACT,UAAU,EACX,EAAE;QACD,SAAS,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;QACzC,UAAU,EAAE,MAAM,CAAA;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IA6DjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,eAAe,CAAC,EACpB,SAAS,EACT,UAAU,EACV,IAAI,EACJ,SAAS,EACT,cAAc,EACf,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAqInD;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBlD;;;;;;;;;;;;OAYG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAW1C;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,WAAW,CACf,OAAO,EAAE,iBAAiB,EAC1B,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,CAAC;IAmG/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAoEzD;;;;;;;;;;;;OAYG;IACG,uBAAuB,CAAC,kBAAkB,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAwEhG;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,YAAY,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAsHpF;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,kBAAkB,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC;CAwD1F"}

package/dist/types/src/PeerPayClient.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 { WalletClient, AtomicBEEF, Base64String } from '@bsv/sdk';
+export declare const STANDARD_PAYMENT_MESSAGEBOX = "payment_inbox";
+/**
+ * Configuration options for initializing PeerPayClient.
+ */
+export interface PeerPayClientConfig {
+    messageBoxHost?: string;
+    walletClient: WalletClient;
+    enableLogging?: boolean;
+}
+/**
+ * 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.
+     * @returns {Promise<any>} Resolves with the payment result.
+     * @throws {Error} If the recipient is missing or the amount is invalid.
+     */
+    sendPayment(payment: PaymentParams): 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.
+     * @returns {Promise<void>} Resolves when the payment has been sent.
+     * @throws {Error} If payment token generation fails.
+     */
+    sendLivePayment(payment: PaymentParams): 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.
+     * @returns {Promise<void>} Resolves when the listener is successfully set up.
+     */
+    listenForLivePayments({ onPayment }: {
+        onPayment: (payment: IncomingPayment) => void;
+    }): 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.
+     *
+     * @returns {Promise<IncomingPayment[]>} Resolves with an array of pending payments.
+     */
+    listIncomingPayments(): Promise<IncomingPayment[]>;
+}
+//# sourceMappingURL=PeerPayClient.d.ts.map

package/dist/types/src/PeerPayClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PeerPayClient.d.ts","sourceRoot":"","sources":["../../../src/PeerPayClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EAAE,YAAY,EAAiC,UAAU,EAAa,YAAY,EAAE,MAAM,UAAU,CAAA;AAc3G,eAAO,MAAM,2BAA2B,kBAAkB,CAAA;AAG1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,YAAY,EAAE,YAAY,CAAA;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kBAAkB,EAAE;QAClB,gBAAgB,EAAE,YAAY,CAAA;QAC9B,gBAAgB,EAAE,YAAY,CAAA;KAC/B,CAAA;IACD,WAAW,EAAE,UAAU,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,YAAY,CAAA;CACpB;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,gBAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAc;IAClD,OAAO,CAAC,kBAAkB,CAAC,CAAW;gBAEzB,MAAM,EAAE,mBAAmB;IASxC,OAAO,KAAK,iBAAiB,GAK5B;IAED;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAgExE;;;;;;;;;;;OAWG;IACG,WAAW,CAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC;IAexD;;;;;;;;;;;;OAYG;IACG,eAAe,CAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB7D;;;;;;;;;;OAUG;IACG,qBAAqB,CAAE,EAC3B,SAAS,EACV,EAAE;QAAE,SAAS,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpE;;;;;;;;;;OAUG;IACG,aAAa,CAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC;IA8B5D;;;;;;;;;OASG;IACG,aAAa,CAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAoD7D;;;;;;;OAOG;IACG,oBAAoB,IAAK,OAAO,CAAC,eAAe,EAAE,CAAC;CAa1D"}

package/dist/types/src/Utils/logger.d.ts

@@ -0,0 +1,9 @@
+export declare class Logger {
+    private static isEnabled;
+    static enable(): void;
+    static disable(): void;
+    static log(...args: unknown[]): void;
+    static warn(...args: unknown[]): void;
+    static error(...args: unknown[]): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/types/src/Utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../src/Utils/logger.ts"],"names":[],"mappings":"AAAA,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAQ;IAEhC,MAAM,CAAC,MAAM,IAAK,IAAI;IAItB,MAAM,CAAC,OAAO,IAAK,IAAI;IAIvB,MAAM,CAAC,GAAG,CAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMrC,MAAM,CAAC,IAAI,CAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMtC,MAAM,CAAC,KAAK,CAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;CAGxC"}

package/dist/types/src/__tests/MessageBoxClient.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=MessageBoxClient.test.d.ts.map

package/dist/types/src/__tests/MessageBoxClient.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageBoxClient.test.d.ts","sourceRoot":"","sources":["../../../../src/__tests/MessageBoxClient.test.ts"],"names":[],"mappings":""}

package/dist/types/src/__tests/PeerPayClientUnit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=PeerPayClientUnit.test.d.ts.map

package/dist/types/src/__tests/PeerPayClientUnit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PeerPayClientUnit.test.d.ts","sourceRoot":"","sources":["../../../../src/__tests/PeerPayClientUnit.test.ts"],"names":[],"mappings":""}

package/dist/types/src/__tests/integration/integrationEncrypted.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=integrationEncrypted.test.d.ts.map

package/dist/types/src/__tests/integration/integrationEncrypted.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrationEncrypted.test.d.ts","sourceRoot":"","sources":["../../../../../src/__tests/integration/integrationEncrypted.test.ts"],"names":[],"mappings":""}

package/dist/types/src/__tests/integration/integrationHTTP.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=integrationHTTP.test.d.ts.map

package/dist/types/src/__tests/integration/integrationHTTP.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrationHTTP.test.d.ts","sourceRoot":"","sources":["../../../../../src/__tests/integration/integrationHTTP.test.ts"],"names":[],"mappings":""}

package/dist/types/src/__tests/integration/integrationOverlay.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=integrationOverlay.test.d.ts.map

package/dist/types/src/__tests/integration/integrationOverlay.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrationOverlay.test.d.ts","sourceRoot":"","sources":["../../../../../src/__tests/integration/integrationOverlay.test.ts"],"names":[],"mappings":""}

package/dist/types/src/__tests/integration/integrationWS.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=integrationWS.test.d.ts.map

package/dist/types/src/__tests/integration/integrationWS.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrationWS.test.d.ts","sourceRoot":"","sources":["../../../../../src/__tests/integration/integrationWS.test.ts"],"names":[],"mappings":""}

package/dist/types/src/__tests/integration/testServer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Starts the MessageBoxServer as a separate process if not already running.
+ */
+export declare function startTestServer(): Promise<void>;
+/**
+ * Stops the MessageBoxServer process after tests.
+ */
+export declare function stopTestServer(): Promise<void>;
+//# sourceMappingURL=testServer.d.ts.map