@adobe/spacecat-shared-data-access 1.55.0 → 1.57.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-data-access-v1.57.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.56.0...@adobe/spacecat-shared-data-access-v1.57.0) (2024-11-22)
+
+
+### Features
+
+* batch create/update items & open oppty type ([#450](https://github.com/adobe/spacecat-shared/issues/450)) ([642beaf](https://github.com/adobe/spacecat-shared/commit/642beaf3ab1ef9494f00c2148241d3986cca7fe7))
+
+# [@adobe/spacecat-shared-data-access-v1.56.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.55.0...@adobe/spacecat-shared-data-access-v1.56.0) (2024-11-21)
+
+
+### Features
+
+* introduce missing audit id property ([#452](https://github.com/adobe/spacecat-shared/issues/452)) ([c17e447](https://github.com/adobe/spacecat-shared/commit/c17e447b275d9788d587dc44f3043fb60e83c51b))
+
 # [@adobe/spacecat-shared-data-access-v1.55.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.54.0...@adobe/spacecat-shared-data-access-v1.55.0) (2024-11-20)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {
@@ -34,10 +34,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@adobe/spacecat-shared-dynamo": "1.3.47",
-    "@adobe/spacecat-shared-utils": "1.22.4",
-    "@aws-sdk/client-dynamodb": "3.693.0",
-    "@aws-sdk/lib-dynamodb": "3.693.0",
+    "@adobe/spacecat-shared-dynamo": "1.3.49",
+    "@adobe/spacecat-shared-utils": "1.23.0",
+    "@aws-sdk/client-dynamodb": "3.696.0",
+    "@aws-sdk/lib-dynamodb": "3.696.0",
     "@types/joi": "17.2.3",
     "aws-xray-sdk": "3.10.2",
     "electrodb": "3.0.1",

package/src/dto/audit.js

@@ -43,6 +43,7 @@ export const AuditDto = {
     } : {};
 
     return {
+      id: audit.getId(),
       siteId: audit.getSiteId(),
       auditedAt: audit.getAuditedAt(),
       auditResult: audit.getAuditResult(),
@@ -62,6 +63,7 @@ export const AuditDto = {
    */
   fromDynamoItem: (dynamoItem) => {
     const auditData = {
+      id: dynamoItem.id,
       siteId: dynamoItem.siteId,
       auditedAt: dynamoItem.auditedAt,
       auditResult: dynamoItem.auditResult,

package/src/index.d.ts

@@ -33,6 +33,12 @@ export declare const ImportUrlStatus: {
  * Represents an individual audit of a site.
  */
 export interface Audit {
+
+  /**
+   * Retrieves the ID of the audit.
+   * @returns {string} The audit ID.
+   */
+  getId: () => string;
   /**
    * Retrieves the site ID associated with this audit.
    * @returns {string} The site ID.

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

@@ -12,6 +12,9 @@
 
 import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
 
+import { ElectroValidationError } from 'electrodb';
+
+import ValidationError from '../errors/validation.error.js';
 import { guardId } from '../util/guards.js';
 
 /**
@@ -75,6 +78,10 @@ class BaseCollection {
     return records.data.map((record) => this._createInstance({ data: record }));
   }
 
+  _getEnumValues(fieldName) {
+    return this.entity.model.schema.attributes[fieldName]?.enumArray;
+  }
+
   /**
    * Finds an entity by its ID.
    * @async
@@ -92,27 +99,130 @@ class BaseCollection {
   }
 
   /**
-   * Creates a new entity in the collection.
+   * Creates a new entity in the collection and directly persists it to the database.
+   * There is no need to call the save method (which is for updates only) after creating
+   * the entity.
    * @async
-   * @param {Object} data - The data for the entity to be created.
+   * @param {Object} item - The data for the entity to be created.
    * @returns {Promise<BaseModel>} - A promise that resolves to the created model instance.
    * @throws {Error} - Throws an error if the data is invalid or if the creation process fails.
    */
-  async create(data) {
-    if (!isNonEmptyObject(data)) {
-      this.log.error(`Failed to create [${this.entityName}]: data is required`);
-      throw new Error(`Failed to create [${this.entityName}]: data is required`);
+  async create(item) {
+    if (!isNonEmptyObject(item)) {
+      const message = `Failed to create [${this.entityName}]: data is required`;
+      this.log.error(message);
+      throw new Error(message);
     }
 
     try {
+      // todo: catch ElectroDB validation errors and re-throws as ValidationError
       // todo: validate associations
-      const record = await this.entity.create(data).go();
+      const record = await this.entity.create(item).go();
       return this._createInstance(record);
     } catch (error) {
       this.log.error(`Failed to create [${this.entityName}]`, error);
       throw error;
     }
   }
+
+  /**
+   * Creates multiple entities in the collection and directly persists them to the database in
+   * a batch write operation. Batches are written in parallel and are limited to 25 items per batch.
+   *
+   * @async
+   * @param {Array<Object>} newItems - An array of data for the entities to be created.
+   * @return {Promise<{ createdItems: BaseModel[],
+   * errorItems: { item: Object, error: ElectroValidationError }[] }>} - A promise that resolves to
+   * an object containing the created items and any items that failed validation.
+   * @throws {ValidationError} - Throws a validation error if any of the items has validation
+   * failures.
+   */
+  async createMany(newItems) {
+    if (!Array.isArray(newItems) || newItems.length === 0) {
+      const message = `Failed to create many [${this.entityName}]: items must be a non-empty array`;
+      this.log.error(message);
+      throw new Error(message);
+    }
+
+    try {
+      const validatedItems = [];
+      const errorItems = [];
+      const createdItems = [];
+
+      newItems.forEach((item) => {
+        try {
+          this.entity.put(item).params();
+          validatedItems.push(item);
+        } catch (error) {
+          if (error instanceof ElectroValidationError) {
+            errorItems.push({ item, error: new ValidationError(error) });
+          }
+        }
+      });
+
+      /**
+       * ElectroDB does not return the created items in the response for batch write operations.
+       * This listener intercepts the batch write requests and extracts the items before they
+       * are stored in the database.
+       * @param {Object} result - The result of the operation.
+       */
+      const requestItemsListener = (result) => {
+        if (result?.type !== 'query' || result?.method !== 'batchWrite') {
+          return;
+        }
+
+        result.params?.RequestItems[this.entity.model.table].forEach((putRequest) => {
+          createdItems.push(putRequest.PutRequest.Item);
+        });
+      };
+
+      let records = [];
+      if (validatedItems.length > 0) {
+        const response = await this.entity.put(validatedItems).go(
+          { listeners: [requestItemsListener] },
+        );
+        records = this._createInstances({ data: createdItems });
+
+        if (Array.isArray(response.unprocessed) && response.unprocessed.length > 0) {
+          this.log.error(`Failed to process all items in batch write for [${this.entityName}]: ${JSON.stringify(response.unprocessed)}`);
+        }
+      }
+
+      return { createdItems: records, errorItems };
+    } catch (error) {
+      this.log.error(`Failed to create many [${this.entityName}]`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates a collection of entities in the database using a batch write (put) operation.
+   *
+   * @async
+   * @param {Array<BaseModel>} items - An array of model instances to be updated.
+   * @return {Promise<void>} - A promise that resolves when the update operation is complete.
+   * @throws {Error} - Throws an error if the update operation fails.
+   * @protected
+   */
+  async _saveMany(items) {
+    if (!Array.isArray(items) || items.length === 0) {
+      const message = `Failed to save many [${this.entityName}]: items must be a non-empty array`;
+      this.log.error(message);
+      throw new Error(message);
+    }
+
+    try {
+      const updates = items.map((item) => item.record);
+      const response = await this.entity.put(updates).go();
+
+      if (response.unprocessed) {
+        this.log.error(`Failed to process all items in batch write for [${this.entityName}]: ${JSON.stringify(response.unprocessed)}`);
+      }
+    } catch (error) {
+      this.log.error(`Failed to save many [${this.entityName}]`, error);
+      throw error;
+    }
+  }
 }
 
 export default BaseCollection;

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

@@ -25,6 +25,8 @@ export interface BaseModel {
  * Interface representing an Opportunity model, extending BaseModel.
  */
 export interface Opportunity extends BaseModel {
+  // eslint-disable-next-line no-use-before-define
+  addSuggestions(suggestions: object[]): Promise<Suggestion[]>;
   // eslint-disable-next-line no-use-before-define
   getSuggestions(): Promise<Suggestion[]>;
   getSiteId(): string;
@@ -73,7 +75,8 @@ export interface Suggestion extends BaseModel {
  */
 export interface BaseCollection<T extends BaseModel> {
   findById(id: string): Promise<T>;
-  create(data: object): Promise<T>;
+  create(item: object): Promise<T>;
+  createMany(items: object[]): Promise<T[]>;
 }
 
 /**
@@ -90,6 +93,7 @@ export interface OpportunityCollection extends BaseCollection<Opportunity> {
 export interface SuggestionCollection extends BaseCollection<Suggestion> {
   allByOpportunityId(opportunityId: string): Promise<Suggestion[]>;
   allByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<Suggestion[]>;
+  bulkUpdateStatus(suggestions: Suggestion[], status: string): Promise<Suggestion[]>;
 }
 
 /**

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

@@ -22,6 +22,25 @@ import BaseModel from './base.model.js';
  */
 
 class Opportunity extends BaseModel {
+  /**
+   * Adds the given suggestions to this Opportunity. Sets this opportunity as the parent
+   * of each suggestion, as such the opportunity ID does not need to be provided.
+   *
+   * @async
+   * @param {Array<Object>} suggestions - An array of suggestion objects to add.
+   * @return {Promise<{ createdItems: BaseModel[],
+   * errorItems: { item: Object, error: ValidationError }[] }>} - A promise that
+   * resolves to an object containing the created suggestion items and any
+   * errors that occurred.
+   */
+  async addSuggestions(suggestions) {
+    const childSuggestions = suggestions.map((suggestion) => ({
+      ...suggestion,
+      [this.idName]: this.getId(),
+    }));
+    return this._getAssociation('SuggestionCollection', 'createMany', childSuggestions);
+  }
+
   /**
    * Retrieves all Suggestion entities associated to this Opportunity.
    * @async

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

@@ -38,7 +38,7 @@ class SuggestionCollection extends BaseCollection {
    * Retrieves all Suggestion entities by their associated Opportunity ID.
    * @async
    * @param {string} opportunityId - The unique identifier of the associated Opportunity.
-   * @returns {Promise<Array<Suggestion>>} - A promise that resolves to an array of Suggestion
+   * @returns {Promise<Suggestion[]>} - A promise that resolves to an array of Suggestion
    * instances related to the given Opportunity ID.
    * @throws {Error} - Throws an error if the opportunityId is not provided or if the query fails.
    */
@@ -75,6 +75,37 @@ class SuggestionCollection extends BaseCollection {
 
     return this._createInstances(records);
   }
+
+  /**
+   * Updates the status of multiple given suggestions. The given status must conform
+   * to the status enum defined in the Suggestion schema.
+   * Saves the updated suggestions to the database automatically.
+   * You don't need to call save() on the suggestions after calling this method.
+   * @async
+   * @param {Suggestion[]} suggestions - An array of Suggestion instances to update.
+   * @param {string} status - The new status to set for the suggestions.
+   * @return {Promise<*>} - A promise that resolves to the updated suggestions.
+   * @throws {Error} - Throws an error if the suggestions are not provided
+   * or if the status is invalid.
+   */
+  async bulkUpdateStatus(suggestions, status) {
+    if (!Array.isArray(suggestions)) {
+      throw new Error('Suggestions must be an array');
+    }
+
+    const validStatuses = this._getEnumValues('status');
+    if (!validStatuses?.includes(status)) {
+      throw new Error(`Invalid status: ${status}. Must be one of: ${validStatuses.join(', ')}`);
+    }
+
+    suggestions.forEach((suggestion) => {
+      suggestion.setStatus(status);
+    });
+
+    await this._saveMany(suggestions);
+
+    return suggestions;
+  }
 }
 
 export default SuggestionCollection;

package/src/v2/schema/opportunity.schema.js

@@ -53,7 +53,7 @@ const OpportunitySchema = {
       validation: (value) => !isValidUrl(value),
     },
     type: {
-      type: ['broken-backlinks', 'broken-internal-links'],
+      type: 'string',
       readOnly: true,
       required: true,
     },

package/src/v2/util/patcher.js

@@ -45,6 +45,7 @@ class Patcher {
     this.model = entity.model;
     this.idName = `${this.model.name.toLowerCase()}Id`;
     this.record = record;
+    this.updates = {};
 
     this.patchRecord = null;
   }
@@ -104,6 +105,7 @@ class Patcher {
       [propertyName]: value,
     });
     this.record[propertyName] = value;
+    this.updates[propertyName] = value;
   }
 
   /**
@@ -175,9 +177,20 @@ class Patcher {
    * @throws {Error} - Throws an error if the save operation fails.
    */
   async save() {
+    if (!this.hasUpdates()) {
+      return;
+    }
     await this.#getPatchRecord().go();
     this.record.updatedAt = new Date().getTime();
   }
+
+  getUpdates() {
+    return this.updates;
+  }
+
+  hasUpdates() {
+    return Object.keys(this.updates).length > 0;
+  }
 }
 
 export default Patcher;