@bopen-io/messagebox-server 1.1.5 → 1.2.1

package/src/routes/permissions/getQuote.ts

@@ -0,0 +1,192 @@
+import { Response } from 'express'
+import { PublicKey } from '@bsv/sdk'
+import { Logger, log } from '../../utils/logger.js'
+import { AuthRequest } from '@bsv/auth-express-middleware'
+import { getRecipientFee, getServerDeliveryFee } from '../../utils/messagePermissions.js'
+
+export interface GetQuoteRequest extends AuthRequest {
+  query: {
+    recipient: string | string[] // identityKey of recipient or array of recipients
+    messageBox?: string           // messageBox type
+  }
+}
+
+/**
+ * @swagger
+ * /permissions/quote:
+ *   get:
+ *     summary: Get message delivery quote(s)
+ *     description: Get pricing information for sending messages to one or many recipients' message boxes
+ *     tags:
+ *       - Permissions
+ *     parameters:
+ *       - in: query
+ *         name: recipient
+ *         required: true
+ *         schema:
+ *           oneOf:
+ *             - type: string
+ *             - type: array
+ *               items:
+ *                 type: string
+ *         description: identityKey of the recipient, or multiple recipients by repeating the parameter (?recipient=A&recipient=B)
+ *       - in: query
+ *         name: messageBox
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: messageBox type
+ *     responses:
+ *       200:
+ *         description: Quote(s) retrieved successfully
+ *       400:
+ *         description: Invalid request parameters
+ *       401:
+ *         description: Authentication required
+ *       500:
+ *         description: Internal server error
+ */
+export default {
+  type: 'get',
+  path: '/permissions/quote',
+  func: async (req: GetQuoteRequest, res: Response): Promise<Response> => {
+    try {
+      Logger.log('[DEBUG] Processing message quote request')
+      log.debug({ operation: 'permissions.quote' }, 'Processing message quote request')
+
+      // Validate authentication (the caller is the SENDER)
+      const sender = req.auth?.identityKey
+      if (sender == null) {
+        Logger.log('[DEBUG] Authentication required for message quote')
+        return res.status(401).json({
+          status: 'error',
+          code: 'ERR_AUTHENTICATION_REQUIRED',
+          description: 'Authentication required.'
+        })
+      }
+
+      const { recipient, messageBox } = req.query
+
+      // Required params
+      if (recipient == null || messageBox == null) {
+        Logger.log('[DEBUG] Missing required parameters for message quote')
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_MISSING_PARAMETERS',
+          description: 'recipient and messageBox parameters are required.'
+        })
+      }
+
+      // Normalize recipients to array (preserve order)
+      const recipients: string[] = Array.isArray(recipient) ? recipient : [recipient]
+
+      if (recipients.length === 0) {
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_MISSING_PARAMETERS',
+          description: 'At least one recipient is required.'
+        })
+      }
+
+      // Validate each recipient public key
+      const invalidIdx: number[] = []
+      for (let i = 0; i < recipients.length; i++) {
+        try {
+          PublicKey.fromString(recipients[i])
+        } catch {
+          invalidIdx.push(i)
+        }
+      }
+      if (invalidIdx.length > 0) {
+        Logger.log('[DEBUG] Invalid recipient public key format in array')
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_PUBLIC_KEY',
+          description: `Invalid recipient public key at index(es): ${invalidIdx.join(', ')}.`
+        })
+      }
+
+      // Delivery fee for this messageBox (applies per message/recipient)
+      const perMessageDeliveryFee = await getServerDeliveryFee(messageBox)
+
+      // Single-recipient path → keep legacy response shape for compatibility
+      if (recipients.length === 1) {
+        const recipientKey = recipients[0]
+        const recipientFee = await getRecipientFee(recipientKey, sender, messageBox)
+
+        return res.status(200).json({
+          status: 'success',
+          description: 'Message delivery quote generated.',
+          quote: {
+            deliveryFee: perMessageDeliveryFee,
+            recipientFee
+          }
+        })
+      }
+
+      // Multi-recipient path → compute per-recipient, plus aggregates
+      const quotesByRecipient: Array<{
+        recipient: string
+        messageBox: string
+        deliveryFee: number
+        recipientFee: number
+        status: 'blocked' | 'always_allow' | 'payment_required'
+      }> = []
+
+      const blockedRecipients: string[] = []
+      let totalRecipientFees = 0
+      let totalDeliveryFees = 0
+
+      // Helper to map fee -> status
+      const feeToStatus = (fee: number): 'blocked' | 'always_allow' | 'payment_required' => {
+        if (fee === -1) return 'blocked'
+        if (fee === 0) return 'always_allow'
+        return 'payment_required'
+      }
+
+      for (const r of recipients) {
+        const recipientFee = await getRecipientFee(r, sender, messageBox)
+        const status = feeToStatus(recipientFee)
+
+        quotesByRecipient.push({
+          recipient: r,
+          messageBox,
+          deliveryFee: perMessageDeliveryFee,
+          recipientFee,
+          status
+        })
+
+        // Aggregate: count deliveryFee per intended message, and recipientFee if not blocked
+        totalDeliveryFees += perMessageDeliveryFee
+        if (recipientFee === -1) {
+          blockedRecipients.push(r)
+        } else {
+          totalRecipientFees += recipientFee
+        }
+      }
+
+      const totals = {
+        deliveryFees: totalDeliveryFees,
+        recipientFees: totalRecipientFees,
+        // If any are blocked, caller may want to handle those separately.
+        // We still provide a full monetary total for non-blocked recipients:
+        totalForPayableRecipients: totalDeliveryFees + totalRecipientFees
+      }
+
+      return res.status(200).json({
+        status: 'success',
+        description: `Message delivery quotes generated for ${recipients.length} recipients.`,
+        quotesByRecipient,
+        totals,
+        blockedRecipients
+      })
+    } catch (error) {
+      Logger.error('[ERROR] Internal Server Error in message quote:', error)
+      return res.status(500).json({
+        status: 'error',
+        code: 'ERR_INTERNAL',
+        description: 'An internal error has occurred.'
+      })
+    }
+  }
+}

package/src/routes/permissions/index.ts

@@ -0,0 +1,12 @@
+// Export all permission-related routes
+import setPermission from './setPermission.js'
+import getPermission from './getPermission.js'
+import getQuote from './getQuote.js'
+import listPermissions from './listPermissions.js'
+
+export const permissionRoutes = [
+  setPermission,
+  getPermission,
+  getQuote,
+  listPermissions
+]

package/src/routes/permissions/listPermissions.ts

@@ -0,0 +1,202 @@
+import { Response } from 'express'
+import { AuthRequest } from '@bsv/auth-express-middleware'
+import { Logger } from '../../utils/logger.js'
+import { runtimeDeps } from '../../runtimeDeps.js'
+
+export interface ListPermissionsRequest extends AuthRequest {
+  query: {
+    messageBox?: string // Optional messageBox filter
+    limit?: string // Optional pagination limit
+    offset?: string // Optional pagination offset
+    createdAtOrder?: string // Optional sort order for created_at ('asc' | 'desc')
+  }
+}
+
+/**
+ * @swagger
+ * /permissions/list:
+ *   get:
+ *     summary: List message permissions for the authenticated user
+ *     description: Retrieve all permissions set by the authenticated user with optional filtering and pagination
+ *     tags:
+ *       - Permissions
+ *     parameters:
+ *       - in: query
+ *         name: messageBox
+ *         required: false
+ *         schema:
+ *           type: string
+ *         description: Optional messageBox type filter (e.g., 'notifications', 'inbox')
+ *       - in: query
+ *         name: limit
+ *         required: false
+ *         schema:
+ *           type: integer
+ *           minimum: 1
+ *           maximum: 1000
+ *           default: 100
+ *         description: Maximum number of permissions to return
+ *       - in: query
+ *         name: offset
+ *         required: false
+ *         schema:
+ *           type: integer
+ *           minimum: 0
+ *           default: 0
+ *         description: Number of permissions to skip for pagination
+ *       - in: query
+ *         name: createdAtOrder
+ *         required: false
+ *         schema:
+ *           type: string
+ *           enum: ['asc', 'desc']
+ *           default: 'desc'
+ *         description: Sort order for created_at date (asc=oldest first, desc=newest first)
+ *     responses:
+ *       200:
+ *         description: Permissions retrieved successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: 'success'
+ *                 permissions:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       sender:
+ *                         type: string
+ *                         nullable: true
+ *                         description: Sender identity key (null for box-wide defaults)
+ *                       messageBox:
+ *                         type: string
+ *                         description: MessageBox type
+ *                       recipientFee:
+ *                         type: integer
+ *                         description: Fee setting (-1=block all, 0=always allow, >0=satoshi amount)
+ *                       created_at:
+ *                         type: string
+ *                         format: date-time
+ *                       updated_at:
+ *                         type: string
+ *                         format: date-time
+ *                 total_count:
+ *                   type: integer
+ *                   description: Total number of permissions (useful for pagination)
+ *       400:
+ *         description: Invalid query parameters
+ *       401:
+ *         description: Unauthorized - authentication required
+ *       500:
+ *         description: Internal server error
+ */
+export default {
+  type: 'get',
+  path: '/permissions/list',
+  /**
+   * List message permissions for the authenticated user
+   *
+   * @param {ListPermissionsRequest} req - Authenticated request with query parameters
+   * @param {Response} res - Express response object
+   * @returns {Promise<Response>} JSON response with permissions list
+   */
+  func: async (req: ListPermissionsRequest, res: Response): Promise<Response> => {
+    Logger.log('[DEBUG] Processing /permissions/list request...')
+
+    try {
+      // Validate authentication
+      if (req.auth?.identityKey == null) {
+        return res.status(401).json({
+          status: 'error',
+          code: 'ERR_UNAUTHORIZED',
+          description: 'Authentication required'
+        })
+      }
+
+      // Parse and validate query parameters
+      const { messageBox, limit: limitStr, offset: offsetStr, createdAtOrder } = req.query
+
+      const limit = limitStr != null ? Number.parseInt(limitStr, 10) : 100
+      const offset = offsetStr != null ? Number.parseInt(offsetStr, 10) : 0
+      const sortOrder = createdAtOrder === 'asc' ? 'asc' : 'desc' // Default to 'desc'
+
+      // Validate pagination parameters
+      if (Number.isNaN(limit) || limit < 1 || limit > 1000) {
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_LIMIT',
+          description: 'Limit must be a number between 1 and 1000'
+        })
+      }
+
+      if (Number.isNaN(offset) || offset < 0) {
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_OFFSET',
+          description: 'Offset must be a non-negative number'
+        })
+      }
+
+      // Validate identity key format
+      const recipientKey = req.auth.identityKey
+
+      Logger.log(`[DEBUG] Listing permissions for recipient: ${recipientKey}, messageBox: ${messageBox ?? 'all'}, limit: ${limit}, offset: ${offset}, createdAtOrder: ${sortOrder}`)
+
+      // Build base query
+      let query = runtimeDeps.knex('message_permissions')
+        .select([
+          'sender',
+          'message_box',
+          'recipient_fee',
+          'created_at',
+          'updated_at'
+        ])
+        .where('recipient', recipientKey)
+        .orderBy([
+          { column: 'message_box', order: 'asc' },
+          { column: 'sender', order: 'asc', nulls: 'first' }, // Box-wide (null) first
+          { column: 'created_at', order: sortOrder }
+        ])
+
+      // Apply messageBox filter if provided
+      if (messageBox != null) {
+        query = query.where('message_box', messageBox)
+      }
+
+      // Get total count for pagination info (before applying limit/offset)
+      const countQuery = query.clone().clearSelect().clearOrder().count('* as count')
+      const [{ count: totalCount }] = await countQuery
+      const total = Number.parseInt(String(totalCount), 10)
+
+      // Apply pagination
+      const permissions = await query
+        .limit(limit)
+        .offset(offset)
+
+      Logger.log(`[DEBUG] Found ${permissions.length} permissions (${total} total)`)
+
+      return res.status(200).json({
+        status: 'success',
+        permissions: permissions.map(p => ({
+          sender: p.sender, // null for box-wide defaults
+          messageBox: p.message_box,
+          recipientFee: p.recipient_fee,
+          createdAt: p.created_at,
+          updatedAt: p.updated_at
+        })),
+        totalCount: total
+      })
+    } catch (error) {
+      Logger.error('[ERROR] Error listing permissions:', error)
+      return res.status(500).json({
+        status: 'error',
+        code: 'ERR_LIST_PERMISSIONS_FAILED',
+        description: 'Failed to list permissions'
+      })
+    }
+  }
+}

package/src/routes/permissions/setPermission.ts

@@ -0,0 +1,155 @@
+import { Response } from 'express'
+import { PublicKey } from '@bsv/sdk'
+import { Logger } from '../../utils/logger.js'
+import { AuthRequest } from '@bsv/auth-express-middleware'
+import { setMessagePermission } from '../../utils/messagePermissions.js'
+
+export interface SetPermissionRequestType extends AuthRequest {
+  body: {
+    sender?: string // Optional - if not provided, sets box-wide default
+    messageBox: string
+    recipientFee: number
+  }
+}
+
+/**
+ * @swagger
+ * /permissions/set:
+ *   post:
+ *     summary: Set message permission for a sender/box combination or box-wide default
+ *     description: Set permission level for receiving messages. If sender is provided, sets permission for that specific sender. If sender is omitted, sets box-wide default for all senders.
+ *     tags:
+ *       - Permissions
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - messageBox
+ *               - recipientFee
+ *             properties:
+ *               sender:
+ *                 type: string
+ *                 description: identityKey of the sender (optional - if omitted, sets box-wide default for all senders)
+ *               messageBox:
+ *                 type: string
+ *                 description: messageBox type (e.g., 'notifications', 'inbox')
+ *               recipientFee:
+ *                 type: integer
+ *                 description: Fee level (-1=blocked, 0=always allow, >0=satoshi amount required)
+ *     responses:
+ *       200:
+ *         description: Permission successfully set/updated
+ *       400:
+ *         description: Invalid request data
+ *       401:
+ *         description: Authentication required
+ *       500:
+ *         description: Internal server error
+ */
+export default {
+  type: 'post',
+  path: '/permissions/set',
+  func: async (req: SetPermissionRequestType, res: Response): Promise<Response> => {
+    try {
+      Logger.log('[DEBUG] Processing set message permission request')
+
+      // Validate authentication
+      const recipient = req.auth?.identityKey
+      if (recipient == null) {
+        Logger.log('[DEBUG] Authentication required for set permission')
+        return res.status(401).json({
+          status: 'error',
+          code: 'ERR_AUTHENTICATION_REQUIRED',
+          description: 'Authentication required.'
+        })
+      }
+
+      const { sender, messageBox, recipientFee } = req.body
+
+      // Validate request body (sender is optional)
+      if (messageBox == null || typeof recipientFee !== 'number') {
+        Logger.log('[DEBUG] Invalid request body for set permission')
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_REQUEST',
+          description: 'messageBox (string) and recipientFee (number) are required. sender (string) is optional for box-wide settings.'
+        })
+      }
+
+      // Validate sender public key format only 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.'
+          })
+        }
+      }
+
+      // Validate recipientFee value
+      if (!Number.isInteger(recipientFee)) {
+        Logger.log('[DEBUG] Invalid recipientFee value - must be integer')
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_FEE_VALUE',
+          description: 'recipientFee must be an integer (-1, 0, or positive number).'
+        })
+      }
+
+      // Validate messageBox value
+      if (typeof messageBox !== 'string' || messageBox.trim() === '') {
+        Logger.log('[DEBUG] Invalid messageBox value')
+        return res.status(400).json({
+          status: 'error',
+          code: 'ERR_INVALID_MESSAGE_BOX',
+          description: 'messageBox must be a non-empty string.'
+        })
+      }
+
+      // Set the message permission (convert undefined sender to null for box-wide)
+      const success = await setMessagePermission(recipient, sender ?? null, messageBox, recipientFee)
+
+      if (success == null) {
+        return res.status(500).json({
+          status: 'error',
+          code: 'ERR_DATABASE_ERROR',
+          description: 'Failed to update message permission.'
+        })
+      }
+
+      const isBoxWide = sender == null
+      Logger.log(`[DEBUG] Successfully updated message permission: ${sender ?? 'BOX-WIDE'} -> ${recipient} (${messageBox}), fee: ${recipientFee}`)
+
+      let description: string
+      const senderText = isBoxWide ? 'all senders' : sender
+      const actionText = isBoxWide ? 'Box-wide default for' : 'Messages from'
+
+      if (recipientFee === -1) {
+        description = `${actionText} ${senderText} to ${messageBox} ${isBoxWide ? 'is' : 'are'} now blocked.`
+      } else if (recipientFee === 0) {
+        description = `${actionText} ${senderText} to ${messageBox} ${isBoxWide ? 'is' : 'are'} now always allowed.`
+      } else {
+        description = `${actionText} ${senderText} to ${messageBox} now require${isBoxWide ? 's' : ''} ${recipientFee} satoshis.`
+      }
+
+      return res.status(200).json({
+        status: 'success',
+        description
+      })
+    } catch (error) {
+      Logger.error('[ERROR] Internal Server Error in set permission:', error)
+      return res.status(500).json({
+        status: 'error',
+        code: 'ERR_INTERNAL',
+        description: 'An internal error has occurred.'
+      })
+    }
+  }
+}