mcdev 10.1.0 → 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.
Files changed (31) hide show
  1. package/@types/lib/index.d.ts.map +1 -1
  2. package/@types/lib/metadataTypes/AttributeGroup.d.ts +69 -24
  3. package/@types/lib/metadataTypes/AttributeGroup.d.ts.map +1 -1
  4. package/@types/lib/metadataTypes/AttributeSet.d.ts +521 -301
  5. package/@types/lib/metadataTypes/AttributeSet.d.ts.map +1 -1
  6. package/@types/lib/metadataTypes/DataExtension.d.ts.map +1 -1
  7. package/@types/lib/metadataTypes/Folder.d.ts.map +1 -1
  8. package/@types/lib/metadataTypes/Journey.d.ts +43 -12
  9. package/@types/lib/metadataTypes/Journey.d.ts.map +1 -1
  10. package/@types/lib/metadataTypes/MetadataType.d.ts.map +1 -1
  11. package/@types/lib/metadataTypes/MobileMessage.d.ts +7 -0
  12. package/@types/lib/metadataTypes/MobileMessage.d.ts.map +1 -1
  13. package/@types/lib/metadataTypes/MobilePush.d.ts +8 -0
  14. package/@types/lib/metadataTypes/MobilePush.d.ts.map +1 -1
  15. package/@types/lib/metadataTypes/definitions/AttributeGroup.definition.d.ts +25 -20
  16. package/@types/lib/metadataTypes/definitions/AttributeSet.definition.d.ts +327 -296
  17. package/lib/cli.js +4 -1
  18. package/lib/index.js +24 -1
  19. package/lib/metadataTypes/AttributeGroup.js +173 -1
  20. package/lib/metadataTypes/AttributeSet.js +847 -14
  21. package/lib/metadataTypes/DataExtension.js +17 -7
  22. package/lib/metadataTypes/Folder.js +20 -0
  23. package/lib/metadataTypes/Journey.js +265 -21
  24. package/lib/metadataTypes/MetadataType.js +21 -13
  25. package/lib/metadataTypes/MobileMessage.js +32 -3
  26. package/lib/metadataTypes/MobilePush.js +37 -3
  27. package/lib/metadataTypes/definitions/AttributeGroup.definition.js +55 -48
  28. package/lib/metadataTypes/definitions/AttributeSet.definition.js +345 -316
  29. package/lib/util/init.git.js +1 -1
  30. package/package.json +19 -17
  31. package/scripts/verify-own-dependencies-latest.mjs +117 -0
@@ -1,9 +1,9 @@
1
1
  'use strict';
2
2
 
3
- import AttributeGroup from './AttributeGroup.js';
4
3
  import MetadataType from './MetadataType.js';
5
4
  import { Util } from '../util/util.js';
6
5
  import cache from '../util/cache.js';
6
+ import { isDeepEqual } from '../util/isDeepEqual.js';
7
7
 
8
8
  /**
9
9
  * @typedef {import('../../types/mcdev.d.js').MetadataTypeItem} MetadataTypeItem
@@ -11,6 +11,29 @@ import cache from '../util/cache.js';
11
11
  * @typedef {import('../../types/mcdev.d.js').MetadataTypeMapObj} MetadataTypeMapObj
12
12
  */
13
13
 
14
+ /**
15
+ * case-insensitive comparison of API ids (GUIDs)
16
+ *
17
+ * @param {string} [a] id
18
+ * @param {string} [b] id
19
+ * @returns {boolean} true if both ids are set and equal
20
+ */
21
+ function isSameId(a, b) {
22
+ return !!a && !!b && String(a).toLowerCase() === String(b).toLowerCase();
23
+ }
24
+
25
+ /**
26
+ * helper for {@link AttributeSet._getDifferences}: retention settings without the duplicate set id
27
+ *
28
+ * @param {MetadataTypeItem} item attributeSet
29
+ * @returns {object} dataRetentionProperties without setDefinitionID
30
+ */
31
+ function getRetention(item) {
32
+ const retention = structuredClone(item.dataRetentionProperties || {});
33
+ delete retention.setDefinitionID;
34
+ return retention;
35
+ }
36
+
14
37
  /**
15
38
  * AttributeSet MetadataType
16
39
  *
@@ -18,6 +41,25 @@ import cache from '../util/cache.js';
18
41
  */
19
42
  class AttributeSet extends MetadataType {
20
43
  static systemValueDefinitions;
44
+ /**
45
+ * data resolved in preDeployTasks that create() needs but which must not be sent to the API
46
+ *
47
+ * @type {Map.<string, {attributeGroupID: string}>}
48
+ */
49
+ static deployContext = new Map();
50
+ /**
51
+ * owning attributeGroup id of every set created during the current deploy, keyed by the set's definitionID
52
+ *
53
+ * @type {Map.<string, string>}
54
+ */
55
+ static createdSetGroups = new Map();
56
+ /**
57
+ * keys of sets the server deleted together with their parent set or attributeGroup during the current delete run;
58
+ * reset whenever the attributeSet cache is reloaded for a delete (see AttributeGroup.cacheForDelete)
59
+ *
60
+ * @type {Set.<string>}
61
+ */
62
+ static cascadeDeletedKeys = new Set();
21
63
 
22
64
  /**
23
65
  * Retrieves Metadata of schema set Definitions.
@@ -29,15 +71,7 @@ class AttributeSet extends MetadataType {
29
71
  * @returns {Promise.<MetadataTypeMapObj>} Promise
30
72
  */
31
73
  static async retrieve(retrieveDir, _, __, key) {
32
- if (retrieveDir && !cache.getCache()?.attributeGroup) {
33
- // ! attributeGroup and attributeSet both link to each other. caching attributeGroup here "manually", assuming that it's quicker than the other way round
34
- Util.logger.info(' - Caching dependent Metadata: attributeGroup');
35
- AttributeGroup.buObject = this.buObject;
36
- AttributeGroup.client = this.client;
37
- AttributeGroup.properties = this.properties;
38
- const result = await AttributeGroup.retrieveForCache();
39
- cache.setMetadata('attributeGroup', result.metadata);
40
- }
74
+ // attributeGroup is cached by Retriever via the attributeSet -> attributeGroup dependency
41
75
  return super.retrieveREST(retrieveDir, '/hub/v1/contacts/schema/setDefinitions', key);
42
76
  }
43
77
 
@@ -167,7 +201,12 @@ class AttributeSet extends MetadataType {
167
201
 
168
202
  // make sure we add the entire list to cache before running postRetrieveTasks because of the self-references this type is using
169
203
  // usually, the cache is only written into after all postRetrieveTasks have been run
170
- cache.setMetadata(this.definition.type, metadataCache);
204
+ if (Array.isArray(body)) {
205
+ // an array body only comes from upsert (create/update results): merge it into the existing cache instead of replacing the full list
206
+ cache.mergeMetadata(this.definition.type, metadataCache);
207
+ } else {
208
+ cache.setMetadata(this.definition.type, metadataCache);
209
+ }
171
210
 
172
211
  const metadataStructure = super.parseResponseBody(body, singleRetrieve);
173
212
  return metadataStructure;
@@ -180,6 +219,9 @@ class AttributeSet extends MetadataType {
180
219
  * @returns {MetadataTypeItem} metadata
181
220
  */
182
221
  static postRetrieveTasks(metadata) {
222
+ // the cache holds the same objects; work on a copy so that other sets can still read the raw relationships from the cache
223
+ metadata = structuredClone(metadata);
224
+
183
225
  // folder
184
226
  if (metadata.storageLogicalType === 'DataExtension') {
185
227
  // attributeSet created for Group Connect do not have a folder
@@ -233,7 +275,11 @@ class AttributeSet extends MetadataType {
233
275
  }
234
276
  }
235
277
 
236
- // relationships to attributeGroups & AttributeSet
278
+ // relationships to attributeGroups & AttributeSet; stored on the set that is linked in (right side)
279
+ const relationships = this._getIncomingRelationships(metadata);
280
+ if (relationships) {
281
+ metadata.relationships = relationships;
282
+ }
237
283
  if (Array.isArray(metadata.relationships)) {
238
284
  for (const relationship of metadata.relationships) {
239
285
  for (const type of ['left', 'right']) {
@@ -308,8 +354,8 @@ class AttributeSet extends MetadataType {
308
354
  (item) => item.valueDefinitionID === id
309
355
  );
310
356
  if (valueDefinition) {
311
- attr['c__' + type + 'FullyQualifiedName'] =
312
- valueDefinition.fullyQualifiedName;
357
+ // the set itself is identified via leftItem / rightItem; only store the field key
358
+ attr['c__' + type + 'Field'] = valueDefinition.definitionKey;
313
359
  delete attr[type + 'AttributeID'];
314
360
  delete attr[type + 'ConnectingID'];
315
361
  } else {
@@ -347,6 +393,793 @@ class AttributeSet extends MetadataType {
347
393
  return metadata;
348
394
  }
349
395
 
396
+ /**
397
+ * helper for {@link AttributeSet.postRetrieveTasks}
398
+ * Returns the relationships that link the given set in (set is rightItem), incl. self-relationships.
399
+ * The API returns set-to-set relationships only on the left (pre-existing) set, so these are taken from the other sets in the cache,
400
+ * while relationships pointing from this set to another set are left out (they are stored in the other set's file).
401
+ *
402
+ * @param {MetadataTypeItem} metadata a single attributeSet (raw API format)
403
+ * @returns {object[] | undefined} copy of the incoming relationships; undefined if the set had none and none were found
404
+ */
405
+ static _getIncomingRelationships(metadata) {
406
+ const ownId = metadata.definitionID;
407
+ const relationships = Array.isArray(metadata.relationships)
408
+ ? metadata.relationships.filter(
409
+ (rel) =>
410
+ !(
411
+ rel.leftItem?.relationshipType === 'AttributeSet' &&
412
+ rel.leftItem.identifier === ownId
413
+ ) || rel.rightItem?.identifier === ownId
414
+ )
415
+ : [];
416
+ const knownIds = new Set(relationships.map((rel) => rel.relationshipID));
417
+ const cachedSets = cache.getCache()?.[this.definition.type] || {};
418
+ for (const otherSet of Object.values(cachedSets)) {
419
+ if (otherSet.definitionID === ownId || !Array.isArray(otherSet.relationships)) {
420
+ continue;
421
+ }
422
+ for (const rel of otherSet.relationships) {
423
+ if (rel.rightItem?.identifier !== ownId || knownIds.has(rel.relationshipID)) {
424
+ continue;
425
+ }
426
+
427
+ relationships.push(structuredClone(rel));
428
+ knownIds.add(rel.relationshipID);
429
+ }
430
+ }
431
+ return Array.isArray(metadata.relationships) || relationships.length
432
+ ? relationships
433
+ : undefined;
434
+ }
435
+
436
+ /**
437
+ * Deploys metadata - merely kept here to be able to print {@link Util.logBeta} once per deploy
438
+ *
439
+ * @param {MetadataTypeMap} metadata metadata mapped by their keyField
440
+ * @param {string} deployDir directory where deploy metadata are saved
441
+ * @param {string} retrieveDir directory where metadata after deploy should be saved
442
+ * @returns {Promise.<MetadataTypeMap>} Promise of keyField => metadata map
443
+ */
444
+ static async deploy(metadata, deployDir, retrieveDir) {
445
+ Util.logBeta(this.definition.type);
446
+ this.deployContext = new Map();
447
+ this.createdSetGroups = new Map();
448
+ return super.deploy(metadata, deployDir, retrieveDir);
449
+ }
450
+
451
+ /**
452
+ * sets linked to other sets of the same deploy need to be created after those; hence upsert runs sequentially on a sorted map
453
+ *
454
+ * @param {MetadataTypeMap} metadataMap metadata mapped by their keyField
455
+ * @param {string} deployDir directory where deploy metadata are saved
456
+ * @returns {Promise.<MetadataTypeMap>} keyField => metadata map
457
+ */
458
+ static async upsert(metadataMap, deployDir) {
459
+ return super.upsert(this._sortForDeploy(metadataMap), deployDir, true);
460
+ }
461
+
462
+ /**
463
+ * helper for {@link AttributeSet.upsert}: puts sets whose incoming relationship starts at another set of this deploy after that set.
464
+ * Sets that are part of (or depend on) a cycle are reported and left out.
465
+ *
466
+ * @param {MetadataTypeMap} metadataMap metadata mapped by their keyField
467
+ * @returns {MetadataTypeMap} sorted copy of the map
468
+ */
469
+ static _sortForDeploy(metadataMap) {
470
+ const parents = {};
471
+ for (const key in metadataMap) {
472
+ parents[key] = (
473
+ Array.isArray(metadataMap[key]?.relationships) ? metadataMap[key].relationships : []
474
+ )
475
+ .map((rel) => rel.leftItem?.r__attributeSet_key)
476
+ .filter((parentKey) => parentKey && parentKey !== key && metadataMap[parentKey]);
477
+ }
478
+ /** @type {MetadataTypeMap} */
479
+ const sorted = {};
480
+ let added = true;
481
+ while (added) {
482
+ added = false;
483
+ for (const key in metadataMap) {
484
+ if (sorted[key] || parents[key].some((parentKey) => !sorted[parentKey])) {
485
+ continue;
486
+ }
487
+
488
+ sorted[key] = metadataMap[key];
489
+ added = true;
490
+ }
491
+ }
492
+ for (const key in metadataMap) {
493
+ if (!sorted[key]) {
494
+ Util.logger.error(
495
+ ` ☇ skipping ${this.definition.type} ${key}: circular relationship between attributeSets of this deploy (${parents[key].join(', ')})`
496
+ );
497
+ }
498
+ }
499
+ return sorted;
500
+ }
501
+
502
+ /**
503
+ * prepares a set for deployment: resolves all references and builds the create payload.
504
+ * Every unsupported situation throws, which makes upsert skip the item.
505
+ *
506
+ * @param {MetadataTypeItem} metadata a single item
507
+ * @returns {Promise.<MetadataTypeItem>} Promise of the create payload
508
+ */
509
+ static async preDeployTasks(metadata) {
510
+ const key = metadata[this.definition.keyField];
511
+ if (metadata.isSystemDefined) {
512
+ throw new Error('system-defined attributeSets cannot be deployed');
513
+ }
514
+ if (metadata.storageLogicalType !== 'DataExtension') {
515
+ throw new Error(
516
+ `attributeSets with storageLogicalType ${metadata.storageLogicalType} cannot be deployed; only sets linking a data extension are supported`
517
+ );
518
+ }
519
+ const name = metadata.name || metadata.definitionName?.value;
520
+ if (!name) {
521
+ throw new Error('name is required');
522
+ }
523
+ if (!metadata.r__dataExtension_key) {
524
+ throw new Error('r__dataExtension_key is required');
525
+ }
526
+
527
+ // data extension (local, shared and synchronized DEs are all in the dataExtension cache)
528
+ const deObjectID = cache.searchForField(
529
+ 'dataExtension',
530
+ metadata.r__dataExtension_key,
531
+ 'CustomerKey',
532
+ 'ObjectID'
533
+ );
534
+ const deName = cache.searchForField(
535
+ 'dataExtension',
536
+ metadata.r__dataExtension_key,
537
+ 'CustomerKey',
538
+ 'Name'
539
+ );
540
+ const otherSet = Object.values(cache.getCache()?.[this.definition.type] || {}).find(
541
+ (set) =>
542
+ set[this.definition.keyField] !== key &&
543
+ isSameId(set.storageReferenceID?.value, deObjectID)
544
+ );
545
+ if (otherSet) {
546
+ throw new Error(
547
+ `dataExtension ${metadata.r__dataExtension_key} is already linked by attributeSet ${otherSet[this.definition.keyField]}`
548
+ );
549
+ }
550
+
551
+ // relationship
552
+ const incoming = (
553
+ Array.isArray(metadata.relationships) ? metadata.relationships : []
554
+ ).filter((rel) => {
555
+ if (
556
+ rel.leftItem?.r__attributeSet_key === key &&
557
+ rel.rightItem?.r__attributeSet_key === key
558
+ ) {
559
+ Util.logger.warn(
560
+ ` - ${this.definition.type} ${key}: self-relationship cannot be created via API and is ignored`
561
+ );
562
+ return false;
563
+ }
564
+ return true;
565
+ });
566
+ if (incoming.length !== 1) {
567
+ throw new Error(
568
+ `exactly one relationship linking this set to an attributeGroup or another attributeSet is required, found ${incoming.length}`
569
+ );
570
+ }
571
+ const rel = incoming[0];
572
+ if (!rel.leftItem?.cardinality || !rel.rightItem?.cardinality) {
573
+ throw new Error('leftItem.cardinality and rightItem.cardinality are required');
574
+ }
575
+ if (!Array.isArray(rel.relationshipAttributes) || !rel.relationshipAttributes.length) {
576
+ throw new Error('relationshipAttributes are required');
577
+ }
578
+ const left = this._resolveLeftItem(rel.leftItem);
579
+ const cachedVersion = cache.getByKey(this.definition.type, key);
580
+ // new sets reference the DE field id; existing sets only need their own attribute ids to detect changes
581
+ const deFieldIds = cachedVersion ? null : await this._getDataExtensionFieldIds(deObjectID);
582
+ const relationshipAttributes = rel.relationshipAttributes.map((attr) => {
583
+ const rightAttributeID = cachedVersion
584
+ ? cachedVersion.valueDefinitions?.find(
585
+ (valueDef) => valueDef.definitionKey === attr.c__rightField
586
+ )?.valueDefinitionID
587
+ : deFieldIds[attr.c__rightField];
588
+ if (!cachedVersion && !rightAttributeID) {
589
+ throw new Error(
590
+ `field ${attr.c__rightField} not found in dataExtension ${metadata.r__dataExtension_key}`
591
+ );
592
+ }
593
+ return {
594
+ leftAttributeID: this._getLeftAttributeID(left, attr.c__leftField),
595
+ rightAttributeID,
596
+ };
597
+ });
598
+
599
+ const relationship = {
600
+ leftItem: {
601
+ identifier: left.identifier,
602
+ relationshipType: left.relationshipType,
603
+ cardinality: rel.leftItem.cardinality,
604
+ },
605
+ rightItem: {
606
+ relationshipType: 'AttributeSet',
607
+ cardinality: rel.rightItem.cardinality,
608
+ },
609
+ relationshipAttributes,
610
+ isGroupToSetRelationship: left.relationshipType === 'AttributeGroup',
611
+ };
612
+ if (relationship.isGroupToSetRelationship) {
613
+ // differs per relationship attribute; send exactly what was retrieved
614
+ if (rel.leftRelationshipReferenceType) {
615
+ relationship.leftRelationshipReferenceType = rel.leftRelationshipReferenceType;
616
+ }
617
+ if (rel.leftRelationshipIDs) {
618
+ relationship.leftRelationshipIDs = structuredClone(rel.leftRelationshipIDs);
619
+ }
620
+ }
621
+
622
+ /** @type {MetadataTypeItem} */
623
+ const payload = {
624
+ definitionKey: key,
625
+ name,
626
+ definitionName: { value: name },
627
+ storageReferenceID: { type: 'Guid', value: deObjectID },
628
+ storageName: deName,
629
+ storageLogicalType: 'DataExtension',
630
+ isRoot: metadata.isRoot ?? false,
631
+ valueDefinitions: [],
632
+ nonStandardAttributeGroupReferences: [],
633
+ relationships: [relationship],
634
+ };
635
+ if (metadata.dataRetentionProperties) {
636
+ // not createable; only used to warn about differences
637
+ payload.dataRetentionProperties = metadata.dataRetentionProperties;
638
+ }
639
+ this.deployContext.set(key, { attributeGroupID: left.groupId });
640
+ return payload;
641
+ }
642
+
643
+ /**
644
+ * helper for {@link AttributeSet.preDeployTasks}
645
+ *
646
+ * @param {object} leftItem leftItem of the relationship in retrieve format
647
+ * @returns {{identifier: string, relationshipType: 'AttributeGroup'|'AttributeSet', groupId: string, set?: MetadataTypeItem}} resolved left side
648
+ */
649
+ static _resolveLeftItem(leftItem) {
650
+ if (leftItem?.r__attributeGroup_key) {
651
+ const group = cache.getByKey('attributeGroup', leftItem.r__attributeGroup_key);
652
+ if (!group?.definitionID) {
653
+ throw new Error(
654
+ `attributeGroup ${leftItem.r__attributeGroup_key} was not found on your BU`
655
+ );
656
+ }
657
+ return {
658
+ identifier: group.definitionID,
659
+ relationshipType: 'AttributeGroup',
660
+ groupId: group.definitionID,
661
+ };
662
+ }
663
+ if (leftItem?.r__attributeSet_key) {
664
+ const set = cache.getByKey(this.definition.type, leftItem.r__attributeSet_key);
665
+ if (!set?.definitionID) {
666
+ throw new Error(
667
+ `attributeSet ${leftItem.r__attributeSet_key} was not found on your BU or in this deploy`
668
+ );
669
+ }
670
+ const groupId = this._getOwningGroupId(set.definitionID);
671
+ if (!groupId) {
672
+ throw new Error(
673
+ `could not find the attributeGroup of attributeSet ${leftItem.r__attributeSet_key}`
674
+ );
675
+ }
676
+ return {
677
+ identifier: set.definitionID,
678
+ relationshipType: 'AttributeSet',
679
+ groupId,
680
+ set,
681
+ };
682
+ }
683
+ throw new Error('leftItem requires r__attributeGroup_key or r__attributeSet_key');
684
+ }
685
+
686
+ /**
687
+ * helper for {@link AttributeSet.preDeployTasks}
688
+ *
689
+ * @param {{relationshipType: string, set?: MetadataTypeItem}} left resolved left side
690
+ * @param {string} fieldKey c__leftField
691
+ * @returns {string} valueDefinitionID of the left attribute
692
+ */
693
+ static _getLeftAttributeID(left, fieldKey) {
694
+ if (left.relationshipType === 'AttributeSet') {
695
+ const valueDefinition = left.set.valueDefinitions?.find(
696
+ (valueDef) => valueDef.definitionKey === fieldKey
697
+ );
698
+ if (!valueDefinition?.valueDefinitionID) {
699
+ throw new Error(
700
+ `field ${fieldKey} not found in attributeSet ${left.set[this.definition.keyField]}`
701
+ );
702
+ }
703
+ return valueDefinition.valueDefinitionID;
704
+ }
705
+ // group side: attributes of the system sets; prefer the root Contact set as keys like ContactKey exist on several system sets
706
+ const systemSets = Object.values(cache.getCache()?.[this.definition.type] || {}).filter(
707
+ (set) => set.isSystemDefined
708
+ );
709
+ const contactMatch = systemSets
710
+ .find((set) => set[this.definition.keyField] === 'Contact')
711
+ ?.valueDefinitions?.find((valueDef) => valueDef.definitionKey === fieldKey);
712
+ if (contactMatch?.valueDefinitionID) {
713
+ return contactMatch.valueDefinitionID;
714
+ }
715
+ const matches = systemSets.flatMap((set) =>
716
+ (set.valueDefinitions || [])
717
+ .filter((valueDef) => valueDef.definitionKey === fieldKey)
718
+ .map((valueDef) => ({ setKey: set[this.definition.keyField], valueDef }))
719
+ );
720
+ if (matches.length === 1 && matches[0].valueDef.valueDefinitionID) {
721
+ return matches[0].valueDef.valueDefinitionID;
722
+ }
723
+ throw new Error(
724
+ matches.length
725
+ ? `field ${fieldKey} is ambiguous on the attributeGroup side (found in ${matches.map((m) => m.setKey).join(', ')})`
726
+ : `field ${fieldKey} not found on the attributeGroup side`
727
+ );
728
+ }
729
+
730
+ /**
731
+ * helper for {@link AttributeSet.preDeployTasks}: SOAP cannot return fields of parent-owned DEs from a child BU, REST can
732
+ *
733
+ * @param {string} deObjectID ObjectID of the data extension
734
+ * @returns {Promise.<Object.<string, string>>} field name => field id
735
+ */
736
+ static async _getDataExtensionFieldIds(deObjectID) {
737
+ const response = await this.client.rest.get(`/data/v1/customobjects/${deObjectID}/fields`);
738
+ const fields = Array.isArray(response) ? response : response?.fields || [];
739
+ return Object.fromEntries(fields.map((field) => [field.name, field.id]));
740
+ }
741
+
742
+ /**
743
+ * finds the raw relationship that links the given set in (set is rightItem; self-relationships are ignored).
744
+ * A set-to-set relationship is only stored on the left set, hence all cached sets are searched.
745
+ *
746
+ * @param {string} setId definitionID of the set
747
+ * @returns {{relationship: object, storedOn: string} | undefined} relationship and the definitionID of the set that holds it
748
+ */
749
+ static _findIncomingRelationship(setId) {
750
+ for (const set of Object.values(cache.getCache()?.[this.definition.type] || {})) {
751
+ for (const rel of Array.isArray(set.relationships) ? set.relationships : []) {
752
+ if (
753
+ isSameId(rel.rightItem?.identifier, setId) &&
754
+ !isSameId(rel.leftItem?.identifier, setId)
755
+ ) {
756
+ return { relationship: rel, storedOn: set.definitionID };
757
+ }
758
+ }
759
+ }
760
+ return;
761
+ }
762
+
763
+ /**
764
+ * returns the id of the attributeGroup a set belongs to; needed as attributeGroupID query parameter
765
+ *
766
+ * @param {string} setId definitionID of the set
767
+ * @param {Set.<string>} [visited] used internally to stop on circular relationships
768
+ * @returns {string | undefined} definitionID of the attributeGroup
769
+ */
770
+ static _getOwningGroupId(setId, visited = new Set()) {
771
+ if (this.createdSetGroups.has(setId)) {
772
+ return this.createdSetGroups.get(setId);
773
+ }
774
+ const groups = Object.values(cache.getCache()?.attributeGroup || {});
775
+ const setKey = Object.values(cache.getCache()?.[this.definition.type] || {}).find((set) =>
776
+ isSameId(set.definitionID, setId)
777
+ )?.[this.definition.keyField];
778
+ const group = groups.find(
779
+ (group) =>
780
+ group.attributeSetIdentifiers?.some((item) => isSameId(item.definitionID, setId)) ||
781
+ // groups deployed in the same run are cached in retrieve format
782
+ (setKey && Array.isArray(group.r__attributeSet_key)
783
+ ? group.r__attributeSet_key.includes(setKey)
784
+ : false)
785
+ );
786
+ if (group) {
787
+ return group.definitionID;
788
+ }
789
+ // follow the incoming relationship up to the group
790
+ if (visited.has(setId)) {
791
+ return;
792
+ }
793
+ visited.add(setId);
794
+ const leftItem = this._findIncomingRelationship(setId)?.relationship.leftItem;
795
+ if (leftItem?.relationshipType === 'AttributeGroup') {
796
+ return leftItem.identifier;
797
+ }
798
+ return leftItem?.identifier
799
+ ? this._getOwningGroupId(leftItem.identifier, visited)
800
+ : undefined;
801
+ }
802
+
803
+ /**
804
+ * Creates a single attributeSet
805
+ *
806
+ * @param {MetadataTypeItem} metadata single metadata entry
807
+ * @returns {Promise.<object> | null} Promise of API response or null in case of an error
808
+ */
809
+ static async create(metadata) {
810
+ const groupId = this.deployContext.get(
811
+ metadata[this.definition.keyField]
812
+ )?.attributeGroupID;
813
+ return super.createREST(
814
+ metadata,
815
+ '/hub/v1/contacts/schema/setDefinitions?attributeGroupID=' + groupId
816
+ );
817
+ }
818
+
819
+ /**
820
+ * helper for {@link MetadataType.createREST}: unwraps the created item so that upsert can parse it like a retrieved item.
821
+ * The server generates definitionID and valueDefinitions; these are copied onto the deployed entry so that upsert caches them
822
+ * and sets linked to this one later in the same deploy can be resolved.
823
+ *
824
+ * @param {MetadataTypeItem} metadataEntry a single metadata Entry
825
+ * @param {object} apiResponse varies depending on the API call
826
+ * @returns {Promise.<object>} apiResponse, potentially modified
827
+ */
828
+ static async postCreateTasks(metadataEntry, apiResponse) {
829
+ let item = apiResponse?.setDefinition || apiResponse;
830
+ if (Array.isArray(item)) {
831
+ item = item[0];
832
+ }
833
+ if (item?.definitionID) {
834
+ Object.assign(metadataEntry, structuredClone(item));
835
+ const groupId = this.deployContext.get(
836
+ metadataEntry[this.definition.keyField]
837
+ )?.attributeGroupID;
838
+ if (groupId) {
839
+ this.createdSetGroups.set(item.definitionID, groupId);
840
+ }
841
+ }
842
+ return item;
843
+ }
844
+
845
+ /**
846
+ * helper for {@link AttributeSet.hasChanged} and {@link AttributeSet.update}
847
+ *
848
+ * @param {MetadataTypeItem} cachedVersion cached version from the server (raw API format)
849
+ * @param {MetadataTypeItem} metadata payload created by preDeployTasks
850
+ * @returns {{name: boolean, cardinality: {relationship: object, storedOn: string} | null, unsupported: string[]}} differences
851
+ */
852
+ static _getDifferences(cachedVersion, metadata) {
853
+ const differences = {
854
+ name:
855
+ metadata.definitionName?.value !==
856
+ (cachedVersion.definitionName?.value ?? cachedVersion.name),
857
+ cardinality: null,
858
+ unsupported: [],
859
+ };
860
+ if (
861
+ !isSameId(metadata.storageReferenceID?.value, cachedVersion.storageReferenceID?.value)
862
+ ) {
863
+ differences.unsupported.push('linked dataExtension');
864
+ }
865
+ if (Boolean(metadata.isRoot) !== Boolean(cachedVersion.isRoot)) {
866
+ differences.unsupported.push('isRoot');
867
+ }
868
+ if (
869
+ metadata.dataRetentionProperties &&
870
+ !isDeepEqual(getRetention(metadata), getRetention(cachedVersion))
871
+ ) {
872
+ differences.unsupported.push('dataRetentionProperties');
873
+ }
874
+ const rel = metadata.relationships?.[0];
875
+ const incoming = this._findIncomingRelationship(cachedVersion.definitionID);
876
+ if (!rel || !incoming) {
877
+ differences.unsupported.push('relationship');
878
+ } else if (
879
+ !isSameId(incoming.relationship.leftItem?.identifier, rel.leftItem.identifier) ||
880
+ incoming.relationship.leftItem?.relationshipType !== rel.leftItem.relationshipType
881
+ ) {
882
+ differences.unsupported.push('relationship parent');
883
+ } else {
884
+ const getPairs = (attributes) =>
885
+ (attributes || [])
886
+ .map((attr) => `${attr.leftAttributeID}|${attr.rightAttributeID}`.toLowerCase())
887
+ .toSorted();
888
+ if (
889
+ !isDeepEqual(
890
+ getPairs(incoming.relationship.relationshipAttributes),
891
+ getPairs(rel.relationshipAttributes)
892
+ )
893
+ ) {
894
+ differences.unsupported.push('relationship fields');
895
+ }
896
+ if (
897
+ incoming.relationship.leftItem.cardinality !== rel.leftItem.cardinality ||
898
+ incoming.relationship.rightItem?.cardinality !== rel.rightItem.cardinality
899
+ ) {
900
+ differences.cardinality = incoming;
901
+ }
902
+ }
903
+ return differences;
904
+ }
905
+
906
+ /**
907
+ * test if metadata was actually changed or not to potentially skip it during deployment.
908
+ * only compares what the payload contains, as the cache holds raw API data
909
+ *
910
+ * @param {MetadataTypeItem} cachedVersion cached version from the server
911
+ * @param {MetadataTypeItem} metadata item to upload
912
+ * @returns {boolean} true if metadata was changed
913
+ */
914
+ static hasChanged(cachedVersion, metadata) {
915
+ const differences = this._getDifferences(cachedVersion, metadata);
916
+ if (differences.name || differences.cardinality || differences.unsupported.length) {
917
+ return true;
918
+ }
919
+ Util.logger.verbose(
920
+ ` ☇ skipping ${this.definition.type} ${metadata[this.definition.keyField]} / ${
921
+ metadata[this.definition.nameField] || ''
922
+ }: no change detected`
923
+ );
924
+ return false;
925
+ }
926
+
927
+ /**
928
+ * Updates the few things the API allows to change: the name and the cardinality of the incoming relationship.
929
+ * Everything else is reported as warning. Relationships are never deleted here because deleting the last one deletes the set.
930
+ *
931
+ * @param {MetadataTypeItem} metadata payload created by preDeployTasks
932
+ * @param {MetadataTypeItem} metadataBefore cached version from the server (raw API format)
933
+ * @returns {Promise.<object | null>} updated item in raw API format or null if nothing was updated
934
+ */
935
+ static async update(metadata, metadataBefore) {
936
+ const key = metadata[this.definition.keyField];
937
+ const differences = this._getDifferences(metadataBefore, metadata);
938
+ if (differences.unsupported.length) {
939
+ Util.logger.warn(
940
+ ` ☇ ${this.definition.type} ${key}: ${differences.unsupported.join(', ')} cannot be changed via API; change not applied`
941
+ );
942
+ }
943
+ let updated = false;
944
+ if (differences.name) {
945
+ try {
946
+ await this.client.rest.post(
947
+ `/hub/v1/contacts/schema/setDefinitions/${metadataBefore.definitionID}/definitionName`,
948
+ { value: metadata.definitionName.value }
949
+ );
950
+ metadataBefore.definitionName = { value: metadata.definitionName.value };
951
+ metadataBefore.name = metadata.definitionName.value;
952
+ updated = true;
953
+ Util.logger.info(
954
+ ` - updated ${this.definition.type} ${key}: name changed to ${metadata.definitionName.value}`
955
+ );
956
+ } catch (ex) {
957
+ this._logUpdateError(ex, key, 'name');
958
+ }
959
+ }
960
+ if (differences.cardinality) {
961
+ const { relationship, storedOn } = differences.cardinality;
962
+ const rel = metadata.relationships[0];
963
+ try {
964
+ await this.client.rest.post(
965
+ `/hub/v1/contacts/schema/setDefinitions/${storedOn}/relationships/${relationship.relationshipID}/items`,
966
+ {
967
+ leftItem: { cardinality: rel.leftItem.cardinality },
968
+ rightItem: { cardinality: rel.rightItem.cardinality },
969
+ }
970
+ );
971
+ // the relationship object is part of the cache (on this set or on the left set)
972
+ relationship.leftItem.cardinality = rel.leftItem.cardinality;
973
+ relationship.rightItem.cardinality = rel.rightItem.cardinality;
974
+ updated = true;
975
+ Util.logger.info(
976
+ ` - updated ${this.definition.type} ${key}: relationship cardinality changed to ${rel.leftItem.cardinality} : ${rel.rightItem.cardinality}`
977
+ );
978
+ } catch (ex) {
979
+ this._logUpdateError(ex, key, 'relationship cardinality');
980
+ }
981
+ }
982
+ if (!updated) {
983
+ return null;
984
+ }
985
+ const result = structuredClone(metadataBefore);
986
+ // upsert caches the deployed entry; keep it in raw API format for sets processed later in this deploy
987
+ Object.assign(metadata, structuredClone(result));
988
+ return result;
989
+ }
990
+
991
+ /**
992
+ * helper for {@link AttributeSet.update}
993
+ *
994
+ * @param {object} ex error
995
+ * @param {string} key key of the set
996
+ * @param {string} what what was updated
997
+ * @returns {void}
998
+ */
999
+ static _logUpdateError(ex, key, what) {
1000
+ Util.logger.error(` ☇ error updating ${what} of ${this.definition.type} ${key}:`);
1001
+ const parsedErrors = this.getErrorsREST(ex);
1002
+ if (parsedErrors.length) {
1003
+ for (const msg of parsedErrors) {
1004
+ Util.logger.error(' • ' + msg);
1005
+ }
1006
+ } else if (ex?.message) {
1007
+ Util.logger.error(' • ' + ex.message);
1008
+ }
1009
+ }
1010
+
1011
+ /**
1012
+ * re-reads all sets after a successful create/update so that the saved files reflect the server
1013
+ * (e.g. a set-to-set relationship is only returned on the left set)
1014
+ *
1015
+ * @param {MetadataTypeMap} upsertResults metadata mapped by their keyField as returned by update/create
1016
+ * @param {MetadataTypeMap} originalMetadata metadata to be updated (contains additioanl fields)
1017
+ * @param {{created: number, updated: number}} createdUpdated counter representing successful creates/updates
1018
+ * @returns {Promise.<void>} -
1019
+ */
1020
+ static async postDeployTasks(upsertResults, originalMetadata, createdUpdated) {
1021
+ if (!createdUpdated.created && !createdUpdated.updated) {
1022
+ return;
1023
+ }
1024
+ try {
1025
+ const fresh = (await this.retrieveForCache()).metadata;
1026
+ for (const key in upsertResults) {
1027
+ if (fresh[key]) {
1028
+ upsertResults[key] = fresh[key];
1029
+ } else {
1030
+ // not (yet) returned by the server: keep what create/update returned
1031
+ cache.mergeMetadata(this.definition.type, { [key]: upsertResults[key] });
1032
+ }
1033
+ }
1034
+ } catch (ex) {
1035
+ Util.logger.warn(
1036
+ ` - could not re-retrieve ${this.definition.type}s after deploy: ${ex.message}`
1037
+ );
1038
+ }
1039
+ }
1040
+
1041
+ /**
1042
+ * makes sure attributeGroup and attributeSet are cached (raw API format) before deleting
1043
+ *
1044
+ * @returns {Promise.<void>} -
1045
+ */
1046
+ static async preDeleteTasks() {
1047
+ // AttributeGroup imports AttributeSet; a dynamic import avoids the circular static import
1048
+ const { default: AttributeGroup } = await import('./AttributeGroup.js');
1049
+ AttributeGroup.buObject = this.buObject;
1050
+ AttributeGroup.client = this.client;
1051
+ AttributeGroup.properties = this.properties;
1052
+ await AttributeGroup.cacheForDelete();
1053
+ }
1054
+
1055
+ /**
1056
+ * keys of all cached sets that belong to the given attributeGroup (incl. sets linked in via another set)
1057
+ *
1058
+ * @param {string} groupId definitionID of the attributeGroup
1059
+ * @returns {string[]} attributeSet keys
1060
+ */
1061
+ static _getSetKeysOfGroup(groupId) {
1062
+ return Object.values(cache.getCache()?.[this.definition.type] || {})
1063
+ .filter((set) => isSameId(this._getOwningGroupId(set.definitionID), groupId))
1064
+ .map((set) => set[this.definition.keyField]);
1065
+ }
1066
+
1067
+ /**
1068
+ * keys of all cached sets that are linked in only through the given set (recursively).
1069
+ * The API deletes a set together with its last incoming relationship, hence these go with it.
1070
+ *
1071
+ * @param {string} setId definitionID of the set that is deleted
1072
+ * @returns {string[]} attributeSet keys
1073
+ */
1074
+ static _getSetKeysLinkedOnlyThrough(setId) {
1075
+ const sets = Object.values(cache.getCache()?.[this.definition.type] || {});
1076
+ /** @type {Map.<string, Set.<string>>} set id => ids of everything that links it in */
1077
+ const incoming = new Map();
1078
+ for (const set of sets) {
1079
+ for (const rel of Array.isArray(set.relationships) ? set.relationships : []) {
1080
+ const right = rel.rightItem?.identifier;
1081
+ const left = rel.leftItem?.identifier;
1082
+ if (!right || !left || isSameId(right, left)) {
1083
+ continue;
1084
+ }
1085
+ const rightId = String(right).toLowerCase();
1086
+ if (!incoming.has(rightId)) {
1087
+ incoming.set(rightId, new Set());
1088
+ }
1089
+ incoming.get(rightId).add(String(left).toLowerCase());
1090
+ }
1091
+ }
1092
+ const removed = new Set([String(setId).toLowerCase()]);
1093
+ const keys = [];
1094
+ let found = true;
1095
+ while (found) {
1096
+ found = false;
1097
+ for (const set of sets) {
1098
+ const id = String(set.definitionID).toLowerCase();
1099
+ const lefts = incoming.get(id);
1100
+ if (!(!removed.has(id) && lefts?.size && [...lefts].every((l) => removed.has(l)))) {
1101
+ continue;
1102
+ }
1103
+
1104
+ removed.add(id);
1105
+ keys.push(set[this.definition.keyField]);
1106
+ found = true;
1107
+ }
1108
+ }
1109
+ return keys;
1110
+ }
1111
+
1112
+ /**
1113
+ * removes deleted sets from the cache and their retrieved files from disk
1114
+ *
1115
+ * @param {string[]} keys attributeSet keys
1116
+ * @param {boolean} [isCascade] true if the server deleted these sets together with their parent set or attributeGroup
1117
+ * @returns {Promise.<void>} -
1118
+ */
1119
+ static async removeDeletedSets(keys, isCascade) {
1120
+ for (const key of keys) {
1121
+ delete cache.getCache()?.[this.definition.type]?.[key];
1122
+ if (isCascade) {
1123
+ this.cascadeDeletedKeys.add(key);
1124
+ }
1125
+ await this.postDeleteTasks(key);
1126
+ }
1127
+ }
1128
+
1129
+ /**
1130
+ * Delete an attributeSet. Sets that are linked in only through this set are deleted by the server as well.
1131
+ *
1132
+ * @param {string} key Identifier of the attributeSet
1133
+ * @returns {Promise.<boolean>} deletion success flag
1134
+ */
1135
+ static async deleteByKey(key) {
1136
+ const set = cache.getByKey(this.definition.type, key);
1137
+ if (!set && this.cascadeDeletedKeys.has(key)) {
1138
+ Util.logger.info(
1139
+ ` - ${this.definition.type} ${key} was already deleted together with its parent`
1140
+ );
1141
+ return true;
1142
+ }
1143
+ if (!set) {
1144
+ await this.deleteNotFound(key);
1145
+ return false;
1146
+ }
1147
+ if (set.isSystemDefined) {
1148
+ Util.logger.error(
1149
+ ` ☇ skipping deletion of ${this.definition.type} ${key}: system-defined attributeSets cannot be deleted`
1150
+ );
1151
+ return false;
1152
+ }
1153
+ const groupId = this._getOwningGroupId(set.definitionID);
1154
+ if (!groupId) {
1155
+ Util.logger.error(
1156
+ ` ☇ skipping deletion of ${this.definition.type} ${key}: could not find the attributeGroup it belongs to`
1157
+ );
1158
+ return false;
1159
+ }
1160
+ const cascaded = this._getSetKeysLinkedOnlyThrough(set.definitionID);
1161
+ if (cascaded.length) {
1162
+ Util.logger.warn(
1163
+ ` - deleting ${this.definition.type} ${key} also deletes the following attributeSets that are only linked in through it: ${cascaded.join(', ')}`
1164
+ );
1165
+ }
1166
+ const isDeleted = await super.deleteByKeyREST(
1167
+ '/hub/v1/contacts/schema/setDefinitions/' +
1168
+ set.definitionID +
1169
+ '?attributeGroupID=' +
1170
+ groupId,
1171
+ key
1172
+ );
1173
+ if (isDeleted) {
1174
+ await this.removeDeletedSets([key]);
1175
+ await this.removeDeletedSets(cascaded, true);
1176
+ Util.logger.warn(
1177
+ ` - the retrieved attributeGroup that held ${this.definition.type} ${key} is now outdated; re-retrieve attributeGroup`
1178
+ );
1179
+ }
1180
+ return isDeleted;
1181
+ }
1182
+
350
1183
  /**
351
1184
  * helper for {@link AttributeSet.postRetrieveTasks}
352
1185
  *