mcdev 7.10.1 → 8.0.1

package/lib/metadataTypes/Journey.js

@@ -182,7 +182,8 @@ class Journey extends MetadataType {
             // if the interaction does not exist, the API returns an error code which would otherwise bring execution to a hold
             if (
                 [
-                    'Interaction matching key not found.',
+                    'Interaction matching key not found.', // might be outdated
+                    'Interaction matching criteria not found.', // seen in 2025-05
                     'Must provide a valid ID or Key parameter',
                 ].includes(ex.message) ||
                 (key && ex.code === 'ERR_BAD_REQUEST')
@@ -270,14 +271,14 @@ class Journey extends MetadataType {
                 if (version !== '*') {
                     if (!/^\d+$/.test(version)) {
                         Util.logger.error(
-                            'Version is required for deleting interactions to avoid accidental deletion of the wrong item. Please append it at the end of the key or id, separated by forward-slash. Example for deleting version 4: ' +
+                            'Version is required for deleting journeys to avoid accidental deletion of the wrong item. Please append it at the end of the key or id, separated by forward-slash. Example for deleting version 4: ' +
                                 key +
                                 '/4'
                         );
                         return false;
                     }
                     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.`
+                        `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 journeys on this BU.`
                     );
                 }
 
@@ -639,6 +640,9 @@ class Journey extends MetadataType {
      * @param {MetadataTypeItem} metadata a single item
      */
     static _postRetrieveTasks_activities(metadata) {
+        if (!metadata.activities) {
+            return;
+        }
         for (const activity of metadata.activities) {
             switch (activity.type) {
                 case 'EMAILV2': {
@@ -1407,9 +1411,7 @@ class Journey extends MetadataType {
                     default: {
                         // it is expected that we'll see 'sms' and 'push' here in the future
                         throw new Error(
-                            `channel ${
-                                metadata.channel
-                            } is not supported yet. Please open a ticket at https://github.com/Accenture/sfmc-devtools/issues/new/choose to request it`
+                            `channel ${metadata.channel} is not supported yet. Please open a ticket at https://github.com/Accenture/sfmc-devtools/issues/new/choose to request it`
                         );
                     }
                 }
@@ -1418,9 +1420,7 @@ class Journey extends MetadataType {
             }
             default: {
                 throw new Error(
-                    `definitionType ${
-                        metadata.definitionType
-                    } is not supported yet. Please open a ticket at https://github.com/Accenture/sfmc-devtools/issues/new/choose to request it`
+                    `definitionType ${metadata.definitionType} is not supported yet. Please open a ticket at https://github.com/Accenture/sfmc-devtools/issues/new/choose to request it`
                 );
             }
         }
@@ -2333,8 +2333,8 @@ class Journey extends MetadataType {
                 case 'PublishCompleted': {
                     spinner.stop();
                     const action = statusUrl.includes('/validateStatus')
-                        ? 'validation successful -'
-                        : 'published';
+                        ? '🔎 validation successful -'
+                        : '🚀 published';
 
                     Util.logger.info(` - ${action} ${this.definition.type}: ${key} / ${name}`);
                     this._showPublishStatusDetails(response);
@@ -2567,6 +2567,159 @@ class Journey extends MetadataType {
         return executedKeyArr.filter(Boolean);
     }
 
+    /**
+     * audit latest or given journey version
+     *
+     * @param {string[]} keyArr customerkey of the metadata
+     * @returns {Promise.<string[]>} Returns list of keys that were paused
+     */
+    static async audit(keyArr) {
+        let version;
+        const endpoint = '/interaction/v1/interactions/';
+        const auditedKeyArr = [];
+        const apiLimit = pLimit(20);
+        const journeyCache = await this.retrieveForCache();
+
+        const ignoredLogProperties = [
+            'executionMode',
+            'id',
+            'originalDefinitionId',
+            'publishRequestId',
+        ];
+        const preformatedProperties = [
+            'action',
+            'description',
+            'errors',
+            'key',
+            'name',
+            'publishedVersion',
+            'publishStatus',
+            'timeStamp',
+            'user',
+            'versionNumber',
+        ];
+
+        await Promise.allSettled(
+            keyArr.map((key) =>
+                apiLimit(async () => {
+                    [key, version] = key.split('/');
+                    if (!journeyCache.metadata[key]) {
+                        Util.logger.error(
+                            ` ☇ skipping audit log of ${this.definition.type} ${key}: not found on server`
+                        );
+                        return;
+                    }
+                    const toBeAuditedVersions = [];
+                    if (version === '*' || !version) {
+                        switch (journeyCache.metadata[key].definitionType) {
+                            case 'Transactional':
+                            case 'Multistep': {
+                                // transactional send journeys technically only have one version, but if you delete them and then create one with the same key their version number goes up and old audit logs are still available
+                                // multi-step journey versions could be retrieved but then we lose info of any versions that might have been deleted. Therefore we add all versions starting with the latest and counting down to 1
+                                for (let i = journeyCache.metadata[key].version; i > 0; i--) {
+                                    toBeAuditedVersions.push(i);
+                                }
+                            }
+                        }
+                    } else {
+                        toBeAuditedVersions.push(version);
+                    }
+
+                    Util.logger.info(
+                        ` - Audit log for ${this.definition.type} ${key} / ${journeyCache.metadata[key].name}`
+                    );
+                    const rateLimitActivities = pLimit(1);
+                    const auditedVersions = (
+                        await Promise.all(
+                            toBeAuditedVersions.map((version) =>
+                                rateLimitActivities(async () => {
+                                    try {
+                                        const response = await this.client.rest.getBulk(
+                                            endpoint +
+                                                journeyCache.metadata[key].id +
+                                                `/audit/all?versionNumber=${version}`
+                                        );
+
+                                        Util.logger.info(
+                                            ` - Version ${version}:\n  - ` +
+                                                response.items
+                                                    .map((log) => {
+                                                        let msg =
+                                                            `${log.action} version ${log.versionNumber} - ${Util.getGrayMsg(log.timeStamp.replace('T', ' ').slice(0, 19))}: ${log.user.name}\n` +
+                                                            (log.publishedVersion
+                                                                ? `    Published Version: ` +
+                                                                  log.publishedVersion +
+                                                                  '\n'
+                                                                : '') +
+                                                            (log.publishStatus
+                                                                ? `    Publish Status: ` +
+                                                                  log.publishStatus +
+                                                                  '\n'
+                                                                : '') +
+                                                            (log.key === key
+                                                                ? ''
+                                                                : `    Key: ` + log.key + '\n') +
+                                                            (log.name ===
+                                                            journeyCache.metadata[key].name
+                                                                ? ''
+                                                                : `    Key: ` + log.key + '\n') +
+                                                            (log.errors
+                                                                ? `    Errors:\n    • ` +
+                                                                  log.errors
+                                                                      .map((error) =>
+                                                                          error.ErrorDetail.replaceAll(
+                                                                              /[\r\n]/g,
+                                                                              ' '
+                                                                          )
+                                                                      )
+                                                                      .join('\n    • ') +
+                                                                  '\n'
+                                                                : '');
+                                                        for (const key in log) {
+                                                            if (
+                                                                !ignoredLogProperties.includes(
+                                                                    key
+                                                                ) &&
+                                                                !preformatedProperties.includes(key)
+                                                            ) {
+                                                                msg +=
+                                                                    `    ${key}: ` +
+                                                                    log[key] +
+                                                                    '\n';
+                                                            }
+                                                        }
+                                                        return msg;
+                                                    })
+                                                    .join('  - ')
+                                        );
+                                        // Util.logger.info(JSON.stringify(auditLog, null, 2));
+                                        return version;
+                                    } catch (ex) {
+                                        if (journeyCache.metadata[key].version > version) {
+                                            Util.logger.error(
+                                                ` - Retrieving audit log for ${this.definition.type} ${key} / ${journeyCache.metadata[key].name} - Version ${version} failed: Version was not found. The highest available version seems to be ${journeyCache.metadata[key].version}`
+                                            );
+                                        } else {
+                                            Util.logger.error(
+                                                ` - Retrieving audit log for ${this.definition.type} ${key} / ${journeyCache.metadata[key].name} - Version ${version} failed: ${ex.message}`
+                                            );
+                                        }
+                                        return;
+                                    }
+                                })
+                            )
+                        )
+                    ).filter(Boolean);
+                    if (auditedVersions.length === toBeAuditedVersions.length) {
+                        auditedKeyArr.push(key);
+                    }
+                })
+            )
+        );
+
+        return auditedKeyArr;
+    }
+
     /**
      * stops latest journey version
      *
@@ -2577,11 +2730,11 @@ class Journey extends MetadataType {
         let version;
         const endpoint = '/interaction/v1/interactions/stop/';
         const stoppedKeyArr = [];
-        const pauseTransactionalKeyArr = [];
+        const stopTransactionalKeyArr = [];
         const apiLimit = pLimit(20);
         const journeyCache = await this.retrieveForCache();
 
-        const stoppableJourneyStatus = ['Paused', 'Published', 'Finishing'];
+        const stoppableJourneyStatus = ['Paused', 'Published', 'Unpublished']; // 'Unpublished' is shown as 'Finishing' in the UI
 
         await Promise.allSettled(
             keyArr.map((key) =>
@@ -2591,7 +2744,7 @@ class Journey extends MetadataType {
                         switch (journeyCache.metadata[key].definitionType) {
                             case 'Transactional': {
                                 // transactional send journeys cannot be "stopped" but only "paused"
-                                pauseTransactionalKeyArr.push(key);
+                                stopTransactionalKeyArr.push(key);
                                 break;
                             }
                             case 'Multistep': {
@@ -2652,12 +2805,12 @@ class Journey extends MetadataType {
                                                         {}
                                                     );
                                                     Util.logger.info(
-                                                        ` - Stopped ${this.definition.type} ${key} / ${journeyCache.metadata[key].name} - Version ${version}`
+                                                        ` - ⛔ stopped ${this.definition.type} ${key} / ${journeyCache.metadata[key].name} - Version ${version}`
                                                     );
                                                     return version;
                                                 } catch (ex) {
                                                     Util.logger.error(
-                                                        ` - Stopping ${this.definition.type} ${key} / ${journeyCache.metadata[key].name} - Version ${version} failed: ${ex.message}`
+                                                        ` - stopping ${this.definition.type} ${key} / ${journeyCache.metadata[key].name} - Version ${version} failed: ${ex.message}`
                                                     );
                                                     return;
                                                 }
@@ -2685,7 +2838,7 @@ class Journey extends MetadataType {
                 })
             )
         );
-        stoppedKeyArr.push(...(await this.pause(pauseTransactionalKeyArr)));
+        stoppedKeyArr.push(...(await this.pause(stopTransactionalKeyArr)));
 
         return stoppedKeyArr;
     }
@@ -2708,16 +2861,20 @@ class Journey extends MetadataType {
                 apiLimit(async () => {
                     [key, version] = key.split('/');
                     if (journeyCache.metadata[key]) {
-                        if (journeyCache.metadata[key].status === 'Paused') {
+                        if (
+                            (!version || journeyCache.metadata[key].version == version) &&
+                            journeyCache.metadata[key].status === 'Paused'
+                        ) {
                             Util.logger.info(
-                                ` ${this.definition.type} ${
-                                    key
-                                } (${journeyCache.metadata[key].name}): already paused`
+                                ` ${this.definition.type} ${key} (${journeyCache.metadata[key].name}): already paused`
                             );
                             // still add this key because technically this method is supposed to pause a journey and this journey is paused. mission accomplished. Also, we need that for _refreshItem() to function
                             pausedKeyArr.push(key);
                             return;
-                        } else if (journeyCache.metadata[key].status !== 'Published') {
+                        } else if (
+                            (!version || journeyCache.metadata[key].version == version) &&
+                            journeyCache.metadata[key].status !== 'Published'
+                        ) {
                             Util.logger.error(
                                 ` - Pausing ${this.definition.type} ${key} / ${journeyCache.metadata[key].name} failed: Cannot pause a journey in status ${journeyCache.metadata[key].status}`
                             );
@@ -2757,7 +2914,7 @@ class Journey extends MetadataType {
                                         {}
                                     );
                                     Util.logger.info(
-                                        ` -- 🛑 paused ${this.definition.type} ${key}/${version} / ${journeyCache.metadata[key].name}`
+                                        ` - 🛑 paused ${this.definition.type} ${key}/${version} / ${journeyCache.metadata[key].name}`
                                     );
                                     pausedKeyArr.push(key);
                                 } catch (ex) {
@@ -2803,7 +2960,10 @@ class Journey extends MetadataType {
                 apiLimit(async () => {
                     [key, version] = key.split('/');
                     if (journeyCache.metadata[key]) {
-                        if (journeyCache.metadata[key].status !== 'Paused') {
+                        if (
+                            (!version || journeyCache.metadata[key].version == version) &&
+                            journeyCache.metadata[key].status !== 'Paused'
+                        ) {
                             Util.logger.error(
                                 ` - Resuming ${this.definition.type} ${key} / ${journeyCache.metadata[key].name} failed: Cannot pause a journey in status ${journeyCache.metadata[key].status}`
                             );

package/lib/metadataTypes/MetadataType.js

@@ -299,7 +299,7 @@ class MetadataType {
      * @returns {Promise.<MetadataTypeMapObj>} metadata
      */
     static async retrieve(retrieveDir, additionalFields, subTypeArr, key) {
-        Util.notSupportedError(this.definition, 'retrieve');
+        Util.logNotSupported(this.definition, 'retrieve');
         return { metadata: {}, type: this.definition.type };
     }
 
@@ -329,6 +329,7 @@ class MetadataType {
     /**
      * Gets metadata cache with limited fields and does not store value to disk
      *
+     * @deprecated Use `retrieve` followed by `build` instead. `retrieveAsTemplate` will be removed in a future version.
      * @param {string} templateDir Directory where retrieved metadata directory will be saved
      * @param {string} name name of the metadata file
      * @param {TemplateMap} templateVariables variables to be replaced in the metadata
@@ -336,7 +337,8 @@ class MetadataType {
      * @returns {Promise.<MetadataTypeItemObj>} metadata
      */
     static async retrieveAsTemplate(templateDir, name, templateVariables, subType) {
-        Util.notSupportedError(this.definition, 'retrieveAsTemplate');
+        Util.logNotSupported(this.definition, 'retrieveAsTemplate');
+        Util.logDeprecated('retrieveAsTemplate', `'retrieve' followed by 'build'`);
         return { metadata: null, type: this.definition.type };
     }
 
@@ -499,7 +501,7 @@ class MetadataType {
      * @returns {Promise.<object> | null} Promise of API response or null in case of an error
      */
     static async create(metadata, deployDir) {
-        Util.notSupportedError(this.definition, 'retrieveAsTemplate', metadata);
+        Util.logNotSupported(this.definition, 'create', metadata);
         return;
     }
 
@@ -511,7 +513,7 @@ class MetadataType {
      * @returns {Promise.<object> | null} Promise of API response or null in case of an error
      */
     static async update(metadata, metadataBefore) {
-        Util.notSupportedError(this.definition, 'retrieveAsTemplate', metadata);
+        Util.logNotSupported(this.definition, 'update', metadata);
         return;
     }
 
@@ -524,7 +526,7 @@ class MetadataType {
      * @returns {Promise.<string[]>} Returns list of keys that were refreshed
      */
     static async refresh(keyArr, checkKey = true, upsertResults) {
-        Util.notSupportedError(this.definition, 'refresh');
+        Util.logNotSupported(this.definition, 'refresh');
         return [];
     }
 
@@ -630,7 +632,7 @@ class MetadataType {
      * @returns {Promise.<MetadataTypeItem | CodeExtractItem>} key of the item that was updated
      */
     static async replaceCbReference(item, retrieveDir, findAssetKeys) {
-        Util.notSupportedError(this.definition, 'replaceCbReference');
+        Util.logNotSupported(this.definition, 'replaceCbReference');
         return [];
     }
 
@@ -642,7 +644,7 @@ class MetadataType {
      * @returns {Promise.<string[]>} Returns list of keys that were executed
      */
     static async execute(keyArr, cache) {
-        Util.notSupportedError(this.definition, 'execute');
+        Util.logNotSupported(this.definition, 'execute');
         return [];
     }
 
@@ -654,7 +656,7 @@ class MetadataType {
      * @returns {Promise.<string[]>} Returns list of keys that were executed
      */
     static async schedule(keyArr, cache) {
-        Util.notSupportedError(this.definition, 'schedule');
+        Util.logNotSupported(this.definition, 'schedule');
         return [];
     }
 
@@ -666,7 +668,7 @@ class MetadataType {
      * @returns {Promise.<string[]>} Returns list of keys that were paused
      */
     static async pause(keyArr, cache) {
-        Util.notSupportedError(this.definition, 'pause');
+        Util.logNotSupported(this.definition, 'pause');
         return [];
     }
 
@@ -677,7 +679,7 @@ class MetadataType {
      * @returns {Promise.<string[]>} Returns list of keys that were stopped
      */
     static async stop(keyArr) {
-        Util.notSupportedError(this.definition, 'stop');
+        Util.logNotSupported(this.definition, 'stop');
         return [];
     }
 
@@ -1251,9 +1253,10 @@ class MetadataType {
      * @param {MetadataTypeItem} metadataEntry a single metadata Entry
      * @param {string} uri rest endpoint for PATCH
      * @param {'patch'|'post'|'put'} [httpMethod] defaults to 'patch'; some update requests require PUT instead of PATCH
+     * @param {boolean} [handleOutside] if the API reponse is irregular this allows you to handle it outside of this generic method
      * @returns {Promise.<object> | null} Promise of API response or null in case of an error
      */
-    static async updateREST(metadataEntry, uri, httpMethod = 'patch') {
+    static async updateREST(metadataEntry, uri, httpMethod = 'patch', handleOutside) {
         const metadataClone = structuredClone(metadataEntry);
         this.removeNotUpdateableFields(metadataEntry);
         try {
@@ -1263,7 +1266,11 @@ class MetadataType {
             this.getErrorsREST(response);
             response = await this.postUpdateTasks(metadataEntry, response, metadataClone);
             // some times, e.g. automation dont return a key in their update response and hence we need to fall back to name
-            Util.logger.info(` - updated ${Util.getTypeKeyName(this.definition, metadataEntry)}`);
+            if (!handleOutside) {
+                Util.logger.info(
+                    ` - updated ${Util.getTypeKeyName(this.definition, metadataEntry)}`
+                );
+            }
             return response;
         } catch (ex) {
             const parsedErrors = this.getErrorsREST(ex);
@@ -1435,15 +1442,35 @@ 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(
+            const amount = Object.keys(results).length;
+            if (amount > 100) {
+                Util.logger.info(
+                    Util.getGrayMsg(
+                        ` - retrieving extended metadata for ${amount} ${this.definition.type}s...`
+                    )
+                );
+            } else {
+                Util.logger.debug(' - retrieving extended metadata');
+            }
+            const rateLimit = pLimit(this.definition.restConcurrentLimit || 5);
+            const extended = await Promise.all(
                 Object.keys(results)
-                    .map((key) =>
-                        uri.endsWith(results[key][this.definition.idField])
+                    .map((key) => {
+                        const url = uri.endsWith(results[key][this.definition.idField])
                             ? null
-                            : uri + results[key][this.definition.idField]
-                    )
+                            : uri + results[key][this.definition.idField];
+                        return url ? { url, key } : null;
+                    })
                     .filter(Boolean)
+                    .map((el) =>
+                        rateLimit(async () => {
+                            try {
+                                return await this.client.rest.get(el.url);
+                            } catch (ex) {
+                                return await this.handleRESTErrors(ex, el.key, el.url);
+                            }
+                        })
+                    )
             );
             for (const ext of extended) {
                 const key = ext[this.definition.keyField];
@@ -1501,7 +1528,7 @@ class MetadataType {
                           try {
                               return await this.client.rest.get(item.uri);
                           } catch (ex) {
-                              return this.handleRESTErrors(ex, item.id);
+                              return await this.handleRESTErrors(ex, item.id, item.uri);
                           }
                       })
                   )
@@ -1523,12 +1550,13 @@ class MetadataType {
      * helper for {@link this.retrieveRESTcollection}
      *
      * @param {RestError} ex exception
-     * @param {string} id id or key of item
+     * @param {string} key id or key of item
+     * @param {string} url url to call for retry
      * @returns {Promise.<any>} -
      */
-    static async handleRESTErrors(ex, id) {
+    static async handleRESTErrors(ex, key, url) {
         // 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}`);
+        Util.logger.debug(` ☇ skipping ${this.definition.type} ${key}: ${ex.message} ${ex.code}`);
 
         return null;
     }
@@ -2438,7 +2466,7 @@ class MetadataType {
      */
     static document(metadata, isDeploy) {
         if (!isDeploy) {
-            Util.notSupportedError(this.definition, 'document');
+            Util.logNotSupported(this.definition, 'document');
         }
     }
 
@@ -2449,7 +2477,7 @@ class MetadataType {
      * @returns {Promise.<{key:string, name:string}>} key, name and path of metadata; null if not found
      */
     static async resolveId(id) {
-        Util.notSupportedError(this.definition, 'resolveId');
+        Util.logNotSupported(this.definition, 'resolveId');
         return;
     }
 
@@ -2460,7 +2488,7 @@ class MetadataType {
      * @returns {Promise.<boolean>} deletion success status
      */
     static async deleteByKey(customerKey) {
-        Util.notSupportedError(this.definition, 'delete');
+        Util.logNotSupported(this.definition, 'delete');
         return false;
     }
 

package/lib/metadataTypes/MobileKeyword.js

@@ -137,12 +137,14 @@ class MobileKeyword extends MetadataType {
     /**
      * retrieve an item and create a template from it
      *
+     * @deprecated Use `retrieve` followed by `build` instead. `retrieveAsTemplate` will be removed in a future version.
      * @param {string} templateDir Directory where retrieved metadata directory will be saved
      * @param {string} key name of the metadata file
      * @param {TemplateMap} templateVariables variables to be replaced in the metadata
      * @returns {Promise.<MetadataTypeItemObj>} Promise of metadata
      */
     static async retrieveAsTemplate(templateDir, key, templateVariables) {
+        Util.logDeprecated('retrieveAsTemplate', `'retrieve' followed by 'build'`);
         try {
             let queryParams;
             [key, queryParams] = this.#getRetrieveKeyAndUrl(key);

package/lib/metadataTypes/Query.js

@@ -127,12 +127,14 @@ class Query extends MetadataType {
     /**
      * Retrieve a specific Query by Name
      *
+     * @deprecated Use `retrieve` followed by `build` instead. `retrieveAsTemplate` will be removed in a future version.
      * @param {string} templateDir Directory where retrieved metadata directory will be saved
      * @param {string} name name of the metadata file
      * @param {TemplateMap} templateVariables variables to be replaced in the metadata
      * @returns {Promise.<{metadata: Query, type: string}>} Promise of metadata
      */
     static async retrieveAsTemplate(templateDir, name, templateVariables) {
+        Util.logDeprecated('retrieveAsTemplate', `'retrieve' followed by 'build'`);
         await File.initPrettier('sql');
         return super.retrieveREST(
             templateDir,

package/lib/metadataTypes/Script.js

@@ -57,12 +57,14 @@ class Script extends MetadataType {
     /**
      * Retrieve a specific Script by Name
      *
+     * @deprecated Use `retrieve` followed by `build` instead. `retrieveAsTemplate` will be removed in a future version.
      * @param {string} templateDir Directory where retrieved metadata directory will be saved
      * @param {string} name name of the metadata file
      * @param {TemplateMap} templateVariables variables to be replaced in the metadata
      * @returns {Promise.<{metadata: ScriptItem, type: string}>} Promise
      */
     static async retrieveAsTemplate(templateDir, name, templateVariables) {
+        Util.logDeprecated('retrieveAsTemplate', `'retrieve' followed by 'build'`);
         await File.initPrettier('ssjs');
         return super.retrieveREST(
             templateDir,