@adobe/spacecat-shared-data-access 2.85.1 → 2.87.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-data-access-v2.87.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.86.0...@adobe/spacecat-shared-data-access-v2.87.0) (2025-11-19)
+
+
+### Features
+
+* add page citability ([#1140](https://github.com/adobe/spacecat-shared/issues/1140)) ([e4dfcdc](https://github.com/adobe/spacecat-shared/commit/e4dfcdccf44ad4a303c3b68b0655e00b25f3da3c))
+
+# [@adobe/spacecat-shared-data-access-v2.86.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.85.1...@adobe/spacecat-shared-data-access-v2.86.0) (2025-11-19)
+
+
+### Features
+
+* add configuration management APIs ([#1063](https://github.com/adobe/spacecat-shared/issues/1063)) ([d6988a9](https://github.com/adobe/spacecat-shared/commit/d6988a94ad79016c238f3f4d9426c328b52c3131))
+
 # [@adobe/spacecat-shared-data-access-v2.85.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.85.0...@adobe/spacecat-shared-data-access-v2.85.1) (2025-11-18)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "2.85.1",
+  "version": "2.87.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/base/entity.registry.js

@@ -40,6 +40,7 @@ import PageIntentCollection from '../page-intent/page-intent.collection.js';
 import ReportCollection from '../report/report.collection.js';
 import TrialUserCollection from '../trial-user/trial-user.collection.js';
 import TrialUserActivityCollection from '../trial-user-activity/trial-user-activity.collection.js';
+import PageCitabilityCollection from '../page-citability/page-citability.collection.js';
 
 import ApiKeySchema from '../api-key/api-key.schema.js';
 import AsyncJobSchema from '../async-job/async-job.schema.js';
@@ -68,6 +69,7 @@ import PageIntentSchema from '../page-intent/page-intent.schema.js';
 import ReportSchema from '../report/report.schema.js';
 import TrialUserSchema from '../trial-user/trial-user.schema.js';
 import TrialUserActivitySchema from '../trial-user-activity/trial-user-activity.schema.js';
+import PageCitabilitySchema from '../page-citability/page-citability.schema.js';
 
 /**
  * EntityRegistry - A registry class responsible for managing entities, their schema and collection.
@@ -165,5 +167,6 @@ EntityRegistry.registerEntity(PageIntentSchema, PageIntentCollection);
 EntityRegistry.registerEntity(ReportSchema, ReportCollection);
 EntityRegistry.registerEntity(TrialUserSchema, TrialUserCollection);
 EntityRegistry.registerEntity(TrialUserActivitySchema, TrialUserActivityCollection);
+EntityRegistry.registerEntity(PageCitabilitySchema, PageCitabilityCollection);
 
 export default EntityRegistry;

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

@@ -14,7 +14,6 @@ import { isNonEmptyObject, isNonEmptyArray } from '@adobe/spacecat-shared-utils'
 
 import { sanitizeIdAndAuditFields } from '../../util/util.js';
 import BaseModel from '../base/base.model.js';
-import { Audit } from '../audit/index.js';
 import { Entitlement } from '../entitlement/index.js';
 
 /**
@@ -47,6 +46,11 @@ class Configuration extends BaseModel {
     FORTNIGHTLY_SUNDAY: 'fortnightly-sunday',
     MONTHLY: 'monthly',
   };
+
+  static AUDIT_NAME_REGEX = /^[a-z0-9-]+$/;
+
+  static AUDIT_NAME_MAX_LENGTH = 37;
+
   // add your custom methods or overrides here
 
   getHandler(type) {
@@ -253,23 +257,186 @@ class Configuration extends BaseModel {
     this.updateHandlerOrgs(type, orgId, false);
   }
 
+  /**
+   * Updates the queue URLs configuration by merging with existing queues.
+   * Only the specified queue URLs will be updated; others remain unchanged.
+   *
+   * @param {object} queues - Queue URLs to update (merged with existing)
+   * @throws {Error} If queues object is empty or invalid
+   */
+  updateQueues(queues) {
+    if (!isNonEmptyObject(queues)) {
+      throw new Error('Queues configuration cannot be empty');
+    }
+    const existingQueues = this.getQueues() || {};
+    const mergedQueues = { ...existingQueues, ...queues };
+    this.setQueues(mergedQueues);
+  }
+
+  /**
+   * Updates a job's properties (interval, group).
+   *
+   * @param {string} type - The job type to update
+   * @param {object} properties - Properties to update (interval, group)
+   * @throws {Error} If job not found or properties are invalid
+   */
+  updateJob(type, properties) {
+    const jobs = this.getJobs();
+    const jobIndex = jobs.findIndex((job) => job.type === type);
+
+    if (jobIndex === -1) {
+      throw new Error(`Job type "${type}" not found in configuration`);
+    }
+
+    if (properties.interval && !Object.values(Configuration.JOB_INTERVALS)
+      .includes(properties.interval)) {
+      throw new Error(`Invalid interval "${properties.interval}". Must be one of: ${Object.values(Configuration.JOB_INTERVALS).join(', ')}`);
+    }
+
+    if (properties.group && !Object.values(Configuration.JOB_GROUPS).includes(properties.group)) {
+      throw new Error(`Invalid group "${properties.group}". Must be one of: ${Object.values(Configuration.JOB_GROUPS).join(', ')}`);
+    }
+
+    jobs[jobIndex] = { ...jobs[jobIndex], ...properties };
+    this.setJobs(jobs);
+  }
+
+  /**
+   * Updates a handler's properties.
+   *
+   * @param {string} type - The handler type to update
+   * @param {object} properties - Properties to update
+   * @throws {Error} If handler not found or properties are invalid
+   */
+  updateHandlerProperties(type, properties) {
+    const handlers = this.getHandlers();
+    if (!handlers[type]) {
+      throw new Error(`Handler "${type}" not found in configuration`);
+    }
+
+    if (properties.productCodes !== undefined) {
+      if (!isNonEmptyArray(properties.productCodes)) {
+        throw new Error('productCodes must be a non-empty array');
+      }
+      const validProductCodes = Object.values(Entitlement.PRODUCT_CODES);
+      if (!properties.productCodes.every((pc) => validProductCodes.includes(pc))) {
+        throw new Error('Invalid product codes provided');
+      }
+    }
+
+    if (isNonEmptyArray(properties.dependencies)) {
+      for (const dep of properties.dependencies) {
+        if (!handlers[dep.handler]) {
+          throw new Error(`Dependency handler "${dep.handler}" does not exist in configuration`);
+        }
+      }
+    }
+
+    if (properties.movingAvgThreshold !== undefined && properties.movingAvgThreshold < 1) {
+      throw new Error('movingAvgThreshold must be greater than or equal to 1');
+    }
+
+    if (properties.percentageChangeThreshold !== undefined && properties
+      .percentageChangeThreshold < 1) {
+      throw new Error('percentageChangeThreshold must be greater than or equal to 1');
+    }
+
+    handlers[type] = { ...handlers[type], ...properties };
+    this.setHandlers(handlers);
+  }
+
+  /**
+   * Updates the configuration by merging changes into existing sections.
+   * This is a flexible update method that allows updating one or more sections at once.
+   * Changes are merged, not replaced - existing data is preserved.
+   *
+   * @param {object} data - Configuration data to update
+   * @param {object} [data.handlers] - Handlers to merge (adds new, updates existing)
+   * @param {Array} [data.jobs] - Jobs to merge (updates matching jobs by type)
+   * @param {object} [data.queues] - Queues to merge (updates specific queue URLs)
+   * @throws {Error} If validation fails
+   */
+  updateConfiguration(data) {
+    if (!isNonEmptyObject(data)) {
+      throw new Error('Configuration data cannot be empty');
+    }
+
+    if (data.handlers !== undefined) {
+      if (!isNonEmptyObject(data.handlers)) {
+        throw new Error('Handlers must be a non-empty object if provided');
+      }
+      const existingHandlers = this.getHandlers() || {};
+      const mergedHandlers = { ...existingHandlers };
+
+      Object.keys(data.handlers).forEach((handlerType) => {
+        mergedHandlers[handlerType] = {
+          ...existingHandlers[handlerType],
+          ...data.handlers[handlerType],
+        };
+      });
+
+      this.setHandlers(mergedHandlers);
+    }
+
+    if (data.jobs !== undefined) {
+      if (!isNonEmptyArray(data.jobs)) {
+        throw new Error('Jobs must be a non-empty array if provided');
+      }
+      const existingJobs = this.getJobs() || [];
+      const mergedJobs = [...existingJobs];
+
+      data.jobs.forEach((newJob) => {
+        const existingIndex = mergedJobs.findIndex(
+          (job) => job.type === newJob.type && job.group === newJob.group,
+        );
+
+        if (existingIndex !== -1) {
+          mergedJobs[existingIndex] = { ...mergedJobs[existingIndex], ...newJob };
+        } else {
+          mergedJobs.push(newJob);
+        }
+      });
+
+      this.setJobs(mergedJobs);
+    }
+
+    if (data.queues !== undefined) {
+      if (!isNonEmptyObject(data.queues)) {
+        throw new Error('Queues must be a non-empty object if provided');
+      }
+      const existingQueues = this.getQueues() || {};
+      const mergedQueues = { ...existingQueues, ...data.queues };
+
+      this.setQueues(mergedQueues);
+    }
+  }
+
   registerAudit(
     type,
     enabledByDefault = false,
     interval = Configuration.JOB_INTERVALS.NEVER,
     productCodes = [],
   ) {
-    // Validate audit type
-    if (!Object.values(Audit.AUDIT_TYPES).includes(type)) {
-      throw new Error(`Audit type ${type} is not a valid audit type in the data model`);
+    if (!type || typeof type !== 'string' || type.trim() === '') {
+      throw new Error('Audit type must be a non-empty string');
+    }
+
+    if (type.length > Configuration.AUDIT_NAME_MAX_LENGTH) {
+      throw new Error(`Audit type must not exceed ${Configuration.AUDIT_NAME_MAX_LENGTH} characters`);
+    }
+    if (!Configuration.AUDIT_NAME_REGEX.test(type)) {
+      throw new Error('Audit type can only contain lowercase letters, numbers, and hyphens');
+    }
+
+    const handlers = this.getHandlers();
+    if (handlers && handlers[type]) {
+      throw new Error(`Audit type "${type}" is already registered`);
     }
 
-    // Validate job interval
     if (!Object.values(Configuration.JOB_INTERVALS).includes(interval)) {
       throw new Error(`Invalid interval ${interval}`);
     }
 
-    // Validate product codes
     if (!isNonEmptyArray(productCodes)) {
       throw new Error('No product codes provided');
     }
@@ -277,26 +444,22 @@ class Configuration extends BaseModel {
       throw new Error('Invalid product codes provided');
     }
 
-    // Add to handlers if not already registered
-    const handlers = this.getHandlers();
-    if (!handlers[type]) {
-      handlers[type] = {
-        enabledByDefault,
-        enabled: {
-          sites: [],
-          orgs: [],
-        },
-        disabled: {
-          sites: [],
-          orgs: [],
-        },
-        dependencies: [],
-        productCodes,
-      };
-      this.setHandlers(handlers);
-    }
-
-    // Add to jobs if not already registered
+    const updatedHandlers = handlers || {};
+    updatedHandlers[type] = {
+      enabledByDefault,
+      enabled: {
+        sites: [],
+        orgs: [],
+      },
+      disabled: {
+        sites: [],
+        orgs: [],
+      },
+      dependencies: [],
+      productCodes,
+    };
+    this.setHandlers(updatedHandlers);
+
     const jobs = this.getJobs();
     const exists = jobs.find((job) => job.group === 'audits' && job.type === type);
     if (!exists) {
@@ -310,19 +473,18 @@ class Configuration extends BaseModel {
   }
 
   unregisterAudit(type) {
-    // Validate audit type
-    if (!Object.values(Audit.AUDIT_TYPES).includes(type)) {
-      throw new Error(`Audit type ${type} is not a valid audit type in the data model`);
+    if (!type || typeof type !== 'string' || type.trim() === '') {
+      throw new Error('Audit type must be a non-empty string');
     }
 
-    // Remove from handlers
     const handlers = this.getHandlers();
-    if (handlers[type]) {
-      delete handlers[type];
-      this.setHandlers(handlers);
+    if (!handlers || !handlers[type]) {
+      throw new Error(`Audit type "${type}" is not registered`);
     }
 
-    // Remove from jobs
+    delete handlers[type];
+    this.setHandlers(handlers);
+
     const jobs = this.getJobs();
     const jobIndex = jobs.findIndex((job) => job.group === 'audits' && job.type === type);
     if (jobIndex !== -1) {

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

@@ -40,7 +40,7 @@ const handlerSchema = Joi.object().pattern(Joi.string(), Joi.object(
         actions: Joi.array().items(Joi.string()),
       },
     )),
-    productCodes: Joi.array().items(Joi.string()),
+    productCodes: Joi.array().items(Joi.string()).min(1).required(),
   },
 )).unknown(true);
 

package/src/models/configuration/index.js

@@ -12,8 +12,10 @@
 
 import Configuration from './configuration.model.js';
 import ConfigurationCollection from './configuration.collection.js';
+import { checkConfiguration } from './configuration.schema.js';
 
 export {
   Configuration,
   ConfigurationCollection,
+  checkConfiguration,
 };

package/src/models/index.js

@@ -38,3 +38,4 @@ export * from './page-intent/index.js';
 export * from './report/index.js';
 export * from './trial-user/index.js';
 export * from './trial-user-activity/index.js';
+export * from './page-citability/index.js';

package/src/models/page-citability/index.d.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2025 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, Site } from '../index.js';
+
+export interface PageCitability extends BaseModel {
+    getSiteId(): string;
+    getSite(): Promise<Site>;
+    getUrl(): string;
+    getCitabilityScore(): number | undefined;
+    getContentRatio(): number | undefined;
+    getWordDifference(): number | undefined;
+    getBotWords(): number | undefined;
+    getNormalWords(): number | undefined;
+
+    setSiteId(siteId: string): PageCitability;
+    setUrl(url: string): PageCitability;
+    setCitabilityScore(citabilityScore?: number): PageCitability;
+    setContentRatio(contentRatio?: number): PageCitability;
+    setWordDifference(wordDifference?: number): PageCitability;
+    setBotWords(botWords?: number): PageCitability;
+    setNormalWords(normalWords?: number): PageCitability;
+}
+
+export interface PageCitabilityCollection extends BaseCollection<PageCitability> {
+    allBySiteId(siteId: string): Promise<PageCitability[]>;
+    findBySiteId(siteId: string): Promise<PageCitability | null>;
+    allByUrl(url: string): Promise<PageCitability[]>;
+    findByUrl(url: string): Promise<PageCitability | null>;
+}

package/src/models/page-citability/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 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 PageCitability from './page-citability.model.js';
+import PageCitabilityCollection from './page-citability.collection.js';
+
+export {
+  PageCitability,
+  PageCitabilityCollection,
+};

package/src/models/page-citability/page-citability.collection.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 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 BaseCollection from '../base/base.collection.js';
+
+/**
+ * PageCitabilityCollection - Manages PageCitability entities.
+ *
+ * @class PageCitabilityCollection
+ * @extends BaseCollection
+ */
+class PageCitabilityCollection extends BaseCollection {
+  // add custom collection-level methods here, if needed
+}
+
+export default PageCitabilityCollection;

package/src/models/page-citability/page-citability.model.js

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2025 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 BaseModel from '../base/base.model.js';
+
+/**
+ * PageCitability - Represents a page's citability metrics within a site.
+ *
+ * @class PageCitability
+ * @extends BaseModel
+ */
+class PageCitability extends BaseModel {
+  static DEFAULT_UPDATED_BY = 'spacecat';
+
+  // add any custom methods or overrides here
+}
+
+export default PageCitability;

package/src/models/page-citability/page-citability.schema.js

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2025 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 { isValidUrl } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import PageCitability from './page-citability.model.js';
+import PageCitabilityCollection from './page-citability.collection.js';
+
+/*
+  Schema: https://electrodb.dev/en/modeling/schema/
+  Attributes: https://electrodb.dev/en/modeling/attributes/
+  Indexes: https://electrodb.dev/en/modeling/indexes/
+*/
+
+const schema = new SchemaBuilder(PageCitability, PageCitabilityCollection)
+  // link back to Site entity
+  .addReference('belongs_to', 'Site')
+
+  // page's full URL (must be unique)
+  .addAttribute('url', {
+    type: 'string',
+    required: true,
+    validate: (value) => isValidUrl(value),
+  })
+
+  // citation readability score
+  .addAttribute('citabilityScore', {
+    type: 'number',
+    required: false,
+    validate: (value) => !value || (typeof value === 'number' && !Number.isNaN(value)),
+  })
+
+  // content increase ratio
+  .addAttribute('contentRatio', {
+    type: 'number',
+    required: false,
+    validate: (value) => !value || (typeof value === 'number' && !Number.isNaN(value)),
+  })
+
+  // word difference between before and after
+  .addAttribute('wordDifference', {
+    type: 'number',
+    required: false,
+    validate: (value) => !value || (typeof value === 'number' && !Number.isNaN(value)),
+  })
+
+  // word count before processing (bot words)
+  .addAttribute('botWords', {
+    type: 'number',
+    required: false,
+    validate: (value) => !value || (typeof value === 'number' && !Number.isNaN(value)),
+  })
+
+  // word count after processing (normal words)
+  .addAttribute('normalWords', {
+    type: 'number',
+    required: false,
+    validate: (value) => !value || (typeof value === 'number' && !Number.isNaN(value)),
+  })
+
+  // optionally track who last updated
+  .addAttribute('updatedBy', {
+    type: 'string',
+    default: PageCitability.DEFAULT_UPDATED_BY,
+  })
+
+  // allow fetching the single record by its URL
+  .addIndex(
+    { composite: ['url'] },
+    { composite: ['updatedAt'] },
+  );
+
+export default schema.build();

package/src/models/site/site.schema.js

@@ -47,6 +47,7 @@ const schema = new SchemaBuilder(Site, SiteCollection)
   .addReference('has_many', 'SiteTopPages')
   .addReference('has_many', 'TrialUserActivities')
   .addReference('has_many', 'PageIntents')
+  .addReference('has_many', 'PageCitabilities')
   .addAttribute('baseURL', {
     type: 'string',
     required: true,