@adobe/spacecat-shared-data-access 1.22.1 → 1.23.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-data-access-v1.23.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.22.1...@adobe/spacecat-shared-data-access-v1.23.0) (2024-05-03)
+
+
+### Features
+
+* key events data access layer ([#223](https://github.com/adobe/spacecat-shared/issues/223)) ([83228cc](https://github.com/adobe/spacecat-shared/commit/83228ccb3011868da54460b7fb2788e27ee33454))
+
 # [@adobe/spacecat-shared-data-access-v1.22.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.22.0...@adobe/spacecat-shared-data-access-v1.22.1) (2024-04-30)
 
 

package/package.json

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

package/src/dto/key-event.js

@@ -0,0 +1,52 @@
+/*
+ * 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 { createKeyEvent } from '../models/key-event.js';
+
+/**
+ * Data transfer object for Key Event.
+ */
+export const KeyEventDto = {
+  /**
+     * Converts a DynamoDB item into a KeyEvent object.
+     * @param {object } dynamoItem - DynamoDB item.
+     * @returns {Readonly<KeyEvent>} KeyEvent object.
+     */
+  fromDynamoItem: (dynamoItem) => {
+    const keyEventData = {
+      id: dynamoItem.id,
+      siteId: dynamoItem.siteId,
+      name: dynamoItem.name,
+      type: dynamoItem.type,
+      time: dynamoItem.time,
+      createdAt: dynamoItem.createdAt,
+      updatedAt: dynamoItem.updatedAt,
+    };
+
+    return createKeyEvent(keyEventData);
+  },
+
+  /**
+     * Converts a KeyEvent object into a DynamoDB item.
+     * @param {Readonly<KeyEvent>} keyEvent - KeyEvent object.
+     * @returns {object} DynamoDB item.
+     */
+  toDynamoItem: (keyEvent) => ({
+    id: keyEvent.getId(),
+    siteId: keyEvent.getSiteId(),
+    name: keyEvent.getName(),
+    type: keyEvent.getType(),
+    time: keyEvent.getTime(),
+    createdAt: keyEvent.getCreatedAt(),
+    updatedAt: keyEvent.getUpdatedAt(),
+  }),
+};

package/src/index.d.ts

@@ -129,6 +129,53 @@ export interface AuditConfig {
   getAuditTypeConfigs: () => object;
 }
 
+/**
+ * Represents a key event.
+ */
+export interface KeyEvent {
+  /**
+   * Retrieves the ID of the key event.
+   * @returns {string} The Key Event ID.
+   */
+  getId: () => string;
+
+  /**
+   * Retrieves the site id of the key event.
+   * @returns {string} site id
+   */
+  getSiteId: () => string;
+
+  /**
+   * Retrieves the name of the key event.
+   * @returns {string} The name
+   */
+  getName: () => string;
+
+  /**
+   * Retrieves the type of the key event.
+   * @returns {string} The type
+   */
+  getType: () => string;
+
+  /**
+   * Retrieves the time of the key event.
+   * @returns {string} The time
+   */
+  getTime: () => string;
+
+  /**
+   * Retrieves the creation timestamp of the key event.
+   * @returns {string} The creation timestamp.
+   */
+  getCreatedAt: () => string;
+
+  /**
+   * Retrieves the last update timestamp of the key event.
+   * @returns {string} The last update timestamp.
+   */
+  getUpdatedAt: () => string;
+}
+
 /**
  * Represents a site with associated audit and configuration data.
  */
@@ -491,16 +538,23 @@ export interface DataAccess {
   getConfigurations: () => Promise<Readonly<Configuration>[]>
   getConfigurationByVersion: (version: string) => Promise<Readonly<Configuration>>
   updateConfiguration: (configurationData: object) => Promise<Readonly<Configuration>>
+
+  // key events functions
+  createKeyEvent: (keyEventData: object) => Promise<KeyEvent>;
+  getKeyEventsForSite: (siteId: string) => Promise<KeyEvent[]>
+  removeKeyEvent: (keyEventId: string) => Promise<void>;
 }
 
 interface DataAccessConfig {
   tableNameAudits: string;
+  tableNameKeyEvents: string;
   tableNameLatestAudits: string;
   tableNameOrganizations: string,
   tableNameSites: string;
   tableNameSiteCandidates: string;
   tableNameConfigurations: string;
   tableNameSiteTopPages: string;
+  indexNameAllKeyEventsBySiteId: string,
   indexNameAllSites: string;
   indexNameAllSitesOrganizations: string,
   indexNameAllSitesByDeliveryType: string;

package/src/index.js

@@ -13,6 +13,7 @@
 import { createDataAccess } from './service/index.js';
 
 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';
 const TABLE_NAME_SITES = 'spacecat-services-sites-dev';
 const TABLE_NAME_SITE_CANDIDATES = 'spacecat-services-site-candidates-dev';
@@ -20,6 +21,7 @@ const TABLE_NAME_ORGANIZATIONS = 'spacecat-services-organizations-dev';
 const TABLE_NAME_CONFIGURATIONS = 'spacecat-services-configurations-dev';
 const TABLE_NAME_SITE_TOP_PAGES = 'spacecat-services-site-top-pages-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';
 const INDEX_NAME_ALL_ORGANIZATIONS = 'spacecat-services-all-organizations-dev';
 const INDEX_NAME_ALL_ORGANIZATIONS_BY_IMS_ORG_ID = 'spacecat-services-all-organizations-by-ims-org-id-dev';
@@ -39,12 +41,14 @@ export default function dataAccessWrapper(fn) {
 
       const {
         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,
         DYNAMO_TABLE_NAME_SITES = TABLE_NAME_SITES,
         DYNAMO_TABLE_NAME_SITE_CANDIDATES = TABLE_NAME_SITE_CANDIDATES,
         DYNAMO_TABLE_NAME_ORGANIZATIONS = TABLE_NAME_ORGANIZATIONS,
         DYNAMO_TABLE_NAME_CONFIGURATIONS = TABLE_NAME_CONFIGURATIONS,
         DYNAMO_TABLE_NAME_SITE_TOP_PAGES = TABLE_NAME_SITE_TOP_PAGES,
+        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,
         DYNAMO_INDEX_NAME_ALL_LATEST_AUDIT_SCORES = INDEX_NAME_ALL_LATEST_AUDIT_SCORES,
@@ -56,12 +60,14 @@ export default function dataAccessWrapper(fn) {
 
       context.dataAccess = createDataAccess({
         tableNameAudits: DYNAMO_TABLE_NAME_AUDITS,
+        tableNameKeyEvents: DYNAMO_TABLE_NAME_KEY_EVENTS,
         tableNameLatestAudits: DYNAMO_TABLE_NAME_LATEST_AUDITS,
         tableNameOrganizations: DYNAMO_TABLE_NAME_ORGANIZATIONS,
         tableNameSites: DYNAMO_TABLE_NAME_SITES,
         tableNameSiteCandidates: DYNAMO_TABLE_NAME_SITE_CANDIDATES,
         tableNameConfigurations: DYNAMO_TABLE_NAME_CONFIGURATIONS,
         tableNameSiteTopPages: DYNAMO_TABLE_NAME_SITE_TOP_PAGES,
+        indexNameAllKeyEventsBySiteId: DYNAMO_INDEX_NAME_ALL_KEY_EVENTS_BY_SITE_ID,
         indexNameAllSites: DYNAMO_INDEX_NAME_ALL_SITES,
         indexNameAllOrganizations: DYNAMO_INDEX_NAME_ALL_ORGANIZATIONS,
         indexNameAllOrganizationsByImsOrgId: DYNAMO_INDEX_NAME_ALL_ORGANIZATIONS_BY_IMS_ORG_ID,

package/src/models/key-event.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, isIsoDate } from '@adobe/spacecat-shared-utils';
+
+import { Base } from './base.js';
+
+export const KEY_EVENT_TYPES = {
+  PERFORMANCE: 'PERFORMANCE',
+  SEO: 'SEO',
+  CONTENT: 'CONTENT',
+  CODE: 'CODE',
+  THIRD_PARTY: 'THIRD PARTY',
+  EXPERIMENTATION: 'EXPERIMENTATION',
+  NETWORK: 'NETWORK',
+};
+
+/**
+ * Creates a new Key Event.
+ *
+ * @param {object} data - key event data
+ * @returns {Readonly<KeyEvent>} new key event
+ */
+const KeyEvent = (data = {}) => {
+  const self = Base(data);
+
+  self.getName = () => self.state.name;
+  self.getSiteId = () => self.state.siteId;
+  self.getType = () => self.state.type;
+  self.getTime = () => self.state.time;
+
+  // no set functions since all values are required at creation time
+
+  return Object.freeze(self);
+};
+
+/**
+ * Creates a new Key Event.
+ *
+ * @param {object} data - key event data
+ * @returns {Readonly<KeyEvent>} new key event
+ */
+export const createKeyEvent = (data) => {
+  const newState = { ...data };
+
+  if (!hasText(newState.siteId)) {
+    throw new Error('Required field "siteId" is missing');
+  }
+
+  if (!hasText(newState.name)) {
+    throw new Error('Required field "name" is missing');
+  }
+
+  if (!hasText(newState.type)) {
+    throw new Error('Required field "type" is missing');
+  }
+
+  if (!Object.values(KEY_EVENT_TYPES).includes(newState.type.toUpperCase())) {
+    throw new Error(`Unknown value for "type": ${newState.type}`);
+  }
+
+  if (hasText(newState.time) && !isIsoDate(newState.time)) {
+    throw new Error('"Time" should be a valid ISO string');
+  }
+
+  if (!hasText(newState.time)) {
+    newState.time = new Date().toISOString();
+  }
+
+  return KeyEvent(newState);
+};

package/src/service/index.js

@@ -12,6 +12,7 @@
 
 import { createClient } from '@adobe/spacecat-shared-dynamo';
 import { auditFunctions } from './audits/index.js';
+import { keyEventFunctions } from './key-events/index.js';
 import { siteFunctions } from './sites/index.js';
 import { siteCandidateFunctions } from './site-candidates/index.js';
 import { organizationFunctions } from './organizations/index.js';
@@ -33,6 +34,7 @@ export const createDataAccess = (config, log = console) => {
   const dynamoClient = createClient(log);
 
   const auditFuncs = auditFunctions(dynamoClient, config, log);
+  const keyEventFuncs = keyEventFunctions(dynamoClient, config, log);
   const siteFuncs = siteFunctions(dynamoClient, config, log);
   const siteCandidateFuncs = siteCandidateFunctions(dynamoClient, config, log);
   const organizationFuncs = organizationFunctions(dynamoClient, config, log);
@@ -41,6 +43,7 @@ export const createDataAccess = (config, log = console) => {
 
   return {
     ...auditFuncs,
+    ...keyEventFuncs,
     ...siteFuncs,
     ...siteCandidateFuncs,
     ...organizationFuncs,

package/src/service/key-events/accessPatterns.js

@@ -0,0 +1,92 @@
+/*
+ * 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 { createKeyEvent } from '../../models/key-event.js';
+import { KeyEventDto } from '../../dto/key-event.js';
+
+/**
+ * Adds a new key event for a site.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {DataAccessConfig} config - The data access config.
+ * @param {object} log - the logger object
+ * @param {object} keyEventData - The key event data.
+ * @returns {Promise<Readonly<KeyEvent>>} newly created key event
+ */
+export const addKeyEvent = async (
+  dynamoClient,
+  config,
+  log,
+  keyEventData,
+) => {
+  const keyEvent = createKeyEvent(keyEventData);
+
+  await dynamoClient.putItem(
+    config.tableNameKeyEvents,
+    KeyEventDto.toDynamoItem(keyEvent),
+  );
+
+  return keyEvent;
+};
+
+/**
+ * Retrieves key events for a specified site.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {DataAccessConfig} config - The data access config.
+ * @param {Logger} log - The logger.
+ * @param {string} siteId - The ID of the site for which key events are being retrieved.
+ * @param {boolean} ascending - Determines if the key events should be sorted ascending
+ * or descending by createdAt.
+ * @returns {Promise<Readonly<KeyEvent>[]>} A promise that resolves to an array of key events
+ * for the specified site.
+ */
+export const getKeyEventsForSite = async (
+  dynamoClient,
+  config,
+  log,
+  siteId,
+  ascending = false,
+) => {
+  const dynamoItems = await dynamoClient.query({
+    TableName: config.tableNameKeyEvents,
+    IndexName: config.indexNameAllKeyEventsBySiteId,
+    KeyConditionExpression: 'siteId = :siteId',
+    ExpressionAttributeValues: { ':siteId': siteId },
+    ScanIndexForward: ascending, // Sorts ascending if true, descending if false
+  });
+
+  return dynamoItems.map((item) => KeyEventDto.fromDynamoItem(item));
+};
+
+/**
+ * Removes a key event.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {DataAccessConfig} config - The data access config.
+ * @param {Logger} log - The logger.
+ * @param {string} keyEventId - The ID of the key event to remove.
+ * @returns {Promise<void>}
+ */
+export const removeKeyEvent = async (
+  dynamoClient,
+  config,
+  log,
+  keyEventId,
+) => {
+  try {
+    await dynamoClient.removeItem(config.tableNameKeyEvents, { id: keyEventId });
+  } catch (error) {
+    log.error(`Error removing key event: ${error.message}`);
+    throw error;
+  }
+};

package/src/service/key-events/index.js

@@ -0,0 +1,38 @@
+/*
+ * 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 {
+  addKeyEvent,
+  getKeyEventsForSite,
+  removeKeyEvent,
+} from './accessPatterns.js';
+
+export const keyEventFunctions = (dynamoClient, config, log) => ({
+  createKeyEvent: (keyEventData) => addKeyEvent(
+    dynamoClient,
+    config,
+    log,
+    keyEventData,
+  ),
+  getKeyEventsForSite: (siteId) => getKeyEventsForSite(
+    dynamoClient,
+    config,
+    log,
+    siteId,
+  ),
+  removeKeyEvent: (keyEventId) => removeKeyEvent(
+    dynamoClient,
+    config,
+    log,
+    keyEventId,
+  ),
+});