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

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

@@ -0,0 +1,74 @@
+/*
+ * 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

@@ -0,0 +1,78 @@
+/*
+ * 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');
+    }
+
+    const records = await this.entity.query.bySiteId({ siteId }).go();
+
+    return this._createInstances(records);
+  }
+
+  /**
+   * 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');
+    }
+
+    const records = await this.entity.query.bySiteIdAndStatus({ siteId, status }).go();
+    return this._createInstances(records);
+  }
+}
+
+export default OpportunityCollection;

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

@@ -0,0 +1,238 @@
+/*
+ * 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 BaseModel from './base.model.js';
+
+/**
+ * Opportunity - A class representing an Opportunity entity.
+ * Provides methods to access and manipulate Opportunity-specific data,
+ * such as related suggestions, audit IDs, site IDs, etc.
+ *
+ * @class Opportunity
+ * @extends BaseModel
+ */
+
+class Opportunity extends BaseModel {
+  /**
+   * Retrieves all Suggestion entities associated to this Opportunity.
+   * @async
+   * @returns {Promise<Array<Suggestion>>} - A promise that resolves to an array of Suggestion
+   * instances associated with this Opportunity.
+   */
+  async getSuggestions() {
+    return this._getAssociation(
+      'SuggestionCollection',
+      'allByOpportunityId',
+      this.getId(),
+    );
+  }
+
+  /**
+   * Gets the ID of the site associated with this Opportunity.
+   * @returns {string} - The unique identifier of the site.
+   */
+  getSiteId() {
+    return this.record.siteId;
+  }
+
+  /**
+   * Sets the site ID for this Opportunity (associates it with a site).
+   * @param {string} siteId - The unique identifier of the site.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the siteId is not a valid UUID.
+   */
+  setSiteId(siteId) {
+    this.patcher.patchValue('siteId', siteId, true);
+    return this;
+  }
+
+  /**
+   * Gets the ID of the audit associated with this Opportunity.
+   * @returns {string} - The unique identifier of the audit.
+   */
+  getAuditId() {
+    return this.record.auditId;
+  }
+
+  /**
+   * Sets the audit ID for this Opportunity (associates it with an audit).
+   * @param {string} auditId - The unique identifier of the audit.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the auditId is not a valid UUID.
+   */
+  setAuditId(auditId) {
+    this.patcher.patchValue('auditId', auditId, true);
+    return this;
+  }
+
+  /**
+   * Gets the runbook URL or reference for this Opportunity.
+   * @returns {string} - The runbook reference for this Opportunity.
+   */
+  getRunbook() {
+    return this.record.runbook;
+  }
+
+  /**
+   * Sets the runbook URL or reference for this Opportunity.
+   * @param {string} runbook - The runbook reference or URL.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the runbook is not a string or empty.
+   */
+  setRunbook(runbook) {
+    this.patcher.patchValue('runbook', runbook);
+    return this;
+  }
+
+  /**
+   * Gets the guidance information for this Opportunity.
+   * @returns {Object} - The guidance object for this Opportunity.
+   */
+  getGuidance() {
+    return this.record.guidance;
+  }
+
+  /**
+   * Sets the guidance information for this Opportunity.
+   * @param {Object} guidance - The guidance object.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the guidance is not an object or empty.
+   */
+  setGuidance(guidance) {
+    this.patcher.patchValue('guidance', guidance);
+    return this;
+  }
+
+  /**
+   * Gets the title of this Opportunity.
+   * @returns {string} - The title of the Opportunity.
+   */
+  getTitle() {
+    return this.record.title;
+  }
+
+  /**
+   * Sets the title of this Opportunity.
+   * @param {string} title - The title of the Opportunity.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the title is not a string or empty.
+   */
+  setTitle(title) {
+    this.patcher.patchValue('title', title);
+    return this;
+  }
+
+  /**
+   * Gets the description of this Opportunity.
+   * @returns {string} - The description of the Opportunity.
+   */
+  getDescription() {
+    return this.record.description;
+  }
+
+  /**
+   * Sets the description of this Opportunity.
+   * @param {string} description - The description of the Opportunity.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the description is not a string or empty.
+   */
+  setDescription(description) {
+    this.patcher.patchValue('description', description);
+    return this;
+  }
+
+  /**
+   * Gets the type of this Opportunity.
+   * @returns {string} - The type of the Opportunity.
+   */
+  getType() {
+    return this.record.type;
+  }
+
+  /**
+   * Gets the status of this Opportunity.
+   * @returns {string} - The status of the Opportunity.
+   */
+  getStatus() {
+    return this.record.status;
+  }
+
+  /**
+   * Sets the status of this Opportunity. Check the schema for valid status values.
+   * @param {string} status - The status of the Opportunity.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the status is not a valid value.
+   */
+  setStatus(status) {
+    this.patcher.patchValue('status', status);
+    return this;
+  }
+
+  /**
+   * Gets the origin of this Opportunity.
+   * @returns {string} - The origin of the Opportunity (e.g., ESS_OPS, AI, AUTOMATION).
+   */
+  getOrigin() {
+    return this.record.origin;
+  }
+
+  /**
+   * Sets the origin of this Opportunity. Check the schema for valid origin values.
+   * @param {string} origin - The origin of the Opportunity.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the origin is not a valid value.
+   */
+  setOrigin(origin) {
+    this.patcher.patchValue('origin', origin);
+    return this;
+  }
+
+  /**
+   * Gets the tags associated with this Opportunity.
+   * @returns {Array<string>} - An array of tags associated with the Opportunity.
+   */
+  getTags() {
+    return this.record.tags;
+  }
+
+  /**
+   * Sets the tags for this Opportunity. Duplicate tags are made unique.
+   * @param {Array<string>} tags - An array of tags to associate with the Opportunity.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the tags are not an array.
+   */
+  setTags(tags) {
+    this.patcher.patchValue('tags', tags);
+    return this;
+  }
+
+  /**
+   * Gets additional data associated with this Opportunity.
+   * @returns {Object} - The additional data for the Opportunity.
+   */
+  getData() {
+    return this.record.data;
+  }
+
+  /**
+   * Sets additional data for this Opportunity.
+   * @param {Object} data - The data to set for the Opportunity.
+   * @returns {Opportunity} - The current instance of Opportunity for chaining.
+   * @throws {Error} - Throws an error if the data is not a valid object.
+   */
+  setData(data) {
+    this.patcher.patchValue('data', data);
+    return this;
+  }
+}
+
+export default Opportunity;

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

@@ -0,0 +1,80 @@
+/*
+ * 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<Array<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');
+    }
+
+    const records = await this.entity.query.byOpportunityId({ opportunityId }).go();
+
+    return this._createInstances(records);
+  }
+
+  /**
+   * 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<Array<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');
+    }
+
+    const records = await this.entity.query.byOpportunityIdAndStatus(
+      { opportunityId, status },
+    ).go();
+
+    return this._createInstances(records);
+  }
+}
+
+export default SuggestionCollection;

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

@@ -0,0 +1,138 @@
+/*
+ * 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 BaseModel from './base.model.js';
+
+/**
+ * Suggestion - A class representing a Suggestion entity.
+ * Provides methods to access and manipulate Suggestion-specific data,
+ * such as related opportunities, types, statuses, etc.
+ *
+ * @class Suggestion
+ * @extends BaseModel
+ */
+class Suggestion extends BaseModel {
+  /**
+   * Retrieves the Opportunity entity associated to this Suggestion.
+   * @async
+   * @returns {Promise<Opportunity>} - A promise that resolves to the Opportunity
+   * instance associated with this Suggestion.
+   */
+  async getOpportunity() {
+    return this._getAssociation('OpportunityCollection', 'findById', this.getOpportunityId());
+  }
+
+  /**
+   * Gets the Opportunity ID for this Suggestion.
+   * @returns {string} - The unique identifier of the related Opportunity.
+   */
+  getOpportunityId() {
+    return this.record.opportunityId;
+  }
+
+  /**
+   * Sets the Opportunity ID for this Suggestion.
+   * @param {string} opportunityId - The unique identifier of the related Opportunity.
+   * @returns {Suggestion} - The current instance of Suggestion for chaining.
+   * @throws {Error} - Throws an error if the opportunityId is not a valid UUID.
+   */
+  setOpportunityId(opportunityId) {
+    this.patcher.patchValue('opportunityId', opportunityId, true);
+    return this;
+  }
+
+  /**
+   * Gets the type of this Suggestion.
+   * @returns {string} - The type of the Suggestion (e.g., CODE_CHANGE, CONTENT_UPDATE).
+   */
+  getType() {
+    return this.record.type;
+  }
+
+  /**
+   * Gets the status of this Suggestion.
+   * @returns {string} - The status of the Suggestion (e.g., NEW, APPROVED, SKIPPED, FIXED, ERROR).
+   */
+  getStatus() {
+    return this.record.status;
+  }
+
+  /**
+   * Sets the status of this Suggestion. Check the schema for possible values.
+   * @param {string} status - The new status of the Suggestion.
+   * @returns {Suggestion} - The current instance of Suggestion for chaining.
+   * @throws {Error} - Throws an error if the status is not a valid value.
+   */
+  setStatus(status) {
+    this.patcher.patchValue('status', status);
+    return this;
+  }
+
+  /**
+   * Gets the rank of this Suggestion.
+   * @returns {number} - The rank of the Suggestion used for sorting or prioritization.
+   */
+  getRank() {
+    return this.record.rank;
+  }
+
+  /**
+   * Sets the rank of this Suggestion.
+   * @param {number} rank - The rank value to set for this Suggestion.
+   * @returns {Suggestion} - The current instance of Suggestion for chaining.
+   * @throws {Error} - Throws an error if the rank is not a valid number.
+   */
+  setRank(rank) {
+    this.patcher.patchValue('rank', rank);
+    return this;
+  }
+
+  /**
+   * Gets additional data associated with this Suggestion.
+   * @returns {Object} - The additional data for the Suggestion.
+   */
+  getData() {
+    return this.record.data;
+  }
+
+  /**
+   * Sets additional data for this Suggestion.
+   * @param {Object} data - The data to set for the Suggestion.
+   * @returns {Suggestion} - The current instance of Suggestion for chaining.
+   * @throws {Error} - Throws an error if the data is not a valid object.
+   */
+  setData(data) {
+    this.patcher.patchValue('data', data);
+    return this;
+  }
+
+  /**
+   * Gets the KPI deltas for this Suggestion.
+   * @returns {Object} - The key performance indicator deltas that are affected by this Suggestion.
+   */
+  getKpiDeltas() {
+    return this.record.kpiDeltas;
+  }
+
+  /**
+   * Sets the KPI deltas for this Suggestion.
+   * @param {Object} kpiDeltas - The KPI deltas to set for the Suggestion.
+   * @returns {Suggestion} - The current instance of Suggestion for chaining.
+   * @throws {Error} - Throws an error if the kpiDeltas is not a valid object.
+   */
+  setKpiDeltas(kpiDeltas) {
+    this.patcher.patchValue('kpiDeltas', kpiDeltas);
+    return this;
+  }
+}
+
+export default Suggestion;