Payment List API

actions/payments.js

@@ -0,0 +1,190 @@
+/*
+ * Copyright (C) 2014 TopCoder Inc., All Rights Reserved.
+ *
+ * @version 1.0
+ * @author hesibo
+ */
+"use strict";
+
+var async = require('async');
+var _ = require('underscore');
+
+var IllegalArgumentError = require("../errors/IllegalArgumentError");
+
+/**
+ * Represents a predefined list of valid sort column.
+ */
+var ALLOWABLE_SORT_COLUMN = ["description", "type", "createDate", "releaseDate", "paidDate", "status", "amount"];
+
+/**
+ * Represents a predefined map of valid sort column mapping to database column name.
+ */
+var SORT_COLUMN = {
+    description : "description",
+    type : "type",
+    createdate : "date_create",
+    releasedate : "release_date",
+    paiddate : "paid_date",
+    status : "status",
+    amount : "amount"
+};
+
+/**
+ * The date format for output date field.
+ */
+var OUTPUT_DATE_FORMAT = "MM/DD/YYYY";
+
+/**
+ * Checks whether given array is empty.
+ *
+ * @param obj - the object
+ * @param objName - the object name
+ * @return {Error} if invalid or null if valid.
+ */
+function checkEmptyArray(obj, objName) {
+    if (obj.length === 0) {
+        return new IllegalArgumentError("The " + objName + " parameter is incorrect.");
+    }
+    return null;
+}
+
+/**
+ * Checks whether given string is empty when it is defined.
+ *
+ * @param obj - the string
+ * @param objName - the string name
+ * @return {Error} if invalid or null if valid.
+ */
+function checkString(obj, objName) {
+    if (_.isDefined(obj) && obj.trim().length === 0) {
+        return new IllegalArgumentError("The " + objName + " parameter should be no-empty string.");
+    }
+    return null;
+}
+
+/**
+ * This function search payments and get payment summary.
+ *
+ * @param {Object} api - The api object that is used to access the global infrastructure
+ * @param {Object} connection - The connection object for the current request
+ * @param {Function<connection, render>} next - The callback to be called after this function is done
+ */
+var searchPayments = function (api, connection, next) {
+    var error, i,
+        helper = api.helper,
+        pageIndex = Number(connection.params.pageIndex || 1),
+        pageSize = Number(connection.params.pageSize || 10),
+        status = connection.params.status,
+        type = connection.params.type,
+        sortColumn = (connection.params.sortColumn || "createDate").toLowerCase(),
+        sortOrder = (connection.params.sortOrder || "asc").toLowerCase(),
+        sqlParams = {},
+        result = {},
+        execQuery = function (name) {
+            return function (cbx) {
+                api.dataAccess.executeQuery(name, sqlParams, connection.dbConnectionMap, cbx);
+            };
+        };
+    async.waterfall([
+        function (cb) {
+            sqlParams.paymentStatusIds = [];
+            var id;
+            for (id in helper.PAYMENT_STATUS) {
+                if (helper.PAYMENT_STATUS.hasOwnProperty(id) && (_.isUndefined(status) || helper.PAYMENT_STATUS[id].toLowerCase() === status.toLowerCase())) {
+                    sqlParams.paymentStatusIds.push(id);
+                }
+            }
+
+            error = helper.checkPositiveInteger(pageIndex, "pageIndex")
+                || helper.checkMaxInt(pageIndex, "pageIndex")
+                || helper.checkPositiveInteger(pageSize, "pageSize")
+                || helper.checkMaxInt(pageSize, "pageSize")
+                || helper.checkMember(connection)
+                || helper.checkContains(["asc", "desc"], sortOrder.toLowerCase(), "sortOrder")
+                || helper.checkSortColumn(ALLOWABLE_SORT_COLUMN, sortColumn)
+                || checkString(type, "type")
+                || checkEmptyArray(sqlParams.paymentStatusIds, "status");
+            if (error) {
+                cb(error);
+                return;
+            }
+
+            sqlParams.userId = connection.caller.userId;
+            sqlParams.type = type;
+            sqlParams.firstRowIndex =  (pageIndex - 1) * pageSize;
+            sqlParams.pageSize = pageSize;
+            sqlParams.sortColumn = SORT_COLUMN[sortColumn];
+            sqlParams.sortOrder = sortOrder;
+
+            async.parallel({
+                count: _.isUndefined(type) ? execQuery("get_payment_count") : execQuery("get_payment_count_with_type"),
+                payments: _.isUndefined(type) ? execQuery("get_payments") : execQuery("get_payments_with_type"),
+                summary: execQuery("get_payment_summary")
+            }, cb);
+        },
+        function (results, cb) {
+            result.total = results.count[0].total;
+            result.pageIndex = pageIndex;
+            result.pageSize = pageSize;
+            result.payments = _.map(results.payments, function (payment) {
+                return {
+                    description : payment.description.trim(),
+                    type : payment.type,
+                    createDate : helper.formatDate(payment.date_create, OUTPUT_DATE_FORMAT),
+                    releaseDate : helper.formatDate(payment.release_date, OUTPUT_DATE_FORMAT),
+                    paidDate : helper.formatDate(payment.paid_date, OUTPUT_DATE_FORMAT) || "",
+                    status : payment.status,
+                    amount : payment.amount
+                };
+            });
+            if (results.summary.length === 0) {
+                result.summary = {
+                    paid : 0
+                };
+            } else {
+                result.summary = {};
+            }
+            results.summary.forEach(function (element) {
+                var list = element.status.split(" ");
+                for (i = 0; i < list.length; i = i + 1) {
+                    list[i] = (i === 0 ? list[i].substr(0, 1).toLowerCase() : list[i].substr(0, 1).toUpperCase()) + list[i].substr(1);
+                }
+                result.summary[list.join("")] = element.sum;
+            });
+            cb();
+        }
+    ], function (err) {
+        if (err) {
+            helper.handleError(api, connection, err);
+        } else {
+            connection.response = result;
+        }
+        next(connection, true);
+    });
+};
+
+/**
+ * get payment list API.
+ */
+exports.getPaymentList = {
+    "name": "getPaymentList",
+    "description": "get payment list api",
+    inputs: {
+        required: [],
+        optional: ["status", "type", "pageIndex", "pageSize", "sortColumn", "sortOrder"]
+    },
+    blockedConnectionTypes: [],
+    outputExample: {},
+    version: 'v2',
+    transaction : 'read', // this action is read-only
+    cacheEnabled : true,
+    databases : ["informixoltp"],
+    run: function (api, connection, next) {
+        if (connection.dbConnectionMap) {
+            api.log("Execute searchPayments#run", 'debug');
+            searchPayments(api, connection, next);
+        } else {
+            api.helper.handleNoConnection(api, connection, next);
+        }
+    }
+};

apiary.apib

@@ -7782,13 +7782,20 @@ Payments APIs
 ### Payment List [GET]
 
 + Parameters
-    + status (optional, string, `Paid`) ... Payment Status: Paid, Owed, Cancelled, Entered into payment system
+    + status (optional, string, `Paid`) ... Payment Status: Paid, Owed, Cancelled, Entered into payment system, etc..
     + type (optional, string, `Contest Payment`) ... Payment Type: Contest Payment, Review Payment, Copilot Payment, etc..
-    + pageIndex (optional, number, `1`) ... The page index of the returned resources. 1-based. It can be null. The default value will be 1
+    + pageIndex (optional, number, `1`) ... The page index of the returned resources. 1-based. It can be null. The default value will be 1.
     + pageSize (optional, number, `50`) ... The page size of the returned resources. 1-based. It can be null. The default value will be 10.
-    + sortColumn (optional, string, `description`) ... The column name to sort, can be null.
-    + sortOrder (optional, string, `asc`) ... The sorting order, can be null. If it's set, it can only be 'asc' or 'desc'.
-
+    + sortColumn (optional, string, `description`) ... The column name to sort, can be null. The default value will be 'createDate'.
+    + sortOrder (optional, string, `asc`) ... The sorting order, can be null. If it's set, it can only be 'asc' or 'desc'. The default value will be 'asc'.
+
++ Request
+
+    + Headers
+
+            Authorization : Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZHwxMzI0NTYiLCJleHAiOjEzOTI4MTc4ODQsImF1ZCI6InRvcGNvZGVyIiwiaWF0IjoxMzkyNzU3ODg0fQ.7X2IKkiyyI1ExSM5GNpdhJ8fGGK5-oAjzccX6YL_BKY
+
+
 + Response 200 (application/json)
 
         {
@@ -7800,17 +7807,19 @@ Payments APIs
                     "description": "[TCCC-4789] - Cockpit Instant Search Task",
                     "type": "Contest Payment",
                     "createDate": "12/13/2012",
-                    "releaseDate": "13/01/1012",
+                    "releaseDate": "01/13/2013",
+                    "paidDate": "02/30/2013",
                     "status": "Paid",
                     "amount": 250
                 },
                 {
                     "description": "(Application, v1.0) TC API - Studio Challenge Result API Update - First2Finish review board",
                     "type": "Review Board Payment",
-                    "createDate": "12/13/2012",
-                    "releaseDate": "13/01/1012",
+                    "createDate": "12/15/2012",
+                    "releaseDate": "01/15/2013",
+                    "paidDate": "02/30/2013",
                     "status": "Paid",
-                    "amount": 3
+                    "amount": 123
                 }
             ],
             "summary": {
@@ -7820,51 +7829,58 @@ Payments APIs
                 "enteredIntoPaymentSystem": 50.0
             }
         }
-
 + Response 400 (application/json)
 
         {
             "name":"Bad Request",
             "value":"400",
-            "description":"This message will explain why the request is invalid or cannot be served."
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"pageIndex should be number."
         }
 
-+ Response 404 (application/json)
++ Response 400 (application/json)
 
         {
-            "name":"Not Found",
-            "value":"404",
-            "description":"This message will explain why the URI requested is invalid or the resource does not exist."
+            "name":"Bad Request",
+            "value":"400",
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"pageIndex should be positive."
         }
 
-+ Response 500 (application/json)
++ Response 400 (application/json)
 
         {
-            "name":"Internal Server Error",
-            "value":"500",
-            "description":"Unknown server error. Please contact support."
+            "name":"Bad Request",
+            "value":"400",
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"pageIndex should be less or equal to 2147483647."
         }
 
-+ Response 503 (application/json)
++ Response 400 (application/json)
 
         {
-            "name":"Service Unavailable",
-            "value":"503",
-            "description":"Servers are up but overloaded. Try again later."
+            "name":"Bad Request",
+            "value":"400",
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"pageSize should be number."
         }
 
-## Docusign Callback [/terms/docusignCallback]
-### Docusign Callback [POST]
++ Response 400 (application/json)
 
-+ Parameters
-    + envelopeStatus (required, String, `Complete`) ... The status of the envelope
-    + envelopeId (required, UUID, `9103DC77-D8F1-4D7B-BED1-6116604EE98C`) ... The envelope to process
-    + tabs (required, Array, [{tabLabel: 'Handle', tabValue: 'anix'}, {...}]) ... The tab values. Can be empty
-    + connectKey (required, String, 'ABCDED-12435-EDFADSEC') The conenct key
+        {
+            "name":"Bad Request",
+            "value":"400",
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"pageSize should be positive."
+        }
+
++ Response 400 (application/json)
 
-+ Response 200 (application/json)
         {
-             "message": "some message"
+            "name":"Bad Request",
+            "value":"400",
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"pageSize should be less or equal to 2147483647."
         }
 
 + Response 400 (application/json)
@@ -7873,14 +7889,43 @@ Payments APIs
             "name":"Bad Request",
             "value":"400",
             "description":"The request was invalid. An accompanying message will explain why."
+            "description":"The sort column 'invalid' is invalid, it should be element of description,type,createDate,releaseDate,paidDate,status,amount."
         }
 
-+ Response 404 (application/json)
++ Response 400 (application/json)
 
         {
-            "name":"Not Found",
-            "value":"404",
-            "description":"This message will explain why the URI requested is invalid or the resource does not exist."
+            "name":"Bad Request",
+            "value":"400",
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"sortOrder should be an element of asc,desc."
+        }
+
++ Response 400 (application/json)
+
+        {
+            "name":"Bad Request",
+            "value":"400",
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"The type parameter is incorrect."
+        }
+
++ Response 400 (application/json)
+
+        {
+            "name":"Bad Request",
+            "value":"400",
+            "description":"The request was invalid. An accompanying message will explain why."
+            "description":"The status parameter is incorrect."
+        }
+
++ Response 401 (application/json)
+
+        {
+            "name":"Unauthorized",
+            "value":"401",
+            "description":"Authentication credentials were missing or incorrect."
+            "details:":"Unauthorized Error"
         }
 
 + Response 500 (application/json)