mcdev 5.2.0 → 6.0.0

package/lib/metadataTypes/MetadataType.js

@@ -7,14 +7,14 @@
  * in the generic version of the method
  */
 
-const TYPE = require('../../types/mcdev.d');
-const Util = require('../util/util');
-const File = require('../util/file');
-const cache = require('../util/cache');
-
-const deepEqual = require('deep-equal');
-const pLimit = require('p-limit');
-const Mustache = require('mustache');
+import TYPE from '../../types/mcdev.d.js';
+
+import { Util } from '../util/util.js';
+import File from '../util/file.js';
+import cache from '../util/cache.js';
+import deepEqual from 'deep-equal';
+import pLimit from 'p-limit';
+import Mustache from 'mustache';
 /**
  * ensure that Mustache does not escape any characters
  *
@@ -139,9 +139,10 @@ class MetadataType {
      *
      * @param {TYPE.MetadataTypeItem} metadataEntry a single metadata Entry
      * @param {object} apiResponse varies depending on the API call
+     * @param {TYPE.MetadataTypeItem} metadataEntryWithAllFields like metadataEntry but before non-creatable fields were stripped
      * @returns {void}
      */
-    static postCreateTasks(metadataEntry, apiResponse) {}
+    static postCreateTasks(metadataEntry, apiResponse, metadataEntryWithAllFields) {}
 
     /**
      * helper for {@link MetadataType.updateREST}
@@ -265,11 +266,10 @@ class MetadataType {
      *
      * @param {string[]} [additionalFields] Returns specified fields even if their retrieve definition is not set to true
      * @param {string[]} [subTypeArr] optionally limit to a single subtype
-     * @param {string} [key] customer key of single item to retrieve
      * @returns {Promise.<TYPE.MetadataTypeMapObj>} metadata
      */
-    static async retrieveForCache(additionalFields, subTypeArr, key) {
-        return this.retrieve(null, additionalFields, subTypeArr, key);
+    static async retrieveForCache(additionalFields, subTypeArr) {
+        return this.retrieve(null, additionalFields, subTypeArr);
     }
     /**
      * Gets metadata cache with limited fields and does not store value to disk
@@ -808,11 +808,12 @@ class MetadataType {
      * @returns {Promise.<object> | null} Promise of API response or null in case of an error
      */
     static async createREST(metadataEntry, uri) {
+        const metadataClone = JSON.parse(JSON.stringify(metadataEntry));
         this.removeNotCreateableFields(metadataEntry);
         try {
             // set to empty object in case API returned nothing to be able to update it in helper classes
             const response = (await this.client.rest.post(uri, metadataEntry)) || {};
-            await this.postCreateTasks(metadataEntry, response);
+            await this.postCreateTasks(metadataEntry, response, metadataClone);
             Util.logger.info(
                 ` - created ${this.definition.type}: ${
                     metadataEntry[this.definition.keyField] ||
@@ -1060,6 +1061,7 @@ class MetadataType {
         const results = this.parseResponseBody(response, singleRetrieve);
         // get extended metadata if applicable
         if (this.definition.hasExtended) {
+            Util.logger.debug(' - retrieving extended metadata');
             const extended = await this.client.rest.getCollection(
                 Object.keys(results).map((key) => uri + results[key][this.definition.idField])
             );
@@ -1088,6 +1090,62 @@ class MetadataType {
             type: this.definition.type,
         };
     }
+    /**
+     *
+     * @param {object[]} urlArray {uri: string, id: string} combo of URL and ID/key of metadata
+     * @param {number} [concurrentRequests] optionally set a different amount of concurrent requests
+     * @param {boolean} [logAmountOfUrls] if true, prints an info message about to-be loaded amount of metadata
+     * @returns {Promise.<{metadata: (TYPE.MetadataTypeMap | TYPE.MetadataTypeItem), type: string}>} Promise of item map (single item for templated result)
+     */
+    static async retrieveRESTcollection(urlArray, concurrentRequests = 10, logAmountOfUrls = true) {
+        if (logAmountOfUrls) {
+            Util.logger.info(
+                Util.getGrayMsg(
+                    ` - ${urlArray?.length} ${this.definition.type}${
+                        urlArray?.length === 1 ? '' : 's'
+                    } found. Retrieving details...`
+                )
+            );
+        }
+        const rateLimit = pLimit(concurrentRequests);
+
+        const metadataArr = urlArray.length
+            ? await Promise.all(
+                  urlArray.map(async (item) =>
+                      rateLimit(async () => {
+                          try {
+                              return await this.client.rest.get(item.uri);
+                          } catch (ex) {
+                              return this.handleRESTErrors(ex, item.id);
+                          }
+                      })
+                  )
+              )
+            : [];
+        const results = {};
+        for (const item of metadataArr) {
+            const key = item[this.definition.keyField];
+            results[key] = item;
+        }
+        return {
+            metadata: results,
+            type: this.definition.type,
+        };
+    }
+
+    /**
+     * helper for {@link this.retrieveRESTcollection}
+     *
+     * @param {Error} ex exception
+     * @param {string} id id or key of item
+     * @returns {null} -
+     */
+    static handleRESTErrors(ex, id) {
+        // if the ID is too short, the system will throw the 400 error
+        Util.logger.debug(` ☇ skipping ${this.definition.type} ${id}: ${ex.message} ${ex.code}`);
+
+        return null;
+    }
     /**
      * Used to execute a query/automation etc.
      *
@@ -1590,27 +1648,35 @@ class MetadataType {
                     }
 
                     const postRetrieveData = results[originalKey];
+                    // normalize results[metadataEntry]
+                    results[originalKey] = postRetrieveData.json;
+
+                    if (Util.OPTIONS.like && !Util.fieldsLike(results[originalKey])) {
+                        Util.logger.debug(`Filtered ${originalKey} because of --like option`);
+                        continue;
+                    }
+
                     if (postRetrieveData.subFolder) {
                         // very complex types have their own subfolder
                         baseDir.push(...postRetrieveData.subFolder);
                     }
                     // save extracted scripts
-                    for (const script of postRetrieveData.codeArr) {
-                        const dir = [...baseDir];
-                        if (script.subFolder) {
-                            // some files shall be saved in yet a deeper subfolder
-                            dir.push(...script.subFolder);
-                        }
-                        File.writePrettyToFile(
-                            dir,
-                            script.fileName + subtypeExtension,
-                            script.fileExt,
-                            script.content,
-                            templateVariables
-                        );
-                    }
-                    // normalize results[metadataEntry]
-                    results[originalKey] = postRetrieveData.json;
+                    await Promise.all(
+                        postRetrieveData.codeArr.map(async (script) => {
+                            const dir = [...baseDir];
+                            if (script.subFolder) {
+                                // some files shall be saved in yet a deeper subfolder
+                                dir.push(...script.subFolder);
+                            }
+                            return File.writePrettyToFile(
+                                dir,
+                                script.fileName + subtypeExtension,
+                                script.fileExt,
+                                script.content,
+                                templateVariables
+                            );
+                        })
+                    );
                 } else {
                     // not a complex type, run the the entire JSON through templating
                     // replace market values with template variable placeholders
@@ -1620,12 +1686,12 @@ class MetadataType {
                             templateVariables
                         );
                     }
+                    if (Util.OPTIONS.like && !Util.fieldsLike(results[originalKey])) {
+                        Util.logger.debug(`Filtered ${originalKey} because of --like option`);
+                        continue;
+                    }
                 }
 
-                if (Util.OPTIONS.like && !Util.fieldsLike(results[originalKey])) {
-                    Util.logger.debug(`Filtered ${originalKey} because of --like option`);
-                    continue;
-                }
                 // we dont store Id on local disk, but we need it for caching logic,
                 // so its in retrieve but not in save. Here we put into the clone so that the original
                 // object used for caching doesnt have the Id removed.
@@ -2126,4 +2192,4 @@ MetadataType.subType = null;
  */
 MetadataType.buObject = null;
 
-module.exports = MetadataType;
+export default MetadataType;

package/lib/metadataTypes/MobileCode.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const MetadataType = require('./MetadataType');
+import TYPE from '../../types/mcdev.d.js';
+import MetadataType from './MetadataType.js';
 
 /**
  * MobileCode MetadataType
@@ -39,6 +39,7 @@ class MobileCode extends MetadataType {
 }
 
 // Assign definition to static attributes
-MobileCode.definition = require('../MetadataTypeDefinitions').mobileCode;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+MobileCode.definition = MetadataTypeDefinitions.mobileCode;
 
-module.exports = MobileCode;
+export default MobileCode;

package/lib/metadataTypes/MobileKeyword.js

@@ -1,10 +1,10 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const MetadataType = require('./MetadataType');
-const Util = require('../util/util');
-const File = require('../util/file');
-const cache = require('../util/cache');
+import TYPE from '../../types/mcdev.d.js';
+import MetadataType from './MetadataType.js';
+import { Util } from '../util/util.js';
+import File from '../util/file.js';
+import cache from '../util/cache.js';
 
 /**
  * MobileKeyword MetadataType
@@ -501,7 +501,7 @@ class MobileKeyword extends MetadataType {
      */
     static async deleteByKey(key) {
         // get id from cache
-        const { metadata } = await this.retrieveForCache(key);
+        const { metadata } = await this.retrieveForCache(undefined, undefined, key);
         if (!metadata[key]) {
             Util.logger.error(`Could not find ${this.definition.type} with key ${key}.`);
             return false;
@@ -549,6 +549,7 @@ class MobileKeyword extends MetadataType {
 }
 
 // Assign definition to static attributes
-MobileKeyword.definition = require('../MetadataTypeDefinitions').mobileKeyword;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+MobileKeyword.definition = MetadataTypeDefinitions.mobileKeyword;
 
-module.exports = MobileKeyword;
+export default MobileKeyword;

package/lib/metadataTypes/MobileMessage.js

@@ -1,10 +1,10 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const MetadataType = require('./MetadataType');
-const Util = require('../util/util');
-const File = require('../util/file');
-const cache = require('../util/cache');
+import TYPE from '../../types/mcdev.d.js';
+import MetadataType from './MetadataType.js';
+import { Util } from '../util/util.js';
+import File from '../util/file.js';
+import cache from '../util/cache.js';
 
 /**
  * MobileMessage MetadataType
@@ -460,6 +460,7 @@ class MobileMessage extends MetadataType {
 }
 
 // Assign definition to static attributes
-MobileMessage.definition = require('../MetadataTypeDefinitions').mobileMessage;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+MobileMessage.definition = MetadataTypeDefinitions.mobileMessage;
 
-module.exports = MobileMessage;
+export default MobileMessage;

package/lib/metadataTypes/Query.js

@@ -1,11 +1,11 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const Util = require('../util/util');
-const MetadataType = require('./MetadataType');
-const File = require('../util/file');
-const cache = require('../util/cache');
-const Mustache = require('mustache');
+import TYPE from '../../types/mcdev.d.js';
+import { Util } from '../util/util.js';
+import MetadataType from './MetadataType.js';
+import File from '../util/file.js';
+import cache from '../util/cache.js';
+import Mustache from 'mustache';
 /**
  * ensure that Mustache does not escape any characters
  *
@@ -471,6 +471,7 @@ class Query extends MetadataType {
 }
 
 // Assign definition & cache to static attributes
-Query.definition = require('../MetadataTypeDefinitions').query;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+Query.definition = MetadataTypeDefinitions.query;
 
-module.exports = Query;
+export default Query;

package/lib/metadataTypes/Role.js

@@ -1,10 +1,10 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const MetadataType = require('./MetadataType');
-const Util = require('../util/util');
-const File = require('../util/file');
-const cache = require('../util/cache');
+import TYPE from '../../types/mcdev.d.js';
+import MetadataType from './MetadataType.js';
+import { Util } from '../util/util.js';
+import File from '../util/file.js';
+import cache from '../util/cache.js';
 
 /**
  * ImportFile MetadataType
@@ -325,6 +325,7 @@ class Role extends MetadataType {
 }
 
 // Assign definition to static attributes
-Role.definition = require('../MetadataTypeDefinitions').role;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+Role.definition = MetadataTypeDefinitions.role;
 
-module.exports = Role;
+export default Role;

package/lib/metadataTypes/Script.js

@@ -1,9 +1,9 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const MetadataType = require('./MetadataType');
-const Util = require('../util/util');
-const File = require('../util/file');
+import TYPE from '../../types/mcdev.d.js';
+import MetadataType from './MetadataType.js';
+import { Util } from '../util/util.js';
+import File from '../util/file.js';
 
 /**
  * Script MetadataType
@@ -327,6 +327,7 @@ class Script extends MetadataType {
 }
 
 // Assign definition & cache to static attributes
-Script.definition = require('../MetadataTypeDefinitions').script;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+Script.definition = MetadataTypeDefinitions.script;
 
-module.exports = Script;
+export default Script;

package/lib/metadataTypes/SendClassification.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const MetadataType = require('./MetadataType');
+import TYPE from '../../types/mcdev.d.js';
+import MetadataType from './MetadataType.js';
 
 /**
  * SendClassification MetadataType
@@ -35,6 +35,7 @@ class SendClassification extends MetadataType {
 }
 
 // Assign definition to static attributes
-SendClassification.definition = require('../MetadataTypeDefinitions').sendClassification;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+SendClassification.definition = MetadataTypeDefinitions.sendClassification;
 
-module.exports = SendClassification;
+export default SendClassification;

package/lib/metadataTypes/TransactionalEmail.js

@@ -1,9 +1,10 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const TransactionalMessage = require('./TransactionalMessage');
-const Util = require('../util/util');
-const cache = require('../util/cache');
+import TYPE from '../../types/mcdev.d.js';
+import TransactionalMessage from './TransactionalMessage.js';
+import Journey from './Journey.js';
+import { Util } from '../util/util.js';
+import cache from '../util/cache.js';
 
 /**
  * TransactionalEmail MetadataType
@@ -40,21 +41,24 @@ class TransactionalEmail extends TransactionalMessage {
      */
     static async preDeployTasks(metadata) {
         // asset
-        if (metadata.content?.customerKey) {
+        if (metadata.r__asset_customerKey) {
             // we merely want to be able to show an error if it does not exist
-            cache.searchForField(
-                'asset',
-                metadata.content.customerKey,
-                'customerKey',
-                'customerKey'
-            );
+            metadata.content = {
+                customerKey: cache.searchForField(
+                    'asset',
+                    metadata.r__asset_customerKey,
+                    'customerKey',
+                    'customerKey'
+                ),
+            };
+            delete metadata.r__asset_customerKey;
         }
         // subscriptions: dataExtension
-        if (metadata.subscriptions?.dataExtension) {
+        if (metadata.subscriptions?.r__dataExtension_CustomerKey) {
             // we merely want to be able to show an error if it does not exist
-            cache.searchForField(
+            metadata.subscriptions.dataExtension = cache.searchForField(
                 'dataExtension',
-                metadata.subscriptions.dataExtension,
+                metadata.subscriptions.r__dataExtension_CustomerKey,
                 'CustomerKey',
                 'CustomerKey'
             );
@@ -69,15 +73,49 @@ class TransactionalEmail extends TransactionalMessage {
         }
 
         // journey
-        if (metadata.journey?.interactionKey) {
-            // ! update & create enpoints dont accept journey.interactionKey. They only allow to create a new journey
-            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;
-        }
+        // ! update & create enpoints dont accept journey.interactionKey. They only allow to create a new journey
+        metadata.options ||= {};
+        metadata.options.createJourney = true; // only send this during create or else we might end up with an unexpected outcome
 
         return metadata;
     }
+    /**
+     * helper for {@link TransactionalEmail.createREST}
+     *
+     * @param {TYPE.MetadataTypeItem} _ not used
+     * @param {object} apiResponse varies depending on the API call
+     * @returns {void}
+     */
+    static async postCreateTasks(_, apiResponse) {
+        if (apiResponse.journey?.interactionKey) {
+            Util.logger.warn(
+                ` - created journey: ${apiResponse.journey.interactionKey} (auto-created when ${this.definition.type} ${apiResponse.definitionKey} was created)`
+            );
+            // when we create new transactionalEmails, we should also download the new journey that was created with it
+            this._createdJourneyKeys ||= [];
+            this._createdJourneyKeys.push(apiResponse.journey?.interactionKey);
+
+            // do what postRetrieveTasks won't be able to do without spending lots of time on caching
+            apiResponse.r__journey_key = apiResponse.journey.interactionKey;
+            delete apiResponse.journey;
+        }
+    }
+    /**
+     * Gets executed after deployment of metadata type
+     *
+     * @returns {void}
+     */
+    static postDeployTasks() {
+        if (this._createdJourneyKeys?.length) {
+            Util.logger.warn(
+                `Please download related journeys via: mcdev r ${this.buObject.credential}/${
+                    this.buObject.businessUnit
+                } journey "${this._createdJourneyKeys.join(',')}"`
+            );
+        }
+        delete this._createdJourneyKeys;
+    }
+
     /**
      * manages post retrieve steps
      *
@@ -87,6 +125,7 @@ class TransactionalEmail extends TransactionalMessage {
     static postRetrieveTasks(metadata) {
         // asset
         if (metadata.content?.customerKey) {
+            metadata.r__asset_customerKey = metadata.content.customerKey;
             try {
                 // we merely want to be able to show an error if it does not exist
                 cache.searchForField(
@@ -102,9 +141,13 @@ class TransactionalEmail extends TransactionalMessage {
                     }): ${ex.message}.`
                 );
             }
+            delete metadata.content;
         }
+
         // subscriptions: dataExtension
         if (metadata.subscriptions?.dataExtension) {
+            metadata.subscriptions.r__dataExtension_CustomerKey =
+                metadata.subscriptions.dataExtension;
             try {
                 // we merely want to be able to show a warning if it does not exist
                 cache.searchForField(
@@ -120,6 +163,7 @@ class TransactionalEmail extends TransactionalMessage {
                     }): ${ex.message}.`
                 );
             }
+            delete metadata.subscriptions.dataExtension;
         }
         // subscriptions: list
         if (metadata.subscriptions?.list) {
@@ -140,9 +184,15 @@ class TransactionalEmail extends TransactionalMessage {
         }
         // journey
         if (metadata.journey?.interactionKey) {
+            metadata.r__journey_key = metadata.journey.interactionKey;
             try {
                 // we merely want to be able to show a warning if it does not exist
-                cache.searchForField('journey', metadata.journey.interactionKey, 'key', 'key');
+                metadata.r__journey_key = cache.searchForField(
+                    'journey',
+                    metadata.journey.interactionKey,
+                    'key',
+                    'key'
+                );
             } catch (ex) {
                 Util.logger.warn(
                     ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
@@ -150,13 +200,41 @@ class TransactionalEmail extends TransactionalMessage {
                     }): ${ex.message}.`
                 );
             }
+            delete metadata.journey;
         }
 
         return metadata;
     }
+    /**
+     * Delete a metadata item from the specified business unit
+     *
+     * @param {string} key Identifier of item
+     * @returns {Promise.<boolean>} deletion success status
+     */
+    static async deleteByKey(key) {
+        const metadataMapObj = await this.retrieveForCache(key);
+        const journeyKey = metadataMapObj?.metadata?.[key]?.journey?.interactionKey;
+
+        const isDeleted = await super.deleteByKeyREST(
+            '/messaging/v1/' + this.subType + '/definitions/' + key,
+            key,
+            false
+        );
+        if (isDeleted && journeyKey) {
+            Util.logger.info(
+                ` - deleted ${Journey.definition.type}: ${journeyKey} (SFMC auto-deletes the related journey of ${this.definition.type} ${key})`
+            );
+            Journey.buObject = this.buObject;
+            Journey.properties = this.properties;
+            Journey.client = this.client;
+            Journey.postDeleteTasks(journeyKey);
+        }
+        return isDeleted;
+    }
 }
 
 // Assign definition to static attributes
-TransactionalEmail.definition = require('../MetadataTypeDefinitions').transactionalEmail;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+TransactionalEmail.definition = MetadataTypeDefinitions.transactionalEmail;
 
-module.exports = TransactionalEmail;
+export default TransactionalEmail;

package/lib/metadataTypes/TransactionalMessage.js

@@ -1,8 +1,8 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const MetadataType = require('./MetadataType');
-const Util = require('../util/util');
+import TYPE from '../../types/mcdev.d.js';
+import MetadataType from './MetadataType.js';
+import { Util } from '../util/util.js';
 
 /**
  * TransactionalMessage MetadataType
@@ -67,13 +67,14 @@ class TransactionalMessage extends MetadataType {
     /**
      * Retrieves event definition metadata for caching
      *
+     * @param {string} [key] customer key of single item to cache
      * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise of metadata
      */
-    static retrieveForCache() {
+    static retrieveForCache(key) {
         // the call to /messaging/v1/email/definitions/ does not return definitionId
         // definitionId is required for resolving dependencies on interactions.
         // we should therefore use the already defined retrieve method
-        return this.retrieve();
+        return this.retrieve(undefined, undefined, undefined, key);
     }
     /**
      * Updates a single item
@@ -114,6 +115,7 @@ class TransactionalMessage extends MetadataType {
 
 // Assign definition to static attributes
 // ! using SMS definitions here as placeholder to have auto completion
-TransactionalMessage.definition = require('../MetadataTypeDefinitions').transactionalSMS;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+TransactionalMessage.definition = MetadataTypeDefinitions.transactionalSMS;
 
-module.exports = TransactionalMessage;
+export default TransactionalMessage;

package/lib/metadataTypes/TransactionalPush.js

@@ -1,9 +1,9 @@
 'use strict';
 
-const TYPE = require('../../types/mcdev.d');
-const TransactionalMessage = require('./TransactionalMessage');
-const Util = require('../util/util');
-const cache = require('../util/cache');
+import TYPE from '../../types/mcdev.d.js';
+import TransactionalMessage from './TransactionalMessage.js';
+import { Util } from '../util/util.js';
+import cache from '../util/cache.js';
 
 /**
  * TransactionalPush TransactionalMessage
@@ -72,6 +72,7 @@ class TransactionalPush extends TransactionalMessage {
 }
 
 // Assign definition to static attributes
-TransactionalPush.definition = require('../MetadataTypeDefinitions').transactionalPush;
+import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
+TransactionalPush.definition = MetadataTypeDefinitions.transactionalPush;
 
-module.exports = TransactionalPush;
+export default TransactionalPush;