@adobe/spacecat-shared-tokowaka-client 1.0.0

package/src/mappers/headings-mapper.js

@@ -0,0 +1,118 @@
+/*
+ * 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 { hasText } from '@adobe/spacecat-shared-utils';
+import { TARGET_USER_AGENTS_CATEGORIES } from '../constants.js';
+import BaseOpportunityMapper from './base-mapper.js';
+
+/**
+ * Mapper for headings opportunity
+ * Handles conversion of heading suggestions to Tokowaka patches
+ */
+export default class HeadingsMapper extends BaseOpportunityMapper {
+  constructor(log) {
+    super(log);
+    this.opportunityType = 'headings';
+    this.prerenderRequired = true;
+  }
+
+  getOpportunityType() {
+    return this.opportunityType;
+  }
+
+  requiresPrerender() {
+    return this.prerenderRequired;
+  }
+
+  suggestionToPatch(suggestion, opportunityId) {
+    const eligibility = this.canDeploy(suggestion);
+    if (!eligibility.eligible) {
+      this.log.warn(`Headings suggestion ${suggestion.getId()} cannot be deployed: ${eligibility.reason}`);
+      return null;
+    }
+
+    const data = suggestion.getData();
+    const { checkType, transformRules } = data;
+
+    const patch = {
+      ...this.createBasePatch(suggestion, opportunityId),
+      op: transformRules.action,
+      selector: transformRules.selector,
+      value: data.recommendedAction,
+      valueFormat: 'text',
+      ...(data.currentValue !== null && { currValue: data.currentValue }),
+      target: TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
+    };
+
+    if (checkType === 'heading-missing-h1' && transformRules.tag) {
+      patch.tag = transformRules.tag;
+    }
+    return patch;
+  }
+
+  /**
+   * Checks if a heading suggestion can be deployed
+   * Supports: heading-empty, heading-missing-h1, heading-h1-length
+   * @param {Object} suggestion - Suggestion object
+   * @returns {Object} { eligible: boolean, reason?: string }
+   */
+  // eslint-disable-next-line class-methods-use-this
+  canDeploy(suggestion) {
+    const data = suggestion.getData();
+    const checkType = data?.checkType;
+
+    // Check if checkType is eligible
+    const eligibleCheckTypes = ['heading-empty', 'heading-missing-h1', 'heading-h1-length'];
+    if (!eligibleCheckTypes.includes(checkType)) {
+      return {
+        eligible: false,
+        reason: `Only ${eligibleCheckTypes.join(', ')} can be deployed. This suggestion has checkType: ${checkType}`,
+      };
+    }
+
+    // Validate required fields
+    if (!data?.recommendedAction) {
+      return { eligible: false, reason: 'recommendedAction is required' };
+    }
+
+    if (!hasText(data.transformRules?.selector)) {
+      return { eligible: false, reason: 'transformRules.selector is required' };
+    }
+
+    // Validate based on checkType
+    if (checkType === 'heading-missing-h1') {
+      if (!['insertBefore', 'insertAfter'].includes(data.transformRules?.action)) {
+        return {
+          eligible: false,
+          reason: 'transformRules.action must be insertBefore or insertAfter for heading-missing-h1',
+        };
+      }
+      if (!hasText(data.transformRules?.tag)) {
+        return {
+          eligible: false,
+          reason: 'transformRules.tag is required for heading-missing-h1',
+        };
+      }
+    }
+
+    if (checkType === 'heading-h1-length' || checkType === 'heading-empty') {
+      if (data.transformRules?.action !== 'replace') {
+        return {
+          eligible: false,
+          reason: `transformRules.action must be replace for ${checkType}`,
+        };
+      }
+    }
+
+    return { eligible: true };
+  }
+}

package/src/mappers/mapper-registry.js

@@ -0,0 +1,87 @@
+/*
+ * 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 HeadingsMapper from './headings-mapper.js';
+import ContentSummarizationMapper from './content-summarization-mapper.js';
+
+/**
+ * Registry for opportunity mappers
+ * Implements Factory Pattern to get the appropriate mapper for an opportunity type
+ */
+export default class MapperRegistry {
+  constructor(log) {
+    this.log = log;
+    this.mappers = new Map();
+    this.#registerDefaultMappers();
+  }
+
+  /**
+   * Registers default mappers for built-in opportunity types
+   * @private
+   */
+  #registerDefaultMappers() {
+    const defaultMappers = [
+      HeadingsMapper,
+      ContentSummarizationMapper,
+      // more mappers here
+    ];
+
+    defaultMappers.forEach((MapperClass) => {
+      const mapper = new MapperClass(this.log);
+      this.registerMapper(mapper);
+    });
+  }
+
+  /**
+   * Registers a mapper for an opportunity type
+   * @param {BaseOpportunityMapper} mapper - Mapper instance
+   */
+  registerMapper(mapper) {
+    const opportunityType = mapper.getOpportunityType();
+    if (this.mappers.has(opportunityType)) {
+      this.log.debug(`Mapper for opportunity type "${opportunityType}" is being overridden`);
+    }
+    this.mappers.set(opportunityType, mapper);
+    this.log.info(`Registered mapper for opportunity type: ${opportunityType}`);
+  }
+
+  /**
+   * Gets mapper for an opportunity type
+   * @param {string} opportunityType - Type of opportunity
+   * @returns {BaseOpportunityMapper|null} - Mapper instance or null if not found
+   */
+  getMapper(opportunityType) {
+    const mapper = this.mappers.get(opportunityType);
+    if (!mapper) {
+      this.log.warn(`No mapper found for opportunity type: ${opportunityType}`);
+      return null;
+    }
+    return mapper;
+  }
+
+  /**
+   * Checks if a mapper exists for an opportunity type
+   * @param {string} opportunityType - Type of opportunity
+   * @returns {boolean} - True if mapper exists
+   */
+  hasMapper(opportunityType) {
+    return this.mappers.has(opportunityType);
+  }
+
+  /**
+   * Gets all registered opportunity types
+   * @returns {string[]} - Array of opportunity types
+   */
+  getSupportedOpportunityTypes() {
+    return Array.from(this.mappers.keys());
+  }
+}

package/test/cdn/base-cdn-client.test.js

@@ -0,0 +1,52 @@
+/*
+ * 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.
+ */
+
+/* eslint-env mocha */
+
+import { expect } from 'chai';
+import BaseCdnClient from '../../src/cdn/base-cdn-client.js';
+
+describe('BaseCdnClient', () => {
+  let client;
+
+  beforeEach(() => {
+    client = new BaseCdnClient({}, console);
+  });
+
+  describe('constructor', () => {
+    it('should use console as default logger if log is not provided', () => {
+      const clientWithoutLog = new BaseCdnClient({});
+      expect(clientWithoutLog.log).to.equal(console);
+    });
+  });
+
+  describe('abstract methods', () => {
+    it('getProviderName should throw error', () => {
+      expect(() => client.getProviderName())
+        .to.throw('getProviderName() must be implemented by subclass');
+    });
+
+    it('validateConfig should throw error', () => {
+      expect(() => client.validateConfig())
+        .to.throw('validateConfig() must be implemented by subclass');
+    });
+
+    it('invalidateCache should throw error', async () => {
+      try {
+        await client.invalidateCache(['/test']);
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.equal('invalidateCache() must be implemented by subclass');
+      }
+    });
+  });
+});

package/test/cdn/cdn-client-registry.test.js

@@ -0,0 +1,179 @@
+/*
+ * 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.
+ */
+
+/* eslint-env mocha */
+/* eslint-disable max-classes-per-file */
+
+import { expect, use } from 'chai';
+import sinon from 'sinon';
+import sinonChai from 'sinon-chai';
+import CdnClientRegistry from '../../src/cdn/cdn-client-registry.js';
+import CloudFrontCdnClient from '../../src/cdn/cloudfront-cdn-client.js';
+import BaseCdnClient from '../../src/cdn/base-cdn-client.js';
+
+use(sinonChai);
+
+describe('CdnClientRegistry', () => {
+  let registry;
+  let log;
+  let env;
+
+  beforeEach(() => {
+    log = {
+      info: sinon.stub(),
+      warn: sinon.stub(),
+      error: sinon.stub(),
+    };
+
+    env = {
+      TOKOWAKA_CDN_CONFIG: JSON.stringify({
+        cloudfront: {
+          distributionId: 'E123456',
+          region: 'us-east-1',
+        },
+      }),
+    };
+
+    registry = new CdnClientRegistry(env, log);
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  describe('constructor', () => {
+    it('should create an instance and register default clients', () => {
+      expect(registry).to.be.instanceOf(CdnClientRegistry);
+      expect(registry.clients).to.be.instanceOf(Map);
+      expect(registry.clients.size).to.be.greaterThan(0);
+    });
+  });
+
+  describe('registerClient', () => {
+    it('should register a custom CDN client', () => {
+      class CustomCdnClient extends BaseCdnClient {}
+
+      registry.registerClient('custom', CustomCdnClient);
+
+      expect(registry.clients.has('custom')).to.be.true;
+      expect(registry.getSupportedProviders()).to.include('custom');
+    });
+
+    it('should register client with case-insensitive provider name', () => {
+      class CustomCdnClient extends BaseCdnClient {}
+
+      registry.registerClient('CUSTOM', CustomCdnClient);
+
+      expect(registry.clients.has('custom')).to.be.true;
+    });
+  });
+
+  describe('getClient', () => {
+    it('should return CloudFront client for cloudfront provider', () => {
+      const client = registry.getClient('cloudfront');
+
+      expect(client).to.be.instanceOf(CloudFrontCdnClient);
+      expect(client.cdnConfig).to.deep.equal({
+        distributionId: 'E123456',
+        region: 'us-east-1',
+      });
+    });
+
+    it('should be case-insensitive for provider names', () => {
+      const client = registry.getClient('CloudFront');
+
+      expect(client).to.be.instanceOf(CloudFrontCdnClient);
+    });
+
+    it('should return null if provider is not specified', () => {
+      const client = registry.getClient('');
+
+      expect(client).to.be.null;
+      expect(log.warn).to.have.been.calledWith('No CDN provider specified');
+    });
+
+    it('should return null if provider is null', () => {
+      const client = registry.getClient(null);
+
+      expect(client).to.be.null;
+      expect(log.warn).to.have.been.calledWith('No CDN provider specified');
+    });
+
+    it('should return null for unsupported provider', () => {
+      const client = registry.getClient('unsupported-provider');
+
+      expect(client).to.be.null;
+      expect(log.warn).to.have.been.calledWith(
+        'No CDN client found for provider: unsupported-provider',
+      );
+    });
+
+    it('should handle client creation errors gracefully', () => {
+      class FailingCdnClient extends BaseCdnClient {
+        constructor() {
+          throw new Error('Construction failed');
+        }
+      }
+
+      registry.registerClient('failing', FailingCdnClient);
+
+      const client = registry.getClient('failing');
+
+      expect(client).to.be.null;
+      expect(log.error).to.have.been.calledWith(
+        sinon.match(/Failed to create CDN client for failing/),
+      );
+    });
+  });
+
+  describe('getSupportedProviders', () => {
+    it('should return list of supported providers', () => {
+      const providers = registry.getSupportedProviders();
+
+      expect(providers).to.be.an('array');
+      expect(providers).to.include('cloudfront');
+    });
+
+    it('should include custom registered providers', () => {
+      class CustomCdnClient extends BaseCdnClient {}
+
+      registry.registerClient('custom', CustomCdnClient);
+
+      const providers = registry.getSupportedProviders();
+
+      expect(providers).to.include('custom');
+      expect(providers).to.include('cloudfront');
+    });
+  });
+
+  describe('isProviderSupported', () => {
+    it('should return true for supported provider', () => {
+      expect(registry.isProviderSupported('cloudfront')).to.be.true;
+    });
+
+    it('should return true for supported provider (case-insensitive)', () => {
+      expect(registry.isProviderSupported('CloudFront')).to.be.true;
+    });
+
+    it('should return false for unsupported provider', () => {
+      expect(registry.isProviderSupported('unsupported')).to.be.false;
+    });
+
+    it('should return false for null provider', () => {
+      expect(registry.isProviderSupported(null)).to.be.false;
+    });
+
+    it('should return false for undefined provider', () => {
+      expect(registry.isProviderSupported(undefined)).to.be.false;
+    });
+  });
+});