@mft/moneyhub-api-client 4.14.0 → 4.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mft/moneyhub-api-client",
-  "version": "4.14.0",
+  "version": "4.16.0",
   "description": "Node.JS client for the Moneyhub API",
   "main": "src/index.js",
   "scripts": {
@@ -21,23 +21,23 @@
   "repository": "moneyhub/moneyhub-api-client",
   "license": "ISC",
   "dependencies": {
-    "form-data": "^3.0.0",
+    "form-data": "^3.0.1",
     "got": "^11.8.3",
     "jose": "^2.0.5",
-    "openid-client": "^4.2.2",
-    "ramda": "^0.27.1"
+    "openid-client": "^4.9.1",
+    "ramda": "^0.27.2"
   },
   "devDependencies": {
     "@mft/eslint-config-momentumft": "^4.0.0",
-    "body-parser": "^1.19.0",
-    "chai": "^4.2.0",
-    "command-line-args": "^5.1.1",
+    "body-parser": "^1.19.2",
+    "chai": "^4.3.6",
+    "command-line-args": "^5.2.1",
     "command-line-usage": "^6.1.1",
-    "config": "^3.3.6",
+    "config": "^3.3.7",
     "eslint": "^7.32.0",
-    "express": "^4.17.1",
-    "husky": "^7.0.2",
-    "mocha": "^9.2.0",
+    "express": "^4.17.3",
+    "husky": "^7.0.4",
+    "mocha": "^9.2.2",
     "mocha-junit-reporter": "^2.0.2"
   },
   "husky": {

package/readme.md

@@ -289,7 +289,7 @@ Creates a request object
 const tokens = await moneyhub.requestObject({
   scope: "the-required-scope",
   state: "state",
-  nonce: "nonce,
+  nonce: "nonce",
   claims: claimsObject,
 })
 ```
@@ -322,7 +322,7 @@ Creates a connection auth request
 
 ```javascript
 const tokens = await moneyhub.createAuthRequest({
-  redirectUri: "redirect-uri,
+  redirectUri: "redirect-uri",
   userId: "user-id",
   scope:"openid 1ffe704d39629a929c8e293880fb449a", // replace bank id with the bank you want to connect to
   categorisationType: "personal", // optional - defaults to personal
@@ -334,7 +334,7 @@ Creates a reauth auth request
 
 ```javascript
 const tokens = await moneyhub.createAuthRequest({
-  redirectUri: "redirect-uri,
+  redirectUri: "redirect-uri",
   userId: "user-id",
   connectionId: "connection-id",
   scope:"openid reauth",
@@ -345,7 +345,7 @@ Creates a refresh auth request
 
 ```javascript
 const tokens = await moneyhub.createAuthRequest({
-  redirectUri: "redirect-uri,
+  redirectUri: "redirect-uri",
   userId: "user-id",
   connectionId: "connection-id",
   scope:"openid refresh",
@@ -356,14 +356,14 @@ Creates a payment auth request
 
 ```javascript
 const tokens = await moneyhub.createAuthRequest({
-  redirectUri: "redirect-uri,
+  redirectUri: "redirect-uri",
   userId: "user-id",
   connectionId: "connection-id",
   scope:"openid payment",
   payment: {
     payeeId: "payee-id",
     amount: 200,
-    payeeRef: "Payee ref,
+    payeeRef: "Payee ref",
     payerRef: "Payer ref"
   },
 })
@@ -373,7 +373,7 @@ Creates a reverse payment auth request
 
 ```javascript
 const tokens = await moneyhub.createAuthRequest({
-  redirectUri: "redirect-uri,
+  redirectUri: "redirect-uri",
   userId: "user-id",
   connectionId: "connection-id",
   scope:"openid reverse_payment",
@@ -438,7 +438,7 @@ Helper method that gets the correct client credentials access token and then reg
 
 ```javascript
 const user = await moneyhub.registerUser({
-  clientUserId: "your user id" /* optional */
+  clientUserId: "your user id" // optional
 })
 ```
 
@@ -1113,7 +1113,7 @@ const url = await moneyhub.getPaymentAuthorizeUrl({
   state: "your state value",
   nonce: "your nonce value", // optional
   context: "Payment context [Other,BillPayment,PartyToParty]", // optional - defaults to PartyToParty
-  userId: "Moneyhub API User ID you wish to attach to the payment" // optional
+  userId: "Moneyhub API User ID you wish to attach to the payment", // optional
   claims: claimsObject, // optional
 })
 
@@ -1333,6 +1333,122 @@ const standingOrder = await moneyhub.getStandingOrder({
 })
 ```
 
+### Recurring Payments (VRP)
+
+#### `getRecurringPaymentAuthorizeUrl`
+
+This is a helper function that returns an authorize url to authorize a recurring payment with the selected bank. This function uses the following scope with the value of the bankId provided `recurring_payment:create openid id:${bankId}`. It also requires the authentication to be `client_secret_jwt` or `private_key_jwt`.
+
+```javascript
+const url = await moneyhub.getRecurringPaymentAuthorizeUrl({
+  bankId: "Bank id to authorise payment from",
+  payeeId: "Id of payee",
+  payeeType: "Payee type [api-payee|mh-user-account]", // optional - defaults to api-payee
+  payerId: "Id of payer", // requird only if payerType is defined
+  payerType: "Payer type [mh-user-account]", // required only if payerId is used
+  reference: "The reference for recurring payment",
+  validFromDate: "The date from which the authorisation is effective" , // should be in an international format, e.g. 15-MAR-2021 or ISO date
+  validToDate: "The date to which the authorisation is effective", // should be in an international format, e.g. 15-MAR-2021 or ISO date
+  maximumIndividualAmount: "The maimum single amount that will be allowed", // the valid in whole minor units (i.e. pence)
+  currency: "The currency code for the maxiumum recurring payment amount [GBP]",
+  periodicLimits: [
+    {
+      amount: "The maximum amount for this recurring payment limit", // the valid in whole minor units (i.e. pence)
+      currency: "The currency code for this recurring payment limit [GBP]",
+      periodType: "The period over which the limit is effective [Day, Week, Fortnight, Month, Half-year, Year]",
+      periodAlignment: "Specifies whether the period starts on the date of consent creation or lines up with a calendar [Consent, Calendar]",   
+    }
+  ],
+  type: [ 
+    "Sweeping", // Specifies that the recurring payment is for the purpose of sweeping payments
+    "Other" // Specifies that the recurring payment is for other payments of another purpose
+  ],
+  context: "Payment context [Other,BillPayment,PartyToParty]", // optional - defaults to PartyToParty
+  state: "your state value",
+  nonce: "your nonce value", // optional
+  claims: claimsObject, // optional
+})
+
+// Scope used with the bankId provided
+const scope = `recurring_payment:create openid id:${bankId}`
+
+// Default claims if none are provided
+const defaultClaims = {
+  id_token: {
+    "mh:con_id": {
+      essential: true,
+    },
+    "mh:recurring_payment": {
+      essential: true,
+      value: {
+        payeeId,
+        payeeType,
+        payerId,
+        payerType,
+        reference,
+        validFromDate,
+        validToDate,
+        maximumIndividualAmount,
+        currency,
+        periodicLimits,
+        context,
+      },
+    },
+  },
+}
+```
+
+#### `getRecurringPayments`
+
+This method returns a list of initiated recurring payment consents. This function uses the scope `recurring_payment:read`
+
+```javascript
+const recurringPayments = await moneyhub.getRecurringPayments({
+  limit: "limit", // optional
+  offset: "offset", // optional
+  userId: "user-id", // optional
+  payeeId: "payee-id", // optional
+  startDate: "2020-01-01", // optional
+  endDate: "2020-12-31", // optional
+})
+```
+
+#### `getRecurringPayment`
+
+This method gets a recurring payment consent. This function uses the scope `recurring_payment:create`
+
+```javascript
+const recurringPayment = await moneyhub.getRecurringPayment({
+  recurringPaymentId: "Id of the recurring payment consent"
+})
+```
+
+#### `makeRecurringPayment`
+
+This method creates a payment using the recurring payment consent. This function uses the scope `recurring_payment:create`
+
+```javascript
+const recurringPayments = await moneyhub.getRecurringPayments({
+  recurringPaymentId: "Id of the recurring payment consent",
+  payment: {
+    payeeId: "payee-id", // optional
+    amount: 200,
+    payeeRef: "Payee ref",
+    payerRef: "Payer ref"
+  }
+})
+```
+
+#### `revokeRecurringPayment`
+
+This method revokes a recurring payment consent. This function uses the scope `recurring_payment:create`
+
+```javascript
+const revokedRecurringPayment = await moneyhub.revokeRecurringPayment({
+  recurringPaymentId: "Id of the recurring payment consent"
+})
+```
+
 #### `getRegularTransactions`
 
 Get all the regular transactions for a user, there is an option to pass an account ID as a parameter as a filter. This function uses the scope `accounts:read`, `transactions:read:all` and `regular_transactions:read`

package/src/__tests__/index.js

@@ -92,6 +92,10 @@ describe("API client", () => {
         "getRentalRecords",
         "createRentalRecord",
         "deleteRentalRecord",
+        "getRecurringPayments",
+        "getRecurringPayment",
+        "makeRecurringPayment",
+        "revokeRecurringPayment",
         "getAuthorizeUrl",
         "getAuthorizeUrlFromRequestUri",
         "requestObject",
@@ -101,6 +105,7 @@ describe("API client", () => {
         "getRefreshAuthorizeUrlForCreatedUser",
         "getPaymentAuthorizeUrl",
         "getReversePaymentAuthorizeUrl",
+        "getRecurringPaymentAuthorizeUrl",
         "getStandingOrderAuthorizeUrl",
         "exchangeCodeForTokensLegacy",
         "exchangeCodeForTokens",

package/src/get-auth-urls.js

@@ -329,6 +329,77 @@ module.exports = ({client, config}) => {
       return url
     },
 
+    getRecurringPaymentAuthorizeUrl: async ({
+      bankId,
+      payeeId,
+      payeeType,
+      payerId,
+      payerType,
+      reference,
+      validFromDate,
+      validToDate,
+      maximumIndividualAmount,
+      currency,
+      periodicLimits,
+      type,
+      context,
+      state,
+      nonce,
+      userId,
+      claims = {},
+    }) => {
+      if (!state) {
+        console.error("State is required")
+        throw new Error("Missing parameters")
+      }
+
+      const scope = `recurring_payment:create openid id:${bankId}`
+      const defaultClaims = {
+        id_token: {
+          "mh:con_id": {
+            essential: true,
+          },
+          "mh:recurring_payment": {
+            essential: true,
+            value: {
+              payeeId,
+              payeeType,
+              payerId,
+              payerType,
+              reference,
+              validFromDate,
+              validToDate,
+              maximumIndividualAmount,
+              currency,
+              periodicLimits,
+              type,
+              context,
+            },
+          },
+          ...userId && {
+            sub: {
+              value: userId
+            }
+          }
+        },
+      }
+
+      const _claims = R.mergeDeepRight(defaultClaims, claims)
+
+      const request = await requestObject({
+        scope,
+        state,
+        claims: _claims,
+        nonce,
+      })
+
+      const requestUri = await getRequestUri(request)
+      const url = getAuthorizeUrlFromRequestUri({
+        requestUri,
+      })
+      return url
+    },
+
     getStandingOrderAuthorizeUrl: async ({
       bankId,
       payeeId,

package/src/index.js

@@ -20,7 +20,8 @@ const requestFactories = [
   require("./requests/categories"),
   require("./requests/standing-orders"),
   require("./requests/regular-transactions"),
-  require("./requests/rental-records")
+  require("./requests/rental-records"),
+  require("./requests/recurring-payments"),
 ]
 const DEFAULT_TIMEOUT = 60000
 

package/src/requests/recurring-payments.js

@@ -0,0 +1,37 @@
+module.exports = ({config, request}) => {
+  const {identityServiceUrl} = config
+
+  return {
+    getRecurringPayments: async (params = {}) =>
+      request(`${identityServiceUrl}/recurring-payments`, {
+        searchParams: params,
+        cc: {
+          scope: "recurring_payment:read",
+        },
+      }),
+
+    getRecurringPayment: async ({recurringPaymentId}) =>
+      request(`${identityServiceUrl}/recurring-payments/${recurringPaymentId}`, {
+        cc: {
+          scope: "recurring_payment:read",
+        },
+      }),
+
+    makeRecurringPayment: async ({recurringPaymentId, payment}) =>
+      request(`${identityServiceUrl}/recurring-payments/${recurringPaymentId}/pay`, {
+        method: "POST",
+        body: payment,
+        cc: {
+          scope: "recurring_payment:create",
+        },
+      }),
+
+    revokeRecurringPayment: async ({recurringPaymentId}) =>
+      request(`${identityServiceUrl}/recurring-payments/${recurringPaymentId}`, {
+        method: "DELETE",
+        cc: {
+          scope: "recurring_payment:create",
+        },
+      }),
+  }
+}