mcdev 6.0.2 → 7.0.0

package/lib/metadataTypes/Asset.js

@@ -1,13 +1,31 @@
 'use strict';
 
 import MetadataType from './MetadataType.js';
-import TYPE from '../../types/mcdev.d.js';
 import { Util } from '../util/util.js';
 import File from '../util/file.js';
 import pLimit from 'p-limit';
 import cliProgress from 'cli-progress';
 import cache from '../util/cache.js';
 import TriggeredSend from './TriggeredSend.js';
+import Folder from './Folder.js';
+import ReplaceCbReference from '../util/replaceContentBlockReference.js';
+
+/**
+ * @typedef {import('../../types/mcdev.d.js').BuObject} BuObject
+ * @typedef {import('../../types/mcdev.d.js').CodeExtract} CodeExtract
+ * @typedef {import('../../types/mcdev.d.js').CodeExtractItem} CodeExtractItem
+ * @typedef {import('../../types/mcdev.d.js').MetadataTypeItem} MetadataTypeItem
+ * @typedef {import('../../types/mcdev.d.js').MetadataTypeItemDiff} MetadataTypeItemDiff
+ * @typedef {import('../../types/mcdev.d.js').MetadataTypeMap} MetadataTypeMap
+ * @typedef {import('../../types/mcdev.d.js').SoapRequestParams} SoapRequestParams
+ * @typedef {import('../../types/mcdev.d.js').TemplateMap} TemplateMap
+ */
+/**
+ * @typedef {import('../../types/mcdev.d.js').AssetSubType} AssetSubType
+ * @typedef {import('../../types/mcdev.d.js').AssetMap} AssetMap
+ * @typedef {import('../../types/mcdev.d.js').AssetItem} AssetItem
+ * @typedef {import('../../types/mcdev.d.js').AssetRequestParams} AssetRequestParams
+ */
 
 /**
  * FileTransfer MetadataType
@@ -19,13 +37,23 @@ class Asset extends MetadataType {
      * Retrieves Metadata of Asset
      *
      * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
-     * @param {void} _ -
-     * @param {TYPE.AssetSubType[]} [subTypeArr] optionally limit to a single subtype
+     * @param {void | string[]} _ unused parameter
+     * @param {string[]} [subTypeArr] optionally limit to a single AssetSubType
      * @param {string} [key] customer key
-     * @returns {Promise.<{metadata: TYPE.AssetMap, type: string}>} Promise
+     * @param {boolean} [loadShared] optionally retrieve assets from other BUs that were shared with the current
+     * @returns {Promise.<{metadata: AssetMap, type: string}>} Promise
      */
-    static async retrieve(retrieveDir, _, subTypeArr, key) {
+    static async retrieve(retrieveDir, _, subTypeArr, key, loadShared = false) {
         const items = [];
+        if (subTypeArr) {
+            // check if elements in subTypeArr exist in this.definition.subTypes
+            const invalidSubTypes = subTypeArr.filter(
+                (subType) => !this.definition.subTypes.includes(subType)
+            );
+            if (invalidSubTypes.length) {
+                throw new Error(`Invalid subType(s) found: ${invalidSubTypes.join(', ')}`);
+            }
+        }
         subTypeArr ||= this._getSubTypes();
         if (retrieveDir) {
             await File.initPrettier();
@@ -34,7 +62,7 @@ class Asset extends MetadataType {
         for (const subType of subTypeArr) {
             // each subtype contains multiple different specific types (images contains jpg and png for example)
             // we use await here to limit the risk of too many concurrent api requests at time
-            items.push(...(await this.requestSubType(subType, retrieveDir, null, null, key)));
+            items.push(...(await this.requestSubType(subType, retrieveDir, key, null, loadShared)));
         }
         const metadata = this.parseResponseBody({ items: items });
         if (retrieveDir) {
@@ -45,16 +73,55 @@ class Asset extends MetadataType {
         }
         return { metadata: metadata, type: this.definition.type };
     }
+    /**
+     * Helper for writing Metadata to disk, used for Retrieve and deploy
+     *
+     * @param {MetadataTypeMap} results metadata results from deploy
+     * @param {string} retrieveDir directory where metadata should be stored after deploy/retrieve
+     * @param {string} [overrideType] for use when there is a subtype (such as folder-queries)
+     * @param {TemplateMap} [templateVariables] variables to be replaced in the metadata
+     * @returns {Promise.<MetadataTypeMap>} Promise of saved metadata
+     */
+    static async saveResults(results, retrieveDir, overrideType, templateVariables) {
+        if (Object.keys(results).length) {
+            // only execute the following if records were found
+            await this._postRetrieveTasksBulk(results);
+        }
+        return super.saveResults(results, retrieveDir, overrideType, templateVariables);
+    }
+    /**
+     * helper for Journey's {@link Asset.saveResults}. Gets executed after retreive of metadata type and
+     *
+     * @param {MetadataTypeMap} metadataMap key=customer key, value=metadata
+     */
+    static async _postRetrieveTasksBulk(metadataMap) {
+        // Template-Based Email
+        let needTemplates = false;
+        for (const key in metadataMap) {
+            if (metadataMap[key].assetType.name == 'templatebasedemail') {
+                needTemplates = true;
+                break;
+            }
+        }
+
+        if (needTemplates && !cache.getCache()?.asset) {
+            // for
+            Util.logger.info(' - Caching dependent Metadata: asset-template');
+            const result = await this.retrieveForCache(undefined, ['template']);
+            cache.setMetadata('asset', result.metadata);
+        }
+    }
 
     /**
      * Retrieves asset metadata for caching
      *
-     * @param {void} _ unused
+     * @param {void | string[]} [_] parameter not used
      * @param {string[]} [subTypeArr] optionally limit to a single subtype
-     * @returns {Promise.<{metadata: TYPE.AssetMap, type: string}>} Promise
+     * @param {boolean} [loadShared] optionally retrieve assets from other BUs that were shared with the current
+     * @returns {Promise.<{metadata: AssetMap, type: string}>} Promise
      */
-    static retrieveForCache(_, subTypeArr) {
-        return this.retrieve(null, null, subTypeArr);
+    static retrieveForCache(_, subTypeArr, loadShared = false) {
+        return this.retrieve(null, null, subTypeArr, undefined, loadShared);
     }
 
     /**
@@ -62,9 +129,9 @@ class Asset extends MetadataType {
      *
      * @param {string} templateDir Directory where retrieved metadata directory will be saved
      * @param {string} name name of the metadata file
-     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
-     * @param {TYPE.AssetSubType} [selectedSubType] optionally limit to a single subtype
-     * @returns {Promise.<{metadata: TYPE.AssetItem, type: string}>} Promise
+     * @param {TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {AssetSubType} [selectedSubType] optionally limit to a single subtype
+     * @returns {Promise.<{metadata: AssetItem, type: string}>} Promise
      */
     static async retrieveAsTemplate(templateDir, name, templateVariables, selectedSubType) {
         const items = [];
@@ -75,7 +142,12 @@ class Asset extends MetadataType {
             // each subtype contains multiple different specific types (images contains jpg and png for example)
             // we use await here to limit the risk of too many concurrent api requests at time
             items.push(
-                ...(await this.requestSubType(subType, templateDir, name, templateVariables))
+                ...(await this.requestSubType(
+                    subType,
+                    templateDir,
+                    'name:' + name,
+                    templateVariables
+                ))
             );
         }
         const metadata = this.parseResponseBody({ items: items });
@@ -90,7 +162,7 @@ class Asset extends MetadataType {
      * helper for {@link Asset.retrieve} + {@link Asset.retrieveAsTemplate}
      *
      * @private
-     * @returns {TYPE.AssetSubType[]} subtype array
+     * @returns {string[]} AssetSubType array
      */
     static _getSubTypes() {
         const selectedSubTypeArr = this.properties.metaDataTypes.retrieve.filter((type) =>
@@ -112,7 +184,7 @@ class Asset extends MetadataType {
     /**
      * Creates a single asset
      *
-     * @param {TYPE.AssetItem} metadata a single asset
+     * @param {AssetItem} metadata a single asset
      * @returns {Promise} Promise
      */
     static create(metadata) {
@@ -124,7 +196,7 @@ class Asset extends MetadataType {
     /**
      * Updates a single asset
      *
-     * @param {TYPE.AssetItem} metadata a single asset
+     * @param {AssetItem} metadata a single asset
      * @returns {Promise} Promise
      */
     static update(metadata) {
@@ -134,25 +206,26 @@ class Asset extends MetadataType {
     /**
      * Retrieves Metadata of a specific asset type
      *
-     * @param {TYPE.AssetSubType} subType group of similar assets to put in a folder (ie. images)
+     * @param {string} subType group of similar assets to put in a folder (ie. images)
      * @param {string} [retrieveDir] target directory for saving assets
-     * @param {string} [templateName] name of the metadata file
-     * @param {TYPE.TemplateMap} [templateVariables] variables to be replaced in the metadata
-     * @param {string} key customer key to filter by
-     * @returns {Promise} Promise
+     * @param {string} [key] key/id/name to filter by
+     * @param {TemplateMap} [templateVariables] variables to be replaced in the metadata
+     * @param {boolean} [loadShared] optionally retrieve assets from other BUs that were shared with the current
+     * @returns {Promise.<object[]>} Promise
      */
-    static async requestSubType(subType, retrieveDir, templateName, templateVariables, key) {
+    static async requestSubType(subType, retrieveDir, key, templateVariables, loadShared = false) {
         if (retrieveDir) {
             Util.logger.info(`- Retrieving Subtype: ${subType}`);
         } else {
             Util.logger.info(` - Caching Subtype: ${subType}`);
         }
-        /** @type {TYPE.AssetSubType[]} */
+        /** @type {AssetSubType[]} */
         const extendedSubTypeArr = this.definition.extendedSubTypes[subType];
         const subtypeIds = extendedSubTypeArr?.map(
             (subTypeItemName) => Asset.definition.typeMapping[subTypeItemName]
         );
-        const uri = '/asset/v1/content/assets/query';
+        const uri = '/asset/v1/content/assets/query' + (loadShared ? '?scope=shared' : '');
+        /** @type {AssetRequestParams} */
         const payload = {
             page: {
                 page: 1,
@@ -162,7 +235,7 @@ class Asset extends MetadataType {
             fields: ['category', 'createdDate', 'createdBy', 'modifiedDate', 'modifiedBy'], // get folder to allow duplicate name check against cache
         };
 
-        if (templateName) {
+        if (key) {
             payload.query = {
                 leftOperand: {
                     property: 'assetType.id',
@@ -170,26 +243,26 @@ class Asset extends MetadataType {
                     value: subtypeIds,
                 },
                 logicalOperator: 'AND',
-                rightOperand: {
+            };
+            if (key.startsWith('id:')) {
+                payload.query.rightOperand = {
+                    property: this.definition.idField,
+                    simpleOperator: 'equal',
+                    value: key.slice(3),
+                };
+            } else if (key.startsWith('name:')) {
+                payload.query.rightOperand = {
                     property: this.definition.nameField,
                     simpleOperator: 'equal',
-                    value: templateName,
-                },
-            };
-        } else if (key) {
-            payload.query = {
-                leftOperand: {
-                    property: 'assetType.id',
-                    simpleOperator: 'in',
-                    value: subtypeIds,
-                },
-                logicalOperator: 'AND',
-                rightOperand: {
+                    value: key.slice(5),
+                };
+            } else {
+                payload.query.rightOperand = {
                     property: this.definition.keyField,
                     simpleOperator: 'equal',
                     value: key,
-                },
-            };
+                };
+            }
         } else {
             payload.query = {
                 property: 'assetType.id',
@@ -252,20 +325,21 @@ class Asset extends MetadataType {
         } while (moreResults);
 
         // only when we save results do we need the complete metadata or files. caching can skip these
-        if (retrieveDir && items.length > 0) {
-            for (const item of items) {
-                if (item.customerKey.trim() !== item.customerKey) {
-                    Util.logger.warn(
-                        `  - ${this.definition.type} ${item[this.definition.nameField]} (${
-                            item[this.definition.keyField]
-                        }) has leading or trailing spaces in customerKey. Please remove them in SFMC.`
-                    );
+        if (retrieveDir) {
+            if (items.length > 0) {
+                for (const item of items) {
+                    if (item.customerKey.trim() !== item.customerKey) {
+                        Util.logger.warn(
+                            `  - ${this.definition.type} ${item[this.definition.nameField]} (${
+                                item[this.definition.keyField]
+                            }) has leading or trailing spaces in customerKey. Please remove them in SFMC.`
+                        );
+                    }
                 }
+                // we have to wait on execution or it potentially causes memory reference issues when changing between BUs
+                await this.requestAndSaveExtended(items, subType, retrieveDir, templateVariables);
             }
-            // we have to wait on execution or it potentially causes memory reference issues when changing between BUs
-            await this.requestAndSaveExtended(items, subType, retrieveDir, templateVariables);
-            Util.logger.debug(`Downloaded asset-${subType}: ${items.length}`);
-        } else if (retrieveDir && !items.length) {
+            // always show the summary even if we already had the progress bar in the console
             Util.logger.info(`  Downloaded asset-${subType}: ${items.length}`);
         }
 
@@ -278,10 +352,10 @@ class Asset extends MetadataType {
      * Retrieves extended metadata (files or extended content) of asset
      *
      * @param {Array} items array of items to retrieve
-     * @param {TYPE.AssetSubType} subType group of similar assets to put in a folder (ie. images)
+     * @param {string} subType group of similar assets to put in a folder (ie. images)
      * @param {string} retrieveDir target directory for saving assets
-     * @param {TYPE.TemplateMap} [templateVariables] variables to be replaced in the metadata
-     * @returns {Promise} Promise
+     * @param {TemplateMap} [templateVariables] variables to be replaced in the metadata
+     * @returns {Promise.<MetadataTypeMap>} Promise
      */
     static async requestAndSaveExtended(items, subType, retrieveDir, templateVariables) {
         // disable CLI logs other than error while retrieving subtype
@@ -293,7 +367,7 @@ class Asset extends MetadataType {
         const extendedBar = new cliProgress.SingleBar(
             {
                 format:
-                    '                 Downloaded [{bar}] {percentage}% | {value}/{total} | asset-' +
+                    '                 Downloading [{bar}] {percentage}% | {value}/{total} | asset-' +
                     subType,
             },
             cliProgress.Presets.shades_classic
@@ -301,6 +375,8 @@ class Asset extends MetadataType {
 
         const completed = [];
         const failed = [];
+        const metadataMap = {};
+
         // put in do loop to manage issues with connection timeout
         do {
             // use promise execution limiting to avoid rate limits on api, but speed up execution
@@ -310,9 +386,8 @@ class Asset extends MetadataType {
                 const rateLimit = pLimit(5);
 
                 const promiseMap = await Promise.all(
-                    items.map((item) =>
+                    items.map((item, index) =>
                         rateLimit(async () => {
-                            const metadata = {};
                             // this is a file so extended is at another endpoint
                             if (item?.fileProperties?.extension && !completed.includes(item.id)) {
                                 try {
@@ -322,7 +397,7 @@ class Asset extends MetadataType {
                                     failed.push({ item: item, error: ex });
                                 }
                                 // even if the extended file failed, still save the metadata
-                                metadata[item.customerKey] = item;
+                                metadataMap[item.customerKey] = item;
                             }
                             // this is a complex type which stores data in the asset itself
                             else if (!completed.includes(item.id)) {
@@ -331,15 +406,17 @@ class Asset extends MetadataType {
                                         'asset/v1/content/assets/' + item.id
                                     );
                                     // only save the metadata if we have extended content
-                                    metadata[item.customerKey] = extendedItem;
+                                    metadataMap[item.customerKey] = extendedItem;
+                                    // overwrite the original item with the extended content to ensure retrieve() returns it
+                                    items[index] = extendedItem;
                                 } catch (ex) {
                                     failed.push({ item: item, error: ex });
                                 }
                             }
                             completed.push(item.id);
-                            if (metadata[item.customerKey]) {
+                            if (metadataMap[item.customerKey]) {
                                 await this.saveResults(
-                                    metadata,
+                                    metadataMap,
                                     retrieveDir,
                                     'asset-' + subType,
                                     templateVariables
@@ -364,6 +441,7 @@ class Asset extends MetadataType {
                 }
             }
         } while (completed.length === items.length);
+        return metadataMap;
     }
 
     /**
@@ -375,28 +453,26 @@ class Asset extends MetadataType {
      */
     static _resetLogLevel(loggerLevelBak, failed) {
         // re-enable CLI logs
-        if (loggerLevelBak !== 'error') {
-            // reset logging level
-            let obj;
-            switch (loggerLevelBak) {
-                case 'info': {
-                    obj = {};
-                    break;
-                }
-                case 'verbose': {
-                    obj = { verbose: true };
-                    break;
-                }
-                case 'debug': {
-                    obj = { debug: true };
-                    break;
-                }
-                case 'error': {
-                    obj = { silent: true };
-                }
+        // reset logging level
+        let obj;
+        switch (loggerLevelBak) {
+            case 'info': {
+                obj = {};
+                break;
+            }
+            case 'verbose': {
+                obj = { verbose: true };
+                break;
+            }
+            case 'debug': {
+                obj = { debug: true };
+                break;
+            }
+            case 'error': {
+                obj = { silent: true };
             }
-            Util.setLoggingLevel(obj);
         }
+        Util.setLoggingLevel(obj);
 
         if (failed.length) {
             Util.logger.warn(
@@ -428,8 +504,8 @@ class Asset extends MetadataType {
      * Some metadata types store their actual content as a separate file, e.g. images
      * This method retrieves these and saves them alongside the metadata json
      *
-     * @param {TYPE.AssetItem} metadata a single asset
-     * @param {TYPE.AssetSubType} subType group of similar assets to put in a folder (ie. images)
+     * @param {AssetItem} metadata a single asset
+     * @param {string} subType group of similar assets to put in a folder (ie. images)
      * @param {string} retrieveDir target directory for saving assets
      * @returns {Promise.<void>} -
      */
@@ -453,8 +529,8 @@ class Asset extends MetadataType {
      * Some metadata types store their actual content as a separate file, e.g. images
      * This method reads these from the local FS stores them in the metadata object allowing to deploy it
      *
-     * @param {TYPE.AssetItem} metadata a single asset
-     * @param {TYPE.AssetSubType} subType group of similar assets to put in a folder (ie. images)
+     * @param {AssetItem} metadata a single asset
+     * @param {string} subType group of similar assets to put in a folder (ie. images)
      * @param {string} deployDir directory of deploy files
      * @param {boolean} [pathOnly] used by getFilesToCommit which does not need the binary file to be actually read
      * @returns {Promise.<string>} if found will return the path of the binary file
@@ -488,22 +564,49 @@ class Asset extends MetadataType {
     /**
      * manages post retrieve steps
      *
-     * @param {TYPE.AssetItem} metadata a single asset
-     * @returns {TYPE.CodeExtractItem} metadata
+     * @param {AssetItem} metadata a single asset
+     * @returns {CodeExtractItem} metadata
      */
     static postRetrieveTasks(metadata) {
         // folder
         this.setFolderPath(metadata);
+
+        // template-based emails
+        if (metadata.assetType.name === 'templatebasedemail') {
+            // get template
+            try {
+                if (metadata.views?.html?.template?.id) {
+                    metadata.views.html.template.r__asset_key = cache.searchForField(
+                        'asset',
+                        metadata.views?.html?.template?.id,
+                        'id',
+                        'customerKey'
+                    );
+                    delete metadata.views.html.template.id;
+                    delete metadata.views.html.template.name;
+                    delete metadata.views.html.template.assetType;
+                    delete metadata.views.html.template.availableViews;
+                    delete metadata.views.html.template.data;
+                    delete metadata.views.html.template.modelVersion;
+                }
+            } catch {
+                Util.logger.warn(
+                    ` - ${this.definition.type} '${metadata[this.definition.nameField]}' (${
+                        metadata[this.definition.keyField]
+                    }): Could not find email template with id (${metadata.views.html.template.id})`
+                );
+            }
+        }
+
         // extract HTML for selected subtypes and convert payload for easier processing in MetadataType.saveResults()
-        metadata = this._extractCode(metadata);
-        return metadata;
+        return this._extractCode(metadata);
     }
 
     /**
      * Gets executed after deployment of metadata type
      *
-     * @param {TYPE.MetadataTypeMap} metadata metadata mapped by their keyField
-     * @param {TYPE.MetadataTypeMap} _ originalMetadata to be updated (contains additioanl fields)
+     * @param {MetadataTypeMap} metadata metadata mapped by their keyField
+     * @param {MetadataTypeMap} _ originalMetadata to be updated (contains additioanl fields)
      * @param {{created: number, updated: number}} createdUpdated counter representing successful creates/updates
      * @returns {Promise.<void>} -
      */
@@ -524,7 +627,7 @@ class Asset extends MetadataType {
      * helper for {@link Asset.postDeployTasks}. triggers a refresh of active triggerredSendDefinitions associated with the updated asset-message items. Gets executed if refresh option has been set.
      *
      * @private
-     * @param {TYPE.MetadataTypeMap} metadata metadata mapped by their keyField
+     * @param {MetadataTypeMap} metadata metadata mapped by their keyField
      * @returns {Promise.<void>} -
      */
     static async _refreshTriggeredSend(metadata) {
@@ -572,9 +675,9 @@ class Asset extends MetadataType {
     /**
      * prepares an asset definition for deployment
      *
-     * @param {TYPE.AssetItem} metadata a single asset
+     * @param {AssetItem} metadata a single asset
      * @param {string} deployDir directory of deploy files
-     * @returns {Promise.<TYPE.AssetItem>} Promise
+     * @returns {Promise.<AssetItem>} Promise
      */
     static async preDeployTasks(metadata, deployDir) {
         // additonalattributes fail where the value is "" so we need to remove them from deploy
@@ -587,6 +690,39 @@ class Asset extends MetadataType {
         // folder
         this.setFolderId(metadata);
 
+        // template-based emails
+        if (
+            metadata.assetType.name === 'templatebasedemail' &&
+            metadata.views?.html?.template?.r__asset_key
+        ) {
+            // template
+            metadata.views.html.template.id = cache.searchForField(
+                'asset',
+                metadata.views.html.template.r__asset_key,
+                'customerKey',
+                'id'
+            );
+            metadata.views.html.template.name = cache.searchForField(
+                'asset',
+                metadata.views.html.template.r__asset_key,
+                'customerKey',
+                'name'
+            );
+            metadata.views.html.template.assetType = {
+                id: 4,
+                name: 'template',
+                displayName: 'Template',
+            };
+
+            metadata.views.html.template.data = {
+                email: { options: { generateFrom: null } },
+            };
+
+            metadata.views.html.template.availableViews = [];
+            metadata.views.html.template.modelVersion = 2;
+            delete metadata.views.html.template.r__asset_key;
+        }
+
         // restore asset type id which is needed for deploy
         metadata.assetType.id = this.definition.typeMapping[metadata.assetType.name];
 
@@ -601,8 +737,9 @@ class Asset extends MetadataType {
 
         // only execute #3 if we are deploying / copying from one BU to another, not while using mcdev as a developer tool
         if (
+            !Util.OPTIONS.noMidSuffix &&
             this.buObject.mid &&
-            metadata.memberId !== this.buObject.mid &&
+            metadata.memberId != this.buObject.mid && // soft comparison to accomodate for string-version of mid
             !metadata[this.definition.keyField].endsWith(this.buObject.mid)
         ) {
             // #3 make sure customer key is unique by suffixing it with target MID (unless we are deploying to the same MID)
@@ -618,7 +755,7 @@ class Asset extends MetadataType {
         const namesInFolder = Object.keys(assetCache)
             .filter((key) => assetCache[key].category.id === metadata.category.id)
             .map((key) => ({
-                type: this._getMainSubtype(assetCache[key].assetType.name),
+                type: this.#getMainSubtype(assetCache[key].assetType.name),
                 key: key,
                 name: assetCache[key].name,
             }));
@@ -626,7 +763,7 @@ class Asset extends MetadataType {
         metadata[this.definition.nameField] = this._findUniqueName(
             metadata[this.definition.keyField],
             metadata[this.definition.nameField],
-            this._getMainSubtype(metadata.assetType.name),
+            this.#getMainSubtype(metadata.assetType.name),
             namesInFolder
         );
         return metadata;
@@ -637,7 +774,7 @@ class Asset extends MetadataType {
      * @param {string} extendedSubType webpage, htmlblock, etc
      * @returns {string} subType: block, message, other, etc
      */
-    static _getMainSubtype(extendedSubType) {
+    static #getMainSubtype(extendedSubType) {
         return Object.keys(this.definition.extendedSubTypes).find((subType) =>
             this.definition.extendedSubTypes[subType].includes(extendedSubType)
         );
@@ -649,7 +786,7 @@ class Asset extends MetadataType {
      * @param {string} key key of the asset
      * @param {string} name name of the asset
      * @param {string} type assetType-name
-     * @param {string[]} namesInFolder names of the assets in the same folder
+     * @param {{ type: string; key: string; name: any; }[]} namesInFolder names of the assets in the same folder
      * @returns {string} new name
      */
     static _findUniqueName(key, name, type, namesInFolder) {
@@ -672,8 +809,8 @@ class Asset extends MetadataType {
      * determines the subtype of the current asset
      *
      * @private
-     * @param {TYPE.AssetItem} metadata a single asset
-     * @returns {TYPE.AssetSubType | void} subtype
+     * @param {AssetItem} metadata a single asset
+     * @returns {string} subtype
      */
     static _getSubtype(metadata) {
         for (const sub in this.definition.extendedSubTypes) {
@@ -681,6 +818,7 @@ class Asset extends MetadataType {
                 return sub;
             }
         }
+        return;
     }
     /**
      * helper for {@link MetadataType.buildDefinition}
@@ -688,10 +826,10 @@ class Asset extends MetadataType {
      *
      * @param {string} templateDir Directory where metadata templates are stored
      * @param {string} targetDir Directory where built definitions will be saved
-     * @param {TYPE.AssetItem} metadata main JSON file that was read from file system
-     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {AssetItem} metadata main JSON file that was read from file system
+     * @param {TemplateMap} templateVariables variables to be replaced in the metadata
      * @param {string} templateName name of the template to be built
-     * @returns {Promise.<void>} -
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
      */
     static buildDefinitionForNested(
         templateDir,
@@ -716,10 +854,10 @@ class Asset extends MetadataType {
      * @example assets of type codesnippetblock will result in 1 json and 1 amp/html 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.AssetItem} metadata main JSON file that was read from file system
-     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {AssetItem} metadata main JSON file that was read from file system
+     * @param {TemplateMap} templateVariables variables to be replaced in the metadata
      * @param {string} templateName name of the template to be built
-     * @returns {Promise.<void>} -
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
      */
     static buildTemplateForNested(
         templateDir,
@@ -743,12 +881,12 @@ class Asset extends MetadataType {
      * handles extracted code if any are found for complex types
      *
      * @param {string} templateDir Directory where metadata templates are stored
-     * @param {string} targetDir Directory where built definitions will be saved
-     * @param {TYPE.AssetItem} metadata main JSON file that was read from file system
-     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {string|string[]} targetDir (List of) Directory where built definitions will be saved
+     * @param {AssetItem} metadata main JSON file that was read from file system
+     * @param {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.<void>} -
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
      */
     static async _buildForNested(
         templateDir,
@@ -759,7 +897,7 @@ class Asset extends MetadataType {
         mode
     ) {
         // * because asset's _mergeCode() is overwriting 'metadata', clone it to ensure the main file is not modified by what we do in here
-        metadata = JSON.parse(JSON.stringify(metadata));
+        metadata = structuredClone(metadata);
 
         // #1 text extracts
         // define asset's subtype
@@ -789,6 +927,9 @@ class Asset extends MetadataType {
                     }: ${extractedFile.fileName}.${extractedFile.fileExt}.`
                 );
             }
+            extractedFile.subFolder = extractedFile.subFolder
+                .map((el) => (el === templateName ? metadata[this.definition.keyField] : el))
+                .map((el) => this.applyTemplateValues(el, templateVariables));
         }
 
         // #2 binary extracts
@@ -816,6 +957,7 @@ class Asset extends MetadataType {
                 encoding: 'base64',
             });
         }
+        const nestedFilePaths = [];
 
         // write to file (#1 + #2)
         const targetDirArr = Array.isArray(targetDir) ? targetDir : [targetDir];
@@ -828,13 +970,22 @@ class Asset extends MetadataType {
                     extractedFile.content,
                     extractedFile.encoding || null
                 );
+                nestedFilePaths.push([
+                    File.normalizePath([targetDir, ...extractedFile.subFolder]),
+                    extractedFile.fileName +
+                        '.' +
+                        this.definition.type +
+                        '-meta.' +
+                        extractedFile.fileExt,
+                ]);
             }
         }
+        return nestedFilePaths;
     }
     /**
      * generic script that retrieves the folder path from cache and updates the given metadata with it after retrieve
      *
-     * @param {TYPE.MetadataTypeItem} metadata a single script activity definition
+     * @param {MetadataTypeItem} metadata a single script activity definition
      */
     static setFolderPath(metadata) {
         try {
@@ -856,7 +1007,7 @@ class Asset extends MetadataType {
     /**
      * Asset-specific script that retrieves the folder ID from cache and updates the given metadata with it before deploy
      *
-     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @param {MetadataTypeItem} metadata a single item
      */
     static setFolderId(metadata) {
         metadata.category = {
@@ -868,12 +1019,12 @@ class Asset extends MetadataType {
     /**
      * helper for {@link Asset.preDeployTasks} that loads extracted code content back into JSON
      *
-     * @param {TYPE.AssetItem} metadata a single asset definition
+     * @param {AssetItem} metadata a single asset definition
      * @param {string} deployDir directory of deploy files
-     * @param {TYPE.AssetSubType} subType asset-subtype name
+     * @param {string} subType asset-subtype name; full list in AssetSubType
      * @param {string} [templateName] name of the template used to built defintion (prior applying templating)
      * @param {boolean} [fileListOnly] does not read file contents nor update metadata if true
-     * @returns {Promise.<TYPE.CodeExtract[]>} fileList for templating (disregarded during deployment)
+     * @returns {Promise.<CodeExtract[]>} fileList for templating (disregarded during deployment)
      */
     static async _mergeCode(metadata, deployDir, subType, templateName, fileListOnly = false) {
         const subtypeExtension = `.${this.definition.type}-${subType}-meta`;
@@ -882,13 +1033,14 @@ class Asset extends MetadataType {
         let readDirArr;
         // unfortunately, asset's key can contain spaces at beginning/end which can break the file system when folders are created with it
         const customerKey = metadata.customerKey.trim();
+        const templateFileName = templateName || customerKey;
         switch (metadata.assetType.name) {
             case 'templatebasedemail': // message
             case 'htmlemail': {
                 // message
                 // this complex type always creates its own subdir per asset
                 subDirArr = [this.definition.type, subType];
-                readDirArr = [deployDir, ...subDirArr, templateName || customerKey];
+                readDirArr = [deployDir, ...subDirArr, templateFileName];
 
                 // metadata.views.html.content (mandatory)
                 // the main content can be empty (=not set up yet) hence check if we did extract sth or else readFile() will print error msgs
@@ -910,13 +1062,78 @@ class Asset extends MetadataType {
                     if (templateName) {
                         // to use this method in templating, store a copy of the info in fileList
                         fileList.push({
-                            subFolder: [...subDirArr, customerKey],
+                            subFolder: [...subDirArr, templateFileName],
                             fileName: fileName,
                             fileExt: 'html',
                             content: metadata.views.html.content,
                         });
                     }
                 }
+                // metadata.views.html.content (optional)
+                // the main content can be empty (=not set up yet) hence check if we did extract sth or else readFile() will print error msgs
+                const fileNamePreheader = 'views.preheader.content' + subtypeExtension;
+                if (
+                    (await File.pathExists(
+                        File.normalizePath([...readDirArr, `${fileNamePreheader}.amp`])
+                    )) &&
+                    metadata.views.preheader
+                ) {
+                    if (!fileListOnly) {
+                        metadata.views.preheader.content = await File.readFilteredFilename(
+                            readDirArr,
+                            fileNamePreheader,
+                            'amp'
+                        );
+                    }
+
+                    if (templateName) {
+                        // to use this method in templating, store a copy of the info in fileList
+                        fileList.push({
+                            subFolder: [...subDirArr, templateFileName],
+                            fileName: fileNamePreheader,
+                            fileExt: 'amp',
+                            content: metadata.views.preheader.content,
+                        });
+                    }
+                }
+
+                // metadata.views.text.content (optional)
+                // the main content can be empty (=not set up yet) hence check if we did extract sth or else readFile() will print error msgs
+                const fileNameText = 'views.text.content' + subtypeExtension;
+                if (
+                    (await File.pathExists(
+                        File.normalizePath([...readDirArr, `${fileNameText}.amp`])
+                    )) &&
+                    metadata.views.text
+                ) {
+                    if (!fileListOnly) {
+                        metadata.views.text.content = await File.readFilteredFilename(
+                            readDirArr,
+                            fileNameText,
+                            'amp'
+                        );
+                    }
+
+                    if (templateName) {
+                        // to use this method in templating, store a copy of the info in fileList
+                        fileList.push({
+                            subFolder: [...subDirArr, templateFileName],
+                            fileName: fileNameText,
+                            fileExt: 'amp',
+                            content: metadata.views.text.content,
+                        });
+                    }
+                } else if (metadata.views.text) {
+                    // ensure the text version gets generated from html
+                    metadata.views.text.data = {
+                        email: {
+                            options: {
+                                generateFrom: 'html',
+                            },
+                        },
+                    };
+                    metadata.views.text.generateFrom = 'html';
+                }
 
                 // metadata.views.html.slots.<>.blocks.<>.content (optional)
                 if (metadata?.views?.html?.slots) {
@@ -938,7 +1155,7 @@ class Asset extends MetadataType {
                 // template-template
                 // this complex type always creates its own subdir per asset
                 subDirArr = [this.definition.type, subType];
-                readDirArr = [deployDir, ...subDirArr, templateName || customerKey];
+                readDirArr = [deployDir, ...subDirArr, templateFileName];
                 const fileName = 'content' + subtypeExtension;
 
                 const fileExtArr = ['html']; // eslint-disable-line no-case-declarations
@@ -959,7 +1176,7 @@ class Asset extends MetadataType {
                         if (templateName) {
                             // to use this method in templating, store a copy of the info in fileList
                             fileList.push({
-                                subFolder: subDirArr,
+                                subFolder: [...subDirArr, templateFileName],
                                 fileName: fileName,
                                 fileExt: ext,
                                 content: metadata.content,
@@ -996,7 +1213,7 @@ class Asset extends MetadataType {
                     await File.pathExists(
                         File.normalizePath([
                             ...readDirArr,
-                            `${templateName || customerKey}${subtypeExtension}.html`,
+                            `${templateFileName}${subtypeExtension}.amp`,
                         ])
                     )
                 ) {
@@ -1004,16 +1221,16 @@ class Asset extends MetadataType {
                     if (!fileListOnly) {
                         metadata.views.text.content = await File.readFilteredFilename(
                             readDirArr,
-                            (templateName || customerKey) + subtypeExtension,
-                            'html'
+                            templateFileName + subtypeExtension,
+                            'amp'
                         );
                     }
                     if (templateName) {
                         // to use this method in templating, store a copy of the info in fileList
                         fileList.push({
                             subFolder: subDirArr,
-                            fileName: customerKey + subtypeExtension,
-                            fileExt: 'html',
+                            fileName: templateFileName + subtypeExtension,
+                            fileExt: 'amp',
                             content: metadata.views.text.content,
                         });
                     }
@@ -1024,7 +1241,7 @@ class Asset extends MetadataType {
                 // asset
                 // this complex type always creates its own subdir per asset
                 subDirArr = [this.definition.type, subType];
-                readDirArr = [deployDir, ...subDirArr, templateName || customerKey];
+                readDirArr = [deployDir, ...subDirArr, templateFileName];
 
                 // metadata.views.html.slots.<>.blocks.<>.content (optional) (pre & post 20222)
                 if (metadata?.views?.html?.slots) {
@@ -1062,7 +1279,7 @@ class Asset extends MetadataType {
                     if (templateName) {
                         // to use this method in templating, store a copy of the info in fileList
                         fileList.push({
-                            subFolder: [...subDirArr, customerKey],
+                            subFolder: [...subDirArr, templateFileName],
                             fileName: 'views.html.content' + subtypeExtension,
                             fileExt: 'html',
                             content: metadata.views.html.content,
@@ -1088,7 +1305,7 @@ class Asset extends MetadataType {
                     if (templateName) {
                         // to use this method in templating, store a copy of the info in fileList
                         fileList.push({
-                            subFolder: [...subDirArr, customerKey],
+                            subFolder: [...subDirArr, templateFileName],
                             fileName: 'content' + subtypeExtension,
                             fileExt: 'html',
                             content: metadata.views.html.content,
@@ -1116,7 +1333,7 @@ class Asset extends MetadataType {
                         await File.pathExists(
                             File.normalizePath([
                                 ...readDirArr,
-                                `${templateName || customerKey}${subtypeExtension}.${ext}`,
+                                `${templateFileName}${subtypeExtension}.${ext}`,
                             ])
                         )
                     ) {
@@ -1124,7 +1341,7 @@ class Asset extends MetadataType {
                         if (!fileListOnly) {
                             metadata.content = await File.readFilteredFilename(
                                 readDirArr,
-                                (templateName || customerKey) + subtypeExtension,
+                                templateFileName + subtypeExtension,
                                 ext
                             );
                             if (ext === 'ssjs') {
@@ -1135,7 +1352,7 @@ class Asset extends MetadataType {
                             // to use this method in templating, store a copy of the info in fileList
                             fileList.push({
                                 subFolder: subDirArr,
-                                fileName: (templateName || customerKey) + subtypeExtension,
+                                fileName: templateFileName + subtypeExtension,
                                 fileExt: ext,
                                 content: metadata.content,
                             });
@@ -1174,6 +1391,8 @@ class Asset extends MetadataType {
         templateName,
         fileListOnly = false
     ) {
+        const templateFileName = templateName || customerKey;
+
         for (const slot in metadataSlots) {
             if (Object.prototype.hasOwnProperty.call(metadataSlots, slot)) {
                 const slotObj = metadataSlots[slot];
@@ -1203,7 +1422,7 @@ class Asset extends MetadataType {
                                 if (templateName) {
                                     // to use this method in templating, store a copy of the info in fileList
                                     fileList.push({
-                                        subFolder: [...subDirArr, customerKey, 'blocks'],
+                                        subFolder: [...subDirArr, templateFileName, 'blocks'],
                                         fileName: fileName,
                                         fileExt: 'html',
                                         content: slotObj.blocks[block].content,
@@ -1233,8 +1452,8 @@ class Asset extends MetadataType {
      * helper for {@link Asset.postRetrieveTasks} that finds code content in JSON and extracts it
      * to allow saving that separately and formatted
      *
-     * @param {TYPE.AssetItem} metadata a single asset definition
-     * @returns {TYPE.CodeExtractItem} { json: metadata, codeArr: object[], subFolder: string[] }
+     * @param {AssetItem} metadata a single asset definition
+     * @returns {CodeExtractItem} { json: metadata, codeArr: object[], subFolder: string[] }
      */
     static _extractCode(metadata) {
         const codeArr = [];
@@ -1255,6 +1474,27 @@ class Asset extends MetadataType {
                     });
                     delete metadata.views.html.content;
                 }
+                // metadata.views.preheader.content (optional)
+                if (metadata.views?.preheader?.content?.length) {
+                    codeArr.push({
+                        subFolder: null,
+                        fileName: 'views.preheader.content',
+                        fileExt: 'amp',
+                        content: metadata.views.preheader.content,
+                    });
+                    delete metadata.views.preheader.content;
+                }
+
+                // metadata.views.text.content (optional)
+                if (metadata.views?.text?.content?.length) {
+                    codeArr.push({
+                        subFolder: null,
+                        fileName: 'views.text.content',
+                        fileExt: 'amp',
+                        content: metadata.views.text.content,
+                    });
+                    delete metadata.views.text.content;
+                }
 
                 // metadata.views.html.slots.<>.blocks.<>.content (optional)
                 if (metadata.views?.html?.slots) {
@@ -1298,7 +1538,7 @@ class Asset extends MetadataType {
                     codeArr.push({
                         subFolder: null,
                         fileName: customerKey,
-                        fileExt: 'html',
+                        fileExt: 'amp',
                         content: metadata.views.text.content,
                     });
                     delete metadata.views.text.content;
@@ -1429,11 +1669,11 @@ class Asset extends MetadataType {
      * Returns file contents mapped to their fileName without '.json' ending
      *
      * @param {string} dir directory that contains '.json' files to be read
-     * @param {void} [_] unused parameter
+     * @param {boolean} _ unused parameter
      * @param {string[]} selectedSubType asset, message, ...
-     * @returns {TYPE.MetadataTypeMap} fileName => fileContent map
+     * @returns {Promise.<MetadataTypeMap>} fileName => fileContent map
      */
-    static getJsonFromFS(dir, _, selectedSubType) {
+    static async getJsonFromFS(dir, _, selectedSubType) {
         const fileName2FileContent = {};
         try {
             for (const subtype of this.definition.subTypes) {
@@ -1445,8 +1685,8 @@ class Asset extends MetadataType {
                     continue;
                 }
                 const currentdir = File.normalizePath([dir, subtype]);
-                if (File.pathExistsSync(currentdir)) {
-                    const files = File.readdirSync(currentdir, { withFileTypes: true });
+                if (await File.pathExists(currentdir)) {
+                    const files = await File.readdir(currentdir, { withFileTypes: true });
 
                     for (const dirent of files) {
                         try {
@@ -1456,7 +1696,7 @@ class Asset extends MetadataType {
                                 // complex types with more than one extracted piece of code are saved in their
                                 // own subfolder (with folder name = CustomerKey)
                                 // this section aims to find that json in the subfolder
-                                const subfolderFiles = File.readdirSync(
+                                const subfolderFiles = await File.readdir(
                                     File.normalizePath([currentdir, dirent.name])
                                 );
                                 for (const subFileName of subfolderFiles) {
@@ -1467,10 +1707,9 @@ class Asset extends MetadataType {
                                 }
                             }
                             if (fileName.endsWith('-meta.json')) {
-                                const fileContent = File.readJSONFile(
+                                const fileContent = await File.readJSONFile(
                                     thisDir,
                                     fileName,
-                                    true,
                                     false
                                 );
                                 // subtype will change the metadata suffix length
@@ -1488,7 +1727,7 @@ class Asset extends MetadataType {
                 }
             }
         } catch (ex) {
-            // this will catch issues with readdirSync
+            // this will catch issues with readdir
             Util.metadataLogger('debug', this.definition.type, 'getJsonFromFS', ex);
             throw new Error(ex);
         }
@@ -1499,7 +1738,7 @@ class Asset extends MetadataType {
      *
      * @param {string} templateDir Directory where metadata templates are stored
      * @param {string} templateName name of the metadata file
-     * @returns {Promise.<TYPE.AssetSubType>} subtype name
+     * @returns {Promise.<string>} AssetSubType name
      */
     static async findSubType(templateDir, templateName) {
         const typeDirArr = [this.definition.type];
@@ -1518,14 +1757,6 @@ class Asset extends MetadataType {
                 break;
             }
         }
-        if (!subType) {
-            throw new Error(
-                `Could not find asset with name ${templateName} in ${File.normalizePath([
-                    templateDir,
-                    ...typeDirArr,
-                ])}`
-            );
-        }
         return subType;
     }
     /**
@@ -1535,7 +1766,7 @@ class Asset extends MetadataType {
      * @param {string[]} typeDirArr current subdir for this type
      * @param {string} templateName name of the metadata template
      * @param {string} fileName name of the metadata template file w/o extension
-     * @returns {TYPE.AssetItem} metadata
+     * @returns {Promise.<string>} metadata in string form
      */
     static async readSecondaryFolder(templateDir, typeDirArr, templateName, fileName) {
         // handles subtypes that create 1 folder per asset -> currently causes the below File.ReadFile to error out
@@ -1547,7 +1778,7 @@ class Asset extends MetadataType {
      * 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']
+     * @returns {Promise.<string[]>} list of all files that need to be committed in a flat array ['path/file1.ext', 'path/file2.ext']
      */
     static async getFilesToCommit(keyArr) {
         const basePath = File.normalizePath([
@@ -1594,7 +1825,7 @@ class Asset extends MetadataType {
                         (await File.pathExists(File.normalizePath([...filePath, fileName])))
                     ) {
                         // #1 load json to be able to find extracted text files & binary files
-                        const metadata = File.readJSONFile(filePath, fileName, true, false);
+                        const metadata = await File.readJSONFile(filePath, fileName, false);
                         // #2 find all extracted text files
                         const fileListNested = (
                             await this._mergeCode(metadata, basePath, subType, metadata.customerKey)
@@ -1629,6 +1860,427 @@ class Asset extends MetadataType {
         ).flat();
         return fileList;
     }
+    /**
+     * helper to allow us to select single metadata entries via REST
+     *
+     * @private
+     * @param {string} key customer key
+     * @returns {Promise.<string>} id value or null
+     */
+    static async _getIdForSingleRetrieve(key) {
+        const name = key.startsWith('name:') ? key.slice(5) : null;
+        const filter = name
+            ? '?$filter=name%20eq%20' + encodeURIComponent(name)
+            : '?$filter=customerKey%20eq%20' + encodeURIComponent(key);
+
+        const results = await this.client.rest.get('/asset/v1/content/assets/' + filter);
+        const items = results?.items || [];
+        const found = items.find((item) =>
+            name ? item[this.definition.nameField] === name : item[this.definition.keyField] === key
+        );
+        return found?.id || null;
+    }
+    /**
+     * helper to allow us to select single metadata entries via REST
+     *
+     * @private
+     * @param {string} id id field
+     * @returns {Promise.<string>} key value or null
+     */
+    static async _getKeyForSingleRetrieve(id) {
+        const results = await this.client.rest.get('/asset/v1/content/assets/' + id);
+        return results?.customerKey || null;
+    }
+
+    /**
+     * Delete a metadata item from the specified business unit
+     *
+     * @param {string} key Identifier of item
+     * @returns {Promise.<boolean>} deletion success flag
+     */
+    static async deleteByKey(key) {
+        // delete only works with the query's object id
+        let id;
+        if (key?.startsWith('id:')) {
+            id = key.slice(3);
+            // we need to get the actual key so that postDeletetTasks know what to do
+            key = await this._getKeyForSingleRetrieve(id);
+        } else {
+            id = key ? await this._getIdForSingleRetrieve(key) : null;
+        }
+        if (!id) {
+            Util.logger.error(` - ${this.definition.type} not found`);
+            return false;
+        }
+        return super.deleteByKeyREST('/asset/v1/content/assets/' + id, key);
+    }
+
+    /**
+     * clean up after deleting a metadata item
+     * cannot use the generic method due to the complexity of how assets are saved to disk
+     *
+     * @param {string} key Identifier of metadata item
+     * @returns {Promise.<void>} -
+     */
+    static async postDeleteTasks(key) {
+        if (key?.startsWith('id:')) {
+            // sad
+        }
+        const fileArr = await this.getFilesToCommit([key]);
+
+        // check if asset sits in its own folder
+        const ownFolderIndex =
+            fileArr[0].indexOf(key + '\\') > 0
+                ? fileArr[0].indexOf(key + '\\')
+                : fileArr[0].indexOf(key + '/');
+        if (ownFolderIndex > 0) {
+            fileArr.push(fileArr[0].slice(0, ownFolderIndex + key.length));
+        }
+
+        for (const filePath of fileArr) {
+            await File.remove(filePath);
+        }
+    }
+    /**
+     * get name & key for provided id
+     *
+     * @param {string} id Identifier of metadata
+     * @returns {Promise.<{key:string, name:string, path:string, folder:string, mid:number, error:string, isShared:boolean}>} key, name and path of metadata; null if not found
+     */
+    static async resolveId(id) {
+        let response;
+        const json = {
+            key: '',
+            isShared: false,
+            name: '',
+            path: '',
+            folder: '',
+            mid: 0,
+            legacyId: 0,
+            error: '',
+            sharedWith: [],
+        };
+        try {
+            response = await this.client.rest.get(
+                'asset/v1/content/assets/' +
+                    id +
+                    '?$fields=id,customerKey,name,memberId,legacyData,sharingProperties'
+            );
+        } catch (ex) {
+            if (ex.response?.status !== 404) {
+                throw ex;
+            }
+        }
+        if (response?.id) {
+            const item = response;
+            const subType = this.#getMainSubtype(item.assetType.name);
+
+            // prep response object
+            json.key = item[this.definition.keyField];
+            json.name = item[this.definition.nameField];
+            json.mid = item.memberId;
+            json.isShared = item.memberId != this.buObject.mid;
+            json.sharedWith = item.sharingProperties?.sharedWith || null;
+            json.legacyId = item.legacyData?.legacyId;
+
+            const ownerBUName = json.isShared
+                ? Util.inverseGet(
+                      this.properties.credentials[this.buObject.credential].businessUnits,
+                      json.mid
+                  )
+                : this.buObject.businessUnit;
+
+            // find path for code of content block, fall back to json if not found; undefined if not even the json exists
+            let path = await this.#getPath(subType, item, ownerBUName);
+
+            if (!json.sharedWith) {
+                delete json.sharedWith;
+            }
+            if (!json.isShared && !path) {
+                // if not shared, we should have the file on disk; attempt download
+                if (!cache.getCache()?.folder) {
+                    // folders not cached yet but required to fill json.path
+                    Folder.client = this.client;
+                    Folder.buObject = this.buObject;
+                    Folder.properties = this.properties;
+                    const result = await Folder.retrieveForCache(null, ['asset', 'asset-shared']);
+                    if (!cache.getCache()) {
+                        cache.initCache(this.buObject);
+                    }
+                    cache.setMetadata('folder', result.metadata);
+                }
+
+                await this.retrieve(
+                    File.normalizePath([
+                        this.properties.directories.retrieve,
+                        this.buObject.credential,
+                        this.buObject.businessUnit,
+                    ]),
+                    null,
+                    [subType],
+                    json.key
+                );
+                // try again
+                path = await this.#getPath(subType, item, this.buObject.businessUnit);
+            }
+
+            if (path) {
+                json.path = path;
+                delete json.error;
+            } else {
+                json.error = 'file not found on local disk';
+                delete json.path;
+            }
+            const fileContent = await this.#getJson(subType, item);
+            if (fileContent?.r__folder_Path) {
+                json.folder = fileContent.r__folder_Path;
+            }
+            if (!json.legacyId) {
+                delete json.legacyId;
+            }
+
+            if (Util.OPTIONS.json) {
+                // for automated processing by VSCode extension, optionally print the json
+                console.log(JSON.stringify(json, null, 2)); // eslint-disable-line no-console
+            } else {
+                Util.logger.info(` - ID: ${id}`);
+                Util.logger.info(` - Key: ${item[this.definition.keyField]}`);
+                Util.logger.info(` - Name: ${item[this.definition.nameField]}`);
+
+                if (json.isShared) {
+                    Util.logger.warn(' - Shared from: ' + ownerBUName + ' (' + json.mid + ')');
+                }
+                if (json.sharedWith && Array.isArray(json.sharedWith)) {
+                    Util.logger.warn(
+                        `          with: ${json.sharedWith
+                            .map(
+                                (mid) =>
+                                    Util.inverseGet(
+                                        this.properties.credentials[this.buObject.credential]
+                                            .businessUnits,
+                                        mid
+                                    ) +
+                                    ' (' +
+                                    mid +
+                                    ')'
+                            )
+                            .sort()
+                            .join(', ')}`
+                    );
+                }
+                if (json.legacyId) {
+                    Util.logger.info(` - Legacy ID: ${json.legacyId}`);
+                }
+                Util.logger.info(` - How to use:`);
+                Util.logger.info(`     %%= ContentBlockByKey("${json.key}") =%%`);
+
+                if (json.folder) {
+                    Util.logger.info(
+                        `     %%= ContentBlockByName("${json.folder.split('/').join('\\') + '\\' + json.name}") =%%`
+                    );
+                    if (json.folder.includes('&amp;') || json.name.includes('&amp;')) {
+                        Util.logger.warn(
+                            ` - ContentBlockByName will fail because your path or name contains the & or &amp; symbol. Please replace it with 'and' or remove it.`
+                        );
+                    }
+                }
+                Util.logger.info(
+                    ' - local link: ' +
+                        (path ||
+                            `404. Try running mcdev r ${this.buObject.credential}/${ownerBUName} ${this.definition.type}-${subType} ${item[this.definition.keyField]}`)
+                );
+            }
+            return json;
+        } else {
+            json.error = 'id not found';
+            delete json.key;
+            delete json.mid;
+            delete json.name;
+            delete json.path;
+            delete json.folder;
+            delete json.isShared;
+            delete json.legacyId;
+            delete json.sharedWith;
+            if (Util.OPTIONS.json) {
+                console.log(JSON.stringify(json, null, 2)); // eslint-disable-line no-console
+                return json;
+            }
+            Util.logger.error(` - ${this.definition.type} with id ${id} not found on BU`);
+            return json;
+        }
+    }
+
+    /**
+     * helper for {@link Asset.resolveId} that finds the path to the asset's code
+     *
+     * @param {string} subType asset subtype
+     * @param {object} item api response for metadata
+     * @param {string} buName owner business unit name
+     * @returns {string} path to the asset's code
+     */
+    static async #getPath(subType, item, buName) {
+        const pathBase1 = `./retrieve/${this.buObject.credential}/${buName}/${this.definition.type}/${subType}/${item[this.definition.keyField]}.${this.definition.type}-${subType}-meta.`;
+        const pathBase2 = `./retrieve/${this.buObject.credential}/${buName}/${this.definition.type}/${subType}/${item[this.definition.keyField]}/${item[this.definition.keyField]}.${this.definition.type}-${subType}-meta.`;
+        const paths = [];
+        for (const ext of ['html', 'ssjs', 'amp', 'json']) {
+            paths.push(pathBase1 + ext, pathBase2 + ext);
+        }
+        const path = await Util.findAsync(paths, async (p) => await File.pathExists(p));
+        return path;
+    }
+    /**
+     * helper for {@link Asset.resolveId} that loads the JSON file for the asset
+     *
+     * @param {string} subType asset subtype
+     * @param {object} item api response for metadata
+     * @returns {Promise.<object>} JS object of the asset we loaded from disk
+     */
+    static async #getJson(subType, item) {
+        const mid = item.memberId;
+        const buName =
+            mid === this.buObject.mid
+                ? this.buObject.businessUnit
+                : Object.keys(
+                      this.properties.credentials[this.buObject.credential].businessUnits
+                  ).find(
+                      (buName) =>
+                          this.properties.credentials[this.buObject.credential].businessUnits[
+                              buName
+                          ] == mid
+                  );
+        const pathBase1 = `./retrieve/${this.buObject.credential}/${buName}/${this.definition.type}/${subType}/${item[this.definition.keyField]}.${this.definition.type}-${subType}-meta.`;
+        const pathBase2 = `./retrieve/${this.buObject.credential}/${buName}/${this.definition.type}/${subType}/${item[this.definition.keyField]}/${item[this.definition.keyField]}.${this.definition.type}-${subType}-meta.`;
+        const paths = [];
+        paths.push(pathBase1 + 'json', pathBase2 + 'json');
+
+        const path = await Util.findAsync(paths, async (p) => await File.pathExists(p));
+        const pathArr = path.split('/');
+        const fileName = pathArr.pop().slice(0, -5);
+        const fileContent = await File.readJSONFile(pathArr.join('/'), fileName, false);
+        return fileContent;
+    }
+    /**
+     *
+     * @param {MetadataTypeItem} item single metadata item
+     * @param {string} retrieveDir directory where metadata is saved
+     * @returns {Promise.<MetadataTypeItem>} key of the item that was updated
+     */
+    static async replaceCbReference(item, retrieveDir) {
+        const responseItem = structuredClone(item);
+        const parentName = `${this.definition.type} ${item[this.definition.keyField]}`;
+        let changes = false;
+        let error;
+
+        // *** type specific logic ***
+        const subType = this.#getMainSubtype(item.assetType.name);
+        /** @type {CodeExtract[]} */
+        const fileList = await this._mergeCode(
+            item,
+            retrieveDir,
+            subType,
+            item[this.definition.keyField],
+            false
+        );
+        const fileListChanged = [];
+        for (const file of fileList) {
+            try {
+                file.content = ReplaceCbReference.replaceReference(file.content, parentName);
+                changes = true;
+                fileListChanged.push(file);
+            } catch (ex) {
+                if (ex.code !== 200) {
+                    error = ex;
+                }
+            }
+        }
+
+        // save what was changed regardless of other errors
+        for (const extractedFile of fileListChanged) {
+            File.writeToFile(
+                [retrieveDir, ...extractedFile.subFolder],
+                extractedFile.fileName,
+                extractedFile.fileExt,
+                extractedFile.content,
+                extractedFile.encoding || null
+            );
+        }
+
+        if (error) {
+            throw error;
+        }
+
+        if (!changes) {
+            const ex = new Error('No changes made to the code.');
+            ex.code = 200;
+            throw ex;
+        }
+
+        // *** finish ***
+        // replaceReference will throw an error if nothing was updated which will end execution here
+        // no error means we have a new item to deploy and need to update the item in our retrieve folder
+        return responseItem;
+    }
+    /**
+     * this iterates over all items found in the retrieve folder and executes the type-specific method for replacing references
+     *
+     * @param {MetadataTypeMap} metadataMap list of metadata (keyField => metadata)
+     * @param {string} retrieveDir retrieve dir including cred and bu
+     * @returns {Promise.<string[]>} Returns list of keys for which references were replaced
+     */
+    static async replaceCbReferenceLoop(metadataMap, retrieveDir) {
+        const keysForDeploy = [];
+        if (!metadataMap) {
+            // if a type was skipped e.g. because it shall only be looked at on the parent then we would expect metadataMap to be undefined
+            return keysForDeploy;
+        }
+
+        const fromDescription = Util.OPTIONS.referenceFrom
+            .map((from) => 'ContentBlockBy' + Util.capitalizeFirstLetter(from))
+            .join(' and ');
+
+        if (Object.keys(metadataMap).length) {
+            Util.logger.info(`Searching ${this.definition.type} for ${fromDescription}:`);
+            // const baseDir = [retrieveDir, ...this.definition.type.split('-')];
+            const deployMap = {};
+
+            for (const key in metadataMap) {
+                const item = metadataMap[key];
+                if (this.isFiltered(item, true) || this.isFiltered(item, false)) {
+                    // we would not have saved these items to disk but they exist in the cache and hence need to be skipped here
+
+                    continue;
+                }
+
+                try {
+                    // add key but make sure to turn it into string or else numeric keys will be filtered later
+                    deployMap[key] = await this.replaceCbReference(item, retrieveDir);
+
+                    // ! this method is equal to the super version except that it does not run saveToDisk here
+                    // await this.saveToDisk(deployMap, key, baseDir);
+
+                    keysForDeploy.push(key + '');
+                    Util.logger.info(` - added ${this.definition.type} to update queue: ${key}`);
+                } catch (ex) {
+                    if (ex.code !== 200) {
+                        // dont print error if we simply did not find relevant content blocks
+                        Util.logger.errorStack(ex, ex.message);
+                    }
+                    Util.logger.info(
+                        Util.getGrayMsg(
+                            ` ☇ skipping ${this.definition.type} ${
+                                item[this.definition.keyField]
+                            }: no ${fromDescription} found`
+                        )
+                    );
+                }
+            }
+
+            Util.logger.info(
+                `Found ${keysForDeploy.length} ${this.definition.type}${keysForDeploy.length === 1 ? '' : 's'} to update`
+            );
+        }
+        return keysForDeploy;
+    }
 }
 
 // Assign definition to static attributes