feat: add configuration management APIs (#1063)

## Summary
This PR adds new configuration management methods to support API-driven
configuration updates

## Changes Made

### Configuration Model (`configuration.model.js`)
- Added `updateQueues(queues)` - Update queue configurations
- Added `updateJob(type, properties)` - Update job properties (interval,
group)
- Added `updateHandlerProperties(type, properties)` - Update handler
settings (enabledByDefault, productCodes, dependencies, thresholds)
- Added `updateConfiguration(data)` - Flexible method to update multiple
configuration sections at once
- Made `productCodes` a required and non-empty field for handlers
- Added `restore(version)` - restores the last good version
- Enhanced `register(audit)` and `unregister(audit)` - remove
AUDIT_TYPES static list validation.

### Configuration Schema (`configuration.schema.js`)
- Updated handler schema to require `productCodes` with minimum 1 item

### Configuration Index (`index.js`)
- Exported `checkConfiguration` function for response validation



## Testing
- All tests passing (1133 tests)

Please ensure your pull request adheres to the following guidelines:
- [X] make sure to link the related issues in this description
- [X] when merging / squashing, make sure the fixed issue references are
visible in the commits, for easy compilation of release notes

## Related Issues
https://jira.corp.adobe.com/browse/LLMO-908

Thanks for contributing!

---------

Co-authored-by: Tathagat Sharma <ftathagat+adobe@adobe.com>

Author: tathagat2241

packages/spacecat-shared-data-access/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,50 +257,209 @@ 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');
     }
     if (!productCodes.every((pc) => Object.values(Entitlement.PRODUCT_CODES).includes(pc))) {
       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) {

packages/spacecat-shared-data-access/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);
 

packages/spacecat-shared-data-access/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,
 };

packages/spacecat-shared-data-access/test/fixtures/configurations.fixture.js

@@ -53,18 +53,22 @@ const configurations = [
     handlers: {
       404: {
         enabledByDefault: true,
+        productCodes: ['ASO'],
       },
       'rum-ingest': {
         enabledByDefault: false,
+        productCodes: ['ASO'],
         enabled: {
           sites: ['c6f41da6-3a7e-4a59-8b8d-2da742ac2dbe'],
         },
       },
       'organic-keywords': {
         enabledByDefault: false,
+        productCodes: ['ASO'],
       },
       cwv: {
         enabledByDefault: true,
+        productCodes: ['ASO'],
         disabled: {
           sites: [
             '5d6d4439-6659-46c2-b646-92d110fa5a52',
@@ -83,6 +87,7 @@ const configurations = [
       },
       sitemap: {
         enabledByDefault: true,
+        productCodes: ['ASO'],
         enabled: {
           sites: [],
           orgs: [],
@@ -94,6 +99,7 @@ const configurations = [
       },
       'lhs-mobile': {
         enabledByDefault: false,
+        productCodes: ['ASO'],
         enabled: {
           sites: ['c6f41da6-3a7e-4a59-8b8d-2da742ac2dbe'],
           orgs: ['757ceb98-05c8-4e07-bb23-bc722115b2b0'],

packages/spacecat-shared-data-access/test/it/configuration/configuration.test.js

@@ -77,6 +77,7 @@ describe('Configuration IT', async () => {
 
     const data = {
       enabledByDefault: true,
+      productCodes: ['ASO'],
       enabled: {
         sites: ['site1'],
         orgs: ['org1'],