@adobe/spacecat-shared-data-access 1.13.2 → 1.14.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-data-access-v1.14.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.14.0...@adobe/spacecat-shared-data-access-v1.14.1) (2024-02-05)
+
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#129](https://github.com/adobe/spacecat-shared/issues/129)) ([22b6c90](https://github.com/adobe/spacecat-shared/commit/22b6c90aea25783116165fa1dacb08c631c792bc))
+
+# [@adobe/spacecat-shared-data-access-v1.14.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.13.2...@adobe/spacecat-shared-data-access-v1.14.0) (2024-02-02)
+
+
+### Features
+
+* site candidate data model ([#126](https://github.com/adobe/spacecat-shared/issues/126)) ([c457645](https://github.com/adobe/spacecat-shared/commit/c4576455b514675e7f3ce1efa53ecc1372fe491a))
+
 # [@adobe/spacecat-shared-data-access-v1.13.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.13.1...@adobe/spacecat-shared-data-access-v1.13.2) (2024-01-30)
 
 

package/README.md

@@ -18,6 +18,13 @@ npm install @adobe/spacecat-shared-data-access
 - **updatedAt** (String): Timestamp of the last update.
 - **GSI1PK** (String): Partition key for the Global Secondary Index.
 
+### SiteCandidates
+- **baseURL** (String): Base URL of the site candidate.
+- **status** (String): Status of the site candidate (PENDING, IGNORED, APPROVED, ERROR)
+- **createdAt** (String): Timestamp of creation.
+- **updatedAt** (String): Timestamp of the last update.
+- **updatedBy** (String): Slack id of the last person updated the site candidate.
+
 ### Audits
 - **siteId** (String): Identifier of the site being audited.
 - **SK** (String): Sort key, typically a composite of audit type and timestamp.
@@ -65,6 +72,11 @@ The module provides two main DAOs:
 - `updateSite`
 - `removeSite`
 
+### Site Candidate Functions
+- `upsertSiteCandidate`
+- `siteCandidateExists`
+- `updateSiteCandidate`
+
 ### Audit Functions
 - `getAuditsForSite`
 - `getAuditForSite`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "1.13.2",
+  "version": "1.14.1",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "main": "src/index.js",
@@ -31,16 +31,17 @@
   "dependencies": {
     "@adobe/spacecat-shared-dynamo": "1.2.5",
     "@adobe/spacecat-shared-utils": "1.2.0",
-    "@aws-sdk/client-dynamodb": "3.501.0",
-    "@aws-sdk/lib-dynamodb": "3.501.0",
+    "@aws-sdk/client-dynamodb": "3.506.0",
+    "@aws-sdk/lib-dynamodb": "3.506.0",
     "@types/joi": "17.2.3",
-    "joi": "17.12.0",
+    "joi": "17.12.1",
     "uuid": "9.0.1"
   },
   "devDependencies": {
     "chai": "4.4.1",
     "chai-as-promised": "7.1.1",
     "dynamo-db-local": "7.3.0",
-    "sinon": "17.0.1"
+    "sinon": "17.0.1",
+    "sinon-chai": "3.7.0"
   }
 }

package/src/dto/site-candidate.js

@@ -0,0 +1,31 @@
+/*
+ * 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.
+ */
+
+/**
+ * Data transfer object for Site Candidate.
+ */
+export const SiteCandidateDto = {
+  /**
+   * Converts a Site Candidate object into a DynamoDB item.
+   * @param {Readonly<SiteCandidate>} siteCandidate - Site Candidate object.
+   * @returns {{baseURL, siteId, source, status, createdAt, updatedAt, updatedBy}}
+   */
+  toDynamoItem: (siteCandidate) => ({
+    baseURL: siteCandidate.getBaseURL(),
+    siteId: siteCandidate.getSiteId(),
+    source: siteCandidate.getSource(),
+    status: siteCandidate.getStatus(),
+    createdAt: siteCandidate.getCreatedAt(),
+    updatedAt: siteCandidate.getUpdatedAt(),
+    updatedBy: siteCandidate.getUpdatedBy(),
+  }),
+};

package/src/index.d.ts

@@ -229,6 +229,54 @@ export interface Site {
   updateOrganizationId: (organizationId: string) => Site;
 }
 
+/**
+ * Represents a site candidate.
+ */
+export interface SiteCandidate {
+  /**
+   * Retrieves the base URL of the site candidate.
+   * @returns {string} The base URL.
+   */
+  getBaseURL: () => string;
+
+  /**
+   * Retrieves the site id of the site candidate.
+   * Only set after APPROVED state
+   * @returns {string} site id
+   */
+  getSiteId: () => string;
+
+  /**
+   * Retrieves the source of the site candidate.
+   * @returns {string} The source
+   */
+  getSource: () => string;
+
+  /**
+   * Retrieves the status of the site candidate.
+   * @returns {string} The status
+   */
+  getStatus: () => string;
+
+  /**
+   * Retrieves the creation timestamp of the site candidate.
+   * @returns {string} The creation timestamp.
+   */
+  getCreatedAt: () => string;
+
+  /**
+   * Retrieves the last update timestamp of the site candidate.
+   * @returns {string} The last update timestamp.
+   */
+  getUpdatedAt: () => string;
+
+  /**
+   * Retrieves the slack id of the person who last updated the site candidate.
+   * @returns {string} The last update timestamp.
+   */
+  getUpdatedBy: () => string;
+}
+
 export interface Organization {
   /**
    * Retrieves the ID of the site.
@@ -353,6 +401,11 @@ export interface DataAccess {
   removeOrganization: (
       organizationId: string,
   ) => Promise<void>;
+
+  // site candidate functions
+  upsertSiteCandidate: (siteCandidateDate: object) => Promise<SiteCandidate>;
+  siteCandidateExists: (baseURL: string) => Promise<boolean>;
+  updateSiteCandidate: (siteCandidate: SiteCandidate) => Promise<SiteCandidate>;
 }
 
 interface DataAccessConfig {
@@ -360,6 +413,7 @@ interface DataAccessConfig {
   tableNameLatestAudits: string;
   tableNameOrganizations: string,
   tableNameSites: string;
+  tableNameSiteCandidates: string;
   indexNameAllSites: string;
   indexNameAllSitesOrganizations: string,
   indexNameAllSitesByDeliveryType: string;

package/src/index.js

@@ -15,6 +15,7 @@ import { createDataAccess } from './service/index.js';
 const TABLE_NAME_AUDITS = 'spacecat-services-audits-dev';
 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';
 const TABLE_NAME_ORGANIZATIONS = 'spacecat-services-organizations-dev';
 
 const INDEX_NAME_ALL_SITES = 'spacecat-services-all-sites-dev';
@@ -36,6 +37,7 @@ export default function dataAccessWrapper(fn) {
         DYNAMO_TABLE_NAME_AUDITS = TABLE_NAME_AUDITS,
         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_INDEX_NAME_ALL_SITES = INDEX_NAME_ALL_SITES,
         DYNAMO_INDEX_NAME_ALL_SITES_BY_DELIVERY_TYPE = INDEX_NAME_ALL_SITES_BY_DELIVERY_TYPE,
@@ -49,6 +51,7 @@ export default function dataAccessWrapper(fn) {
         tableNameLatestAudits: DYNAMO_TABLE_NAME_LATEST_AUDITS,
         tableNameOrganizations: DYNAMO_TABLE_NAME_ORGANIZATIONS,
         tableNameSites: DYNAMO_TABLE_NAME_SITES,
+        tableNameSiteCandidates: DYNAMO_TABLE_NAME_SITE_CANDIDATES,
         indexNameAllSites: DYNAMO_INDEX_NAME_ALL_SITES,
         indexNameAllOrganizations: DYNAMO_INDEX_NAME_ALL_ORGANIZATIONS,
         indexNameAllSitesByDeliveryType: DYNAMO_INDEX_NAME_ALL_SITES_BY_DELIVERY_TYPE,

package/src/models/site-candidate.js

@@ -0,0 +1,96 @@
+/*
+ * 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, isValidUrl } from '@adobe/spacecat-shared-utils';
+
+import { Base } from './base.js';
+
+export const DEFAULT_UPDATED_BY = 'spacecat';
+
+export const SITE_CANDIDATE_SOURCES = {
+  SPACECAT_SLACK_BOT: 'SPACECAT_SLACK_BOT',
+  RUM: 'RUM',
+  CDN: 'CDN',
+};
+
+export const SITE_CANDIDATE_STATUS = {
+  PENDING: 'PENDING', // site candidate notification sent and waiting for human input
+  IGNORED: 'IGNORED', // site candidate discarded: not to be added to star catalogue
+  APPROVED: 'APPROVED', // site candidate is added to star catalogue
+  ERROR: 'ERROR', // site candidate is discovered
+};
+
+/**
+ * Creates a new Site Candidate.
+ *
+ * @param {object} data - site candidate data
+ * @returns {Readonly<SiteCandidate>} new site candidate
+ */
+const SiteCandidate = (data = {}) => {
+  const self = Base({
+    updatedBy: DEFAULT_UPDATED_BY,
+    ...data,
+  });
+  delete self.id; // no id property used in SiteCandidate modal
+
+  self.getBaseURL = () => self.state.baseURL;
+  self.getSiteId = () => self.state.siteId;
+  self.getSource = () => self.state.source;
+  self.getStatus = () => self.state.status;
+  self.getUpdatedBy = () => self.state.updatedBy;
+
+  self.setSiteId = (siteId) => {
+    self.state.siteId = siteId;
+    self.touch();
+    return self;
+  };
+
+  self.setSource = (source) => {
+    self.state.source = source;
+    self.touch();
+    return self;
+  };
+
+  self.setStatus = (status) => {
+    self.state.status = status;
+    self.touch();
+    return self;
+  };
+
+  self.setUpdatedBy = (updatedBy) => {
+    self.state.updatedBy = updatedBy;
+    self.touch();
+    return self;
+  };
+
+  return Object.freeze(self);
+};
+
+/**
+ * Creates a new Site Candidate.
+ *
+ * @param {object} data - site candidate data
+ * @returns {Readonly<SiteCandidate>} new site candidate
+ */
+export const createSiteCandidate = (data) => {
+  const newState = { ...data };
+
+  if (!isValidUrl(newState.baseURL)) {
+    throw new Error('Base URL must be a valid URL');
+  }
+
+  if (!hasText(newState.updatedBy)) {
+    newState.updatedBy = DEFAULT_UPDATED_BY;
+  }
+
+  return SiteCandidate(newState);
+};

package/src/service/index.js

@@ -13,6 +13,7 @@
 import { createClient } from '@adobe/spacecat-shared-dynamo';
 import { auditFunctions } from './audits/index.js';
 import { siteFunctions } from './sites/index.js';
+import { siteCandidateFunctions } from './site-candidates/index.js';
 import { organizationFunctions } from './organizations/index.js';
 
 /**
@@ -30,11 +31,13 @@ export const createDataAccess = (config, log = console) => {
 
   const auditFuncs = auditFunctions(dynamoClient, config, log);
   const siteFuncs = siteFunctions(dynamoClient, config, log);
+  const siteCandidateFuncs = siteCandidateFunctions(dynamoClient, config, log);
   const organizationFuncs = organizationFunctions(dynamoClient, config, log);
 
   return {
     ...auditFuncs,
     ...siteFuncs,
+    ...siteCandidateFuncs,
     ...organizationFuncs,
   };
 };

package/src/service/site-candidates/accessPatterns.js

@@ -0,0 +1,86 @@
+/*
+ * 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 { createSiteCandidate } from '../../models/site-candidate.js';
+import { SiteCandidateDto } from '../../dto/site-candidate.js';
+
+/**
+ * Checks if a site candidate exists in site candidates table using base url
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {DataAccessConfig} config - The data access config.
+ * @param {string} baseURL - base url of the site candidate.
+ * @return {Promise<Readonly<Boolean>>} A promise that resolves to true if site candidate exist
+ */
+export const exists = async (dynamoClient, config, baseURL) => {
+  const dynamoItem = await dynamoClient.getItem(config.tableNameSiteCandidates, { baseURL });
+
+  return isObject(dynamoItem);
+};
+
+/**
+ * Upserts a site candidate.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {DataAccessConfig} config - The data access config.
+ * @param {object} log - the logger object
+ * @param {object} siteCandidateData - The site candidate data.
+ * @returns {Promise<Readonly<SiteCandidate>>} newly created site candidate if hadn't created before
+ */
+export const upsertSiteCandidate = async (
+  dynamoClient,
+  config,
+  log,
+  siteCandidateData,
+) => {
+  const siteCandidate = createSiteCandidate(siteCandidateData);
+  const siteCandidateExists = await exists(dynamoClient, config, siteCandidate.getBaseURL());
+
+  if (siteCandidateExists) {
+    log.info(`Ignoring the site candidate with base url ${siteCandidate.getBaseURL()} because it already exists`);
+    return siteCandidate;
+  }
+
+  await dynamoClient.putItem(
+    config.tableNameSiteCandidates,
+    SiteCandidateDto.toDynamoItem(siteCandidate),
+  );
+
+  return siteCandidate;
+};
+
+/**
+ * Updates a site candidate.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {DataAccessConfig} config - The data access config.
+ * @param {SiteCandidate} siteCandidate - The site candidate object to be updated.
+ * @returns {Promise<Readonly<Site>>} - The updated site candidate.
+ */
+export const updateSiteCandidate = async (
+  dynamoClient,
+  config,
+  siteCandidate,
+) => {
+  const siteCandidateExists = await exists(dynamoClient, config, siteCandidate.getBaseURL());
+
+  if (!siteCandidateExists) {
+    throw new Error(`Site candidate with base url ${siteCandidate.getBaseURL()} does not exist`);
+  }
+
+  await dynamoClient.putItem(
+    config.tableNameSiteCandidates,
+    SiteCandidateDto.toDynamoItem(siteCandidate),
+  );
+
+  return siteCandidate;
+};

package/src/service/site-candidates/index.js

@@ -0,0 +1,36 @@
+/*
+ * 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 {
+  upsertSiteCandidate,
+  exists,
+  updateSiteCandidate,
+} from './accessPatterns.js';
+
+export const siteCandidateFunctions = (dynamoClient, config, log) => ({
+  upsertSiteCandidate: (siteCandidateData) => upsertSiteCandidate(
+    dynamoClient,
+    config,
+    log,
+    siteCandidateData,
+  ),
+  siteCandidateExists: (baseUrl) => exists(
+    dynamoClient,
+    config,
+    baseUrl,
+  ),
+  updateSiteCandidate: (siteCandidateData) => updateSiteCandidate(
+    dynamoClient,
+    config,
+    siteCandidateData,
+  ),
+});