Merge branch 'master' into stable

Merge in master for 1.5.0 release

lib/resources/Authorization.js

@@ -4,15 +4,34 @@
 var generate = require('../generate');
 var api = require('../api');
 
+/**
+ * Retrieving, capturing, voiding, and reauthorizing previously created authorizations
+ * @return {Object} authorization functions
+ */
 function authorization() {
     var baseURL = '/v1/payments/authorization/';
     var operations = ['get', 'capture'];
 
     var ret = {
         baseURL: baseURL,
+        /**
+         * Void a previously authorized payment
+         * @param  {String}   id     authorization identifier
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb        
+         * @return {Object}          Authorization object
+         */
         void: function voidAuthorization(id, config, cb) {
             api.executeHttp('POST', this.baseURL + id + '/void', {}, config, cb);
         },
+        /**
+         * Reauthorize a PayPal account payment
+         * @param  {String}   id     authorization identifier
+         * @param  {object}   data   amount object with total e.g. 7.00 and currency e.g. USD
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb     
+         * @return {[type]}          [description]
+         */
         reauthorize: function reauthorize(id, data, config, cb) {
             api.executeHttp('POST', this.baseURL + id + '/reauthorize', data, config, cb);
         },

lib/resources/BillingAgreement.js

@@ -4,10 +4,24 @@
 var generate = require('../generate');
 var api = require('../api');
 
+/**
+ * The billing agreements allows merchants to have users agree to be billed
+ * for billing plans
+ * @return {Object} billing agreement functions
+ */
 function billingAgreement() {
     var baseURL = '/v1/payments/billing-agreements/';
     var operations = ['create', 'get', 'update', 'cancel'];
 
+    /**
+     * Search for transactions within a billing agreement
+     * @param  {String}   id         Identifier of the agreement resource for which to list transactions.
+     * @param  {String}   start_date YYYY-MM-DD start date of range of transactions to list
+     * @param  {String}   end_date   YYYY-MM-DD end date of range of transactions to list
+     * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+     * @param  {Function} cb         
+     * @return {Object}              agreement transaction list, array of agreement transaction objects
+     */
     function searchTransactions(id, start_date, end_date, config, cb) {
         var date_range = {
             "start_date": start_date,
@@ -16,22 +30,67 @@ function billingAgreement() {
         api.executeHttp('GET', baseURL + id + '/transactions', date_range, config, cb);
     }
 
+    /**
+     * Bill outstanding balance of an agreement
+     * @param  {String}   id     Identifier of the agreement resource for which to bill balance
+     * @param  {Object}   data   Agreement state descriptor, fields include note and amount which has two attributes, value and currency
+     * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+     * @param  {Function} cb      
+     * @return {}          Returns the HTTP status of 204 if the call is successful
+     */
     function billBalance(id, data, config, cb) {
         api.executeHttp('POST', baseURL + id + '/bill-balance', data, config, cb);
     }
 
+    /**
+     * Set the outstanding amount of an agreement
+     * @param  {String}   id     Identifier of the agreement resource for which to set balance
+     * @param  {Object}   data   Two attributes currency e.g. "USD" and value e.g. "100"
+     * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+     * @param  {Function} cb
+     * @return {}          Returns the HTTP status of 204 if the call is successful
+     */
     function setBalance(id, data, config, cb) {
         api.executeHttp('POST', baseURL + id + '/set-balance', data, config, cb);
     }
 
     var ret = {
         baseURL: baseURL,
+        /**
+         * Execute an agreement after the buyer approves it
+         * @param  {String}   token  Payment Token of format EC-XXXXXX, appended to return url as a parameter after buyer approves agreement
+         * @param  {Object|Function}   data Empty object or callback. Optional, will be removed in next major release. 
+         * @param  {Object|Function}   config Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb     
+         * @return {Object}          agreement object
+         */
         execute: function execute(token, data, config, cb) {
+            //support case where neither data nor config is provided
+            if (typeof data === "function" && arguments.length === 2) {
+                cb = data;
+                data = {};
+            }
             api.executeHttp('POST', this.baseURL + token + '/agreement-execute', data, config, cb);
         },
+        /**
+         * Changes agreement state to suspended, can be reactivated unlike cancelling agreement
+         * @param  {String}   id     Identifier of the agreement resource for which to suspend
+         * @param  {Object}   data   Add note attribute, reason for changing state of agreement
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb
+         * @return {}          Returns the HTTP status of 204 if the call is successful
+         */
         suspend: function suspend(id, data, config, cb) {
             api.executeHttp('POST', this.baseURL + id + '/suspend', data, config, cb);
         },
+        /**
+         * Reactivate a suspended agreement
+         * @param  {String}   id     Identifier of the agreement resource for which to reactivate
+         * @param  {Object}   data   Add note attribute, reason for changing state of agreement
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb
+         * @return {}          Returns the HTTP status of 204 if the call is successful
+         */
         reactivate: function reactivate(id, data, config, cb) {
             api.executeHttp('POST', this.baseURL + id + '/re-activate', data, config, cb);
         },
@@ -46,5 +105,4 @@ function billingAgreement() {
     ret = generate.mixin(ret, operations);
     return ret;
 }
-
 module.exports = billingAgreement;

lib/resources/BillingPlan.js

@@ -4,12 +4,24 @@
 var generate = require('../generate');
 var api = require('../api');
 
+/**
+ * Create planned sets of future recurring payments at periodic intervals (sometimes known as “subscriptions”).
+ * @return {Object} billing plan functions
+ */
 function billingPlan() {
     var baseURL = '/v1/payments/billing-plans/';
     var operations = ['create', 'get', 'list', 'update'];
 
     var ret = {
         baseURL: baseURL,
+        /**
+         * Activate a billing plan so that it can be used to form
+         * billing agreements with users
+         * @param  {String}   id     Billing plan identifier
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb     
+         * @return {}          Returns the HTTP status of 200 if the call is successful
+         */
         activate: function activate(id, config, cb) {
             var activate_attributes = [
                 {

lib/resources/Capture.js

@@ -3,6 +3,10 @@
 
 var generate = require('../generate');
 
+/**
+ * Look up and refund captured payments
+ * @return {Object} capture functions
+ */
 function capture() {
     var baseURL = '/v1/payments/capture/';
     var operations = ['get', 'refund'];

lib/resources/CreditCard.js

@@ -3,6 +3,10 @@
 
 var generate = require('../generate');
 
+/**
+ * Store credit cards information securely in vault
+ * @return {Object} Credit Card functions
+ */
 function creditCard() {
     var baseURL = '/v1/vault/credit-card/';
     var operations = ['create', 'get', 'update', 'del', 'delete'];

lib/resources/Invoice.js

@@ -4,6 +4,11 @@
 var generate = require('../generate');
 var api = require('../api');
 
+/**
+ * Create, send and manage invoices, PayPal emails the customer with link to invoice
+ * on PayPal's website. Customers can pay with PayPal, check, debit or credit card.
+ * @return {Invoice} Invoice functions
+ */
 function invoice() {
     var baseURL = '/v1/invoicing/invoices/';
     var operations = ['create', 'get', 'list', 'del', 'delete', 'cancel'];

lib/resources/Notification.js

@@ -9,6 +9,7 @@ var crc32 = require('buffer-crc32');
 
 /**
  * Exposes REST endpoints for creating and managing webhooks
+ * @return {Object} webhook functions
  */
 function webhook() {
     var baseURL = '/v1/notifications/webhooks/';
@@ -31,6 +32,7 @@ function webhook() {
  * Exposes REST endpoints for working with subscribed webhooks events
  *
  * https://developer.paypal.com/webapps/developer/docs/integration/direct/rest-webhooks-overview/#events
+ * @return {Object} webhook event functions
  */
 function webhookEvent() {
     var baseURL = '/v1/notifications/webhooks-events/';
@@ -79,6 +81,7 @@ function webhookEvent() {
 
 /**
  * Exposes REST endpoint for listing available event types for webhooks
+ * @return {Object} webhook event type functions
  */
 function webhookEventType() {
     var baseURL = '/v1/notifications/webhooks-event-types/';
@@ -95,6 +98,7 @@ function webhookEventType() {
  * Exposes the namespace for webhook and webhook event functionalities
  * 
  * https://developer.paypal.com/webapps/developer/docs/api/#notifications
+ * @return {Object} notification functions
  */
 function notification() {
     return {

lib/resources/OpenIdConnect.js

@@ -127,6 +127,7 @@ function userInfoRequest(data, config, cb) {
 
 /**
  * Use log in with PayPal to avoid storing user data on the system
+ * @return {Object} openidconnect functions
  */
 function openIdConnect() {
     return {

lib/resources/Order.js

@@ -4,15 +4,34 @@
 var generate = require('../generate');
 var api = require('../api');
 
+/**
+ * Take action on a payment with the intent of order
+ * @return {Object} order functions
+ */
 function order() {
     var baseURL = '/v1/payments/orders/';
     var operations = ['get', 'capture'];
 
     var ret = {
         baseURL: baseURL,
+        /**
+         * Void an existing order
+         * @param  {String}   id     Order identifier
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb        
+         * @return {Object}          Order object, with state set to voided
+         */
         void: function voidOrder(id, config, cb) {
             api.executeHttp('POST', this.baseURL + id + '/do-void', {}, config, cb);
         },
+        /**
+         * Authorize an order
+         * @param  {String}   id     Order identifier
+         * @param  {Object}   data   Amount object with total and currency
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb 
+         * @return {Object}          Authorization object
+         */
         authorize: function authorize(id, data, config, cb) {
             api.executeHttp('POST', this.baseURL + id + '/authorize', data, config, cb);
         },

lib/resources/Payment.js

@@ -4,12 +4,24 @@
 var generate = require('../generate');
 var api = require('../api');
 
+/**
+ * Create or get details of payments
+ * @return {Object} Payment functions
+ */
 function payment() {
     var baseURL = '/v1/payments/payment/';
     var operations = ['create', 'get', 'list'];
 
     var ret = {
         baseURL: baseURL,
+        /**
+         * Execute(complete) a PayPal or payment that has been approved by the payer
+         * @param  {String}   id     Payment identifier
+         * @param  {Object}   data   Transaction details if updating a payment
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb     
+         * @return {Object}          Payment object for completed PayPal payment
+         */
         execute: function execute(id, data, config, cb) {
             api.executeHttp('POST', this.baseURL + id + '/execute', data, config, cb);
         }

lib/resources/Payout.js

@@ -4,6 +4,10 @@
 var generate = require('../generate');
 var api = require('../api');
 
+/**
+ * Make payouts to multiple PayPal accounts, or multiple payments to same PayPal account
+ * @return {Object} payout functions
+ */
 function payout() {
     var baseURL = '/v1/payments/payouts/';
     var operations = ['get'];
@@ -14,6 +18,14 @@ function payout() {
 
     var ret = {
         baseURL: baseURL,
+        /**
+         * Create a batch(asynchronous) or single(synchronous) payout
+         * @param  {Object}   data      payout details
+         * @param  {String}   sync_mode true for synchronous payouts, false by default
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb
+         * @return {Object}             Payout object
+         */
         create: function create(data, sync_mode, config, cb) {
             cb = (typeof sync_mode === 'function') ? sync_mode : cb;
             sync_mode = (typeof sync_mode === 'string' && sync_mode === 'true') ? 'true' : 'false';

lib/resources/PayoutItem.js

@@ -2,13 +2,31 @@
 "use strict";
 
 var generate = require('../generate');
+var api = require('../api');
 
+/**
+ * An individual Payout item
+ * @return {Object} payout object functions
+ */
 function payoutItem() {
     var baseURL = '/v1/payments/payouts-item/';
     var operations = ['get'];
 
     var ret = {
-        baseURL: baseURL
+        baseURL: baseURL,
+        /**
+         * Cancel an existing payout/transaction in UNCLAIMED state
+         * Explicitly define `cancel` method here to avoid having to pass in an empty `data` parameter
+         * as required by the generated generic `cancel` operation.
+         * 
+         * @param  {String}   id     Payout item id
+         * @param  {Object|Function}   config     Configuration parameters e.g. client_id, client_secret override or callback
+         * @param  {Function} cb
+         * @return {Object}          Payout item details object with transaction status of RETURNED
+         */
+        cancel: function cancel(id, config, cb) {
+            api.executeHttp('POST', this.baseURL + id + '/cancel', {}, config, cb);
+        }
     };
     ret = generate.mixin(ret, operations);
     return ret;

lib/resources/Refund.js

@@ -3,6 +3,10 @@
 
 var generate = require('../generate');
 
+/**
+ * Refunds on direct and captured payments
+ * @return {Object} refund functions
+ */
 function refund() {
     var baseURL = '/v1/payments/refund/';
     var operations = ['get'];

lib/resources/Sale.js

@@ -3,6 +3,10 @@
 
 var generate = require('../generate');
 
+/**
+ * Completed payments are referred to as sale transactions
+ * @return {Object} sale functions
+ */
 function sale() {
     var baseURL = '/v1/payments/sale/';
     var operations = ['get', 'refund'];