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

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.3.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.2.4...@adobe/spacecat-shared-tokowaka-client-v1.3.0) (2025-12-04)
+
+
+### Features
+
+* Tokowaka generic oppty mapper ([#1204](https://github.com/adobe/spacecat-shared/issues/1204)) ([710a36c](https://github.com/adobe/spacecat-shared/commit/710a36cd8b4e6f91a702da252c5a8739444a4e46))
+
+# [@adobe/spacecat-shared-tokowaka-client-v1.2.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.2.3...@adobe/spacecat-shared-tokowaka-client-v1.2.4) (2025-11-29)
+
+
+### Bug Fixes
+
+* url param in tokowaka readability mapper ([#1192](https://github.com/adobe/spacecat-shared/issues/1192)) ([566b9f1](https://github.com/adobe/spacecat-shared/commit/566b9f1d9ca03a9ffe6bbf59a89d6ccba8b278c0))
+
 # [@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)
 
 

package/package.json

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

package/src/mappers/generic-mapper.js

@@ -0,0 +1,117 @@
+/*
+ * 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';
+
+/**
+ * Generic mapper for code change opportunities
+ * Handles conversion of generic code change suggestions to Tokowaka patches
+ */
+export default class GenericMapper extends BaseOpportunityMapper {
+  constructor(log) {
+    super(log);
+    this.opportunityType = 'generic-autofix-edge';
+    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(`Generic suggestion ${suggestion.getId()} cannot be deployed: ${eligibility.reason}`);
+        return;
+      }
+
+      const data = suggestion.getData();
+      const { transformRules } = data;
+
+      const patch = {
+        ...this.createBasePatch(suggestion, opportunityId),
+        op: transformRules.action,
+        selector: transformRules.selector,
+        value: data.patchValue,
+        valueFormat: data.format || 'text',
+        target: TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
+      };
+
+      if (data.tag) {
+        patch.tag = data.tag;
+      }
+
+      patches.push(patch);
+    });
+
+    return patches;
+  }
+
+  /**
+   * Checks if a generic 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 transformRules exists
+    if (!data?.transformRules) {
+      return { eligible: false, reason: 'transformRules is required' };
+    }
+
+    // Validate required fields
+    if (!hasText(data.transformRules.selector)) {
+      return { eligible: false, reason: 'transformRules.selector is required' };
+    }
+
+    if (!hasText(data?.patchValue)) {
+      return { eligible: false, reason: 'patchValue is required' };
+    }
+
+    if (!hasText(data.transformRules.action)) {
+      return { eligible: false, reason: 'transformRules.action is required' };
+    }
+
+    // Validate action value
+    const validOperations = ['insertBefore', 'insertAfter', 'replace'];
+    if (!validOperations.includes(data.transformRules.action)) {
+      return {
+        eligible: false,
+        reason: `transformRules.action must be one of: ${validOperations.join(', ')}. Got: ${data.transformRules.action}`,
+      };
+    }
+
+    if (!hasText(data?.url)) {
+      return { eligible: false, reason: 'url is required' };
+    }
+
+    return { eligible: true };
+  }
+}

package/src/mappers/mapper-registry.js

@@ -14,6 +14,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';
+import GenericMapper from './generic-mapper.js';
 
 /**
  * Registry for opportunity mappers
@@ -36,6 +37,7 @@ export default class MapperRegistry {
       ContentSummarizationMapper,
       FaqMapper,
       ReadabilityMapper,
+      GenericMapper,
       // more mappers here
     ];
 

package/src/mappers/readability-mapper.js

@@ -89,8 +89,8 @@ export default class ReadabilityMapper extends BaseOpportunityMapper {
 
     const { transformRules } = data;
 
-    if (!isValidUrl(data.pageUrl)) {
-      return { eligible: false, reason: `pageUrl ${data.pageUrl} is not a valid URL` };
+    if (!isValidUrl(data.url)) {
+      return { eligible: false, reason: `url ${data.url} is not a valid URL` };
     }
 
     if (!hasText(transformRules.selector)) {

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

@@ -0,0 +1,665 @@
+/*
+ * 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 GenericMapper from '../../src/mappers/generic-mapper.js';
+
+describe('GenericMapper', () => {
+  let mapper;
+  let log;
+
+  beforeEach(() => {
+    log = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    };
+    mapper = new GenericMapper(log);
+  });
+
+  describe('getOpportunityType', () => {
+    it('should return generic', () => {
+      expect(mapper.getOpportunityType()).to.equal('generic-autofix-edge');
+    });
+  });
+
+  describe('requiresPrerender', () => {
+    it('should return true', () => {
+      expect(mapper.requiresPrerender()).to.be.true;
+    });
+  });
+
+  describe('canDeploy', () => {
+    it('should return eligible for valid suggestion with all required fields', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#create-with-multiple-top-ai-models-all-in-one-place',
+          },
+          patchValue: 'Blah Blah some text',
+          url: 'https://www.adobe.com/products/firefly.html',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({ eligible: true });
+    });
+
+    it('should return eligible for insertBefore operation', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'insertBefore',
+            selector: 'h1',
+          },
+          patchValue: 'New content',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({ eligible: true });
+    });
+
+    it('should return eligible for replace operation', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'replace',
+            selector: '.content',
+          },
+          patchValue: 'Replaced content',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({ eligible: true });
+    });
+
+    it('should return ineligible when transformRules is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          patchValue: 'Some text',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules is required',
+      });
+    });
+
+    it('should return ineligible when selector is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+          },
+          patchValue: 'Some text',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.selector is required',
+      });
+    });
+
+    it('should return ineligible when selector is empty string', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '',
+          },
+          patchValue: 'Some text',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.selector is required',
+      });
+    });
+
+    it('should return ineligible when patchValue is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'patchValue is required',
+      });
+    });
+
+    it('should return ineligible when patchValue is empty string', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          patchValue: '',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'patchValue is required',
+      });
+    });
+
+    it('should return ineligible when action is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            selector: '#selector',
+          },
+          patchValue: 'Some text',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.action is required',
+      });
+    });
+
+    it('should return ineligible when action is empty string', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: '',
+            selector: '#selector',
+          },
+          patchValue: 'Some text',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.action is required',
+      });
+    });
+
+    it('should return ineligible when action is invalid', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'invalidOperation',
+            selector: '#selector',
+          },
+          patchValue: 'Some text',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules.action must be one of: insertBefore, insertAfter, replace. Got: invalidOperation',
+      });
+    });
+
+    it('should return ineligible when url is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          patchValue: 'Some text',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'url is required',
+      });
+    });
+
+    it('should return ineligible when url is empty string', () => {
+      const suggestion = {
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          patchValue: 'Some text',
+          url: '',
+        }),
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'url 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 data is undefined', () => {
+      const suggestion = {
+        getData: () => undefined,
+      };
+
+      const result = mapper.canDeploy(suggestion);
+
+      expect(result).to.deep.equal({
+        eligible: false,
+        reason: 'transformRules is required',
+      });
+    });
+  });
+
+  describe('suggestionsToPatches', () => {
+    it('should create patch for valid suggestion with insertAfter', () => {
+      const suggestion = {
+        getId: () => 'ee8fc5e8-29c1-4894-9391-efc10b8a5f5c',
+        getUpdatedAt: () => '2025-11-27T16:22:14.258Z',
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#create-with-multiple-top-ai-models-all-in-one-place',
+          },
+          patchValue: 'Blah Blah some text',
+          url: 'https://www.adobe.com/products/firefly.html',
+          contentBefore: '**Create with multiple top AI models, all in one place.**',
+          rationale: 'This makes LLMs read more text about blah blah.',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches(
+        '/products/firefly.html',
+        [suggestion],
+        '7a663e47-e132-4bba-954a-26419e0541b8',
+      );
+
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      expect(patch).to.deep.include({
+        op: 'insertAfter',
+        selector: '#create-with-multiple-top-ai-models-all-in-one-place',
+        value: 'Blah Blah some text',
+        valueFormat: 'text',
+        opportunityId: '7a663e47-e132-4bba-954a-26419e0541b8',
+        suggestionId: 'ee8fc5e8-29c1-4894-9391-efc10b8a5f5c',
+        prerenderRequired: true,
+      });
+      expect(patch.lastUpdated).to.be.a('number');
+      expect(patch.target).to.equal('ai-bots');
+    });
+
+    it('should create patch for insertBefore operation', () => {
+      const suggestion = {
+        getId: () => 'sugg-123',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          transformRules: {
+            action: 'insertBefore',
+            selector: 'h1',
+          },
+          patchValue: 'Important notice',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/page', [suggestion], 'opp-123');
+
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      expect(patch).to.deep.include({
+        op: 'insertBefore',
+        selector: 'h1',
+        value: 'Important notice',
+        valueFormat: 'text',
+        opportunityId: 'opp-123',
+        suggestionId: 'sugg-123',
+        prerenderRequired: true,
+      });
+      expect(patch.lastUpdated).to.be.a('number');
+    });
+
+    it('should create patch for replace operation', () => {
+      const suggestion = {
+        getId: () => 'sugg-456',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          transformRules: {
+            action: 'replace',
+            selector: '.content',
+          },
+          patchValue: 'Replaced content text',
+          url: 'https://example.com/page2',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/page2', [suggestion], 'opp-456');
+
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      expect(patch).to.deep.include({
+        op: 'replace',
+        selector: '.content',
+        value: 'Replaced content text',
+        valueFormat: 'text',
+        opportunityId: 'opp-456',
+        suggestionId: 'sugg-456',
+        prerenderRequired: true,
+      });
+      expect(patch.lastUpdated).to.be.a('number');
+    });
+
+    it('should handle multiple suggestions', () => {
+      const suggestions = [
+        {
+          getId: () => 'sugg-1',
+          getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+          getData: () => ({
+            transformRules: {
+              action: 'insertAfter',
+              selector: '#selector1',
+            },
+            patchValue: 'Text 1',
+            url: 'https://example.com/page',
+          }),
+        },
+        {
+          getId: () => 'sugg-2',
+          getUpdatedAt: () => '2025-01-15T11:00:00.000Z',
+          getData: () => ({
+            transformRules: {
+              action: 'insertBefore',
+              selector: '#selector2',
+            },
+            patchValue: 'Text 2',
+            url: 'https://example.com/page',
+          }),
+        },
+      ];
+
+      const patches = mapper.suggestionsToPatches('/page', suggestions, 'opp-123');
+
+      expect(patches.length).to.equal(2);
+      expect(patches[0].suggestionId).to.equal('sugg-1');
+      expect(patches[0].value).to.equal('Text 1');
+      expect(patches[1].suggestionId).to.equal('sugg-2');
+      expect(patches[1].value).to.equal('Text 2');
+    });
+
+    it('should return empty array for invalid suggestion', () => {
+      const suggestion = {
+        getId: () => 'sugg-invalid',
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          // Missing patchValue
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/page', [suggestion], 'opp-invalid');
+
+      expect(patches.length).to.equal(0);
+    });
+
+    it('should skip invalid suggestions but process valid ones', () => {
+      const suggestions = [
+        {
+          getId: () => 'sugg-valid',
+          getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+          getData: () => ({
+            transformRules: {
+              action: 'insertAfter',
+              selector: '#valid',
+            },
+            patchValue: 'Valid text',
+            url: 'https://example.com/page',
+          }),
+        },
+        {
+          getId: () => 'sugg-invalid',
+          getData: () => ({
+            transformRules: {
+              action: 'insertAfter',
+              selector: '#invalid',
+            },
+            // Missing patchValue
+            url: 'https://example.com/page',
+          }),
+        },
+      ];
+
+      const patches = mapper.suggestionsToPatches('/page', suggestions, 'opp-123');
+
+      expect(patches.length).to.equal(1);
+      expect(patches[0].suggestionId).to.equal('sugg-valid');
+    });
+
+    it('should log warning for invalid suggestion', () => {
+      let warnMessage = '';
+      const warnLog = {
+        debug: () => {},
+        info: () => {},
+        warn: (msg) => { warnMessage = msg; },
+        error: () => {},
+      };
+      const warnMapper = new GenericMapper(warnLog);
+
+      const suggestion = {
+        getId: () => 'sugg-warn',
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          // Missing patchValue
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const patches = warnMapper.suggestionsToPatches('/page', [suggestion], 'opp-warn');
+
+      expect(patches.length).to.equal(0);
+      expect(warnMessage).to.include('Generic suggestion sugg-warn cannot be deployed');
+      expect(warnMessage).to.include('patchValue is required');
+    });
+
+    it('should handle complex CSS selectors', () => {
+      const suggestion = {
+        getId: () => 'sugg-complex',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#text-85a9876220 > h2:nth-of-type(1)',
+          },
+          patchValue: 'Complex selector content',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/page', [suggestion], 'opp-complex');
+
+      expect(patches.length).to.equal(1);
+      expect(patches[0].selector).to.equal('#text-85a9876220 > h2:nth-of-type(1)');
+    });
+
+    it('should handle multiline patchValue', () => {
+      const suggestion = {
+        getId: () => 'sugg-multiline',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          transformRules: {
+            action: 'replace',
+            selector: '.content',
+          },
+          patchValue: 'Line 1\nLine 2\nLine 3',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/page', [suggestion], 'opp-multiline');
+
+      expect(patches.length).to.equal(1);
+      expect(patches[0].value).to.equal('Line 1\nLine 2\nLine 3');
+    });
+
+    it('should include tag when provided', () => {
+      const suggestion = {
+        getId: () => 'sugg-with-tag',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          patchValue: 'Content with tag',
+          format: 'hast',
+          tag: 'div',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/page', [suggestion], 'opp-tag');
+
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      expect(patch).to.deep.include({
+        op: 'insertAfter',
+        selector: '#selector',
+        value: 'Content with tag',
+        valueFormat: 'hast',
+        tag: 'div',
+        opportunityId: 'opp-tag',
+        suggestionId: 'sugg-with-tag',
+        prerenderRequired: true,
+      });
+      expect(patch.lastUpdated).to.be.a('number');
+    });
+
+    it('should not include tag when not provided', () => {
+      const suggestion = {
+        getId: () => 'sugg-no-tag',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          patchValue: 'Content without tag',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/page', [suggestion], 'opp-no-tag');
+
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      expect(patch.tag).to.be.undefined;
+      expect(patch.valueFormat).to.equal('text');
+    });
+
+    it('should not include UI-only fields in patch', () => {
+      const suggestion = {
+        getId: () => 'sugg-ui',
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+        getData: () => ({
+          transformRules: {
+            action: 'insertAfter',
+            selector: '#selector',
+          },
+          patchValue: 'Text content',
+          url: 'https://example.com/page',
+          contentBefore: 'Original content',
+          expectedContentAfter: 'Expected result',
+          rationale: 'This improves SEO',
+          aggregationKey: 'some-key',
+        }),
+      };
+
+      const patches = mapper.suggestionsToPatches('/page', [suggestion], 'opp-ui');
+
+      expect(patches.length).to.equal(1);
+      const patch = patches[0];
+
+      // Should not include UI-only fields
+      expect(patch.contentBefore).to.be.undefined;
+      expect(patch.expectedContentAfter).to.be.undefined;
+      expect(patch.rationale).to.be.undefined;
+      expect(patch.aggregationKey).to.be.undefined;
+
+      // Should include only operational fields
+      expect(patch.op).to.equal('insertAfter');
+      expect(patch.selector).to.equal('#selector');
+      expect(patch.value).to.equal('Text content');
+    });
+  });
+});

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

@@ -46,7 +46,7 @@ describe('ReadabilityMapper', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Lorem ipsum...',
-          pageUrl: 'https://www.website.com',
+          url: 'https://www.website.com',
           transformRules: {
             value: 'Tech enthusiasts keep up with the latest tech news...',
             op: 'replace',
@@ -66,7 +66,7 @@ describe('ReadabilityMapper', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Lorem ipsum...',
-          pageUrl: 'https://www.website.com',
+          url: 'https://www.website.com',
           transformRules: {
             value: 'Improved readability text...',
             op: 'replace',
@@ -84,7 +84,7 @@ describe('ReadabilityMapper', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Lorem ipsum...',
-          pageUrl: 'https://www.website.com',
+          url: 'https://www.website.com',
         }),
       };
 
@@ -113,7 +113,7 @@ describe('ReadabilityMapper', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           transformRules: {
             value: 'New text',
             op: 'replace',
@@ -133,7 +133,7 @@ describe('ReadabilityMapper', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           transformRules: {
             value: 'New text',
             selector: '#content',
@@ -153,7 +153,7 @@ describe('ReadabilityMapper', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           transformRules: {
             value: 'New text',
             op: 'insertAfter',
@@ -174,7 +174,7 @@ describe('ReadabilityMapper', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           transformRules: {
             op: 'replace',
             selector: '#content',
@@ -194,7 +194,7 @@ describe('ReadabilityMapper', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           transformRules: {
             value: 'New text',
             op: 'replace',
@@ -211,11 +211,11 @@ describe('ReadabilityMapper', () => {
       });
     });
 
-    it('should return ineligible when pageUrl is invalid', () => {
+    it('should return ineligible when url is invalid', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'not-a-valid-url',
+          url: 'not-a-valid-url',
           transformRules: {
             value: 'New text',
             op: 'replace',
@@ -228,11 +228,11 @@ describe('ReadabilityMapper', () => {
 
       expect(result).to.deep.equal({
         eligible: false,
-        reason: 'pageUrl not-a-valid-url is not a valid URL',
+        reason: 'url not-a-valid-url is not a valid URL',
       });
     });
 
-    it('should return ineligible when pageUrl is missing', () => {
+    it('should return ineligible when url is missing', () => {
       const suggestion = {
         getData: () => ({
           textPreview: 'Text...',
@@ -248,7 +248,7 @@ describe('ReadabilityMapper', () => {
 
       expect(result).to.deep.equal({
         eligible: false,
-        reason: 'pageUrl undefined is not a valid URL',
+        reason: 'url undefined is not a valid URL',
       });
     });
   });
@@ -260,7 +260,7 @@ describe('ReadabilityMapper', () => {
         getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
         getData: () => ({
           textPreview: 'Lorem ipsum...',
-          pageUrl: 'https://www.website.com',
+          url: 'https://www.website.com',
           scrapedAt: '2025-09-20T06:21:12.584Z',
           transformRules: {
             value: 'Tech enthusiasts keep up with the latest tech news...',
@@ -296,7 +296,7 @@ describe('ReadabilityMapper', () => {
         getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
         getData: () => ({
           textPreview: 'Original text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           scrapedAt: '2025-09-20T06:21:12.584Z',
           transformRules: {
             value: 'Improved readability text',
@@ -319,7 +319,7 @@ describe('ReadabilityMapper', () => {
         getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           transformRules: {
             value: 'Better text',
             op: 'replace',
@@ -341,7 +341,7 @@ describe('ReadabilityMapper', () => {
         getId: () => 'sugg-999',
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           // Missing transformRules
         }),
       };
@@ -364,7 +364,7 @@ describe('ReadabilityMapper', () => {
         getId: () => 'sugg-warn',
         getData: () => ({
           textPreview: 'Text...',
-          pageUrl: 'https://www.example.com',
+          url: 'https://www.example.com',
           transformRules: {
             op: 'replace',
             // Missing selector and value
@@ -386,7 +386,7 @@ describe('ReadabilityMapper', () => {
           getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
           getData: () => ({
             textPreview: 'Original text 1',
-            pageUrl: 'https://www.example.com/page1',
+            url: 'https://www.example.com/page1',
             transformRules: {
               value: 'First improved text',
               op: 'replace',
@@ -399,7 +399,7 @@ describe('ReadabilityMapper', () => {
           getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
           getData: () => ({
             textPreview: 'Original text 2',
-            pageUrl: 'https://www.example.com/page2',
+            url: 'https://www.example.com/page2',
             transformRules: {
               value: 'Second improved text',
               op: 'replace',