mcdev 5.0.0 → 5.0.2

package/lib/metadataTypes/MobileKeyword.js

@@ -24,14 +24,12 @@ class MobileKeyword extends MetadataType {
      */
     static retrieve(retrieveDir, _, __, key) {
         try {
+            let queryParams;
+            [key, queryParams] = this.#getRetrieveKeyAndUrl(key);
+
             return super.retrieveREST(
                 retrieveDir,
-                '/legacy/v1/beta/mobile/keyword/' +
-                    (key
-                        ? key.startsWith('id:')
-                            ? key.slice(3)
-                            : `?view=simple&$where=keyword%20eq%20%27${key}%27%20`
-                        : '?view=simple'),
+                '/legacy/v1/beta/mobile/keyword/' + queryParams,
                 null,
                 key
             );
@@ -47,6 +45,109 @@ class MobileKeyword extends MetadataType {
         }
     }
 
+    /**
+     * Builds map of metadata entries mapped to their keyfields
+     *
+     * @param {object} body json of response body
+     * @param {string|number} [singleRetrieve] key of single item to filter by
+     * @returns {TYPE.MetadataTypeMap} keyField => metadata map
+     */
+    static parseResponseBody(body, singleRetrieve) {
+        const bodyIteratorField = this.definition.bodyIteratorField;
+        const keyField = this.definition.keyField;
+        const metadataStructure = {};
+        if (body !== null) {
+            if (Array.isArray(body)) {
+                // in some cases data is just an array
+                for (const item of body) {
+                    this.#createCustomKeyField(item);
+                    const key = item[keyField];
+                    metadataStructure[key] = item;
+                }
+            } else if (body[bodyIteratorField]) {
+                for (const item of body[bodyIteratorField]) {
+                    this.#createCustomKeyField(item);
+                    const key = item[keyField];
+                    metadataStructure[key] = item;
+                }
+            } else if (singleRetrieve) {
+                // some types will return a single item intead of an array if the key is supported by their api
+                this.#createCustomKeyField(body);
+                // ! currently, the id: prefix is only supported by journey (interaction)
+                if (singleRetrieve.startsWith('id:')) {
+                    singleRetrieve = body[keyField];
+                }
+                metadataStructure[singleRetrieve] = body;
+                return metadataStructure;
+            }
+            if (
+                metadataStructure[singleRetrieve] &&
+                (typeof singleRetrieve === 'string' || typeof singleRetrieve === 'number')
+            ) {
+                // in case we really just wanted one entry but couldnt do so in the api call, filter it here
+                const single = {};
+                single[singleRetrieve] = metadataStructure[singleRetrieve];
+                return single;
+            } else if (singleRetrieve) {
+                return {};
+            }
+        }
+        return metadataStructure;
+    }
+
+    /**
+     * helper for {@link parseResponseBody} that creates a custom key field for this type based on mobileCode and keyword
+     *
+     * @private
+     * @param {TYPE.MetadataType} metadata single item
+     */
+    static #createCustomKeyField(metadata) {
+        metadata.c__codeKeyword = metadata.code.code + '.' + metadata.keyword;
+    }
+
+    /**
+     * helper for {@link preDeployTasks} and {@link createOrUpdate} to ensure we have code & keyword properly set
+     *
+     * @private
+     * @param {TYPE.MetadataType} metadata single item
+     */
+    static #setCodeAndKeyword(metadata) {
+        const [code, keyword] = metadata.c__codeKeyword.split('.');
+
+        // mobileCode
+        metadata.code = {
+            id: cache.searchForField('mobileCode', code, 'code', 'id'),
+        };
+
+        // keyword
+        metadata.keyword = keyword;
+    }
+
+    /**
+     * helper for {@link MetadataType.upsert}
+     *
+     * @param {TYPE.MetadataTypeMap} metadataMap list of metadata
+     * @param {string} metadataKey key of item we are looking at
+     * @param {boolean} hasError error flag from previous code
+     * @param {TYPE.MetadataTypeItemDiff[]} metadataToUpdate list of items to update
+     * @param {TYPE.MetadataTypeItem[]} metadataToCreate list of items to create
+     * @returns {'create' | 'update' | 'skip'} action to take
+     */
+    static createOrUpdate(metadataMap, metadataKey, hasError, metadataToUpdate, metadataToCreate) {
+        const createOrUpdateAction = super.createOrUpdate(
+            metadataMap,
+            metadataKey,
+            hasError,
+            metadataToUpdate,
+            metadataToCreate
+        );
+        if (createOrUpdateAction === 'update') {
+            // in case --changeKeyField or --changeKeyValue was used, let's ensure we set code & keyword here again
+            this.#setCodeAndKeyword(metadataMap[metadataKey]);
+        }
+        return createOrUpdateAction;
+    }
+
     /**
      * Retrieves event definition metadata for caching
      *
@@ -60,26 +161,29 @@ class MobileKeyword extends MetadataType {
     }
 
     /**
-     * Retrieve a specific keyword
+     * retrieve an item and create a template from it
      *
      * @param {string} templateDir Directory where retrieved metadata directory will be saved
-     * @param {string} name name of the metadata file
+     * @param {string} key name of the metadata file
      * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
      * @returns {Promise.<TYPE.MetadataTypeItemObj>} Promise of metadata
      */
-    static async retrieveAsTemplate(templateDir, name, templateVariables) {
+    static async retrieveAsTemplate(templateDir, key, templateVariables) {
         try {
+            let queryParams;
+            [key, queryParams] = this.#getRetrieveKeyAndUrl(key);
+
             return super.retrieveTemplateREST(
                 templateDir,
-                `/legacy/v1/beta/mobile/keyword/?view=simple&$where=keyword%20eq%20%27${name}%27%20`,
+                `/legacy/v1/beta/mobile/keyword/` + queryParams,
                 templateVariables,
-                name
+                key
             );
         } catch (ex) {
             // if the mobileMessage does not exist, the API returns the error "Request failed with status code 400 (ERR_BAD_REQUEST)" which would otherwise bring execution to a hold
-            if (name && ex.code === 'ERR_BAD_REQUEST') {
+            if (key && ex.code === 'ERR_BAD_REQUEST') {
                 Util.logger.info(
-                    `Downloaded: ${this.definition.type} (0)${Util.getKeysString(name)}`
+                    `Downloaded: ${this.definition.type} (0)${Util.getKeysString(key)}`
                 );
             } else {
                 throw ex;
@@ -88,13 +192,43 @@ class MobileKeyword extends MetadataType {
     }
 
     /**
-     * Creates a single Event Definition
+     * helper for {@link retrieve} and {@link retrieveAsTemplate}
+     *
+     * @private
+     * @param {string} key customer key of single item to retrieve / name of the metadata file
+     * @returns {Array} key, queryParams
+     */
+    static #getRetrieveKeyAndUrl(key) {
+        let queryParams;
+        if (key) {
+            if (key.startsWith('id:')) {
+                // overwrite queryParams
+                queryParams = key.slice(3);
+            } else if (key.includes('.')) {
+                // keywords are always uppercased
+                key = key.toUpperCase();
+                // format: code.keyword
+                const [code, keyword] = key.split('.');
+                queryParams = `?view=simple&$where=keyword%20eq%20%27${keyword}%27%20and%code%20eq%20%27${code}%27%20`;
+            } else {
+                throw new Error(
+                    `key ${key} has unexpected format. Expected 'code.keyword' or 'id:yourId'`
+                );
+            }
+        } else {
+            queryParams = '?view=simple';
+        }
+        return [key, queryParams];
+    }
+
+    /**
+     * Creates a single item
      *
-     * @param {TYPE.MetadataTypeItem} MobileKeyword a single Event Definition
+     * @param {TYPE.MetadataTypeItem} metadata a single item
      * @returns {Promise} Promise
      */
-    static create(MobileKeyword) {
-        return super.createREST(MobileKeyword, '/legacy/v1/beta/mobile/keyword/');
+    static create(metadata) {
+        return super.createREST(metadata, '/legacy/v1/beta/mobile/keyword/');
     }
     /**
      * Updates a single item
@@ -114,9 +248,21 @@ class MobileKeyword extends MetadataType {
      * manages post retrieve steps
      *
      * @param {TYPE.MetadataTypeItem} metadata a single item
-     * @returns {TYPE.CodeExtractItem | TYPE.MetadataTypeItem} Array with one metadata object and one ssjs string
+     * @returns {TYPE.CodeExtractItem | TYPE.MetadataTypeItem | void} Array with one metadata object and one ssjs string; or single metadata object; nothing if filtered
      */
     static postRetrieveTasks(metadata) {
+        try {
+            cache.searchForField('mobileCode', metadata.code.code, 'code', 'id');
+        } catch {
+            // in case the the mobileCode cannot be found, do not save this keyword as its no longer accessible in the UI either
+            Util.logger.debug(
+                ` - skipping ${this.definition.type} ${
+                    metadata[this.definition.keyField]
+                }. Could not find parent mobileCode ${metadata.code.code}`
+            );
+            return;
+        }
+
         if (metadata.responseMessage) {
             // extract message body
             const codeArr = [];
@@ -295,8 +441,7 @@ class MobileKeyword extends MetadataType {
             );
         }
 
-        // mobileCode
-        metadata.code.id = cache.searchForField('mobileCode', metadata.code.code, 'code', 'id');
+        this.#setCodeAndKeyword(metadata);
         return metadata;
     }
     /**

package/lib/metadataTypes/MobileMessage.js

@@ -163,21 +163,17 @@ class MobileMessage extends MetadataType {
 
         // mobileKeyword
         try {
-            if (metadata.keyword?.keyword) {
-                cache.searchForField(
-                    'mobileKeyword',
-                    metadata.keyword.keyword,
-                    'keyword',
-                    'keyword'
-                );
-            }
-            if (metadata.subscriptionKeyword?.keyword) {
-                cache.searchForField(
-                    'mobileKeyword',
-                    metadata.subscriptionKeyword.keyword,
-                    'keyword',
-                    'keyword'
-                );
+            for (const attr of ['keyword', 'subscriptionKeyword', 'nextKeyword']) {
+                if (metadata[attr]?.id) {
+                    metadata[attr] = {
+                        c__codeKeyword: cache.searchForField(
+                            'mobileKeyword',
+                            metadata[attr].id,
+                            'id',
+                            'c__codeKeyword'
+                        ),
+                    };
+                }
             }
         } catch (ex) {
             Util.logger.warn(
@@ -265,20 +261,16 @@ class MobileMessage extends MetadataType {
         metadata.code = code;
 
         // mobileKeyword
-        if (metadata.keyword?.keyword) {
-            const keyword = cache.getByKey('mobileKeyword', metadata.keyword.keyword);
-            if (!keyword) {
-                throw new Error(`mobileKeyword ${metadata.keyword.keyword} not found in cache`);
-            }
-            metadata.keyword = keyword;
-        }
-        if (metadata.subscriptionKeyword?.keyword) {
-            const keyword = cache.getByKey('mobileKeyword', metadata.subscriptionKeyword.keyword);
-            if (!keyword) {
-                throw new Error(`mobileKeyword ${metadata.keyword.keyword} not found in cache`);
+        for (const attr of ['keyword', 'subscriptionKeyword', 'nextKeyword']) {
+            if (metadata[attr]?.c__codeKeyword) {
+                const keywordObj = cache.getByKey('mobileKeyword', metadata[attr].c__codeKeyword);
+                if (!keywordObj) {
+                    throw new Error(
+                        `mobileKeyword ${metadata[attr].c__codeKeyword} not found in cache`
+                    );
+                }
+                metadata[attr] = keywordObj;
             }
-
-            metadata.subscriptionKeyword.keyword = keyword;
         }
 
         // campaign

package/lib/metadataTypes/Role.js

@@ -102,9 +102,8 @@ class Role extends MetadataType {
                 `Downloaded: ${this.definition.type} (${Object.keys(savedMetadata).length})` +
                     Util.getKeysString(key)
             );
-            if (this.properties.metaDataTypes.documentOnRetrieve.includes(this.definition.type)) {
-                await this.document(savedMetadata);
-            }
+
+            await this.runDocumentOnRetrieve(key, savedMetadata);
         }
         return { metadata: parsed, type: this.definition.type };
     }

package/lib/metadataTypes/TransactionalSMS.js

@@ -58,9 +58,9 @@ class TransactionalSMS extends TransactionalMessage {
             // we merely want to be able to show an error if it does not exist
             cache.searchForField(
                 'mobileKeyword',
-                metadata.subscriptions.keyword,
-                'keyword',
-                'keyword'
+                metadata.subscriptions.shortCode + '.' + metadata.subscriptions.keyword,
+                'c__codeKeyword',
+                'id'
             );
         }
         return metadata;
@@ -142,9 +142,9 @@ class TransactionalSMS extends TransactionalMessage {
                 // we merely want to be able to show a warning if it does not exist
                 cache.searchForField(
                     'mobileKeyword',
-                    metadata.subscriptions.keyword,
+                    metadata.subscriptions.shortCode + '.' + metadata.subscriptions.keyword,
                     'keyword',
-                    'keyword'
+                    'id'
                 );
             } catch {
                 Util.logger.warn(

package/lib/metadataTypes/User.js

@@ -149,25 +149,33 @@ class User extends MetadataType {
         // convert SSO / Federation Token into API compliant format
         if (metadata.SsoIdentity || metadata.SsoIdentities) {
             const ssoIdentity = {};
+            let error = false;
             if (metadata.SsoIdentity) {
                 // assume metadata.SsoIdentity is an object
                 ssoIdentity.IsActive = metadata.SsoIdentity.IsActive;
-                ssoIdentity.FederatedId = metadata.SsoIdentity.FederatedId;
+                ssoIdentity.FederatedID = metadata.SsoIdentity.FederatedID;
                 delete metadata.SsoIdentity;
             } else if (Array.isArray(metadata.SsoIdentities)) {
                 // be nice and allow SsoIdentities as an alternative if its an array of objects
                 ssoIdentity.IsActive = metadata.SsoIdentities[0].IsActive;
-                ssoIdentity.FederatedId = metadata.SsoIdentities[0].FederatedId;
+                ssoIdentity.FederatedID = metadata.SsoIdentities[0].FederatedID;
             } else if (
                 Array.isArray(metadata.SsoIdentities?.SsoIdentity) &&
                 metadata.SsoIdentities?.SsoIdentity.length
             ) {
                 // API-compliant format already provided; just use it
                 ssoIdentity.IsActive = metadata.SsoIdentities.SsoIdentity[0]?.IsActive;
-                ssoIdentity.FederatedId = metadata.SsoIdentities.SsoIdentity[0]?.FederatedId;
+                ssoIdentity.FederatedID = metadata.SsoIdentities.SsoIdentity[0]?.FederatedID;
             } else {
+                error = true;
+            }
+            if (
+                (ssoIdentity.IsActive !== true && ssoIdentity.IsActive !== false) ||
+                !ssoIdentity.FederatedID ||
+                error
+            ) {
                 throw new TypeError(
-                    'SsoIdentity should be an object with IsActive and FederatedId properties.'
+                    'SsoIdentity should be an object with IsActive and FederatedID properties.'
                 );
             }
             // if SsoIdentity is set, assume this was on purpose and bring it
@@ -175,7 +183,7 @@ class User extends MetadataType {
                 SsoIdentity: [
                     {
                         IsActive: ssoIdentity.IsActive,
-                        FederatedId: ssoIdentity.FederatedId,
+                        FederatedID: ssoIdentity.FederatedID,
                     },
                 ],
             };
@@ -207,12 +215,12 @@ class User extends MetadataType {
         );
 
         if (action === 'create') {
-            const createItem = metadataToCreate[metadataToCreate.length - 1];
+            const createItem = metadataToCreate.at(-1);
             User._setPasswordForNewUser(createItem);
             User._prepareRoleAssignments({ after: createItem });
             User._prepareBuAssignments(metadata[metadataKey], null, createItem);
         } else if (action === 'update') {
-            const updateItem = metadataToUpdate[metadataToUpdate.length - 1];
+            const updateItem = metadataToUpdate.at(-1);
             User._prepareRoleAssignments(updateItem);
             User._prepareBuAssignments(metadata[metadataKey], updateItem, null);
         }
@@ -723,13 +731,7 @@ class User extends MetadataType {
                     )
                 );
             }
-            if (
-                !singleRetrieve &&
-                this.buObject &&
-                this.properties.metaDataTypes.documentOnRetrieve.includes(this.definition.type)
-            ) {
-                await this.document(savedMetadata);
-            }
+            await this.runDocumentOnRetrieve(singleRetrieve, savedMetadata);
         }
         return { metadata: metadata, type: this.definition.type };
     }
@@ -936,14 +938,6 @@ class User extends MetadataType {
             return;
         }
 
-        // if ran as part of retrieve/deploy with key, exit here
-        if (metadata && Object.keys(metadata).length === 1) {
-            Util.logger.debug(
-                'Only 1 user found. Skipping documentation, assuming we ran retrieve-by-key.'
-            );
-            return;
-        }
-
         if (!metadata) {
             // load users from disk if document was called directly and not part of a retrieve
             try {

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

@@ -3,8 +3,8 @@ module.exports = {
     dependencies: ['mobileCode'],
     hasExtended: false,
     idField: 'id',
-    keyIsFixed: false,
-    keyField: 'keyword',
+    keyIsFixed: false, // custom field but mapped to normal fields
+    keyField: 'c__codeKeyword',
     nameField: 'keyword',
     createdDateField: 'createdDate',
     createdNameField: 'createdBy.name',
@@ -21,14 +21,20 @@ module.exports = {
             // irregular format: NXV4ZFMwTEFwRVczd3RaLUF5X3p5dzo4Njow
             isCreateable: false,
             isUpdateable: true,
-            retrieving: true,
+            retrieving: false,
             template: false,
         },
+        c__codeKeyword: {
+            isCreateable: false,
+            isUpdateable: false,
+            retrieving: true,
+            template: true,
+        },
         keyword: {
             isCreateable: true,
             isUpdateable: true,
-            retrieving: true,
-            template: true,
+            retrieving: false,
+            template: false,
         },
         createdDate: {
             isCreateable: false,
@@ -133,11 +139,17 @@ module.exports = {
             retrieving: true,
             template: false,
         },
+        code: {
+            isCreateable: true,
+            isUpdateable: true,
+            retrieving: false,
+            template: false,
+        },
         'code.code': {
             isCreateable: false,
             isUpdateable: false,
-            retrieving: true,
-            template: true,
+            retrieving: false,
+            template: false,
         },
         'code.id': {
             isCreateable: true,

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

@@ -316,6 +316,12 @@ module.exports = {
         'keyword.keyword': {
             isCreateable: true,
             isUpdateable: true,
+            retrieving: false,
+            template: false,
+        },
+        'keyword.c__codeKeyword': {
+            isCreateable: false,
+            isUpdateable: false,
             retrieving: true,
             template: true,
         },
@@ -620,27 +626,63 @@ module.exports = {
         'subscriptionKeyword.id': {
             isCreatable: true,
             isUpdatable: true,
-            retrieving: true,
-            template: true,
+            retrieving: false,
+            template: false,
         },
         'subscriptionKeyword.keyword': {
-            isCreatable: true,
-            isUpdatable: true,
+            isCreatable: false,
+            isUpdatable: false,
+            retrieving: false,
+            template: false,
+        },
+        'subscriptionKeyword.c__codeKeyword': {
+            isCreateable: false,
+            isUpdateable: false,
             retrieving: true,
             template: true,
         },
         'subscriptionKeyword.restriction': {
-            isCreatable: true,
-            isUpdatable: true,
-            retrieving: true,
-            template: true,
+            isCreatable: false,
+            isUpdatable: false,
+            retrieving: false,
+            template: false,
         },
         'subscriptionKeyword.isInherited': {
+            isCreatable: false,
+            isUpdatable: false,
+            retrieving: false,
+            template: false,
+        },
+        'nextKeyword.id': {
             isCreatable: true,
             isUpdatable: true,
+            retrieving: false,
+            template: false,
+        },
+        'nextKeyword.keyword': {
+            isCreatable: false,
+            isUpdatable: false,
+            retrieving: false,
+            template: false,
+        },
+        'nextKeyword.c__codeKeyword': {
+            isCreateable: false,
+            isUpdateable: false,
             retrieving: true,
             template: true,
         },
+        'nextKeyword.restriction': {
+            isCreatable: false,
+            isUpdatable: false,
+            retrieving: false,
+            template: false,
+        },
+        'nextKeyword.isInherited': {
+            isCreatable: false,
+            isUpdatable: false,
+            retrieving: false,
+            template: false,
+        },
         subscriberResponseMessage: {
             isCreatable: true,
             isUpdatable: true,

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

@@ -17,6 +17,7 @@ module.exports = {
     typeDescription: 'Marketing Cloud users',
     typeName: 'User',
     typeRetrieveByDefault: false,
+    documentInOneFile: true,
     stringifyFieldsBeforeTemplate: ['DefaultBusinessUnit', 'c__AssociatedBusinessUnits'],
     fields: {
         AccountUserID: {
@@ -196,19 +197,19 @@ module.exports = {
             retrieving: false, // retrieve not supported by API
             template: false,
         },
-        'SsoIdentities[]': {
+        'SsoIdentities.SsoIdentity': {
             isCreateable: true,
             isUpdateable: true,
-            retrieving: false,
+            retrieving: false, // retrieve not supported by API
             template: false,
         },
-        'SsoIdentities[].IsActive': {
+        'SsoIdentities.SsoIdentity[].IsActive': {
             isCreateable: true,
             isUpdateable: true,
             retrieving: false,
             template: false,
         },
-        'SsoIdentities[].FederatedID': {
+        'SsoIdentities.SsoIdentity[].FederatedID': {
             isCreateable: true,
             isUpdateable: true,
             retrieving: false,

package/lib/util/auth.js

@@ -129,7 +129,19 @@ function setupSDK(sessionKey, authObject) {
                 if (Util.OPTIONS.api === 'cli') {
                     console.log(`${Util.color.fgMagenta}API REQUEST >>${Util.color.reset}`, msg); // eslint-disable-line no-console
                 } else if (Util.OPTIONS.api === 'log') {
+                    let data;
+                    if (msg.data) {
+                        data = msg.data;
+                        delete msg.data;
+                    }
                     Util.logger.debug('API REQUEST >> ' + JSON.stringify(msg, null, 2));
+                    if (data) {
+                        // printing it separately leads to better formatting
+                        Util.logger.debug(
+                            'API REQUEST body >> \n  ' +
+                                (typeof data === 'string' ? data : JSON.stringify(data, null, 2))
+                        );
+                    }
                 }
             },
             logResponse: (res) => {
@@ -138,7 +150,7 @@ function setupSDK(sessionKey, authObject) {
                 if (Util.OPTIONS.api === 'cli') {
                     console.log(`${Util.color.fgMagenta}API RESPONSE <<${Util.color.reset}`, msg); // eslint-disable-line no-console
                 } else if (Util.OPTIONS.api === 'log') {
-                    Util.logger.debug('API RESPONSE << ' + msg);
+                    Util.logger.debug('API RESPONSE body << \n  ' + msg);
                 }
             },
         },

package/lib/util/cli.js

@@ -570,7 +570,7 @@ const Cli = {
         }
         if (Util.OPTIONS.json) {
             if (Util.OPTIONS.loggerLevel !== 'error') {
-                console.log(json); // eslint-disable-line no-console
+                console.log(JSON.stringify(json, null, 2)); // eslint-disable-line no-console
             }
             return json;
         }

package/lib/util/file.js

@@ -517,9 +517,10 @@ const File = {
      * @param {string} [filetype='html'] filetype ie. JSON or SSJS
      * @returns {Promise.<boolean>} success of config load
      */
-    async initPrettier(filetype) {
-        if (FileFs.prettierConfig === null) {
-            filetype ||= 'html';
+    async initPrettier(filetype = 'html') {
+        if (FileFs.prettierConfig === null || FileFs.prettierConfigFileType !== filetype) {
+            // run this if no config was yet found or if the filetype previously used to initialize it differs (because it results in a potentially different config!)
+            FileFs.prettierConfigFileType = filetype;
             try {
                 // pass in project dir with fake index.html to avoid "no parser" error
                 // by using process.cwd we are limiting ourselves to a config in the project root
@@ -547,5 +548,6 @@ const File = {
 };
 const FileFs = { ...fs, ...File };
 FileFs.prettierConfig = null;
+FileFs.prettierConfigFileType = null;
 
 module.exports = FileFs;