@adobe/spacecat-shared-data-access 1.59.2 → 1.60.0

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

@@ -0,0 +1,283 @@
+/*
+ * 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, isNonEmptyObject } from '@adobe/spacecat-shared-utils';
+
+import {
+  classExtends,
+  entityNameToCollectionName,
+  entityNameToIdName,
+  isNonEmptyArray,
+  isPositiveInteger,
+  keyNamesToMethodName,
+  modelNameToEntityName,
+} from '../../util/util.js';
+
+import BaseCollection from './base.collection.js';
+import BaseModel from './base.model.js';
+import { INDEX_TYPES } from './constants.js';
+import Reference from './reference.js';
+
+class Schema {
+  /**
+   * Constructs a new Schema instance.
+   * @constructor
+   * @param {BaseModel} modelClass - The class representing the model.
+   * @param {BaseCollection} collectionClass - The class representing the model collection.
+   * @param {object} rawSchema - The raw schema data.
+   * @param {string} rawSchema.serviceName - The name of the service.
+   * @param {number} rawSchema.schemaVersion - The version of the schema.
+   * @param {object} rawSchema.attributes - The attributes of the schema.
+   * @param {object} rawSchema.indexes - The indexes of the schema.
+   * @param {Reference[]} [rawSchema.references] - The references of the schema.
+   */
+  constructor(
+    modelClass,
+    collectionClass,
+    rawSchema,
+  ) {
+    this.modelClass = modelClass;
+    this.collectionClass = collectionClass;
+
+    this.serviceName = rawSchema.serviceName;
+    this.schemaVersion = rawSchema.schemaVersion;
+    this.attributes = rawSchema.attributes;
+    this.indexes = rawSchema.indexes;
+    this.references = rawSchema.references || [];
+
+    this.#validateSchema();
+  }
+
+  #validateSchema() {
+    if (!classExtends(this.modelClass, BaseModel)) {
+      throw new Error('Model class must extend BaseModel');
+    }
+
+    if (!classExtends(this.collectionClass, BaseCollection)) {
+      throw new Error('Collection class must extend BaseCollection');
+    }
+
+    if (!hasText(this.serviceName)) {
+      throw new Error('Schema must have a service name');
+    }
+
+    if (!isPositiveInteger(this.schemaVersion)) {
+      throw new Error('Schema version must be a positive integer');
+    }
+
+    if (!isNonEmptyObject(this.attributes)) {
+      throw new Error('Schema must have attributes');
+    }
+
+    if (!isNonEmptyObject(this.indexes)) {
+      throw new Error('Schema must have indexes');
+    }
+
+    if (!Array.isArray(this.references)) {
+      throw new Error('References must be an array');
+    }
+  }
+
+  getAttribute(name) {
+    return this.attributes[name];
+  }
+
+  getAttributes() {
+    return this.attributes;
+  }
+
+  getCollectionName() {
+    return this.collectionClass.name;
+  }
+
+  getEntityName() {
+    return modelNameToEntityName(this.getModelName());
+  }
+
+  getIdName() {
+    return entityNameToIdName(this.getModelName());
+  }
+
+  /**
+   * Returns a data structure describing all index-based accessors (like allByX, findByX).
+   * This can then be used by BaseCollection to create methods without duplicating logic.
+   * @return {Array<{indexName: string, keySets: string[][]}>}
+   *   Example: [
+   *     { indexName: 'byOpportunityId', keySets: [['opportunityId'], ['opportunityId','status']] },
+   *     { indexName: 'byStatusAndCreatedAt', keySets: [['status'],['status','createdAt']] }
+   *   ]
+   */
+  getIndexAccessors() {
+    const indexes = this.getIndexes([INDEX_TYPES.PRIMARY]);
+    const result = [];
+
+    Object.keys(indexes).forEach((indexName) => {
+      const indexKeys = this.getIndexKeys(indexName);
+
+      if (!isNonEmptyArray(indexKeys)) return;
+
+      const keySets = [];
+      for (let i = 1; i <= indexKeys.length; i += 1) {
+        keySets.push(indexKeys.slice(0, i));
+      }
+
+      result.push({ indexName, keySets });
+    });
+
+    return result;
+  }
+
+  getIndexByName(indexName) {
+    return this.indexes[indexName];
+  }
+
+  /**
+   * Returns the indexes for the schema. By default, this returns all indexes.
+   * You can use the `exclude` parameter to exclude certain indexes.
+   * @param {Array<string>} [exclude] - One of the INDEX_TYPES values.
+   * @return {object} The indexes.
+   */
+  getIndexes(exclude) {
+    if (!Array.isArray(exclude)) {
+      return this.indexes;
+    }
+
+    return Object.keys(this.indexes).reduce((acc, indexName) => {
+      const index = this.indexes[indexName];
+
+      if (!exclude.includes(indexName)) {
+        acc[indexName] = index;
+      }
+
+      return acc;
+    }, {});
+  }
+
+  getIndexKeys(indexName) {
+    const index = this.getIndexByName(indexName);
+
+    if (!isNonEmptyObject(index)) {
+      return [];
+    }
+
+    const pkKeys = Array.isArray(index.pk?.facets) ? index.pk.facets : [];
+    const skKeys = Array.isArray(index.sk?.facets) ? index.sk.facets : [index.sk?.field];
+
+    return [...pkKeys, ...skKeys];
+  }
+
+  getModelClass() {
+    return this.modelClass;
+  }
+
+  getModelName() {
+    return this.modelClass.name;
+  }
+
+  /**
+   * Given a type and a target model name, returns the reciprocal reference if it exists.
+   * For example, if we have a has_many reference from Foo to Bar, this method can help find
+   * the belongs_to reference in Bar that points back to Foo.
+   * @param {EntityRegistry} registry - The entity registry.
+   * @param {Reference} reference - The reference to find the reciprocal for.
+   * @return {Reference|null} - The reciprocal reference or null if not found.
+   */
+  getReciprocalReference(registry, reference) {
+    const target = reference.getTarget();
+    const type = reference.getType();
+
+    if (type !== Reference.TYPES.HAS_MANY) {
+      return null;
+    }
+
+    const targetSchema = registry.getCollection(entityNameToCollectionName(target)).schema;
+
+    return targetSchema.getReferenceByTypeAndTarget(
+      Reference.TYPES.BELONGS_TO,
+      this.getModelName(),
+    );
+  }
+
+  getReferences() {
+    return this.references;
+  }
+
+  getReferencesByType(type) {
+    return this.references.filter((ref) => ref.type === type);
+  }
+
+  getReferenceByTypeAndTarget(type, target) {
+    return this.references.find((ref) => ref.type === type && ref.target === target);
+  }
+
+  getServiceName() {
+    return this.serviceName;
+  }
+
+  getVersion() {
+    return this.schemaVersion;
+  }
+
+  toAccessorConfigs(entity, log) {
+    const indexAccessors = this.getIndexAccessors();
+    const accessorConfigs = [];
+
+    indexAccessors.forEach(({ indexName, keySets }) => {
+      // generate a method for each prefix of the keySets array
+      // for example, if keySets = ['opportunityId', 'status'], we create:
+      //   allByOpportunityId(...)
+      //   findByOpportunityId(...)
+      //   allByOpportunityIdAndStatus(...)
+      //   findByOpportunityIdAndStatus(...)
+      keySets.forEach((subset) => {
+        accessorConfigs.push({
+          context: entity,
+          collection: entity,
+          name: keyNamesToMethodName(subset, 'allBy'),
+          requiredKeys: subset,
+          all: true,
+        });
+
+        accessorConfigs.push({
+          context: entity,
+          collection: entity,
+          name: keyNamesToMethodName(subset, 'findBy'),
+          requiredKeys: subset,
+        });
+
+        log.info(`Created accessors for index [${indexName}] with keys [${subset.join(', ')}]`);
+      });
+    });
+
+    return accessorConfigs;
+  }
+
+  /**
+   * Transforms the stored schema model into a format directly usable by ElectroDB.
+   * Here, you could do any final adjustments or transformations needed before returning.
+   *
+   * @returns {object} ElectroDB-compatible schema.
+   */
+  toElectroDBSchema() {
+    return {
+      model: {
+        entity: this.getModelName(),
+        version: String(this.getVersion()),
+        service: this.getServiceName(),
+      },
+      attributes: this.attributes,
+      indexes: this.indexes,
+    };
+  }
+}
+
+export default Schema;

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

@@ -0,0 +1,39 @@
+/*
+ * 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 { incrementVersion, sanitizeIdAndAuditFields } from '../../util/util.js';
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * ConfigurationCollection - A collection class responsible for managing Configuration entities.
+ * Extends the BaseCollection to provide specific methods for interacting with
+ * Configuration records.
+ *
+ * @class ConfigurationCollection
+ * @extends BaseCollection
+ */
+class ConfigurationCollection extends BaseCollection {
+  async create(data) {
+    const latestConfiguration = await this.findLatest();
+    const version = latestConfiguration ? incrementVersion(latestConfiguration.getVersion()) : 1;
+    const sanitizedData = sanitizeIdAndAuditFields('Organization', data);
+    sanitizedData.version = version;
+
+    return super.create(sanitizedData);
+  }
+
+  async findLatest() {
+    return this.findByAll({}, { order: 'desc' });
+  }
+}
+
+export default ConfigurationCollection;

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

@@ -0,0 +1,160 @@
+/*
+ * 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 { sanitizeIdAndAuditFields } from '../../util/util.js';
+import BaseModel from '../base/base.model.js';
+
+/**
+ * Configuration - A class representing an Configuration entity.
+ * Provides methods to access and manipulate Configuration-specific data.
+ *
+ * @class Configuration
+ * @extends BaseModel
+ */
+class Configuration extends BaseModel {
+  // add your custom methods or overrides here
+
+  getHandler(type) {
+    return this.getHandlers()?.[type];
+  }
+
+  addHandler = (type, handlerData) => {
+    const handlers = this.getHandlers() || {};
+    handlers[type] = { ...handlerData };
+
+    this.setHandlers(handlers);
+  };
+
+  getSlackRoleMembersByRole(role) {
+    return this.getSlackRoles()?.[role] || [];
+  }
+
+  getEnabledSiteIdsForHandler(type) {
+    return this.getHandler(type)?.enabled?.sites || [];
+  }
+
+  isHandlerEnabledForSite(type, site) {
+    const handler = this.getHandlers()?.[type];
+    if (!handler) return false;
+
+    const siteId = site.getId();
+    const orgId = site.getOrganizationId();
+
+    if (handler.enabled) {
+      const sites = handler.enabled.sites || [];
+      const orgs = handler.enabled.orgs || [];
+      return sites.includes(siteId) || orgs.includes(orgId);
+    }
+
+    if (handler.disabled) {
+      const sites = handler.disabled.sites || [];
+      const orgs = handler.disabled.orgs || [];
+      return !(sites.includes(siteId) || orgs.includes(orgId));
+    }
+
+    return handler.enabledByDefault;
+  }
+
+  isHandlerEnabledForOrg(type, org) {
+    const handler = this.getHandlers()?.[type];
+    if (!handler) return false;
+
+    const orgId = org.getId();
+
+    if (handler.enabled) {
+      return handler.enabled.orgs?.includes(orgId);
+    }
+
+    if (handler.disabled) {
+      return !handler.disabled.orgs?.includes(orgId);
+    }
+
+    return handler.enabledByDefault;
+  }
+
+  #updatedHandler(type, entityId, enabled, entityKey) {
+    const handlers = this.getHandlers();
+    const handler = handlers?.[type];
+
+    if (!isNonEmptyObject(handler)) return;
+
+    if (!isNonEmptyObject(handler.disabled)) {
+      handler.disabled = { orgs: [], sites: [] };
+    }
+
+    if (!isNonEmptyObject(handler.enabled)) {
+      handler.enabled = { orgs: [], sites: [] };
+    }
+
+    if (enabled) {
+      if (handler.enabledByDefault) {
+        handler.disabled[entityKey] = handler.disabled[entityKey]
+          .filter((id) => id !== entityId) || [];
+      } else {
+        handler.enabled[entityKey] = Array
+          .from(new Set([...(handler.enabled[entityKey] || []), entityId]));
+      }
+    } else if (handler.enabledByDefault) {
+      handler.disabled[entityKey] = Array
+        .from(new Set([...(handler.disabled[entityKey] || []), entityId]));
+    } else {
+      handler.enabled[entityKey] = handler.enabled[entityKey].filter((id) => id !== entityId) || [];
+    }
+
+    handlers[type] = handler;
+    this.setHandlers(handlers);
+  }
+
+  updateHandlerOrgs(type, orgId, enabled) {
+    this.#updatedHandler(type, orgId, enabled, 'orgs');
+  }
+
+  updateHandlerSites(type, siteId, enabled) {
+    this.#updatedHandler(type, siteId, enabled, 'sites');
+  }
+
+  enableHandlerForSite(type, site) {
+    const siteId = site.getId();
+    if (this.isHandlerEnabledForSite(type, site)) return;
+
+    this.updateHandlerSites(type, siteId, true);
+  }
+
+  enableHandlerForOrg(type, org) {
+    const orgId = org.getId();
+    if (this.isHandlerEnabledForOrg(type, org)) return;
+
+    this.updateHandlerOrgs(type, orgId, true);
+  }
+
+  disableHandlerForSite(type, site) {
+    const siteId = site.getId();
+    if (!this.isHandlerEnabledForSite(type, site)) return;
+
+    this.updateHandlerSites(type, siteId, false);
+  }
+
+  disableHandlerForOrg(type, org) {
+    const orgId = org.getId();
+    if (!this.isHandlerEnabledForOrg(type, org)) return;
+
+    this.updateHandlerOrgs(type, orgId, false);
+  }
+
+  async save() {
+    return this.collection.create(sanitizeIdAndAuditFields(this.constructor.name, this.toJSON()));
+  }
+}
+
+export default Configuration;

package/src/v2/models/configuration/configuration.schema.js

@@ -0,0 +1,103 @@
+/*
+ * 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.
+ */
+
+/* c8 ignore start */
+
+import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
+
+import Joi from 'joi';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import Configuration from './configuration.model.js';
+import ConfigurationCollection from './configuration.collection.js';
+
+const handlerSchema = Joi.object().pattern(Joi.string(), Joi.object(
+  {
+    enabled: Joi.object({
+      sites: Joi.array().items(Joi.string()),
+      orgs: Joi.array().items(Joi.string()),
+    }),
+    disabled: Joi.object({
+      sites: Joi.array().items(Joi.string()),
+      orgs: Joi.array().items(Joi.string()),
+    }),
+    enabledByDefault: Joi.boolean().required(),
+    dependencies: Joi.array().items(Joi.object(
+      {
+        handler: Joi.string(),
+        actions: Joi.array().items(Joi.string()),
+      },
+    )),
+  },
+)).unknown(true);
+
+const jobsSchema = Joi.array().required();
+
+const queueSchema = Joi.object().required();
+
+const configurationSchema = Joi.object({
+  version: Joi.number().required(),
+  queues: queueSchema,
+  handlers: handlerSchema,
+  jobs: jobsSchema,
+}).unknown(true);
+
+export const checkConfiguration = (data, schema = configurationSchema) => {
+  const { error, value } = schema.validate(data);
+
+  if (error) {
+    throw new Error(`Configuration validation error: ${error.message}`);
+  }
+
+  return value;
+};
+
+/*
+Schema Doc: https://electrodb.dev/en/modeling/schema/
+Attribute Doc: https://electrodb.dev/en/modeling/attributes/
+Indexes Doc: https://electrodb.dev/en/modeling/indexes/
+ */
+
+const schema = new SchemaBuilder(Configuration, ConfigurationCollection)
+  .addAttribute('handlers', {
+    type: 'any',
+    validate: (value) => !value || checkConfiguration(value, handlerSchema),
+  })
+  .addAttribute('jobs', {
+    type: 'list',
+    items: {
+      type: 'map',
+      properties: {
+        group: { type: ['audits', 'imports', 'reports'] },
+        type: { type: 'string', required: true },
+        interval: { type: ['daily', 'weekly'] },
+      },
+    },
+  })
+  .addAttribute('queues', {
+    type: 'any',
+    required: true,
+    validate: (value) => isNonEmptyObject(value),
+  })
+  .addAttribute('slackRoles', {
+    type: 'any',
+    validate: (value) => !value || isNonEmptyObject(value),
+  })
+  .addAttribute('version', {
+    type: 'number',
+    required: true,
+    readOnly: true,
+  })
+  // eslint-disable-next-line no-template-curly-in-string
+  .addAllIndexWithTemplateField('version', '${version}');
+
+export default schema.build();

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

@@ -0,0 +1,111 @@
+/*
+ * 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 type {
+  BaseCollection, BaseModel, Organization, Site,
+} from '../index';
+
+export interface Configuration extends BaseModel {
+  /**
+   * Retrieves the configuration version.
+   * @returns {number} The configuration version.
+   */
+  getVersion: () => number;
+
+  /**
+   * Retrieves the queues configuration.
+   * @returns {object} The queues configuration.
+   */
+  getQueues: () => object;
+
+  /**
+   * Retrieves the jobs configuration.
+   * @returns {Array} The jobs configurations.
+   */
+  getJobs: () => Array<object>;
+
+  /**
+   * Retrieves the handlers configuration.
+   * @returns {object} The handlers configuration.
+   */
+  getHandlers: () => object;
+
+  /**
+   * Retrieves the handler configuration for handler type.
+   * @param type The handler type.
+   * @returns {object} The handler type configuration.
+   */
+  getHandler: (type) => object;
+
+  /**
+   * Retrieves the slack roles configuration.
+   * @returns {object} The slack roles configuration.
+   */
+  getSlackRoles: () => object;
+
+  /**
+   * Return true if a handler type is enabled for an organization.
+   * @param type handler type
+   * @param org organization
+   */
+  isHandlerEnabledForOrg: (type: string, org: Organization) => boolean;
+
+  /**
+   * Return true if a handler type is enabled for a site.
+   * @param type handler type
+   * @param site site
+   */
+  isHandlerEnabledForSite: (type: string, site: Site) => boolean;
+
+  /**
+   * Enables a handler type for an site.
+   * @param type handler type
+   * @param site site
+   */
+  enableHandlerForSite: (type: string, site: Site) => void;
+
+  /**
+   * Enables a handler type for an organization.
+   * @param type handler type
+   * @param org organization
+   */
+  enableHandlerForOrg: (type: string, org: Organization) => void;
+
+  /**
+   * Disables a handler type for an site.
+   * @param type handler type
+   * @param site site
+   */
+  disableHandlerForSite: (type: string, site: Site) => void;
+
+  /**
+   * Disables a handler type for an organization.
+   * @param type handler type
+   * @param org organization
+   */
+  disableHandlerForOrg: (type:string, org: Organization) => void;
+}
+
+export interface ConfigurationCollection extends BaseCollection<Configuration> {
+  /**
+   * Retrieves the latest configuration by version.
+   * @returns {Configuration} The configuration.
+   */
+  findLatest: () => Configuration;
+
+  /**
+   * Retrieves the configuration by version.
+   * @param version The configuration version.
+   * @returns {Configuration} The configuration.
+   */
+  findByVersion: (version: number) => Configuration;
+}