@bopen-io/messagebox-server 1.1.5 → 1.2.0

package/src/routes/acknowledgeMessage.ts

@@ -0,0 +1,153 @@
+/**
+ * @file acknowledgeMessage.ts
+ * @description
+ * Express route to allow a client to acknowledge receipt of one or more messages.
+ * Acknowledged messages are permanently removed from the database for the
+ * authenticated identity key (recipient).
+ *
+ * This is used in the MessageBox system to clear delivered messages once received
+ * and handled on the client side (e.g., after syncing or displaying them).
+ */
+
+import { Request, Response } from 'express'
+import { Logger } from '../utils/logger.js'
+import { runtimeDeps } from '../runtimeDeps.js'
+
+/**
+ * @interface AcknowledgeRequest
+ * @extends Request
+ * @description Represents an authenticated request body for acknowledging messages.
+ */
+export interface AcknowledgeRequest extends Request {
+  auth: { identityKey: string }
+  body: { messageIds?: string[] }
+}
+
+/**
+ * @openapi
+ * /acknowledgeMessage:
+ *   post:
+ *     summary: Acknowledge receipt of one or more messages
+ *     description: |
+ *       Removes acknowledged messages from the database for the authenticated identity key.
+ *       This is used after a client has received and handled messages.
+ *     tags:
+ *       - Message
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               messageIds:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                 description: Array of message IDs to acknowledge
+ *     responses:
+ *       200:
+ *         description: Successfully acknowledged messages
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: success
+ *       400:
+ *         description: Invalid input or message not found
+ *       500:
+ *         description: Internal server error
+ */
+
+/**
+ * @exports
+ * Route definition for acknowledging MessageBox messages.
+ * This object is consumed by the Express route loader to register the endpoint.
+ */
+export default {
+  type: 'post',
+  path: '/acknowledgeMessage',
+  get knex () { return runtimeDeps.knex },
+  summary: 'Use this route to acknowledge a message has been received',
+  parameters: {
+    messageIds: ['3301']
+  },
+  exampleResponse: {
+    status: 'success'
+  },
+  errors: [],
+
+  /**
+   * @function func
+   * @description
+   * Express route handler that processes a POST request to acknowledge messages.
+   * Deletes messages from the database where:
+   *   - recipient matches the authenticated identity key
+   *   - messageId matches one or more of the provided IDs
+   *
+   * Returns:
+   *   - 200 success if deletion occurs
+   *   - 400 if no messages were found or input is invalid
+   *   - 500 on internal error
+   *
+   * @param {AcknowledgeRequest} req - Express request object containing auth and message IDs
+   * @param {Response} res - Express response object
+   * @returns {Promise<Response>} JSON response with status and optional error codes
+   */
+  func: async (req: AcknowledgeRequest, res: Response): Promise<Response> => {
+    try {
+      const { messageIds } = req.body
+
+      Logger.log('[SERVER] acknowledgeMessage called for messageIds:', messageIds, 'by', req.auth.identityKey)
+
+      // Validate request: must be a non-empty array of strings
+      if ((messageIds == null) || (Array.isArray(messageIds) && messageIds.length === 0)) {
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_MESSAGE_ID_REQUIRED',
+          description: 'Please provide the ID of the message(s) to acknowledge!'
+        })
+      }
+
+      if (!Array.isArray(messageIds) || messageIds.some(id => typeof id !== 'string')) {
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_MESSAGE_ID',
+          description: 'Message IDs must be formatted as an array of strings!'
+        })
+      }
+
+      // Delete acknowledged messages for this recipient from the database
+      const deleted = await runtimeDeps.knex('messages')
+        .where({ recipient: req.auth.identityKey })
+        .whereIn('messageId', Array.isArray(messageIds) ? messageIds : [messageIds])
+        .del()
+
+      // No matching messages found
+      if (deleted === 0) {
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_ACKNOWLEDGMENT',
+          description: 'Message not found!'
+        })
+      }
+
+      // Deletion failed unexpectedly
+      if (deleted < 0) {
+        throw new Error('Deletion failed')
+      }
+
+      return res.status(200).json({ status: 'success' })
+    } catch (e) {
+      Logger.error(e)
+      return res.status(500).json({
+        status: 'error',
+        code: 'ERR_INTERNAL_ERROR',
+        description: 'An internal error has occurred while acknowledging the message'
+      })
+    }
+  }
+}

package/src/routes/index.ts

@@ -0,0 +1,17 @@
+import sendMessage from './sendMessage.js'
+import listMessages from './listMessages.js'
+import acknowledgeMessage from './acknowledgeMessage.js'
+import registerDevice from './registerDevice.js'
+import listDevices from './listDevices.js'
+import { permissionRoutes } from './permissions/index.js'
+
+// Explicitly type the exported arrays to avoid type inference issues
+export const preAuth: Array<{ type: string, path: string, func: Function }> = []
+export const postAuth: Array<{ type: string, path: string, func: Function }> = [
+  sendMessage,
+  listMessages,
+  acknowledgeMessage,
+  registerDevice,
+  listDevices,
+  ...permissionRoutes
+]

package/src/routes/listDevices.ts

@@ -0,0 +1,80 @@
+import { Response } from 'express'
+import { Logger } from '../utils/logger.js'
+import { AuthRequest } from '@bsv/auth-express-middleware'
+import { runtimeDeps } from '../runtimeDeps.js'
+
+export interface RegisteredDevice {
+  id: number
+  deviceId: string | null
+  platform: string | null
+  fcmToken: string
+  active: boolean
+  createdAt: string
+  updatedAt: string
+  lastUsed: string
+}
+
+export default {
+  type: 'get',
+  path: '/devices',
+  func: async (req: AuthRequest, res: Response): Promise<Response> => {
+    try {
+      Logger.log('[DEBUG] Processing list devices request')
+
+      // Validate authentication
+      const identityKey = req.auth?.identityKey
+      if (identityKey == null) {
+        Logger.log('[DEBUG] Authentication required for listing devices')
+        return res.status(401).json({
+          status: 'error',
+          code: 'ERR_AUTHENTICATION_REQUIRED',
+          description: 'Authentication required.'
+        })
+      }
+
+      try {
+        // Query devices for the authenticated user
+        const devices = await runtimeDeps.knex('device_registrations')
+          .select([
+            'id',
+            'device_id as deviceId',
+            'platform',
+            'fcm_token as fcmToken',
+            'active',
+            'created_at as createdAt',
+            'updated_at as updatedAt',
+            'last_used as lastUsed'
+          ])
+          .where('identity_key', identityKey)
+          .orderBy('updated_at', 'desc')
+
+        Logger.log(`[DEBUG] Found ${devices.length} registered devices for ${identityKey}`)
+
+        return res.status(200).json({
+          status: 'success',
+          devices: devices.map(device => ({
+            ...device,
+            // Truncate FCM token for security (show only last 10 characters)
+            fcmToken: `...${device.fcmToken.slice(-10)}`
+          }))
+        })
+
+      } catch (dbError: any) {
+        Logger.error('[ERROR] Database error during device listing:', dbError)
+        return res.status(500).json({
+          status: 'error',
+          code: 'ERR_DATABASE_ERROR',
+          description: 'Failed to retrieve devices.'
+        })
+      }
+
+    } catch (error) {
+      Logger.error('[ERROR] Internal Server Error in listDevices:', error)
+      return res.status(500).json({
+        status: 'error',
+        code: 'ERR_INTERNAL',
+        description: 'An internal error has occurred.'
+      })
+    }
+  }
+}

package/src/routes/listMessages.ts

@@ -0,0 +1,195 @@
+/**
+ * @file listMessages.ts
+ * @description
+ * This route allows an authenticated user to retrieve messages from a specific named messageBox.
+ *
+ * Messages are only returned if the authenticated identity has access to the specified messageBox.
+ * If the messageBox does not exist, an empty message list is returned.
+ *
+ * Typical usage: Inbox or queue retrieval for real-time or deferred message delivery.
+ */
+
+import { Response } from 'express'
+import { AuthRequest } from '@bsv/auth-express-middleware'
+import { log } from '../utils/logger.js'
+import { runtimeDeps } from '../runtimeDeps.js'
+
+/**
+ * @interface ListMessagesRequest
+ * @extends Request
+ * @description Extends Express Request to include `auth` identity and expected `messageBox` body property.
+ */
+interface ListMessagesRequest extends AuthRequest {
+  body: { messageBox?: string }
+}
+
+/**
+ * @openapi
+ * /listMessages:
+ *   post:
+ *     summary: Retrieve messages from a specific messageBox
+ *     description: |
+ *       Returns all stored messages for the specified messageBox that belong to the authenticated identity.
+ *       If the box does not exist or has no messages, an empty array is returned.
+ *     tags:
+ *       - Message
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               messageBox:
+ *                 type: string
+ *                 description: The name of the messageBox to retrieve messages from
+ *     responses:
+ *       200:
+ *         description: Successfully retrieved messages (can be empty)
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: success
+ *                 messages:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       messageId:
+ *                         type: string
+ *                       body:
+ *                         type: string
+ *                       sender:
+ *                         type: string
+ *                       createdAt:
+ *                         type: string
+ *                         format: date-time
+ *                       updatedAt:
+ *                         type: string
+ *                         format: date-time
+ *       400:
+ *         description: Invalid or missing messageBox name
+ *       500:
+ *         description: Internal server/database error
+ */
+
+/**
+ * @exports
+ * Route definition used by the Express router to expose the `/listMessages` POST endpoint.
+ * Responsible for querying stored messages from a messageBox owned by the authenticated user.
+ */
+export default {
+  type: 'post',
+  path: '/listMessages',
+  get knex () { return runtimeDeps.knex },
+  summary: 'Use this route to list messages from your messageBox.',
+  parameters: {
+    messageBox: 'The name of the messageBox you would like to list messages from.'
+  },
+  exampleResponse: {
+    status: 'success',
+    messages: [
+      {
+        messageId: '3301',
+        body: '{}',
+        sender: '028d37b941208cd6b8a4c28288eda5f2f16c2b3ab0fcb6d13c18b47fe37b971fc1'
+      }
+    ]
+  },
+  /**
+ * @function func
+ * @description
+ * Express handler for listing stored messages in a specified messageBox.
+ *
+ * Input:
+ * - `req.body.messageBox`: Name of the messageBox to retrieve messages from.
+ * - `req.auth.identityKey`: Authenticated user’s public identity key.
+ *
+ * Behavior:
+ * - Checks if the specified messageBox exists for the identity.
+ * - If found, returns all messages in that messageBox.
+ * - If not found, returns an empty array.
+ * - Normalizes all message bodies to strings for consistent output.
+ *
+ * Output:
+ * - 200 with `{ status: 'success', messages: [...] }`
+ * - 400 if input is missing or malformed.
+ * - 500 on internal server/database errors.
+ *
+ * @param {ListMessagesRequest} req - Authenticated request containing the messageBox name
+ * @param {Response} res - Express response object
+ * @returns {Promise<Response>} JSON response containing message records or an error
+ */
+  func: async (req: ListMessagesRequest, res: Response): Promise<Response> => {
+    try {
+      const { messageBox } = req.body
+
+      // Validate a messageBox is provided and is a string
+      if (messageBox == null || messageBox === '') {
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_MESSAGEBOX_REQUIRED',
+          description: 'Please provide the name of a valid MessageBox!'
+        })
+      }
+
+      if (typeof messageBox !== 'string') {
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_MESSAGEBOX',
+          description: 'MessageBox name must be a string!'
+        })
+      }
+
+      // Find the messageBox ID for this user
+      const [messageBoxRecord] = await runtimeDeps.knex('messageBox')
+        .where({
+          identityKey: req.auth?.identityKey,
+          type: messageBox
+        })
+        .select('messageBoxId')
+
+      // Return empty array if no messageBox was found
+      if (messageBoxRecord === undefined) {
+        return res.status(200).json({
+          status: 'success',
+          messages: []
+        })
+      }
+
+      // Retrieve all messages associated with the messageBox
+      const messages = await runtimeDeps.knex('messages')
+        .where({
+          recipient: req.auth?.identityKey,
+          messageBoxId: messageBoxRecord.messageBoxId
+        })
+        .select('messageId', 'body', 'sender', 'created_at', 'updated_at')
+
+      // Normalize all message bodies to strings and convert to camelCase
+      const formattedMessages = messages.map(message => ({
+        messageId: message.messageId,
+        body: typeof message.body === 'string' ? message.body : JSON.stringify(message.body),
+        sender: message.sender,
+        createdAt: message.created_at,
+        updatedAt: message.updated_at
+      }))
+
+      // Return a list of matching messages
+      return res.status(200).json({
+        status: 'success',
+        messages: formattedMessages
+      })
+    } catch (e) {
+      log.error({ operation: 'messages.list', outcome: 'error', err: e }, 'Failed to list messages')
+      return res.status(500).json({
+        status: 'error',
+        code: 'ERR_INTERNAL_ERROR',
+        description: 'An internal error has occurred while listing messages.'
+      })
+    }
+  }
+}

package/src/routes/permissions/getPermission.ts

@@ -0,0 +1,152 @@
+import { Response } from 'express'
+import { PublicKey } from '@bsv/sdk'
+import { Logger } from '../../utils/logger.js'
+import { AuthRequest } from '@bsv/auth-express-middleware'
+import { runtimeDeps } from '../../runtimeDeps.js'
+
+export interface GetPermissionRequest extends AuthRequest {
+  query: {
+    sender?: string // identityKey of sender to check
+    messageBox?: string // messageBox type to check
+  }
+}
+
+/**
+ * @swagger
+ * /permissions/get:
+ *   get:
+ *     summary: Get message permission for a sender/box combination
+ *     description: Retrieve the permission setting for a specific sender and message box combination
+ *     tags:
+ *       - Permissions
+ *     parameters:
+ *       - in: query
+ *         name: sender
+ *         required: false
+ *         schema:
+ *           type: string
+ *         description: identityKey of the sender to check (omit for box-wide default)
+ *       - in: query
+ *         name: messageBox
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: messageBox type to check
+ *     responses:
+ *       200:
+ *         description: Permission setting retrieved successfully (or undefined if not set)
+ *       400:
+ *         description: Invalid request parameters
+ *       401:
+ *         description: Authentication required
+ *       500:
+ *         description: Internal server error
+ */
+export default {
+  type: 'get',
+  path: '/permissions/get',
+  func: async (req: GetPermissionRequest, res: Response): Promise<Response> => {
+    try {
+      Logger.log('[DEBUG] Processing get message permission request')
+
+      // Validate authentication
+      if (req.auth?.identityKey == null) {
+        Logger.log('[DEBUG] Authentication required for get permission')
+        return res.status(401).json({
+          status: 'error',
+          code: 'ERR_AUTHENTICATION_REQUIRED',
+          description: 'Authentication required.'
+        })
+      }
+
+      const { sender, messageBox } = req.query
+
+      // Validate required parameters
+      if (messageBox == null) {
+        Logger.log('[DEBUG] Missing required parameters for get permission')
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_MISSING_PARAMETERS',
+          description: 'messageBox parameter is required.'
+        })
+      }
+
+      // Validate sender public key format if provided
+      if (sender != null) {
+        try {
+          PublicKey.fromString(sender)
+        } catch (error) {
+          Logger.log('[DEBUG] Invalid sender public key format')
+          return res.status(400).json({
+            status: 'error',
+            code: 'ERR_INVALID_PUBLIC_KEY',
+            description: 'Invalid sender public key format.'
+          })
+        }
+      }
+
+      const recipient = req.auth.identityKey
+
+      // Get message permission directly from database
+      const whereClause: any = {
+        recipient,
+        message_box: messageBox
+      }
+
+      // Add sender condition (null for box-wide, specific sender for sender-specific)
+      if (sender != null) {
+        whereClause.sender = sender
+      } else {
+        whereClause.sender = null
+      }
+
+      const permission = await runtimeDeps.knex('message_permissions')
+        .where(whereClause)
+        .select('recipient_fee', 'created_at', 'updated_at')
+        .first()
+
+      Logger.log(`[DEBUG] Permission record for ${sender ?? 'box-wide'} -> ${recipient} (${messageBox}): ${JSON.stringify(permission)}`)
+
+      if (permission != null) {
+        // Helper function to determine status from recipient fee
+        const getStatusFromFee = (fee: number): 'always_allow' | 'blocked' | 'payment_required' => {
+          if (fee === -1) return 'blocked'
+          if (fee === 0) return 'always_allow'
+          return 'payment_required'
+        }
+
+        // Permission is set, return it
+        return res.status(200).json({
+          status: 'success',
+          description: sender != null
+            ? `Permission setting found for sender ${sender} to ${messageBox}.`
+            : `Box-wide permission setting found for ${messageBox}.`,
+          permission: {
+            sender: sender ?? null,
+            messageBox,
+            recipientFee: permission.recipient_fee,
+            status: getStatusFromFee(permission.recipient_fee),
+            createdAt: permission.created_at.toISOString(),
+            updatedAt: permission.updated_at.toISOString()
+          }
+        })
+      } else {
+        // No permission set, return undefined
+        return res.status(200).json({
+          status: 'success',
+          description: sender != null
+            ? `No permission setting found for sender ${sender} to ${messageBox}.`
+            : `No box-wide permission setting found for ${messageBox}.`,
+          permission: undefined
+        })
+      }
+    } catch (error) {
+      Logger.error('[ERROR] Internal Server Error in get permission:', error)
+      return res.status(500).json({
+        status: 'error',
+        code: 'ERR_INTERNAL',
+        description: 'An internal error has occurred.'
+      })
+    }
+  }
+}