mcdev 10.1.1 → 10.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,14 +1,28 @@
1
1
  'use strict';
2
2
 
3
+ import AttributeSet from './AttributeSet.js';
3
4
  import MetadataType from './MetadataType.js';
4
5
  import { Util } from '../util/util.js';
5
6
  import cache from '../util/cache.js';
6
7
 
7
8
  /**
8
9
  * @typedef {import('../../types/mcdev.d.js').MetadataTypeItem} MetadataTypeItem
10
+ * @typedef {import('../../types/mcdev.d.js').MetadataTypeMap} MetadataTypeMap
9
11
  * @typedef {import('../../types/mcdev.d.js').MetadataTypeMapObj} MetadataTypeMapObj
10
12
  */
11
13
 
14
+ /**
15
+ * helper for {@link AttributeGroup.hasChanged}: description is a plain string in the cache (raw API, absent when empty) and {value} after preDeployTasks
16
+ *
17
+ * @param {MetadataTypeItem} item attributeGroup
18
+ * @returns {string} description or empty string
19
+ */
20
+ function getDescription(item) {
21
+ return (
22
+ (typeof item.description === 'object' ? item.description?.value : item.description) || ''
23
+ );
24
+ }
25
+
12
26
  /**
13
27
  * AttributeGroup MetadataType
14
28
  *
@@ -25,6 +39,15 @@ class AttributeGroup extends MetadataType {
25
39
  * @returns {Promise.<MetadataTypeMapObj>} Promise of metadata
26
40
  */
27
41
  static async retrieve(retrieveDir, _, __, key) {
42
+ if (retrieveDir && !cache.getCache()?.attributeSet) {
43
+ // ! attributeSet depends on attributeGroup (deploy order) but postRetrieveTasks needs the attributeSet cache to resolve r__attributeSet_key. caching attributeSet here "manually"
44
+ Util.logger.info(' - Caching dependent Metadata: attributeSet');
45
+ AttributeSet.buObject = this.buObject;
46
+ AttributeSet.client = this.client;
47
+ AttributeSet.properties = this.properties;
48
+ const result = await AttributeSet.retrieveForCache();
49
+ cache.setMetadata('attributeSet', result.metadata);
50
+ }
28
51
  return super.retrieveREST(retrieveDir, '/hub/v1/contacts/schema/attributeGroups', key);
29
52
  }
30
53
 
@@ -104,12 +127,161 @@ class AttributeGroup extends MetadataType {
104
127
  return metadata;
105
128
  }
106
129
 
130
+ /**
131
+ * Deploys metadata - merely kept here to be able to print {@link Util.logBeta} once per deploy
132
+ *
133
+ * @param {MetadataTypeMap} metadata metadata mapped by their keyField
134
+ * @param {string} deployDir directory where deploy metadata are saved
135
+ * @param {string} retrieveDir directory where metadata after deploy should be saved
136
+ * @returns {Promise.<MetadataTypeMap>} Promise of keyField => metadata map
137
+ */
138
+ static async deploy(metadata, deployDir, retrieveDir) {
139
+ Util.logBeta(this.definition.type);
140
+ return super.deploy(metadata, deployDir, retrieveDir);
141
+ }
142
+
107
143
  /**
108
144
  * prepares for deployment
109
145
  *
110
146
  * @param {MetadataTypeItem} metadata a single item
111
- * @returns {MetadataTypeItem} Promise
147
+ * @returns {Promise.<MetadataTypeItem>} Promise
148
+ */
149
+ static async preDeployTasks(metadata) {
150
+ if (metadata.isSystemDefined || metadata.applicationKey) {
151
+ throw new Error(
152
+ 'system-defined attributeGroups cannot be deployed (isSystemDefined / applicationKey is set)'
153
+ );
154
+ }
155
+ if (!metadata.definitionName?.value) {
156
+ throw new Error('definitionName.value is required');
157
+ }
158
+ // the API only accepts description as {value}; retrieve stores it as a plain string
159
+ if (typeof metadata.description === 'string') {
160
+ metadata.description = { value: metadata.description };
161
+ }
162
+ metadata.fullyQualifiedName = metadata.definitionName.value;
163
+ // membership is owned by the attributeSets and read-only on the group
164
+ delete metadata.r__attributeSet_key;
165
+ // server id of the source BU; never sent and must not trigger the id-based update path in createOrUpdate (debug mode)
166
+ delete metadata.definitionID;
167
+ return metadata;
168
+ }
169
+
170
+ /**
171
+ * Creates a single attributeGroup
172
+ *
173
+ * @param {MetadataTypeItem} metadata single metadata entry
174
+ * @returns {Promise.<object> | null} Promise of API response or null in case of an error
175
+ */
176
+ static async create(metadata) {
177
+ return super.createREST(metadata, '/hub/v1/contacts/schema/attributeGroups');
178
+ }
179
+
180
+ /**
181
+ * helper for {@link MetadataType.createREST}: unwraps the created item so that upsert can parse it like a retrieved item
182
+ *
183
+ * @param {MetadataTypeItem} metadataEntry a single metadata Entry
184
+ * @param {object} apiResponse varies depending on the API call
185
+ * @returns {Promise.<object>} apiResponse, potentially modified
186
+ */
187
+ static async postCreateTasks(metadataEntry, apiResponse) {
188
+ return apiResponse?.attributeGroupDefinition || apiResponse;
189
+ }
190
+
191
+ /**
192
+ * attributeGroups cannot be changed via API after creation (only a rename exists, which also overwrites the key on the server).
193
+ * Nothing is sent; differences are only reported. Compares against the raw cached API data.
194
+ *
195
+ * @param {MetadataTypeItem} metadata single metadata entry
196
+ * @param {MetadataTypeItem} metadataBefore cached version from the server
197
+ * @returns {Promise.<null>} always null as nothing is updated
198
+ */
199
+ static async update(metadata, metadataBefore) {
200
+ const key = metadata[this.definition.keyField];
201
+ if (metadata.definitionName?.value !== metadataBefore?.definitionName?.value) {
202
+ Util.logger.error(
203
+ ` ☇ skipping ${this.definition.type} ${key}: renaming an attributeGroup changes its key on the server; rename it in Contact Builder and re-retrieve`
204
+ );
205
+ } else if (
206
+ getDescription(metadata) !== getDescription(metadataBefore) ||
207
+ (metadata.attributeGroupIconKey || '') !== (metadataBefore?.attributeGroupIconKey || '')
208
+ ) {
209
+ Util.logger.warn(
210
+ ` ☇ skipping ${this.definition.type} ${key}: description and attributeGroupIconKey cannot be changed via API after creation`
211
+ );
212
+ } else {
213
+ Util.logger.verbose(` ☇ skipping ${this.definition.type} ${key}: no change detected`);
214
+ }
215
+ return null;
216
+ }
217
+
218
+ /**
219
+ * caches attributeGroup and attributeSet (raw API format) unless already cached; shared by both types' preDeleteTasks
220
+ *
221
+ * @returns {Promise.<void>} -
112
222
  */
223
+ static async cacheForDelete() {
224
+ if (!cache.getCache()) {
225
+ cache.initCache(this.buObject);
226
+ }
227
+ AttributeSet.buObject = this.buObject;
228
+ AttributeSet.client = this.client;
229
+ AttributeSet.properties = this.properties;
230
+ if (!cache.getCache().attributeGroup) {
231
+ cache.setMetadata('attributeGroup', (await this.retrieveForCache()).metadata);
232
+ }
233
+ if (!cache.getCache().attributeSet) {
234
+ // a fresh cache starts a new delete run: forget cascade-deleted keys of earlier runs / other BUs.
235
+ // Not reset when already cached so that deleting attributeGroup and attributeSet in one command keeps the group's cascade
236
+ AttributeSet.cascadeDeletedKeys.clear();
237
+ // parseResponseBody already writes the raw list into the cache
238
+ await AttributeSet.retrieveForCache();
239
+ }
240
+ }
241
+
242
+ /**
243
+ * makes sure attributeGroup and attributeSet are cached before deleting
244
+ *
245
+ * @returns {Promise.<void>} -
246
+ */
247
+ static async preDeleteTasks() {
248
+ await this.cacheForDelete();
249
+ }
250
+
251
+ /**
252
+ * Delete an attributeGroup. The server deletes all attributeSets of the group with it (data extensions stay).
253
+ *
254
+ * @param {string} key Identifier of the attributeGroup
255
+ * @returns {Promise.<boolean>} deletion success flag
256
+ */
257
+ static async deleteByKey(key) {
258
+ const group = cache.getByKey(this.definition.type, key);
259
+ if (!group) {
260
+ await this.deleteNotFound(key);
261
+ return false;
262
+ }
263
+ if (group.isSystemDefined) {
264
+ Util.logger.error(
265
+ ` ☇ skipping deletion of ${this.definition.type} ${key}: system-defined attributeGroups cannot be deleted`
266
+ );
267
+ return false;
268
+ }
269
+ const cascaded = AttributeSet._getSetKeysOfGroup(group.definitionID);
270
+ if (cascaded.length) {
271
+ Util.logger.warn(
272
+ ` - deleting ${this.definition.type} ${key} also deletes all of its attributeSets: ${cascaded.join(', ')}`
273
+ );
274
+ }
275
+ const isDeleted = await super.deleteByKeyREST(
276
+ '/hub/v1/contacts/schema/attributeGroups/' + group.definitionID,
277
+ key
278
+ );
279
+ if (isDeleted) {
280
+ delete cache.getCache()[this.definition.type][key];
281
+ await AttributeSet.removeDeletedSets(cascaded, true);
282
+ }
283
+ return isDeleted;
284
+ }
113
285
  }
114
286
 
115
287
  // Assign definition to static attributes