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

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-data-access-v1.54.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.53.1...@adobe/spacecat-shared-data-access-v1.54.0) (2024-11-20)
+
+
+### Features
+
+* opportunity & suggestion model (+electrodb) ([#447](https://github.com/adobe/spacecat-shared/issues/447)) ([91cf931](https://github.com/adobe/spacecat-shared/commit/91cf931facbc7f13a6fe6eebe71f2948a4ec007e))
+
 # [@adobe/spacecat-shared-data-access-v1.53.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.53.0...@adobe/spacecat-shared-data-access-v1.53.1) (2024-11-16)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "1.53.1",
+  "version": "1.54.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {
@@ -16,6 +16,7 @@
     "clean": "rm -rf package-lock.json node_modules"
   },
   "mocha": {
+    "require": "test/setup-env.js",
     "reporter": "mocha-multi-reporters",
     "reporter-options": "configFile=.mocha-multi.json"
   },
@@ -38,6 +39,8 @@
     "@aws-sdk/client-dynamodb": "3.693.0",
     "@aws-sdk/lib-dynamodb": "3.693.0",
     "@types/joi": "17.2.3",
+    "aws-xray-sdk": "3.10.2",
+    "electrodb": "3.0.1",
     "joi": "17.13.3",
     "uuid": "11.0.3"
   },

package/src/index.d.ts

@@ -892,6 +892,10 @@ export interface DataAccess {
   getExperiments: (siteId: string, experimentId?: string) => Promise<Experiment[]>;
   getExperiment: (siteId: string, experimentId: string, url: string) => Promise<Experiment | null>;
   upsertExperiment: (experimentData: object) => Promise<Experiment>;
+
+  // electro-based entities
+  Opportunity: object,
+  Suggestion: object,
 }
 
 interface DataAccessConfig {
@@ -930,3 +934,5 @@ export function createDataAccess(
   config: DataAccessConfig,
   logger: object,
 ): DataAccess;
+
+export type * from './v2/index.d.ts';

package/src/index.js

@@ -14,6 +14,7 @@ import { createDataAccess } from './service/index.js';
 
 export { ImportJobStatus, ImportUrlStatus, ImportOptions } from './models/importer/import-constants.js';
 
+const TABLE_NAME_DATA = 'spacecat-services-data-dev';
 const TABLE_NAME_AUDITS = 'spacecat-services-audits-dev';
 const TABLE_NAME_KEY_EVENTS = 'spacecat-services-key-events';
 const TABLE_NAME_LATEST_AUDITS = 'spacecat-services-latest-audits-dev';
@@ -52,6 +53,7 @@ export default function dataAccessWrapper(fn) {
       const { log } = context;
 
       const {
+        DYNAMO_TABLE_NAME_DATA = TABLE_NAME_DATA,
         DYNAMO_TABLE_NAME_AUDITS = TABLE_NAME_AUDITS,
         DYNAMO_TABLE_NAME_KEY_EVENTS = TABLE_NAME_KEY_EVENTS,
         DYNAMO_TABLE_NAME_LATEST_AUDITS = TABLE_NAME_LATEST_AUDITS,
@@ -82,6 +84,7 @@ export default function dataAccessWrapper(fn) {
       } = context.env;
 
       context.dataAccess = createDataAccess({
+        tableNameData: DYNAMO_TABLE_NAME_DATA,
         tableNameAudits: DYNAMO_TABLE_NAME_AUDITS,
         tableNameKeyEvents: DYNAMO_TABLE_NAME_KEY_EVENTS,
         tableNameLatestAudits: DYNAMO_TABLE_NAME_LATEST_AUDITS,
@@ -118,3 +121,5 @@ export default function dataAccessWrapper(fn) {
     return fn(request, context);
   };
 }
+
+export * from './v2/index.js';

package/src/service/index.js

@@ -11,6 +11,17 @@
  */
 
 import { createClient } from '@adobe/spacecat-shared-dynamo';
+import { DynamoDB } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+import AWSXray from 'aws-xray-sdk';
+import { Service } from 'electrodb';
+
+import ModelFactory from '../v2/models/model.factory.js';
+import OpportunityCollection from '../v2/models/opportunity.collection.js';
+import SuggestionCollection from '../v2/models/suggestion.collection.js';
+import OpportunitySchema from '../v2/schema/opportunity.schema.js';
+import SuggestionSchema from '../v2/schema/suggestion.schema.js';
+
 import { auditFunctions } from './audits/index.js';
 import { keyEventFunctions } from './key-events/index.js';
 import { siteFunctions } from './sites/index.js';
@@ -23,6 +34,36 @@ import { importUrlFunctions } from './import-url/index.js';
 import { experimentFunctions } from './experiments/index.js';
 import { apiKeyFunctions } from './api-key/index.js';
 
+const createRawClient = () => {
+  const dbClient = AWSXray.captureAWSv3Client(new DynamoDB());
+  return DynamoDBDocument.from(dbClient, {
+    marshallOptions: {
+      convertEmptyValues: true,
+      removeUndefinedValues: true,
+    },
+  });
+};
+
+const createElectroService = (client, config, log) => {
+  const { tableNameData: table } = config;
+  /* c8 ignore start */
+  const logger = (event) => {
+    log.debug(JSON.stringify(event, null, 4));
+  };
+  /* c8 ignore end */
+  return new Service(
+    {
+      opportunity: OpportunitySchema,
+      suggestion: SuggestionSchema,
+    },
+    {
+      client,
+      table,
+      logger,
+    },
+  );
+};
+
 /**
  * Creates a data access object.
  *
@@ -51,6 +92,14 @@ export const createDataAccess = (config, log = console) => {
   const experimentFuncs = experimentFunctions(dynamoClient, config, log);
   const apiKeyFuncs = apiKeyFunctions(dynamoClient, config, log);
 
+  // electro-based data access objects
+  const rawClient = createRawClient();
+  const electroService = createElectroService(rawClient, config, log);
+  const modelFactory = new ModelFactory(electroService, log);
+
+  const Opportunity = modelFactory.getCollection(OpportunityCollection.name);
+  const Suggestion = modelFactory.getCollection(SuggestionCollection.name);
+
   return {
     ...auditFuncs,
     ...keyEventFuncs,
@@ -63,5 +112,8 @@ export const createDataAccess = (config, log = console) => {
     ...importUrlFuncs,
     ...experimentFuncs,
     ...apiKeyFuncs,
+    // electro-based data access objects
+    Opportunity,
+    Suggestion,
   };
 };

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

@@ -0,0 +1,13 @@
+/*
+ * 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.
+ */
+
+export type ValidationError = Error

package/src/v2/errors/index.js

@@ -0,0 +1,15 @@
+/*
+ * 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 ValidationError from './validation.error.js';
+
+export { ValidationError };

package/src/v2/errors/validation.error.js

@@ -0,0 +1,13 @@
+/*
+ * 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.
+ */
+
+export default class ValidationError extends Error {}

package/src/v2/index.d.ts

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+
+export type * from './errors/index.d.ts';
+export type * from './models/index.d.ts';
+export type * from './util/index.d.ts';

package/src/v2/index.js

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+
+export * from './errors/index.js';
+export * from './models/index.js';
+export * from './util/index.js';

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

@@ -0,0 +1,118 @@
+/*
+ * 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 { guardId } from '../util/guards.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 {Class} 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.
+   * @protected
+   * @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.
+   * @protected
+   * @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 }));
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * Creates a new entity in the collection.
+   * @async
+   * @param {Object} data - 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`);
+    }
+
+    try {
+      // todo: validate associations
+      const record = await this.entity.create(data).go();
+      return this._createInstance(record);
+    } catch (error) {
+      this.log.error(`Failed to create [${this.entityName}]`, error);
+      throw error;
+    }
+  }
+}
+
+export default BaseCollection;

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

@@ -0,0 +1,127 @@
+/*
+ * 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 Patcher from '../util/patcher.js';
+
+/**
+ * Base - A base class for representing individual entities in the application.
+ * Provides common functionality for entity management, including fetching, updating,
+ * and deleting records.
+ *
+ * @class BaseModel
+ */
+class BaseModel {
+  /**
+   * Constructs an instance of BaseModel.
+   * @constructor
+   * @param {Object} electroService - The ElectroDB service used for managing entities.
+   * @param {Object} modelFactory - A factory for creating model instances.
+   * @param {Object} record - The initial data for the entity instance.
+   * @param {Object} log - A logger for capturing logging information.
+   */
+  constructor(electroService, modelFactory, record, log) {
+    this.modelFactory = modelFactory;
+    this.record = record;
+    this.entityName = this.constructor.name.toLowerCase();
+    this.entity = electroService.entities[this.entityName];
+    this.idName = `${this.entityName}Id`;
+    this.log = log;
+
+    this.patcher = new Patcher(this.entity, this.record);
+    this.associationsCache = {};
+  }
+
+  /**
+   * Gets the association of the model by querying another related model. Retrieved
+   * associations are cached to avoid redundant queries.
+   * @protected
+   * @async
+   * @param {string} modelName - The name of the related model.
+   * @param {string} method - The method to use for querying the related model.
+   * @param {...*} args - Additional arguments to be passed to the method.
+   * @returns {Promise<Object>} - A promise that resolves to the associated model instance.
+   */
+  async _getAssociation(modelName, method, ...args) {
+    const cache = this.associationsCache;
+
+    cache[modelName] = cache[modelName] || {};
+
+    if (!(method in cache[modelName])) {
+      cache[modelName][method] = await this.modelFactory.getCollection(modelName)[method](...args);
+    }
+
+    return cache[modelName][method];
+  }
+
+  /**
+   * Gets the ID of the current entity.
+   * @returns {string} - The unique identifier of the entity.
+   */
+  getId() {
+    return this.record[this.idName];
+  }
+
+  /**
+   * Gets the creation timestamp of the current entity.
+   * @returns {string} - The ISO string representing when the entity was created.
+   */
+  getCreatedAt() {
+    return new Date(this.record.createdAt).toISOString();
+  }
+
+  /**
+   * Gets the update timestamp of the current entity.
+   * @returns {string} - The ISO string representing when the entity was last updated.
+   */
+  getUpdatedAt() {
+    return new Date(this.record.updatedAt).toISOString();
+  }
+
+  /**
+   * Removes the current entity from the database.
+   * @async
+   * @returns {Promise<BaseModel>} - A promise that resolves to the current instance of the entity
+   * after it has been removed.
+   * @throws {Error} - Throws an error if the removal fails.
+   */
+  async remove() {
+    try {
+      // todo: remove dependents (child associations)
+      await this.entity.remove({ [this.idName]: this.getId() }).go();
+      return this;
+    } catch (error) {
+      this.log.error('Failed to remove record', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Saves the current entity to the database. This method must be called after making changes
+   * to the entity via their respective setter methods.
+   * @async
+   * @returns {Promise<BaseModel>} - A promise that resolves to the current instance of the entity
+   * after it has been saved.
+   * @throws {Error} - Throws an error if the save operation fails.
+   */
+  async save() {
+    // todo: validate associations
+    try {
+      await this.patcher.save();
+      return this;
+    } catch (error) {
+      this.log.error('Failed to save record', error);
+      throw error;
+    }
+  }
+}
+
+export default BaseModel;

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

@@ -0,0 +1,100 @@
+/*
+ * 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.
+ */
+
+/**
+ * Interface representing a base model for interacting with a data entity.
+ */
+export interface BaseModel {
+  getId(): string;
+  getCreatedAt(): string;
+  getUpdatedAt(): string;
+  remove(): Promise<this>;
+  save(): Promise<this>;
+}
+
+/**
+ * Interface representing an Opportunity model, extending BaseModel.
+ */
+export interface Opportunity extends BaseModel {
+  // eslint-disable-next-line no-use-before-define
+  getSuggestions(): Promise<Suggestion[]>;
+  getSiteId(): string;
+  setSiteId(siteId: string): Opportunity;
+  getAuditId(): string;
+  setAuditId(auditId: string): Opportunity;
+  getRunbook(): string;
+  setRunbook(runbook: string): Opportunity;
+  getGuidance(): string;
+  setGuidance(guidance: string): Opportunity;
+  getTitle(): string;
+  setTitle(title: string): Opportunity;
+  getDescription(): string;
+  setDescription(description: string): Opportunity;
+  getType(): string;
+  getStatus(): string;
+  setStatus(status: string): Opportunity;
+  getOrigin(): string;
+  setOrigin(origin: string): Opportunity;
+  getTags(): string[];
+  setTags(tags: string[]): Opportunity;
+  getData(): object;
+  setData(data: object): Opportunity;
+}
+
+/**
+ * Interface representing a Suggestion model, extending BaseModel.
+ */
+export interface Suggestion extends BaseModel {
+  getOpportunity(): Promise<Opportunity>;
+  getOpportunityId(): string;
+  setOpportunityId(opportunityId: string): Suggestion;
+  getType(): string;
+  getStatus(): string;
+  setStatus(status: string): Suggestion;
+  getRank(): number;
+  setRank(rank: number): Suggestion;
+  getData(): object;
+  setData(data: object): Suggestion;
+  getKpiDeltas(): object;
+  setKpiDeltas(kpiDeltas: object): Suggestion;
+}
+
+/**
+ * Interface representing a base collection for interacting with data entities.
+ */
+export interface BaseCollection<T extends BaseModel> {
+  findById(id: string): Promise<T>;
+  create(data: object): Promise<T>;
+}
+
+/**
+ * Interface representing the Opportunity collection, extending BaseCollection.
+ */
+export interface OpportunityCollection extends BaseCollection<Opportunity> {
+  allBySiteId(siteId: string): Promise<Opportunity[]>;
+  allBySiteIdAndStatus(siteId: string, status: string): Promise<Opportunity[]>;
+}
+
+/**
+ * Interface representing the Suggestion collection, extending BaseCollection.
+ */
+export interface SuggestionCollection extends BaseCollection<Suggestion> {
+  allByOpportunityId(opportunityId: string): Promise<Suggestion[]>;
+  allByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<Suggestion[]>;
+}
+
+/**
+ * Interface representing the Model Factory for creating and managing model collections.
+ */
+export interface ModelFactory {
+  getCollection<T extends BaseModel>(collectionName: string): BaseCollection<T>;
+}

package/src/v2/models/index.js

@@ -0,0 +1,27 @@
+/*
+ * 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 ModelFactory from './model.factory.js';
+import BaseModel from './base.model.js';
+import Opportunity from './opportunity.model.js';
+import OpportunityCollection from './opportunity.collection.js';
+import Suggestion from './suggestion.model.js';
+import SuggestionCollection from './suggestion.collection.js';
+
+export {
+  ModelFactory,
+  BaseModel,
+  Opportunity,
+  OpportunityCollection,
+  Suggestion,
+  SuggestionCollection,
+};