Skip to content

Commit 6e251c5

Browse files
NickOvtNickOvt
authored
fix(api-messages): Added all messages endpoints to api docs generation ZMS-140 (#666)
* added Update Message information api endpoint to api docs generation * fix response types * Added delete a message api endpoint to api docs generation * Added Delete all messages from a Mailbox api endpoint to api docs generation * fix some response types. Added delete an outbound message api endpoint to api docs generation
1 parent d983477 commit 6e251c5

File tree

1 file changed

+214
-53
lines changed

1 file changed

+214
-53
lines changed

‎lib/api/messages.js

+214-53
Original file line numberDiff line numberDiff line change
@@ -154,24 +154,12 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
154154
const putMessageHandler = async (req, res) => {
155155
res.charSet('utf-8');
156156

157-
const schema = Joi.object().keys({
158-
user: Joi.string().hex().lowercase().length(24).required(),
159-
mailbox: Joi.string().hex().lowercase().length(24).required(),
160-
moveTo: Joi.string().hex().lowercase().length(24),
161-
162-
message: Joi.string()
163-
.regex(/^\d+(,\d+)*$|^\d+:(\d+|\*)$/i)
164-
.required(),
165-
166-
seen: booleanSchema,
167-
deleted: booleanSchema,
168-
flagged: booleanSchema,
169-
draft: booleanSchema,
170-
expires: Joi.alternatives().try(Joi.date(), booleanSchema.allow(false)),
171-
metaData: metaDataSchema.label('metaData'),
172-
173-
sess: sessSchema,
174-
ip: sessIPSchema
157+
const { requestBody, queryParams, pathParams } = req.route.spec.validationObjs;
158+
159+
const schema = Joi.object({
160+
...requestBody,
161+
...queryParams,
162+
...pathParams
175163
});
176164

177165
const result = schema.validate(req.params, {
@@ -1694,20 +1682,139 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
16941682
})
16951683
);
16961684

1697-
server.put('/users/:user/mailboxes/:mailbox/messages/:message', tools.responseWrapper(putMessageHandler));
1698-
server.put('/users/:user/mailboxes/:mailbox/messages', tools.responseWrapper(putMessageHandler));
1685+
server.put(
1686+
{
1687+
path: '/users/:user/mailboxes/:mailbox/messages/:message',
1688+
tags: ['Messages'],
1689+
summary: 'Update message information with path param',
1690+
description: 'This method updates message flags and also allows to move messages to a different mailbox',
1691+
validationObjs: {
1692+
requestBody: {
1693+
moveTo: Joi.string().hex().lowercase().length(24).description('ID of the target Mailbox if you want to move messages'),
1694+
1695+
seen: booleanSchema.description('State of the \\Seen flag'),
1696+
deleted: booleanSchema.description('State of the \\Deleted flag'),
1697+
flagged: booleanSchema.description('State of the \\Flagged flag'),
1698+
draft: booleanSchema.description('State of the \\Draft flag'),
1699+
expires: Joi.alternatives()
1700+
.try(Joi.date(), booleanSchema.allow(false))
1701+
.description('Either expiration date or false to turn off autoexpiration'),
1702+
metaData: metaDataSchema.label('metaData').description('Optional metadata, must be an object or JSON formatted string'),
1703+
1704+
sess: sessSchema,
1705+
ip: sessIPSchema
1706+
},
1707+
queryParams: {},
1708+
pathParams: {
1709+
user: userId,
1710+
mailbox: mailboxId,
1711+
message: Joi.string()
1712+
.regex(/^\d+(,\d+)*$|^\d+:(\d+|\*)$/i)
1713+
.required()
1714+
.description(
1715+
'Message ID. Either singular or comma separated number (1,2,3) or colon separated range (3:15), or a range from UID to end (3:*)'
1716+
)
1717+
},
1718+
response: {
1719+
200: {
1720+
description: 'Success',
1721+
model: Joi.object({
1722+
success: successRes,
1723+
id: Joi.array()
1724+
.items(Joi.object({}))
1725+
.description(
1726+
'If messages were moved then lists new ID values. Array entry is an array with first element pointing to old ID and second to new ID'
1727+
),
1728+
mailbox: Joi.string().description('MoveTo mailbox address'),
1729+
updated: Joi.number().description('If messages were not moved, then indicates the number of updated messages')
1730+
})
1731+
}
1732+
}
1733+
}
1734+
},
1735+
tools.responseWrapper(putMessageHandler)
1736+
);
1737+
server.put(
1738+
{
1739+
path: '/users/:user/mailboxes/:mailbox/messages',
1740+
tags: ['Messages'],
1741+
summary: 'Update Message information',
1742+
description: 'This method updates message flags and also allows to move messages to a different mailbox',
1743+
validationObjs: {
1744+
requestBody: {
1745+
message: Joi.string()
1746+
.regex(/^\d+(,\d+)*$|^\d+:(\d+|\*)$/i)
1747+
.required()
1748+
.description(
1749+
'Message ID. Either singular or comma separated number (1,2,3) or colon separated range (3:15), or a range from UID to end (3:*)'
1750+
),
1751+
moveTo: Joi.string().hex().lowercase().length(24).description('ID of the target Mailbox if you want to move messages'),
1752+
1753+
seen: booleanSchema.description('State of the \\Seen flag'),
1754+
deleted: booleanSchema.description('State of the \\Deleted flag'),
1755+
flagged: booleanSchema.description('State of the \\Flagged flag'),
1756+
draft: booleanSchema.description('State of the \\Draft flag'),
1757+
expires: Joi.alternatives()
1758+
.try(Joi.date(), booleanSchema.allow(false))
1759+
.description('Either expiration date or false to turn off autoexpiration'),
1760+
metaData: metaDataSchema.label('metaData').description('Optional metadata, must be an object or JSON formatted string'),
1761+
1762+
sess: sessSchema,
1763+
ip: sessIPSchema
1764+
},
1765+
queryParams: {},
1766+
pathParams: {
1767+
user: userId,
1768+
mailbox: mailboxId
1769+
},
1770+
response: {
1771+
200: {
1772+
description: 'Success',
1773+
model: Joi.object({
1774+
success: successRes,
1775+
id: Joi.array()
1776+
.items(Joi.object({}))
1777+
.description(
1778+
'If messages were moved then lists new ID values. Array entry is an array with first element pointing to old ID and second to new ID'
1779+
),
1780+
mailbox: Joi.string().description('MoveTo mailbox address'),
1781+
updated: Joi.number().description('If messages were not moved, then indicates the number of updated messages')
1782+
})
1783+
}
1784+
}
1785+
}
1786+
},
1787+
tools.responseWrapper(putMessageHandler)
1788+
);
16991789

17001790
server.del(
1701-
'/users/:user/mailboxes/:mailbox/messages/:message',
1791+
{
1792+
path: '/users/:user/mailboxes/:mailbox/messages/:message',
1793+
tags: ['Messages'],
1794+
summary: 'Delete a Message',
1795+
validationObjs: {
1796+
requestBody: {},
1797+
queryParams: {
1798+
sess: sessSchema,
1799+
ip: sessIPSchema
1800+
},
1801+
pathParams: {
1802+
user: userId,
1803+
mailbox: mailboxId,
1804+
message: messageId
1805+
},
1806+
response: { 200: { description: 'Success', model: Joi.object({ success: successRes }) } }
1807+
}
1808+
},
17021809
tools.responseWrapper(async (req, res) => {
17031810
res.charSet('utf-8');
17041811

1705-
const schema = Joi.object().keys({
1706-
user: Joi.string().hex().lowercase().length(24).required(),
1707-
mailbox: Joi.string().hex().lowercase().length(24).required(),
1708-
message: Joi.number().min(1).required(),
1709-
sess: sessSchema,
1710-
ip: sessIPSchema
1812+
const { requestBody, queryParams, pathParams } = req.route.spec.validationObjs;
1813+
1814+
const schema = Joi.object({
1815+
...requestBody,
1816+
...queryParams,
1817+
...pathParams
17111818
});
17121819

17131820
const result = schema.validate(req.params, {
@@ -1775,18 +1882,44 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
17751882
);
17761883

17771884
server.del(
1778-
'/users/:user/mailboxes/:mailbox/messages',
1885+
{
1886+
path: '/users/:user/mailboxes/:mailbox/messages',
1887+
tags: ['Messages'],
1888+
summary: 'Delete all Messages from a Mailbox',
1889+
validationObjs: {
1890+
requestBody: {},
1891+
queryParams: {
1892+
async: booleanSchema.default(false).description('Schedule deletion task'),
1893+
1894+
skipArchive: booleanSchema.default(false).description('Skip archived messages'),
1895+
sess: sessSchema,
1896+
ip: sessIPSchema
1897+
},
1898+
pathParams: {
1899+
user: userId,
1900+
mailbox: mailboxId
1901+
},
1902+
response: {
1903+
200: {
1904+
description: 'Success',
1905+
model: Joi.object({
1906+
success: successRes,
1907+
deleted: Joi.number().required().description('Indicates the count of deleted messages'),
1908+
errors: Joi.number().required().description('Indicate the count of errors during the delete')
1909+
})
1910+
}
1911+
}
1912+
}
1913+
},
17791914
tools.responseWrapper(async (req, res) => {
17801915
res.charSet('utf-8');
17811916

1782-
const schema = Joi.object().keys({
1783-
user: Joi.string().hex().lowercase().length(24).required(),
1784-
mailbox: Joi.string().hex().lowercase().length(24).required(),
1785-
async: booleanSchema.default(false),
1917+
const { requestBody, queryParams, pathParams } = req.route.spec.validationObjs;
17861918

1787-
skipArchive: booleanSchema.default(false),
1788-
sess: sessSchema,
1789-
ip: sessIPSchema
1919+
const schema = Joi.object({
1920+
...requestBody,
1921+
...queryParams,
1922+
...pathParams
17901923
});
17911924

17921925
const result = schema.validate(req.params, {
@@ -1977,13 +2110,16 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
19772110
200: {
19782111
description: 'Success',
19792112
model: Joi.object({
1980-
success: Joi.boolean().description('Indicates successful response'),
2113+
success: successRes,
19812114
message: Joi.object({
1982-
id: Joi.number(),
1983-
malbox: Joi.string(),
1984-
size: Joi.number()
1985-
}).description('Message information'),
1986-
previousDeleted: Joi.boolean().description('Set if replacing a previous message was requested')
2115+
id: Joi.number().required().description('Message ID in mailbox'),
2116+
malbox: Joi.string().required().description('Mailbox ID the message was stored into'),
2117+
size: Joi.number().required().description('Size of the RFC822 formatted email')
2118+
})
2119+
.required()
2120+
.description('Message information'),
2121+
previousDeleted: booleanSchema.description('Set if replacing a previous message was requested'),
2122+
previousDeleteError: Joi.string().description('Previus delete error message')
19872123
})
19882124
}
19892125
}
@@ -2366,14 +2502,14 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
23662502
200: {
23672503
description: 'Success',
23682504
model: Joi.object({
2369-
success: Joi.boolean().description('Indicates successful response'),
2505+
success: successRes,
23702506
queueId: Joi.string().description('Message ID in outbound queue'),
23712507
forwarded: Joi.array()
23722508
.items(
23732509
Joi.object({
2374-
seq: Joi.string(),
2375-
type: Joi.string(),
2376-
value: Joi.string()
2510+
seq: Joi.string().required().description('Sequence ID'),
2511+
type: Joi.string().required().description('Target type'),
2512+
value: Joi.string().required().description('Target address')
23772513
}).$_setFlag('objectName', 'Forwarded')
23782514
)
23792515
.description('Information about forwarding targets')
@@ -2573,12 +2709,12 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
25732709
200: {
25742710
description: 'Success',
25752711
model: Joi.object({
2576-
success: booleanSchema.description('Indicates successful response').required(),
2712+
success: successRes,
25772713
queueId: Joi.string().description('Message ID in outbound queue').required(),
25782714
message: Joi.object({
25792715
id: Joi.number().description('Message ID in mailbox').required(),
25802716
mailbox: Joi.string().description('Mailbox ID the message was stored into').required(),
2581-
size: Joi.number().description('Size of the RFC822 formatted email')
2717+
size: Joi.number().required().description('Size of the RFC822 formatted email')
25822718
})
25832719
.description('Message information')
25842720
.$_setFlag('objectName', 'Message')
@@ -2938,15 +3074,40 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
29383074
);
29393075

29403076
server.del(
2941-
'/users/:user/outbound/:queueId',
3077+
{
3078+
path: '/users/:user/outbound/:queueId',
3079+
tags: ['Messages'],
3080+
summary: 'Delete an Outbound Message',
3081+
description: 'You can delete outbound emails that are still in queue. Queue ID can be found from the `outbound` property of a stored email.',
3082+
validationObjs: {
3083+
requestBody: {},
3084+
queryParams: {
3085+
sess: sessSchema,
3086+
ip: sessIPSchema
3087+
},
3088+
pathParams: {
3089+
user: userId,
3090+
queueId: Joi.string().hex().lowercase().min(18).max(24).required().description('Outbound queue ID of the message')
3091+
},
3092+
response: {
3093+
200: {
3094+
description: 'Success',
3095+
model: Joi.object({
3096+
success: successRes
3097+
})
3098+
}
3099+
}
3100+
}
3101+
},
29423102
tools.responseWrapper(async (req, res) => {
29433103
res.charSet('utf-8');
29443104

2945-
const schema = Joi.object().keys({
2946-
user: Joi.string().hex().lowercase().length(24).required(),
2947-
queueId: Joi.string().hex().lowercase().min(18).max(24).required(),
2948-
sess: sessSchema,
2949-
ip: sessIPSchema
3105+
const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
3106+
3107+
const schema = Joi.object({
3108+
...pathParams,
3109+
...queryParams,
3110+
...requestBody
29503111
});
29513112

29523113
const result = schema.validate(req.params, {

0 commit comments

Comments
 (0)