mcdev 4.1.12 → 4.2.0

package/lib/metadataTypes/Folder.js

@@ -21,16 +21,19 @@ class Folder extends MetadataType {
      * @param {TYPE.BuObject} buObject properties for auth
      * @param {void} [___] unused parameter
      * @param {string} [key] customer key of single item to retrieve
+     * @param {string[]} [contentTypeList] content type of folder
      * @returns {Promise} Promise
      */
-    static async retrieve(retrieveDir, additionalFields, buObject, ___, key) {
+    static async retrieve(retrieveDir, additionalFields, buObject, ___, key, contentTypeList) {
         if (key) {
             Util.logger.error(`Folder.retrieve() does not support key parameter`);
         }
-        const queryAllFolders = await this.retrieveHelper(additionalFields, true);
+        const queryAllFolders = await this.retrieveHelper(additionalFields, true, contentTypeList);
 
         if (buObject.eid !== buObject.mid) {
-            queryAllFolders.push(...(await this.retrieveHelper(additionalFields, false)));
+            queryAllFolders.push(
+                ...(await this.retrieveHelper(additionalFields, false, contentTypeList))
+            );
         }
         const sortPairs = toposort(queryAllFolders.map((a) => [a.ParentFolder.ID, a.ID]));
         const idMap = {};
@@ -150,10 +153,11 @@ class Folder extends MetadataType {
      * Retrieves folder metadata for caching
      *
      * @param {TYPE.BuObject} buObject properties for auth
+     * @param {string[]} [contentTypeList] content type of folder
      * @returns {Promise} Promise
      */
-    static retrieveForCache(buObject) {
-        return this.retrieve(null, null, buObject);
+    static retrieveForCache(buObject, contentTypeList) {
+        return this.retrieve(null, null, buObject, null, null, contentTypeList);
     }
 
     /**
@@ -515,10 +519,30 @@ class Folder extends MetadataType {
      *
      * @param {string[]} [additionalFields] Returns specified fields even if their retrieve definition is not set to true
      * @param {boolean} [queryAllAccounts] which queryAllAccounts setting to use
+     * @param {string[]} [contentTypeList] content type of folder
      * @returns {Promise.<object>} soap object
      */
-    static async retrieveHelper(additionalFields, queryAllAccounts) {
+    static async retrieveHelper(additionalFields, queryAllAccounts, contentTypeList) {
         const options = { QueryAllAccounts: !!queryAllAccounts };
+        if (contentTypeList) {
+            for (const contentType of contentTypeList) {
+                options.filter = options.filter
+                    ? {
+                          leftOperand: {
+                              leftOperand: 'ContentType',
+                              operator: 'equals',
+                              rightOperand: contentType,
+                          },
+                          operator: 'OR',
+                          rightOperand: options.filter,
+                      }
+                    : {
+                          leftOperand: 'ContentType',
+                          operator: 'equals',
+                          rightOperand: contentType,
+                      };
+            }
+        }
         const response = await this.client.soap.retrieveBulk(
             'DataFolder',
             this.getFieldNamesToRetrieve(additionalFields).filter(

package/lib/metadataTypes/List.js

@@ -2,8 +2,10 @@
 
 const TYPE = require('../../types/mcdev.d');
 const MetadataType = require('./MetadataType');
+const Folder = require('./Folder');
 const Util = require('../util/util');
 const cache = require('../util/cache');
+const auth = require('../util/auth');
 
 /**
  * List MetadataType
@@ -16,12 +18,12 @@ class List extends MetadataType {
      *
      * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
      * @param {void} [_] unused parameter
-     * @param {void} [__] unused parameter
+     * @param {TYPE.BuObject} buObject properties for auth
      * @param {void} [___] unused parameter
      * @param {string} [key] customer key of single item to retrieve
      * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise
      */
-    static retrieve(retrieveDir, _, __, ___, key) {
+    static async retrieve(retrieveDir, _, buObject, ___, key) {
         /** @type {TYPE.SoapRequestParams} */
         let requestParams = null;
         if (key) {
@@ -42,21 +44,112 @@ class List extends MetadataType {
                 },
             };
         }
-        return super.retrieveSOAP(retrieveDir, null, requestParams);
+        const results = await super.retrieveSOAP(retrieveDir, null, requestParams);
+        return await this._retrieveParentAllSubs(buObject, results);
     }
     /**
      * Gets metadata cache with limited fields and does not store value to disk
      *
+     * @param {TYPE.BuObject} buObject properties for auth
      * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise of metadata
      */
-    static async retrieveForCache() {
-        const results = await this.retrieve(null);
+    static async retrieveForCache(buObject) {
+        const results = await this.retrieve(null, null, buObject);
+        if (!cache.getCache()?.folder) {
+            Util.logger.debug('folders not cached but required for list');
+            Util.logger.info(' - Caching dependent Metadata: folder');
+            Folder.client = this.client;
+            Folder.properties = this.properties;
+            const result = await Folder.retrieveForCache(buObject, [
+                'list',
+                'mysubs',
+                'suppression_list',
+                'publication',
+                'contextual_suppression_list',
+            ]);
+            cache.setMetadata('folder', result.metadata);
+        }
         for (const metadataEntry in results.metadata) {
             this.parseMetadata(results.metadata[metadataEntry], true);
         }
         return results;
     }
 
+    /**
+     * helper for @link retrieveForCache and @link retrieve
+     *
+     * @param {TYPE.BuObject} buObject properties for auth
+     * @param {TYPE.MetadataTypeMapObj} results metadata from retrieve for current BU
+     * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise
+     */
+    static async _retrieveParentAllSubs(buObject, results) {
+        if (buObject.eid !== buObject.mid) {
+            // for caching, we want to get the All Subscriber List from the Parent Account
+            Util.logger.debug(' - Checking MasterUnsubscribeBehavior for current BU');
+            /** @type {TYPE.BuObject} */
+            const buObjectParentBu = {
+                eid: this.properties.credentials[buObject.credential].eid,
+                mid: this.properties.credentials[buObject.credential].eid,
+                businessUnit: Util.parentBuName,
+                credential: buObject.credential,
+            };
+            try {
+                this.client = auth.getSDK(buObjectParentBu);
+            } catch (ex) {
+                Util.logger.error(ex.message);
+                return;
+            }
+            const buResult = await this.client.soap.retrieve(
+                'BusinessUnit',
+                ['MasterUnsubscribeBehavior'],
+                {
+                    QueryAllAccounts: true,
+                    filter: {
+                        leftOperand: 'ID',
+                        operator: 'equals',
+                        rightOperand: this.properties.credentials[buObject.credential].eid,
+                    },
+                }
+            );
+            const masterUnsubscribeBehavior = buResult.Results[0]?.MasterUnsubscribeBehavior;
+            if (masterUnsubscribeBehavior === 'ENTIRE_ENTERPRISE') {
+                Util.logger.debug(` - BU uses ParentBU's All Subscriber List`);
+                Util.logger.info(
+                    ' - Caching dependent Metadata: All Subscriber list (on _ParentBU_)'
+                );
+                const metadataParentBu = await this.retrieve(
+                    null,
+                    null,
+                    buObjectParentBu,
+                    null,
+                    'All Subscribers'
+                );
+                // manually set folder path of parent's All Subscriber List to avoid retrieving folders
+                for (const key of Object.keys(metadataParentBu.metadata)) {
+                    metadataParentBu.metadata[key].r__folder_Path = 'my subscribers';
+                }
+                // find & delete local All Subscriber list to avoid referencing the wrong one
+                for (const key of Object.keys(results.metadata)) {
+                    if (results.metadata[key].ListName === 'All Subscribers') {
+                        delete results.metadata[key];
+                        break;
+                    }
+                }
+
+                // make sure to overwrite parent bu DEs with local ones
+                return {
+                    metadata: { ...metadataParentBu.metadata, ...results.metadata },
+                    type: results.type,
+                };
+            } else if (masterUnsubscribeBehavior === 'BUSINESS_UNIT_ONLY') {
+                Util.logger.debug(' - BU uses own All Subscriber List');
+            }
+            // revert client to current default
+            this.client = auth.getSDK(this.buObject);
+        }
+        return results;
+    }
+
     /**
      * Delete a metadata item from the specified business unit
      *
@@ -85,20 +178,25 @@ class List extends MetadataType {
      * @returns {TYPE.MetadataTypeItem} Array with one metadata object and one sql string
      */
     static parseMetadata(metadata, parseForCache) {
-        try {
-            metadata.r__folder_Path = cache.searchForField(
-                'folder',
-                metadata.Category,
-                'ID',
-                'Path'
-            );
-            if (!parseForCache) {
-                delete metadata.Category;
+        if (!metadata.r__folder_Path) {
+            // if we cached all subs from parent bu, we don't need to parse the folder path again here
+            try {
+                metadata.r__folder_Path = cache.searchForField(
+                    'folder',
+                    metadata.Category,
+                    'ID',
+                    'Path'
+                );
+                if (!parseForCache) {
+                    delete metadata.Category;
+                }
+            } catch (ex) {
+                Util.logger.warn(
+                    ` - List ${metadata.ID}: '${metadata.CustomerKey}': ${ex.message}`
+                );
             }
-            return metadata;
-        } catch (ex) {
-            Util.logger.warn(` - List ${metadata.ID}: '${metadata.CustomerKey}': ${ex.message}`);
         }
+        return metadata;
     }
 }
 // Assign definition to static attributes

package/lib/metadataTypes/MetadataType.js

@@ -532,8 +532,8 @@ class MetadataType {
                 (filteredByPreDeploy > 0 ? ` / ${filteredByPreDeploy} filtered` : '')
         );
 
-        // if Results then parse as SOAP
         if (this.definition.bodyIteratorField === 'Results') {
+            // if Results then parse as SOAP
             // put in Retrieve Format for parsing
             // todo add handling when response does not contain items.
             // @ts-ignore
@@ -545,11 +545,12 @@ class MetadataType {
                 .map((r) => r.Object);
             return this.parseResponseBody({ Results: metadataResults });
         } else {
+            // likely comming from one of the many REST APIs
             // put in Retrieve Format for parsing
             // todo add handling when response does not contain items.
             // @ts-ignore
             const metadataResults = createResults.concat(updateResults).filter(Boolean);
-            return this.parseResponseBody({ items: metadataResults });
+            return this.parseResponseBody(metadataResults);
         }
     }
 
@@ -613,20 +614,7 @@ class MetadataType {
             }
             return response;
         } catch (ex) {
-            if (!handleOutside) {
-                const errorMsg =
-                    ex.results && ex.results.length
-                        ? `${ex.results[0].StatusMessage} (Code ${ex.results[0].ErrorCode})`
-                        : ex.message;
-                Util.logger.error(
-                    ` ☇ error creating ${this.definition.type} '${
-                        metadataEntry[this.definition.keyField]
-                    }': ${errorMsg}`
-                );
-            } else {
-                throw ex;
-            }
-
+            this._handleSOAPErrors(ex, 'creating', metadataEntry, handleOutside);
             return {};
         }
     }
@@ -692,22 +680,28 @@ class MetadataType {
             }
             return response;
         } catch (ex) {
-            if (!handleOutside) {
-                const errorMsg = ex?.json?.Results.length
-                    ? `${ex.json.Results[0].StatusMessage} (Code ${ex.json.Results[0].ErrorCode})`
-                    : ex.message;
-                Util.logger.error(
-                    ` ☇ error updating ${this.definition.type} '${
-                        metadataEntry[this.definition.keyField]
-                    }': ${errorMsg}`
-                );
-            } else {
-                throw ex;
-            }
-
+            this._handleSOAPErrors(ex, 'updating', metadataEntry, handleOutside);
             return {};
         }
     }
+    /**
+     *
+     * @param {Error} ex error that occured
+     * @param {'creating'|'updating'} msg what to print in the log
+     * @param {TYPE.MetadataTypeItem} [metadataEntry] single metadata entry
+     * @param {boolean} [handleOutside] if the API reponse is irregular this allows you to handle it outside of this generic method
+     */
+    static _handleSOAPErrors(ex, msg, metadataEntry, handleOutside) {
+        if (handleOutside) {
+            throw ex;
+        } else {
+            const errorMsg = ex?.json?.Results?.length
+                ? `${ex.json.Results[0].StatusMessage} (Code ${ex.json.Results[0].ErrorCode})`
+                : ex.message;
+            const name = metadataEntry ? ` '${metadataEntry[this.definition.keyField]}'` : '';
+            Util.logger.error(` ☇ error ${msg} ${this.definition.type}${name}: ${errorMsg}`);
+        }
+    }
     /**
      * Retrieves SOAP via generic fuel-soap wrapper based metadata of metadata type into local filesystem. executes callback with retrieved metadata
      *
@@ -720,11 +714,17 @@ class MetadataType {
     static async retrieveSOAP(retrieveDir, buObject, requestParams, additionalFields) {
         requestParams = requestParams || {};
         const fields = this.getFieldNamesToRetrieve(additionalFields);
-        const response = await this.client.soap.retrieveBulk(
-            this.definition.type,
-            fields,
-            requestParams
-        );
+        let response;
+        try {
+            response = await this.client.soap.retrieveBulk(
+                this.definition.type,
+                fields,
+                requestParams
+            );
+        } catch (ex) {
+            this._handleSOAPErrors(ex, 'retrieving');
+            return {};
+        }
         const metadata = this.parseResponseBody(response);
 
         if (retrieveDir) {
@@ -785,9 +785,9 @@ class MetadataType {
                 `Downloaded: ${overrideType || this.definition.type} (${
                     Object.keys(savedMetadata).length
                 })` +
-                    (singleRetrieve !== null
-                        ? ` ${color.dim}(Key: ${singleRetrieve})${color.reset}`
-                        : '')
+                    (singleRetrieve === null
+                        ? ''
+                        : ` ${color.dim}(Key: ${singleRetrieve})${color.reset}`)
             );
         }
 
@@ -1454,7 +1454,7 @@ class MetadataType {
 
         try {
             // write to file
-            const targetDirArr = !Array.isArray(targetDir) ? [targetDir] : targetDir;
+            const targetDirArr = Array.isArray(targetDir) ? targetDir : [targetDir];
 
             for (const targetDir of targetDirArr) {
                 await File.writeJSONToFile(
@@ -1580,15 +1580,48 @@ class MetadataType {
 
             return true;
         } catch (ex) {
-            if (!handleOutside) {
+            if (handleOutside) {
+                throw ex;
+            } else {
                 const errorMsg = ex?.results?.length
                     ? `${ex.results[0].StatusMessage} (Code ${ex.results[0].ErrorCode})`
                     : ex.message;
                 Util.logger.error(
                     `- error deleting ${this.definition.type} '${customerKey}': ${errorMsg}`
                 );
-            } else {
+            }
+
+            return false;
+        }
+    }
+    /**
+     * Delete a data extension from the specified business unit
+     *
+     * @param {TYPE.BuObject} buObject references credentials
+     * @param {string} url endpoint
+     * @param {string} key Identifier of metadata
+     * @param {boolean} [handleOutside] if the API reponse is irregular this allows you to handle it outside of this generic method
+     * @returns {boolean} deletion success flag
+     */
+    static async deleteByKeyREST(buObject, url, key, handleOutside) {
+        const keyObj = {};
+        keyObj[this.definition.keyField] = key;
+        try {
+            this.client.rest.delete(url);
+            if (!handleOutside) {
+                Util.logger.info(`- deleted ${this.definition.type}: ${key}`);
+            }
+            this.postDeleteTasks(buObject, key);
+
+            return true;
+        } catch (ex) {
+            if (handleOutside) {
                 throw ex;
+            } else {
+                const errorMsg = ex?.results?.length
+                    ? `${ex.results[0].StatusMessage} (Code ${ex.results[0].ErrorCode})`
+                    : ex.message;
+                Util.logger.error(`- error deleting ${this.definition.type} '${key}': ${errorMsg}`);
             }
 
             return false;

package/lib/metadataTypes/Query.js

@@ -120,7 +120,7 @@ class Query extends MetadataType {
     static async preDeployTasks(metadata, deployDir) {
         metadata.queryText = await File.readFilteredFilename(
             deployDir + '/' + this.definition.type,
-            metadata.key + '.' + this.definition.type + '-meta',
+            metadata[this.definition.keyField] + '.' + this.definition.type + '-meta',
             'sql'
         );
         metadata.targetKey = cache.searchForField(
@@ -292,7 +292,7 @@ class Query extends MetadataType {
         const codeArr = [
             {
                 subFolder: null,
-                fileName: metadata.key,
+                fileName: metadata[this.definition.keyField],
                 fileExt: 'sql',
                 content: metadata.queryText,
             },

package/lib/metadataTypes/Script.js

@@ -93,7 +93,7 @@ class Script extends MetadataType {
      * @returns {Promise.<string>} content for metadata.script
      */
     static async _mergeCode(metadata, deployDir, templateName) {
-        templateName = templateName || metadata.key;
+        templateName = templateName || metadata[this.definition.keyField];
         let code;
         const codePath = File.normalizePath([
             deployDir,
@@ -275,7 +275,7 @@ class Script extends MetadataType {
         delete metadata.script;
         codeArr.push({
             subFolder: null,
-            fileName: metadata.key,
+            fileName: metadata[this.definition.keyField],
             fileExt: fileExt,
             content: code,
         });

package/lib/metadataTypes/TransactionalEmail.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const TYPE = require('../../types/mcdev.d');
+const TransactionalMessage = require('./TransactionalMessage');
+const Util = require('../util/util');
+const cache = require('../util/cache');
+
+/**
+ * TransactionalEmail MetadataType
+ *
+ * @augments TransactionalMessage
+ */
+class TransactionalEmail extends TransactionalMessage {
+    static subType = 'email';
+
+    /**
+     * Updates a single item
+     *
+     * @param {TYPE.MetadataTypeItem} metadata how the item shall look after the update
+     * @returns {Promise} Promise
+     */
+    static update(metadata) {
+        if (metadata.options?.createJourney) {
+            // only send this during create or else we might end up with an unexpected outcome
+            Util.logger.warn(
+                ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                    metadata[this.definition.keyField]
+                }): Cannot update journey link during update. If you need to relink this item to a new journey please delete and recreate it.`
+            );
+            delete metadata.options.createJourney;
+        }
+        return super.update(metadata);
+    }
+
+    /**
+     * prepares for deployment
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {TYPE.MetadataTypeItem} Promise
+     */
+    static async preDeployTasks(metadata) {
+        // asset
+        if (metadata.content?.customerKey) {
+            // we merely want to be able to show an error if it does not exist
+            cache.searchForField(
+                'asset',
+                metadata.content.customerKey,
+                'customerKey',
+                'customerKey'
+            );
+        }
+        // subscriptions: dataExtension
+        if (metadata.subscriptions?.dataExtension) {
+            // we merely want to be able to show an error if it does not exist
+            cache.searchForField(
+                'dataExtension',
+                metadata.subscriptions.dataExtension,
+                'CustomerKey',
+                'CustomerKey'
+            );
+        }
+        // subscriptions: list
+        if (metadata.subscriptions?.r__list_PathName) {
+            metadata.subscriptions.list = cache.getListObjectId(
+                metadata.subscriptions.r__list_PathName,
+                'CustomerKey'
+            );
+            delete metadata.subscriptions.r__list_PathName;
+        }
+
+        // journey
+        if (metadata.journey?.interactionKey) {
+            // ! update & create enpoints dont accept journey.interactionKey. They only allow to create a new journey
+            // cache.searchForField('interaction', metadata.journey.interactionKey, 'key', 'key');
+            metadata.options = metadata.options || {};
+            metadata.options.createJourney = true; // only send this during create or else we might end up with an unexpected outcome
+            delete metadata.journey.interactionKey;
+        }
+
+        return metadata;
+    }
+    /**
+     * manages post retrieve steps
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {TYPE.MetadataTypeItem} a single item
+     */
+    static postRetrieveTasks(metadata) {
+        // asset
+        if (metadata.content?.customerKey) {
+            try {
+                // we merely want to be able to show an error if it does not exist
+                cache.searchForField(
+                    'asset',
+                    metadata.content.customerKey,
+                    'customerKey',
+                    'customerKey'
+                );
+            } catch (ex) {
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): ${ex.message}.`
+                );
+            }
+        }
+        // subscriptions: dataExtension
+        if (metadata.subscriptions?.dataExtension) {
+            try {
+                // we merely want to be able to show a warning if it does not exist
+                cache.searchForField(
+                    'dataExtension',
+                    metadata.subscriptions.dataExtension,
+                    'CustomerKey',
+                    'CustomerKey'
+                );
+            } catch (ex) {
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): ${ex.message}.`
+                );
+            }
+        }
+        // subscriptions: list
+        if (metadata.subscriptions?.list) {
+            try {
+                // List
+                metadata.subscriptions.r__list_PathName = cache.getListPathName(
+                    metadata.subscriptions.list,
+                    'CustomerKey'
+                );
+                delete metadata.subscriptions.list;
+            } catch (ex) {
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): ${ex.message}.`
+                );
+            }
+        }
+        // journey
+        if (metadata.journey?.interactionKey) {
+            try {
+                // we merely want to be able to show a warning if it does not exist
+                cache.searchForField('interaction', metadata.journey.interactionKey, 'key', 'key');
+            } catch (ex) {
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): ${ex.message}.`
+                );
+            }
+        }
+
+        return metadata;
+    }
+}
+
+// Assign definition to static attributes
+TransactionalEmail.definition = require('../MetadataTypeDefinitions').transactionalEmail;
+
+module.exports = TransactionalEmail;