@bsv/message-box-client 1.2.3 → 1.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/message-box-client",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "publishConfig": {
     "access": "public"
   },

package/src/MessageBoxClient.ts

@@ -116,7 +116,7 @@ export class MessageBoxClient {
    * })
    * await client.init()
    */
-  constructor(options: MessageBoxClientOptions = {}) {
+  constructor (options: MessageBoxClientOptions = {}) {
     const {
       host,
       walletClient,
@@ -168,7 +168,7 @@ export class MessageBoxClient {
    * await client.init()
    * await client.sendMessage({ recipient, messageBox: 'inbox', body: 'Hello' })
    */
-  async init(targetHost: string = this.host, originator?: string): Promise<void> {
+  async init (targetHost: string = this.host, originator?: string): Promise<void> {
     const normalizedHost = targetHost?.trim()
     if (normalizedHost === '') {
       throw new Error('Cannot anoint host: No valid host provided')
@@ -189,9 +189,14 @@ export class MessageBoxClient {
     // 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, originator)
-      if (txid == null || txid.trim() === '') {
-        throw new Error('Failed to anoint host: No transaction ID returned')
+      try {
+        const { txid } = await this.anointHost(normalizedHost, originator)
+        if (txid == null || txid.trim() === '') {
+          throw new Error('Failed to anoint host: No transaction ID returned')
+        }
+      } catch (error) {
+        Logger.log('[MB CLIENT] Failed to anoint host, continuing with default functionality:', error)
+        // Continue with default host - client can still function for basic operations
       }
     }
     this.initialized = true
@@ -208,7 +213,7 @@ export class MessageBoxClient {
    *
    * Used automatically by all public methods that require initialization.
    */
-  private async assertInitialized(): Promise<void> {
+  private async assertInitialized (): Promise<void> {
     if (!this.initialized || this.host == null || this.host.trim() === '') {
       await this.init()
     }
@@ -221,7 +226,7 @@ export class MessageBoxClient {
    * Returns a live list of WebSocket rooms the client is subscribed to.
    * Useful for inspecting state or ensuring no duplicates are joined.
    */
-  public getJoinedRooms(): Set<string> {
+  public getJoinedRooms (): Set<string> {
     return this.joinedRooms
   }
 
@@ -233,7 +238,7 @@ export class MessageBoxClient {
  * Returns the client's identity key, used for signing, encryption, and addressing.
  * If not already loaded, it will fetch and cache it.
  */
-  public async getIdentityKey(originator?: string): Promise<string> {
+  public async getIdentityKey (originator?: string): Promise<string> {
     if (this.myIdentityKey != null && this.myIdentityKey.trim() !== '') {
       return this.myIdentityKey
     }
@@ -261,7 +266,7 @@ export class MessageBoxClient {
    * Note: Do not interact with the socket directly unless necessary.
    * Use the provided `sendLiveMessage`, `listenForLiveMessages`, and related methods.
    */
-  public get testSocket(): ReturnType<typeof AuthSocketClient> | undefined {
+  public get testSocket (): ReturnType<typeof AuthSocketClient> | undefined {
     return this.socket
   }
 
@@ -289,8 +294,7 @@ export class MessageBoxClient {
    * await mb.initializeConnection()
    * // WebSocket is now ready for use
    */
-  async initializeConnection(originator?: string): Promise<void> {
-    await this.assertInitialized()
+  async initializeConnection (originator?: string, overrideHost?: string): Promise<void> {
     Logger.log('[MB CLIENT] initializeConnection() STARTED')
 
     if (this.myIdentityKey == null || this.myIdentityKey.trim() === '') {
@@ -305,10 +309,11 @@ export class MessageBoxClient {
     Logger.log('[MB CLIENT] Setting up WebSocket connection...')
 
     if (this.socket == null) {
-      if (typeof this.host !== 'string' || this.host.trim() === '') {
-        throw new Error('Cannot initialize WebSocket: Host is not set')
+      const targetHost = overrideHost ?? this.host
+      if (typeof targetHost !== 'string' || targetHost.trim() === '') {
+        throw new Error('Cannot initialize WebSocket: No valid host provided')
       }
-      this.socket = AuthSocketClient(this.host, { wallet: this.walletClient })
+      this.socket = AuthSocketClient(targetHost, { wallet: this.walletClient })
 
       let identitySent = false
       let authenticated = false
@@ -383,7 +388,7 @@ export class MessageBoxClient {
    * @example
    * const host = await resolveHostForRecipient('028d...') // → returns either overlay host or this.host
    */
-  async resolveHostForRecipient(identityKey: string, originator?: string): Promise<string> {
+  async resolveHostForRecipient (identityKey: string, originator?: string): Promise<string> {
     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}`)
@@ -401,7 +406,7 @@ 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(
+  async queryAdvertisements (
     identityKey?: string,
     host?: string,
     originator?: string
@@ -466,14 +471,13 @@ export class MessageBoxClient {
    * await client.joinRoom('payment_inbox')
    * // Now listening for real-time messages in room '028d...-payment_inbox'
    */
-  async joinRoom(messageBox: string): Promise<void> {
-    await this.assertInitialized()
+  async joinRoom (messageBox: string, originator?: string, overrideHost?: string): Promise<void> {
     Logger.log(`[MB CLIENT] Attempting to join WebSocket room: ${messageBox}`)
 
     // Ensure WebSocket connection is established first
     if (this.socket == null) {
       Logger.log('[MB CLIENT] No WebSocket connection. Initializing...')
-      await this.initializeConnection()
+      await this.initializeConnection(originator, overrideHost)
     }
 
     if (this.myIdentityKey == null || this.myIdentityKey.trim() === '') {
@@ -525,20 +529,27 @@ export class MessageBoxClient {
    *   onMessage: (msg) => console.log('Received live message:', msg)
    * })
    */
-  async listenForLiveMessages({
+  async listenForLiveMessages ({
     onMessage,
     messageBox,
-    originator
+    originator,
+    overrideHost
   }: {
     onMessage: (message: PeerMessage) => void
     messageBox: string
     originator?: string
+    overrideHost?: string
   }): Promise<void> {
-    await this.assertInitialized()
     Logger.log(`[MB CLIENT] Setting up listener for WebSocket room: ${messageBox}`)
 
-    // Ensure WebSocket connection and room join
-    await this.joinRoom(messageBox)
+    // Ensure WebSocket connection is established first
+    if (this.socket == null) {
+      Logger.log('[MB CLIENT] No WebSocket connection. Initializing...')
+      await this.initializeConnection(originator, overrideHost)
+    }
+
+    // Join the room
+    await this.joinRoom(messageBox, originator, overrideHost)
 
     // Ensure identity key is available before creating roomId
     if (this.myIdentityKey == null || this.myIdentityKey.trim() === '') {
@@ -623,7 +634,7 @@ export class MessageBoxClient {
    *   body: { amount: 1000 }
    * })
    */
-  async sendLiveMessage({
+  async sendLiveMessage ({
     recipient,
     messageBox,
     body,
@@ -781,7 +792,7 @@ export class MessageBoxClient {
    * @example
    * await client.leaveRoom('payment_inbox')
    */
-  async leaveRoom(messageBox: string): Promise<void> {
+  async leaveRoom (messageBox: string): Promise<void> {
     await this.assertInitialized()
     if (this.socket == null) {
       Logger.warn('[MB CLIENT] Attempted to leave a room but WebSocket is not connected.')
@@ -813,7 +824,7 @@ export class MessageBoxClient {
    * @example
    * await client.disconnectWebSocket()
    */
-  async disconnectWebSocket(): Promise<void> {
+  async disconnectWebSocket (): Promise<void> {
     await this.assertInitialized()
     if (this.socket != null) {
       Logger.log('[MB CLIENT] Closing WebSocket connection...')
@@ -851,7 +862,7 @@ export class MessageBoxClient {
    *   body: { type: 'ping' }
    * })
    */
-  async sendMessage(
+  async sendMessage (
     message: SendMessageParams,
     overrideHost?: string,
     originator?: string
@@ -1015,7 +1026,7 @@ export class MessageBoxClient {
    * @example
    * const { txid } = await client.anointHost('https://my-messagebox.io')
    */
-  async anointHost(host: string, originator?: string): Promise<{ txid: string }> {
+  async anointHost (host: string, originator?: string): Promise<{ txid: string }> {
     Logger.log('[MB CLIENT] Starting anointHost...')
     try {
       if (!host.startsWith('http')) {
@@ -1097,7 +1108,7 @@ export class MessageBoxClient {
    * @example
    * const { txid } = await client.revokeHost('https://my-messagebox.io')
    */
-  async revokeHostAdvertisement(advertisementToken: AdvertisementToken, originator?: string): Promise<{ txid: string }> {
+  async revokeHostAdvertisement (advertisementToken: AdvertisementToken, originator?: string): Promise<{ txid: string }> {
     Logger.log('[MB CLIENT] Starting revokeHost...')
     const outpoint = `${advertisementToken.txid}.${advertisementToken.outputIndex}`
     try {
@@ -1213,7 +1224,11 @@ export class MessageBoxClient {
 
     let hosts: string[] = host != null ? [host] : []
     if (hosts.length === 0) {
-      const advertisedHosts = await this.queryAdvertisements(await this.getIdentityKey(originator), originator)
+      const advertisedHosts = await this.queryAdvertisements(
+        await this.getIdentityKey(originator),
+        undefined,
+        originator
+      )
       hosts = Array.from(new Set([this.host, ...advertisedHosts.map(h => h.host)]))
     }
 
@@ -1266,20 +1281,12 @@ export class MessageBoxClient {
     // 6. Early‑out: no messages but at least one host succeeded → []
     if (dedupMap.size === 0) return []
 
-    const tryParse = (raw: string): any => {
-      try {
-        return JSON.parse(raw)
-      } catch {
-        return raw
-      }
-    }
-
     const messages: PeerMessage[] = Array.from(dedupMap.values())
 
     for (const message of messages) {
       try {
         const parsedBody: unknown =
-          typeof message.body === 'string' ? tryParse(message.body) : message.body
+          typeof message.body === 'string' ? this.tryParse(message.body) : message.body
 
         let messageContent: any = parsedBody
         let paymentData: Payment | undefined
@@ -1292,7 +1299,7 @@ export class MessageBoxClient {
           // Handle wrapped message format (with payment data)
           const wrappedMessage = (parsedBody as any).message
           messageContent = typeof wrappedMessage === 'string'
-            ? tryParse(wrappedMessage)
+            ? this.tryParse(wrappedMessage)
             : wrappedMessage
           paymentData = (parsedBody as any).payment
         }
@@ -1348,7 +1355,7 @@ export class MessageBoxClient {
         if (
           messageContent != null &&
           typeof messageContent === 'object' &&
-          typeof (messageContent as any).encryptedMessage === 'string'
+          typeof (messageContent).encryptedMessage === 'string'
         ) {
           Logger.log(
             `[MB CLIENT] Decrypting message from ${String(message.sender)}…`
@@ -1365,7 +1372,7 @@ export class MessageBoxClient {
           }, originator)
 
           const decryptedText = Utils.toUTF8(decrypted.plaintext)
-          message.body = tryParse(decryptedText)
+          message.body = this.tryParse(decryptedText)
         } else {
           // For non-encrypted messages, use the processed content
           message.body = messageContent ?? parsedBody
@@ -1388,6 +1395,37 @@ export class MessageBoxClient {
     return messages
   }
 
+  /**
+   * @method listMessagesLite
+   * @async
+   * @param {ListMessagesParams} params - Contains the `messageBox` to read from and the `host` to query.
+   * @returns {Promise<PeerMessage[]>} - Returns an array of decrypted `PeerMessage` objects with minimal processing.
+   *
+   * @description
+   * A lightweight variant of {@link listMessages} that fetches and decrypts messages
+   * from a specific host without performing:
+   * - Overlay host resolution
+   * - Payment acceptance or internalization
+   * - Cross-host deduplication
+   *
+   * This method:
+   * - Sends a direct POST request to the specified host's `/listMessages` endpoint.
+   * - Parses message bodies as JSON when possible.
+   * - Decrypts messages if they contain an `encryptedMessage` field, using AES-256-GCM via BRC-2-compliant ECDH key derivation.
+   * - Returns messages in the order provided by the host.
+   *
+   * This is intended for cases where you already know the host and need faster,
+   * simpler retrieval without the additional processing overhead of `listMessages`.
+   *
+   * @throws {Error} If the host returns an error status or decryption fails.
+   *
+   * @example
+   * const messages = await client.listMessagesLite({
+   *   messageBox: 'notifications',
+   *   host: 'https://messagebox.babbage.systems'
+   * })
+   * console.log(messages)
+   */
   async listMessagesLite ({ messageBox, host }: ListMessagesParams): Promise<PeerMessage[]> {
     const res = await this.authFetch.fetch(`${host as string}/listMessages`, {
       method: 'POST',
@@ -1452,6 +1490,121 @@ export class MessageBoxClient {
     return messages
   }
 
+  /**
+   * @method tryParse
+   * @private
+   * @param {string} raw - A raw string value that may contain JSON.
+   * @returns {any} - The parsed JavaScript object if valid JSON, or the original string if parsing fails.
+   *
+   * @description
+   * Attempts to parse a string as JSON. If the string is valid JSON, returns the parsed object;
+   * otherwise returns the original string unchanged.
+   *
+   * This method is used throughout the client to safely handle message bodies that may or may not be
+   * JSON-encoded without throwing parsing errors.
+   *
+   * @example
+   * tryParse('{"hello":"world"}') // → { hello: "world" }
+   * tryParse('plain text')        // → "plain text"
+   */
+  tryParse (raw: string): any {
+    try {
+      return JSON.parse(raw)
+    } catch {
+      return raw
+    }
+  }
+
+  /**
+   * @method acknowledgeNotification
+   * @async
+   * @param {PeerMessage} message - The peer message object to acknowledge.
+   * @returns {Promise<boolean>} - Resolves to `true` if the message included a recipient payment and it was successfully internalized, otherwise `false`.
+   *
+   * @description
+   * Acknowledges receipt of a specific notification message and, if applicable, processes any recipient
+   * payment contained within it.
+   *
+   * This method:
+   * 1. Calls `acknowledgeMessage()` to remove the message from the server's queue.
+   * 2. Checks the message body for embedded payment data.
+   * 3. If a recipient payment exists, attempts to internalize it into the wallet.
+   *
+   * This is a convenience wrapper for acknowledgment and payment handling specifically for messages
+   * representing notifications.
+   *
+   * @example
+   * const success = await client.acknowledgeNotification(message)
+   * console.log(success ? 'Payment received' : 'No payment or failed')
+   */
+  async acknowledgeNotification (message: PeerMessage): Promise<boolean> {
+    await this.acknowledgeMessage({ messageIds: [message.messageId] })
+
+    const parsedBody: unknown =
+      typeof message.body === 'string' ? this.tryParse(message.body) : message.body
+
+    let paymentData: Payment | undefined
+
+    if (
+      parsedBody != null &&
+      typeof parsedBody === 'object' &&
+      'message' in parsedBody
+    ) {
+      paymentData = (parsedBody as any).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 < 1) {
+          Logger.log(
+            '[MB CLIENT] No wallet payment outputs found in payment data'
+          )
+          return false
+        }
+
+        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'
+        })
+
+        if (internalizeResult.accepted) {
+          Logger.log(
+            '[MB CLIENT] Successfully internalized recipient payment'
+          )
+          return true
+        } else {
+          Logger.warn(
+            '[MB CLIENT] Recipient payment internalization was not accepted'
+          )
+          return false
+        }
+      } catch (paymentError) {
+        Logger.error(
+          '[MB CLIENT ERROR] Failed to internalize recipient payment:',
+          paymentError
+        )
+        return false
+      }
+    }
+    return false
+  }
+
   /**
    * @method acknowledgeMessage
    * @async
@@ -1473,8 +1626,7 @@ export class MessageBoxClient {
    * @example
    * await client.acknowledgeMessage({ messageIds: ['msg123', 'msg456'] })
    */
-  async acknowledgeMessage({ messageIds, host, originator }: AcknowledgeMessageParams): Promise<string> {
-    await this.assertInitialized()
+  async acknowledgeMessage ({ messageIds, host, originator }: AcknowledgeMessageParams): Promise<string> {
     if (!Array.isArray(messageIds) || messageIds.length === 0) {
       throw new Error('Message IDs array cannot be empty')
     }
@@ -1556,11 +1708,10 @@ export class MessageBoxClient {
    *   recipientFee: -1
    * })
    */
-  async setMessageBoxPermission(
+  async setMessageBoxPermission (
     params: SetMessageBoxPermissionParams,
     overrideHost?: string
   ): Promise<void> {
-    await this.assertInitialized()
     const finalHost = overrideHost ?? this.host
 
     Logger.log('[MB CLIENT] Setting messageBox permission...')
@@ -1604,12 +1755,10 @@ export class MessageBoxClient {
    *   sender: '03abc123...'
    * })
    */
-  async getMessageBoxPermission(
+  async getMessageBoxPermission (
     params: GetMessageBoxPermissionParams,
     overrideHost?: string
   ): Promise<MessageBoxPermission | null> {
-    await this.assertInitialized()
-
     const finalHost = overrideHost ?? await this.resolveHostForRecipient(params.recipient)
     const queryParams = new URLSearchParams({
       recipient: params.recipient,
@@ -1651,9 +1800,7 @@ export class MessageBoxClient {
    *   messageBox: 'notifications'
    * })
    */
-  async getMessageBoxQuote(params: GetQuoteParams, overrideHost?: string): Promise<MessageBoxQuote> {
-    await this.assertInitialized()
-
+  async getMessageBoxQuote (params: GetQuoteParams, overrideHost?: string): Promise<MessageBoxQuote> {
     const finalHost = overrideHost ?? await this.resolveHostForRecipient(params.recipient)
     const queryParams = new URLSearchParams({
       recipient: params.recipient,
@@ -1709,9 +1856,7 @@ export class MessageBoxClient {
    *   offset: 0
    * })
    */
-  async listMessageBoxPermissions(params?: ListPermissionsParams, overrideHost?: string): Promise<MessageBoxPermission[]> {
-    await this.assertInitialized()
-
+  async listMessageBoxPermissions (params?: ListPermissionsParams, overrideHost?: string): Promise<MessageBoxPermission[]> {
     const finalHost = overrideHost ?? this.host
     const queryParams = new URLSearchParams()
 
@@ -1770,7 +1915,7 @@ export class MessageBoxClient {
    * await client.allowNotificationsFromPeer('03abc123...') // Always allow
    * await client.allowNotificationsFromPeer('03def456...', 5) // Allow for 5 sats
    */
-  async allowNotificationsFromPeer(identityKey: PubKeyHex, recipientFee: number = 0, overrideHost?: string): Promise<void> {
+  async allowNotificationsFromPeer (identityKey: PubKeyHex, recipientFee: number = 0, overrideHost?: string): Promise<void> {
     await this.setMessageBoxPermission({
       messageBox: 'notifications',
       sender: identityKey,
@@ -1790,7 +1935,7 @@ export class MessageBoxClient {
    * @example
    * await client.denyNotificationsFromPeer('03spam123...')
    */
-  async denyNotificationsFromPeer(identityKey: PubKeyHex, overrideHost?: string): Promise<void> {
+  async denyNotificationsFromPeer (identityKey: PubKeyHex, overrideHost?: string): Promise<void> {
     await this.setMessageBoxPermission({
       messageBox: 'notifications',
       sender: identityKey,
@@ -1811,7 +1956,7 @@ export class MessageBoxClient {
    * const status = await client.checkPeerNotificationStatus('03abc123...')
    * console.log(status.allowed) // true/false
    */
-  async checkPeerNotificationStatus(identityKey: PubKeyHex, overrideHost?: string): Promise<MessageBoxPermission | null> {
+  async checkPeerNotificationStatus (identityKey: PubKeyHex, overrideHost?: string): Promise<MessageBoxPermission | null> {
     const myIdentityKey = await this.getIdentityKey()
     return await this.getMessageBoxPermission({
       recipient: myIdentityKey,
@@ -1831,7 +1976,7 @@ export class MessageBoxClient {
    * @example
    * const notifications = await client.listPeerNotifications()
    */
-  async listPeerNotifications(overrideHost?: string): Promise<MessageBoxPermission[]> {
+  async listPeerNotifications (overrideHost?: string): Promise<MessageBoxPermission[]> {
     return await this.listMessageBoxPermissions({ messageBox: 'notifications' }, overrideHost)
   }
 
@@ -1854,7 +1999,7 @@ export class MessageBoxClient {
    * // Send with maximum payment limit for safety
    * await client.sendNotification('03def456...', { title: 'Alert', body: 'Important update' }, 50)
    */
-  async sendNotification(
+  async sendNotification (
     recipient: PubKeyHex,
     body: string | object,
     overrideHost?: string
@@ -1890,12 +2035,10 @@ export class MessageBoxClient {
    *   deviceId: 'iPhone15Pro'
    * })
    */
-  async registerDevice(
+  async registerDevice (
     params: DeviceRegistrationParams,
     overrideHost?: string
   ): Promise<DeviceRegistrationResponse> {
-    await this.assertInitialized()
-
     if (params.fcmToken == null || params.fcmToken.trim() === '') {
       throw new Error('fcmToken is required and must be a non-empty string')
     }
@@ -1957,11 +2100,9 @@ export class MessageBoxClient {
    *   console.log(`Device: ${device.platform} - ${device.fcmToken}`)
    * })
    */
-  async listRegisteredDevices(
+  async listRegisteredDevices (
     overrideHost?: string
   ): Promise<RegisteredDevice[]> {
-    await this.assertInitialized()
-
     const finalHost = overrideHost ?? this.host
 
     Logger.log('[MB CLIENT] Listing registered devices...')
@@ -1989,22 +2130,39 @@ export class MessageBoxClient {
   // PRIVATE HELPER METHODS
   // ===========================
 
-  private static getStatusFromFee(fee: number): 'always_allow' | 'blocked' | 'payment_required' {
+  private static getStatusFromFee (fee: number): 'always_allow' | 'blocked' | 'payment_required' {
     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
-   */
-  private async createMessagePayment(
+  * @method createMessagePayment
+  * @private
+  * @param {string} recipient - Recipient's identity key.
+  * @param {MessageBoxQuote} quote - Quote object containing recipient and delivery fees.
+  * @param {string} [description='MessageBox delivery payment'] - Description for the payment action.
+  * @param {string} [originator] - Optional originator to use for wallet operations.
+  * @returns {Promise<Payment>} - Payment data including the transaction and remittance outputs.
+  *
+  * @description
+  * Constructs and signs a payment transaction covering both delivery and recipient fees for
+  * message delivery, based on a previously obtained quote.
+  *
+  * The transaction includes:
+  * - An optional delivery fee output for the MessageBox server.
+  * - An optional recipient fee output for the message recipient.
+  *
+  * Payment remittance metadata (derivation prefix/suffix, sender identity) is embedded to allow
+  * the payee to derive their private key and spend the output.
+  *
+  * @throws {Error} If no payment is required, key derivation fails, or the action creation fails.
+  *
+  * @example
+  * const payment = await client.createMessagePayment(recipientKey, quote)
+  * await client.sendMessage({ recipient, messageBox, body, payment })
+  */
+  private async createMessagePayment (
     recipient: string,
     quote: MessageBoxQuote,
     description: string = 'MessageBox delivery payment',