mcdev 4.1.11 → 4.2.0

package/lib/metadataTypes/TransactionalMessage.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const TYPE = require('../../types/mcdev.d');
+const MetadataType = require('./MetadataType');
+const Util = require('../util/util');
+
+/**
+ * TransactionalMessage MetadataType
+ *
+ * @augments MetadataType
+ */
+class TransactionalMessage extends MetadataType {
+    // define this.subType as string here for intellisense; requires to be redefined in child class
+    static subType;
+    /**
+     * Retrieves Metadata of Mobile Keywords
+     * Endpoint /legacy/v1/beta/mobile/code/ return all Mobile Codes with all details.
+     *
+     * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
+     * @param {void} [_] unused parameter
+     * @param {void} [__] unused parameter
+     * @param {void} [___] unused parameter
+     * @param {string} [key] customer key of single item to retrieve
+     * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise of metadata
+     */
+    static async retrieve(retrieveDir, _, __, ___, key) {
+        let keyList;
+        const baseUri = '/messaging/v1/' + this.subType + '/definitions/';
+        if (key) {
+            // Retrieve single
+            keyList = [key];
+        } else {
+            // Retrieve all
+            const response = this.definition.restPagination
+                ? await this.client.rest.getBulk(baseUri)
+                : await this.client.rest.get(baseUri);
+            const parsed = this.parseResponseBody(response);
+            keyList = Object.keys(parsed).filter((item) => parsed[item].status !== 'Deleted');
+            const filteredCount = Object.keys(parsed).length - keyList.length;
+            if (filteredCount) {
+                Util.logger.info(
+                    ` - Filtered ${this.definition.type} with status 'deleted': ${filteredCount} (downloaded but not saved to disk)`
+                );
+            }
+        }
+
+        // get all sms with additional details not given by the list endpoint
+        const details = (
+            await Promise.all(
+                keyList.map(async (key) => {
+                    try {
+                        return await this.client.rest.get(baseUri + (key || ''));
+                    } catch {
+                        return null;
+                    }
+                })
+            )
+        ).filter(Boolean);
+        const parsed = this.parseResponseBody({ definitions: details });
+
+        // * retrieveDir is mandatory in this method as it is not used for caching (there is a seperate method for that)
+        const savedMetadata = await this.saveResults(parsed, retrieveDir, null, null);
+        // defined colors for optionally printing the keys we filtered by
+        const color = {
+            reset: '\x1B[0m',
+            dim: '\x1B[2m',
+        };
+        Util.logger.info(
+            `Downloaded: ${this.definition.type} (${Object.keys(savedMetadata).length})` +
+                (key === null ? '' : ` ${color.dim}(Key: ${key})${color.reset}`)
+        );
+
+        return { metadata: savedMetadata, type: this.definition.type };
+    }
+
+    /**
+     * Retrieves event definition metadata for caching
+     *
+     * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise of metadata
+     */
+    static retrieveForCache() {
+        return super.retrieveREST(null, '/messaging/v1/' + this.subType + '/definitions/');
+    }
+    /**
+     * Updates a single item
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {Promise} Promise
+     */
+    static update(metadata) {
+        return super.updateREST(
+            metadata,
+            '/messaging/v1/' + this.subType + '/definitions/' + metadata[this.definition.keyField]
+        );
+    }
+
+    /**
+     * Creates a single item
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {Promise} Promise
+     */
+    static create(metadata) {
+        return super.createREST(metadata, '/messaging/v1/' + this.subType + '/definitions');
+    }
+    /**
+     * Delete a metadata item from the specified business unit
+     *
+     * @param {TYPE.BuObject} buObject references credentials
+     * @param {string} key Identifier of item
+     * @returns {Promise.<boolean>} deletion success status
+     */
+    static deleteByKey(buObject, key) {
+        return super.deleteByKeyREST(
+            buObject,
+            '/messaging/v1/' + this.subType + '/definitions/' + key,
+            key,
+            false
+        );
+    }
+}
+
+// Assign definition to static attributes
+// ! using SMS definitions here as placeholder to have auto completion
+TransactionalMessage.definition = require('../MetadataTypeDefinitions').transactionalSMS;
+
+module.exports = TransactionalMessage;

package/lib/metadataTypes/TransactionalPush.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const TYPE = require('../../types/mcdev.d');
+const TransactionalMessage = require('./TransactionalMessage');
+const Util = require('../util/util');
+const cache = require('../util/cache');
+
+/**
+ * TransactionalPush TransactionalMessage
+ *
+ * @augments TransactionalMessage
+ */
+class TransactionalPush extends TransactionalMessage {
+    static subType = 'push';
+
+    /**
+     * prepares for deployment
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {TYPE.MetadataTypeItem} Promise
+     */
+    static async preDeployTasks(metadata) {
+        // asset
+        if (metadata.content?.customerKey) {
+            // we merely want to be able to show an error if it does not exist
+            cache.searchForField(
+                'asset',
+                metadata.content.customerKey,
+                'customerKey',
+                'customerKey'
+            );
+        }
+        if (metadata.options?.badge && typeof metadata.options?.badge !== 'string') {
+            // ensure it's a string, or else the API will return an error. Our SDK turns numbers in strings into actual numbers
+            metadata.options.badge += '';
+        }
+
+        return metadata;
+    }
+    /**
+     * manages post retrieve steps
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {TYPE.MetadataTypeItem} a single item
+     */
+    static postRetrieveTasks(metadata) {
+        // asset
+        if (metadata.content?.customerKey) {
+            try {
+                // we merely want to be able to show an error if it does not exist
+                cache.searchForField(
+                    'asset',
+                    metadata.content.customerKey,
+                    'customerKey',
+                    'customerKey'
+                );
+            } catch (ex) {
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): ${ex.message}.`
+                );
+            }
+        }
+        if (metadata.options?.badge && typeof metadata.options?.badge !== 'string') {
+            // ensure it's a string, or else the API will return an error. Our SDK turns numbers in strings into actual numbers
+            metadata.options.badge += '';
+        }
+
+        return metadata;
+    }
+}
+
+// Assign definition to static attributes
+TransactionalPush.definition = require('../MetadataTypeDefinitions').transactionalPush;
+
+module.exports = TransactionalPush;

package/lib/metadataTypes/TransactionalSMS.js

@@ -0,0 +1,354 @@
+'use strict';
+
+const TYPE = require('../../types/mcdev.d');
+const TransactionalMessage = require('./TransactionalMessage');
+const Util = require('../util/util');
+const File = require('../util/file');
+const beautifier = require('beauty-amp-core');
+const cache = require('../util/cache');
+
+/**
+ * TransactionalSMS MetadataType
+ *
+ * @augments TransactionalMessage
+ */
+class TransactionalSMS extends TransactionalMessage {
+    static subType = 'sms';
+    /**
+     * clean up after deleting a metadata item
+     *
+     * @param {TYPE.BuObject} buObject references credentials
+     * @param {string} customerKey Identifier of metadata item
+     * @returns {void}
+     */
+    static async postDeleteTasks(buObject, customerKey) {
+        // delete local copy: retrieve/cred/bu/type/...json
+        const fileName = File.normalizePath([
+            this.properties.directories.retrieve,
+            buObject.credential,
+            buObject.businessUnit,
+            this.definition.type,
+            `${customerKey}.${this.definition.type}-meta.`,
+        ]);
+        await File.remove(fileName + 'json');
+        await File.remove(fileName + 'amp');
+    }
+
+    /**
+     * prepares for deployment
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @param {string} dir directory of deploy files
+     * @returns {TYPE.MetadataTypeItem} Promise
+     */
+    static async preDeployTasks(metadata, dir) {
+        // code
+        metadata.content = {
+            message: await this._mergeCode(metadata, dir),
+        };
+
+        if (this._isHTML(metadata.content?.message)) {
+            // keep this as a non-blocking warning because the test not 100% accurate
+            Util.logger.warn(
+                ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                    metadata[this.definition.keyField]
+                }): HTML detected`
+            );
+        }
+
+        // subscriptions: mobileCode
+        if (metadata.subscriptions?.shortCode) {
+            // we merely want to be able to show an error if it does not exist
+            cache.searchForField('mobileCode', metadata.subscriptions.shortCode, 'code', 'code');
+        }
+        // subscriptions: mobileKeyword
+        if (metadata.subscriptions?.keyword) {
+            // we merely want to be able to show an error if it does not exist
+            cache.searchForField(
+                'mobileKeyword',
+                metadata.subscriptions.keyword,
+                'keyword',
+                'keyword'
+            );
+        }
+        return metadata;
+    }
+    /**
+     * helper for {@link preDeployTasks} that loads extracted code content back into JSON
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single definition
+     * @param {string} deployDir directory of deploy files
+     * @param {string} [templateName] name of the template used to built defintion (prior applying templating)
+     * @returns {Promise.<string>} content for metadata.script
+     */
+    static async _mergeCode(metadata, deployDir, templateName) {
+        templateName = templateName || metadata[this.definition.keyField];
+        const codePath = File.normalizePath([
+            deployDir,
+            this.definition.type,
+            templateName + '.' + this.definition.type + '-meta',
+        ]);
+
+        if (await File.pathExists(codePath + '.amp')) {
+            return await File.readFilteredFilename(
+                [deployDir, this.definition.type],
+                templateName + '.' + this.definition.type + '-meta',
+                'amp'
+            );
+        } else {
+            throw new Error(`Could not find ${codePath}.amp`);
+        }
+    }
+    /**
+     * manages post retrieve steps
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {TYPE.CodeExtractItem} Array with one metadata object and one ssjs string
+     */
+    static postRetrieveTasks(metadata) {
+        // extract message body
+        const codeArr = [];
+        // keep between tags
+        const { fileExt, code } = this.prepExtractedCode(metadata.content?.message);
+        delete metadata.content;
+        codeArr.push({
+            subFolder: null,
+            fileName: metadata[this.definition.keyField],
+            fileExt: fileExt,
+            content: code,
+        });
+
+        if (this._isHTML(code)) {
+            Util.logger.warn(
+                ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                    metadata[this.definition.keyField]
+                }): HTML detected`
+            );
+        }
+
+        // subscriptions: mobileCode
+        if (metadata.subscriptions?.shortCode) {
+            try {
+                // we merely want to be able to show a warning if it does not exist
+                cache.searchForField(
+                    'mobileCode',
+                    metadata.subscriptions.shortCode,
+                    'code',
+                    'code'
+                );
+            } catch {
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): Could not find mobileCode ${metadata.subscriptions.shortCode}.`
+                );
+            }
+        }
+        // subscriptions: mobileKeyword
+        if (metadata.subscriptions?.keyword) {
+            try {
+                // we merely want to be able to show a warning if it does not exist
+                cache.searchForField(
+                    'mobileKeyword',
+                    metadata.subscriptions.keyword,
+                    'keyword',
+                    'keyword'
+                );
+            } catch {
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): Could not find mobileKeyword ${metadata.subscriptions.keyword}.`
+                );
+            }
+        }
+
+        return { json: metadata, codeArr: codeArr, subFolder: null };
+    }
+    /**
+     * helper for {@link parseMetadata} and {@link _buildForNested}
+     *
+     * @param {string} metadataScript the code of the file
+     * @returns {{fileExt:string,code:string}} returns found extension and file content
+     */
+    static prepExtractedCode(metadataScript) {
+        // immutable at the moment:
+        const ampscript = {
+            capitalizeAndOrNot: true,
+            capitalizeIfFor: true,
+            capitalizeSet: true,
+            capitalizeVar: true,
+            maxParametersPerLine: 4,
+        };
+        // immutable at the moment:
+        const editor = {
+            insertSpaces: true,
+            tabSize: 4,
+        };
+        // logs trough console only for the moment.
+        const logs = {
+            loggerOn: false, // <= disable logging
+        };
+
+        beautifier.setup(ampscript, editor, logs);
+        const code = beautifier.beautify(metadataScript);
+        const fileExt = 'amp';
+
+        return { fileExt, code };
+    }
+    /**
+     * helper for {@link MetadataType.buildDefinition}
+     * handles extracted code if any are found for complex types
+     *
+     * @param {string} templateDir Directory where metadata templates are stored
+     * @param {string|string[]} targetDir (List of) Directory where built definitions will be saved
+     * @param {TYPE.MetadataTypeItem} metadata main JSON file that was read from file system
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {string} templateName name of the template to be built
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
+     */
+    static buildDefinitionForNested(
+        templateDir,
+        targetDir,
+        metadata,
+        templateVariables,
+        templateName
+    ) {
+        return this._buildForNested(
+            templateDir,
+            targetDir,
+            metadata,
+            templateVariables,
+            templateName,
+            'definition'
+        );
+    }
+    /**
+     * helper for {@link MetadataType.buildTemplate}
+     * handles extracted code if any are found for complex types
+     *
+     * @example scripts are saved as 1 json and 1 ssjs file. both files need to be run through templating
+     * @param {string} templateDir Directory where metadata templates are stored
+     * @param {string|string[]} targetDir (List of) Directory where built definitions will be saved
+     * @param {TYPE.MetadataTypeItem} metadata main JSON file that was read from file system
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {string} templateName name of the template to be built
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
+     */
+    static buildTemplateForNested(
+        templateDir,
+        targetDir,
+        metadata,
+        templateVariables,
+        templateName
+    ) {
+        return this._buildForNested(
+            templateDir,
+            targetDir,
+            metadata,
+            templateVariables,
+            templateName,
+            'template'
+        );
+    }
+
+    /**
+     * helper for {@link buildTemplateForNested} / {@link buildDefinitionForNested}
+     * handles extracted code if any are found for complex types
+     *
+     * @param {string} templateDir Directory where metadata templates are stored
+     * @param {string|string[]} targetDir (List of) Directory where built definitions will be saved
+     * @param {TYPE.MetadataTypeItem} metadata main JSON file that was read from file system
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {string} templateName name of the template to be built
+     * @param {'definition'|'template'} mode defines what we use this helper for
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
+     */
+    static async _buildForNested(
+        templateDir,
+        targetDir,
+        metadata,
+        templateVariables,
+        templateName,
+        mode
+    ) {
+        // get code from filesystem
+        let code = await this._mergeCode(metadata, templateDir, templateName);
+        const file = this.prepExtractedCode(code, metadata.name);
+        const fileExt = file.fileExt;
+        code = file.code;
+        // apply templating
+        try {
+            if (mode === 'definition') {
+                // replace template variables with their values
+                code = this.applyTemplateValues(code, templateVariables);
+            } else if (mode === 'template') {
+                // replace template values with corresponding variable names
+                code = this.applyTemplateNames(code, templateVariables);
+            }
+        } catch {
+            throw new Error(
+                `${this.definition.type}:: Error applying template variables on ${
+                    templateName + '.' + this.definition.type
+                }-meta.${fileExt}.`
+            );
+        }
+
+        // write to file
+        const targetDirArr = Array.isArray(targetDir) ? targetDir : [targetDir];
+        const nestedFilePaths = [];
+
+        // keep old name if creating templates, otherwise use new name
+        const fileName = mode === 'definition' ? metadata[this.definition.keyField] : templateName;
+
+        for (const targetDir of targetDirArr) {
+            File.writeToFile(
+                [targetDir, this.definition.type],
+                fileName + '.' + this.definition.type + '-meta',
+                fileExt,
+                code
+            );
+            nestedFilePaths.push([
+                targetDir,
+                this.definition.type,
+                fileName + '.' + this.definition.type + '-meta.' + fileExt,
+            ]);
+        }
+        return nestedFilePaths;
+    }
+    /**
+     * very simplified test for HTML code in our SMS
+     *
+     * @param {string} code sms source code
+     * @returns {boolean} true if HTML is found
+     */
+    static _isHTML(code) {
+        return /(<([^>]+)>)/gi.test(code);
+    }
+    /**
+     * should return only the json for all but asset, query and script that are saved as multiple files
+     * additionally, the documentation for dataExtension and automation should be returned
+     *
+     * @param {string[]} keyArr customerkey of the metadata
+     * @returns {string[]} list of all files that need to be committed in a flat array ['path/file1.ext', 'path/file2.ext']
+     */
+    static getFilesToCommit(keyArr) {
+        const path = File.normalizePath([
+            this.properties.directories.retrieve,
+            this.buObject.credential,
+            this.buObject.businessUnit,
+            this.definition.type,
+        ]);
+
+        const fileList = keyArr.flatMap((key) => [
+            File.normalizePath([path, `${key}.${this.definition.type}-meta.json`]),
+            File.normalizePath([path, `${key}.${this.definition.type}-meta.amp`]),
+        ]);
+        return fileList;
+    }
+}
+
+// Assign definition to static attributes
+TransactionalSMS.definition = require('../MetadataTypeDefinitions').transactionalSMS;
+
+module.exports = TransactionalSMS;

package/lib/metadataTypes/TriggeredSendDefinition.js

@@ -169,14 +169,16 @@ class TriggeredSendDefinition extends MetadataType {
                 );
             }
         }
-        // List
-        try {
-            metadata.r__list_PathName = cache.getListPathName(metadata.List.ID, 'ID');
-            delete metadata.List;
-        } catch (ex) {
-            Util.logger.warn(
-                ` - ${this.definition.typeName} '${metadata.Name}'/'${metadata.CustomerKey}': ${ex.message}`
-            );
+        // List (optional)
+        if (metadata.List) {
+            try {
+                metadata.r__list_PathName = cache.getListPathName(metadata.List.ID, 'ID');
+                delete metadata.List;
+            } catch (ex) {
+                Util.logger.warn(
+                    ` - ${this.definition.typeName} '${metadata.Name}'/'${metadata.CustomerKey}': ${ex.message}`
+                );
+            }
         }
 
         return metadata;
@@ -227,7 +229,7 @@ class TriggeredSendDefinition extends MetadataType {
                 `r__assetMessage_Key / r__email_Name not defined but instead found Email.ID. Please try re-retrieving this TSD from your BU.`
             );
         }
-        // get List
+        // get List (optional)
         if (metadata.r__list_PathName) {
             metadata.List = {
                 ID: cache.getListObjectId(metadata.r__list_PathName, 'ID'),