@adobe/spacecat-shared-tokowaka-client 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.2.3](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.2.2...@adobe/spacecat-shared-tokowaka-client-v1.2.3) (2025-11-28)
+
+
+### Bug Fixes
+
+* readability opportunity handling in edge APIs ([#1188](https://github.com/adobe/spacecat-shared/issues/1188)) ([fdf1bd9](https://github.com/adobe/spacecat-shared/commit/fdf1bd9678e5284200e3fd4378391e515ee8baba))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.2.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.2.1...@adobe/spacecat-shared-tokowaka-client-v1.2.2) (2025-11-28)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Tokowaka Client for SpaceCat - Edge optimization config management",
   "type": "module",
   "engines": {

package/src/index.d.ts

@@ -173,6 +173,23 @@ export class HeadingsMapper extends BaseOpportunityMapper {
   canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
 }
 
+/**
+ * Readability opportunity mapper
+ * Handles conversion of readability suggestions to Tokowaka patches
+ */
+export class ReadabilityMapper extends BaseOpportunityMapper {
+  constructor(log: any);
+  
+  getOpportunityType(): string;
+  requiresPrerender(): boolean;
+  suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string
+  ): TokawakaPatch[];
+  canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
+}
+
 /**
  * Content summarization opportunity mapper
  * Handles conversion of content summarization suggestions to Tokowaka patches with HAST format

package/src/mappers/mapper-registry.js

@@ -13,6 +13,7 @@
 import HeadingsMapper from './headings-mapper.js';
 import ContentSummarizationMapper from './content-summarization-mapper.js';
 import FaqMapper from './faq-mapper.js';
+import ReadabilityMapper from './readability-mapper.js';
 
 /**
  * Registry for opportunity mappers
@@ -34,6 +35,7 @@ export default class MapperRegistry {
       HeadingsMapper,
       ContentSummarizationMapper,
       FaqMapper,
+      ReadabilityMapper,
       // more mappers here
     ];
 

package/src/mappers/readability-mapper.js

@@ -0,0 +1,113 @@
+/*
+ * 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, isValidUrl, isBoolean } from '@adobe/spacecat-shared-utils';
+import { TARGET_USER_AGENTS_CATEGORIES } from '../constants.js';
+import BaseOpportunityMapper from './base-mapper.js';
+
+/**
+ * Mapper for readability opportunity
+ * Handles conversion of readability suggestions to Tokowaka patches
+ */
+export default class ReadabilityMapper extends BaseOpportunityMapper {
+  constructor(log) {
+    super(log);
+    this.opportunityType = 'readability';
+    this.prerenderRequired = true;
+  }
+
+  getOpportunityType() {
+    return this.opportunityType;
+  }
+
+  requiresPrerender() {
+    return this.prerenderRequired;
+  }
+
+  /**
+   * Converts suggestions to Tokowaka patches
+   * @param {string} urlPath - URL path for the suggestions
+   * @param {Array} suggestions - Array of suggestion entities for the same URL
+   * @param {string} opportunityId - Opportunity ID
+   * @returns {Array} - Array of Tokowaka patch objects
+   */
+  suggestionsToPatches(urlPath, suggestions, opportunityId) {
+    const patches = [];
+
+    suggestions.forEach((suggestion) => {
+      const eligibility = this.canDeploy(suggestion);
+      if (!eligibility.eligible) {
+        this.log.warn(`Readability suggestion ${suggestion.getId()} cannot be deployed: ${eligibility.reason}`);
+        return;
+      }
+
+      const data = suggestion.getData();
+      const { transformRules } = data;
+
+      const patch = {
+        ...this.createBasePatch(suggestion, opportunityId),
+        op: transformRules.op,
+        selector: transformRules.selector,
+        value: transformRules.value,
+        valueFormat: 'text',
+        ...(
+          isBoolean(transformRules.prerenderRequired)
+           && { prerenderRequired: transformRules.prerenderRequired }
+        ),
+        ...(hasText(data.textPreview) && { currValue: data.textPreview }),
+        target: transformRules.target || TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
+      };
+
+      patches.push(patch);
+    });
+
+    return patches;
+  }
+
+  /**
+   * Checks if a readability suggestion can be deployed
+   * @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();
+
+    // Validate required fields
+    if (!data?.transformRules) {
+      return { eligible: false, reason: 'transformRules is required' };
+    }
+
+    const { transformRules } = data;
+
+    if (!isValidUrl(data.pageUrl)) {
+      return { eligible: false, reason: `pageUrl ${data.pageUrl} is not a valid URL` };
+    }
+
+    if (!hasText(transformRules.selector)) {
+      return { eligible: false, reason: 'transformRules.selector is required' };
+    }
+
+    if (transformRules.op !== 'replace') {
+      return {
+        eligible: false,
+        reason: 'transformRules.op must be "replace" for readability suggestions',
+      };
+    }
+
+    if (!hasText(transformRules.value)) {
+      return { eligible: false, reason: 'transformRules.value is required' };
+    }
+
+    return { eligible: true };
+  }
+}

package/test/mappers/readability-mapper.test.js

@@ -0,0 +1,422 @@
+/*
+ * 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 ReadabilityMapper from '../../src/mappers/readability-mapper.js';
+
+describe('ReadabilityMapper', () => {
+  let mapper;
+  let log;
+
+  beforeEach(() => {
+    log = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    };
+    mapper = new ReadabilityMapper(log);
+  });
+
+  describe('getOpportunityType', () => {
+    it('should return readability', () => {
+      expect(mapper.getOpportunityType()).to.equal('readability');
+    });
+  });
+
+  describe('requiresPrerender', () => {
+    it('should return true', () => {
+      expect(mapper.requiresPrerender()).to.be.true;
+    });
+  });
+
+  describe('canDeploy', () => {
+    it('should return eligible for valid readability suggestion', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Lorem ipsum...',
+          pageUrl: 'https://www.website.com',
+          transformRules: {
+            value: 'Tech enthusiasts keep up with the latest tech news...',
+            op: 'replace',
+            selector: '#main-238828 > div:nth-child(1) > span',
+            target: 'ai-bots',
+            prerenderRequired: true,
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({ eligible: true });
+    });
+
+    it('should return eligible for readability suggestion without target (uses default)', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Lorem ipsum...',
+          pageUrl: 'https://www.website.com',
+          transformRules: {
+            value: 'Improved readability text...',
+            op: 'replace',
+            selector: '#content > p',
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({ eligible: true });
+    });
+
+    it('should return ineligible when transformRules is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Lorem ipsum...',
+          pageUrl: 'https://www.website.com',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules is required',
+      });
+    });
+
+    it('should return ineligible when data is null', () => {
+      const suggestion = {
+        getData: () => null,
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules is required',
+      });
+    });
+
+    it('should return ineligible when transformRules.selector is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'https://www.example.com',
+          transformRules: {
+            value: 'New text',
+            op: 'replace',
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.selector is required',
+      });
+    });
+
+    it('should return ineligible when transformRules.op is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'https://www.example.com',
+          transformRules: {
+            value: 'New text',
+            selector: '#content',
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.op must be "replace" for readability suggestions',
+      });
+    });
+
+    it('should return ineligible when transformRules.op is not "replace"', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'https://www.example.com',
+          transformRules: {
+            value: 'New text',
+            op: 'insertAfter',
+            selector: '#content',
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.op must be "replace" for readability suggestions',
+      });
+    });
+
+    it('should return ineligible when transformRules.value is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'https://www.example.com',
+          transformRules: {
+            op: 'replace',
+            selector: '#content',
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.value is required',
+      });
+    });
+
+    it('should return ineligible when transformRules.selector is empty string', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'https://www.example.com',
+          transformRules: {
+            value: 'New text',
+            op: 'replace',
+            selector: '',
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.selector is required',
+      });
+    });
+
+    it('should return ineligible when pageUrl is invalid', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'not-a-valid-url',
+          transformRules: {
+            value: 'New text',
+            op: 'replace',
+            selector: '#content',
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'pageUrl not-a-valid-url is not a valid URL',
+      });
+    });
+
+    it('should return ineligible when pageUrl is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          textPreview: 'Text...',
+          transformRules: {
+            value: 'New text',
+            op: 'replace',
+            selector: '#content',
+          },
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'pageUrl undefined is not a valid URL',
+      });
+    });
+  });
+
+  describe('suggestionsToPatches', () => {
+    it('should create patch for readability suggestion', () => {
+      const suggestion = {
+        getId: () => 'sugg-123',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          textPreview: 'Lorem ipsum...',
+          pageUrl: 'https://www.website.com',
+          scrapedAt: '2025-09-20T06:21:12.584Z',
+          transformRules: {
+            value: 'Tech enthusiasts keep up with the latest tech news...',
+            op: 'replace',
+            selector: '#main-238828 > div:nth-child(1) > span',
+            target: 'ai-bots',
+            prerenderRequired: true,
+          },
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/path', [suggestion], 'opp-123');
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      expect(patch).to.deep.include({
+        op: 'replace',
+        selector: '#main-238828 > div:nth-child(1) > span',
+        value: 'Tech enthusiasts keep up with the latest tech news...',
+        valueFormat: 'text',
+        currValue: 'Lorem ipsum...',
+        target: 'ai-bots',
+        opportunityId: 'opp-123',
+        suggestionId: 'sugg-123',
+        prerenderRequired: true,
+      });
+      expect(patch.lastUpdated).to.be.a('number');
+    });
+
+    it('should create patch with scrapedAt timestamp', () => {
+      const suggestion = {
+        getId: () => 'sugg-456',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          textPreview: 'Original text...',
+          pageUrl: 'https://www.example.com',
+          scrapedAt: '2025-09-20T06:21:12.584Z',
+          transformRules: {
+            value: 'Improved readability text',
+            op: 'replace',
+            selector: '.content > p',
+          },
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/path', [suggestion], 'opp-456');
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      expect(patch.lastUpdated).to.equal(new Date('2025-09-20T06:21:12.584Z').getTime());
+    });
+
+    it('should use default target when not specified', () => {
+      const suggestion = {
+        getId: () => 'sugg-789',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'https://www.example.com',
+          transformRules: {
+            value: 'Better text',
+            op: 'replace',
+            selector: '#content',
+          },
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/path', [suggestion], 'opp-789');
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      expect(patch.target).to.equal('ai-bots');
+      expect(patch.currValue).to.equal('Text...');
+    });
+
+    it('should return empty array for invalid suggestion', () => {
+      const suggestion = {
+        getId: () => 'sugg-999',
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'https://www.example.com',
+          // Missing transformRules
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/path', [suggestion], 'opp-999');
+      expect(patches.length).to.equal(0);
+    });
+
+    it('should log warning for invalid suggestion', () => {
+      let warnMessage = '';
+      const warnLog = {
+        debug: () => {},
+        info: () => {},
+        warn: (msg) => { warnMessage = msg; },
+        error: () => {},
+      };
+      const warnMapper = new ReadabilityMapper(warnLog);
+
+      const suggestion = {
+        getId: () => 'sugg-warn',
+        getData: () => ({
+          textPreview: 'Text...',
+          pageUrl: 'https://www.example.com',
+          transformRules: {
+            op: 'replace',
+            // Missing selector and value
+          },
+        }),
+      };
+
+      const patches = warnMapper.suggestionsToPatches('/path', [suggestion], 'opp-warn');
+
+      expect(patches.length).to.equal(0);
+      expect(warnMessage).to.include('cannot be deployed');
+      expect(warnMessage).to.include('sugg-warn');
+    });
+
+    it('should handle multiple suggestions', () => {
+      const suggestions = [
+        {
+          getId: () => 'sugg-1',
+          getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+          getData: () => ({
+            textPreview: 'Original text 1',
+            pageUrl: 'https://www.example.com/page1',
+            transformRules: {
+              value: 'First improved text',
+              op: 'replace',
+              selector: '#p1',
+            },
+          }),
+        },
+        {
+          getId: () => 'sugg-2',
+          getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+          getData: () => ({
+            textPreview: 'Original text 2',
+            pageUrl: 'https://www.example.com/page2',
+            transformRules: {
+              value: 'Second improved text',
+              op: 'replace',
+              selector: '#p2',
+            },
+          }),
+        },
+      ];
+
+      const patches = mapper.suggestionsToPatches('/path', suggestions, 'opp-multi');
+      expect(patches.length).to.equal(2);
+      expect(patches[0].suggestionId).to.equal('sugg-1');
+      expect(patches[0].selector).to.equal('#p1');
+      expect(patches[0].currValue).to.equal('Original text 1');
+      expect(patches[1].suggestionId).to.equal('sugg-2');
+      expect(patches[1].selector).to.equal('#p2');
+      expect(patches[1].currValue).to.equal('Original text 2');
+    });
+  });
+});