krikkert/habitica
1
0
Fork 0
mirror of https://github.com/HabitRPG/habitica.git synced 2025-12-16 22:27:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): Define resource not found errors and permissions

Browse Source
This commit is contained in:
Blade Barringer
2016-10-03 21:24:38 -05:00
parent 52f4e5f37d
commit 2dc0958678
13 changed files with 468 additions and 247 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
website/server/controllers/api-v3/challenges.js
View File

@@ -20,12 +20,19 @@ import csvStringify from '../../libs/csvStringify';
let api = {}; let api = {};
/**
* @apiDefine ChallengeNotFound
* @apiError (404) {NotFound} ChallengeNotFound The specified challenge could not be found.
*/
/** /**
* @api {post} /api/v3/challenges Create a new challenge * @api {post} /api/v3/challenges Create a new challenge
* @apiName CreateChallenge * @apiName CreateChallenge
* @apiGroup Challenge * @apiGroup Challenge
* *
* @apiSuccess {Object} data The newly created challenge * @apiSuccess {Object} data The newly created challenge
*
* @apiUse GroupNotFound
*/ */
api.createChallenge = { api.createChallenge = {
method: 'POST', method: 'POST',
@@ -116,6 +123,8 @@ api.createChallenge = {
* @apiParam {UUID} challengeId The challenge _id * @apiParam {UUID} challengeId The challenge _id
* *
* @apiSuccess {Object} data The challenge the user joined * @apiSuccess {Object} data The challenge the user joined
*
* @apiUse ChallengeNotFound
*/ */
api.joinChallenge = { api.joinChallenge = {
method: 'POST', method: 'POST',
@@ -162,6 +171,8 @@ api.joinChallenge = {
* @apiParam {UUID} challengeId The challenge _id * @apiParam {UUID} challengeId The challenge _id
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiUse ChallengeNotFound
*/ */
api.leaveChallenge = { api.leaveChallenge = {
method: 'POST', method: 'POST',
@@ -244,6 +255,8 @@ api.getUserChallenges = {
* @apiParam {UUID} groupId The group _id * @apiParam {UUID} groupId The group _id
* *
* @apiSuccess {Array} data An array of challenges sorted with official challenges first, followed by the challenges in order from newest to oldest * @apiSuccess {Array} data An array of challenges sorted with official challenges first, followed by the challenges in order from newest to oldest
*
* @apiUse GroupNotFound
*/ */
api.getGroupChallenges = { api.getGroupChallenges = {
method: 'GET', method: 'GET',
@@ -286,6 +299,8 @@ api.getGroupChallenges = {
* @apiParam {UUID} challengeId The challenge _id * @apiParam {UUID} challengeId The challenge _id
* *
* @apiSuccess {Object} data The challenge object * @apiSuccess {Object} data The challenge object
*
* @apiUse ChallengeNotFound
*/ */
api.getChallenge = { api.getChallenge = {
method: 'GET', method: 'GET',
@@ -328,6 +343,8 @@ api.getChallenge = {
* @apiParam {UUID} challengeId The challenge _id * @apiParam {UUID} challengeId The challenge _id
* *
* @apiSuccess {String} challenge A csv file * @apiSuccess {String} challenge A csv file
*
* @apiUse ChallengeNotFound
*/ */
api.exportChallengeCsv = { api.exportChallengeCsv = {
method: 'GET', method: 'GET',
@@ -400,6 +417,8 @@ api.exportChallengeCsv = {
* @apiParam {UUID} challengeId The challenge _id * @apiParam {UUID} challengeId The challenge _id
* *
* @apiSuccess {Object} data The updated challenge * @apiSuccess {Object} data The updated challenge
*
* @apiUse ChallengeNotFound
*/ */
api.updateChallenge = { api.updateChallenge = {
method: 'PUT', method: 'PUT',
@@ -445,6 +464,8 @@ api.updateChallenge = {
* @apiParam {UUID} challengeId The _id for the challenge to delete * @apiParam {UUID} challengeId The _id for the challenge to delete
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiUse ChallengeNotFound
*/ */
api.deleteChallenge = { api.deleteChallenge = {
method: 'DELETE', method: 'DELETE',
@@ -477,6 +498,8 @@ api.deleteChallenge = {
* @apiParam {UUID} winnerId The _id of the winning user * @apiParam {UUID} winnerId The _id of the winning user
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiUse ChallengeNotFound
*/ */
api.selectChallengeWinner = { api.selectChallengeWinner = {
method: 'POST', method: 'POST',

27
website/server/controllers/api-v3/chat.js
View File

@@ -17,6 +17,11 @@ const FLAG_REPORT_EMAILS = nconf.get('FLAG_REPORT_EMAIL').split(',').map((email)
return { email, canSend: true }; return { email, canSend: true };
}); });
/**
* @apiDefine MessageNotFound
* @apiError (404) {NotFound} MessageNotFound The specified message could not be found.
*/
let api = {}; let api = {};
async function getAuthorEmailFromMessage (message) { async function getAuthorEmailFromMessage (message) {
@@ -43,6 +48,8 @@ async function getAuthorEmailFromMessage (message) {
* @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted) * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
* *
* @apiSuccess {Array} data An array of chat messages * @apiSuccess {Array} data An array of chat messages
*
* @apiUse GroupNotFound
*/ */
api.getChat = { api.getChat = {
method: 'GET', method: 'GET',
@@ -73,6 +80,8 @@ api.getChat = {
* @apiParam {UUID} previousMsg Query parameter - The previous chat message which will force a return of the full group chat * @apiParam {UUID} previousMsg Query parameter - The previous chat message which will force a return of the full group chat
* *
* @apiSuccess data An array of chat messages if a new message was posted after previousMsg, otherwise the posted message * @apiSuccess data An array of chat messages if a new message was posted after previousMsg, otherwise the posted message
*
* @apiUse GroupNotFound
*/ */
api.postChat = { api.postChat = {
method: 'POST', method: 'POST',
@@ -136,6 +145,9 @@ api.postChat = {
* @apiParam {UUID} chatId The chat message _id * @apiParam {UUID} chatId The chat message _id
* *
* @apiSuccess {Object} data The liked chat message * @apiSuccess {Object} data The liked chat message
*
* @apiUse GroupNotFound
* @apiUse MessageNotFound
*/ */
api.likeChat = { api.likeChat = {
method: 'POST', method: 'POST',
@@ -156,6 +168,7 @@ api.likeChat = {
let message = _.find(group.chat, {id: req.params.chatId}); let message = _.find(group.chat, {id: req.params.chatId});
if (!message) throw new NotFound(res.t('messageGroupChatNotFound')); if (!message) throw new NotFound(res.t('messageGroupChatNotFound'));
// TODO correct this error type
if (message.uuid === user._id) throw new NotFound(res.t('messageGroupChatLikeOwnMessage')); if (message.uuid === user._id) throw new NotFound(res.t('messageGroupChatLikeOwnMessage'));
let update = {$set: {}}; let update = {$set: {}};
@@ -192,8 +205,8 @@ api.likeChat = {
* @apiSuccess {UUID} data.uuid The user id of the author of the message * @apiSuccess {UUID} data.uuid The user id of the author of the message
* @apiSuccess {String} data.user The username of the author of the message * @apiSuccess {String} data.user The username of the author of the message
* *
* @apiError GroupNotFound Group could not be found or you don't have access * @apiUse GroupNotFound
* @apiError ChatNotFound Chat message with specified id could not be found * @apiUse MessageNotFound
* @apiError FlagOwnMessage Chat messages cannot be flagged by the author of the message * @apiError FlagOwnMessage Chat messages cannot be flagged by the author of the message
* @apiError AlreadyFlagged Chat messages cannot be flagged more than once by a user * @apiError AlreadyFlagged Chat messages cannot be flagged more than once by a user
*/ */
@@ -225,6 +238,7 @@ api.flagChat = {
// Log user ids that have flagged the message // Log user ids that have flagged the message
if (!message.flags) message.flags = {}; if (!message.flags) message.flags = {};
// TODO fix error type
if (message.flags[user._id] && !user.contributor.admin) throw new NotFound(res.t('messageGroupChatFlagAlreadyReported')); if (message.flags[user._id] && !user.contributor.admin) throw new NotFound(res.t('messageGroupChatFlagAlreadyReported'));
message.flags[user._id] = true; message.flags[user._id] = true;
update.$set[`chat.$.flags.${user._id}`] = true; update.$set[`chat.$.flags.${user._id}`] = true;
@@ -282,7 +296,7 @@ api.flagChat = {
/** /**
* @api {post} /api/v3/groups/:groupId/chat/:chatId/clearflags Clear flags * @api {post} /api/v3/groups/:groupId/chat/:chatId/clearflags Clear flags
* @apiDescription Resets the flag count on a chat message. Retains the id of the user's that have flagged the message. (Only visible to moderators) * @apiDescription Resets the flag count on a chat message. Retains the id of the user's that have flagged the message. (Only visible to moderators)
* @apiPermission Moderators * @apiPermission Admin
* @apiName ClearFlags * @apiName ClearFlags
* @apiGroup Chat * @apiGroup Chat
* *
@@ -291,9 +305,9 @@ api.flagChat = {
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
* *
* @apiUse GroupNotFound
* @apiUse MessageNotFound
* @apiError MustBeAdmin Must be a moderator to use this route * @apiError MustBeAdmin Must be a moderator to use this route
* @apiError GroupNotFound Group could not be found or you don't have access
* @apiError ChatNotFound Chat message with specified id could not be found
*/ */
api.clearChatFlags = { api.clearChatFlags = {
method: 'Post', method: 'Post',
@@ -404,6 +418,9 @@ api.seenChat = {
* *
* @apiSuccess data The updated chat array or an empty object if no message was posted after previousMsg * @apiSuccess data The updated chat array or an empty object if no message was posted after previousMsg
* @apiSuccess {Object} data An empty object when the previous message was deleted * @apiSuccess {Object} data An empty object when the previous message was deleted
*
* @apiUse GroupNotFound
* @apiUse MessageNotFound
*/ */
api.deleteChat = { api.deleteChat = {
method: 'DELETE', method: 'DELETE',

22
website/server/controllers/api-v3/debug.js
View File

@@ -4,13 +4,23 @@ import { BadRequest } from '../../libs/errors';
import { content } from '../../../common'; import { content } from '../../../common';
import _ from 'lodash'; import _ from 'lodash';
/**
* @apiDefine Development Development
* These routes only exist while Habitica is in development mode. (Such as running a local instance on your computer)
*/
/**
* @apiDefine Developers Local Development
* This route only exists when developing Habitica in non-production environment.
*/
let api = {}; let api = {};
/** /**
* @api {post} /api/v3/debug/add-ten-gems Add ten gems to the current user * @api {post} /api/v3/debug/add-ten-gems Add ten gems to the current user
* @apiDescription Only available in development mode.
* @apiName AddTenGems * @apiName AddTenGems
* @apiGroup Development * @apiGroup Development
* @apiPermission Developers
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*/ */
@@ -31,9 +41,9 @@ api.addTenGems = {
/** /**
* @api {post} /api/v3/debug/add-hourglass Add Hourglass to the current user * @api {post} /api/v3/debug/add-hourglass Add Hourglass to the current user
* @apiDescription Only available in development mode.
* @apiName AddHourglass * @apiName AddHourglass
* @apiGroup Development * @apiGroup Development
* @apiPermission Developers
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*/ */
@@ -54,9 +64,9 @@ api.addHourglass = {
/** /**
* @api {post} /api/v3/debug/set-cron Set lastCron for user * @api {post} /api/v3/debug/set-cron Set lastCron for user
* @apiDescription Only available in development mode.
* @apiName setCron * @apiName setCron
* @apiGroup Development * @apiGroup Development
* @apiPermission Developers
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*/ */
@@ -78,9 +88,9 @@ api.setCron = {
/** /**
* @api {post} /api/v3/debug/make-admin Sets contributor.admin to true * @api {post} /api/v3/debug/make-admin Sets contributor.admin to true
* @apiDescription Only available in development mode.
* @apiName setCron * @apiName setCron
* @apiGroup Development * @apiGroup Development
* @apiPermission Developers
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*/ */
@@ -101,9 +111,9 @@ api.makeAdmin = {
/** /**
* @api {post} /api/v3/debug/modify-inventory Manipulate user's inventory * @api {post} /api/v3/debug/modify-inventory Manipulate user's inventory
* @apiDescription Only available in development mode.
* @apiName modifyInventory * @apiName modifyInventory
* @apiGroup Development * @apiGroup Development
* @apiPermission Developers
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*/ */
@@ -141,9 +151,9 @@ api.modifyInventory = {
/** /**
* @api {post} /api/v3/debug/quest-progress Artificially accelerate quest progress * @api {post} /api/v3/debug/quest-progress Artificially accelerate quest progress
* @apiDescription Only available in development mode.
* @apiName questProgress * @apiName questProgress
* @apiGroup Development * @apiGroup Development
* @apiPermission Developers
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*/ */

31
website/server/controllers/api-v3/groups.js
View File

@@ -21,6 +21,21 @@ import { encrypt } from '../../libs/encryption';
import { sendNotification as sendPushNotification } from '../../libs/pushNotifications'; import { sendNotification as sendPushNotification } from '../../libs/pushNotifications';
import pusher from '../../libs/pusher'; import pusher from '../../libs/pusher';
/**
* @apiDefine GroupNotFound
* @apiError (404) {NotFound} GroupNotFound The specified group could not be found.
*/
/**
* @apiDefine PartyNotFound
* @apiError (404) {NotFound} PartyNotFound The user's party could not be found.
*/
/**
* @apiDefine GroupLeader Group Leader
* The group leader can use this route.
*/
let api = {}; let api = {};
/** /**
@@ -123,6 +138,8 @@ api.getGroups = {
* @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted) * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
* *
* @apiSuccess {Object} data The group object * @apiSuccess {Object} data The group object
*
* @apiUse GroupNotFound
*/ */
api.getGroup = { api.getGroup = {
method: 'GET', method: 'GET',
@@ -160,6 +177,10 @@ api.getGroup = {
* @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted) * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
* *
* @apiSuccess {Object} data The updated group * @apiSuccess {Object} data The updated group
*
* @apiUse GroupNotFound
*
* @apiPermission GroupLeader
*/ */
api.updateGroup = { api.updateGroup = {
method: 'PUT', method: 'PUT',
@@ -203,6 +224,8 @@ api.updateGroup = {
* @apiParam {UUID} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted) * @apiParam {UUID} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
* *
* @apiSuccess {Object} data The joined group * @apiSuccess {Object} data The joined group
*
* @apiUse GroupNotFound
*/ */
api.joinGroup = { api.joinGroup = {
method: 'POST', method: 'POST',
@@ -361,6 +384,8 @@ api.rejectGroupInvite = {
* @apiParam {String="remove-all","keep-all"} keep Query parameter - Whether to keep or not challenges' tasks. Defaults to keep-all * @apiParam {String="remove-all","keep-all"} keep Query parameter - Whether to keep or not challenges' tasks. Defaults to keep-all
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiUse GroupNotFound
*/ */
api.leaveGroup = { api.leaveGroup = {
method: 'POST', method: 'POST',
@@ -420,6 +445,10 @@ function _sendMessageToRemoved (group, removedUser, message) {
* @apiParam {String} message Query parameter - The message to send to the removed members * @apiParam {String} message Query parameter - The message to send to the removed members
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiPermission GroupLeader
*
* @apiUse GroupNotFound
*/ */
api.removeGroupMember = { api.removeGroupMember = {
method: 'POST', method: 'POST',
@@ -669,7 +698,7 @@ async function _inviteByEmail (invite, group, inviter, req, res) {
* ] * ]
* } * }
* *
* @apiError GroupNotFound The group could not be found * @apiUse GroupNotFound
* @apiError InvalidInvitationParams An error relating to the data sent in `emails` and/or `uuids` * @apiError InvalidInvitationParams An error relating to the data sent in `emails` and/or `uuids`
* @apiError TooManyInvites A max of 100 invites (combined emails and user ids) can be sent out at a time * @apiError TooManyInvites A max of 100 invites (combined emails and user ids) can be sent out at a time
*/ */

14
website/server/controllers/api-v3/hall.js
View File

@@ -6,6 +6,11 @@ import {
} from '../../libs/errors'; } from '../../libs/errors';
import _ from 'lodash'; import _ from 'lodash';
/**
* @apiDefine Admin Moderators
* Contributors of tier 8 or higher can use this route.
*/
let api = {}; let api = {};
/** /**
@@ -78,11 +83,14 @@ const heroAdminFields = 'contributor balance profile.name purchased items auth f
/** /**
* @api {get} /api/v3/hall/heroes/:heroId Get any user ("hero") given the UUID * @api {get} /api/v3/hall/heroes/:heroId Get any user ("hero") given the UUID
* @apiDescription Must be an admin to make this request.
* @apiName GetHero * @apiName GetHero
* @apiGroup Hall * @apiGroup Hall
* *
* @apiSuccess {Object} data The user object * @apiSuccess {Object} data The user object
*
* @apiPermission Admin
*
* @apiUse UserNotFound
*/ */
api.getHero = { api.getHero = {
method: 'GET', method: 'GET',
@@ -120,6 +128,10 @@ const gemsPerTier = {1: 3, 2: 3, 3: 3, 4: 4, 5: 4, 6: 4, 7: 4, 8: 0, 9: 0};
* @apiGroup Hall * @apiGroup Hall
* *
* @apiSuccess {Object} data The updated user object * @apiSuccess {Object} data The updated user object
*
* @apiPermission Admin
*
* @apiUse UserNotFound
*/ */
api.updateHero = { api.updateHero = {
method: 'PUT', method: 'PUT',

17
website/server/controllers/api-v3/members.js
View File

@@ -28,6 +28,8 @@ let api = {};
* @apiParam {UUID} memberId The member's id * @apiParam {UUID} memberId The member's id
* *
* @apiSuccess {Object} data The member object * @apiSuccess {Object} data The member object
*
* @apiUse UserNotFound
*/ */
api.getMember = { api.getMember = {
method: 'GET', method: 'GET',
@@ -163,6 +165,8 @@ function _getMembersForItem (type) {
* @apiParam {boolean} includeAllPublicFields Query parameter available only when fetching a party. If === `true` then all public fields for members will be returned (like when making a request for a single member) * @apiParam {boolean} includeAllPublicFields Query parameter available only when fetching a party. If === `true` then all public fields for members will be returned (like when making a request for a single member)
* *
* @apiSuccess {array} data An array of members, sorted by _id * @apiSuccess {array} data An array of members, sorted by _id
* @apiUse ChallengeNotFound
* @apiUse GroupNotFound
*/ */
api.getMembersForGroup = { api.getMembersForGroup = {
method: 'GET', method: 'GET',
@@ -181,6 +185,9 @@ api.getMembersForGroup = {
* @apiParam {UUID} lastId Query parameter to specify the last invite returned in a previous request to this route and get the next batch of results * @apiParam {UUID} lastId Query parameter to specify the last invite returned in a previous request to this route and get the next batch of results
* *
* @apiSuccess {array} data An array of invites, sorted by _id * @apiSuccess {array} data An array of invites, sorted by _id
*
* @apiUse ChallengeNotFound
* @apiUse GroupNotFound
*/ */
api.getInvitesForGroup = { api.getInvitesForGroup = {
method: 'GET', method: 'GET',
@@ -204,6 +211,9 @@ api.getInvitesForGroup = {
* @apiParam {String} includeAllMembers BETA Query parameter - If 'true' all challenge members are returned * @apiParam {String} includeAllMembers BETA Query parameter - If 'true' all challenge members are returned
* @apiSuccess {array} data An array of members, sorted by _id * @apiSuccess {array} data An array of members, sorted by _id
*
* @apiUse ChallengeNotFound
* @apiUse GroupNotFound
*/ */
api.getMembersForChallenge = { api.getMembersForChallenge = {
method: 'GET', method: 'GET',
@@ -221,6 +231,9 @@ api.getMembersForChallenge = {
* @apiParam {UUID} member The member _id * @apiParam {UUID} member The member _id
* *
* @apiSuccess {Object} data Return an object with member _id, profile.name and a tasks object with the challenge tasks for the member * @apiSuccess {Object} data Return an object with member _id, profile.name and a tasks object with the challenge tasks for the member
*
* @apiUse ChallengeNotFound
* @apiUse UserNotFound
*/ */
api.getChallengeMemberProgress = { api.getChallengeMemberProgress = {
method: 'GET', method: 'GET',
@@ -273,6 +286,8 @@ api.getChallengeMemberProgress = {
* @apiParam {UUID} toUserId Body parameter - The user to contact * @apiParam {UUID} toUserId Body parameter - The user to contact
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*
* @apiUse UserNotFound
*/ */
api.sendPrivateMessage = { api.sendPrivateMessage = {
method: 'POST', method: 'POST',
@@ -334,6 +349,8 @@ api.sendPrivateMessage = {
* @apiParam {Integer} gemAmount Body parameter The number of gems to send * @apiParam {Integer} gemAmount Body parameter The number of gems to send
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*
* @apiUse UserNotFound
*/ */
api.transferGems = { api.transferGems = {
method: 'POST', method: 'POST',

54
website/server/controllers/api-v3/quests.js
View File

@@ -26,17 +26,30 @@ function canStartQuestAutomatically (group) {
return _.every(group.quest.members, _.isBoolean); return _.every(group.quest.members, _.isBoolean);
} }
/**
* @apiDefine QuestNotFound
* @apiError (404) {NotFound} QuestNotFound The specified quest could not be found.
*/
/**
* @apiDefine QuestLeader Quest Leader
* The quest leader can use this route.
*/
let api = {}; let api = {};
/** /**
* @api {post} /api/v3/groups/:groupId/quests/invite Invite users to a quest * @api {post} /api/v3/groups/:groupId/quests/invite Invite users to a quest
* @apiName InviteToQuest * @apiName InviteToQuest
* @apiGroup Group * @apiGroup Quest
* *
* @apiParam {String} groupId The group _id (or 'party') * @apiParam {String} groupId The group _id (or 'party')
* @apiParam {String} questKey * @apiParam {String} questKey
* *
* @apiSuccess {Object} data Quest object * @apiSuccess {Object} data Quest object
*
* @apiUse GroupNotFound
* @apiUse QuestNotFound
*/ */
api.inviteToQuest = { api.inviteToQuest = {
method: 'POST', method: 'POST',
@@ -142,11 +155,14 @@ api.inviteToQuest = {
/** /**
* @api {post} /api/v3/groups/:groupId/quests/accept Accept a pending quest * @api {post} /api/v3/groups/:groupId/quests/accept Accept a pending quest
* @apiName AcceptQuest * @apiName AcceptQuest
* @apiGroup Group * @apiGroup Quest
* *
* @apiParam {String} groupId The group _id (or 'party') * @apiParam {String} groupId The group _id (or 'party')
* *
* @apiSuccess {Object} data Quest Object * @apiSuccess {Object} data Quest Object
*
* @apiUse GroupNotFound
* @apiUse QuestNotFound
*/ */
api.acceptQuest = { api.acceptQuest = {
method: 'POST', method: 'POST',
@@ -198,11 +214,14 @@ api.acceptQuest = {
/** /**
* @api {post} /api/v3/groups/:groupId/quests/reject Reject a quest * @api {post} /api/v3/groups/:groupId/quests/reject Reject a quest
* @apiName RejectQuest * @apiName RejectQuest
* @apiGroup Group * @apiGroup Quest
* *
* @apiParam {String} groupId The group _id (or 'party') * @apiParam {String} groupId The group _id (or 'party')
* *
* @apiSuccess {Object} data Quest Object * @apiSuccess {Object} data Quest Object
*
* @apiUse GroupNotFound
* @apiUse QuestNotFound
*/ */
api.rejectQuest = { api.rejectQuest = {
method: 'POST', method: 'POST',
@@ -255,11 +274,17 @@ api.rejectQuest = {
/** /**
* @api {post} /api/v3/groups/:groupId/quests/force-start Force-start a pending quest * @api {post} /api/v3/groups/:groupId/quests/force-start Force-start a pending quest
* @apiName ForceQuestStart * @apiName ForceQuestStart
* @apiGroup Group * @apiGroup Quest
* *
* @apiParam {String} groupId The group _id (or 'party') * @apiParam {String} groupId The group _id (or 'party')
* *
* @apiSuccess {Object} data Quest Object * @apiSuccess {Object} data Quest Object
*
* @apiPermission QuestLeader
* @apiPermission GroupLeader
*
* @apiUse GroupNotFound
* @apiUse QuestNotFound
*/ */
api.forceStart = { api.forceStart = {
method: 'POST', method: 'POST',
@@ -307,11 +332,17 @@ api.forceStart = {
/** /**
* @api {post} /api/v3/groups/:groupId/quests/cancel Cancel a quest that is not active * @api {post} /api/v3/groups/:groupId/quests/cancel Cancel a quest that is not active
* @apiName CancelQuest * @apiName CancelQuest
* @apiGroup Group * @apiGroup Quest
* *
* @apiParam {String} groupId The group _id (or 'party') * @apiParam {String} groupId The group _id (or 'party')
* *
* @apiSuccess {Object} data Quest Object * @apiSuccess {Object} data Quest Object
*
* @apiPermission QuestLeader
* @apiPermission GroupLeader
*
* @apiUse GroupNotFound
* @apiUse QuestNotFound
*/ */
api.cancelQuest = { api.cancelQuest = {
method: 'POST', method: 'POST',
@@ -355,11 +386,17 @@ api.cancelQuest = {
/** /**
* @api {post} /api/v3/groups/:groupId/quests/abort Abort the current quest * @api {post} /api/v3/groups/:groupId/quests/abort Abort the current quest
* @apiName AbortQuest * @apiName AbortQuest
* @apiGroup Group * @apiGroup Quest
* *
* @apiParam {String} groupId The group _id (or 'party') * @apiParam {String} groupId The group _id (or 'party')
* *
* @apiSuccess {Object} data Quest Object * @apiSuccess {Object} data Quest Object
*
* @apiPermission QuestLeader
* @apiPermission GroupLeader
*
* @apiUse GroupNotFound
* @apiUse QuestNotFound
*/ */
api.abortQuest = { api.abortQuest = {
method: 'POST', method: 'POST',
@@ -407,11 +444,14 @@ api.abortQuest = {
/** /**
* @api {post} /api/v3/groups/:groupId/quests/leave Leave the active quest * @api {post} /api/v3/groups/:groupId/quests/leave Leave the active quest
* @apiName LeaveQuest * @apiName LeaveQuest
* @apiGroup Group * @apiGroup Quest
* *
* @apiParam {String} groupId The group _id (or 'party') * @apiParam {String} groupId The group _id (or 'party')
* *
* @apiSuccess {Object} data Quest Object * @apiSuccess {Object} data Quest Object
*
* @apiUse GroupNotFound
* @apiUse QuestNotFound
*/ */
api.leaveQuest = { api.leaveQuest = {
method: 'POST', method: 'POST',

13
website/server/controllers/api-v3/tags.js
View File

@@ -7,6 +7,11 @@ import {
import _ from 'lodash'; import _ from 'lodash';
import { removeFromArray } from '../../libs/collectionManipulators'; import { removeFromArray } from '../../libs/collectionManipulators';
/**
* @apiDefine TagNotFound
* @apiError (404) {NotFound} TagNotFound The specified tag could not be found.
*/
let api = {}; let api = {};
/** /**
@@ -57,6 +62,8 @@ api.getTags = {
* @apiParam {UUID} tagId The tag _id * @apiParam {UUID} tagId The tag _id
* *
* @apiSuccess {Object} data The tag object * @apiSuccess {Object} data The tag object
*
* @apiUse TagNotFound
*/ */
api.getTag = { api.getTag = {
method: 'GET', method: 'GET',
@@ -84,6 +91,8 @@ api.getTag = {
* @apiParam {UUID} tagId The tag _id * @apiParam {UUID} tagId The tag _id
* *
* @apiSuccess {Object} data The updated tag * @apiSuccess {Object} data The updated tag
*
* @apiUse TagNotFound
*/ */
api.updateTag = { api.updateTag = {
method: 'PUT', method: 'PUT',
@@ -118,6 +127,8 @@ api.updateTag = {
* @apiParam {Number} to Position the tag is moving to * @apiParam {Number} to Position the tag is moving to
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiUse TagNotFound
*/ */
api.reorderTags = { api.reorderTags = {
method: 'POST', method: 'POST',
@@ -151,6 +162,8 @@ api.reorderTags = {
* @apiParam {UUID} tagId The tag _id * @apiParam {UUID} tagId The tag _id
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiUse TagNotFound
*/ */
api.deleteTag = { api.deleteTag = {
method: 'DELETE', method: 'DELETE',

47
website/server/controllers/api-v3/tasks.js
View File

@@ -21,6 +21,16 @@ import Bluebird from 'bluebird';
import _ from 'lodash'; import _ from 'lodash';
import logger from '../../libs/logger'; import logger from '../../libs/logger';
/**
* @apiDefine TaskNotFound
* @apiError (404) {NotFound} TaskNotFound The specified task could not be found.
*/
/**
* @apiDefine ChecklistNotFound
* @apiError (404) {NotFound} ChecklistNotFound The specified checklist item could not be found.
*/
let api = {}; let api = {};
let requiredGroupFields = '_id leader tasksOrder name'; let requiredGroupFields = '_id leader tasksOrder name';
@@ -60,6 +70,8 @@ api.createUserTasks = {
* @apiParam {UUID} challengeId The id of the challenge the new task(s) will belong to * @apiParam {UUID} challengeId The id of the challenge the new task(s) will belong to
* *
* @apiSuccess data An object if a single task was created, otherwise an array of tasks * @apiSuccess data An object if a single task was created, otherwise an array of tasks
*
* @apiUse ChallengeNotFound
*/ */
api.createChallengeTasks = { api.createChallengeTasks = {
method: 'POST', method: 'POST',
@@ -126,6 +138,8 @@ api.getUserTasks = {
* @apiParam {string="habits","dailys","todos","rewards"} type Optional query parameter to return just a type of tasks * @apiParam {string="habits","dailys","todos","rewards"} type Optional query parameter to return just a type of tasks
* *
* @apiSuccess {Array} data An array of tasks * @apiSuccess {Array} data An array of tasks
*
* @apiUse ChallengeNotFound
*/ */
api.getChallengeTasks = { api.getChallengeTasks = {
method: 'GET', method: 'GET',
@@ -160,6 +174,8 @@ api.getChallengeTasks = {
* @apiParam {String} taskId The task _id or alias * @apiParam {String} taskId The task _id or alias
* *
* @apiSuccess {Object} data The task object * @apiSuccess {Object} data The task object
*
* @apiUse TaskNotFound
*/ */
api.getTask = { api.getTask = {
method: 'GET', method: 'GET',
@@ -193,6 +209,9 @@ api.getTask = {
* @apiParam {String} taskId The task _id or alias * @apiParam {String} taskId The task _id or alias
* *
* @apiSuccess {Object} data The updated task * @apiSuccess {Object} data The updated task
*
* @apiUse TaskNotFound
* @apiUse ChallengeNotFound
*/ */
api.updateTask = { api.updateTask = {
method: 'PUT', method: 'PUT',
@@ -275,6 +294,8 @@ api.updateTask = {
* @apiSuccess {Object} data._tmp If an item was dropped it'll be returned in te _tmp object * @apiSuccess {Object} data._tmp If an item was dropped it'll be returned in te _tmp object
* @apiSuccess {Number} data.delta The delta * @apiSuccess {Number} data.delta The delta
* @apiSuccess {Object} data The user stats * @apiSuccess {Object} data The user stats
*
* @apiUse TaskNotFound
*/ */
api.scoreTask = { api.scoreTask = {
method: 'POST', method: 'POST',
@@ -369,6 +390,8 @@ api.scoreTask = {
* @apiParam {Number} position Query parameter - Where to move the task (-1 means push to bottom). First position is 0 * @apiParam {Number} position Query parameter - Where to move the task (-1 means push to bottom). First position is 0
* *
* @apiSuccess {Array} data The new tasks order (user.tasksOrder.{task.type}s) * @apiSuccess {Array} data The new tasks order (user.tasksOrder.{task.type}s)
*
* @apiUse TaskNotFound
*/ */
api.moveTask = { api.moveTask = {
method: 'POST', method: 'POST',
@@ -420,6 +443,9 @@ api.moveTask = {
* @apiParam {String} taskId The task _id or alias * @apiParam {String} taskId The task _id or alias
* *
* @apiSuccess {Object} data The updated task * @apiSuccess {Object} data The updated task
*
* @apiUse TaskNotFound
* @apiUse ChallengeNotFound
*/ */
api.addChecklistItem = { api.addChecklistItem = {
method: 'POST', method: 'POST',
@@ -474,6 +500,9 @@ api.addChecklistItem = {
* @apiParam {UUID} itemId The checklist item _id * @apiParam {UUID} itemId The checklist item _id
* *
* @apiSuccess {Object} data The updated task * @apiSuccess {Object} data The updated task
*
* @apiUse TaskNotFound
* @apiUse ChecklistNotFound
*/ */
api.scoreCheckListItem = { api.scoreCheckListItem = {
method: 'POST', method: 'POST',
@@ -513,6 +542,10 @@ api.scoreCheckListItem = {
* @apiParam {UUID} itemId The checklist item _id * @apiParam {UUID} itemId The checklist item _id
* *
* @apiSuccess {Object} data The updated task * @apiSuccess {Object} data The updated task
*
* @apiUse TaskNotFound
* @apiUse ChecklistNotFound
* @apiUse ChallengeNotFound
*/ */
api.updateChecklistItem = { api.updateChecklistItem = {
method: 'PUT', method: 'PUT',
@@ -570,6 +603,10 @@ api.updateChecklistItem = {
* @apiParam {UUID} itemId The checklist item _id * @apiParam {UUID} itemId The checklist item _id
* *
* @apiSuccess {Object} data The updated task * @apiSuccess {Object} data The updated task
*
* @apiUse TaskNotFound
* @apiUse ChallengeNotFound
* @apiUse ChecklistNotFound
*/ */
api.removeChecklistItem = { api.removeChecklistItem = {
method: 'DELETE', method: 'DELETE',
@@ -625,6 +662,8 @@ api.removeChecklistItem = {
* @apiParam {UUID} tagId The tag id * @apiParam {UUID} tagId The tag id
* *
* @apiSuccess {Object} data The updated task * @apiSuccess {Object} data The updated task
*
* @apiUse TaskNotFound
*/ */
api.addTagToTask = { api.addTagToTask = {
method: 'POST', method: 'POST',
@@ -665,6 +704,9 @@ api.addTagToTask = {
* @apiParam {UUID} tagId The tag id * @apiParam {UUID} tagId The tag id
* *
* @apiSuccess {Object} data The updated task * @apiSuccess {Object} data The updated task
*
* @apiUse TaskNotFound
* @apiUse TagNotFound
*/ */
api.removeTagFromTask = { api.removeTagFromTask = {
method: 'DELETE', method: 'DELETE',
@@ -762,6 +804,8 @@ api.unlinkAllTasks = {
* @apiParam {String} keep Query parameter - keep or remove * @apiParam {String} keep Query parameter - keep or remove
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiUse TaskNotFound
*/ */
api.unlinkOneTask = { api.unlinkOneTask = {
method: 'POST', method: 'POST',
@@ -838,6 +882,9 @@ api.clearCompletedTodos = {
* @apiParam {String} taskId The task _id or alias * @apiParam {String} taskId The task _id or alias
* *
* @apiSuccess {Object} data An empty object * @apiSuccess {Object} data An empty object
*
* @apiUse TaskNotFound
* @apiUse ChallengeNotFound
*/ */
api.deleteTask = { api.deleteTask = {
method: 'DELETE', method: 'DELETE',

295
website/server/controllers/api-v3/user.js
View File

@@ -15,6 +15,11 @@ import Bluebird from 'bluebird';
import _ from 'lodash'; import _ from 'lodash';
import * as passwordUtils from '../../libs/password'; import * as passwordUtils from '../../libs/password';
/**
* @apiDefine UserNotFound
* @apiError (404) {NotFound} UserNotFound The specified user could not be found.
*/
let api = {}; let api = {};
/** /**
@@ -328,6 +333,10 @@ const partyMembersFields = 'profile.name stats achievements items.special';
* brightness: "Searing Brightness" * brightness: "Searing Brightness"
* healAll: "Blessing" * healAll: "Blessing"
* *
* @apiUse TaskNotFound
* @apiUse PartyNotFound
* @apiUse UserNotFound
*
*/ */
api.castSpell = { api.castSpell = {
method: 'POST', method: 'POST',
@@ -760,18 +769,18 @@ api.feed = {
}; };
/** /**
* @api {post} /api/v3/user/change-class Change class * @api {post} /api/v3/user/change-class Change class
* @apiDescription User must be at least level 10. If ?class is defined and user.flags.classSelected is false it'll change the class. If user.preferences.disableClasses it'll enable classes, otherwise it sets user.flags.classSelected to false (costs 3 gems) * @apiDescription User must be at least level 10. If ?class is defined and user.flags.classSelected is false it'll change the class. If user.preferences.disableClasses it'll enable classes, otherwise it sets user.flags.classSelected to false (costs 3 gems)
* @apiName UserChangeClass * @apiName UserChangeClass
* @apiGroup User * @apiGroup User
* *
* @apiParam {String} class Query parameter - ?class={warrior|rogue|wizard|healer} * @apiParam {String} class Query parameter - ?class={warrior|rogue|wizard|healer}
* *
* @apiSuccess {Object} data.flags user.flags * @apiSuccess {Object} data.flags user.flags
* @apiSuccess {Object} data.stats user.stats * @apiSuccess {Object} data.stats user.stats
* @apiSuccess {Object} data.preferences user.preferences * @apiSuccess {Object} data.preferences user.preferences
* @apiSuccess {Object} data.items user.items * @apiSuccess {Object} data.items user.items
*/ */
api.changeClass = { api.changeClass = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -785,14 +794,14 @@ api.changeClass = {
}; };
/** /**
* @api {post} /api/v3/user/disable-classes Disable classes * @api {post} /api/v3/user/disable-classes Disable classes
* @apiName UserDisableClasses * @apiName UserDisableClasses
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data.flags user.flags * @apiSuccess {Object} data.flags user.flags
* @apiSuccess {Object} data.stats user.stats * @apiSuccess {Object} data.stats user.stats
* @apiSuccess {Object} data.preferences user.preferences * @apiSuccess {Object} data.preferences user.preferences
*/ */
api.disableClasses = { api.disableClasses = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -806,17 +815,17 @@ api.disableClasses = {
}; };
/** /**
* @api {post} /api/v3/user/purchase/:type/:key Purchase Gem or Gem-purchasable item * @api {post} /api/v3/user/purchase/:type/:key Purchase Gem or Gem-purchasable item
* @apiName UserPurchase * @apiName UserPurchase
* @apiGroup User * @apiGroup User
* *
* @apiParam {String} type Type of item to purchase. Must be one of: gems, eggs, hatchingPotions, food, quests, or gear * @apiParam {String} type Type of item to purchase. Must be one of: gems, eggs, hatchingPotions, food, quests, or gear
* @apiParam {String} key Item's key (use "gem" for purchasing gems) * @apiParam {String} key Item's key (use "gem" for purchasing gems)
* *
* @apiSuccess {Object} data.items user.items * @apiSuccess {Object} data.items user.items
* @apiSuccess {Number} data.balance user.balance * @apiSuccess {Number} data.balance user.balance
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.purchase = { api.purchase = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -830,17 +839,17 @@ api.purchase = {
}; };
/** /**
* @api {post} /api/v3/user/purchase-hourglass/:type/:key Purchase Hourglass-purchasable item * @api {post} /api/v3/user/purchase-hourglass/:type/:key Purchase Hourglass-purchasable item
* @apiName UserPurchaseHourglass * @apiName UserPurchaseHourglass
* @apiGroup User * @apiGroup User
* *
* @apiParam {String} type The type of item to purchase (pets or mounts) * @apiParam {String} type The type of item to purchase (pets or mounts)
* @apiParam {String} key Ex: {MantisShrimp-Base}. The key for the mount/pet * @apiParam {String} key Ex: {MantisShrimp-Base}. The key for the mount/pet
* *
* @apiSuccess {Object} data.items user.items * @apiSuccess {Object} data.items user.items
* @apiSuccess {Object} data.purchasedPlanConsecutive user.purchased.plan.consecutive * @apiSuccess {Object} data.purchasedPlanConsecutive user.purchased.plan.consecutive
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userPurchaseHourglass = { api.userPurchaseHourglass = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -854,16 +863,16 @@ api.userPurchaseHourglass = {
}; };
/** /**
* @api {post} /api/v3/user/read-card/:cardType Read a card * @api {post} /api/v3/user/read-card/:cardType Read a card
* @apiName UserReadCard * @apiName UserReadCard
* @apiGroup User * @apiGroup User
* *
* @apiParam {String} cardType Type of card to read * @apiParam {String} cardType Type of card to read
* *
* @apiSuccess {Object} data.specialItems user.items.special * @apiSuccess {Object} data.specialItems user.items.special
* @apiSuccess {Boolean} data.cardReceived user.flags.cardReceived * @apiSuccess {Boolean} data.cardReceived user.flags.cardReceived
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.readCard = { api.readCard = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -877,13 +886,13 @@ api.readCard = {
}; };
/** /**
* @api {post} /api/v3/user/open-mystery-item Open the Mystery Item box * @api {post} /api/v3/user/open-mystery-item Open the Mystery Item box
* @apiName UserOpenMysteryItem * @apiName UserOpenMysteryItem
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data The item obtained * @apiSuccess {Object} data The item obtained
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userOpenMysteryItem = { api.userOpenMysteryItem = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -897,12 +906,12 @@ api.userOpenMysteryItem = {
}; };
/* @api {post} /api/v3/user/release-pets Release pets /* @api {post} /api/v3/user/release-pets Release pets
* @apiName UserReleasePets * @apiName UserReleasePets
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data.items `user.items.pets` * @apiSuccess {Object} data.items `user.items.pets`
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userReleasePets = { api.userReleasePets = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -916,15 +925,15 @@ api.userReleasePets = {
}; };
/** /**
* @api {post} /api/v3/user/release-both Release pets and mounts and grants Triad Bingo * @api {post} /api/v3/user/release-both Release pets and mounts and grants Triad Bingo
* @apiName UserReleaseBoth * @apiName UserReleaseBoth
* @apiGroup User * @apiGroup User
* @apiSuccess {Object} data.achievements * @apiSuccess {Object} data.achievements
* @apiSuccess {Object} data.items * @apiSuccess {Object} data.items
* @apiSuccess {Number} data.balance * @apiSuccess {Number} data.balance
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userReleaseBoth = { api.userReleaseBoth = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -938,13 +947,13 @@ api.userReleaseBoth = {
}; };
/** /**
* @api {post} /api/v3/user/release-mounts Release mounts * @api {post} /api/v3/user/release-mounts Release mounts
* @apiName UserReleaseMounts * @apiName UserReleaseMounts
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data user.items.mounts * @apiSuccess {Object} data user.items.mounts
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userReleaseMounts = { api.userReleaseMounts = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -958,17 +967,17 @@ api.userReleaseMounts = {
}; };
/** /**
* @api {post} /api/v3/user/sell/:type/:key Sell a gold-sellable item owned by the user * @api {post} /api/v3/user/sell/:type/:key Sell a gold-sellable item owned by the user
* @apiName UserSell * @apiName UserSell
* @apiGroup User * @apiGroup User
* *
* @apiParam {String} type The type of item to sell. Must be one of: eggs, hatchingPotions, or food * @apiParam {String} type The type of item to sell. Must be one of: eggs, hatchingPotions, or food
* @apiParam {String} key The key of the item * @apiParam {String} key The key of the item
* *
* @apiSuccess {Object} data.stats * @apiSuccess {Object} data.stats
* @apiSuccess {Object} data.items * @apiSuccess {Object} data.items
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userSell = { api.userSell = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -982,17 +991,17 @@ api.userSell = {
}; };
/** /**
* @api {post} /api/v3/user/unlock Unlock item or set of items by purchase * @api {post} /api/v3/user/unlock Unlock item or set of items by purchase
* @apiName UserUnlock * @apiName UserUnlock
* @apiGroup User * @apiGroup User
* *
* @apiParam {String} path Query parameter. The path to unlock * @apiParam {String} path Query parameter. The path to unlock
* *
* @apiSuccess {Object} data.purchased * @apiSuccess {Object} data.purchased
* @apiSuccess {Object} data.items * @apiSuccess {Object} data.items
* @apiSuccess {Object} data.preferences * @apiSuccess {Object} data.preferences
* @apiSuccess {String} message * @apiSuccess {String} message
*/ */
api.userUnlock = { api.userUnlock = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1006,13 +1015,13 @@ api.userUnlock = {
}; };
/** /**
* @api {post} /api/v3/user/revive Revive user from death * @api {post} /api/v3/user/revive Revive user from death
* @apiName UserRevive * @apiName UserRevive
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data user.items * @apiSuccess {Object} data user.items
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userRevive = { api.userRevive = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1026,14 +1035,14 @@ api.userRevive = {
}; };
/** /**
* @api {post} /api/v3/user/rebirth Use Orb of Rebirth on user * @api {post} /api/v3/user/rebirth Use Orb of Rebirth on user
* @apiName UserRebirth * @apiName UserRebirth
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data.user * @apiSuccess {Object} data.user
* @apiSuccess {Array} data.tasks User's modified tasks (no rewards) * @apiSuccess {Array} data.tasks User's modified tasks (no rewards)
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userRebirth = { api.userRebirth = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1069,7 +1078,7 @@ api.userRebirth = {
* @apiParam {UUID} uuid The uuid of the user to block / unblock * @apiParam {UUID} uuid The uuid of the user to block / unblock
* *
* @apiSuccess {Array} data user.inbox.blocks * @apiSuccess {Array} data user.inbox.blocks
**/ */
api.blockUser = { api.blockUser = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1090,7 +1099,7 @@ api.blockUser = {
* @apiParam {UUID} id The id of the message to delete * @apiParam {UUID} id The id of the message to delete
* *
* @apiSuccess {Object} data user.inbox.messages * @apiSuccess {Object} data user.inbox.messages
**/ */
api.deleteMessage = { api.deleteMessage = {
method: 'DELETE', method: 'DELETE',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1109,7 +1118,7 @@ api.deleteMessage = {
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data user.inbox.messages * @apiSuccess {Object} data user.inbox.messages
**/ */
api.clearMessages = { api.clearMessages = {
method: 'DELETE', method: 'DELETE',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1128,7 +1137,7 @@ api.clearMessages = {
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data user.inbox.messages * @apiSuccess {Object} data user.inbox.messages
**/ */
api.markPmsRead = { api.markPmsRead = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1142,14 +1151,14 @@ api.markPmsRead = {
}; };
/** /**
* @api {post} /api/v3/user/reroll Reroll a user using the Fortify Potion * @api {post} /api/v3/user/reroll Reroll a user using the Fortify Potion
* @apiName UserReroll * @apiName UserReroll
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data.user * @apiSuccess {Object} data.user
* @apiSuccess {Object} data.tasks User's modified tasks (no rewards) * @apiSuccess {Object} data.tasks User's modified tasks (no rewards)
* @apiSuccess {Object} message Success message * @apiSuccess {Object} message Success message
*/ */
api.userReroll = { api.userReroll = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1177,14 +1186,14 @@ api.userReroll = {
}; };
/** /**
* @api {post} /api/v3/user/reset Reset user * @api {post} /api/v3/user/reset Reset user
* @apiName UserReset * @apiName UserReset
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data.user * @apiSuccess {Object} data.user
* @apiSuccess {Object} data.tasksToRemove IDs of removed tasks * @apiSuccess {Object} data.tasksToRemove IDs of removed tasks
* @apiSuccess {String} message Success message * @apiSuccess {String} message Success message
*/ */
api.userReset = { api.userReset = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -1212,12 +1221,12 @@ api.userReset = {
}; };
/** /**
* @api {post} /api/v3/user/custom-day-start Set preferences.dayStart for user * @api {post} /api/v3/user/custom-day-start Set preferences.dayStart for user
* @apiName setCustomDayStart * @apiName setCustomDayStart
* @apiGroup User * @apiGroup User
* *
* @apiSuccess {Object} data An empty Object * @apiSuccess {Object} data An empty Object
*/ */
api.setCustomDayStart = { api.setCustomDayStart = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],

168
website/server/controllers/api-v3/webhook.js
View File

@@ -14,7 +14,7 @@ let api = {};
/** /**
* @apiDefine WebhookNotFound * @apiDefine WebhookNotFound
* @apiError (404) {NotFound} WebhookNotFound The specified Webhook could not be found. * @apiError (404) {NotFound} WebhookNotFound The specified webhook could not be found.
*/ */
/** /**
@@ -23,54 +23,54 @@ let api = {};
*/ */
/** /**
* @api {post} /api/v3/user/webhook Create a new webhook - BETA * @api {post} /api/v3/user/webhook Create a new webhook - BETA
* @apiName AddWebhook * @apiName AddWebhook
* @apiGroup Webhook * @apiGroup Webhook
* *
* @apiParam {UUID} [id="Randomly Generated UUID"] Body parameter - The webhook's id * @apiParam {UUID} [id="Randomly Generated UUID"] Body parameter - The webhook's id
* @apiParam {String} url Body parameter - The webhook's URL * @apiParam {String} url Body parameter - The webhook's URL
* @apiParam {String} [label] Body parameter - A label to remind you what this webhook does * @apiParam {String} [label] Body parameter - A label to remind you what this webhook does
* @apiParam {Boolean} [enabled=true] Body parameter - If the webhook should be enabled * @apiParam {Boolean} [enabled=true] Body parameter - If the webhook should be enabled
* @apiParam {Sring="taskActivity","groupChatReceived"} [type="taskActivity"] Body parameter - The webhook's type. * @apiParam {Sring="taskActivity","groupChatReceived"} [type="taskActivity"] Body parameter - The webhook's type.
* @apiParam {Object} [options] Body parameter - The webhook's options. Wil differ depending on type. Required for `groupChatReceived` type. If a webhook supports options, the default values are displayed in the examples below * @apiParam {Object} [options] Body parameter - The webhook's options. Wil differ depending on type. Required for `groupChatReceived` type. If a webhook supports options, the default values are displayed in the examples below
* @apiParamExample {json} Task Activity Example * @apiParamExample {json} Task Activity Example
* { * {
* "enabled": true, // default * "enabled": true, // default
* "url": "http://some-webhook-url.com", * "url": "http://some-webhook-url.com",
* "label": "My Webhook", * "label": "My Webhook",
* "type": "taskActivity", // default * "type": "taskActivity", // default
* "options": { * "options": {
* "created": false, // default * "created": false, // default
* "updated": false, // default * "updated": false, // default
* "deleted": false, // default * "deleted": false, // default
* "scored": true // default * "scored": true // default
* } * }
* } * }
* @apiParamExample {json} Group Chat Received Example * @apiParamExample {json} Group Chat Received Example
* { * {
* "enabled": true, * "enabled": true,
* "url": "http://some-webhook-url.com", * "url": "http://some-webhook-url.com",
* "label": "My Chat Webhook", * "label": "My Chat Webhook",
* "type": "groupChatReceived", * "type": "groupChatReceived",
* "options": { * "options": {
* "groupId": "required-uuid-of-group" * "groupId": "required-uuid-of-group"
* } * }
* } * }
* @apiParamExample {json} Minimal Example * @apiParamExample {json} Minimal Example
* { * {
* "url": "http://some-webhook-url.com" * "url": "http://some-webhook-url.com"
* } * }
* *
* @apiSuccess {Object} data The created webhook * @apiSuccess {Object} data The created webhook
* @apiSuccess {UUID} data.id The uuid of the webhook * @apiSuccess {UUID} data.id The uuid of the webhook
* @apiSuccess {String} data.url The url of the webhook * @apiSuccess {String} data.url The url of the webhook
* @apiSuccess {String} data.label A label for you to keep track of what this webhooks is for * @apiSuccess {String} data.label A label for you to keep track of what this webhooks is for
* @apiSuccess {Boolean} data.enabled Whether the webhook should be sent * @apiSuccess {Boolean} data.enabled Whether the webhook should be sent
* @apiSuccess {String} data.type The type of the webhook * @apiSuccess {String} data.type The type of the webhook
* @apiSuccess {Object} data.options The options for the webhook (See examples) * @apiSuccess {Object} data.options The options for the webhook (See examples)
* *
* @apiUse WebhookBodyInvalid * @apiUse WebhookBodyInvalid
*/ */
api.addWebhook = { api.addWebhook = {
method: 'POST', method: 'POST',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],
@@ -96,41 +96,41 @@ api.addWebhook = {
}; };
/** /**
* @api {put} /api/v3/user/webhook/:id Edit a webhook - BETA * @api {put} /api/v3/user/webhook/:id Edit a webhook - BETA
* @apiName UserUpdateWebhook * @apiName UserUpdateWebhook
* @apiGroup Webhook * @apiGroup Webhook
* @apiDescription Can change `url`, `enabled`, `type`, and `options` properties. Cannot change `id`. * @apiDescription Can change `url`, `enabled`, `type`, and `options` properties. Cannot change `id`.
* *
* @apiParam {UUID} id URL parameter - The id of the webhook to update * @apiParam {UUID} id URL parameter - The id of the webhook to update
* @apiParam {String} [url] Body parameter - The webhook's URL * @apiParam {String} [url] Body parameter - The webhook's URL
* @apiParam {String} [label] Body parameter - A label to remind you what this webhook does * @apiParam {String} [label] Body parameter - A label to remind you what this webhook does
* @apiParam {Boolean} [enabled] Body parameter - If the webhook should be enabled * @apiParam {Boolean} [enabled] Body parameter - If the webhook should be enabled
* @apiParam {Sring="taskActivity","groupChatReceived"} [type] Body parameter - The webhook's type. * @apiParam {Sring="taskActivity","groupChatReceived"} [type] Body parameter - The webhook's type.
* @apiParam {Object} [options] Body parameter - The webhook's options. Wil differ depending on type. The options are enumerated in the [add webhook examples](#api-Webhook-UserAddWebhook). * @apiParam {Object} [options] Body parameter - The webhook's options. Wil differ depending on type. The options are enumerated in the [add webhook examples](#api-Webhook-UserAddWebhook).
* @apiParamExample {json} Update Enabled and Type Properties * @apiParamExample {json} Update Enabled and Type Properties
* { * {
* "enabled": false, * "enabled": false,
* "type": "taskActivity" * "type": "taskActivity"
* } * }
* @apiParamExample {json} Update Group Id for Group Chat Receieved Webhook * @apiParamExample {json} Update Group Id for Group Chat Receieved Webhook
* { * {
* "options": { * "options": {
* "groupId": "new-uuid-of-group" * "groupId": "new-uuid-of-group"
* } * }
* } * }
* *
* @apiSuccess {Object} data The updated webhook * @apiSuccess {Object} data The updated webhook
* @apiSuccess {UUID} data.id The uuid of the webhook * @apiSuccess {UUID} data.id The uuid of the webhook
* @apiSuccess {String} data.url The url of the webhook * @apiSuccess {String} data.url The url of the webhook
* @apiSuccess {String} data.label A label for you to keep track of what this webhooks is for * @apiSuccess {String} data.label A label for you to keep track of what this webhooks is for
* @apiSuccess {Boolean} data.enabled Whether the webhook should be sent * @apiSuccess {Boolean} data.enabled Whether the webhook should be sent
* @apiSuccess {String} data.type The type of the webhook * @apiSuccess {String} data.type The type of the webhook
* @apiSuccess {Object} data.options The options for the webhook (See webhook add examples) * @apiSuccess {Object} data.options The options for the webhook (See webhook add examples)
* *
* @apiUse WebhookNotFound * @apiUse WebhookNotFound
* @apiUse WebhookBodyInvalid * @apiUse WebhookBodyInvalid
* *
*/ */
api.updateWebhook = { api.updateWebhook = {
method: 'PUT', method: 'PUT',
middlewares: [authWithHeaders()], middlewares: [authWithHeaders()],

2
website/server/controllers/top-level/dataexport.js
View File

@@ -146,6 +146,8 @@ api.exportUserDataXml = {
* @apiDescription NOTE: Part of the private API that may change at any time. * @apiDescription NOTE: Part of the private API that may change at any time.
* *
* @apiSuccess {String} An html page * @apiSuccess {String} An html page
*
* @apiUse UserNotFound
*/ */
api.exportUserAvatarHtml = { api.exportUserAvatarHtml = {
method: 'GET', method: 'GET',

2
website/server/controllers/top-level/email.js
View File

@@ -17,6 +17,8 @@ let api = {};
* @apiParam {String} code Query parameter - An unsubscription code * @apiParam {String} code Query parameter - An unsubscription code
* *
* @apiSuccess {String} An html success message * @apiSuccess {String} An html success message
*
* @apiUse UserNotFound
*/ */
api.unsubscribe = { api.unsubscribe = {
method: 'GET', method: 'GET',