emailengine-app 2.68.1 → 2.70.0

package/lib/api-routes/blocklist-routes.js

@@ -0,0 +1,344 @@
+'use strict';
+
+const Boom = require('@hapi/boom');
+const Joi = require('joi');
+const { redis } = require('../db');
+const { Account } = require('../account');
+const getSecret = require('../get-secret');
+const { lists } = require('../lists');
+const { failAction } = require('../tools');
+const { handleError } = require('./route-helpers');
+const { accountIdSchema, errorResponses } = require('../schemas');
+const { REDIS_PREFIX } = require('../consts');
+
+async function init(args) {
+    const { server, call, CORS_CONFIG } = args;
+
+    server.route({
+        method: 'GET',
+        path: '/v1/blocklists',
+
+        async handler(request) {
+            try {
+                return await lists.list(request.query.page, request.query.pageSize);
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+
+        options: {
+            description: 'List blocklists',
+            notes: 'List blocklists with blocked addresses',
+            tags: ['api', 'Blocklists'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                query: Joi.object({
+                    page: Joi.number()
+                        .integer()
+                        .min(0)
+                        .max(1024 * 1024)
+                        .default(0)
+                        .example(0)
+                        .description('Page number (zero indexed, so use 0 for first page)')
+                        .label('PageNumber'),
+                    pageSize: Joi.number().integer().min(1).max(1000).default(20).example(20).description('How many entries per page').label('PageSize')
+                }).label('PageListsRequest')
+            },
+
+            response: {
+                schema: Joi.object({
+                    total: Joi.number().integer().example(120).description('How many matching entries').label('TotalNumber'),
+                    page: Joi.number().integer().example(0).description('Current page (0-based index)').label('PageNumber'),
+                    pages: Joi.number().integer().example(24).description('Total page count').label('PagesNumber'),
+
+                    blocklists: Joi.array()
+                        .items(
+                            Joi.object({
+                                listId: Joi.string().max(256).required().example('example').description('List ID'),
+                                count: Joi.number().integer().example(12).description('Count of blocked addresses in this list')
+                            }).label('BlocklistsResponseItem')
+                        )
+                        .label('BlocklistsEntries')
+                }).label('BlocklistsResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'GET',
+        path: '/v1/blocklist/{listId}',
+
+        async handler(request) {
+            try {
+                return await lists.listContent(request.params.listId, request.query.page, request.query.pageSize);
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+
+        options: {
+            description: 'List blocklist entries',
+            notes: 'List blocked addresses for a list',
+            tags: ['api', 'Blocklists'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    listId: Joi.string()
+                        .hostname()
+                        .example('test-list')
+                        .description('List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.')
+                        .label('ListID')
+                        .required()
+                }).label('BlocklistListRequest'),
+
+                query: Joi.object({
+                    page: Joi.number()
+                        .integer()
+                        .min(0)
+                        .max(1024 * 1024)
+                        .default(0)
+                        .example(0)
+                        .description('Page number (zero indexed, so use 0 for first page)')
+                        .label('PageNumber'),
+                    pageSize: Joi.number().integer().min(1).max(1000).default(20).example(20).description('How many entries per page').label('PageSize')
+                }).label('PageListsRequest')
+            },
+
+            response: {
+                schema: Joi.object({
+                    listId: Joi.string().max(256).required().example('example').description('List ID'),
+                    total: Joi.number().integer().example(120).description('How many matching entries').label('TotalNumber'),
+                    page: Joi.number().integer().example(0).description('Current page (0-based index)').label('PageNumber'),
+                    pages: Joi.number().integer().example(24).description('Total page count').label('PagesNumber'),
+                    addresses: Joi.array()
+                        .items(
+                            Joi.object({
+                                recipient: Joi.string().email().example('user@example.com').description('Listed email address').required(),
+                                account: accountIdSchema.required(),
+                                messageId: Joi.string().example('<test123@example.com>').description('Message ID'),
+                                source: Joi.string().example('api').description('Which mechanism was used to add the entry'),
+                                reason: Joi.string().example('block').description('Why this entry was added'),
+                                remoteAddress: Joi.string()
+                                    .ip({
+                                        version: ['ipv4', 'ipv6'],
+                                        cidr: 'optional'
+                                    })
+                                    .description('Which IP address triggered the entry'),
+                                userAgent: Joi.string().example('Mozilla/5.0 (Macintosh)').description('Which user agent triggered the entry'),
+                                created: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this entry was added or updated').required()
+                            }).label('BlocklistListResponseItem')
+                        )
+                        .label('BlocklistListEntries')
+                }).label('BlocklistListResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'POST',
+        path: '/v1/blocklist/{listId}',
+        async handler(request) {
+            let accountObject = new Account({
+                redis,
+                account: request.payload.account,
+                call,
+                secret: await getSecret(),
+                timeout: request.headers['x-ee-timeout']
+            });
+
+            try {
+                // throws if account does not exist
+                await accountObject.loadAccountData();
+
+                let added = await redis.eeListAdd(
+                    `${REDIS_PREFIX}lists:unsub:lists`,
+                    `${REDIS_PREFIX}lists:unsub:entries:${request.params.listId}`,
+                    request.params.listId,
+                    request.payload.recipient.toLowerCase().trim(),
+                    JSON.stringify({
+                        recipient: request.payload.recipient,
+                        account: request.payload.account,
+                        source: 'api',
+                        reason: request.payload.reason,
+                        remoteAddress: request.app.ip,
+                        userAgent: request.headers['user-agent'],
+                        created: new Date().toISOString()
+                    })
+                );
+
+                return {
+                    success: true,
+                    added: !!added
+                };
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+        options: {
+            description: 'Add to blocklist',
+            notes: 'Add an email address to a blocklist',
+            tags: ['api', 'Blocklists'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    listId: Joi.string()
+                        .hostname()
+                        .example('test-list')
+                        .description('List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.')
+                        .label('ListID')
+                        .required()
+                }).label('BlocklistListRequest'),
+
+                payload: Joi.object({
+                    account: accountIdSchema.required(),
+                    recipient: Joi.string().empty('').email().example('user@example.com').description('Email address to add to the list').required(),
+                    reason: Joi.string().empty('').default('block').description('Identifier for the blocking reason')
+                }).label('BlocklistListAddPayload')
+            },
+
+            response: {
+                schema: Joi.object({
+                    success: Joi.boolean().example(true).description('Was the request successful').label('BlocklistListAddSuccess'),
+                    added: Joi.boolean().example(true).description('Was the address added to the list')
+                }).label('BlocklistListAddResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'DELETE',
+        path: '/v1/blocklist/{listId}',
+
+        async handler(request) {
+            try {
+                let exists = await redis.hexists(`${REDIS_PREFIX}lists:unsub:lists`, request.params.listId);
+                if (!exists) {
+                    let message = 'Requested blocklist was not found';
+                    let error = Boom.boomify(new Error(message), { statusCode: 404 });
+                    throw error;
+                }
+
+                let deleted = await redis.eeListRemove(
+                    `${REDIS_PREFIX}lists:unsub:lists`,
+                    `${REDIS_PREFIX}lists:unsub:entries:${request.params.listId}`,
+                    request.params.listId,
+                    request.query.recipient.toLowerCase().trim()
+                );
+
+                return {
+                    deleted: !!deleted
+                };
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+        options: {
+            description: 'Remove from blocklist',
+            notes: 'Delete a blocked email address from a list',
+            tags: ['api', 'Blocklists'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    listId: Joi.string()
+                        .hostname()
+                        .example('test-list')
+                        .description('List ID. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.')
+                        .label('ListID')
+                        .required()
+                }).label('BlocklistListRequest'),
+
+                query: Joi.object({
+                    recipient: Joi.string().empty('').email().example('user@example.com').description('Email address to remove from the list').required()
+                }).label('RecipientQuery')
+            },
+
+            response: {
+                schema: Joi.object({
+                    deleted: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Was the address removed from the list')
+                }).label('DeleteBlocklistResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+}
+
+module.exports = init;

package/lib/api-routes/chat-routes.js

@@ -11,7 +11,7 @@ const util = require('util');
 
 const LOG_VERBOSE = getBoolean(process.env.EE_OPENAPI_VERBOSE);
 
-const { accountIdSchema, addressSchema, messageSpecialUseSchema, fromAddressSchema } = require('../schemas');
+const { accountIdSchema, messageSpecialUseSchema, responseAddressSchema, responseFromAddressSchema, errorResponses } = require('../schemas');
 
 function getDateValue(str) {
     try {
@@ -97,7 +97,7 @@ async function init(args) {
             startTime: sortingResponse?.start_time,
             endTime: sortingResponse?.end_time,
             model: sortingResponse?.model,
-            tokens: sortingResponse.tokens
+            tokens: sortingResponse?.tokens
         });
 
         // Step 2. Embeddings for the request
@@ -195,7 +195,7 @@ async function init(args) {
                 filter: vectorsFilter?.bool?.must
             });
             return {
-                success: true,
+                success: false,
                 answer: null,
                 processPipeline
             };
@@ -281,7 +281,7 @@ async function init(args) {
             message: 'Retrieved the answer',
             messages: queryResponse?.messageId?.length || 0,
             model: queryResponse?.model,
-            tokens: queryResponse.tokens
+            tokens: queryResponse?.tokens
         });
 
         if (queryResponse?.answer) {
@@ -360,7 +360,7 @@ async function init(args) {
         }
 
         return {
-            success: !!(responseData.answer || responseData.message),
+            success: !!responseData.answer,
             ...responseData,
             processPipeline
         };
@@ -399,9 +399,13 @@ async function init(args) {
         options: {
             description: 'Chat with emails',
             notes: 'Use OpenAI API and embeddings stored in the Document Store to "chat" with account emails. Requires Document Store indexing and the "Chat with emails" feature to be enabled.',
-            tags: ['Deprecated endpoints (Document Store)'],
+            tags: ['api', 'Deprecated endpoints (Document Store)'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -434,30 +438,44 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    success: Joi.boolean().example(true).description('Was the request successful').label('ReturnChatResponseSuccess'),
-                    answer: Joi.string().trim().example('Last tuesday').description('Chat response').label('ChatResponse').required(),
+                    success: Joi.boolean()
+                        .example(true)
+                        .description('Whether the LLM produced an answer. Can be false on a 200 response when no answer was found')
+                        .label('ReturnChatResponseSuccess'),
+                    answer: Joi.string()
+                        .trim()
+                        .allow(null)
+                        .example('Last tuesday')
+                        .description('Chat response. Not present (or null) when no answer was produced')
+                        .label('ChatResponse'),
                     messages: Joi.array()
                         .items(
                             Joi.object({
                                 id: Joi.string().example('AAAAAgAACrI').description('Unique identifier for the message').label('ChatMessageId'),
                                 path: Joi.string().example('INBOX').description('Folder this message was found from').label('ChatMessagePath'),
                                 date: Joi.date().iso().example('2023-09-29T10:03:49.000Z').description('Date of the email'),
-                                from: fromAddressSchema,
+                                from: responseFromAddressSchema,
 
                                 to: Joi.array()
-                                    .items(addressSchema)
+                                    .items(responseAddressSchema)
                                     .single()
                                     .description('List of addresses')
                                     .example([{ address: 'recipient@example.com' }])
-                                    .label('AddressList'),
-                                subject: Joi.string().allow('').example('What a wonderful message').description('Message subject'),
+                                    .label('ChatToAddressList'),
+                                cc: Joi.array().items(responseAddressSchema).single().description('List of CC addresses').label('ChatCcAddressList'),
+                                bcc: Joi.array().items(responseAddressSchema).single().description('List of BCC addresses').label('ChatBccAddressList'),
+                                subject: Joi.string().example('What a wonderful message').description('Message subject'),
                                 messageSpecialUse: messageSpecialUseSchema
                             })
                                 .description('Email that best matched the question')
                                 .label('ChatResponseMessage')
                         )
                         .description('Emails that best matched the question')
-                        .label('ChatResponseMessages')
+                        .label('ChatResponseMessages'),
+                    processPipeline: Joi.array()
+                        .items(Joi.object().unknown().label('ChatProcessPipelineStep'))
+                        .description('Diagnostic information about the chat processing steps, including timings and token usage')
+                        .label('ChatProcessPipeline')
                 }).label('ReturnChatResponse'),
                 failAction: 'log'
             }