missing updates

2 files changed, 196 insertions, 60 deletions

diff --git a/routes/admin.js b/routes/admin.js
index 566de322..b02b6b6e 100644
--- a/routes/admin.js
+++ b/routes/admin.js
@@ -7,10 +7,23 @@ const Op = Sequelize.Op;
 
 const { v4: uuidv4 } = require('uuid');
 
-// usage:  GET '/users'
-//
-// Returns: 
-//    { users: <list of users }
+/**
+ * @api {get} /users Retrieve user list
+ * @apiName getUsers
+ * @apiGroup Admin
+ *
+ * @apiPermission admin
+ * 
+ * @apiSuccess {token: referral_code, expiry: expiry} Token and expiry if applicable.
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *       "users" : [
+ *         { "username": 'John Doe', "email": '[email protected]', ...},
+ *         { "username": 'Jane Doe', "email": '[email protected]', ...}
+ *        ]
+ *     }
+ */
 router.get(
   "/users",
   auth,
@@ -29,10 +42,23 @@ router.get(
   })
 );
 
-// usage:  GET '/referrals'
-//
-// Returns: 
-//    { referrals: <list of referral tokens> }
+/**
+ * @api {get} /referrals Retrieve list of referral tokens
+ * @apiName referrals
+ * @apiGroup Admin
+ *
+ * @apiPermission admin
+ * 
+ * @apiSuccess returns list of referral tokens
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *       "referrals" : [
+ *         { "token": '***', "status": 'pending', sponsor: 'Adam', user: 'newUsername1', expiry: null },
+ *         { "token": '***', "status": 'pending', sponsor: 'Adam', user: 'newUsername2', expiry: null },
+ *        ]
+ *     }
+ */
 router.get(
   "/referrals",
   auth,
@@ -63,10 +89,23 @@ router.get(
   })
 );
 
-// usage:  GET '/accounts'
-//
-// Returns: 
-//    { referrals: <list of referral tokens> }
+/**
+ * @api {get} /accounts Retrieve list of accounts
+ * @apiName accounts
+ * @apiGroup Admin
+ *
+ * @apiPermission admin
+ * 
+ * @apiSuccess returns list of accounts
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *       "accounts" : [
+ *         { "user": 'Adam', "account_id": '123', balance: 500 ... },
+ *          ...
+ *        ]
+ *     }
+ */
 router.get(
   "/accounts",
   auth,
@@ -89,19 +128,24 @@ router.get(
   })
 );
 
-// usage:  GET '/user/transactions'
-//
-// Returns: 
-//    { users: [
-//         <user attributes>, 
-//         Invoices: 
-//           <invoice attributes>, 
-//         Payments: 
-//           <invoice attributes>, 
-//         Orders: 
-//           <invoice attributes>, 
-//       ], ...
-//    }
+/**
+ * @api {get} /user_transactions Retrieve summary of user transactions
+ * 
+ * @apiName user_transactions
+ * @apiGroup Admin
+ *
+ * @apiPermission admin
+ * 
+ * @apiSuccess returns list of invoices, payments, orders for users
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *       "transactions" : [
+ *         { "username": 'Adam', "email": '[email protected]', invoices: 1, orders: 0, payments: 2 },
+         ...
+ *        ]
+ *     }
+ */
 router.get(
   "/user_transactions",
   auth,
@@ -143,14 +187,24 @@ router.get(
   })
 );
 
-// usage:  GET '/user_kyc'
-//
-// Returns: 
-//    { 
-//  users: [
-//    <list of user attributes>,
-//    kyc: <list of kyc attributes for this user>
-//  ] 
+/**
+ * @api {get} /user_kyc Retrieve user kyc details
+ * 
+ * @apiName user_kyc
+ * @apiGroup Admin
+ *
+ * @apiPermission admin
+ * 
+ * @apiSuccess returns list of kyc details for each user
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *       "users" : [
+ *         { "username": 'Adam', "email": '[email protected]', ... kyc_data... },
+         ...
+ *        ]
+ *     }
+ */
 router.get(
   "/user_kyc",
   auth,
diff --git a/routes/referrals.js b/routes/referrals.js
index 9fc47166..c2314690 100644
--- a/routes/referrals.js
+++ b/routes/referrals.js
@@ -17,6 +17,27 @@ router.get('/', function(req, res, next) {
 // Changes to DB: 
 //    adds record to referrals table:
 //      { token: <uuid>, sponsor_id: <user.id>, status: "pending" }
+
+/**
+ * @api {post} /grant Grant Referral code
+ * @apiName Grant
+ * @apiGroup Referrals
+ *
+ * 
+ * @apiPermission member
+ * 
+ * @apiParam {sponsor_id} user_id of member generating referral code.
+ * @apiParam {expiry} optional expiry date for token.
+ *
+ * @apiSuccess {token: referral_code, expiry: expiry} Token and expiry if applicable.
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *        "token": "*********", 
+ *        "status": "pending", 
+ *        "expiry": null
+ *     }
+ */
 router.post(
   "/grant",
   auth,
@@ -33,13 +54,33 @@ router.post(
     })
 
     debug('generated referral: ' + JSON.stringify(ref))
-    return res.send({token: token, expiry: expiry})
+    return res.send({token: token, status: 'pending', expiry: expiry})
   })
 );
 
+/**
+ * @api {get} /grant Grant Referral code (variation using get)
+ * @apiName Grant
+ * @apiGroup Referrals
+ *
+ * @apiPermission member
+ * 
+ * @apiPermission member
+ * @apiParam {sponsor_id} user_id of member generating referral code.
+ * @apiParam {expiry} optional expiry date for token.
+ *
+ * @apiSuccess {token: referral_code, status: status, expiry: expiry} Token and expiry if applicable.
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *        "token": "*********", 
+ *        "status": "pending", 
+ *        "expiry": null
+ *     }
+ */
 router.get(
   "/grant",
-  // auth,
+  auth,
   ah(async (req, res) => {
     const {sponsor_id, expiry} = req.query
     debug('grant token..')
@@ -58,16 +99,33 @@ router.get(
 );
 
 
-// usage:  GET '/checkTokens/<user_id>'
-//
-// Required: 
-//   sponsor_id (= user.id)
-// Returns: 
-//    { tokens: <list of tokens>}
+/**
+ * @api {get} /checkTokens/:sponsor_id Retrieve list of referral tokens generated by this user
+ * 
+ * @apiName checkTokens
+ * @apiGroup Referrals
+ *
+ *  
+ * @apiPermission member
+ * 
+ * @apiParam {sponsor_id} user_id of member generating referral code.
+ * @apiParam {status} optional token status.
+ *
+ * @apiSuccess tokens array of token objects 
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *       "tokens": [
+ *         {"token": "*********", "status": "pending", "expiry": null}
+ *       ]
+ *     }
+ */
+
 // TO FIX - change sponsor_id so that it is retrieved from current payload (NOT FROM URL)
+
 router.get(
   "/checkTokens/:sponsor_id",
-  // auth,
+  auth,
   ah(async (req, res) => {
     const {sponsor_id} = req.params
 
@@ -84,15 +142,28 @@ router.get(
   })
 );
 
-// Verify token and apply to existing user
-// usage:  GET '/verify/<user_id>/<token>'
-//
-// Required: 
-//   current user_id (= user.id)
-//   token
-// Changes to DB (on success): 
-//    referral token is updated from 'pending' to 'active'
-//    referral token is updated with existing user_id
+
+/**
+ * @api {get} /verify/:user_id  Verify token and apply to existing user
+ * 
+ * @apiName verify
+ * @apiGroup Referrals
+ * 
+ * @apiPermission member
+ *  
+ * @apiParam {user_id} Current user
+ * @apiParam {token} Token to validate
+ *
+ * @apiSuccess verified = true
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *       "verified": true
+ *     }
+ * 
+ * @apiDescription referral token is updated from 'pending' to 'active'
+ * @apiDescription referral token is updated with existing user_id
+ */
 router.get(
   "/verify/:user_id/:token",
   auth,
@@ -134,15 +205,26 @@ router.get(
   })
 );
 
-// Add email / sms to waiting list 
-// usage:  POST '/joinQueue'  { email: , sms: }
-//
-// Required: 
-//   either email or sms
-// Changes to DB (on success): 
-//    adds record to waiting_list:
-//       { email: <email>, sms: <sms> }
-// Returns: { success: true, message: <message>} 
+
+/**
+ * @api {post} /joinQueue  Join waiting list (track email & sms)
+ * @apiName joinQueue
+ * @apiGroup Referrals
+ *
+ * @apiParam {email} 
+ * @apiParam {sms} 
+ *
+ * @apiSuccess verified = true
+ * @apiSuccessExample {json} Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+ *       "success": true
+ *       "message": 'Added to waiting list'
+ *     }
+ * 
+ * @apiDescription referral token is updated from 'pending' to 'active'
+ * @apiDescription referral token is updated with existing user_id
+ */
 router.post(
   "/joinQueue",
   ah(async (req, res) => {