@bsv/message-box-client 1.1.10 → 1.2.0

package/dist/esm/src/MessageBoxClient.js

@@ -21,9 +21,9 @@
  * @author Project Babbage
  * @license Open BSV License
  */
-import { WalletClient, AuthFetch, LookupResolver, TopicBroadcaster, Utils, Transaction, PushDrop } from '@bsv/sdk';
+import { WalletClient, AuthFetch, LookupResolver, TopicBroadcaster, Utils, Transaction, PushDrop, P2PKH, PublicKey, ProtoWallet, Random } from '@bsv/sdk';
 import { AuthSocketClient } from '@bsv/authsocket-client';
-import { Logger } from './Utils/logger.js';
+import * as Logger from './Utils/logger.js';
 const DEFAULT_MAINNET_HOST = 'https://messagebox.babbage.systems';
 const DEFAULT_TESTNET_HOST = 'https://staging-messagebox.babbage.systems';
 /**
@@ -67,7 +67,7 @@ export class MessageBoxClient {
      * @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 {WalletInterface} 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.
      *
@@ -88,12 +88,12 @@ export class MessageBoxClient {
      * await client.init()
      */
     constructor(options = {}) {
-        const { host, walletClient, enableLogging = false, networkPreset = 'mainnet' } = options;
+        const { host, walletClient, enableLogging = false, networkPreset = 'mainnet', originator = undefined } = options;
         const defaultHost = this.networkPreset === 'testnet'
             ? DEFAULT_TESTNET_HOST
             : DEFAULT_MAINNET_HOST;
         this.host = host?.trim() ?? defaultHost;
-        this.walletClient = walletClient ?? new WalletClient();
+        this.walletClient = walletClient ?? new WalletClient('auto', originator);
         this.authFetch = new AuthFetch(this.walletClient);
         this.networkPreset = networkPreset;
         this.lookupResolver = new LookupResolver({
@@ -107,6 +107,7 @@ export class MessageBoxClient {
      * @method init
      * @async
      * @param {string} [targetHost] - Optional host to set or override the default host.
+     * @param {string} [originator] - Optional originator to use with walletClient.
      * @returns {Promise<void>}
      *
      * @description
@@ -125,7 +126,7 @@ export class MessageBoxClient {
      * await client.init()
      * await client.sendMessage({ recipient, messageBox: 'inbox', body: 'Hello' })
      */
-    async init(targetHost = this.host) {
+    async init(targetHost = this.host, originator) {
         const normalizedHost = targetHost?.trim();
         if (normalizedHost === '') {
             throw new Error('Cannot anoint host: No valid host provided');
@@ -138,13 +139,13 @@ export class MessageBoxClient {
         if (this.initialized)
             return;
         // 1. Get our identity key
-        const identityKey = await this.getIdentityKey();
+        const identityKey = await this.getIdentityKey(originator);
         // 2. Check for any matching advertisements for the given host
-        const [firstAdvertisement] = await this.queryAdvertisements(identityKey, normalizedHost);
+        const [firstAdvertisement] = await this.queryAdvertisements(identityKey, normalizedHost, originator);
         // 3. If none our found, anoint this host
         if (firstAdvertisement == null || firstAdvertisement?.host?.trim() === '' || firstAdvertisement?.host !== normalizedHost) {
             Logger.log('[MB CLIENT] Anointing host:', normalizedHost);
-            const { txid } = await this.anointHost(normalizedHost);
+            const { txid } = await this.anointHost(normalizedHost, originator);
             if (txid == null || txid.trim() === '') {
                 throw new Error('Failed to anoint host: No transaction ID returned');
             }
@@ -179,18 +180,19 @@ export class MessageBoxClient {
     }
     /**
    * @method getIdentityKey
+   * @param {string} [originator] - Optional originator to use for identity key lookup
    * @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.
    */
-    async getIdentityKey() {
+    async getIdentityKey(originator) {
         if (this.myIdentityKey != null && this.myIdentityKey.trim() !== '') {
             return this.myIdentityKey;
         }
         Logger.log('[MB CLIENT] Fetching identity key...');
         try {
-            const keyResult = await this.walletClient.getPublicKey({ identityKey: true });
+            const keyResult = await this.walletClient.getPublicKey({ identityKey: true }, originator);
             this.myIdentityKey = keyResult.publicKey;
             Logger.log(`[MB CLIENT] Identity key fetched: ${this.myIdentityKey}`);
             return this.myIdentityKey;
@@ -216,6 +218,7 @@ export class MessageBoxClient {
     }
     /**
      * @method initializeConnection
+     * @param {string} [originator] - Optional originator to use for authentication.
      * @async
      * @returns {Promise<void>}
      * @description
@@ -237,20 +240,11 @@ export class MessageBoxClient {
      * await mb.initializeConnection()
      * // WebSocket is now ready for use
      */
-    async initializeConnection() {
+    async initializeConnection(originator) {
         await this.assertInitialized();
         Logger.log('[MB CLIENT] initializeConnection() STARTED');
         if (this.myIdentityKey == null || this.myIdentityKey.trim() === '') {
-            Logger.log('[MB CLIENT] Fetching identity key...');
-            try {
-                const keyResult = await this.walletClient.getPublicKey({ identityKey: true });
-                this.myIdentityKey = keyResult.publicKey;
-                Logger.log(`[MB CLIENT] Identity key fetched successfully: ${this.myIdentityKey}`);
-            }
-            catch (error) {
-                Logger.error('[MB CLIENT ERROR] Failed to fetch identity key:', error);
-                throw new Error('Identity key retrieval failed');
-            }
+            await this.getIdentityKey(originator);
         }
         if (this.myIdentityKey == null || this.myIdentityKey.trim() === '') {
             Logger.error('[MB CLIENT ERROR] Identity key is still missing after retrieval!');
@@ -314,6 +308,7 @@ export class MessageBoxClient {
      * @method resolveHostForRecipient
      * @async
      * @param {string} identityKey - The public identity key of the intended recipient.
+     * @param {string} [originator] - The originator to use for the WalletClient.
      * @returns {Promise<string>} - A fully qualified host URL for the recipient's MessageBox server.
      *
      * @description
@@ -328,8 +323,8 @@ export class MessageBoxClient {
      * @example
      * const host = await resolveHostForRecipient('028d...') // → returns either overlay host or this.host
      */
-    async resolveHostForRecipient(identityKey) {
-        const advertisementTokens = await this.queryAdvertisements(identityKey);
+    async resolveHostForRecipient(identityKey, originator) {
+        const advertisementTokens = await this.queryAdvertisements(identityKey, undefined, originator);
         if (advertisementTokens.length === 0) {
             Logger.warn(`[MB CLIENT] No advertisements for ${identityKey}, using default host ${this.host}`);
             return this.host;
@@ -345,10 +340,10 @@ export class MessageBoxClient {
      * @param host?        if passed, only look for adverts anointed at that host
      * @returns            0-length array if nothing valid was found
      */
-    async queryAdvertisements(identityKey, host) {
+    async queryAdvertisements(identityKey, host, originator) {
         const hosts = [];
         try {
-            const query = { identityKey: identityKey ?? await this.getIdentityKey() };
+            const query = { identityKey: identityKey ?? await this.getIdentityKey(originator) };
             if (host != null && host.trim() !== '')
                 query.host = host;
             const result = await this.lookupResolver.query({
@@ -356,7 +351,7 @@ export class MessageBoxClient {
                 query
             });
             if (result.type !== 'output-list') {
-                throw new Error(`Unexpected result type: ${result.type}`);
+                throw new Error(`Unexpected result type: ${String(result.type)}`);
             }
             for (const output of result.outputs) {
                 try {
@@ -458,7 +453,7 @@ export class MessageBoxClient {
      *   onMessage: (msg) => console.log('Received live message:', msg)
      * })
      */
-    async listenForLiveMessages({ onMessage, messageBox }) {
+    async listenForLiveMessages({ onMessage, messageBox, originator }) {
         await this.assertInitialized();
         Logger.log(`[MB CLIENT] Setting up listener for WebSocket room: ${messageBox}`);
         // Ensure WebSocket connection and room join
@@ -491,7 +486,7 @@ export class MessageBoxClient {
                             keyID: '1',
                             counterparty: message.sender,
                             ciphertext: Utils.toArray(parsedBody.encryptedMessage, 'base64')
-                        });
+                        }, originator);
                         message.body = Utils.toUTF8(decrypted.plaintext);
                     }
                     else {
@@ -543,7 +538,7 @@ export class MessageBoxClient {
      *   body: { amount: 1000 }
      * })
      */
-    async sendLiveMessage({ recipient, messageBox, body, messageId, skipEncryption }) {
+    async sendLiveMessage({ recipient, messageBox, body, messageId, skipEncryption, checkPermissions, originator }) {
         await this.assertInitialized();
         if (recipient == null || recipient.trim() === '') {
             throw new Error('[MB CLIENT ERROR] Recipient identity key is required');
@@ -569,7 +564,7 @@ export class MessageBoxClient {
                 protocolID: [1, 'messagebox'],
                 keyID: '1',
                 counterparty: recipient
-            });
+            }, originator);
             finalMessageId = messageId ?? Array.from(hmac.hmac).map(b => b.toString(16).padStart(2, '0')).join('');
         }
         catch (error) {
@@ -588,7 +583,7 @@ export class MessageBoxClient {
                 keyID: '1',
                 counterparty: recipient,
                 plaintext: Utils.toArray(typeof body === 'string' ? body : JSON.stringify(body), 'utf8')
-            });
+            }, originator);
             outgoingBody = JSON.stringify({
                 encryptedMessage: Utils.toBase64(encryptedMessage.ciphertext)
             });
@@ -612,7 +607,8 @@ export class MessageBoxClient {
                         messageBox,
                         body,
                         messageId: finalMessageId,
-                        skipEncryption
+                        skipEncryption,
+                        checkPermissions
                     };
                     this.resolveHostForRecipient(recipient)
                         .then(async (host) => {
@@ -651,7 +647,8 @@ export class MessageBoxClient {
                         messageBox,
                         body,
                         messageId: finalMessageId,
-                        skipEncryption
+                        skipEncryption,
+                        checkPermissions
                     };
                     this.resolveHostForRecipient(recipient)
                         .then(async (host) => {
@@ -744,7 +741,7 @@ export class MessageBoxClient {
      *   body: { type: 'ping' }
      * })
      */
-    async sendMessage(message, overrideHost) {
+    async sendMessage(message, overrideHost, originator) {
         await this.assertInitialized();
         if (message.recipient == null || message.recipient.trim() === '') {
             throw new Error('You must provide a message recipient!');
@@ -755,6 +752,33 @@ export class MessageBoxClient {
         if (message.body == null || (typeof message.body === 'string' && message.body.trim().length === 0)) {
             throw new Error('Every message must have a body!');
         }
+        // Optional permission checking for backwards compatibility
+        let paymentData;
+        if (message.checkPermissions === true) {
+            try {
+                Logger.log('[MB CLIENT] Checking permissions and fees for message...');
+                // Get quote to check if payment is required
+                const quote = await this.getMessageBoxQuote({
+                    recipient: message.recipient,
+                    messageBox: message.messageBox
+                });
+                if (quote.recipientFee === -1) {
+                    throw new Error('You have been blocked from sending messages to this recipient.');
+                }
+                if (quote.recipientFee > 0 || quote.deliveryFee > 0) {
+                    const requiredPayment = quote.recipientFee + quote.deliveryFee;
+                    if (requiredPayment > 0) {
+                        Logger.log(`[MB CLIENT] Creating payment of ${requiredPayment} sats for message...`);
+                        // Create payment using helper method
+                        paymentData = await this.createMessagePayment(message.recipient, quote, overrideHost);
+                        Logger.log('[MB CLIENT] Payment data prepared:', paymentData);
+                    }
+                }
+            }
+            catch (error) {
+                throw new Error(`Permission check failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
         let messageId;
         try {
             const hmac = await this.walletClient.createHmac({
@@ -762,7 +786,7 @@ export class MessageBoxClient {
                 protocolID: [1, 'messagebox'],
                 keyID: '1',
                 counterparty: message.recipient
-            });
+            }, originator);
             messageId = message.messageId ?? Array.from(hmac.hmac).map(b => b.toString(16).padStart(2, '0')).join('');
         }
         catch (error) {
@@ -779,7 +803,7 @@ export class MessageBoxClient {
                 keyID: '1',
                 counterparty: message.recipient,
                 plaintext: Utils.toArray(typeof message.body === 'string' ? message.body : JSON.stringify(message.body), 'utf8')
-            });
+            }, originator);
             finalBody = JSON.stringify({ encryptedMessage: Utils.toBase64(encryptedMessage.ciphertext) });
         }
         const requestBody = {
@@ -787,7 +811,8 @@ export class MessageBoxClient {
                 ...message,
                 messageId,
                 body: finalBody
-            }
+            },
+            ...(paymentData != null && { payment: paymentData })
         };
         try {
             const finalHost = overrideHost ?? await this.resolveHostForRecipient(message.recipient);
@@ -795,7 +820,7 @@ export class MessageBoxClient {
             Logger.log('[MB CLIENT] Request Body:', JSON.stringify(requestBody, null, 2));
             if (this.myIdentityKey == null || this.myIdentityKey === '') {
                 try {
-                    const keyResult = await this.walletClient.getPublicKey({ identityKey: true });
+                    const keyResult = await this.walletClient.getPublicKey({ identityKey: true }, originator);
                     this.myIdentityKey = keyResult.publicKey;
                     Logger.log(`[MB CLIENT] Fetched identity key before sending request: ${this.myIdentityKey}`);
                 }
@@ -856,19 +881,19 @@ export class MessageBoxClient {
      * @example
      * const { txid } = await client.anointHost('https://my-messagebox.io')
      */
-    async anointHost(host) {
+    async anointHost(host, originator) {
         Logger.log('[MB CLIENT] Starting anointHost...');
         try {
             if (!host.startsWith('http')) {
                 throw new Error('Invalid host URL');
             }
-            const identityKey = await this.getIdentityKey();
+            const identityKey = await this.getIdentityKey(originator);
             Logger.log('[MB CLIENT] Fields - Identity:', identityKey, 'Host:', host);
             const fields = [
                 Utils.toArray(identityKey, 'hex'),
                 Utils.toArray(host, 'utf8')
             ];
-            const pushdrop = new PushDrop(this.walletClient);
+            const pushdrop = new PushDrop(this.walletClient, originator);
             Logger.log('Fields:', fields.map(a => Utils.toHex(a)));
             Logger.log('ProtocolID:', [1, 'messagebox advertisement']);
             Logger.log('KeyID:', '1');
@@ -886,7 +911,7 @@ export class MessageBoxClient {
                         outputDescription: 'Overlay advertisement output'
                     }],
                 options: { randomizeOutputs: false, acceptDelayedBroadcast: false }
-            });
+            }, originator);
             Logger.log('[MB CLIENT] Transaction created:', txid);
             if (tx !== undefined) {
                 const broadcaster = new TopicBroadcaster(['tm_messagebox'], {
@@ -910,6 +935,7 @@ export class MessageBoxClient {
      * @method revokeHostAdvertisement
      * @async
      * @param {AdvertisementToken} advertisementToken - The advertisement token containing the messagebox host to revoke.
+     * @param {string} [originator] - Optional originator to use with walletClient.
      * @returns {Promise<{ txid: string }>} - The transaction ID of the revocation broadcast to the overlay network.
      *
      * @description
@@ -919,7 +945,7 @@ export class MessageBoxClient {
      * @example
      * const { txid } = await client.revokeHost('https://my-messagebox.io')
      */
-    async revokeHostAdvertisement(advertisementToken) {
+    async revokeHostAdvertisement(advertisementToken, originator) {
         Logger.log('[MB CLIENT] Starting revokeHost...');
         const outpoint = `${advertisementToken.txid}.${advertisementToken.outputIndex}`;
         try {
@@ -933,13 +959,13 @@ export class MessageBoxClient {
                         inputDescription: 'Revoking host advertisement token'
                     }
                 ]
-            });
+            }, originator);
             if (signableTransaction === undefined) {
                 throw new Error('Failed to create signable transaction.');
             }
             const partialTx = Transaction.fromBEEF(signableTransaction.tx);
             // Prepare the unlocker
-            const pushdrop = new PushDrop(this.walletClient);
+            const pushdrop = new PushDrop(this.walletClient, originator);
             const unlocker = await pushdrop.unlock([1, 'messagebox advertisement'], '1', 'anyone', 'all', false, advertisementToken.outputIndex, advertisementToken.lockingScript);
             // Convert to Transaction, apply signature
             const finalUnlockScript = await unlocker.sign(partialTx, advertisementToken.outputIndex);
@@ -954,7 +980,7 @@ export class MessageBoxClient {
                 options: {
                     acceptDelayedBroadcast: false
                 }
-            });
+            }, originator);
             if (signedTx === undefined) {
                 throw new Error('Failed to finalize the transaction signature.');
             }
@@ -985,9 +1011,16 @@ export class MessageBoxClient {
      *
      * Each message is:
      * - Parsed and, if encrypted, decrypted using AES-256-GCM via BRC-2-compliant ECDH key derivation and symmetric encryption.
+     * - Automatically processed for payments: if the message includes recipient fee payments, they are internalized using `walletClient.internalizeAction()`.
      * - 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.
+     * Payment Processing:
+     * - Detects messages that include payment data (from paid message delivery).
+     * - Automatically internalizes recipient payment outputs, allowing you to receive payments without additional API calls.
+     * - Only recipient payments are stored with messages - delivery fees are already processed by the server.
+     * - Continues processing messages even if payment internalization fails.
+     *
+     * 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.
@@ -995,15 +1028,16 @@ export class MessageBoxClient {
      * @example
      * const messages = await client.listMessages({ messageBox: 'inbox' })
      * messages.forEach(msg => console.log(msg.sender, msg.body))
+     * // Payments included with messages are automatically received
      */
-    async listMessages({ messageBox, host }) {
+    async listMessages({ messageBox, host, originator }) {
         await this.assertInitialized();
         if (messageBox.trim() === '') {
             throw new Error('MessageBox cannot be empty');
         }
         let hosts = host != null ? [host] : [];
         if (hosts.length === 0) {
-            const advertisedHosts = await this.queryAdvertisements(await this.getIdentityKey());
+            const advertisedHosts = await this.queryAdvertisements(await this.getIdentityKey(originator), originator);
             hosts = Array.from(new Set([this.host, ...advertisedHosts.map(h => h.host)]));
         }
         // Query each host in parallel
@@ -1066,21 +1100,65 @@ export class MessageBoxClient {
         for (const message of messages) {
             try {
                 const parsedBody = typeof message.body === 'string' ? tryParse(message.body) : message.body;
+                let messageContent = parsedBody;
+                let paymentData;
                 if (parsedBody != null &&
                     typeof parsedBody === 'object' &&
-                    typeof parsedBody.encryptedMessage === 'string') {
+                    'message' in parsedBody) {
+                    // Handle wrapped message format (with payment data)
+                    const wrappedMessage = parsedBody.message;
+                    messageContent = typeof wrappedMessage === 'string'
+                        ? tryParse(wrappedMessage)
+                        : wrappedMessage;
+                    paymentData = parsedBody.payment;
+                }
+                // Process payment if present - server now only stores recipient payments
+                if (paymentData?.tx != null && paymentData.outputs != null) {
+                    try {
+                        Logger.log(`[MB CLIENT] Processing recipient payment in message from ${String(message.sender)}…`);
+                        // All outputs in the stored payment data are for the recipient
+                        // (delivery fees are already processed by the server)
+                        const recipientOutputs = paymentData.outputs.filter(output => output.protocol === 'wallet payment');
+                        if (recipientOutputs.length > 0) {
+                            Logger.log(`[MB CLIENT] Internalizing ${recipientOutputs.length} recipient payment output(s)…`);
+                            const internalizeResult = await this.walletClient.internalizeAction({
+                                tx: paymentData.tx,
+                                outputs: recipientOutputs,
+                                description: paymentData.description ?? 'MessageBox recipient payment'
+                            }, originator);
+                            if (internalizeResult.accepted) {
+                                Logger.log('[MB CLIENT] Successfully internalized recipient payment');
+                            }
+                            else {
+                                Logger.warn('[MB CLIENT] Recipient payment internalization was not accepted');
+                            }
+                        }
+                        else {
+                            Logger.log('[MB CLIENT] No wallet payment outputs found in payment data');
+                        }
+                    }
+                    catch (paymentError) {
+                        Logger.error('[MB CLIENT ERROR] Failed to internalize recipient payment:', paymentError);
+                        // Continue processing the message even if payment fails
+                    }
+                }
+                // Handle message decryption
+                if (messageContent != null &&
+                    typeof messageContent === 'object' &&
+                    typeof messageContent.encryptedMessage === 'string') {
                     Logger.log(`[MB CLIENT] Decrypting message from ${String(message.sender)}…`);
                     const decrypted = await this.walletClient.decrypt({
                         protocolID: [1, 'messagebox'],
                         keyID: '1',
                         counterparty: message.sender,
-                        ciphertext: Utils.toArray(parsedBody.encryptedMessage, 'base64')
-                    });
+                        ciphertext: Utils.toArray(messageContent.encryptedMessage, 'base64')
+                    }, originator);
                     const decryptedText = Utils.toUTF8(decrypted.plaintext);
                     message.body = tryParse(decryptedText);
                 }
                 else {
-                    message.body = parsedBody;
+                    // For non-encrypted messages, use the processed content
+                    message.body = messageContent ?? parsedBody;
                 }
             }
             catch (err) {
@@ -1113,7 +1191,7 @@ export class MessageBoxClient {
      * @example
      * await client.acknowledgeMessage({ messageIds: ['msg123', 'msg456'] })
      */
-    async acknowledgeMessage({ messageIds, host }) {
+    async acknowledgeMessage({ messageIds, host, originator }) {
         await this.assertInitialized();
         if (!Array.isArray(messageIds) || messageIds.length === 0) {
             throw new Error('Message IDs array cannot be empty');
@@ -1122,8 +1200,8 @@ export class MessageBoxClient {
         let hosts = host != null ? [host] : [];
         if (hosts.length === 0) {
             // 1. Determine all hosts (advertised + default)
-            const identityKey = await this.getIdentityKey();
-            const advertisedHosts = await this.queryAdvertisements(identityKey);
+            const identityKey = await this.getIdentityKey(originator);
+            const advertisedHosts = await this.queryAdvertisements(identityKey, undefined, originator);
             hosts = Array.from(new Set([this.host, ...advertisedHosts.map(h => h.host)]));
         }
         // 2. Dispatch parallel acknowledge requests
@@ -1161,5 +1239,506 @@ export class MessageBoxClient {
         }
         throw new Error(`Failed to acknowledge messages on all hosts: ${errs.map(e => String(e)).join('; ')}`);
     }
+    // ===========================
+    // PERMISSION MANAGEMENT METHODS
+    // ===========================
+    /**
+     * @method setMessageBoxPermission
+     * @async
+     * @param {SetMessageBoxPermissionParams} params - Permission configuration
+     * @param {string} [overrideHost] - Optional host override
+     * @returns {Promise<void>} Permission status after setting
+     *
+     * @description
+     * Sets permission for receiving messages in a specific messageBox.
+     * Can set sender-specific permissions or box-wide defaults.
+     *
+     * @example
+     * // Set box-wide default: allow notifications for 10 sats
+     * await client.setMessageBoxPermission({ messageBox: 'notifications', recipientFee: 10 })
+     *
+     * // Block specific sender
+     * await client.setMessageBoxPermission({
+     *   messageBox: 'notifications',
+     *   sender: '03abc123...',
+     *   recipientFee: -1
+     * })
+     */
+    async setMessageBoxPermission(params, overrideHost) {
+        await this.assertInitialized();
+        const finalHost = overrideHost ?? this.host;
+        Logger.log('[MB CLIENT] Setting messageBox permission...');
+        const response = await this.authFetch.fetch(`${finalHost}/permissions/set`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                messageBox: params.messageBox,
+                recipientFee: params.recipientFee,
+                ...(params.sender != null && { sender: params.sender })
+            })
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(`Failed to set permission: HTTP ${response.status} - ${String(errorData.description) !== '' ? String(errorData.description) : response.statusText}`);
+        }
+        const { status, description } = await response.json();
+        if (status === 'error') {
+            throw new Error(description ?? 'Failed to set permission');
+        }
+    }
+    /**
+     * @method getMessageBoxPermission
+     * @async
+     * @param {GetMessageBoxPermissionParams} params - Permission query parameters
+     * @param {string} [overrideHost] - Optional host override
+     * @returns {Promise<MessageBoxPermission | null>} Permission data (null if not set)
+     *
+     * @description
+     * Gets current permission data for a sender/messageBox combination.
+     * Returns null if no permission is set.
+     *
+     * @example
+     * const status = await client.getMessageBoxPermission({
+     *   recipient: '03def456...',
+     *   messageBox: 'notifications',
+     *   sender: '03abc123...'
+     * })
+     */
+    async getMessageBoxPermission(params, overrideHost) {
+        await this.assertInitialized();
+        const finalHost = overrideHost ?? await this.resolveHostForRecipient(params.recipient);
+        const queryParams = new URLSearchParams({
+            recipient: params.recipient,
+            messageBox: params.messageBox,
+            ...(params.sender != null && { sender: params.sender })
+        });
+        Logger.log('[MB CLIENT] Getting messageBox permission...');
+        const response = await this.authFetch.fetch(`${finalHost}/permissions/get?${queryParams.toString()}`, {
+            method: 'GET'
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(`Failed to get permission: HTTP ${response.status} - ${String(errorData.description) !== '' ? String(errorData.description) : response.statusText}`);
+        }
+        const data = await response.json();
+        if (data.status === 'error') {
+            throw new Error(data.description ?? 'Failed to get permission');
+        }
+        return data.permission;
+    }
+    /**
+     * @method getMessageBoxQuote
+     * @async
+     * @param {GetQuoteParams} params - Quote request parameters
+     * @returns {Promise<MessageBoxQuote>} Fee quote and permission status
+     *
+     * @description
+     * Gets a fee quote for sending a message, including delivery and recipient fees.
+     *
+     * @example
+     * const quote = await client.getMessageBoxQuote({
+     *   recipient: '03def456...',
+     *   messageBox: 'notifications'
+     * })
+     */
+    async getMessageBoxQuote(params, overrideHost) {
+        await this.assertInitialized();
+        const finalHost = overrideHost ?? await this.resolveHostForRecipient(params.recipient);
+        const queryParams = new URLSearchParams({
+            recipient: params.recipient,
+            messageBox: params.messageBox
+        });
+        Logger.log('[MB CLIENT] Getting messageBox quote...');
+        const response = await this.authFetch.fetch(`${finalHost}/permissions/quote?${queryParams.toString()}`, {
+            method: 'GET'
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(`Failed to get quote: HTTP ${response.status} - ${String(errorData.description) ?? response.statusText}`);
+        }
+        const { status, description, quote } = await response.json();
+        if (status === 'error') {
+            throw new Error(description ?? 'Failed to get quote');
+        }
+        const deliveryAgentIdentityKey = response.headers.get('x-bsv-auth-identity-key');
+        if (deliveryAgentIdentityKey == null) {
+            throw new Error('Failed to get quote: Delivery agent did not provide their identity key');
+        }
+        return {
+            recipientFee: quote.recipientFee,
+            deliveryFee: quote.deliveryFee,
+            deliveryAgentIdentityKey
+        };
+    }
+    /**
+     * @method listMessageBoxPermissions
+     * @async
+     * @param {ListPermissionsParams} [params] - Optional filtering and pagination parameters
+     * @returns {Promise<MessageBoxPermission[]>} List of current permissions
+     *
+     * @description
+     * Lists permissions for the authenticated user's messageBoxes with optional pagination.
+     *
+     * @example
+     * // List all permissions
+     * const all = await client.listMessageBoxPermissions()
+     *
+     * // List only notification permissions with pagination
+     * const notifications = await client.listMessageBoxPermissions({
+     *   messageBox: 'notifications',
+     *   limit: 50,
+     *   offset: 0
+     * })
+     */
+    async listMessageBoxPermissions(params, overrideHost) {
+        await this.assertInitialized();
+        const finalHost = overrideHost ?? this.host;
+        const queryParams = new URLSearchParams();
+        if (params?.messageBox != null) {
+            queryParams.set('message_box', params.messageBox);
+        }
+        if (params?.limit !== undefined) {
+            queryParams.set('limit', params.limit.toString());
+        }
+        if (params?.offset !== undefined) {
+            queryParams.set('offset', params.offset.toString());
+        }
+        Logger.log('[MB CLIENT] Listing messageBox permissions with params:', queryParams.toString());
+        const response = await this.authFetch.fetch(`${finalHost}/permissions/list?${queryParams.toString()}`, {
+            method: 'GET'
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(`Failed to list permissions: HTTP ${response.status} - ${String(errorData.description) !== '' ? String(errorData.description) : response.statusText}`);
+        }
+        const data = await response.json();
+        if (data.status === 'error') {
+            throw new Error(data.description ?? 'Failed to list permissions');
+        }
+        return data.permissions.map((p) => ({
+            sender: p.sender,
+            messageBox: p.message_box,
+            recipientFee: p.recipient_fee,
+            status: MessageBoxClient.getStatusFromFee(p.recipient_fee),
+            createdAt: p.created_at,
+            updatedAt: p.updated_at
+        }));
+    }
+    // ===========================
+    // NOTIFICATION CONVENIENCE METHODS
+    // ===========================
+    /**
+     * @method allowNotificationsFromPeer
+     * @async
+     * @param {PubKeyHex} identityKey - Sender's identity key to allow
+     * @param {number} [recipientFee=0] - Fee to charge (0 for always allow)
+     * @param {string} [overrideHost] - Optional host override
+     * @returns {Promise<void>} Permission status after allowing
+     *
+     * @description
+     * Convenience method to allow notifications from a specific peer.
+     *
+     * @example
+     * await client.allowNotificationsFromPeer('03abc123...') // Always allow
+     * await client.allowNotificationsFromPeer('03def456...', 5) // Allow for 5 sats
+     */
+    async allowNotificationsFromPeer(identityKey, recipientFee = 0, overrideHost) {
+        await this.setMessageBoxPermission({
+            messageBox: 'notifications',
+            sender: identityKey,
+            recipientFee
+        }, overrideHost);
+    }
+    /**
+     * @method denyNotificationsFromPeer
+     * @async
+     * @param {PubKeyHex} identityKey - Sender's identity key to block
+     * @returns {Promise<void>} Permission status after denying
+     *
+     * @description
+     * Convenience method to block notifications from a specific peer.
+     *
+     * @example
+     * await client.denyNotificationsFromPeer('03spam123...')
+     */
+    async denyNotificationsFromPeer(identityKey, overrideHost) {
+        await this.setMessageBoxPermission({
+            messageBox: 'notifications',
+            sender: identityKey,
+            recipientFee: -1
+        }, overrideHost);
+    }
+    /**
+     * @method checkPeerNotificationStatus
+     * @async
+     * @param {PubKeyHex} identityKey - Sender's identity key to check
+     * @returns {Promise<MessageBoxPermission>} Current permission status
+     *
+     * @description
+     * Convenience method to check notification permission for a specific peer.
+     *
+     * @example
+     * const status = await client.checkPeerNotificationStatus('03abc123...')
+     * console.log(status.allowed) // true/false
+     */
+    async checkPeerNotificationStatus(identityKey, overrideHost) {
+        const myIdentityKey = await this.getIdentityKey();
+        return await this.getMessageBoxPermission({
+            recipient: myIdentityKey,
+            messageBox: 'notifications',
+            sender: identityKey
+        }, overrideHost);
+    }
+    /**
+     * @method listPeerNotifications
+     * @async
+     * @returns {Promise<MessageBoxPermission[]>} List of notification permissions
+     *
+     * @description
+     * Convenience method to list all notification permissions.
+     *
+     * @example
+     * const notifications = await client.listPeerNotifications()
+     */
+    async listPeerNotifications(overrideHost) {
+        return await this.listMessageBoxPermissions({ messageBox: 'notifications' }, overrideHost);
+    }
+    /**
+     * @method sendNotification
+     * @async
+     * @param {PubKeyHex} recipient - Recipient's identity key
+     * @param {string | object} body - Notification content
+     * @param {string} [overrideHost] - Optional host override
+     * @returns {Promise<SendMessageResponse>} Send result
+     *
+     * @description
+     * Convenience method to send a notification with automatic quote fetching and payment handling.
+     * Automatically determines the required payment amount and creates the payment if needed.
+     *
+     * @example
+     * // Send notification (auto-determines payment needed)
+     * await client.sendNotification('03def456...', 'Hello!')
+     *
+     * // Send with maximum payment limit for safety
+     * await client.sendNotification('03def456...', { title: 'Alert', body: 'Important update' }, 50)
+     */
+    async sendNotification(recipient, body, overrideHost) {
+        await this.assertInitialized();
+        // Use sendMessage with permission checking enabled
+        // This eliminates duplication of quote fetching and payment logic
+        return await this.sendMessage({
+            recipient,
+            messageBox: 'notifications',
+            body,
+            checkPermissions: true
+        }, overrideHost);
+    }
+    /**
+     * Register a device for FCM push notifications.
+     *
+     * @async
+     * @param {DeviceRegistrationParams} params - Device registration parameters
+     * @param {string} [overrideHost] - Optional host override
+     * @returns {Promise<DeviceRegistrationResponse>} Registration response
+     *
+     * @description
+     * Registers a device with the message box server to receive FCM push notifications.
+     * The FCM token is obtained from Firebase SDK on the client side.
+     *
+     * @example
+     * const result = await client.registerDevice({
+     *   fcmToken: 'eBo8F...',
+     *   platform: 'ios',
+     *   deviceId: 'iPhone15Pro'
+     * })
+     */
+    async registerDevice(params, overrideHost) {
+        await this.assertInitialized();
+        if (params.fcmToken == null || params.fcmToken.trim() === '') {
+            throw new Error('fcmToken is required and must be a non-empty string');
+        }
+        // Validate platform if provided
+        const validPlatforms = ['ios', 'android', 'web'];
+        if (params.platform != null && !validPlatforms.includes(params.platform)) {
+            throw new Error('platform must be one of: ios, android, web');
+        }
+        const finalHost = overrideHost ?? this.host;
+        Logger.log('[MB CLIENT] Registering device for FCM notifications...');
+        const response = await this.authFetch.fetch(`${finalHost}/registerDevice`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                fcmToken: params.fcmToken.trim(),
+                deviceId: params.deviceId?.trim() ?? undefined,
+                platform: params.platform ?? undefined
+            })
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            const description = String(errorData.description) ?? response.statusText;
+            throw new Error(`Failed to register device: HTTP ${response.status} - ${description}`);
+        }
+        const data = await response.json();
+        if (data.status === 'error') {
+            throw new Error(data.description ?? 'Failed to register device');
+        }
+        Logger.log('[MB CLIENT] Device registered successfully');
+        return {
+            status: data.status,
+            message: data.message,
+            deviceId: data.deviceId
+        };
+    }
+    /**
+     * List all registered devices for push notifications.
+     *
+     * @async
+     * @param {string} [overrideHost] - Optional host override
+     * @returns {Promise<RegisteredDevice[]>} Array of registered devices
+     *
+     * @description
+     * Retrieves all devices registered by the authenticated user for FCM push notifications.
+     * Only shows devices belonging to the current user (authenticated via AuthFetch).
+     *
+     * @example
+     * const devices = await client.listRegisteredDevices()
+     * console.log(`Found ${devices.length} registered devices`)
+     * devices.forEach(device => {
+     *   console.log(`Device: ${device.platform} - ${device.fcmToken}`)
+     * })
+     */
+    async listRegisteredDevices(overrideHost) {
+        await this.assertInitialized();
+        const finalHost = overrideHost ?? this.host;
+        Logger.log('[MB CLIENT] Listing registered devices...');
+        const response = await this.authFetch.fetch(`${finalHost}/devices`, {
+            method: 'GET'
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            const description = String(errorData.description) ?? response.statusText;
+            throw new Error(`Failed to list devices: HTTP ${response.status} - ${description}`);
+        }
+        const data = await response.json();
+        if (data.status === 'error') {
+            throw new Error(data.description ?? 'Failed to list devices');
+        }
+        Logger.log(`[MB CLIENT] Found ${data.devices.length} registered devices`);
+        return data.devices;
+    }
+    // ===========================
+    // PRIVATE HELPER METHODS
+    // ===========================
+    static getStatusFromFee(fee) {
+        if (fee === -1)
+            return 'blocked';
+        if (fee === 0)
+            return 'always_allow';
+        return 'payment_required';
+    }
+    /**
+     * Creates payment transaction for message delivery fees
+     * TODO: Consider consolidating payment generating logic with a util PeerPayClient can use as well.
+     * @private
+     * @param {string} recipient - Recipient identity key
+     * @param {MessageBoxQuote} quote - Fee quote with delivery and recipient fees
+     * @param {string} description - Description for the payment transaction
+     * @returns {Promise<Payment>} Payment transaction data
+     */
+    async createMessagePayment(recipient, quote, description = 'MessageBox delivery payment', originator) {
+        if (quote.recipientFee <= 0 && quote.deliveryFee <= 0) {
+            throw new Error('No payment required');
+        }
+        Logger.log(`[MB CLIENT] Creating payment transaction for ${quote.recipientFee} sats (delivery: ${quote.deliveryFee}, recipient: ${quote.recipientFee})`);
+        const outputs = [];
+        const createActionOutputs = [];
+        // Get sender identity key for remittance data
+        const senderIdentityKey = await this.getIdentityKey();
+        // Add server delivery fee output if > 0
+        let outputIndex = 0;
+        if (quote.deliveryFee > 0) {
+            const derivationPrefix = Utils.toBase64(Random(32));
+            const derivationSuffix = Utils.toBase64(Random(32));
+            // Get host's derived public key
+            const { publicKey: derivedKeyResult } = await this.walletClient.getPublicKey({
+                protocolID: [2, '3241645161d8'],
+                keyID: `${derivationPrefix} ${derivationSuffix}`,
+                counterparty: quote.deliveryAgentIdentityKey
+            }, originator);
+            // Create locking script using host's public key
+            const lockingScript = new P2PKH().lock(PublicKey.fromString(derivedKeyResult).toAddress()).toHex();
+            // Add to createAction outputs
+            createActionOutputs.push({
+                satoshis: quote.deliveryFee,
+                lockingScript,
+                outputDescription: 'MessageBox server delivery fee',
+                customInstructions: JSON.stringify({
+                    derivationPrefix,
+                    derivationSuffix,
+                    recipientIdentityKey: quote.deliveryAgentIdentityKey
+                })
+            });
+            outputs.push({
+                outputIndex: outputIndex++,
+                protocol: 'wallet payment',
+                paymentRemittance: {
+                    derivationPrefix,
+                    derivationSuffix,
+                    senderIdentityKey
+                }
+            });
+        }
+        // Add recipient fee output if > 0
+        if (quote.recipientFee > 0) {
+            const derivationPrefix = Utils.toBase64(Random(32));
+            const derivationSuffix = Utils.toBase64(Random(32));
+            // Get a derived public key for the recipient that "anyone" can verify
+            const anyoneWallet = new ProtoWallet('anyone');
+            const { publicKey: derivedKeyResult } = await anyoneWallet.getPublicKey({
+                protocolID: [2, '3241645161d8'],
+                keyID: `${derivationPrefix} ${derivationSuffix}`,
+                counterparty: recipient
+            });
+            if (derivedKeyResult == null || derivedKeyResult.trim() === '') {
+                throw new Error('Failed to derive recipient\'s public key');
+            }
+            // Create locking script using recipient's public key
+            const lockingScript = new P2PKH().lock(PublicKey.fromString(derivedKeyResult).toAddress()).toHex();
+            // Add to createAction outputs
+            createActionOutputs.push({
+                satoshis: quote.recipientFee,
+                lockingScript,
+                outputDescription: 'Recipient message fee',
+                customInstructions: JSON.stringify({
+                    derivationPrefix,
+                    derivationSuffix,
+                    recipientIdentityKey: recipient
+                })
+            });
+            outputs.push({
+                outputIndex: outputIndex++,
+                protocol: 'wallet payment',
+                paymentRemittance: {
+                    derivationPrefix,
+                    derivationSuffix,
+                    senderIdentityKey: (await anyoneWallet.getPublicKey({ identityKey: true })).publicKey
+                }
+            });
+        }
+        const { tx } = await this.walletClient.createAction({
+            description,
+            outputs: createActionOutputs,
+            options: { randomizeOutputs: false, acceptDelayedBroadcast: false }
+        }, originator);
+        if (tx == null) {
+            throw new Error('Failed to create payment transaction');
+        }
+        return {
+            tx,
+            outputs,
+            description
+            // labels
+        };
+    }
 }
 //# sourceMappingURL=MessageBoxClient.js.map