refactor: document endpoints

src/controllers/contactController.js

@@ -14,14 +14,17 @@ const { sendErrorResponse } = require('../utils')
  * @returns {Object} The contact information object.
  */
 const getClassInfo = async (req, res) => {
+  /*
+    #swagger.summary = 'Get the contact'
+  */
   try {
     const { contactId } = req.body
     const client = sessions.get(req.params.sessionId)
     const contact = await client.getContactById(contactId)
     if (!contact) {
-      sendErrorResponse(res, 404, 'Contact not Found')
+      throw new Error('Contact not found')
     }
-    res.json({ success: true, result: contact })
+    res.json({ success: true, contact })
   } catch (error) {
     sendErrorResponse(res, 500, error.message)
   }
@@ -40,12 +43,15 @@ const getClassInfo = async (req, res) => {
  * @returns {Object} The result of the blocking operation.
  */
 const block = async (req, res) => {
+  /*
+    #swagger.summary = 'Block contact'
+  */
   try {
     const { contactId } = req.body
     const client = sessions.get(req.params.sessionId)
     const contact = await client.getContactById(contactId)
     if (!contact) {
-      sendErrorResponse(res, 404, 'Contact not Found')
+      throw new Error('Contact not found')
     }
     const result = await contact.block()
     res.json({ success: true, result })
@@ -67,12 +73,16 @@ const block = async (req, res) => {
  * @returns {Object} The 'About' information of the contact.
  */
 const getAbout = async (req, res) => {
+  /*
+    #swagger.summary = "Get the contact's current info"
+    #swagger.description = "Get the Contact's current 'about' info. Returns null if you don't have permission to read their status."
+  */
   try {
     const { contactId } = req.body
     const client = sessions.get(req.params.sessionId)
     const contact = await client.getContactById(contactId)
     if (!contact) {
-      sendErrorResponse(res, 404, 'Contact not Found')
+      throw new Error('Contact not found')
     }
     const result = await contact.getAbout()
     res.json({ success: true, result })
@@ -94,11 +104,17 @@ const getAbout = async (req, res) => {
  * @returns {Promise<void>} A promise that resolves with the chat information of the contact.
  */
 const getChat = async (req, res) => {
+  /*
+    #swagger.summary = 'Get the chat'
+    #swagger.description = 'Get the chat that corresponds to the contact. Will return null when getting chat for currently logged in user.'
+  */
   try {
     const { contactId } = req.body
     const client = sessions.get(req.params.sessionId)
     const contact = await client.getContactById(contactId)
-    if (!contact) { sendErrorResponse(res, 404, 'Contact not Found') }
+    if (!contact) {
+      throw new Error('Contact not found')
+    }
     const result = await contact.getChat()
     res.json({ success: true, result })
   } catch (error) {
@@ -119,11 +135,17 @@ const getChat = async (req, res) => {
  * @returns {Promise<void>} A promise that resolves with the formatted number of the contact.
  */
 const getFormattedNumber = async (req, res) => {
+  /*
+    #swagger.summary = 'Get the formatted phone number'
+    #swagger.description = "Returns the contact's formatted phone number, (12345678901@c.us) => (+1 (234) 5678-901)."
+  */
   try {
     const { contactId } = req.body
     const client = sessions.get(req.params.sessionId)
     const contact = await client.getContactById(contactId)
-    if (!contact) { sendErrorResponse(res, 404, 'Contact not Found') }
+    if (!contact) {
+      throw new Error('Contact not found')
+    }
     const result = await contact.getFormattedNumber()
     res.json({ success: true, result })
   } catch (error) {
@@ -144,11 +166,17 @@ const getFormattedNumber = async (req, res) => {
  * @returns {Promise<void>} A promise that resolves with the country code of the contact.
  */
 const getCountryCode = async (req, res) => {
+  /*
+    #swagger.summary = 'Get the country code'
+    #swagger.description = "Returns the contact's country code, (1541859685@c.us) => (1)."
+  */
   try {
     const { contactId } = req.body
     const client = sessions.get(req.params.sessionId)
     const contact = await client.getContactById(contactId)
-    if (!contact) { sendErrorResponse(res, 404, 'Contact not Found') }
+    if (!contact) {
+      throw new Error('Contact not found')
+    }
     const result = await contact.getCountryCode()
     res.json({ success: true, result })
   } catch (error) {
@@ -169,11 +197,17 @@ const getCountryCode = async (req, res) => {
  * @returns {Promise<void>} A promise that resolves with the profile picture url of the contact.
  */
 const getProfilePicUrl = async (req, res) => {
+  /*
+    #swagger.summary = 'Get the profile picture URL'
+    #swagger.description = "Get the contact's profile picture URL, if privacy settings allow it."
+  */
   try {
     const { contactId } = req.body
     const client = sessions.get(req.params.sessionId)
     const contact = await client.getContactById(contactId)
-    if (!contact) { sendErrorResponse(res, 404, 'Contact not Found') }
+    if (!contact) {
+      throw new Error('Contact not found')
+    }
     const result = await contact.getProfilePicUrl() || null
     res.json({ success: true, result })
   } catch (error) {
@@ -194,11 +228,17 @@ const getProfilePicUrl = async (req, res) => {
  * @returns {Promise<void>} A promise that resolves with the result of unblocking the contact.
  */
 const unblock = async (req, res) => {
+  /*
+    #swagger.summary = 'Unblock the contact'
+    #swagger.description = "Unblock the contact from WhatsApp."
+  */
   try {
     const { contactId } = req.body
     const client = sessions.get(req.params.sessionId)
     const contact = await client.getContactById(contactId)
-    if (!contact) { sendErrorResponse(res, 404, 'Contact not Found') }
+    if (!contact) {
+      throw new Error('Contact not found')
+    }
     const result = await contact.unblock()
     res.json({ success: true, result })
   } catch (error) {
@@ -206,6 +246,37 @@ const unblock = async (req, res) => {
   }
 }
 
+/**
+ * Gets the contact's common groups with you.
+ *
+ * @async
+ * @function unblock
+ * @param {Object} req - The request object.
+ * @param {Object} res - The response object.
+ * @param {string} req.params.sessionId - The session ID.
+ * @param {string} req.body.contactId - The ID of the client whose contact is being unblocked.
+ * @throws {Error} If the contact with the given contactId is not found or if there is an error unblocking the contact.
+ * @returns {Promise<void>} A promise that resolves with the result of unblocking the contact.
+ */
+const getCommonGroups = async (req, res) => {
+  /*
+    #swagger.summary = "Get the contact's common groups"
+    #swagger.description = "Get the contact's common groups with you. Returns empty array if you don't have any common group."
+  */
+  try {
+    const { contactId } = req.body
+    const client = sessions.get(req.params.sessionId)
+    const contact = await client.getContactById(contactId)
+    if (!contact) {
+      throw new Error('Contact not found')
+    }
+    const result = await contact.getCommonGroups()
+    res.json({ success: true, result })
+  } catch (error) {
+    sendErrorResponse(res, 500, error.message)
+  }
+}
+
 module.exports = {
   getClassInfo,
   block,
@@ -214,5 +285,6 @@ module.exports = {
   unblock,
   getFormattedNumber,
   getCountryCode,
-  getProfilePicUrl
+  getProfilePicUrl,
+  getCommonGroups
 }