mcdev 3.1.1 → 4.0.0

package/lib/retrieveChangelog.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 'use strict';
-
+/* eslint-disable unicorn/prefer-top-level-await */
 /**
  * sample file on how to retrieve a simple changelog to use in GUIs or automated processing of any kind
+ *
  * @example
  [{
     name: 'deName',
@@ -45,10 +46,10 @@ const customDefinition = {
     const userList = (await mcdev.retrieve('ACN-Learning/_ParentBU_', 'accountUser', true))
         .accountUser;
     // reduce userList to simple id-name map
-    Object.keys(userList).forEach((key) => {
+    for (const key of Object.keys(userList)) {
         userList[userList[key].ID] = userList[key].Name;
         delete userList[key];
-    });
+    }
 
     // get changed metadata
     const changelogList = await mcdev.retrieve('ACN-Learning/MCDEV_Training_Source', null, true);
@@ -81,13 +82,13 @@ const customDefinition = {
         }
     });
     const finalResult = allMetadata.filter((item) => undefined !== item);
-    console.log('finalResult', finalResult);
+    console.log('finalResult', finalResult); // eslint-disable-line no-console
 })();
 
 /**
  *
- * @param {object<string,string>} userList user-id > user-name map
- * @param {object<string,string>} item single metadata item
+ * @param {Object.<string, string>} userList user-id > user-name map
+ * @param {Object.<string, string>} item single metadata item
  * @param {string} fieldname name of field containing the info
  * @returns {string} username or user id or 'n/a'
  */

package/lib/util/auth.js

@@ -0,0 +1,117 @@
+const TYPE = require('../../types/mcdev.d');
+const Util = require('./util');
+const File = require('./file');
+const SDK = require('sfmc-sdk');
+const Conf = require('conf');
+const credentialStore = new Conf({ configName: 'sessions', clearInvalidConfig: true });
+// const currentMID = null;
+const initializedSDKs = {};
+let authfile;
+
+const Auth = {
+    /**
+     * For each business unit, set up base credentials to be used.
+     *
+     * @param {TYPE.AuthObject} authObject details for
+     * @param {string} credential of the instance
+     * @returns {void}
+     */
+    async saveCredential(authObject, credential) {
+        const sdk = setupSDK(credential, authObject);
+        try {
+            // check credentials to allow clear log output and stop execution
+            const test = await sdk.auth.getAccessToken();
+            if (test.error) {
+                throw new Error(test.error_description);
+            } else if (test.scope) {
+                // find missing rights
+                const missingAccess = sdk.auth
+                    .getSupportedScopes()
+                    .filter((element) => !test.scope.includes(element));
+
+                if (missingAccess.length) {
+                    Util.logger.warn(
+                        'Installed package has insufficient access. You might encounter malfunctions!'
+                    );
+                    Util.logger.warn('Missing scope: ' + missingAccess.join(', '));
+                }
+                const existingAuth = (await File.pathExists(Util.authFileName))
+                    ? await File.readJson(Util.authFileName)
+                    : {};
+                existingAuth[credential] = authObject;
+                await File.writeJSONToFile('./', Util.authFileName.split('.json')[0], existingAuth);
+                authfile = existingAuth;
+            }
+        } catch (ex) {
+            throw new Error(ex.message);
+        }
+    },
+    /**
+     * Returns an SDK instance to be used for API calls
+     *
+     * @param {TYPE.BuObject} buObject information about current context
+     * @returns {SDK} auth object
+     */
+    getSDK(buObject) {
+        const credentialKey = `${buObject.credential}/${buObject.businessUnit}`;
+        if (initializedSDKs[credentialKey]) {
+            // return initialied SDK if available
+            return initializedSDKs[credentialKey];
+        } else {
+            // check existing credentials cached
+            authfile = authfile || File.readJsonSync(Util.authFileName);
+            const newAuthObj = authfile[buObject.credential];
+            // use client_id + MID to ensure a unique combination across instances
+            const sessionKey = newAuthObj.client_id + '|' + buObject.mid;
+            const existingAuthObj = credentialStore.get(sessionKey);
+            if (!existingAuthObj) {
+                newAuthObj.account_id = buObject.mid;
+            }
+            initializedSDKs[credentialKey] = setupSDK(credentialKey, existingAuthObj || newAuthObj);
+            return initializedSDKs[credentialKey];
+        }
+    },
+    /**
+     * helper to clear all auth sessions
+     *
+     * @returns {void}
+     */
+    clearSessions() {
+        credentialStore.clear();
+        Util.logger.info(`Auth sessions cleared`);
+    },
+};
+/**
+ * Returns an SDK instance to be used for API calls
+ *
+ * @param {string} sessionKey key for specific BU
+ * @param {TYPE.AuthObject} authObject credentials for specific BU
+ * @returns {SDK} auth object
+ */
+function setupSDK(sessionKey, authObject) {
+    return new SDK(authObject, {
+        eventHandlers: {
+            onLoop: (type, req) => {
+                Util.logger.info(
+                    `- Requesting next batch (currently ${req.Results.length} records)`
+                );
+            },
+            onRefresh: (authObject) => {
+                authObject.scope = authObject.scope.split(' '); // Scope is usually not an array, but we enforce conversion here for simplicity
+                credentialStore.set(sessionKey, authObject);
+            },
+            onConnectionError: (ex, remainingAttempts) => {
+                Util.logger.warn(
+                    `- Connection problem (Code: ${ex.code}). Retrying ${remainingAttempts} time${
+                        remainingAttempts > 1 ? 's' : ''
+                    }`
+                );
+                Util.logger.errorStack(ex);
+            },
+        },
+        requestAttempts: 4,
+        retryOnConnectionError: true,
+    });
+}
+
+module.exports = Auth;

package/lib/util/businessUnit.js

@@ -1,8 +1,9 @@
 'use strict';
 
+const TYPE = require('../../types/mcdev.d');
 const Util = require('./util');
 const File = require('./file');
-const Retriever = require('../Retriever');
+const auth = require('./auth');
 
 /**
  * Helper that handles retrieval of BU info
@@ -10,57 +11,42 @@ const Retriever = require('../Retriever');
 const BusinessUnit = {
     /**
      * Refreshes BU names and ID's from MC instance
-     * @param {object} properties current properties that have to be refreshed
+     *
+     * @param {TYPE.Mcdevrc} properties current properties that have to be refreshed
      * @param {string} credentialsName identifying name of the installed package / project
-     * @returns {Promise<boolean>} success of refresh
+     * @returns {Promise.<boolean>} success of refresh
      */
     refreshBUProperties: async function (properties, credentialsName) {
         const currentCredentials = properties.credentials[credentialsName];
-        const buObject = {
-            clientId: currentCredentials.clientId,
-            clientSecret: currentCredentials.clientSecret,
-            tenant: currentCredentials.tenant,
-        };
-        let client;
-        Util.logger.info(`Testing credentials`);
-        try {
-            client = await Util.getETClient(buObject);
-        } catch (ex) {
-            Util.logger.error(ex.message);
-            return false;
-        }
-        const retriever = new Retriever(properties, buObject, client);
         Util.logger.info(`Loading BUs`);
-
-        const buResult = await new Promise((resolve) => {
-            retriever.client.SoapClient.retrieve(
+        try {
+            const client = auth.getSDK({
+                mid: currentCredentials.eid,
+                eid: currentCredentials.eid,
+                credential: credentialsName,
+                businessUnit: '_ParentBU_',
+            });
+            const buResult = await client.soap.retrieve(
                 'BusinessUnit',
                 ['Name', 'ID', 'ParentName', 'ParentID', 'IsActive'],
-                { queryAllAccounts: true },
-                (error, response) => {
-                    if (error) {
-                        Util.logger.error(`Credentials failure. ${error}`);
-                        resolve(null);
-                        // throw new Error(error);
-                    } else {
-                        resolve(response.body.Results);
-                    }
-                }
+                { QueryAllAccounts: true }
             );
-        });
-        if (buResult !== null && !buResult.length) {
-            Util.logger.error(`Credentials worked but no BUs found. Check access rights!`);
-        } else if (buResult !== null) {
-            Util.logger.info(`Found ${buResult.length} BUs:`);
-            // create shortcut and reset BU list at the same time. we don't want old entries clutter the new list
-            const myBuList = (currentCredentials.businessUnits = {});
-            // sort array by name for better display (wont affect object in settings)
-            buResult
-                .sort((a, b) => {
-                    if (a.ParentID === '0') {
+            if (buResult !== null && !buResult.Results) {
+                Util.logger.error(`Credentials worked but no BUs found. Check access rights!`);
+            } else if (buResult !== null) {
+                Util.logger.info(`Found ${buResult.Results.length} BUs:`);
+                // create shortcut and reset BU list at the same time. we don't want old entries clutter the new list
+                const myBuList = (currentCredentials.businessUnits = {});
+                // sort array by name for better display (wont affect object in settings)
+                for (const element of buResult.Results.map((element) => {
+                    element.ID = Number.parseInt(element.ID);
+                    element.ParentID = Number.parseInt(element.ParentID);
+                    return element;
+                }).sort((a, b) => {
+                    if (a.ParentID === 0) {
                         return -1;
                     }
-                    if (b.ParentID === '0') {
+                    if (b.ParentID === 0) {
                         return 1;
                     }
                     if (a.Name.toLowerCase() < b.Name.toLowerCase()) {
@@ -70,9 +56,8 @@ const BusinessUnit = {
                         return 1;
                     }
                     return 0;
-                })
-                .forEach((element) => {
-                    if (element.ParentID === '0') {
+                })) {
+                    if (element.ParentID === 0) {
                         myBuList[Util.parentBuName] = element.ID;
                         currentCredentials.eid = element.ID;
                         Util.logger.info(` - ${Util.parentBuName} (${element.Name})`);
@@ -87,29 +72,33 @@ const BusinessUnit = {
                             }`
                         );
                     }
-                });
-            Util.logger.debug(`EID: ${currentCredentials.eid}`);
-            if (currentCredentials.eid === null) {
-                Util.logger.warn(
-                    `It seems your 'installed package' was not created on the Parent BU of your instance.`
-                );
-                Util.logger.warn(
-                    `While basic functionality will work, it is strongly recommended that you create a new 'installed package' there to enable support for shared Data Extensions and automatic retrieval of the BU list.`
-                );
-                Util.logger.warn(
-                    `If you cannot create a package on the Parent BU, please open your ./.mcdevrc.json and update the list of BUs and their MIDs manually.`
+                }
+                Util.logger.debug(`EID: ${currentCredentials.eid}`);
+                if (currentCredentials.eid === null) {
+                    Util.logger.warn(
+                        `It seems your 'installed package' was not created on the Parent BU of your instance.`
+                    );
+                    Util.logger.warn(
+                        `While basic functionality will work, it is strongly recommended that you create a new 'installed package' there to enable support for shared Data Extensions and automatic retrieval of the BU list.`
+                    );
+                    Util.logger.warn(
+                        `If you cannot create a package on the Parent BU, please open your ./.mcdevrc.json and update the list of BUs and their MIDs manually.`
+                    );
+                    // allow user to work by setting this to an obviously false value which nonetheless doesn't block execution
+                    currentCredentials.eid = -1;
+                }
+                // store BU list for repo
+                await File.writeJSONToFile(
+                    properties.directories.businessUnits,
+                    File.filterIllegalFilenames(credentialsName + '.businessUnits'),
+                    buResult.Results
                 );
-                // allow user to work by setting this to an obviously false value which nonetheless doesn't block execution
-                currentCredentials.eid = -1;
+                // update config
+                await File.saveConfigFile(properties);
             }
-            // store BU list for repo
-            await File.writeJSONToFile(
-                properties.directories.businessUnits,
-                File.filterIllegalFilenames(credentialsName + '.businessUnits'),
-                buResult
-            );
-            // update config
-            await File.saveConfigFile(properties);
+        } catch (ex) {
+            Util.logger.error(`Credentials failure. ${ex}`);
+            return null;
         }
         return true;
     },

package/lib/util/cache.js

@@ -0,0 +1,194 @@
+const TYPE = require('../../types/mcdev.d');
+const Util = require('./util');
+
+/** @type {TYPE.Cache} */
+const dataStore = {};
+let currentMID = null;
+
+module.exports = {
+    /**
+     * Method to setup buObject
+     * NOTE: in future this may need to restore, rather than wipe the cache
+     *
+     * @param {TYPE.BuObject} buObject for current Business unit
+     * @returns {void}
+     */
+    initCache: (buObject) => {
+        if (buObject?.mid) {
+            currentMID = buObject.mid;
+            dataStore[currentMID] = {};
+            // If the EID is not setup, also do this for required types (ie. Folders)
+            if (!dataStore[buObject.eid]) {
+                dataStore[buObject.eid] = {};
+            }
+        } else {
+            throw new Error('Business Unit (buObject) used when initialzing cache was missing MID');
+        }
+    },
+    /**
+     * return entire cache for current MID
+     *
+     * @returns {TYPE.MultiMetadataTypeMap} cache for one Business Unit
+     */
+    getCache: () => dataStore[currentMID],
+
+    /* eslint-disable unicorn/no-array-for-each */
+    /**
+     * clean cache for one BU if mid provided, otherwise whole cache
+     *
+     * @param {number} [mid] of business unit
+     * @returns {void}
+     */
+    clearCache: (mid) =>
+        mid
+            ? Object.keys(dataStore[mid]).forEach((key) => delete dataStore[mid][key])
+            : Object.keys(dataStore).forEach((key) => delete dataStore[key]),
+    /* eslint-enable unicorn/no-array-for-each */
+
+    /**
+     * return a specific item from cache
+     *
+     * @param {TYPE.SupportedMetadataTypes} type of Metadata to retrieve from cache
+     * @param {string} key of the specific metadata
+     * @returns {TYPE.MetadataTypeItem} cached metadata item
+     */
+    getByKey: (type, key) => dataStore[currentMID]?.[type]?.[key],
+    /**
+     * override cache for given metadata type with new data
+     *
+     * @param {TYPE.SupportedMetadataTypes} type of Metadata to retrieve from cache
+     * @param {TYPE.MetadataTypeMap} metadataMap map to be set
+     * @returns {void}
+     */
+    setMetadata: (type, metadataMap) => {
+        dataStore[currentMID][type] = metadataMap;
+    },
+    /**
+     * merges entire metadata type with existing cache
+     *
+     * @param {TYPE.SupportedMetadataTypes} type of Metadata to retrieve from cache
+     * @param {TYPE.MetadataTypeMap} metadataMap map to be merged
+     * @param {number} overrideMID which should be used for merging
+     * @returns {void}
+     */
+    mergeMetadata: (type, metadataMap, overrideMID) => {
+        dataStore[overrideMID || currentMID][type] = Object.assign(
+            metadataMap,
+            dataStore[currentMID][type]
+        );
+    },
+    /**
+     * standardized method for getting data from cache.
+     *
+     * @param {TYPE.SupportedMetadataTypes} metadataType metadata type ie. query
+     * @param {string|number|boolean} searchValue unique identifier of metadata being looked for
+     * @param {string} searchField field name (key in object) which contains the unique identifer
+     * @param {string} returnField field which should be returned
+     * @param {number} [overrideMID] ignore currentMID and use alternative (for example parent MID)
+     * @returns {string|number|boolean} value of specified field. Error is thrown if not found
+     */
+    searchForField(metadataType, searchValue, searchField, returnField, overrideMID) {
+        for (const key in dataStore[overrideMID || currentMID]?.[metadataType]) {
+            if (
+                Util.resolveObjPath(
+                    searchField,
+                    dataStore[overrideMID || currentMID][metadataType][key]
+                ) == searchValue
+            ) {
+                try {
+                    if (
+                        Util.resolveObjPath(
+                            returnField,
+                            dataStore[overrideMID || currentMID][metadataType][key]
+                        )
+                    ) {
+                        return Util.resolveObjPath(
+                            returnField,
+                            dataStore[overrideMID || currentMID][metadataType][key]
+                        );
+                    } else {
+                        throw new Error(); // eslint-disable-line unicorn/error-message
+                    }
+                } catch {
+                    throw new Error(
+                        `${metadataType} with ${searchField} '${searchValue}' does not have field '${returnField}'`
+                    );
+                }
+            }
+        }
+        throw new Error(
+            `Dependent ${metadataType} with ${searchField}='${searchValue}' was not found on your BU`
+        );
+    },
+    /**
+     * standardized method for getting data from cache - adapted for special case of lists
+     * ! keeping this in util/cache.js rather than in metadataTypes/List.js to avoid potential circular dependencies
+     *
+     * @param {string} searchValue unique identifier of metadata being looked for
+     * @param {string} searchField ObjectID or ID
+     * @returns {string} unique folderPath/ListName combo of list
+     */
+    getListPathName(searchValue, searchField) {
+        const returnField1 = 'r__folder_Path';
+        const returnField2 = 'ListName';
+        for (const key in dataStore[currentMID]['list']) {
+            if (dataStore[currentMID]['list'][key][searchField] === searchValue) {
+                try {
+                    if (
+                        dataStore[currentMID]['list'][key][returnField1] &&
+                        dataStore[currentMID]['list'][key][returnField2]
+                    ) {
+                        return (
+                            dataStore[currentMID]['list'][key][returnField1] +
+                            '/' +
+                            dataStore[currentMID]['list'][key][returnField2]
+                        );
+                    } else {
+                        throw new Error(); // eslint-disable-line unicorn/error-message
+                    }
+                } catch {
+                    throw new Error(
+                        `${'list'} with ${searchField}='${searchValue}' does not have the fields ${returnField1} and ${returnField2}`
+                    );
+                }
+            }
+        }
+        throw new Error(
+            `Dependent list with ${searchField}='${searchValue}' was not found on your BU`
+        );
+    },
+    /**
+     * standardized method for getting data from cache - adapted for special case of lists
+     * ! keeping this in util/cache.js rather than in metadataTypes/List.js to avoid potential circular dependencies
+     *
+     * @param {string} listPathName folderPath/ListName combo of list
+     * @param {string} returnField ObjectID or ID
+     * @returns {string} unique ObjectId of list
+     */
+    getListObjectId(listPathName, returnField) {
+        let folderPath = listPathName.split('/');
+        const listName = folderPath.pop();
+        folderPath = folderPath.join('/');
+        for (const key in dataStore[currentMID]['list']) {
+            if (
+                dataStore[currentMID]['list'][key].ListName === listName &&
+                dataStore[currentMID]['list'][key].r__folder_Path === folderPath
+            ) {
+                try {
+                    if (dataStore[currentMID]['list'][key][returnField]) {
+                        return dataStore[currentMID]['list'][key][returnField];
+                    } else {
+                        throw new Error(); // eslint-disable-line unicorn/error-message
+                    }
+                } catch {
+                    throw new Error(
+                        `${'list'} with ListName='${listName}' and r__folder_Path='${folderPath}' does not have field '${returnField}'`
+                    );
+                }
+            }
+        }
+        throw new Error(
+            `Dependent list with ListName='${listName}' and r__folder_Path='${folderPath}' was not found on your BU`
+        );
+    },
+};