@adobe/spacecat-shared-data-access 1.37.0 → 1.38.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-data-access-v1.38.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.38.0...@adobe/spacecat-shared-data-access-v1.38.1) (2024-07-24)
+
+
+### Bug Fixes
+
+* naming issues ([#300](https://github.com/adobe/spacecat-shared/issues/300)) ([f0a7468](https://github.com/adobe/spacecat-shared/commit/f0a7468526a5f71c4bfed5ec0b88c3c889316cd6))
+
+# [@adobe/spacecat-shared-data-access-v1.38.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.37.0...@adobe/spacecat-shared-data-access-v1.38.0) (2024-07-23)
+
+
+### Features
+
+* Experimentation entity ([#288](https://github.com/adobe/spacecat-shared/issues/288)) ([774e2c7](https://github.com/adobe/spacecat-shared/commit/774e2c7013c9e617c745c494e20e1cdd8cce71e7))
+
 # [@adobe/spacecat-shared-data-access-v1.37.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.36.0...@adobe/spacecat-shared-data-access-v1.37.0) (2024-07-22)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "1.37.0",
+  "version": "1.38.1",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "main": "src/index.js",

package/src/dto/experiment.js

@@ -0,0 +1,66 @@
+/*
+ * 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 { createExperiment } from '../models/experiment.js';
+
+/**
+ * Data transfer object for Experiment.
+ */
+export const ExperimentDto = {
+  /**
+   * Converts an Experiment object into a DynamoDB item.
+   * @param {Readonly<Experiment>} experiment - Experiment object.
+   * @returns {{siteId, id, name, url, status, type, startDate, endDate,
+   * variants, updatedAt, updatedBy, conversionEventName, conversionEventValue}}
+   */
+  toDynamoItem: (experiment) => ({
+    siteId: experiment.getSiteId(),
+    experimentId: experiment.getExperimentId(),
+    name: experiment.getName(),
+    url: experiment.getUrl(),
+    status: experiment.getStatus(),
+    type: experiment.getType(),
+    startDate: experiment.getStartDate(),
+    endDate: experiment.getEndDate(),
+    variants: experiment.getVariants(),
+    updatedAt: experiment.getUpdatedAt(),
+    updatedBy: experiment.getUpdatedBy(),
+    conversionEventName: experiment.getConversionEventName(),
+    conversionEventValue: experiment.getConversionEventValue(),
+    SK: `${experiment.getExperimentId()}#${experiment.getUrl()}`,
+  }),
+
+  /**
+   * Converts a DynamoDB item into Experiment object;
+   * @param {object } dynamoItem - DynamoDB item.
+   * @returns {Readonly<Experiment>} Experiment object.
+   */
+  fromDynamoItem: (dynamoItem) => {
+    const experiment = {
+      siteId: dynamoItem.siteId,
+      experimentId: dynamoItem.experimentId,
+      name: dynamoItem.name,
+      url: dynamoItem.url,
+      status: dynamoItem.status,
+      type: dynamoItem.type,
+      startDate: dynamoItem.startDate,
+      endDate: dynamoItem.endDate,
+      variants: dynamoItem.variants,
+      updatedAt: dynamoItem.updatedAt,
+      updatedBy: dynamoItem.updatedBy,
+      conversionEventName: dynamoItem.conversionEventName,
+      conversionEventValue: dynamoItem.conversionEventValue,
+    };
+
+    return createExperiment(experiment);
+  },
+};

package/src/index.d.ts

@@ -534,6 +534,76 @@ export interface ImportUrl {
 
 }
 
+/**
+ * Represents an experiment entity.
+ */
+export interface Experiment {
+  /**
+   * Retrieves the ID of the experiment.
+   */
+  getExperimentId: () => string;
+
+  /**
+   * Retrieves the site ID of the experiment.
+   */
+  getSiteId: () => string;
+
+  /**
+   * Retrieves the Control URL of the experiment.
+   */
+  getUrl: () => string;
+
+  /**
+   * Retrieves the experiment name.
+   */
+  getName: () => string;
+
+  /**
+   * Retrieves the experiment type.
+   */
+  getType: () => string;
+
+  /**
+   * Retrieves the experiment status.
+   */
+  getStatus: () => string;
+
+  /**
+   * Retrieves the experiment variants.
+   */
+  getVariants: () => Array<object>;
+
+  /**
+   * Retrieves the experiment start date.
+   */
+  getStartDate: () => string;
+
+  /**
+   * Retrieves the experiment end date.
+   */
+  getEndDate: () => string;
+
+  /**
+   * Retrieves the conversion event name.
+   */
+  getConversionEventName: () => string;
+
+  /**
+   * Retrieves the conversion event value
+   */
+  getConversionEventValue: () => string;
+
+  /**
+   * Retrieves the last update timestamp of the experiment entity in persistent store.
+   */
+  getUpdatedAt: () => string;
+
+  /**
+   * Retrieves the updated by of the experiment entity in persistent store.
+   */
+  getUpdatedBy: () => string;
+}
+
 export interface DataAccess {
   getAuditForSite: (
     sitedId: string,
@@ -675,6 +745,11 @@ export interface DataAccess {
   createKeyEvent: (keyEventData: object) => Promise<KeyEvent>;
   getKeyEventsForSite: (siteId: string) => Promise<KeyEvent[]>
   removeKeyEvent: (keyEventId: string) => Promise<void>;
+
+  // experiment functions
+  getExperiments: (siteId: string, experimentId?: string) => Promise<Experiment[]>;
+  getExperiment: (siteId: string, experimentId: string, url: string) => Promise<Experiment | null>;
+  upsertExperiment: (experimentData: object) => Promise<Experiment>;
 }
 
 interface DataAccessConfig {
@@ -688,6 +763,7 @@ interface DataAccessConfig {
   tableNameSiteTopPages: string;
   tableNameImportJobs: string;
   tableNameImportUrls: string;
+  tableNameExperiments: string;
   indexNameAllKeyEventsBySiteId: string,
   indexNameAllSites: string;
   indexNameAllSitesOrganizations: string,

package/src/index.js

@@ -24,6 +24,7 @@ const TABLE_NAME_CONFIGURATIONS = 'spacecat-services-configurations-dev';
 const TABLE_NAME_SITE_TOP_PAGES = 'spacecat-services-site-top-pages-dev';
 const TABLE_NAME_IMPORT_JOBS = 'spacecat-services-import-jobs-dev';
 const TABLE_NAME_IMPORT_URLS = 'spacecat-services-import-urls-dev';
+const TABLE_NAME_EXPERIMENTS = 'spacecat-services-experiments-dev';
 
 const INDEX_NAME_ALL_KEY_EVENTS_BY_SITE_ID = 'spacecat-services-key-events-by-site-id';
 const INDEX_NAME_ALL_SITES = 'spacecat-services-all-sites-dev';
@@ -58,6 +59,7 @@ export default function dataAccessWrapper(fn) {
         DYNAMO_TABLE_NAME_SITE_TOP_PAGES = TABLE_NAME_SITE_TOP_PAGES,
         DYNAMO_TABLE_NAME_IMPORT_JOBS = TABLE_NAME_IMPORT_JOBS,
         DYNAMO_TABLE_NAME_IMPORT_URLS = TABLE_NAME_IMPORT_URLS,
+        DYNAMO_TABLE_NAME_EXPERIMENTS = TABLE_NAME_EXPERIMENTS,
         DYNAMO_INDEX_NAME_ALL_KEY_EVENTS_BY_SITE_ID = INDEX_NAME_ALL_KEY_EVENTS_BY_SITE_ID,
         DYNAMO_INDEX_NAME_ALL_SITES = INDEX_NAME_ALL_SITES,
         DYNAMO_INDEX_NAME_ALL_SITES_BY_DELIVERY_TYPE = INDEX_NAME_ALL_SITES_BY_DELIVERY_TYPE,
@@ -83,6 +85,7 @@ export default function dataAccessWrapper(fn) {
         tableNameSiteTopPages: DYNAMO_TABLE_NAME_SITE_TOP_PAGES,
         tableNameImportJobs: DYNAMO_TABLE_NAME_IMPORT_JOBS,
         tableNameImportUrls: DYNAMO_TABLE_NAME_IMPORT_URLS,
+        tableNameExperiments: DYNAMO_TABLE_NAME_EXPERIMENTS,
         indexNameAllKeyEventsBySiteId: DYNAMO_INDEX_NAME_ALL_KEY_EVENTS_BY_SITE_ID,
         indexNameAllSites: DYNAMO_INDEX_NAME_ALL_SITES,
         indexNameAllOrganizations: DYNAMO_INDEX_NAME_ALL_ORGANIZATIONS,

package/src/models/experiment.js

@@ -0,0 +1,67 @@
+/*
+ * 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 { Base } from './base.js';
+
+export const DEFAULT_UPDATED_BY = 'spacecat';
+
+/**
+ * Creates a new Experiment.
+ *
+ * @param {object} data - experiment data
+ * @returns {Readonly<SiteCandidate>} new experiment
+ */
+const Experiment = (data = {}) => {
+  const self = Base(data);
+
+  self.getSiteId = () => self.state.siteId;
+  self.getExperimentId = () => self.state.experimentId;
+  self.getName = () => self.state.name;
+  self.getUrl = () => self.state.url;
+  self.getStatus = () => self.state.status;
+  self.getType = () => self.state.type;
+  self.getStartDate = () => self.state.startDate;
+  self.getEndDate = () => self.state.endDate;
+  self.getVariants = () => self.state.variants;
+  self.getUpdatedAt = () => self.state.updatedAt;
+  self.getUpdatedBy = () => self.state.updatedBy;
+  self.getConversionEventName = () => self.state.conversionEventName;
+  self.getConversionEventValue = () => self.state.conversionEventValue;
+
+  return Object.freeze(self);
+};
+
+/**
+ * Creates a new Experiment.
+ *
+ * @param {object} data - experiment data
+ * @returns {Readonly<SiteCandidate>} new experiment
+ */
+export const createExperiment = (data) => {
+  const newState = { ...data };
+
+  if (!hasText(newState.siteId)) {
+    throw new Error('Site ID must be provided');
+  }
+
+  if (!hasText(newState.experimentId)) {
+    throw new Error('Experiment ID must be provided');
+  }
+
+  if (!hasText(newState.updatedBy)) {
+    newState.updatedBy = DEFAULT_UPDATED_BY;
+  }
+
+  return Experiment(newState);
+};

package/src/models/site/config.js

@@ -61,7 +61,7 @@ export const Config = (data = {}) => {
   self.getHandlers = () => state.handlers;
   self.getImports = () => state.imports;
   self.getExcludedURLs = (type) => state?.handlers[type]?.excludedURLs;
-  self.getManualOverrides = (type) => state?.handlers[type]?.manualOverwrites;
+  self.getManualOverwrites = (type) => state?.handlers[type]?.manualOverwrites;
   self.getFixedURLs = (type) => state?.handlers[type]?.fixedURLs;
 
   self.updateSlackConfig = (channel, workspace, invitedUserCount) => {
@@ -79,13 +79,13 @@ export const Config = (data = {}) => {
     state.handlers[type].mentions.slack = mentions;
   };
 
-  self.updateExcludeURLs = (type, excludedURLs) => {
+  self.updateExcludedURLs = (type, excludedURLs) => {
     state.handlers = state.handlers || {};
     state.handlers[type] = state.handlers[type] || {};
     state.handlers[type].excludedURLs = excludedURLs;
   };
 
-  self.updateManualOverrides = (type, manualOverwrites) => {
+  self.updateManualOverwrites = (type, manualOverwrites) => {
     state.handlers = state.handlers || {};
     state.handlers[type] = state.handlers[type] || {};
     state.handlers[type].manualOverwrites = manualOverwrites;

package/src/service/experiments/accessPatterns.js

@@ -0,0 +1,98 @@
+/*
+ * 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 { isObject } from '@adobe/spacecat-shared-utils';
+import { createExperiment } from '../../models/experiment.js';
+import { ExperimentDto } from '../../dto/experiment.js';
+
+/**
+ * Returns the experiment if exists in experiments table using siteId, experimentId and url
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {DataAccessConfig} config - The data access config.
+ * @param {string} siteId - siteId of the experiment.
+ * @param {string} id - id of the experiment.
+ * @return the experiment if exists, null otherwise
+ */
+export const getExperiment = async (dynamoClient, config, siteId, experimentId, url) => {
+  const queryParams = {
+    TableName: config.tableNameExperiments,
+    KeyConditionExpression: 'siteId = :siteId AND SK = :SK',
+    ExpressionAttributeValues: {
+      ':siteId': siteId,
+      ':SK': `${experimentId}#${url}`,
+    },
+    ScanIndexForward: false,
+  };
+  const dynamoItems = await dynamoClient.query(queryParams);
+  if (dynamoItems != null && dynamoItems.length > 0 && isObject(dynamoItems[0])) {
+    return ExperimentDto.fromDynamoItem(dynamoItems[0]);
+  }
+
+  return null;
+};
+
+/**
+ * Retrieves all experiments for a given siteId.
+ * @param {*} dynamoClient - The DynamoDB client.
+ * @param {*} config - The data access config.
+ * @param {*} log  - the logger object
+ * @param {*} siteId - siteId of the experiment.
+ * @param {*} experimentId - experiment id.
+ * @returns {Promise<ReadonlyArray<SiteCandidate>>} A promise that resolves to
+ * an array of experiments
+ */
+export const getExperiments = async (
+  dynamoClient,
+  config,
+  log,
+  siteId,
+  experimentId,
+) => {
+  const queryParams = {
+    TableName: config.tableNameExperiments,
+    KeyConditionExpression: 'siteId = :siteId',
+    ExpressionAttributeValues: { ':siteId': siteId },
+    ScanIndexForward: false,
+  };
+  if (experimentId) {
+    queryParams.KeyConditionExpression += ' AND begins_with(SK, :experimentId)';
+    queryParams.ExpressionAttributeValues[':experimentId'] = experimentId;
+  }
+  const dynamoItems = await dynamoClient.query(queryParams);
+
+  return dynamoItems.map((item) => ExperimentDto.fromDynamoItem(item));
+};
+
+/**
+ * Upserts an experiment.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {DataAccessConfig} config - The data access config.
+ * @param {object} log - the logger object
+ * @param {object} experimentData - The experiment data.
+ * @returns {Promise<Readonly<SiteCandidate>>} A promise that resolves to newly created/updated
+ * experiment
+ */
+export const upsertExperiment = async (
+  dynamoClient,
+  config,
+  log,
+  experimentData,
+) => {
+  const experiment = createExperiment(experimentData);
+  await dynamoClient.putItem(
+    config.tableNameExperiments,
+    ExperimentDto.toDynamoItem(experiment),
+  );
+
+  return experiment;
+};

package/src/service/experiments/index.js

@@ -0,0 +1,40 @@
+/*
+ * 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 {
+  getExperiments,
+  upsertExperiment,
+  getExperiment,
+} from './accessPatterns.js';
+
+export const experimentFunctions = (dynamoClient, config, log) => ({
+  getExperiments: (siteId, experimentId) => getExperiments(
+    dynamoClient,
+    config,
+    log,
+    siteId,
+    experimentId,
+  ),
+  upsertExperiment: (experimentData) => upsertExperiment(
+    dynamoClient,
+    config,
+    log,
+    experimentData,
+  ),
+  getExperiment: (siteId, experimentId, url) => getExperiment(
+    dynamoClient,
+    config,
+    siteId,
+    experimentId,
+    url,
+  ),
+});

package/src/service/index.js

@@ -20,13 +20,15 @@ import { configurationFunctions } from './configurations/index.js';
 import { siteTopPagesFunctions } from './site-top-pages/index.js';
 import { importJobFunctions } from './import-job/index.js';
 import { importUrlFunctions } from './import-url/index.js';
+import { experimentFunctions } from './experiments/index.js';
 
 /**
  * Creates a data access object.
  *
  * @param {{pkAllSites: string, pkAllLatestAudits: string, indexNameAllLatestAuditScores: string,
  * tableNameAudits: string,tableNameLatestAudits: string, indexNameAllSitesOrganizations: string,
- * tableNameSites: string, tableNameOrganizations: string, indexNameAllSites: string,
+ * tableNameSites: string, tableNameOrganizations: string, tableNameExperiments: string,
+ * indexNameAllSites: string,
  * tableNameImportJobs: string, pkAllImportJobs: string, indexNameAllImportJobs: string,
  * tableNameSiteTopPages: string, indexNameAllOrganizations: string,
  * indexNameAllOrganizationsByImsOrgId: string, pkAllOrganizations: string}} config configuration
@@ -45,6 +47,7 @@ export const createDataAccess = (config, log = console) => {
   const siteTopPagesFuncs = siteTopPagesFunctions(dynamoClient, config);
   const importJobFuncs = importJobFunctions(dynamoClient, config, log);
   const importUrlFuncs = importUrlFunctions(dynamoClient, config, log);
+  const experimentFuncs = experimentFunctions(dynamoClient, config, log);
 
   return {
     ...auditFuncs,
@@ -56,5 +59,6 @@ export const createDataAccess = (config, log = console) => {
     ...siteTopPagesFuncs,
     ...importJobFuncs,
     ...importUrlFuncs,
+    ...experimentFuncs,
   };
 };