From b3d48ce9b7e9e73154140987f911499872c633b4 Mon Sep 17 00:00:00 2001 From: Nikolai Ovtsinnikov Date: Tue, 23 Apr 2024 10:48:37 +0300 Subject: [PATCH 1/2] Added submission api endpoint to api docs generation --- lib/api/submit.js | 209 +++++++++++++++++++++++----------------------- 1 file changed, 105 insertions(+), 104 deletions(-) diff --git a/lib/api/submit.js b/lib/api/submit.js index 86561551..47af61c9 100644 --- a/lib/api/submit.js +++ b/lib/api/submit.js @@ -12,8 +12,11 @@ const tools = require('../tools'); const Maildropper = require('../maildropper'); const roles = require('../roles'); const Transform = require('stream').Transform; -const { sessSchema, sessIPSchema, booleanSchema } = require('../schemas'); +const { sessSchema, sessIPSchema, booleanSchema, metaDataSchema } = require('../schemas'); const { preprocessAttachments } = require('../data-url'); +const { userId, mailboxId } = require('../schemas/request/general-schemas'); +const { AddressOptionalName, AddressOptionalNameArray, Header, Attachment, ReferenceWithAttachments } = require('../schemas/request/messages-schemas'); +const { successRes } = require('../schemas/response/general-schemas'); class StreamCollect extends Transform { constructor() { @@ -620,113 +623,111 @@ module.exports = (db, server, messageHandler, userHandler, settingsHandler) => { const submitMessageWrapper = util.promisify(submitMessage); server.post( - { name: 'send', path: '/users/:user/submit' }, + { + name: 'send', + path: '/users/:user/submit', + tags: ['Submission'], + summary: 'Submit a Message for Delivery', + description: 'Use this method to send emails from a user account', + validationObjs: { + requestBody: { + mailbox: mailboxId, + from: AddressOptionalName.description('Addres for the From: header'), + replyTo: AddressOptionalName.description('Address for the Reply-To: header'), + to: Joi.array() + .items( + Joi.object({ + name: Joi.string().empty('').max(255).description('Name of the sender'), + address: Joi.string().email({ tlds: false }).failover('').required().description('Address of the sender') + }).$_setFlag('objectName', 'AddressOptionalName') + ) + .description('Addresses for the To: header'), + + cc: AddressOptionalNameArray.description('Addresses for the Cc: header'), + + bcc: AddressOptionalNameArray.description('Addresses for the Bcc: header'), + + headers: Joi.array() + .items(Header) + .description( + 'Custom headers for the message. If reference message is set then In-Reply-To and References headers are set automatically' + ), + subject: Joi.string() + .empty('') + .max(2 * 1024) + .description('Message subject. If not then resolved from Reference message'), + text: Joi.string() + .empty('') + .max(1024 * 1024) + .description('Plaintext message'), + html: Joi.string() + .empty('') + .max(1024 * 1024) + .description('HTML formatted message'), + attachments: Joi.array().items(Attachment).description('Attachments for the message'), + + meta: metaDataSchema.label('metaData').description('Optional metadata, must be an object or JSON formatted string'), + sess: sessSchema, + ip: sessIPSchema, + reference: ReferenceWithAttachments.description( + 'Optional referenced email. If uploaded message is a reply draft and relevant fields are not provided then these are resolved from the message to be replied to' + ), + // if true then treat this message as a draft + isDraft: booleanSchema.default(false).description('Is the message a draft or not'), + // if set then this message is based on a draft that should be deleted after processing + draft: Joi.object() + .keys({ + mailbox: mailboxId, + id: Joi.number().required().description('Message ID') + }) + .description('Draft message to base this one on'), + sendTime: Joi.date().description('Send time'), + uploadOnly: booleanSchema.default(false).description('If true only uploads the message but does not send it'), + envelope: Joi.object() + .keys({ + from: AddressOptionalName.description('Addres for the From: header'), + to: Joi.array().items( + Joi.object() + .keys({ + name: Joi.string().empty('').max(255).description('Name of the sender'), + address: Joi.string().email({ tlds: false }).required().description('Address of the sender') + }) + .description('Addresses for the To: header') + ) + }) + .description('Optional envelope') + }, + queryParams: {}, + pathParams: { + user: userId + }, + response: { + 200: { + description: 'Success', + model: Joi.object({ + success: successRes, + message: Joi.object({ + mailbox: Joi.string().required().description('Mailbox ID the message was stored to'), + id: Joi.number().description('Message ID in the Mailbox').required(), + queueId: Joi.string().required().description('Queue ID in MTA') + }) + .required() + .description('Information about submitted Message') + .$_setFlag('objectName', 'MessageWithQueueId') + }) + } + } + } + }, tools.responseWrapper(async (req, res) => { res.charSet('utf-8'); - const schema = Joi.object().keys({ - user: Joi.string().hex().lowercase().length(24).required(), - - mailbox: Joi.string().hex().lowercase().length(24), - - reference: Joi.object().keys({ - mailbox: Joi.string().hex().lowercase().length(24).required(), - id: Joi.number().required(), - action: Joi.string().valid('reply', 'replyAll', 'forward').required() - }), - - // if true then treat this message as a draft - isDraft: booleanSchema.default(false), - - // if set then this message is based on a draft that should be deleted after processing - draft: Joi.object().keys({ - mailbox: Joi.string().hex().lowercase().length(24).required(), - id: Joi.number().required() - }), - - uploadOnly: booleanSchema.default(false), + const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs; - sendTime: Joi.date(), - - envelope: Joi.object().keys({ - from: Joi.object().keys({ - name: Joi.string().empty('').max(255), - address: Joi.string().email({ tlds: false }).required() - }), - to: Joi.array().items( - Joi.object().keys({ - name: Joi.string().empty('').max(255), - address: Joi.string().email({ tlds: false }).required() - }) - ) - }), - - from: Joi.object().keys({ - name: Joi.string().empty('').max(255), - address: Joi.string().email({ tlds: false }).required() - }), - - replyTo: Joi.object().keys({ - name: Joi.string().empty('').max(255), - address: Joi.string().email({ tlds: false }).required() - }), - - to: Joi.array().items( - Joi.object().keys({ - name: Joi.string().empty('').max(255), - address: Joi.string().email({ tlds: false }).required() - }) - ), - - cc: Joi.array().items( - Joi.object().keys({ - name: Joi.string().empty('').max(255), - address: Joi.string().email({ tlds: false }).required() - }) - ), - - bcc: Joi.array().items( - Joi.object().keys({ - name: Joi.string().empty('').max(255), - address: Joi.string().email({ tlds: false }).required() - }) - ), - - headers: Joi.array().items( - Joi.object().keys({ - key: Joi.string().empty('').max(255), - value: Joi.string() - .empty('') - .max(100 * 1024) - }) - ), - - subject: Joi.string() - .empty('') - .max(2 * 1024), - text: Joi.string() - .empty('') - .max(1024 * 1024), - html: Joi.string() - .empty('') - .max(1024 * 1024), - - attachments: Joi.array().items( - Joi.object().keys({ - filename: Joi.string().empty('').max(255), - - contentType: Joi.string().empty('').max(255), - contentTransferEncoding: Joi.string().empty('').trim().lowercase(), - contentDisposition: Joi.string().empty('').trim().lowercase().valid('inline', 'attachment'), - cid: Joi.string().empty('').max(255), - - encoding: Joi.string().empty('').default('base64'), - content: Joi.string().required() - }) - ), - meta: Joi.object().unknown(true), - sess: sessSchema, - ip: sessIPSchema + const schema = Joi.object({ + ...pathParams, + ...requestBody, + ...queryParams }); // extract embedded attachments from HTML From 4777e16fd9ac1039326dd740116e4aed00cfadd1 Mon Sep 17 00:00:00 2001 From: Nikolai Ovtsinnikov Date: Thu, 9 May 2024 10:01:14 +0300 Subject: [PATCH 2/2] added users updates api endpoin to api docs generation --- lib/api/updates.js | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/lib/api/updates.js b/lib/api/updates.js index d8d5c38f..6aef39e8 100644 --- a/lib/api/updates.js +++ b/lib/api/updates.js @@ -7,18 +7,39 @@ const tools = require('../tools'); const roles = require('../roles'); const base32 = require('base32.js'); const { sessSchema, sessIPSchema } = require('../schemas'); +const { userId } = require('../schemas/request/general-schemas'); module.exports = (db, server, notifier) => { server.get( - '/users/:user/updates', + { + path: '/users/:user/updates', + tags: ['Users'], + summary: 'Open change stream', + description: + 'This api call returns an EventSource response. Listen on this stream to get notifications about changes in messages and mailboxes. Returned events are JSON encoded strings', + validationObjs: { + requestBody: {}, + queryParams: { + 'Last-Event-ID': Joi.string().hex().lowercase().length(24).description('Last event ID header as query param'), + sess: sessSchema, + ip: sessIPSchema + }, + pathParams: { + user: userId + }, + response: { 200: { description: 'Success', model: Joi.string() } } + }, + responseType: 'text/event-stream' + }, tools.responseWrapper(async (req, res) => { res.charSet('utf-8'); - const schema = Joi.object().keys({ - user: Joi.string().hex().lowercase().length(24).required(), - 'Last-Event-ID': Joi.string().hex().lowercase().length(24), - sess: sessSchema, - ip: sessIPSchema + const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs; + + const schema = Joi.object({ + ...pathParams, + ...requestBody, + ...queryParams }); if (req.header('Last-Event-ID')) {