@adobe/spacecat-shared-data-access 1.0.0

package/src/index.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2023 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 { createDataAccess } from './service/index.js';
+
+export default function dataAccessWrapper(fn) {
+  return async (request, context) => {
+    if (!context.dataAccess) {
+      const { log } = context;
+      context.dataAccess = createDataAccess(log);
+    }
+
+    return fn(request, context);
+  };
+}

package/src/models/audit.js

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2023 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, isObject } from '@adobe/spacecat-shared-utils';
+import { Base } from './base.js';
+
+export const AUDIT_TYPE_CWV = 'cwv';
+export const AUDIT_TYPE_LHS = 'lhs';
+
+const EXPIRES_IN_DAYS = 30;
+
+const AUDIT_TYPE_PROPERTIES = {
+  [AUDIT_TYPE_CWV]: [],
+  [AUDIT_TYPE_LHS]: ['performance', 'seo', 'accessibility', 'best-practices'],
+};
+
+/**
+ * Validates if the auditResult contains the required properties for the given audit type.
+ * @param {object} auditResult - The audit result to validate.
+ * @param {string} auditType - The type of the audit.
+ * @returns {boolean} - True if valid, false otherwise.
+ */
+const validateAuditResult = (auditResult, auditType) => {
+  const expectedProperties = AUDIT_TYPE_PROPERTIES[auditType];
+  if (!expectedProperties) {
+    throw new Error(`Unknown audit type: ${auditType}`);
+  }
+
+  for (const prop of expectedProperties) {
+    if (!(prop in auditResult)) {
+      throw new Error(`Missing expected property '${prop}' for audit type '${auditType}'`);
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Creates a new Audit.
+ * @param {object } data - audit data
+ * @returns {Readonly<Audit>} audit - new audit
+ */
+const Audit = (data = {}) => {
+  const self = Base(data);
+
+  self.getSiteId = () => self.state.siteId;
+  self.getAuditedAt = () => self.state.auditedAt;
+  self.getAuditResult = () => self.state.auditResult;
+  self.getAuditType = () => self.state.auditType.toLowerCase();
+  self.getExpiresAt = () => self.state.expiresAt;
+  self.getFullAuditRef = () => self.state.fullAuditRef;
+  self.getScores = () => self.getAuditResult();
+
+  return Object.freeze(self);
+};
+
+/**
+ * Creates a new Audit.
+ *
+ * @param {object} data - audit data
+ * @returns {Readonly<Audit>} audit - new audit
+ */
+export const createAudit = (data) => {
+  const newState = { ...data };
+
+  if (!hasText(newState.siteId)) {
+    throw new Error('Site ID must be provided');
+  }
+
+  if (!isIsoDate(newState.auditedAt)) {
+    throw new Error('Audited at must be a valid ISO date');
+  }
+
+  if (!hasText(newState.auditType)) {
+    throw new Error('Audit type must be provided');
+  }
+
+  if (!isObject(newState.auditResult)) {
+    throw new Error('Audit result must be an object');
+  }
+
+  validateAuditResult(data.auditResult, data.auditType);
+
+  if (!hasText(newState.fullAuditRef)) {
+    throw new Error('Full audit ref must be provided');
+  }
+
+  if (!newState.expiresAt) {
+    newState.expiresAt = new Date(newState.auditedAt);
+    newState.expiresAt.setDate(newState.expiresAt.getDate() + EXPIRES_IN_DAYS);
+  }
+
+  return Audit(newState);
+};

package/src/models/base.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2023 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 { v4 as uuidv4 } from 'uuid';
+import { isString } from '@adobe/spacecat-shared-utils';
+
+/**
+ * Base model.
+ *
+ * @param {object} data data
+ * @returns {Base} base model
+ */
+export const Base = (data = {}) => {
+  const self = { state: { ...data } };
+  const newRecord = !isString(self.state.id);
+  const nowISO = new Date().toISOString();
+
+  if (newRecord) {
+    self.state.id = uuidv4();
+    self.state.createdAt = nowISO;
+    self.state.updatedAt = nowISO;
+  }
+
+  self.getId = () => self.state.id;
+  self.getCreatedAt = () => self.state.createdAt;
+  self.getUpdatedAt = () => self.state.updatedAt;
+
+  self.touch = () => {
+    self.state.updatedAt = new Date().toISOString();
+  };
+
+  return self;
+};

package/src/models/site.js

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2023 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';
+
+/**
+ * Creates a new Site.
+ *
+ * @param {object} data - site data
+ * @returns {Readonly<Site>} site - new site
+ */
+const Site = (data = {}) => {
+  const self = Base(data);
+
+  self.getAudits = () => self.state.audits;
+  self.getBaseURL = () => self.state.baseURL;
+  self.getImsOrgId = () => self.state.imsOrgId;
+
+  // TODO: updating the baseURL is not supported yet, it will require a transact write
+  //  on dynamodb (put then delete) since baseURL is part of the primary key, something like:
+  // const updateSiteBaseURL = async (oldBaseURL, updatedSiteData) => {
+  //   const params = {
+  //     TransactItems: [
+  //       {
+  //         Put: {
+  //           TableName: 'YourSiteTableName',
+  //           Item: updatedSiteData,
+  //         },
+  //       },
+  //       {
+  //         Delete: {
+  //           TableName: 'YourSiteTableName',
+  //           Key: {
+  //             baseURL: oldBaseURL,
+  //           },
+  //         },
+  //       },
+  //     ],
+  //   };
+  //
+  //   await dynamoDbClient.transactWrite(params).promise();
+  //
+  //   return createSite(updatedSiteData);
+  // };
+  /*  self.updateBaseURL = (baseURL) => {
+    if (!isValidUrl(baseURL)) {
+      throw new Error('Base URL must be a valid URL');
+    }
+
+    self.state.baseURL = baseURL;
+    self.touch();
+
+    return self;
+  }; */
+
+  self.updateImsOrgId = (imsOrgId) => {
+    if (!hasText(imsOrgId)) {
+      throw new Error('IMS Org ID must be provided');
+    }
+
+    self.state.imsOrgId = imsOrgId;
+    self.touch();
+
+    return self;
+  };
+
+  self.setAudits = (audits) => {
+    self.state.audits = audits;
+    return self;
+  };
+
+  return Object.freeze(self);
+};
+
+/**
+ * Creates a new Site.
+ *
+ * @param {object} data - site data
+ * @returns {Readonly<Site>} site - new site
+ */
+export const createSite = (data) => {
+  const newState = { ...data };
+
+  if (!isValidUrl(newState.baseURL)) {
+    throw new Error('Base URL must be a valid URL');
+  }
+
+  if (!Array.isArray(newState.audits)) {
+    newState.audits = [];
+  }
+
+  return Site(newState);
+};

package/src/service/audits/accessPatterns.js

@@ -0,0 +1,231 @@
+/*
+ * Copyright 2023 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 { AuditDto } from '../../dto/audit.js';
+import { createAudit } from '../../models/audit.js';
+
+const TABLE_NAME_AUDITS = 'audits';
+const TABLE_NAME_LATEST_AUDITS = 'latest_audits';
+const INDEX_NAME_ALL_LATEST_AUDIT_SCORES = 'all_latest_audit_scores';
+const PK_ALL_LATEST_AUDITS = 'ALL_LATEST_AUDITS';
+
+/**
+ * Retrieves audits for a specified site. If an audit type is provided,
+ * it returns only audits of that type.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {Logger} log - The logger.
+ * @param {string} siteId - The ID of the site for which audits are being retrieved.
+ * @param {string} [auditType] - Optional. The type of audits to retrieve.
+ * @returns {Promise<Readonly<Audit>[]>} A promise that resolves to an array of audits
+ * for the specified site.
+ */
+export const getAuditsForSite = async (dynamoClient, log, siteId, auditType) => {
+  const queryParams = {
+    TableName: TABLE_NAME_AUDITS,
+    KeyConditionExpression: 'siteId = :siteId',
+    ExpressionAttributeValues: {
+      ':siteId': siteId,
+    },
+  };
+
+  if (auditType !== undefined) {
+    queryParams.KeyConditionExpression += ' AND begins_with(SK, :auditType)';
+    queryParams.ExpressionAttributeValues[':auditType'] = `${auditType}#`;
+  }
+
+  const dynamoItems = await dynamoClient.query(queryParams);
+
+  return dynamoItems.map((item) => AuditDto.fromDynamoItem(item));
+};
+
+/**
+ * Retrieves a specific audit for a specified site.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {Logger} log - The logger.
+ * @param {string} siteId - The ID of the site for which to retrieve the audit.
+ * @param {string} auditType - The type of audit to retrieve.
+ * @param auditedAt - The ISO 8601 timestamp of the audit.
+ * @returns {Promise<Readonly<Audit>|null>}
+ */
+export const getAuditForSite = async (
+  dynamoClient,
+  log,
+  siteId,
+  auditType,
+  auditedAt,
+) => {
+  const audit = await dynamoClient.query({
+    TableName: TABLE_NAME_AUDITS,
+    KeyConditionExpression: 'siteId = :siteId AND SK = :sk',
+    ExpressionAttributeValues: {
+      ':siteId': siteId,
+      ':sk': `${auditType}#${auditedAt}`,
+    },
+    Limit: 1,
+  });
+
+  return audit.length > 0 ? AuditDto.fromDynamoItem(audit[0]) : null;
+};
+
+/**
+ * Retrieves the latest audits of a specific type across all sites.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {Logger} log - The logger.
+ * @param {string} auditType - The type of audits to retrieve.
+ * @param {boolean} ascending - Determines if the audits should be sorted ascending
+ * or descending by scores.
+ * @returns {Promise<Readonly<Audit>[]>} A promise that resolves to an array of the latest
+ * audits of the specified type.
+ */
+export const getLatestAudits = async (
+  dynamoClient,
+  log,
+  auditType,
+  ascending = true,
+) => {
+  const dynamoItems = await dynamoClient.query({
+    TableName: TABLE_NAME_LATEST_AUDITS,
+    IndexName: INDEX_NAME_ALL_LATEST_AUDIT_SCORES,
+    KeyConditionExpression: 'GSI1PK = :gsi1pk AND begins_with(GSI1SK, :auditType)',
+    ExpressionAttributeValues: {
+      ':gsi1pk': PK_ALL_LATEST_AUDITS,
+      ':auditType': `${auditType}#`,
+    },
+    ScanIndexForward: ascending, // Sorts ascending if true, descending if false
+  });
+
+  return dynamoItems.map((item) => AuditDto.fromDynamoItem(item));
+};
+
+/**
+ * Retrieves latest audits for a specified site.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {Logger} log - The logger.
+ * @param {string} siteId - The ID of the site for which audits are being retrieved.
+ * @returns {Promise<Readonly<Audit>[]>} A promise that resolves to an array of latest audits
+ * for the specified site.
+ */
+export const getLatestAuditsForSite = async (dynamoClient, log, siteId) => {
+  const queryParams = {
+    TableName: TABLE_NAME_LATEST_AUDITS,
+    KeyConditionExpression: 'siteId = :siteId',
+    ExpressionAttributeValues: { ':siteId': siteId },
+  };
+
+  const dynamoItems = await dynamoClient.query(queryParams);
+
+  return dynamoItems.map((item) => AuditDto.fromDynamoItem(item));
+};
+
+/**
+ * Retrieves the latest audit for a specified site and audit type.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {Logger} log - The logger.
+ * @param {string} siteId - The ID of the site for which the latest audit is being retrieved.
+ * @param {string} auditType - The type of audit to retrieve the latest instance of.
+ * @returns {Promise<Audit|null>} A promise that resolves to the latest audit of the
+ * specified type for the site, or null if none is found.
+ */
+export const getLatestAuditForSite = async (
+  dynamoClient,
+  log,
+  siteId,
+  auditType,
+) => {
+  const latestAudit = await dynamoClient.query({
+    TableName: TABLE_NAME_LATEST_AUDITS,
+    KeyConditionExpression: 'siteId = :siteId AND begins_with(SK, :auditType)',
+    ExpressionAttributeValues: {
+      ':siteId': siteId,
+      ':auditType': `${auditType}#`,
+    },
+    Limit: 1,
+  });
+
+  return latestAudit.length > 0 ? AuditDto.fromDynamoItem(latestAudit[0]) : null;
+};
+
+/**
+ * Adds an audit.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {Logger} log - The logger.
+ * @param {object} auditData - The audit data.
+ * @returns {Promise<Readonly<Audit>>}
+ */
+export const addAudit = async (dynamoClient, log, auditData) => {
+  const audit = createAudit(auditData);
+  const existingAudit = await getAuditForSite(
+    dynamoClient,
+    log,
+    audit.getSiteId(),
+    audit.getAuditType(),
+    audit.getAuditedAt(),
+  );
+
+  if (isObject(existingAudit)) {
+    throw new Error('Audit already exists');
+  }
+
+  // TODO: Add transaction support
+  await dynamoClient.putItem('audits', AuditDto.toDynamoItem(audit));
+  await dynamoClient.putItem('latest_audits', AuditDto.toDynamoItem(audit, true));
+
+  return audit;
+};
+
+/**
+ * Removes audits from the database.
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {Logger} log - The logger.
+ * @param audits
+ * @param latest
+ * @returns {Promise<void>}
+ */
+async function removeAudits(dynamoClient, audits, latest = false) {
+  const tableName = latest ? TABLE_NAME_LATEST_AUDITS : TABLE_NAME_AUDITS;
+  // TODO: use batch-remove (needs dynamo client update)
+  const removeAuditPromises = audits.map((audit) => dynamoClient.removeItem(tableName, {
+    siteId: audit.getSiteId(),
+    SK: `${audit.getAuditType()}#${audit.getAuditedAt()}`,
+  }));
+
+  await Promise.all(removeAuditPromises);
+}
+
+/**
+ * Removes all audits for a specified site and the latest audit entry.
+ *
+ * @param {DynamoDbClient} dynamoClient - The DynamoDB client.
+ * @param {Logger} log - The logger.
+ * @param {string} siteId - The ID of the site for which audits are being removed.
+ * @returns {Promise<void>}
+ */
+export const removeAuditsForSite = async (dynamoClient, log, siteId) => {
+  try {
+    const audits = await getAuditsForSite(dynamoClient, log, siteId);
+    const latestAudits = await getLatestAuditsForSite(dynamoClient, log, siteId);
+
+    await removeAudits(dynamoClient, audits);
+    await removeAudits(dynamoClient, latestAudits, true);
+  } catch (error) {
+    log.error(`Error removing audits for site ${siteId}: ${error.message}`);
+    throw error;
+  }
+};

package/src/service/audits/index.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2023 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 {
+  addAudit, getAuditForSite,
+  getAuditsForSite,
+  getLatestAuditForSite,
+  getLatestAudits,
+  removeAuditsForSite,
+} from './accessPatterns.js';
+
+export const auditFunctions = (dynamoClient, log) => ({
+  getAuditForSite: (siteId, auditType, auditedAt) => getAuditForSite(
+    dynamoClient,
+    log,
+    siteId,
+    auditType,
+    auditedAt,
+  ),
+  getAuditsForSite: (siteId, auditType) => getAuditsForSite(
+    dynamoClient,
+    log,
+    siteId,
+    auditType,
+  ),
+  getLatestAudits: (auditType, ascending) => getLatestAudits(
+    dynamoClient,
+    log,
+    auditType,
+    ascending,
+  ),
+  getLatestAuditForSite: (siteId, auditType) => getLatestAuditForSite(
+    dynamoClient,
+    log,
+    siteId,
+    auditType,
+  ),
+  addAudit: (auditData) => addAudit(
+    dynamoClient,
+    log,
+    auditData,
+  ),
+  removeAuditsForSite: (siteId) => removeAuditsForSite(
+    dynamoClient,
+    log,
+    siteId,
+  ),
+});

package/src/service/index.js

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2023 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 { createClient } from '@adobe/spacecat-shared-dynamo';
+import { auditFunctions } from './audits/index.js';
+import { siteFunctions } from './sites/index.js';
+
+/**
+ * Creates a data access object.
+ *
+ * @param {Logger} log logger
+ * @returns {object} data access object
+ */
+export const createDataAccess = (log = console) => {
+  const dynamoClient = createClient(log);
+
+  const auditFuncs = auditFunctions(dynamoClient, log);
+  const siteFuncs = siteFunctions(dynamoClient, log);
+
+  return {
+    ...auditFuncs,
+    ...siteFuncs,
+  };
+};