@adobe/spacecat-shared-tokowaka-client 1.0.2 → 1.0.4

package/src/mappers/headings-mapper.js

@@ -33,30 +33,44 @@ export default class HeadingsMapper extends BaseOpportunityMapper {
     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;
-    }
+  /**
+   * 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 = [];
 
-    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;
+    suggestions.forEach((suggestion) => {
+      const eligibility = this.canDeploy(suggestion);
+      if (!eligibility.eligible) {
+        this.log.warn(`Headings suggestion ${suggestion.getId()} cannot be deployed: ${eligibility.reason}`);
+        return;
+      }
+
+      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;
+      }
+
+      patches.push(patch);
+    });
+
+    return patches;
   }
 
   /**

package/src/mappers/mapper-registry.js

@@ -12,6 +12,7 @@
 
 import HeadingsMapper from './headings-mapper.js';
 import ContentSummarizationMapper from './content-summarization-mapper.js';
+import FaqMapper from './faq-mapper.js';
 
 /**
  * Registry for opportunity mappers
@@ -32,6 +33,7 @@ export default class MapperRegistry {
     const defaultMappers = [
       HeadingsMapper,
       ContentSummarizationMapper,
+      FaqMapper,
       // more mappers here
     ];
 

package/src/utils/markdown-utils.js

@@ -0,0 +1,24 @@
+/*
+ * 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 { toHast } from 'mdast-util-to-hast';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+
+/**
+ * Converts markdown text to HAST (Hypertext Abstract Syntax Tree) format
+ * @param {string} markdown - Markdown text
+ * @returns {Object} - HAST object
+ */
+export function markdownToHast(markdown) {
+  const mdast = fromMarkdown(markdown);
+  return toHast(mdast);
+}

package/src/utils/patch-utils.js

@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+
+/**
+ * Generates a unique key for a patch based on its structure
+ * Individual patches (one suggestion per patch):
+ *    → Key: opportunityId:suggestionId
+ * Patches with no suggestionId:
+ *    → Key: opportunityId
+ */
+function getPatchKey(patch) {
+  // Heading patch (no suggestionId): use special key
+  if (!patch.suggestionId) {
+    return `${patch.opportunityId}`;
+  }
+
+  // Individual patches include suggestionId in key
+  // This ensures each suggestion gets its own separate patch
+  return `${patch.opportunityId}:${patch.suggestionId}`;
+}
+
+/**
+ * Merges new patches into existing patches based on patch keys
+ * - If a patch with the same key exists, it's updated
+ * - If a patch with a new key is found, it's added
+ * @param {Array} existingPatches - Array of existing patches
+ * @param {Array} newPatches - Array of new patches to merge
+ * @returns {Object} - { patches: Array, updateCount: number, addCount: number }
+ */
+export function mergePatches(existingPatches, newPatches) {
+  // Create a map of existing patches by their key
+  const patchMap = new Map();
+  existingPatches.forEach((patch, index) => {
+    const key = getPatchKey(patch);
+    patchMap.set(key, { patch, index });
+  });
+
+  // Process new patches
+  const mergedPatches = [...existingPatches];
+  let updateCount = 0;
+  let addCount = 0;
+
+  newPatches.forEach((newPatch) => {
+    const key = getPatchKey(newPatch);
+    const existing = patchMap.get(key);
+
+    if (existing) {
+      mergedPatches[existing.index] = newPatch;
+      updateCount += 1;
+    } else {
+      mergedPatches.push(newPatch);
+      addCount += 1;
+    }
+  });
+
+  return { patches: mergedPatches, updateCount, addCount };
+}

package/src/utils/s3-utils.js

@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+
+/**
+ * Generates S3 path for Tokowaka configuration
+ * @param {string} apiKey - Tokowaka API key
+ * @returns {string} - S3 path
+ */
+export function getTokowakaConfigS3Path(apiKey) {
+  return `opportunities/${apiKey}`;
+}

package/src/utils/site-utils.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 { isValidUrl } from '@adobe/spacecat-shared-utils';
+
+/**
+ * Gets the effective base URL for a site, respecting overrideBaseURL if configured
+ * @param {Object} site - Site entity
+ * @returns {string} - Base URL to use
+ */
+export function getEffectiveBaseURL(site) {
+  const overrideBaseURL = site.getConfig()?.getFetchConfig?.()?.overrideBaseURL;
+  return (overrideBaseURL && isValidUrl(overrideBaseURL))
+    ? overrideBaseURL
+    : site.getBaseURL();
+}

package/src/utils/suggestion-utils.js

@@ -0,0 +1,69 @@
+/*
+ * 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.
+ */
+
+/**
+ * Groups suggestions by URL pathname
+ * @param {Array} suggestions - Array of suggestion entities
+ * @param {string} baseURL - Base URL for pathname extraction
+ * @param {Object} log - Logger instance
+ * @returns {Object} - Object with URL paths as keys and arrays of suggestions as values
+ */
+export function groupSuggestionsByUrlPath(suggestions, baseURL, log) {
+  return suggestions.reduce((acc, suggestion) => {
+    const data = suggestion.getData();
+    const url = data?.url;
+
+    if (!url) {
+      log.warn(`Suggestion ${suggestion.getId()} does not have a URL, skipping`);
+      return acc;
+    }
+
+    let urlPath;
+    try {
+      urlPath = new URL(url, baseURL).pathname;
+    } catch (e) {
+      log.warn(`Failed to extract pathname from URL for suggestion ${suggestion.getId()}: ${url}`);
+      return acc;
+    }
+
+    if (!acc[urlPath]) {
+      acc[urlPath] = [];
+    }
+    acc[urlPath].push(suggestion);
+    return acc;
+  }, {});
+}
+
+/**
+ * Filters suggestions into eligible and ineligible based on mapper's canDeploy method
+ * @param {Array} suggestions - Array of suggestion entities
+ * @param {Object} mapper - Mapper instance with canDeploy method
+ * @returns {Object} - { eligible: Array, ineligible: Array<{suggestion, reason}> }
+ */
+export function filterEligibleSuggestions(suggestions, mapper) {
+  const eligible = [];
+  const ineligible = [];
+
+  suggestions.forEach((suggestion) => {
+    const eligibility = mapper.canDeploy(suggestion);
+    if (eligibility.eligible) {
+      eligible.push(suggestion);
+    } else {
+      ineligible.push({
+        suggestion,
+        reason: eligibility.reason || 'Suggestion cannot be deployed',
+      });
+    }
+  });
+
+  return { eligible, ineligible };
+}

package/test/index.test.js

@@ -199,7 +199,7 @@ describe('TokowakaClient', () => {
 
   describe('generateConfig', () => {
     it('should generate config for headings opportunity', () => {
-      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions);
+      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions, null);
 
       expect(config).to.deep.include({
         siteId: 'site-123',
@@ -218,12 +218,105 @@ describe('TokowakaClient', () => {
         selector: 'h1',
         value: 'New Heading',
         opportunityId: 'opp-123',
-        suggestionId: 'sugg-1',
         prerenderRequired: true,
       });
+      expect(patch.suggestionId).to.equal('sugg-1');
       expect(patch).to.have.property('lastUpdated');
     });
 
+    it('should generate config for FAQ opportunity', () => {
+      mockOpportunity = {
+        getId: () => 'opp-faq-123',
+        getType: () => 'faq',
+      };
+
+      mockSuggestions = [
+        {
+          getId: () => 'sugg-faq-1',
+          getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+          getData: () => ({
+            url: 'https://example.com/page1',
+            headingText: 'FAQs',
+            shouldOptimize: true,
+            item: {
+              question: 'Question 1?',
+              answer: 'Answer 1.',
+            },
+            transformRules: {
+              action: 'appendChild',
+              selector: 'main',
+            },
+          }),
+        },
+        {
+          getId: () => 'sugg-faq-2',
+          getUpdatedAt: () => '2025-01-15T11:00:00.000Z',
+          getData: () => ({
+            url: 'https://example.com/page1',
+            headingText: 'FAQs',
+            shouldOptimize: true,
+            item: {
+              question: 'Question 2?',
+              answer: 'Answer 2.',
+            },
+            transformRules: {
+              action: 'appendChild',
+              selector: 'main',
+            },
+          }),
+        },
+      ];
+
+      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions, null);
+
+      expect(config).to.deep.include({
+        siteId: 'site-123',
+        baseURL: 'https://example.com',
+        version: '1.0',
+        tokowakaForceFail: false,
+      });
+
+      expect(config.tokowakaOptimizations).to.have.property('/page1');
+      expect(config.tokowakaOptimizations['/page1'].prerender).to.be.true;
+      expect(config.tokowakaOptimizations['/page1'].patches).to.have.length(3); // heading + 2 FAQs
+
+      // First patch: heading (no suggestionId)
+      const headingPatch = config.tokowakaOptimizations['/page1'].patches[0];
+      expect(headingPatch).to.include({
+        op: 'appendChild',
+        selector: 'main',
+        opportunityId: 'opp-faq-123',
+        prerenderRequired: true,
+      });
+      expect(headingPatch.suggestionId).to.be.undefined;
+      expect(headingPatch).to.have.property('lastUpdated');
+      expect(headingPatch.value.tagName).to.equal('h2');
+
+      // Second patch: first FAQ
+      const firstFaqPatch = config.tokowakaOptimizations['/page1'].patches[1];
+      expect(firstFaqPatch).to.include({
+        op: 'appendChild',
+        selector: 'main',
+        opportunityId: 'opp-faq-123',
+        prerenderRequired: true,
+      });
+      expect(firstFaqPatch.suggestionId).to.equal('sugg-faq-1');
+      expect(firstFaqPatch).to.have.property('lastUpdated');
+      expect(firstFaqPatch.value.tagName).to.equal('div');
+
+      // Third patch: second FAQ
+      const secondFaqPatch = config.tokowakaOptimizations['/page1'].patches[2];
+      expect(secondFaqPatch).to.include({
+        op: 'appendChild',
+        selector: 'main',
+        opportunityId: 'opp-faq-123',
+        prerenderRequired: true,
+      });
+      expect(secondFaqPatch.suggestionId).to.equal('sugg-faq-2');
+      expect(secondFaqPatch).to.have.property('lastUpdated');
+      expect(secondFaqPatch.value.tagName).to.equal('div');
+    });
+
     it('should group suggestions by URL path', () => {
       mockSuggestions = [
         {
@@ -254,7 +347,7 @@ describe('TokowakaClient', () => {
         },
       ];
 
-      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions);
+      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions, null);
 
       expect(Object.keys(config.tokowakaOptimizations)).to.have.length(2);
       expect(config.tokowakaOptimizations).to.have.property('/page1');
@@ -289,7 +382,7 @@ describe('TokowakaClient', () => {
         },
       ];
 
-      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions);
+      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions, null);
 
       expect(Object.keys(config.tokowakaOptimizations)).to.have.length(1);
       expect(config.tokowakaOptimizations).to.have.property('/relative-path');
@@ -306,7 +399,7 @@ describe('TokowakaClient', () => {
         },
       ];
 
-      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions);
+      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions, null);
 
       expect(Object.keys(config.tokowakaOptimizations)).to.have.length(0);
       expect(log.warn).to.have.been.calledWith(sinon.match(/does not have a URL/));
@@ -329,7 +422,7 @@ describe('TokowakaClient', () => {
         },
       ];
 
-      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions);
+      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions, null);
 
       expect(Object.keys(config.tokowakaOptimizations)).to.have.length(0);
       expect(log.warn).to.have.been.calledWith(sinon.match(/Failed to extract pathname from URL/));
@@ -363,10 +456,23 @@ describe('TokowakaClient', () => {
         },
       ];
 
-      expect(() => client.generateConfig(mockSite, mockOpportunity, mockSuggestions))
+      expect(() => client.generateConfig(mockSite, mockOpportunity, mockSuggestions, null))
         .to.throw(/No mapper found for opportunity type: unsupported-type/)
         .with.property('status', 501);
     });
+
+    it('should generate config without allOpportunitySuggestions', () => {
+      const config = client.generateConfig(mockSite, mockOpportunity, mockSuggestions, null);
+
+      expect(config).to.deep.include({
+        siteId: 'site-123',
+        baseURL: 'https://example.com',
+        version: '1.0',
+        tokowakaForceFail: false,
+      });
+
+      expect(config.tokowakaOptimizations).to.have.property('/page1');
+    });
   });
 
   describe('uploadConfig', () => {

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

@@ -41,9 +41,9 @@ describe('BaseOpportunityMapper', () => {
         .to.throw('requiresPrerender() must be implemented by subclass');
     });
 
-    it('suggestionToPatch should throw error', () => {
-      expect(() => mapper.suggestionToPatch({}, 'opp-123'))
-        .to.throw('suggestionToPatch() must be implemented by subclass');
+    it('suggestionsToPatches should throw error', () => {
+      expect(() => mapper.suggestionsToPatches('/path', [], 'opp-123', null))
+        .to.throw('suggestionsToPatches() must be implemented by subclass');
     });
 
     it('canDeploy should throw error if not implemented', () => {
@@ -60,14 +60,15 @@ describe('BaseOpportunityMapper', () => {
 
         requiresPrerender() { return true; }
 
-        suggestionToPatch() { return {}; }
+        suggestionsToPatches() { return []; }
 
         canDeploy() { return { eligible: true }; }
       }
 
-      const testMapper = new TestMapper();
+      const testMapper = new TestMapper(log);
       const suggestion = {
         getId: () => 'test-123',
+        getData: () => ({}),
         getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
       };
 
@@ -85,14 +86,15 @@ describe('BaseOpportunityMapper', () => {
 
         requiresPrerender() { return true; }
 
-        suggestionToPatch() { return {}; }
+        suggestionsToPatches() { return []; }
 
         canDeploy() { return { eligible: true }; }
       }
 
-      const testMapper = new TestMapper();
+      const testMapper = new TestMapper(log);
       const suggestion = {
         getId: () => 'test-no-date',
+        getData: () => ({}),
         getUpdatedAt: () => null, // Returns null
       };
 
@@ -106,5 +108,103 @@ describe('BaseOpportunityMapper', () => {
       expect(patch.lastUpdated).to.be.at.most(afterTime);
       expect(patch.prerenderRequired).to.be.true;
     });
+
+    it('should prioritize scrapedAt from getData()', () => {
+      class TestMapper extends BaseOpportunityMapper {
+        getOpportunityType() { return 'test'; }
+
+        requiresPrerender() { return true; }
+
+        suggestionsToPatches() { return []; }
+
+        canDeploy() { return { eligible: true }; }
+      }
+
+      const testMapper = new TestMapper(log);
+      const scrapedTime = '2025-01-20T15:30:00.000Z';
+      const suggestion = {
+        getId: () => 'test-scraped',
+        getData: () => ({ scrapedAt: scrapedTime }),
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+      };
+
+      const patch = testMapper.createBasePatch(suggestion, 'opp-scraped');
+
+      expect(patch.lastUpdated).to.equal(new Date(scrapedTime).getTime());
+    });
+
+    it('should use transformRules.scrapedAt when scrapedAt is not available', () => {
+      class TestMapper extends BaseOpportunityMapper {
+        getOpportunityType() { return 'test'; }
+
+        requiresPrerender() { return true; }
+
+        suggestionsToPatches() { return []; }
+
+        canDeploy() { return { eligible: true }; }
+      }
+
+      const testMapper = new TestMapper(log);
+      const transformScrapedTime = '2025-01-18T12:00:00.000Z';
+      const suggestion = {
+        getId: () => 'test-transform',
+        getData: () => ({ transformRules: { scrapedAt: transformScrapedTime } }),
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+      };
+
+      const patch = testMapper.createBasePatch(suggestion, 'opp-transform');
+
+      expect(patch.lastUpdated).to.equal(new Date(transformScrapedTime).getTime());
+    });
+
+    it('should handle invalid date strings by using Date.now()', () => {
+      class TestMapper extends BaseOpportunityMapper {
+        getOpportunityType() { return 'test'; }
+
+        requiresPrerender() { return true; }
+
+        suggestionsToPatches() { return []; }
+
+        canDeploy() { return { eligible: true }; }
+      }
+
+      const testMapper = new TestMapper(log);
+      const suggestion = {
+        getId: () => 'test-invalid',
+        getData: () => ({}),
+        getUpdatedAt: () => 'invalid-date-string',
+      };
+
+      const beforeTime = Date.now();
+      const patch = testMapper.createBasePatch(suggestion, 'opp-invalid');
+      const afterTime = Date.now();
+
+      // Should fallback to Date.now() for invalid dates
+      expect(patch.lastUpdated).to.be.at.least(beforeTime);
+      expect(patch.lastUpdated).to.be.at.most(afterTime);
+    });
+
+    it('should handle missing getData() gracefully', () => {
+      class TestMapper extends BaseOpportunityMapper {
+        getOpportunityType() { return 'test'; }
+
+        requiresPrerender() { return true; }
+
+        suggestionsToPatches() { return []; }
+
+        canDeploy() { return { eligible: true }; }
+      }
+
+      const testMapper = new TestMapper(log);
+      const suggestion = {
+        getId: () => 'test-no-data',
+        getData: () => null,
+        getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+      };
+
+      const patch = testMapper.createBasePatch(suggestion, 'opp-no-data');
+
+      expect(patch.lastUpdated).to.equal(new Date('2025-01-15T10:00:00.000Z').getTime());
+    });
   });
 });