@adobe/spacecat-shared-data-access 1.59.2 → 1.60.0

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

@@ -1,275 +0,0 @@
-/*
- * Copyright 2024 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 { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
-
-import { ElectroValidationError } from 'electrodb';
-
-import ValidationError from '../errors/validation.error.js';
-import { guardId } from '../util/guards.js';
-import { keyNamesToIndexName } from '../util/reference.js';
-
-/**
- * BaseCollection - A base class for managing collections of entities in the application.
- * This class uses ElectroDB to interact with entities and provides common functionality
- * for data operations.
- *
- * @class BaseCollection
- */
-class BaseCollection {
-  /**
-   * Constructs an instance of BaseCollection.
-   * @constructor
-   * @param {Object} electroService - The ElectroDB service used for managing entities.
-   * @param {Object} modelFactory - A factory for creating model instances.
-   * @param {BaseModel} clazz - The model class that represents the entity.
-   * @param {Object} log - A logger for capturing logging information.
-   */
-  constructor(electroService, modelFactory, clazz, log) {
-    this.electroService = electroService;
-    this.modelFactory = modelFactory;
-    this.clazz = clazz;
-    this.entityName = this.clazz.name.toLowerCase();
-    this.entity = electroService.entities[this.entityName];
-    this.idName = `${this.entityName}Id`;
-    this.log = log;
-  }
-
-  /**
-   * Creates an instance of a model from a record.
-   * @private
-   * @param {Object} record - The record containing data to create the model instance.
-   * @returns {BaseModel|null} - Returns an instance of the model class if the data is valid,
-   * otherwise null.
-   */
-  #createInstance(record) {
-    if (!isNonEmptyObject(record?.data)) {
-      this.log.warn(`Failed to create instance of [${this.entityName}]: record is empty`);
-      return null;
-    }
-    // eslint-disable-next-line new-cap
-    return new this.clazz(
-      this.electroService,
-      this.modelFactory,
-      record.data,
-      this.log,
-    );
-  }
-
-  /**
-   * Creates instances of models from a set of records.
-   * @private
-   * @param {Object} records - The records containing data to create the model instances.
-   * @returns {Array<BaseModel>} - An array of instances of the model class.
-   */
-  #createInstances(records) {
-    if (!Array.isArray(records?.data)) {
-      this.log.warn(`Failed to create instances of [${this.entityName}]: records are empty`);
-      return [];
-    }
-    return records.data.map((record) => this.#createInstance({ data: record }));
-  }
-
-  /**
-   * Retrieves the enum values for a field in the entity schema. Useful for validating
-   * enum values prior to creating or updating an entity.
-   * @param {string} fieldName - The name of the field to retrieve enum values for.
-   * @return {string[]} - An array of enum values for the field.
-   * @protected
-   */
-  _getEnumValues(fieldName) {
-    return this.entity.model.schema.attributes[fieldName]?.enumArray;
-  }
-
-  /**
-   * Finds an entity by its ID.
-   * @async
-   * @param {string} id - The unique identifier of the entity to be found.
-   * @returns {Promise<BaseModel|null>} - A promise that resolves to an instance of
-   * the model if found, otherwise null.
-   * @throws {Error} - Throws an error if the ID is not provided.
-   */
-  async findById(id) {
-    guardId(this.idName, id, this.entityName);
-
-    const record = await this.entity.get({ [this.idName]: id }).go();
-
-    return this.#createInstance(record);
-  }
-
-  /**
-   * Finds entities by a set of index keys. Index keys are used to query entities by
-   * a specific index defined in the entity schema. The index keys must match the
-   * fields defined in the index.
-   * @param {Object} keys - The index keys to use for the query.
-   * @return {Promise<Array<BaseModel>>} - A promise that resolves to an array of model instances.
-   * @throws {Error} - Throws an error if the index keys are not provided or if the index
-   * is not found.
-   * @async
-   */
-  async findByIndexKeys(keys) {
-    if (!isNonEmptyObject(keys)) {
-      const message = `Failed to find by index keys [${this.entityName}]: keys are required`;
-      this.log.error(message);
-      throw new Error(message);
-    }
-
-    const indexName = keyNamesToIndexName(Object.keys(keys));
-    const index = this.entity.query[indexName];
-
-    if (!index) {
-      const message = `Failed to find by index keys [${this.entityName}]: index [${indexName}] not found`;
-      this.log.error(message);
-      throw new Error(message);
-    }
-
-    const records = await index(keys).go();
-
-    return this.#createInstances(records);
-  }
-
-  /**
-   * 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} 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(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(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.
-   * @param {BaseModel} [parent] - Optional parent entity that these items are associated with.
-   * @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, parent = null) {
-    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)}`);
-        }
-      }
-
-      if (parent) {
-        records.forEach((record) => {
-          // eslint-disable-next-line no-underscore-dangle
-          record._cacheReference(parent.entity.model.name, parent);
-        });
-      }
-
-      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/model.factory.js

@@ -1,74 +0,0 @@
-/*
- * Copyright 2024 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 OpportunityCollection from './opportunity.collection.js';
-import SuggestionCollection from './suggestion.collection.js';
-
-/**
- * ModelFactory - A factory class responsible for creating and managing collections
- * of different models. This class serves as a centralized point for accessing and
- * instantiating model collections.
- *
- * @class ModelFactory
- */
-class ModelFactory {
-  /**
-   * Constructs an instance of ModelFactory.
-   * @constructor
-   * @param {Object} service - The ElectroDB service instance used to manage entities.
-   * @param {Object} logger - A logger for capturing and logging information.
-   */
-  constructor(service, logger) {
-    this.service = service;
-    this.logger = logger;
-    this.models = new Map();
-
-    this.initialize();
-  }
-
-  /**
-   * Initializes the collections managed by the ModelFactory.
-   * This method creates instances of each collection and stores them in an internal map.
-   * @private
-   */
-  initialize() {
-    const opportunityCollection = new OpportunityCollection(
-      this.service,
-      this,
-      this.logger,
-    );
-    const suggestionCollection = new SuggestionCollection(
-      this.service,
-      this,
-      this.logger,
-    );
-
-    this.models.set(OpportunityCollection.name, opportunityCollection);
-    this.models.set(SuggestionCollection.name, suggestionCollection);
-  }
-
-  /**
-   * Gets a collection instance by its name.
-   * @param {string} collectionName - The name of the collection to retrieve.
-   * @returns {Object} - The requested collection instance.
-   * @throws {Error} - Throws an error if the collection with the specified name is not found.
-   */
-  getCollection(collectionName) {
-    const collection = this.models.get(collectionName);
-    if (!collection) {
-      throw new Error(`Collection ${collectionName} not found`);
-    }
-    return collection;
-  }
-}
-
-export default ModelFactory;

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

@@ -1,74 +0,0 @@
-/*
- * Copyright 2024 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 { hasText } from '@adobe/spacecat-shared-utils';
-
-import BaseCollection from './base.collection.js';
-import Opportunity from './opportunity.model.js';
-
-/**
- * OpportunityCollection - A collection class responsible for managing Opportunity entities.
- * Extends the BaseCollection to provide specific methods for interacting with Opportunity records.
- *
- * @class OpportunityCollection
- * @extends BaseCollection
- */
-class OpportunityCollection extends BaseCollection {
-  /**
-   * Constructs an instance of OpportunityCollection. Tells the base class which model to use.
-   * @constructor
-   * @param {Object} service - The ElectroDB service instance used to manage Opportunity entities.
-   * @param {Object} modelFactory - A factory for creating model instances.
-   * @param {Object} log - A logger for capturing logging information.
-   */
-  constructor(service, modelFactory, log) {
-    super(service, modelFactory, Opportunity, log);
-  }
-
-  /**
-   * Retrieves all Opportunity entities by their associated site ID.
-   * @async
-   * @param {string} siteId - The unique identifier of the site.
-   * @returns {Promise<Array<Opportunity>>} - A promise that resolves to an array of
-   * Opportunity instances related to the given site ID.
-   * @throws {Error} - Throws an error if the siteId is not provided or if the query fails.
-   */
-  async allBySiteId(siteId) {
-    if (!hasText(siteId)) {
-      throw new Error('SiteId is required');
-    }
-    return this.findByIndexKeys({ siteId });
-  }
-
-  /**
-   * Retrieves all Opportunity entities by their associated site ID and status.
-   * @param {string} siteId - The unique identifier of the site.
-   * @param {string} status - The status of the Opportunity entities to retrieve.
-   * @return {Promise<Array<BaseModel>>} - A promise that resolves to an array of
-   * Opportunity instances.
-   * @throws {Error} - Throws an error if the siteId or status is not provided or if the
-   * query fails.
-   */
-  async allBySiteIdAndStatus(siteId, status) {
-    if (!hasText(siteId)) {
-      throw new Error('SiteId is required');
-    }
-
-    if (!hasText(status)) {
-      throw new Error('Status is required');
-    }
-
-    return this.findByIndexKeys({ siteId, status });
-  }
-}
-
-export default OpportunityCollection;

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

@@ -1,104 +0,0 @@
-/*
- * Copyright 2024 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 { hasText } from '@adobe/spacecat-shared-utils';
-
-import BaseCollection from './base.collection.js';
-import Suggestion from './suggestion.model.js';
-
-/**
- * SuggestionCollection - A collection class responsible for managing Suggestion entities.
- * Extends the BaseCollection to provide specific methods for interacting with Suggestion records.
- *
- * @class SuggestionCollection
- * @extends BaseCollection
- */
-class SuggestionCollection extends BaseCollection {
-  /**
-   * Constructs an instance of SuggestionCollection. Tells the base class which model to use.
-   * @constructor
-   * @param {Object} service - The ElectroDB service instance used to manage Suggestion entities.
-   * @param {Object} modelFactory - A factory for creating model instances.
-   * @param {Object} log - A logger for capturing logging information.
-   */
-  constructor(service, modelFactory, log) {
-    super(service, modelFactory, Suggestion, log);
-  }
-
-  /**
-   * Retrieves all Suggestion entities by their associated Opportunity ID.
-   * @async
-   * @param {string} opportunityId - The unique identifier of the associated Opportunity.
-   * @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.
-   */
-  async allByOpportunityId(opportunityId) {
-    if (!hasText(opportunityId)) {
-      throw new Error('OpportunityId is required');
-    }
-    return this.findByIndexKeys({ opportunityId });
-  }
-
-  /**
-   * Retrieves all Suggestion entities by their associated Opportunity ID and status.
-   * @param {string} opportunityId - The unique identifier of the associated Opportunity.
-   * @param {string} status - The status of the Suggestion entities
-   * @return {Promise<BaseModel[]>} - A promise that resolves to an array of
-   * Suggestion instances.
-   * @throws {Error} - Throws an error if the opportunityId or status is not provided.
-   */
-  async allByOpportunityIdAndStatus(opportunityId, status) {
-    if (!hasText(opportunityId)) {
-      throw new Error('OpportunityId is required');
-    }
-
-    if (!hasText(status)) {
-      throw new Error('Status is required');
-    }
-
-    return this.findByIndexKeys({ opportunityId, status });
-  }
-
-  /**
-   * 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

@@ -1,159 +0,0 @@
-/*
- * Copyright 2024 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.
- */
-
-/* c8 ignore start */
-
-import { isNonEmptyObject, isValidUrl } from '@adobe/spacecat-shared-utils';
-
-import { validate as uuidValidate, v4 as uuid } from 'uuid';
-
-/*
-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 OpportunitySchema = {
-  model: {
-    entity: 'Opportunity',
-    version: '1',
-    service: 'SpaceCat',
-  },
-  attributes: {
-    opportunityId: {
-      type: 'string',
-      required: true,
-      readOnly: true,
-      // https://electrodb.dev/en/modeling/attributes/#default
-      default: () => uuid(),
-      // https://electrodb.dev/en/modeling/attributes/#attribute-validation
-      validate: (value) => uuidValidate(value),
-    },
-    siteId: {
-      type: 'string',
-      required: true,
-      validate: (value) => uuidValidate(value),
-    },
-    auditId: {
-      type: 'string',
-      required: true,
-      validate: (value) => uuidValidate(value),
-    },
-    runbook: {
-      type: 'string',
-      validate: (value) => !value || isValidUrl(value),
-    },
-    type: {
-      type: 'string',
-      readOnly: true,
-      required: true,
-    },
-    data: {
-      type: 'any',
-      required: false,
-      validate: (value) => !value || isNonEmptyObject(value),
-    },
-    origin: {
-      type: ['ESS_OPS', 'AI', 'AUTOMATION'],
-      required: true,
-    },
-    title: {
-      type: 'string',
-      required: true,
-    },
-    description: {
-      type: 'string',
-      required: false,
-    },
-    status: {
-      type: ['NEW', 'IN_PROGRESS', 'IGNORED', 'RESOLVED'],
-      required: true,
-      default: () => 'NEW',
-    },
-    guidance: {
-      type: 'any',
-      required: false,
-      validate: (value) => !value || isNonEmptyObject(value),
-    },
-    tags: {
-      type: 'set',
-      items: 'string',
-      required: false,
-    },
-    createdAt: {
-      type: 'number',
-      readOnly: true,
-      required: true,
-      default: () => Date.now(),
-      set: () => Date.now(),
-    },
-    updatedAt: {
-      type: 'number',
-      watch: '*',
-      required: true,
-      default: () => Date.now(),
-      set: () => Date.now(),
-    },
-    // todo: add createdBy, updatedBy and auto-set from auth context
-  },
-  indexes: {
-    primary: { // operates on the main table, no 'index' property
-      pk: {
-        field: 'pk',
-        composite: ['opportunityId'],
-      },
-      sk: {
-        field: 'sk',
-        composite: [],
-      },
-    },
-    bySiteId: {
-      index: 'spacecat-data-opportunity-by-site',
-      pk: {
-        field: 'gsi1pk',
-        composite: ['siteId'],
-      },
-      sk: {
-        field: 'gsi1sk',
-        composite: ['opportunityId'],
-      },
-    },
-    bySiteIdAndStatus: {
-      index: 'spacecat-data-opportunity-by-site-and-status',
-      pk: {
-        field: 'gsi2pk',
-        composite: ['siteId', 'status'],
-      },
-      sk: {
-        field: 'gsi2sk',
-        composite: ['updatedAt'],
-      },
-    },
-  },
-};
-
-/**
- * References to other entities. This is not part of the standard ElectroDB schema, but is used
- * to define relationships between entities in our data layer API.
- * @type {{belongs_to: [{type: string, target: string}]}}
- */
-OpportunitySchema.references = {
-  has_many: [
-    { type: 'has_many', target: 'Suggestions' },
-  ],
-  belongs_to: [
-    { type: 'belongs_to', target: 'Site' },
-    { type: 'belongs_to', target: 'Audit' },
-  ],
-};
-
-export default OpportunitySchema;