sfmc-sdk 0.6.3 → 0.8.0

package/.eslintrc.json

@@ -5,6 +5,7 @@
         "mocha": true
     },
     "extends": [
+        "plugin:unicorn/recommended",
         "eslint:recommended",
         "plugin:mocha/recommended",
         "plugin:jsdoc/recommended",
@@ -18,5 +19,42 @@
     "parserOptions": {
         "ecmaVersion": 2020,
         "sourceType": "module"
+    },
+    "settings": {
+        "jsdoc": {
+            "mode": "jsdoc",
+            "preferredTypes": {
+                "array": "Array",
+                "array.<>": "[]",
+                "Array.<>": "[]",
+                "array<>": "[]",
+                "Array<>": "[]",
+                "Object": "object",
+                "object.<>": "Object.<>",
+                "object<>": "Object.<>",
+                "Object<>": "Object.<>",
+                "promise": "Promise",
+                "promise.<>": "Promise.<>",
+                "promise<>": "Promise.<>",
+                "Promise<>": "Promise.<>"
+            }
+        }
+    },
+    "rules": {
+        "unicorn/prefer-module": "off",
+        "unicorn/numeric-separators-style": "off",
+        "jsdoc/check-line-alignment": 2,
+        "jsdoc/require-jsdoc": [
+            "warn",
+            {
+                "require": {
+                    "FunctionDeclaration": true,
+                    "MethodDefinition": true,
+                    "ClassDeclaration": true,
+                    "ArrowFunctionExpression": false,
+                    "FunctionExpression": true
+                }
+            }
+        ]
     }
 }

package/.fork/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 40,
+  "trailingComma": "none"
+}

package/.fork/custom-commands.json

@@ -0,0 +1,26 @@
+[
+  {
+    "name": "Create PR to develop branch",
+    "target": "ref",
+    "refTargets": [
+      "localbranch",
+      "remotebranch"
+    ],
+    "action": {
+      "type": "url",
+      "url": "https://github.com/DougMidgley/SFMC-SDK/compare/develop...$shortname?expand=1"
+    }
+  },
+  {
+    "name": "Create PR to hotfix branch",
+    "target": "ref",
+    "refTargets": [
+      "localbranch",
+      "remotebranch"
+    ],
+    "action": {
+      "type": "url",
+      "url": "https://github.com/DougMidgley/SFMC-SDK/compare/hotfix...$shortname?expand=1"
+    }
+  }
+]

package/.gitattributes

@@ -1,5 +1,2 @@
 # Set the default behavior, in case people don't have core.autocrlf set.
-* text=auto eol=lf
-
-# Declare files that will always have LF line endings on checkout.
-*.ssjs text eol=lf
+* text=auto eol=lf

package/.husky/commit-msg

@@ -0,0 +1,10 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+INPUT_FILE=$1
+START_LINE=`head -n1 $INPUT_FILE`
+PATTERN="^(#[[:digit:]]|Merge)"
+
+if ! [[ "$START_LINE" =~ $PATTERN ]] ; then
+  echo "Bad commit message, see example: \"#431 commit message\", you provided: \"$START_LINE\""
+  exit 1
+fi

package/.husky/post-checkout

@@ -0,0 +1,5 @@
+#!/bin/sh
+git config commit.template .git/templatemessage
+TICKETID=`git rev-parse --abbrev-ref HEAD | LC_ALL=en_US.utf8 grep -oP '((feature|bug|bugfix|fix|hotfix|task|chore)\/)\K\d{1,7}'`
+echo "[POST_CHECKOUT] Setting template commit to $TICKETID"
+echo "#$TICKETID: " > ".git/templatemessage"

package/lib/auth.js

@@ -1,5 +1,4 @@
 'use strict';
-
 const axios = require('axios');
 const { isConnectionError, RestError } = require('./util');
 const AVAIALABLE_SCOPES = [
@@ -99,7 +98,7 @@ module.exports = class Auth {
      * @param {string} authObject.client_secret Client Secret from SFMC config
      * @param {number} authObject.account_id MID of Business Unit used for API Calls
      * @param {string} authObject.auth_url Auth URL from SFMC config
-     * @param {Array<string>} [authObject.scope] Array of scopes used for requests
+     * @param {string[]} [authObject.scope] Array of scopes used for requests
      * @param {object} options options for the SDK as a whole, for example collection of handler functions, or retry settings
      */
     constructor(authObject, options) {
@@ -108,23 +107,23 @@ module.exports = class Auth {
         } else if (!authObject.client_id) {
             throw new Error('client_id or client_secret is missing or invalid');
         } else if (typeof authObject.client_id !== 'string') {
-            throw new Error('client_id or client_secret must be strings');
+            throw new TypeError('client_id or client_secret must be strings');
         } else if (!authObject.client_secret) {
             throw new Error('client_id or client_secret is missing or invalid');
         } else if (typeof authObject.client_secret !== 'string') {
-            throw new Error('client_id or client_secret must be strings');
+            throw new TypeError('client_id or client_secret must be strings');
         } else if (!authObject.account_id) {
             throw new Error('account_id is missing or invalid');
         } else if (!Number.isInteger(Number.parseInt(authObject.account_id))) {
-            throw new Error(
+            throw new TypeError(
                 'account_id must be an Integer (Integers in String format are accepted)'
             );
         } else if (!authObject.auth_url) {
             throw new Error('auth_url is missing or invalid');
         } else if (typeof authObject.auth_url !== 'string') {
-            throw new Error('auth_url must be a string');
+            throw new TypeError('auth_url must be a string');
         } else if (
-            !/https:\/\/[a-z0-9-]{28}\.auth\.marketingcloudapis\.com\//gm.test(authObject.auth_url)
+            !/https:\/\/[\da-z-]{28}\.auth\.marketingcloudapis\.com\//gm.test(authObject.auth_url)
         ) {
             throw new Error(
                 'auth_url must be in format https://mcXXXXXXXXXXXXXXXXXXXXXXXXXX.auth.marketingcloudapis.com/'
@@ -134,7 +133,7 @@ module.exports = class Auth {
         } else if (authObject.scope && getInvalidScopes(authObject.scope).length > 0) {
             throw new Error(
                 getInvalidScopes(authObject.scope)
-                    .map((val) => '"' + val + '"')
+                    .map((value) => '"' + value + '"')
                     .join(',') + ' is/are invalid scope(s)'
             );
         }
@@ -146,7 +145,7 @@ module.exports = class Auth {
      *
      * @param {boolean} forceRefresh used to enforce a refresh of token
      * @param {number} remainingAttempts number of retries in case of issues
-     * @returns {Promise<object>} current session information
+     * @returns {Promise.<object>} current session information
      */
     async getAccessToken(forceRefresh, remainingAttempts) {
         if (remainingAttempts === undefined) {
@@ -156,19 +155,19 @@ module.exports = class Auth {
             try {
                 remainingAttempts--;
                 this.authObject = await _requestToken(this.authObject);
-            } catch (ex) {
+            } catch (error) {
                 if (
                     this.options.retryOnConnectionError &&
                     remainingAttempts > 0 &&
-                    isConnectionError(ex.code)
+                    isConnectionError(error.code)
                 ) {
                     if (this.options?.eventHandlers?.onConnectionError) {
-                        this.options.eventHandlers.onConnectionError(ex, remainingAttempts);
+                        this.options.eventHandlers.onConnectionError(error, remainingAttempts);
                     }
                     return this.getAccessToken(forceRefresh, remainingAttempts);
                 }
 
-                throw new RestError(ex);
+                throw new RestError(error);
             }
 
             if (this.options?.eventHandlers?.onRefresh) {
@@ -205,7 +204,7 @@ function _isExpired(authObject) {
 }
 /**
  * @param {object} authObject Auth Object for api calls
- * @returns {Promise<object>} updated Auth Object
+ * @returns {Promise.<object>} updated Auth Object
  */
 async function _requestToken(authObject) {
     // TODO retry logic
@@ -218,19 +217,19 @@ async function _requestToken(authObject) {
     if (authObject.scope && Array.isArray(authObject.scope)) {
         payload.scope = authObject.scope.join(' ');
     }
-    const res = await axios({
+    const result = await axios({
         method: 'post',
         baseURL: authObject.auth_url,
         url: '/v2/token',
         data: payload,
     });
-    return Object.assign(authObject, res.data, {
-        expiration: process.hrtime()[0] + res.data.expires_in,
+    return Object.assign(authObject, result.data, {
+        expiration: process.hrtime()[0] + result.data.expires_in,
     });
 }
 /**
- * @param {Array<string>} scopes list of scopes requested for the auth
- * @returns {Array<string>} list of invalid scopes
+ * @param {string[]} scopes list of scopes requested for the auth
+ * @returns {string[]} list of invalid scopes
  */
 function getInvalidScopes(scopes) {
     return scopes.filter((scope) => !AVAIALABLE_SCOPES.includes(scope));

package/lib/index.js

@@ -1,3 +1,4 @@
+'use strict';
 const Auth = require('./auth');
 const Rest = require('./rest');
 const Soap = require('./soap');

package/lib/rest.js

@@ -1,5 +1,4 @@
 'use strict';
-
 const axios = require('axios');
 const { isObject, isPayload, isConnectionError, RestError } = require('./util');
 const pLimit = require('p-limit');
@@ -26,7 +25,7 @@ module.exports = class Rest {
      * Method that makes the GET API request
      *
      * @param {string} url of the resource to retrieve
-     * @returns {Promise<object>} API response
+     * @returns {Promise.<object>} API response
      */
     get(url) {
         return this._apiRequest(
@@ -37,51 +36,87 @@ module.exports = class Rest {
             this.options.requestAttempts
         );
     }
-    isTransactionalMessageApi(url) {
+    /**
+     * helper for {@link getBulk} to determine if the url is a transactional message API
+     *
+     * @private
+     * @param {string} url url without query params
+     * @returns {boolean} true if the url is a transactional message API
+     */
+    _isTransactionalMessageApi(url) {
         return url && this.transactionalApis.some((api) => url.includes(api));
     }
+    /**
+     * helper for {@link getBulk} to determine if the url is a legacy API
+     *
+     * @private
+     * @param {string} url url without query params
+     * @returns {boolean} true if the url is a legacy API
+     */
+    _isLegacyApi(url) {
+        return url && url.startsWith('/legacy/v1/');
+    }
     /**
      * Method that makes paginated GET API Requests using $pageSize and $page parameters
      *
      * @param {string} url of the resource to retrieve
      * @param {number} [pageSize] of the response, defaults to 50
-     * @returns {Promise<object>} API response combined items
+     * @param {string} [iteratorField] attribute of the response to iterate over (only required if it's not 'items'|'definitions'|'entry')
+     * @returns {Promise.<object>} API response combined items
      */
-    async getBulk(url, pageSize) {
-        let iteratorField;
+    async getBulk(url, pageSize, iteratorField) {
         let page = 1;
         const baseUrl = url.split('?')[0];
-        const isTransactionalMessageApi = this.isTransactionalMessageApi(baseUrl);
-        const queryParams = new URLSearchParams(url.split('?')[1]);
+        const isTransactionalMessageApi = this._isTransactionalMessageApi(baseUrl);
+        const isLegacyApi = this._isLegacyApi(baseUrl);
+        const queryParameters = new URLSearchParams(url.split('?')[1]);
         let collector;
         let shouldPaginate = false;
-        queryParams.set('$pageSize', Number(pageSize || 50).toString());
+        let pageSizeKey = '$pageSize';
+        let pageKey = '$page';
+        let countKey = 'count';
+        if (isLegacyApi) {
+            pageSizeKey = '$top';
+            pageKey = '$skip';
+            countKey = 'totalResults';
+            page = 0; // legacy index starts with 0
+            if (pageSize != 50) {
+                // values other than 50 are ignored by at least some of the sub-endpoints; while others have 50 as the maximum.
+                pageSize = 50;
+            }
+        }
+        queryParameters.set(pageSizeKey, Number(pageSize || 50).toString());
         do {
-            queryParams.set('$page', Number(page).toString());
-            const temp = await this._apiRequest(
+            queryParameters.set(pageKey, Number(page).toString());
+            const responseBatch = await this._apiRequest(
                 {
                     method: 'GET',
-                    url: baseUrl + '?' + decodeURIComponent(queryParams.toString()),
+                    url: baseUrl + '?' + decodeURIComponent(queryParameters.toString()),
                 },
                 this.options.requestAttempts
             );
-            if (Array.isArray(temp.items)) {
+            if (iteratorField && Array.isArray(responseBatch[iteratorField])) {
+                // if the iteratorField is set, use it
+            } else if (Array.isArray(responseBatch.items)) {
                 iteratorField = 'items';
-            } else if (Array.isArray(temp.definitions)) {
+            } else if (Array.isArray(responseBatch.definitions)) {
                 iteratorField = 'definitions';
+            } else if (Array.isArray(responseBatch.entry)) {
+                iteratorField = 'entry';
             } else {
-                throw new Error('Could not find an array to iterate over');
+                throw new TypeError('Could not find an array to iterate over');
             }
-            if (collector && Array.isArray(temp[iteratorField])) {
-                collector[iteratorField].push(...temp[iteratorField]);
-            } else if (collector == null) {
-                collector = temp;
+            if (collector && Array.isArray(responseBatch[iteratorField])) {
+                collector[iteratorField].push(...responseBatch[iteratorField]);
+            } else if (!collector) {
+                collector = responseBatch;
             }
             if (
                 Array.isArray(collector[iteratorField]) &&
-                collector[iteratorField].length >= temp.count &&
+                collector[iteratorField].length >= responseBatch[countKey] &&
                 (!isTransactionalMessageApi ||
-                    (isTransactionalMessageApi && temp.count != temp.pageSize))
+                    (isTransactionalMessageApi &&
+                        responseBatch[countKey] != responseBatch[pageSizeKey]))
             ) {
                 // ! the transactional message API returns a value for "count" that represents the currently returned number of records, instead of the total amount. checking for count != pageSize is a workaround for this
                 // * opened Support Case #43988240 for this issue
@@ -90,6 +125,8 @@ module.exports = class Rest {
                 page++;
                 shouldPaginate = true;
                 if (this.options?.eventHandlers?.onLoop) {
+                    // TODO in v1 change to undefined to ensure breaking changes considered
+                    // eslint-disable-next-line unicorn/no-null
                     this.options.eventHandlers.onLoop(null, collector?.[iteratorField]);
                 }
             }
@@ -99,9 +136,9 @@ module.exports = class Rest {
     /**
      * Method that makes a GET API request for each URL (including rate limiting)
      *
-     * @param {Array<string>} urlArray of the resource to retrieve
+     * @param {string[]} urlArray of the resource to retrieve
      * @param {number} [concurrentLimit=5] number of requests to execute at once
-     * @returns {Promise<Array>} API response
+     * @returns {Promise.<Array>} API response
      */
     async getCollection(urlArray, concurrentLimit) {
         const limit = pLimit(concurrentLimit || 5);
@@ -126,7 +163,7 @@ module.exports = class Rest {
      *
      * @param {string} url of the resource to create
      * @param {object} payload for the POST request body
-     * @returns {Promise<object>} API response
+     * @returns {Promise.<object>} API response
      */
     post(url, payload) {
         const requestOptions = {
@@ -142,7 +179,7 @@ module.exports = class Rest {
      *
      * @param {string} url of the resource to replace
      * @param {object} payload for the PUT request body
-     * @returns {Promise<object>} API response
+     * @returns {Promise.<object>} API response
      */
     put(url, payload) {
         const requestOptions = {
@@ -158,7 +195,7 @@ module.exports = class Rest {
      *
      * @param {string} url of the resource to update
      * @param {object} payload for the PATCH request body
-     * @returns {Promise<object>} API response
+     * @returns {Promise.<object>} API response
      */
     patch(url, payload) {
         const requestOptions = {
@@ -173,7 +210,7 @@ module.exports = class Rest {
      * Method that makes the DELETE api request
      *
      * @param {string} url of the resource to delete
-     * @returns {Promise<object>} API response
+     * @returns {Promise.<object>} API response
      */
     delete(url) {
         return this._apiRequest(
@@ -190,7 +227,7 @@ module.exports = class Rest {
      *
      * @param {object} requestOptions configuration for the request including body
      * @param {number} remainingAttempts number of times this request should be reattempted in case of error
-     * @returns {Promise<object>} Results from the Rest request in Object format
+     * @returns {Promise.<object>} Results from the Rest request in Object format
      */
     async _apiRequest(requestOptions, remainingAttempts) {
         if (!isObject(requestOptions)) {
@@ -214,9 +251,9 @@ module.exports = class Rest {
                 });
             }
             return response.data;
-        } catch (ex) {
+        } catch (error) {
             if (requestOptions.url) {
-                ex.endpoint =
+                error.endpoint =
                     requestOptions.baseURL +
                     (requestOptions.url.startsWith('/')
                         ? requestOptions.url.slice(1)
@@ -225,19 +262,19 @@ module.exports = class Rest {
             if (
                 this.options.retryOnConnectionError &&
                 remainingAttempts > 0 &&
-                isConnectionError(ex.code)
+                isConnectionError(error.code)
             ) {
                 if (this.options?.eventHandlers?.onConnectionError) {
-                    this.options.eventHandlers.onConnectionError(ex, remainingAttempts);
+                    this.options.eventHandlers.onConnectionError(error, remainingAttempts);
                 }
                 return this._apiRequest(requestOptions, remainingAttempts);
-            } else if (ex.response && ex.response.status === 401 && remainingAttempts) {
+            } else if (error.response && error.response.status === 401 && remainingAttempts) {
                 // force refresh due to url related issue
                 await this.auth.getAccessToken(true);
                 //only retry once on refresh since there should be no reason for this token to be invalid
                 return this._apiRequest(requestOptions, 1);
             } else {
-                throw new RestError(ex);
+                throw new RestError(error);
             }
         }
     }