Merge pull request #27 from aron123/feature/new-email-transfer

Implement the new way of email transfer and related functionalities

README.md

@@ -20,7 +20,10 @@ Helps manage e-payment transactions through the [Barion Smart Gateway](https://w
     - [Capture a previously authorized payment](#capture-a-previously-authorized-payment---barioncaptureauthorizedpaymentoptions-callback)
     - [Cancel a previously authorized payment](#cancel-a-previously-authorized-payment---barioncancelauthorizedpaymentoptions-callback)
     - [Send money to a bank account](#send-money-to-a-bank-account---barionbanktransferoptions-callback)
-    - [Send money to a Barion user or email address](#send-money-to-a-barion-user-or-email-address---barionbariontransferoptions-callback)
+    - [Get existing accounts of the user](#get-existing-accounts-of-the-user---bariongetaccountsoptions-callback)
+    - [Send money to a Barion user or email address](#send-e-money-to-an-email-address---barionemailtransferoptions-callback)
+    - [Send money to a Barion user or email address](#send-money-to-a-barion-user-or-email-address---barionbariontransferoptions-callback) ![][DEPRECATED]
+
     - [Handling errors](#handling-errors)
 
   - [Future improvements](#future-improvements)
@@ -78,6 +81,7 @@ If you are not familiar with Promise and other ES6 stuff, [get closer to it](htt
 - capture or cancel a previously authorized payment
 - refund a completed payment
 - send money out of Barion via international bank transfer
+- get existing accounts of the user
 - send money to existing Barion account or email address
 
 > **IMPORTANT**: ``node-barion`` is completely consistent with [Barion Docs](https://docs.barion.com/Main_Page), so you can use exactly the same field names, that are specified in it. **Reading the official Barion documentation is highly reccomended** before starting to use ``node-barion`` module.<br>
@@ -495,7 +499,97 @@ barion.bankTransfer({
 });
 ```
 
+### Get existing accounts of the user - barion.getAccounts(options, \[callback\])
+To query the existing accounts of a user, call the ``getAccounts`` function. [[Barion Docs](https://docs.barion.com/Accounts-Get-v2)]
+
+**Parameters**:
+  - ``UserName``: Email address of the user in the Barion system (string). (required)
+
+  - ``Password``: Password of the user in the Barion system (string). (required)
+
+**Output**: [Read at Barion Docs](https://docs.barion.com/Accounts-Get-v2#Output_properties)
+
+#### Usage example
+##### With callback
+```js
+barion.getAccounts({
+    UserName: 'info@example.com',
+    Password: 'someRlyStrongP4ss#!'
+}, function (err, data) {
+    //handle error / process data
+});
+```
+##### With promise
+```js
+barion.getAccounts({
+    UserName: 'info@example.com',
+    Password: 'someRlyStrongP4ss#!'
+}).then(data => {
+    //process data
+}).catch(err => {
+    //handle error
+});
+```
+
+### Send e-money to an email address - barion.emailTransfer(options, \[callback\])
+To send money to a Barion user or to an email address, call the ``emailTransfer`` function. [[Barion Docs](https://docs.barion.com/Transfer-Email-v2)]
+
+**Parameters**:
+  - ``UserName``: Email address of the user in the Barion system (string). (required)
+
+  - ``Password``: Password of the user in the Barion system (string). (required)
+
+  - ``SourceAccountId``: The identifier of the Barion wallet. Must be an account of the authenticating user. It can be determined using the [getAccounts](#get-existing-accounts-of-the-user---bariongetaccountsoptions-callback) function (string). (required)
+
+  - ``Amount``: The total amount to transfer ([Money](https://docs.barion.com/Money)). (required)
+
+  - ``TargetEmail``: The recipient's email address. If they are an active Barion user, they receive the money instantly. If the e-mail address is not registered in Barion, they must register in 7 days  to claim the money (string). (required)
+
+  - ``Comment``: Comment of the transfer (string). (optional)
+
+**Output**: [Read at Barion Docs](https://docs.barion.com/Transfer-Email-v2#Output_properties)
+
+#### Usage example
+##### With callback
+```js
+barion.emailTransfer({
+    UserName: 'info@example.com',
+    Password: 'someRlyStrongP4ss#!',
+    SourceAccountId: 'bdf45c1d-bb98-4fee-bbf1-62411fb26b86',
+    Amount: {
+        Currency: 'HUF',
+        Value: 50
+    },
+    TargetEmail: 'hello@example.com',
+    Comment: 'Buy some milk please.'
+}, function (err, data) {
+    //handle error / process data
+});
+```
+##### With promise
+```js
+barion.emailTransfer({
+    UserName: 'info@example.com',
+    Password: 'someRlyStrongP4ss#!',
+    SourceAccountId: 'bdf45c1d-bb98-4fee-bbf1-62411fb26b86',
+    Amount: {
+        Currency: 'HUF',
+        Value: 50
+    },
+    TargetEmail: 'hello@example.com',
+    Comment: 'Buy some milk please.'
+}).then(data => {
+    //process data
+}).catch(err => {
+    //handle error
+});
+```
+
 ### Send money to a Barion user or email address - barion.barionTransfer(options, \[callback\])
+![][DEPRECATED]
+> **IMPORTANT**: This function is deprecated since version 2.1.0, and will be removed in the next major version of the module.
+> Please use the [emailTransfer](#send-e-money-to-an-email-address---barionemailtransferoptions-callback) function instead.
+
 To send money to a Barion user or to an email address, call the ``barionTransfer`` function. [[Barion Docs](https://docs.barion.com/Transfer-Send-v1)]
 
 **Parameters**:
@@ -638,3 +732,4 @@ Unless otherwise stated in sources, the terms specified in LICENSE file are appl
 <!-- References -->
 [3DS]: https://img.shields.io/badge/-3DS-yellow "Required for 3DS"
 [TEST-ONLY]: https://img.shields.io/badge/-TEST%20ONLY-red "Feature is currently only available on the sandox server"
+[DEPRECATED]: https://img.shields.io/badge/-deprecated-red "Deprecated feature"

lib/barion.js

@@ -7,7 +7,9 @@ const {
     CancelAuthorization,
     PaymentRefund,
     BankTransfer,
-    SendTransfer
+    GetAccounts,
+    SendTransfer,
+    EmailTransfer
 } = require('./domain');
 const { buildRequest, buildRequestWithoutValidation } = require('./build');
 const { sanitizeThenValidate } = require('./validate');
@@ -186,11 +188,27 @@ Barion.prototype.bankTransfer = function (options, callback) {
     }, callback);
 };
 
+/**
+ * Queries the existing accounts of the calling user.
+ * @param {Object} options - Options that are required to query the existing accounts.
+ * @param {Function} [callback] - Callback that handles the response. If not passed, the function returns a *Promise*.
+ * @see {@link https://docs.barion.com/Accounts-Get-v2|Barion API Documentation}
+ */
+Barion.prototype.getAccounts = function (options, callback) {
+    return doRequestAndReturn({
+        defaults: this.defaults,
+        customs: options,
+        schema: GetAccounts,
+        service: services.getAccounts
+    }, callback);
+};
+
 /**
  * Sends money between accounts in Barion.
  * @param {Object} options - Options that are required to send money to Barion user.
  * @param {Function} [callback] - Callback that handles the response. If not passed, the function returns a *Promise*.
  * @see {@link https://docs.barion.com/Transfer-Send-v1|Barion API Documentation}
+ * @deprecated since version 2.1.0
  */
 Barion.prototype.barionTransfer = function (options, callback) {
     return doRequestAndReturn({
@@ -201,4 +219,19 @@ Barion.prototype.barionTransfer = function (options, callback) {
     }, callback);
 };
 
+/**
+ * Sends e-money to a given e-mail address.
+ * @param {Object} options - Options that are required to send money.
+ * @param {Function} [callback] - Callback that handles the response. If not passed, the function returns a *Promise*.
+ * @see {@link https://docs.barion.com/Transfer-Email-v2|Barion API Documentation}
+ */
+Barion.prototype.emailTransfer = function (options, callback) {
+    return doRequestAndReturn({
+        defaults: this.defaults,
+        customs: options,
+        schema: EmailTransfer,
+        service: services.emailTransfer
+    }, callback);
+};
+
 module.exports = Barion;

lib/constants.js

@@ -6,7 +6,9 @@ const {
     CancelAuthorization,
     PaymentRefund,
     BankTransfer,
-    SendTransfer
+    GetAccounts,
+    SendTransfer,
+    EmailTransfer
 } = require('./domain');
 
 /**
@@ -54,10 +56,20 @@ module.exports = {
             path: '/v2/Withdraw/BankTransfer',
             model: BankTransfer
         },
+        getAccounts: {
+            method: 'GET',
+            path: '/v2/Accounts/Get',
+            model: GetAccounts
+        },
         barionTransfer: {
             method: 'POST',
             path: '/v1/Transfer/Send',
             model: SendTransfer
+        },
+        emailTransfer: {
+            method: 'POST',
+            path: '/v2/Transfer/Email',
+            model: EmailTransfer
         }
     }
 };

lib/domain/EmailTransfer.js

@@ -0,0 +1,24 @@
+const Joi = require('@hapi/joi');
+const { CaseInsensitiveSchema } = require('../schema');
+
+const Money = require('./common/Money');
+
+/**
+ * Used to send e-money to a given e-mail address. 
+ *
+ * @see {@link https://docs.barion.com/Transfer-Email-v2|Barion API Documentation}
+ */
+const schema = Joi.object({
+    UserName: Joi.string().required()
+        .email(),
+    Password: Joi.string().required(),
+    SourceAccountId: Joi.string().required()
+        .guid(),
+    Amount: Money.required(),
+    TargetEmail: Joi.string().required()
+        .email(),
+    Comment: Joi.string().optional()
+        .max(1000)
+});
+
+module.exports = new CaseInsensitiveSchema(schema);

lib/domain/GetAccounts.js

@@ -0,0 +1,15 @@
+const Joi = require('@hapi/joi');
+const { CaseInsensitiveSchema } = require('../schema');
+
+/**
+ * Used to query the existing accounts of the calling user.
+ *
+ * @see {@link https://docs.barion.com/Accounts-Get-v2|Barion API Documentation}
+ */
+const schema = Joi.object({
+    UserName: Joi.string().required()
+        .email(),
+    Password: Joi.string().required()
+});
+
+module.exports = new CaseInsensitiveSchema(schema);

lib/domain/common/Money.js

@@ -0,0 +1,18 @@
+const Joi = require('@hapi/joi');
+const { CaseInsensitiveSchema } = require('../../schema');
+
+const constraints = require('../_constraints');
+
+/**
+ * This structure represents an amount of money in the Barion system. 
+ *
+ * @see {@link https://docs.barion.com/Money|Barion API Documentation}
+ */
+const schema = Joi.object({
+    Currency: Joi.string().required()
+        .valid(...constraints.Currency),
+    Value: Joi.number().required()
+        .greater(0)
+});
+
+module.exports = new CaseInsensitiveSchema(schema);

lib/domain/index.js

@@ -6,7 +6,9 @@ const CapturePayment = require('./CapturePayment');
 const CancelAuthorization = require('./CancelAuthorization');
 const PaymentRefund = require('./PaymentRefund');
 const BankTransfer = require('./BankTransfer');
+const GetAccounts = require('./GetAccounts');
 const SendTransfer = require('./SendTransfer');
+const EmailTransfer = require('./EmailTransfer');
 
 module.exports = {
     InitialOptions,
@@ -17,5 +19,7 @@ module.exports = {
     CancelAuthorization,
     PaymentRefund,
     BankTransfer,
-    SendTransfer
+    GetAccounts,
+    SendTransfer,
+    EmailTransfer
 };

lib/services.js

@@ -99,15 +99,34 @@ function bankTransfer (environment, options) {
     return doRequest(environment, endPoints.bankTransfer, options);
 }
 
+/**
+ * Queries the existing accounts of the calling user. 
+ * @param {String} environment - The environment to use ('test' or 'prod').
+ * @param {Object} options - The final request body to send to the Barion API.
+ */
+function getAccounts (environment, options) {
+    return doRequest(environment, endPoints.getAccounts, options);
+}
+
 /**
  * Sends money between accounts in Barion.
  * @param {String} environment - The environment to use ('test' or 'prod').
  * @param {Object} options - The final request body to send to the Barion API.
  */
 function barionTransfer (environment, options) {
+    console.warn('WARNING! node-barion module\'s barionTransfer function has been deprecated since version 2.1.0 and will be removed in the next major version of the module. Please use the "emailTransfer" function instead.');
     return doRequest(environment, endPoints.barionTransfer, options);
 }
 
+/**
+ * Sends money to an email address.
+ * @param {String} environment - The environment to use ('test' or 'prod').
+ * @param {Object} options - The final request body to send to the Barion API.
+ */
+function emailTransfer (environment, options) {
+    return doRequest(environment, endPoints.emailTransfer, options);
+}
+
 module.exports = {
     startPayment,
     getPaymentState,
@@ -116,7 +135,9 @@ module.exports = {
     captureAuthorizedPayment,
     cancelAuthorizedPayment,
     bankTransfer,
+    getAccounts,
     barionTransfer,
+    emailTransfer,
     _private: {
         getBaseUrl,
         doRequest