mcdev 7.0.1 → 7.0.3

package/eslint.config.js

@@ -0,0 +1,143 @@
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import eslintPluginUnicorn from 'eslint-plugin-unicorn';
+import globals from 'globals';
+import mochaPlugin from 'eslint-plugin-mocha';
+import jsdoc from 'eslint-plugin-jsdoc';
+import js from '@eslint/js';
+
+export default [
+    {
+        ignores: ['docs/**/*', 'node_modules/**/*', 'retrieve/**/*'],
+    },
+    js.configs.recommended,
+    eslintPluginPrettierRecommended,
+    mochaPlugin.configs.flat.recommended,
+    jsdoc.configs['flat/recommended'],
+    eslintPluginUnicorn.configs['flat/recommended'],
+    {
+        languageOptions: {
+            globals: {
+                ...globals.nodeBuiltin,
+                Atomics: 'readonly',
+                SharedArrayBuffer: 'readonly',
+            },
+
+            ecmaVersion: 2022,
+            sourceType: 'module',
+        },
+
+        settings: {
+            jsdoc: {
+                mode: 'typescript',
+
+                preferredTypes: {
+                    array: 'Array',
+                    'array.<>': '[]',
+                    'Array.<>': '[]',
+                    'array<>': '[]',
+                    'Array<>': '[]',
+                    Object: 'object',
+                    'object.<>': 'Object.<>',
+                    'object<>': 'Object.<>',
+                    'Object<>': 'Object.<>',
+                    set: 'Set',
+                    'set.<>': 'Set.<>',
+                    'set<>': 'Set.<>',
+                    'Set<>': 'Set.<>',
+                    promise: 'Promise',
+                    'promise.<>': 'Promise.<>',
+                    'promise<>': 'Promise.<>',
+                    'Promise<>': 'Promise.<>',
+                },
+            },
+        },
+
+        rules: {
+            'logical-assignment-operators': ['error', 'always'],
+            'unicorn/better-regex': 'off',
+
+            'unicorn/catch-error-name': [
+                'error',
+                {
+                    name: 'ex',
+                },
+            ],
+
+            'unicorn/explicit-length-check': 'off',
+            'unicorn/no-null': 'off',
+            'unicorn/prefer-module': 'off',
+            'unicorn/prevent-abbreviations': 'off',
+            'unicorn/filename-case': 'off',
+            'unicorn/no-array-callback-reference': 'off',
+            'unicorn/no-array-reduce': 'off',
+            'unicorn/no-await-expression-member': 'off',
+            'unicorn/no-hex-escape': 'off',
+            'unicorn/no-nested-ternary': 'off',
+            'unicorn/no-static-only-class': 'off',
+            'unicorn/no-unused-properties': 'warn',
+            'unicorn/numeric-separators-style': 'off',
+            'unicorn/prefer-array-some': 'off',
+            'unicorn/prefer-set-has': 'off',
+            'unicorn/prefer-spread': 'off',
+            'unicorn/prefer-string-replace-all': 'error',
+            'arrow-body-style': ['error', 'as-needed'],
+            curly: 'error',
+            'no-console': 'error',
+            'jsdoc/check-line-alignment': 2,
+
+            'jsdoc/require-jsdoc': [
+                'warn',
+                {
+                    require: {
+                        FunctionDeclaration: true,
+                        MethodDefinition: true,
+                        ClassDeclaration: true,
+                        ArrowFunctionExpression: false,
+                        FunctionExpression: true,
+                    },
+                },
+            ],
+
+            'jsdoc/require-param-type': 'error',
+
+            'jsdoc/tag-lines': [
+                'warn',
+                'any',
+                {
+                    startLines: 1,
+                },
+            ],
+
+            'jsdoc/no-undefined-types': 'error',
+            'valid-jsdoc': 'off',
+
+            'spaced-comment': [
+                'warn',
+                'always',
+                {
+                    block: {
+                        exceptions: ['*'],
+                        balanced: true,
+                    },
+                },
+            ],
+        },
+    },
+    {
+        files: ['**/*.js'],
+
+        rules: {
+            'no-var': 'error',
+            'prefer-const': 'error',
+            'prettier/prettier': 'warn',
+            'prefer-arrow-callback': 'warn',
+        },
+    },
+    {
+        files: ['test/*.js'],
+        rules: {
+            'mocha/no-mocha-arrows': 'off',
+            'mocha/no-pending-tests': 'off',
+        },
+    },
+];

package/lib/index.js

@@ -399,7 +399,10 @@ class Mcdev {
                         // Clear output folder structure for selected type
                         retrieveTypesArr.push(type);
                     }
-                    if (!keys) {
+                    const areKeySet = Array.isArray(selectedTypesArr)
+                        ? keys
+                        : Object.values(selectedTypesArr).filter(Boolean).length;
+                    if (!areKeySet) {
                         // dont delete directories if we are just re-retrieving a single file
                         await File.remove(File.normalizePath(removePathArr));
                         // clean up old folders after types were renamed
@@ -420,7 +423,7 @@ class Mcdev {
             if (!retrieveTypesArr.length) {
                 // assume no type was given and config settings are used instead:
                 // Clear output folder structure
-                File.removeSync(File.normalizePath([properties.directories.retrieve, cred, bu]));
+                await File.remove(File.normalizePath([properties.directories.retrieve, cred, bu]));
                 // removes subtypes and removes duplicates
                 retrieveTypesArr.push(
                     ...new Set(properties.metaDataTypes.retrieve.map((type) => type.split('-')[0]))

package/lib/metadataTypes/Asset.js

@@ -117,10 +117,11 @@ class Asset extends MetadataType {
      *
      * @param {void | string[]} [_] parameter not used
      * @param {string[]} [subTypeArr] optionally limit to a single subtype
+     * @param {void | string} [__] parameter not used
      * @param {boolean} [loadShared] optionally retrieve assets from other BUs that were shared with the current
      * @returns {Promise.<{metadata: AssetMap, type: string}>} Promise
      */
-    static retrieveForCache(_, subTypeArr, loadShared = false) {
+    static retrieveForCache(_, subTypeArr, __, loadShared = false) {
         return this.retrieve(null, null, subTypeArr, undefined, loadShared);
     }
 
@@ -1010,6 +1011,11 @@ class Asset extends MetadataType {
      * @param {MetadataTypeItem} metadata a single item
      */
     static setFolderId(metadata) {
+        if (!metadata.r__folder_Path) {
+            throw new Error(
+                `Dependent folder could not be found because r__folder_Path is not set`
+            );
+        }
         metadata.category = {
             id: cache.searchForField('folder', metadata.r__folder_Path, 'Path', 'ID'),
         };
@@ -1158,7 +1164,7 @@ class Asset extends MetadataType {
                 readDirArr = [deployDir, ...subDirArr, templateFileName];
                 const fileName = 'content' + subtypeExtension;
 
-                const fileExtArr = ['html']; // eslint-disable-line no-case-declarations
+                const fileExtArr = ['html'];
                 for (const ext of fileExtArr) {
                     if (
                         await File.pathExists(
@@ -1327,7 +1333,7 @@ class Asset extends MetadataType {
                 // metadata.content
                 subDirArr = [this.definition.type, subType];
                 readDirArr = [deployDir, ...subDirArr];
-                const fileExtArr = ['html', 'ssjs', 'amp']; // eslint-disable-line no-case-declarations
+                const fileExtArr = ['html', 'ssjs', 'amp'];
                 for (const ext of fileExtArr) {
                     if (
                         await File.pathExists(
@@ -1510,7 +1516,7 @@ class Asset extends MetadataType {
             case 'template': {
                 // template-template
                 // metadata.content
-                const fileExt = 'html'; // eslint-disable-line no-case-declarations
+                const fileExt = 'html';
                 if (metadata?.content?.length) {
                     codeArr.push({
                         subFolder: null,
@@ -2116,7 +2122,7 @@ class Asset extends MetadataType {
      * @param {string} subType asset subtype
      * @param {object} item api response for metadata
      * @param {string} buName owner business unit name
-     * @returns {string} path to the asset's code
+     * @returns {Promise.<string>} path to the asset's code
      */
     static async #getPath(subType, item, buName) {
         const pathBase1 = `./retrieve/${this.buObject.credential}/${buName}/${this.definition.type}/${subType}/${item[this.definition.keyField]}.${this.definition.type}-${subType}-meta.`;

package/lib/metadataTypes/Automation.js

@@ -506,6 +506,8 @@ class Automation extends MetadataType {
                             );
                         }
                     }
+                    // In some cases the displayOrder and array order are not equal which leads to a different order every time we retrieve & deployed the automation. To prevent that, we sort the activities by displayOrder on retrieve
+                    step.activities.sort((a, b) => a.displayOrder - b.displayOrder);
                 }
             }
             return structuredClone(metadata);
@@ -846,25 +848,25 @@ class Automation extends MetadataType {
                     for (const activity of step.activities) {
                         activity.displayOrder = ++displayOrder;
                         if (
-                            activity.name &&
+                            activity.r__key &&
                             this.definition.dependencies.includes(activity.r__type)
                         ) {
                             if (
                                 activity.r__type === 'verification' &&
-                                this.createdKeyMap?.[buName]?.verification?.[activity.name]
+                                this.createdKeyMap?.[buName]?.verification?.[activity.r__key]
                             ) {
-                                Util.logger.info(
+                                Util.logger.debug(
                                     Util.getGrayMsg(
                                         ` - updated verification activity name from ${
-                                            activity.name
+                                            activity.r__key
                                         } to ${
-                                            this.createdKeyMap[buName].verification[activity.name]
+                                            this.createdKeyMap[buName].verification[activity.r__key]
                                         }`
                                     )
                                 );
                                 // map structure: cred/bu --> type --> old key --> new key
-                                activity.name =
-                                    this.createdKeyMap[buName].verification[activity.name];
+                                activity.r__key =
+                                    this.createdKeyMap[buName].verification[activity.r__key];
                             }
                             // automations can have empty placeholder for activities with only their type defined
                             activity.activityObjectId = cache.searchForField(
@@ -873,9 +875,16 @@ class Automation extends MetadataType {
                                 Definitions[activity.r__type].keyField,
                                 Definitions[activity.r__type].idField
                             );
+                            activity.name = cache.searchForField(
+                                activity.r__type,
+                                activity.r__key,
+                                Definitions[activity.r__type].keyField,
+                                Definitions[activity.r__type].nameField
+                            );
                         }
                         activity.objectTypeId =
                             this.definition.activityTypeMapping[activity.r__type];
+                        delete activity.r__key;
                         delete activity.r__type;
                     }
                     step.annotation = step.name;
@@ -911,13 +920,13 @@ class Automation extends MetadataType {
                     // check if manual deploy required. if so then log warning
                     if (this.definition.manualDeployTypes.includes(activity.r__type)) {
                         Util.logger.warn(
-                            `- ${this.definition.type} '${metadata.name}' requires additional manual configuration: '${activity.name}' in step ${stepNumber}.${displayOrder}`
+                            `- ${this.definition.type} '${metadata.name}' requires additional manual configuration: '${activity.r__key || activity.name}' in step ${stepNumber}.${displayOrder}`
                         );
                     }
                     // cannot deploy because it is not supported
                     else if (!this.definition.dependencies.includes(activity.r__type)) {
                         errors.push(
-                            `   • not supported ${activity.r__type} activity '${activity.name}' in step ${stepNumber}.${displayOrder}`
+                            `   • not supported ${activity.r__type} activity '${activity.r__key || activity.name}' in step ${stepNumber}.${displayOrder}`
                         );
                         deployable = false;
                     }
@@ -1169,36 +1178,6 @@ class Automation extends MetadataType {
         }
     }
 
-    /**
-     * automation-specific script that retrieves the folder ID from cache and updates the given metadata with it before deploy
-     *
-     * @param {MetadataTypeItem} metadata a single item
-     */
-    static setFolderId(metadata) {
-        try {
-            metadata.categoryId = cache.searchForField(
-                'folder',
-                metadata.r__folder_Path,
-                'Path',
-                'ID'
-            );
-            if (metadata.r__folder_Path !== 'my automations') {
-                Util.logger.warn(
-                    ` - Automation '${
-                        metadata[this.definition.nameField]
-                    }' is located in subfolder ${
-                        metadata.r__folder_Path
-                    }. Please note that creating automation folders is not supported via API and hence you will have to create it manually in the GUI if you choose to deploy this automation.`
-                );
-            }
-            delete metadata.r__folder_Path;
-        } catch {
-            throw new Error(
-                `Folder '${metadata.r__folder_Path}' was not found on the server. Please create this manually in the GUI. Automation-folders cannot be deployed automatically.`
-            );
-        }
-    }
-
     /**
      * Builds a schedule object to be used for scheduling an automation
      * based on combination of ical string and start/end dates.
@@ -1543,13 +1522,15 @@ class Automation extends MetadataType {
     static async document(metadata) {
         if (['md', 'both'].includes(this.properties.options.documentType)) {
             if (!metadata) {
-                metadata = await this.readBUMetadataForType(
-                    File.normalizePath([
-                        this.properties.directories.retrieve,
-                        this.buObject.credential,
-                        this.buObject.businessUnit,
-                    ]),
-                    true
+                metadata = (
+                    await this.readBUMetadataForType(
+                        File.normalizePath([
+                            this.properties.directories.retrieve,
+                            this.buObject.credential,
+                            this.buObject.businessUnit,
+                        ]),
+                        true
+                    )
                 ).automation;
             }
             const docPath = File.normalizePath([

package/lib/metadataTypes/DataExtension.js

@@ -1353,13 +1353,15 @@ class DataExtension extends MetadataType {
     static async document(metadataMap) {
         try {
             if (!metadataMap) {
-                metadataMap = await this.readBUMetadataForType(
-                    File.normalizePath([
-                        this.properties.directories.retrieve,
-                        this.buObject.credential,
-                        this.buObject.businessUnit,
-                    ]),
-                    true
+                metadataMap = (
+                    await this.readBUMetadataForType(
+                        File.normalizePath([
+                            this.properties.directories.retrieve,
+                            this.buObject.credential,
+                            this.buObject.businessUnit,
+                        ]),
+                        true
+                    )
                 ).dataExtension;
             }
         } catch (ex) {

package/lib/metadataTypes/Folder.js

@@ -351,29 +351,42 @@ class Folder extends MetadataType {
         }
         const path = metadataEntry.Path;
         try {
-            // * We tried using the SOAP endpoint for creating folders but that did not support folders for automations nor journeys. This rest endpoint seems to cover everything though
-            const restPayload = {
-                parentCatId: metadataEntry.ParentFolder.ID,
-                name: metadataEntry.Name,
-                catType: metadataEntry.ContentType,
-            };
-            const response = await super.createREST(restPayload, '/email/v1/category', true);
-            if (response?.objectId) {
-                // convert the response to the same format as the SOAP response
-                metadataEntry.ID = response.objectId;
-                // the following is a bit of a hack to make the response look like the SOAP response; not sure if we actually need that anywhere like this --> future developers feel free to double check
-                const returnObject = {
-                    Results: [
-                        {
-                            Object: metadataEntry,
-                        },
-                    ],
+            if (this.definition.deployFolderTypesRest.includes(metadataEntry.ContentType)) {
+                // * The SOAP endpoint for creating folders does not support folders for automations nor journeys. The Rest endpoint on the other hand errors out on certain characters in the folder names that are actually valid. We therefore only use Rest for the folder types that are not supported by SOAP.
+                const restPayload = {
+                    parentCatId: metadataEntry.ParentFolder.ID,
+                    name: metadataEntry.Name,
+                    catType: metadataEntry.ContentType,
                 };
+                const response = await super.createREST(restPayload, '/email/v1/category', true);
+                if (response?.objectId) {
+                    // convert the response to the same format as the SOAP response
+                    metadataEntry.ID = response.objectId;
+                    // the following is a bit of a hack to make the response look like the SOAP response; not sure if we actually need that anywhere like this --> future developers feel free to double check
+                    const returnObject = {
+                        Results: [
+                            {
+                                Object: metadataEntry,
+                            },
+                        ],
+                    };
 
-                Util.logger.info(` - created folder: ${path}`);
-                return returnObject;
+                    Util.logger.info(` - created folder: ${path}`);
+                    return returnObject;
+                } else {
+                    throw new Error(response);
+                }
             } else {
-                throw new Error(response);
+                const response = await super.createSOAP(metadataEntry, true);
+                if (response) {
+                    response.Results[0].Object = metadataEntry;
+                    response.Results[0].Object.ID = response.Results[0].NewID;
+                    response.Results[0].Object.CustomerKey = metadataEntry.CustomerKey;
+                    delete response.Results[0].Object.$;
+
+                    Util.logger.info(` - created folder: ${path}`);
+                    return response;
+                }
             }
         } catch (ex) {
             if (ex?.results) {

package/lib/metadataTypes/Journey.js

@@ -49,8 +49,6 @@ class Journey extends MetadataType {
         let singleKey = '';
         let mode = 'key';
         if (key) {
-            /* eslint-disable unicorn/prefer-ternary */
-
             if (key.startsWith('id:') || key.startsWith('%23')) {
                 // ! allow selecting journeys by ID because that's what users see in the URL
                 // if the key started with %23 assume an ID was copied from the URL but the user forgot to prefix it with id:
@@ -71,7 +69,6 @@ class Journey extends MetadataType {
                 // assume actual key was provided
                 singleKey = 'key:' + encodeURIComponent(key);
             }
-            /* eslint-enable unicorn/prefer-ternary */
         }
 
         try {
@@ -176,7 +173,7 @@ class Journey extends MetadataType {
     static async deleteByKey(key) {
         let version;
         let singleKey = '';
-        /* eslint-disable unicorn/prefer-ternary */
+
         if (key.startsWith('id:') || key.startsWith('%23')) {
             // ! allow selecting journeys by ID because that's what users see in the URL
             // if the key started with %23 assume an ID was copied from the URL but the user forgot to prefix it with id:
@@ -223,7 +220,7 @@ class Journey extends MetadataType {
         Util.logger.warn(
             `Deleting Journeys via this command breaks following retrieve-by-key/id requests until you've deployed/created a new draft version! You can get still get the latest available version of your journey by retrieving all interactions on this BU.`
         );
-        /* eslint-enable unicorn/prefer-ternary */
+
         return super.deleteByKeyREST(
             '/interaction/v1/interactions/' + singleKey + `?versionNumber=${version}`,
             key,

package/lib/metadataTypes/MetadataType.js

@@ -245,6 +245,11 @@ class MetadataType {
         if (!this.definition.folderIdField) {
             return;
         }
+        if (!metadata.r__folder_Path) {
+            throw new Error(
+                `Dependent folder could not be found because r__folder_Path is not set`
+            );
+        }
         metadata[this.definition.folderIdField] = cache.searchForField(
             'folder',
             metadata.r__folder_Path,
@@ -1831,7 +1836,7 @@ class MetadataType {
      * @param {string[]} baseDir [retrieveDir, ...overrideType.split('-')]
      * @param {string} [subtypeExtension] e.g. ".asset-meta" or ".query-meta"
      * @param {TemplateMap} [templateVariables] variables to be replaced in the metadata
-     * @returns {MetadataTypeItem} saved metadata
+     * @returns {Promise.<MetadataTypeItem>} saved metadata
      */
     static async saveToDisk(results, originalKey, baseDir, subtypeExtension, templateVariables) {
         subtypeExtension ||= '.' + this.definition.type + '-meta';

package/lib/metadataTypes/definitions/Automation.definition.js

@@ -528,6 +528,7 @@ export default {
             template: false,
         },
         'steps[].activities[].displayOrder': {
+            // we remove it during post-processing but need to ensure the array order equals the displayOrder
             isCreateable: true,
             isUpdateable: true,
             retrieving: false,

package/lib/metadataTypes/definitions/Folder.definition.js

@@ -4,6 +4,7 @@ export default {
     subTypes: [
         'asset-shared',
         'asset',
+        'automations',
         'contextual_suppression_list',
         'dataextension',
         'filteractivity',
@@ -52,6 +53,7 @@ export default {
         'triggered_send_journeybuilder',
         'triggered_send',
     ],
+    deployFolderTypesRest: ['automations', 'journey', 'triggered_send_journeybuilder'],
     deployFolderBlacklist: [
         // lower-case values!
         'shared data extensions',