@adobe/spacecat-shared-data-access 2.71.1 → 2.72.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-data-access-v2.72.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.71.1...@adobe/spacecat-shared-data-access-v2.72.0) (2025-10-16)
+
+
+### Features
+
+* Sites 34129 adds many to many relationship between Fix Entity and Suggestions ([#993](https://github.com/adobe/spacecat-shared/issues/993)) ([8739d2b](https://github.com/adobe/spacecat-shared/commit/8739d2b891d5df6ce883ba3b319047531419100e))
+
 # [@adobe/spacecat-shared-data-access-v2.71.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.71.0...@adobe/spacecat-shared-data-access-v2.71.1) (2025-10-13)
 
 

package/README.md

@@ -85,6 +85,38 @@ npm install @adobe/spacecat-shared-data-access
 - **status** (String): Status of the enrollment. (ACTIVE, SUSPENDED, ENDED)
 - **createdAt** (String): Timestamp of creation.
 
+### FixEntity
+- **fixEntityId** (String): Unique identifier for the fix entity.
+- **opportunityId** (String): ID of the associated opportunity.
+- **createdAt** (String): Timestamp of creation.
+- **updatedAt** (String): Timestamp of the last update.
+- **type** (String): Type of the fix entity (from Suggestion.TYPES).
+- **status** (String): Status of the fix entity (PENDING, DEPLOYED, PUBLISHED, FAILED, ROLLED_BACK).
+- **executedBy** (String): Who executed the fix.
+- **executedAt** (String): When the fix was executed.
+- **publishedAt** (String): When the fix was published.
+- **changeDetails** (Object): Details of the changes made.
+
+### Suggestion
+- **suggestionId** (String): Unique identifier for the suggestion.
+- **opportunityId** (String): ID of the associated opportunity.
+- **createdAt** (String): Timestamp of creation.
+- **updatedAt** (String): Timestamp of the last update.
+- **status** (String): Status of the suggestion (NEW, APPROVED, IN_PROGRESS, SKIPPED, FIXED, ERROR, OUTDATED).
+- **type** (String): Type of the suggestion (CODE_CHANGE, CONTENT_UPDATE, REDIRECT_UPDATE, METADATA_UPDATE, AI_INSIGHTS, CONFIG_UPDATE).
+- **rank** (Number): Rank/priority of the suggestion.
+- **data** (Object): Data payload for the suggestion.
+- **kpiDeltas** (Object): KPI delta information (optional).
+
+### FixEntitySuggestion
+- **suggestionId** (String): ID of the associated suggestion (primary partition key).
+- **fixEntityId** (String): ID of the associated fix entity (primary sort key).
+- **opportunityId** (String): ID of the associated opportunity.
+- **fixEntityCreatedAt** (String): Creation timestamp of the fix entity.
+- **fixEntityCreatedDate** (String): Date portion of fixEntityCreatedAt (auto-generated).
+- **createdAt** (String): Timestamp of creation.
+- **updatedAt** (String): Timestamp of the last update.
+
 ## DynamoDB Data Model
 
 The module is designed to work with the following DynamoDB tables:
@@ -144,6 +176,18 @@ The module provides the following DAOs:
 - `getTopPagesForSite`
 - `addSiteTopPage`
 
+### FixEntity Functions
+- `getSuggestionsByFixEntityId` - Gets all suggestions associated with a specific FixEntity
+- `setSuggestionsForFixEntity` - Sets suggestions for a FixEntity by managing junction table relationships
+
+### Suggestion Functions
+- `bulkUpdateStatus` - Updates the status of multiple suggestions in bulk
+- `getFixEntitiesBySuggestionId` - Gets all FixEntities associated with a specific Suggestion
+
+### FixEntitySuggestion Functions
+- `allBySuggestionId` - Gets all junction records associated with a specific Suggestion
+- `allByFixEntityId` - Gets all junction records associated with a specific FixEntity
+
 ## Integrating Data Access in AWS Lambda Functions
 
 Our `spacecat-shared-data-access` module includes a wrapper that can be easily integrated into AWS Lambda functions using `@adobe/helix-shared-wrap`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "2.71.1",
+  "version": "2.72.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/base/base.collection.js

@@ -22,7 +22,7 @@ import { ElectroValidationError } from 'electrodb';
 import DataAccessError from '../../errors/data-access.error.js';
 import ValidationError from '../../errors/validation.error.js';
 import { createAccessors } from '../../util/accessor.utils.js';
-import { guardId } from '../../util/guards.js';
+import { guardId, guardArray } from '../../util/guards.js';
 import {
   entityNameToAllPKValue,
   removeElectroProperties,
@@ -361,6 +361,53 @@ class BaseCollection {
     return isNonEmptyObject(record?.data);
   }
 
+  /**
+   * Retrieves multiple entities by their IDs in a single batch operation.
+   * This method is more efficient than calling findById multiple times.
+   *
+   * @async
+   * @param {Array<string>} ids - An array of entity IDs to retrieve.
+   * @param {{attributes?: string[]}} [options] - Additional options for the query.
+   * @returns {Promise<{data: Array<BaseModel>, unprocessed: Array<string>}>} - A promise that
+   *   resolves
+   *   to an object containing:
+   *   - data: Array of found model instances
+   *   - unprocessed: Array of IDs that couldn't be processed (due to throttling, etc.)
+   * @throws {DataAccessError} - Throws an error if the IDs are not provided or if the batch
+   *   operation fails.
+   */
+  async batchGetByKeys(keys, options = {}) {
+    guardArray('keys', keys, this.entityName, 'any');
+
+    try {
+      const goOptions = {};
+
+      // Add attributes if specified
+      if (options.attributes !== undefined) {
+        goOptions.attributes = options.attributes;
+      }
+
+      const result = await this.entity.get(
+        keys,
+      ).go(goOptions);
+
+      // Process found entities
+      const data = result.data
+        .map((record) => this.#createInstance(record))
+        .filter((entity) => entity !== null);
+
+      // Extract unprocessed keys
+      const unprocessed = result.unprocessed
+        ? result.unprocessed.map((item) => item)
+        : [];
+
+      return { data, unprocessed };
+    } catch (error) {
+      this.log.error(`Failed to batch get by keys [${this.entityName}]`, error);
+      throw new DataAccessError('Failed to batch get by keys', this, error);
+    }
+  }
+
   /**
    * Finds a single entity by index keys.
    * @param {Object} keys - The index keys to use for the query.
@@ -550,6 +597,51 @@ class BaseCollection {
       return this.#logAndThrowError('Failed to remove by IDs', error);
     }
   }
+
+  /**
+   * Removes records from the collection using an array of key objects for batch deletion.
+   * This method is particularly useful for junction tables in many-to-many relationships
+   * where you need to remove multiple records based on their composite keys.
+   *
+   * Each key object in the array represents a record to be deleted, identified by its
+   * key attributes (typically partition key + sort key combinations).
+   *
+   * @async
+   * @param {Array<Object>} keys - Array of key objects to match for deletion.
+   *   Each object should contain the key attributes that uniquely identify a record.
+   * @returns {Promise<void>} A promise that resolves when the deletion is complete.
+   *   The method also invalidates the cache after successful deletion.
+   * @throws {DataAccessError} Throws an error if:
+   *   - The keys parameter is not a non-empty array
+   *   - Any key object in the array is empty or invalid
+   *   - The database operation fails
+   *
+   * @since 2.64.1
+   * @memberof BaseCollection
+   */
+  async removeByIndexKeys(keys) {
+    if (!isNonEmptyArray(keys)) {
+      const message = `Failed to remove by index keys [${this.entityName}]: keys must be a non-empty array`;
+      this.log.error(message);
+      throw new DataAccessError(message);
+    }
+
+    keys.forEach((key) => {
+      if (!isNonEmptyObject(key)) {
+        const message = `Failed to remove by index keys [${this.entityName}]: key must be a non-empty object`;
+        this.log.error(message);
+        throw new DataAccessError(message);
+      }
+    });
+
+    try {
+      await this.entity.delete(keys).go();
+      this.log.info(`Removed ${keys.length} items for [${this.entityName}]`);
+      return this.#invalidateCache();
+    } catch (error) {
+      return this.#logAndThrowError('Failed to remove by index keys', error);
+    }
+  }
 }
 
 export default BaseCollection;

package/src/models/base/base.model.js

@@ -241,6 +241,12 @@ class BaseModel {
     return this._remove();
   }
 
+  generateCompositeKeys() {
+    return {
+      [this.idName]: this.getId(),
+    };
+  }
+
   /**
    * Internal remove method that removes the current entity from the database and its dependents.
    * This method does not check if the schema allows removal in order to be able to remove
@@ -269,7 +275,7 @@ class BaseModel {
 
       await Promise.all(removePromises);
 
-      await this.entity.remove({ [this.idName]: this.getId() }).go();
+      await this.entity.remove(this.generateCompositeKeys()).go();
 
       this.#invalidateCache();
 

package/src/models/base/entity.registry.js

@@ -20,6 +20,7 @@ import ConfigurationCollection from '../configuration/configuration.collection.j
 import ExperimentCollection from '../experiment/experiment.collection.js';
 import EntitlementCollection from '../entitlement/entitlement.collection.js';
 import FixEntityCollection from '../fix-entity/fix-entity.collection.js';
+import FixEntitySuggestionCollection from '../fix-entity-suggestion/fix-entity-suggestion.collection.js';
 import ImportJobCollection from '../import-job/import-job.collection.js';
 import ImportUrlCollection from '../import-url/import-url.collection.js';
 import KeyEventCollection from '../key-event/key-event.collection.js';
@@ -46,6 +47,7 @@ import AuditSchema from '../audit/audit.schema.js';
 import ConfigurationSchema from '../configuration/configuration.schema.js';
 import EntitlementSchema from '../entitlement/entitlement.schema.js';
 import FixEntitySchema from '../fix-entity/fix-entity.schema.js';
+import FixEntitySuggestionSchema from '../fix-entity-suggestion/fix-entity-suggestion.schema.js';
 import ExperimentSchema from '../experiment/experiment.schema.js';
 import ImportJobSchema from '../import-job/import-job.schema.js';
 import ImportUrlSchema from '../import-url/import-url.schema.js';
@@ -142,6 +144,7 @@ EntityRegistry.registerEntity(AuditSchema, AuditCollection);
 EntityRegistry.registerEntity(ConfigurationSchema, ConfigurationCollection);
 EntityRegistry.registerEntity(EntitlementSchema, EntitlementCollection);
 EntityRegistry.registerEntity(FixEntitySchema, FixEntityCollection);
+EntityRegistry.registerEntity(FixEntitySuggestionSchema, FixEntitySuggestionCollection);
 EntityRegistry.registerEntity(ExperimentSchema, ExperimentCollection);
 EntityRegistry.registerEntity(ImportJobSchema, ImportJobCollection);
 EntityRegistry.registerEntity(ImportUrlSchema, ImportUrlCollection);

package/src/models/base/index.d.ts

@@ -43,12 +43,17 @@ export interface QueryOptions {
   fetchAllPages?: boolean;
 }
 
+export interface BatchGetOptions {
+  attributes?: string[];
+}
+
 export interface BaseCollection<T extends BaseModel> {
   _onCreate(item: T): void;
   _onCreateMany(items: MultiStatusCreateResult<T>): void;
   _saveMany(items: T[]): Promise<T[]>;
   all(sortKeys?: object, options?: QueryOptions): Promise<T[]>;
   allByIndexKeys(keys: object, options?: QueryOptions): Promise<T[]>;
+  batchGetByKeys(keys: object[], options?: BatchGetOptions): Promise<{ data: T[]; unprocessed: object[] }>;
   create(item: object): Promise<T>;
   createMany(items: object[], parent?: T): Promise<MultiStatusCreateResult<T>>;
   existsById(id: string): Promise<boolean>;

package/src/models/base/schema.js

@@ -170,7 +170,9 @@ class Schema {
         const allKeys = [...(pk?.facets || []), ...(sk?.facets || [])];
 
         // check if all keys in the index are in the sort keys
-        return subKeyNames.every((key) => allKeys.includes(key));
+        const pkKeys = Array.isArray(pk?.facets) ? pk.facets : [];
+        return pkKeys.every((key) => subKeyNames.includes(key))
+          && subKeyNames.every((key) => allKeys.includes(key));
       });
 
       if (isNonEmptyObject(index)) {

package/src/models/fix-entity/fix-entity.collection.js

@@ -10,17 +10,235 @@
  * governing permissions and limitations under the License.
  */
 import BaseCollection from '../base/base.collection.js';
+import DataAccessError from '../../errors/data-access.error.js';
+import ValidationError from '../../errors/validation.error.js';
+import { guardId, guardArray, guardString } from '../../util/guards.js';
+import { resolveUpdates } from '../../util/util.js';
 
 /**
- * SiteCandidateCollection - A collection class responsible for managing FixEntities.
+ * FixEntityCollection - A collection class responsible for managing FixEntities.
  * Extends the BaseCollection to provide specific methods for interacting with
- * FixEntity records.
+ * FixEntity records and their relationships with Suggestions.
+ *
+ * This collection provides methods to:
+ * - Retrieve suggestions associated with a specific FixEntity
+ * - Set suggestions for a FixEntity by managing junction table relationships
  *
  * @class FixEntityCollection
  * @extends BaseCollection
  */
 class FixEntityCollection extends BaseCollection {
-  // add custom methods here
+  /**
+   * Gets all suggestions associated with a specific FixEntity.
+   *
+   * @async
+   * @param {string} fixEntityId - The ID of the FixEntity.
+   * @returns {Promise<Array>} - A promise that resolves to an array of Suggestion models
+   * @throws {DataAccessError} - Throws an error if the fixEntityId is not provided or if the
+   *   query fails.
+   */
+  async getSuggestionsByFixEntityId(fixEntityId) {
+    guardId('fixEntityId', fixEntityId, 'FixEntityCollection');
+
+    try {
+      const fixEntitySuggestionCollection = this.entityRegistry.getCollection('FixEntitySuggestionCollection');
+
+      const fixEntitySuggestions = await fixEntitySuggestionCollection
+        .allByFixEntityId(fixEntityId);
+
+      if (fixEntitySuggestions.length === 0) {
+        return [];
+      }
+
+      const suggestionCollection = this.entityRegistry.getCollection('SuggestionCollection');
+      const suggestions = await suggestionCollection
+        .batchGetByKeys(fixEntitySuggestions
+          .map((record) => ({ [suggestionCollection.idName]: record.getSuggestionId() })));
+      return suggestions.data;
+    } catch (error) {
+      this.log.error(`Failed to get suggestions for fix entity: ${fixEntityId}`, error);
+      throw new DataAccessError('Failed to get suggestions for fix entity', this, error);
+    }
+  }
+
+  /**
+   * Sets suggestions for a specific FixEntity by replacing all existing suggestions with new ones.
+   * This method efficiently only removes relationships that are no longer needed and only adds
+   * new ones.
+   *
+   * @async
+   * @param {string} opportunityId - The ID of the opportunity.
+   * @param {FixEntity} fixEntity - The FixEntity entity.
+   * @param {Array<Suggestion>} suggestions - An array of Suggestion entities.
+   * @returns {Promise<{createdItems: Array, errorItems: Array, removedCount: number}>} - A promise
+   *   that resolves to an object containing:
+   *   - createdItems: Array of created FixEntitySuggestionCollection junction records
+   *   - errorItems: Array of items that failed validation
+   *   - removedCount: Number of existing relationships that were removed
+   * @throws {DataAccessError} - Throws an error if the entities are not provided or if the
+   *   operation fails.
+   */
+  async setSuggestionsForFixEntity(opportunityId, fixEntity, suggestions) {
+    guardId('opportunityId', opportunityId, 'FixEntityCollection');
+    guardArray('suggestions', suggestions, 'FixEntityCollection', 'any');
+
+    // Simple null checks
+    if (!fixEntity) {
+      throw new ValidationError('fixEntity is required');
+    }
+
+    // Extract IDs and other values from entities
+    const fixEntityId = fixEntity.getId();
+    const fixEntityCreatedAt = fixEntity.getCreatedAt();
+    const suggestionIds = suggestions.map((suggestion) => suggestion.getId());
+
+    try {
+      const fixEntitySuggestionCollection = this.entityRegistry.getCollection('FixEntitySuggestionCollection');
+
+      const existingRelationships = await fixEntitySuggestionCollection
+        .allByFixEntityId(fixEntityId);
+
+      // Extract existing suggestion IDs from relationship objects
+      const existingSuggestionIds = existingRelationships.map((rel) => rel.getSuggestionId());
+
+      const { toDelete, toCreate } = resolveUpdates(existingSuggestionIds, suggestionIds);
+
+      let removePromise;
+      let createPromise;
+
+      if (toDelete.length > 0) {
+        removePromise = fixEntitySuggestionCollection.removeByIndexKeys(
+          toDelete.map((suggestionId) => (
+            {
+              suggestionId,
+              fixEntityId,
+            })),
+        );
+      }
+
+      if (toCreate.length > 0) {
+        createPromise = fixEntitySuggestionCollection.createMany(toCreate.map((suggestionId) => (
+          {
+            opportunityId,
+            fixEntityCreatedAt,
+            fixEntityId,
+            suggestionId,
+          })));
+      }
+
+      const [removeResult, createResult] = await Promise.allSettled([removePromise, createPromise]);
+
+      let removedCount = 0;
+      let createdItems = [];
+      let errorItems = [];
+      if (removeResult.status === 'fulfilled') {
+        removedCount = toDelete.length;
+      } else {
+        this.log.error('Remove operation failed:', removeResult.reason);
+      }
+
+      if (createResult.status === 'fulfilled') {
+        createdItems = createResult.value?.createdItems || [];
+        errorItems = createResult.value?.errorItems || [];
+      } else {
+        this.log.error('Create operation failed:', createResult.reason);
+      }
+
+      this.log.info(`Set suggestions for fix entity ${fixEntityId}: removed ${removedCount}, `
+        + `added ${createdItems.length}, failed ${errorItems.length}`);
+
+      return { createdItems, errorItems, removedCount };
+    } catch (error) {
+      this.log.error('Failed to set suggestions for fix entity', error);
+      throw new DataAccessError('Failed to set suggestions for fix entity', this, error);
+    }
+  }
+
+  /**
+   * Gets all fixes with their suggestions for a specific opportunity and created date.
+   * This method retrieves all fix entities and their associated suggestions for a given opportunity
+   * and creation date.
+   *
+   * @async
+   * @param {string} opportunityId - The ID of the opportunity.
+   * @param {string} fixEntityCreatedDate - The creation date to filter by (YYYY-MM-DD format).
+   * @returns {Promise<Array>} - A promise that resolves to an array of objects containing:
+   *   - fixEntity: The FixEntity model
+   *   - suggestions: Array of associated Suggestion models
+   * @throws {DataAccessError} - Throws an error if the query fails.
+   * @throws {ValidationError} - Throws an error if opportunityId or
+   *   fixEntityCreatedDate is not provided.
+   */
+  async getAllFixesWithSuggestionByCreatedAt(opportunityId, fixEntityCreatedDate) {
+    guardId('opportunityId', opportunityId, 'FixEntityCollection');
+    guardString('fixEntityCreatedDate', fixEntityCreatedDate, 'FixEntityCollection');
+
+    try {
+      const fixEntitySuggestionCollection = this.entityRegistry.getCollection('FixEntitySuggestionCollection');
+      const suggestionCollection = this.entityRegistry.getCollection('SuggestionCollection');
+
+      // Query fix entity suggestions by opportunity ID and created date
+      const fixEntitySuggestions = await fixEntitySuggestionCollection
+        .allByOpportunityIdAndFixEntityCreatedDate(opportunityId, fixEntityCreatedDate);
+
+      if (fixEntitySuggestions.length === 0) {
+        return [];
+      }
+
+      // Group suggestions by fix entity ID
+      const suggestionsByFixEntityId = {};
+      const fixEntityIds = new Set();
+
+      for (const fixEntitySuggestion of fixEntitySuggestions) {
+        const fixEntityId = fixEntitySuggestion.getFixEntityId();
+        const suggestionId = fixEntitySuggestion.getSuggestionId();
+
+        fixEntityIds.add(fixEntityId);
+
+        if (!suggestionsByFixEntityId[fixEntityId]) {
+          suggestionsByFixEntityId[fixEntityId] = [];
+        }
+        suggestionsByFixEntityId[fixEntityId].push(suggestionId);
+      }
+
+      // Get all fix entities
+      const fixEntities = await this.batchGetByKeys(
+        Array.from(fixEntityIds).map((id) => ({ [this.idName]: id })),
+      );
+
+      // Get all suggestions
+      const allSuggestionIds = Object.values(suggestionsByFixEntityId).flat();
+      const suggestions = await suggestionCollection.batchGetByKeys(
+        allSuggestionIds.map((id) => ({ [suggestionCollection.idName]: id })),
+      );
+
+      // Create a map of suggestions by ID for quick lookup
+      const suggestionsById = {};
+      for (const suggestion of suggestions.data) {
+        suggestionsById[suggestion.getId()] = suggestion;
+      }
+
+      // Combine fix entities with their suggestions
+      const result = [];
+      for (const fixEntity of fixEntities.data) {
+        const fixEntityId = fixEntity.getId();
+        const suggestionIds = suggestionsByFixEntityId[fixEntityId] || [];
+        const suggestionsForFixEntity = suggestionIds
+          .map((id) => suggestionsById[id])
+          .filter(Boolean);
+
+        result.push({
+          fixEntity,
+          suggestions: suggestionsForFixEntity,
+        });
+      }
+
+      return result;
+    } catch (error) {
+      this.log.error('Failed to get all fixes with suggestions by created date', error);
+      throw new DataAccessError('Failed to get all fixes with suggestions by created date', this, error);
+    }
+  }
 }
 
 export default FixEntityCollection;

package/src/models/fix-entity/fix-entity.model.js

@@ -28,6 +28,12 @@ class FixEntity extends BaseModel {
     FAILED: 'FAILED', // failed to apply the fix
     ROLLED_BACK: 'ROLLED_BACK', // the fix has been rolled_back
   };
+
+  async getSuggestions() {
+    const fixEntityCollection = this.entityRegistry.getCollection('FixEntityCollection');
+    return fixEntityCollection
+      .getSuggestionsByFixEntityId(this.getId());
+  }
 }
 
 export default FixEntity;

package/src/models/fix-entity/fix-entity.schema.js

@@ -15,7 +15,7 @@ import { isIsoDate, isNonEmptyObject } from '@adobe/spacecat-shared-utils';
 import SchemaBuilder from '../base/schema.builder.js';
 import FixEntity from './fix-entity.model.js';
 import FixEntityCollection from './fix-entity.collection.js';
-import { Suggestion } from '../suggestion/index.js';
+import Suggestion from '../suggestion/suggestion.model.js';
 
 /*
 Schema Doc: https://electrodb.dev/en/modeling/schema/
@@ -24,7 +24,7 @@ Indexes Doc: https://electrodb.dev/en/modeling/indexes/
  */
 
 const schema = new SchemaBuilder(FixEntity, FixEntityCollection)
-  .addReference('has_many', 'Suggestion', ['status'])
+  .addReference('has_many', 'FixEntitySuggestion', ['updatedAt'], { removeDependents: true })
   .addReference('belongs_to', 'Opportunity', ['status'])
   .addAttribute('type', {
     type: Object.values(Suggestion.TYPES),

package/src/models/fix-entity/index.d.ts

@@ -11,7 +11,7 @@
  */
 
 import type {
-  BaseCollection, BaseModel, Opportunity, Suggestion,
+  BaseCollection, BaseModel, Opportunity, Suggestion, FixEntitySuggestion,
 } from '../index';
 
 export interface FixEntity extends BaseModel {
@@ -28,8 +28,6 @@ export interface FixEntity extends BaseModel {
   setPublishedAt(value: string): this;
   getStatus(): string;
   setStatus(value: string): this;
-  getSuggestions(): Promise<Suggestion[]>;
-  getSuggestionsByUpdatedAt(updatedAt: string): Promise<Suggestion[]>;
   getType(): string;
 }
 
@@ -38,4 +36,6 @@ export interface FixEntityCollection extends BaseCollection<FixEntity> {
   allByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<FixEntity[]>;
   findByOpportunityId(opportunityId: string): Promise<FixEntity | null>;
   findByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<FixEntity | null>;
+  getSuggestionsByFixEntityId(fixEntityId: string): Promise<{data: Array<Suggestion>, unprocessed: Array<string>}>;
+  setSuggestionsForFixEntity(opportunityId: string, fixEntity: FixEntity, suggestions: Array<Suggestion>): Promise<{createdItems: Array<FixEntitySuggestion>, errorItems: Array<FixEntitySuggestion>, removedCount: number}>;
 }

package/src/models/fix-entity-suggestion/fix-entity-suggestion.collection.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { guardId } from '../../util/guards.js';
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * FixEntitySuggestionCollection - A collection class responsible for managing
+ * FixEntitySuggestion junction records. This collection handles the many-to-many
+ * relationship between FixEntity and Suggestion entities.
+ *
+ * This collection provides methods to:
+ * - Retrieve junction records by Suggestion ID
+ * - Retrieve junction records by FixEntity ID
+ *
+ * @class FixEntitySuggestionCollection
+ * @extends BaseCollection
+ */
+class FixEntitySuggestionCollection extends BaseCollection {
+  /**
+   * Gets all junction records associated with a specific Suggestion.
+   *
+   * @async
+   * @param {string} suggestionId - The ID of the Suggestion.
+   * @param {Object} options - Additional query options.
+   * @returns {Promise<Array>} - A promise that resolves to
+   *  an array of FixEntitySuggestion junction records
+   * @throws {Error} - Throws an error if the suggestionId is not provided
+   */
+  async allBySuggestionId(suggestionId, options = {}) {
+    guardId('suggestionId', suggestionId, 'FixEntitySuggestionCollection');
+    return this.allByIndexKeys({ suggestionId }, options);
+  }
+}
+
+export default FixEntitySuggestionCollection;

package/src/models/fix-entity-suggestion/fix-entity-suggestion.model.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * FixEntitySuggestion - A junction table class representing the many-to-many relationship
+ * between FixEntity and Suggestion entities. This allows one fix entity to be associated
+ * with multiple suggestions and one suggestion to be associated with multiple fix entities.
+ *
+ * @class FixEntitySuggestion
+ * @extends BaseModel
+ */
+class FixEntitySuggestion extends BaseModel {
+  static DEFAULT_UPDATED_BY = 'spacecat';
+
+  /**
+   * Generates the composite keys for the FixEntitySuggestion model.
+   * @returns {Object} - The composite keys.
+   */
+  generateCompositeKeys() {
+    return {
+      suggestionId: this.getSuggestionId(),
+      fixEntityId: this.getFixEntityId(),
+    };
+  }
+}
+
+export default FixEntitySuggestion;

package/src/models/fix-entity-suggestion/fix-entity-suggestion.schema.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import SchemaBuilder from '../base/schema.builder.js';
+import FixEntitySuggestion from './fix-entity-suggestion.model.js';
+import FixEntitySuggestionCollection from './fix-entity-suggestion.collection.js';
+
+/*
+Schema Doc: https://electrodb.dev/en/modeling/schema/
+Attribute Doc: https://electrodb.dev/en/modeling/attributes/
+Indexes Doc: https://electrodb.dev/en/modeling/indexes/
+ */
+
+const schema = new SchemaBuilder(FixEntitySuggestion, FixEntitySuggestionCollection)
+  .withPrimaryPartitionKeys(['suggestionId'])
+  .withPrimarySortKeys(['fixEntityId'])
+  .addReference('belongs_to', 'FixEntity')
+  .addReference('belongs_to', 'Suggestion')
+  .addAttribute('opportunityId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('fixEntityCreatedAt', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('fixEntityCreatedDate', {
+    type: 'string',
+    readOnly: true,
+    watch: ['fixEntityCreatedAt'],
+    set: (_, { fixEntityCreatedAt }) => (fixEntityCreatedAt ? fixEntityCreatedAt.split('T')[0] : undefined),
+  })
+  .addIndex(
+    { composite: ['opportunityId'] },
+    { composite: ['fixEntityCreatedDate', 'updatedAt'] },
+  );
+
+export default schema.build();

package/src/models/fix-entity-suggestion/index.d.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type { BaseCollection, BaseModel, FixEntity, Suggestion } from '../index';
+
+export interface FixEntitySuggestion extends BaseModel {
+  getFixEntity(): Promise<FixEntity>;
+  getSuggestion(): Promise<Suggestion>;
+  getFixEntityId(): string;
+  setFixEntityId(value: string): this;
+  getSuggestionId(): string;
+  setSuggestionId(value: string): this;
+  getFixEntityCreatedAt(): string;
+  setFixEntityCreatedAt(value: string): this;
+  getFixEntityCreatedDate(): string;
+  setFixEntityCreatedDate(value: string): this;
+}
+
+export interface FixEntitySuggestionCollection extends BaseCollection<FixEntitySuggestion> {
+  allBySuggestionId(suggestionId: string): Promise<FixEntitySuggestion[]>;
+  allByFixEntityId(fixEntityId: string): Promise<FixEntitySuggestion[]>;
+  allByOpportunityIdAndFixEntityCreatedDate(opportunityId: string, fixEntityCreatedDate: string): Promise<FixEntitySuggestion[]>;
+}

package/src/models/fix-entity-suggestion/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import FixEntitySuggestion from './fix-entity-suggestion.model.js';
+import FixEntitySuggestionCollection from './fix-entity-suggestion.collection.js';
+
+export {
+  FixEntitySuggestion,
+  FixEntitySuggestionCollection,
+};

package/src/models/index.d.ts

@@ -15,6 +15,7 @@ export type * from './async-job';
 export type * from './configuration';
 export type * from './base';
 export type * from './fix-entity';
+export type * from './fix-entity-suggestion';
 export type * from './experiment';
 export type * from './entitlement';
 export type * from './import-job';

package/src/models/index.js

@@ -17,6 +17,7 @@ export * from './base/index.js';
 export * from './configuration/index.js';
 export * from './entitlement/index.js';
 export * from './fix-entity/index.js';
+export * from './fix-entity-suggestion/index.js';
 export * from './experiment/index.js';
 export * from './import-job/index.js';
 export * from './import-url/index.js';

package/src/models/opportunity/opportunity.model.js

@@ -59,22 +59,151 @@ class Opportunity extends BaseModel {
   /**
    * Adds the given fixEntities to this Opportunity. Sets this opportunity as the parent
    * of each fixEntity, as such the opportunity ID does not need to be provided.
+   * Each fixEntity must contain a suggestions array that will be used to create
+   * FixEntitySuggestion records.
    *
    * @async
    * @param {Array<Object>} fixEntities - An array of fixEntities objects to add.
+   *   Each fixEntity must have a suggestions property with at least one suggestion.
    * @return {Promise<{ createdItems: BaseModel[],
    * errorItems: { item: Object, error: ValidationError }[] }>} - A promise that
    * resolves to an object containing the created fixEntities items and any
    * errors that occurred.
    */
   async addFixEntities(fixEntities) {
-    const childFixEntities = fixEntities.map((fixEntity) => ({
-      ...fixEntity,
-      [this.idName]: this.getId(),
-    }));
-    return this.entityRegistry
-      .getCollection('FixEntityCollection')
-      .createMany(childFixEntities, this);
+    const errorItems = [];
+    const opportunityId = this.getId();
+
+    // Step 1: Input validation - categorize fixEntities into valid and invalid
+    const validFixEntities = [];
+    fixEntities.forEach((fixEntity) => {
+      if (!fixEntity.suggestions) {
+        errorItems.push({
+          item: fixEntity,
+          error: new Error('fixEntity must have a suggestions property'),
+        });
+      } else if (!Array.isArray(fixEntity.suggestions)) {
+        errorItems.push({
+          item: fixEntity,
+          error: new Error('fixEntity.suggestions must be an array'),
+        });
+      } else if (fixEntity.suggestions.length === 0) {
+        errorItems.push({
+          item: fixEntity,
+          error: new Error('fixEntity.suggestions cannot be empty'),
+        });
+      } else {
+        validFixEntities.push(fixEntity);
+      }
+    });
+
+    // If no valid fixEntities, return early
+    if (validFixEntities.length === 0) {
+      return { createdItems: [], errorItems };
+    }
+
+    const fixEntityCollection = this.entityRegistry.getCollection('FixEntityCollection');
+    const suggestionCollection = this.entityRegistry.getCollection('SuggestionCollection');
+    const fixEntitySuggestionCollection = this.entityRegistry
+      .getCollection('FixEntitySuggestionCollection');
+
+    // Step 2: Flatten and fetch all unique suggestion IDs
+    const allSuggestionIds = new Set();
+    validFixEntities.forEach((fixEntity) => {
+      fixEntity.suggestions.forEach((suggestionId) => {
+        allSuggestionIds.add(suggestionId);
+      });
+    });
+
+    const suggestionResults = await suggestionCollection.batchGetByKeys(
+      Array.from(allSuggestionIds).map((suggestionId) => ({
+        [suggestionCollection.idName]: suggestionId,
+      })),
+    );
+
+    // Create a map of suggestionId -> suggestion entity for O(1) retrieval
+    const suggestionMap = new Map();
+    suggestionResults.data.forEach((suggestion) => {
+      suggestionMap.set(suggestion.getId(), suggestion);
+    });
+
+    // Step 3: Validate that all suggestion IDs exist and prepare fixEntities to create
+    const fixEntitiesToCreate = [];
+    validFixEntities.forEach((fixEntity) => {
+      const missingSuggestions = fixEntity.suggestions.filter(
+        (suggestionId) => !suggestionMap.has(suggestionId),
+      );
+
+      if (missingSuggestions.length > 0) {
+        errorItems.push({
+          item: fixEntity,
+          error: new Error(`Invalid suggestion IDs: ${missingSuggestions.join(', ')}`),
+        });
+      } else {
+        fixEntitiesToCreate.push(fixEntity);
+      }
+    });
+
+    // If no valid fixEntities to create, return early
+    if (fixEntitiesToCreate.length === 0) {
+      return { createdItems: [], errorItems };
+    }
+
+    // Step 4: Create FixEntity records
+    const fixEntityCreateResult = await fixEntityCollection.createMany(
+      fixEntitiesToCreate.map((fixEntity) => {
+        const { suggestions: _, ...fixEntityWithoutSuggestions } = fixEntity;
+        return {
+          ...fixEntityWithoutSuggestions,
+          [this.idName]: opportunityId,
+        };
+      }),
+      this,
+    );
+
+    // Add any errors from fix entity creation
+    if (fixEntityCreateResult.errorItems && fixEntityCreateResult.errorItems.length > 0) {
+      // Match error items back to original fixEntities with suggestions
+      fixEntityCreateResult.errorItems.forEach((errorItem) => {
+        const originalIndex = fixEntitiesToCreate.findIndex(
+          (fe) => fe.type === errorItem.item.type
+            && JSON.stringify(fe.changeDetails) === JSON.stringify(errorItem.item.changeDetails),
+        );
+        if (originalIndex !== -1) {
+          errorItems.push({
+            item: fixEntitiesToCreate[originalIndex],
+            error: errorItem.error,
+          });
+        }
+      });
+    }
+
+    // Step 5: Create FixEntitySuggestion junction records
+    const junctionRecordsToCreate = [];
+    fixEntityCreateResult.createdItems.forEach((createdFixEntity, index) => {
+      const originalFixEntity = fixEntitiesToCreate[index];
+      const fixEntityId = createdFixEntity.getId();
+      const fixEntityCreatedAt = createdFixEntity.getCreatedAt();
+
+      originalFixEntity.suggestions.forEach((suggestionId) => {
+        junctionRecordsToCreate.push({
+          opportunityId,
+          fixEntityId,
+          suggestionId,
+          fixEntityCreatedAt,
+        });
+      });
+    });
+
+    // Create all junction records at once
+    if (junctionRecordsToCreate.length > 0) {
+      await fixEntitySuggestionCollection.createMany(junctionRecordsToCreate);
+    }
+
+    return {
+      createdItems: fixEntityCreateResult.createdItems,
+      errorItems,
+    };
   }
 }
 

package/src/models/suggestion/index.d.ts

@@ -10,15 +10,13 @@
  * governing permissions and limitations under the License.
  */
 
-import type { BaseCollection, BaseModel, Opportunity } from '../index';
+import type { BaseCollection, BaseModel, Opportunity, FixEntitySuggestion, FixEntity } from '../index';
 
 export interface Suggestion extends BaseModel {
   getData(): object;
   getKpiDeltas(): object;
   getOpportunity(): Promise<Opportunity>;
   getOpportunityId(): string;
-  getFixEntityId(): string;
-  getFixEntity(): Promise<object>;
   getRank(): number;
   getStatus(): string;
   getType(): string;
@@ -31,9 +29,9 @@ export interface Suggestion extends BaseModel {
 
 export interface SuggestionCollection extends BaseCollection<Suggestion> {
   allByOpportunityId(opportunityId: string): Promise<Suggestion[]>;
-  allByFixEntityId(fixEntityId: string): Promise<Suggestion[]>;
   allByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<Suggestion[]>;
   bulkUpdateStatus(suggestions: Suggestion[], status: string): Promise<Suggestion[]>;
   findByOpportunityId(opportunityId: string): Promise<Suggestion | null>;
   findByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<Suggestion | null>;
+  getFixEntitiesBySuggestionId(suggestionId: string): Promise<{data: Array<FixEntity>, unprocessed: Array<string>}>;
 }

package/src/models/suggestion/suggestion.collection.js

@@ -11,11 +11,18 @@
  */
 
 import BaseCollection from '../base/base.collection.js';
+import DataAccessError from '../../errors/data-access.error.js';
 import Suggestion from './suggestion.model.js';
+import { guardId } from '../../util/guards.js';
 
 /**
  * SuggestionCollection - A collection class responsible for managing Suggestion entities.
- * Extends the BaseCollection to provide specific methods for interacting with Suggestion records.
+ * Extends the BaseCollection to provide specific methods for interacting with Suggestion records
+ * and their relationships with FixEntities.
+ *
+ * This collection provides methods to:
+ * - Update the status of multiple suggestions in bulk
+ * - Retrieve FixEntities associated with a specific Suggestion
  *
  * @class SuggestionCollection
  * @extends BaseCollection
@@ -50,6 +57,40 @@ class SuggestionCollection extends BaseCollection {
 
     return suggestions;
   }
+
+  /**
+   * Gets all FixEntities associated with a specific Suggestion.
+   *
+   * @async
+   * @param {string} suggestionId - The ID of the Suggestion.
+   * @returns {Promise<Array>} - A promise that resolves to an array of FixEntity models
+   * @throws {DataAccessError} - Throws an error if the suggestionId is not provided or if the
+   *   query fails.
+   */
+  async getFixEntitiesBySuggestionId(suggestionId) {
+    guardId('suggestionId', suggestionId, 'SuggestionCollection');
+
+    try {
+      const fixEntitySuggestionCollection = this.entityRegistry.getCollection('FixEntitySuggestionCollection');
+      const fixEntityCollection = this.entityRegistry.getCollection('FixEntityCollection');
+
+      // Get all junction records for this suggestion
+      const fixEntitySuggestions = await fixEntitySuggestionCollection
+        .allBySuggestionId(suggestionId);
+
+      if (fixEntitySuggestions.length === 0) {
+        return [];
+      }
+
+      const fixEntityIds = fixEntitySuggestions.map((record) => record.getFixEntityId());
+      const result = await fixEntityCollection
+        .batchGetByKeys(fixEntityIds.map((id) => ({ [fixEntityCollection.idName]: id })));
+      return result.data;
+    } catch (error) {
+      this.log.error('Failed to get fix entities for suggestion', error);
+      throw new DataAccessError('Failed to get fix entities for suggestion', this, error);
+    }
+  }
 }
 
 export default SuggestionCollection;

package/src/models/suggestion/suggestion.schema.js

@@ -26,7 +26,7 @@ Indexes Doc: https://electrodb.dev/en/modeling/indexes/
 
 const schema = new SchemaBuilder(Suggestion, SuggestionCollection)
   .addReference('belongs_to', 'Opportunity', ['status', 'rank'])
-  .addReference('belongs_to', 'FixEntity', ['updatedAt'], { required: false })
+  .addReference('has_many', 'FixEntitySuggestion', ['updatedAt'], { removeDependents: true })
   .addAttribute('type', {
     type: Object.values(Suggestion.TYPES),
     required: true,

package/src/util/util.js

@@ -12,6 +12,7 @@
 
 import { hasText, isInteger } from '@adobe/spacecat-shared-utils';
 import pluralize from 'pluralize';
+import { guardArray } from './guards.js';
 
 const capitalize = (str) => (hasText(str) ? str[0].toUpperCase() + str.slice(1) : '');
 
@@ -94,6 +95,19 @@ const zeroPad = (num, length) => {
     : '0'.repeat(length - str.length) + str;
 };
 
+const resolveUpdates = (existingItems, newItems) => {
+  guardArray('existingItems', existingItems, 'resolveUpdates');
+  guardArray('newItems', newItems, 'resolveUpdates');
+
+  // Deduplicate new items
+  const dedupedNew = [...new Set(newItems)];
+
+  const toDelete = existingItems.filter((item) => !dedupedNew.includes(item));
+  const toCreate = dedupedNew.filter((item) => !existingItems.includes(item));
+
+  return { toDelete, toCreate };
+};
+
 export {
   capitalize,
   classExtends,
@@ -113,4 +127,5 @@ export {
   sanitizeIdAndAuditFields,
   sanitizeTimestamps,
   zeroPad,
+  resolveUpdates,
 };