mcdev 3.1.1 → 4.0.0

package/lib/Retriever.js

@@ -1,8 +1,11 @@
 'use strict';
 
+const TYPE = require('../types/mcdev.d');
 const MetadataTypeInfo = require('./MetadataTypeInfo');
 const Util = require('./util/util');
 const File = require('./util/file');
+const cache = require('./util/cache');
+const auth = require('./util/auth');
 /**
  * Retrieves metadata from a business unit and saves it to the local filesystem.
  */
@@ -10,20 +13,11 @@ class Retriever {
     /**
      * Creates a Retriever, uses v2 auth if v2AuthOptions are passed.
      *
-     * @param {Object} properties General configuration to be used in retrieve
-     * @param {Object} properties.directories Directories to be used when interacting with FS
-     * @param {Object} buObject properties for auth
-     * @param {String} buObject.clientId clientId for FuelSDK auth
-     * @param {String} buObject.clientSecret clientSecret for FuelSDK auth
-     * @param {Object} buObject.credential clientId for FuelSDK auth
-     * @param {String} buObject.tenant v2 Auth Tenant Information
-     * @param {String} [buObject.mid] ID of Business Unit to authenticate with
-     * @param {String} [buObject.businessUnit] name of Business Unit to authenticate with
-     * @param {Util.ET_Client} client fuel client
+     * @param {TYPE.Mcdevrc} properties General configuration to be used in retrieve
+     * @param {TYPE.BuObject} buObject properties for auth
      */
-    constructor(properties, buObject, client) {
+    constructor(properties, buObject) {
         this.buObject = buObject;
-        this.client = client;
         this.properties = properties;
         this.retrieveDir = properties.directories.retrieve;
         this.templateDir = properties.directories.template;
@@ -32,109 +26,92 @@ class Retriever {
             buObject.credential,
             buObject.businessUnit,
         ]);
-        this.metadata = {};
     }
 
     /**
      * Retrieve metadata of specified types into local file system and Retriever.metadata
-     * @param {String[]} metadataTypes String list of metadata types to retrieve
-     * @param {String} [name] name of Metadata to retrieve (in case of templating)
-     * @param {Object} [templateVariables] Object of values which can be replaced (in case of templating)
+     *
+     * @param {string[]} metadataTypes String list of metadata types to retrieve
+     * @param {string[]} [namesOrKeys] name of Metadata to retrieveAsTemplate or list of keys for normal retrieval
+     * @param {TYPE.TemplateMap} [templateVariables] Object of values which can be replaced (in case of templating)
      * @param {boolean} [changelogOnly] skip saving, only create json in memory
-     * @returns {Promise<Object<string,Object>>} Promise
+     * @returns {Promise.<TYPE.MultiMetadataTypeList>} Promise of a list of retrieved items grouped by type {automation:[...], query:[...]}
      */
-    async retrieve(metadataTypes, name, templateVariables, changelogOnly) {
+    async retrieve(metadataTypes, namesOrKeys, templateVariables, changelogOnly) {
+        /**
+         * @type {TYPE.MultiMetadataTypeList}
+         */
         const retrieveChangelog = {};
+        if (!namesOrKeys || !namesOrKeys.length) {
+            // make iterating over namesOrKeys easier
+            namesOrKeys = [null];
+        }
         for (const metadataType of Util.getMetadataHierachy(metadataTypes)) {
-            let result;
             const [type, subType] = metadataType.split('-');
-            // add metadata & client to metadata process class instead of passing cache/mapping every time
-            MetadataTypeInfo[type].cache = this.metadata;
-            MetadataTypeInfo[type].client = this.client;
+            // add client to metadata process class instead of passing every time
+            MetadataTypeInfo[type].client = auth.getSDK(this.buObject);
             MetadataTypeInfo[type].properties = this.properties;
-
+            MetadataTypeInfo[type].buObject = this.buObject;
             try {
+                let result;
                 if (!metadataTypes.includes(type) && !metadataTypes.includes(metadataType)) {
                     if (changelogOnly) {
                         // no extra caching needed for list view
                         continue;
                     }
                     Util.logger.info(`Caching dependent Metadata: ${metadataType}`);
-                    await Util.retryOnError(
-                        `Retrying to cache ${metadataType}`,
-                        async () => {
-                            result = await MetadataTypeInfo[type].retrieveForCache(
-                                this.buObject,
-                                subType
-                            );
-                        },
-                        false
-                    );
+                    result = await MetadataTypeInfo[type].retrieveForCache(this.buObject, subType);
                 } else if (templateVariables) {
                     Util.logger.info(`Retrieving as Template: ${metadataType}`);
-                    let nameArr;
-                    if (name.includes(',')) {
-                        nameArr = name.split(',').map((item) =>
-                            // allow whitespace in comma-separated lists
-                            item.trim()
-                        );
-                    } else {
-                        nameArr = [name.trim()];
-                    }
-                    await Util.retryOnError(`Retrying ${metadataType}`, async () => {
-                        result = await Promise.all(
-                            nameArr.map((name) => {
-                                // with npx and powershell spaces are not parsed correctly as part of a string
-                                // we hence require users to put %20 in their stead and have to convert that back
-                                name = name.split('%20').join(' ');
 
-                                return MetadataTypeInfo[type].retrieveAsTemplate(
-                                    this.templateDir,
-                                    name,
-                                    templateVariables,
-                                    subType
-                                );
-                            })
-                        );
-                    });
+                    result = await Promise.all(
+                        namesOrKeys.map((name) =>
+                            MetadataTypeInfo[type].retrieveAsTemplate(
+                                this.templateDir,
+                                name,
+                                templateVariables,
+                                subType
+                            )
+                        )
+                    );
                 } else {
                     Util.logger.info('Retrieving: ' + metadataType);
-                    if (changelogOnly) {
-                        await Util.retryOnError(`Retrying ${metadataType}`, async () => {
-                            result = await MetadataTypeInfo[type].retrieveChangelog(
-                                null,
-                                this.buObject,
-                                subType
-                            );
-                        });
-                    } else {
-                        await Util.retryOnError(`Retrying ${metadataType}`, async () => {
-                            result = await MetadataTypeInfo[type].retrieve(
-                                this.savePath,
-                                null,
-                                this.buObject,
-                                subType
-                            );
-                        });
-                    }
+                    result = await (changelogOnly
+                        ? MetadataTypeInfo[type].retrieveChangelog(this.buObject, null, subType)
+                        : Promise.all(
+                              namesOrKeys.map((key) =>
+                                  MetadataTypeInfo[type].retrieve(
+                                      this.savePath,
+                                      null,
+                                      this.buObject,
+                                      subType,
+                                      key
+                                  )
+                              )
+                          ));
                 }
                 if (result) {
-                    if (templateVariables && Array.isArray(result)) {
-                        // so far we are only doing this for templates, hence the above if-check
-                        this.metadata[type] = result.map((element) => element.metadata);
+                    if (Array.isArray(result)) {
+                        cache.setMetadata(
+                            type,
+                            result.filter((el) => !!el).map((element) => element.metadata)[0]
+                        );
+                        if (metadataTypes.includes(type) || metadataTypes.includes(metadataType)) {
+                            retrieveChangelog[type] = result
+                                .filter((el) => !!el)
+                                .map((element) => element.metadata);
+                        }
                     } else {
-                        this.metadata[type] = result.metadata;
+                        cache.setMetadata(type, result.metadata);
                         if (metadataTypes.includes(type) || metadataTypes.includes(metadataType)) {
                             retrieveChangelog[type] = result.metadata;
                         }
                     }
                 }
             } catch (ex) {
-                Util.logger.error(`Retriever.retrieve:: Retrieving ${metadataType} failed`);
-                Util.logger.debug(ex.stack);
-                if (Util.logger.level === 'debug') {
-                    console.log(ex.stack);
-                }
+                Util.logger.errorStack(ex, `Retrieving ${metadataType} failed`);
+                // do not continue retrieving if one type failed. simply skip processing the rest of the for-loop
+                break;
             }
         }
         return retrieveChangelog;

package/lib/cli.js

@@ -13,7 +13,7 @@ yargs
     .scriptName('mcdev')
     .usage('$0 <command> [options]')
     .command({
-        command: 'retrieve [BU] [TYPE]',
+        command: 'retrieve [BU] [TYPE] [KEY]',
         aliases: ['r'],
         desc: 'retrieves metadata of a business unit',
         // @ts-ignore
@@ -27,15 +27,20 @@ yargs
                 .positional('TYPE', {
                     type: 'string',
                     describe: 'metadata type that shall be exclusively downloaded',
+                })
+                .positional('KEY', {
+                    type: 'string',
+                    describe: 'metadata keys that shall be exclusively downloaded',
                 });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
-            Mcdev.retrieve(argv.BU, argv.TYPE);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
+            Mcdev.retrieve(argv.BU, csvToArray(argv.TYPE), csvToArray(argv.KEY));
         },
     })
     .command({
-        command: 'deploy [BU] [TYPE]',
+        command: 'deploy [BU] [TYPE] [KEY] [fromRetrieve]',
         aliases: ['d'],
         desc: 'deploys local metadata to a business unit',
         builder: (yargs) => {
@@ -48,11 +53,20 @@ yargs
                 .positional('TYPE', {
                     type: 'string',
                     describe: 'metadata type that shall be exclusively uploaded',
+                })
+                .positional('KEY', {
+                    type: 'string',
+                    describe: 'metadata key that shall be exclusively uploaded',
+                })
+                .positional('fromRetrieve', {
+                    type: 'string',
+                    describe: 'optionally deploy from retrieve folder',
                 });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
-            Mcdev.deploy(argv.BU, argv.TYPE);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
+            Mcdev.deploy(argv.BU, csvToArray(argv.TYPE), csvToArray(argv.KEY), argv.fromRetrieve);
         },
     })
     .command({
@@ -65,7 +79,8 @@ yargs
             });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.initProject(argv.credentialsName, argv.skipInteraction);
         },
     })
@@ -80,7 +95,8 @@ yargs
             });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.findBUs(argv.credentialsName);
         },
     })
@@ -94,7 +110,8 @@ yargs
             });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.badKeys(argv.BU);
         },
     })
@@ -104,19 +121,20 @@ yargs
         desc: 'Creates Markdown or HTML documentation for the selected type',
         builder: (yargs) => {
             yargs
-                .positional('TYPE', {
+                .positional('BU', {
                     type: 'string',
                     describe:
-                        'metadata type to generate docs for; currently supported: dataExtension, role',
+                        'the business unit to generate docs for (in format "credential name/BU name")',
                 })
-                .positional('BU', {
+                .positional('TYPE', {
                     type: 'string',
                     describe:
-                        'the business unit to generate docs for (in format "credential name/BU name")',
+                        'metadata type to generate docs for; currently supported: dataExtension, role',
                 });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.document(argv.BU, argv.TYPE);
         },
     })
@@ -141,14 +159,15 @@ yargs
                 });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.deleteByKey(argv.BU, argv.TYPE, argv.EXTERNALKEY);
         },
     })
     .command({
         command: 'retrieveAsTemplate <BU> <TYPE> <NAME> <MARKET>',
         aliases: ['rt'],
-        desc: 'Retrieves a specific metadata file by name for templating',
+        desc: 'Retrieves a specific metadata file by name from the server for templating',
         builder: (yargs) => {
             yargs
                 .positional('BU', {
@@ -170,8 +189,41 @@ yargs
                 });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
-            Mcdev.retrieveAsTemplate(argv.BU, argv.TYPE, argv.NAME, argv.MARKET);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
+            Mcdev.retrieveAsTemplate(argv.BU, argv.TYPE, csvToArray(argv.NAME), argv.MARKET);
+        },
+    })
+    .command({
+        command: 'buildTemplate <BU> <TYPE> <KEY> <MARKET>',
+        aliases: ['bt'],
+        desc: 'builds a template out of a specific metadata file already in your retrieve folder',
+        builder: (yargs) => {
+            yargs
+                .positional('BU', {
+                    type: 'string',
+                    describe:
+                        'the business unit to deploy to (in format "credential name/BU name")',
+                })
+                .positional('TYPE', {
+                    type: 'string',
+                    describe: 'metadata type',
+                })
+                .positional('KEY', {
+                    type: 'string',
+                    describe: 'key(s) of the metadata component(s)',
+                })
+                .positional('MARKET', {
+                    type: 'string',
+                    describe: 'market used for reverse building template',
+                });
+        },
+        handler: (argv) => {
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
+            const keyArr = csvToArray(argv.KEY);
+
+            Mcdev.buildTemplate(argv.BU, argv.TYPE, keyArr, argv.MARKET);
         },
     })
     .command({
@@ -198,7 +250,8 @@ yargs
                 });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.buildDefinition(argv.BU, argv.TYPE, argv.NAME, argv.MARKET);
         },
     })
@@ -222,7 +275,8 @@ yargs
                 });
         },
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.buildDefinitionBulk(argv.LISTNAME, argv.TYPE, argv.NAME);
         },
     })
@@ -231,7 +285,8 @@ yargs
         aliases: ['st'],
         desc: 'lets you choose what metadata types to retrieve',
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.selectTypes();
         },
     })
@@ -240,7 +295,8 @@ yargs
         aliases: ['et'],
         desc: 'explains metadata types that can be retrieved',
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.explainTypes();
         },
     })
@@ -260,14 +316,47 @@ yargs
                         'Disable templating & instead filter by the specified file path (comma separated)',
                 });
         },
-        handler: Mcdev.createDeltaPkg,
+        handler: (argv) => {
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
+            Mcdev.createDeltaPkg(argv);
+        },
+    })
+    .command({
+        command: 'getFilesToCommit <BU> <TYPE> <KEY>',
+        aliases: ['fc'],
+        desc: 'returns a list of relative paths to files one needs to include in a commit',
+        builder: (yargs) => {
+            yargs
+                .positional('BU', {
+                    type: 'string',
+                    describe:
+                        'the business unit to deploy to (in format "credential name/BU name")',
+                })
+                .positional('TYPE', {
+                    type: 'string',
+                    describe: 'metadata type',
+                })
+                .positional('KEY', {
+                    type: 'string',
+                    describe: 'key(s) of the metadata component(s)',
+                });
+        },
+        handler: (argv) => {
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
+            const keyArr = csvToArray(argv.KEY);
+
+            Mcdev.getFilesToCommit(argv.BU, argv.TYPE, keyArr);
+        },
     })
     .command({
         command: 'upgrade',
         aliases: ['up'],
         desc: 'Add NPM dependencies and IDE configuration files to your project',
         handler: (argv) => {
-            Mcdev._setLoggingLevel(argv);
+            Mcdev.setSkipInteraction(argv.skipInteraction);
+            Mcdev.setLoggingLevel(argv);
             Mcdev.upgrade(argv.skipInteraction);
         },
     })
@@ -291,5 +380,24 @@ yargs
     .strict()
     .recommendCommands()
     .wrap(yargs.terminalWidth())
-    .epilog('Copyright 2021. Accenture.')
+    .epilog(
+        'Copyright 2022. Accenture. Get support at https://github.com/Accenture/sfmc-devtools/issues'
+    )
     .help().argv;
+
+/**
+ * helper to convert CSVs into an array. if only one value was given, it's also returned as an array
+ *
+ * @param {string} csv potentially comma-separated value or null
+ * @returns {string[]} values split into an array.
+ */
+function csvToArray(csv) {
+    return !csv
+        ? null
+        : csv.includes(',')
+        ? csv.split(',').map((item) =>
+              // allow whitespace in comma-separated lists
+              item.trim()
+          )
+        : [csv.trim()];
+}