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

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.3.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.3.0...@adobe/spacecat-shared-tokowaka-client-v1.3.1) (2025-12-10)
+
+
+### Bug Fixes
+
+* heading and toc mappers ([#1230](https://github.com/adobe/spacecat-shared/issues/1230)) ([f767fb3](https://github.com/adobe/spacecat-shared/commit/f767fb319c97ed64848a1c5fc5913693a52290d9))
+
 # [@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)
 
 

package/package.json

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

package/src/index.d.ts

@@ -34,7 +34,9 @@ export const TARGET_USER_AGENTS_CATEGORIES: {
 
 export interface TokowakaMetaconfig {
   siteId: string;
-  prerender: boolean;
+  prerender?: {
+    allowList?: string[];
+  } | boolean;
 }
 
 export interface TokowakaConfig {
@@ -231,6 +233,23 @@ export class FaqMapper extends BaseOpportunityMapper {
   ): TokawakaPatch[];
 }
 
+/**
+ * Table of Contents (TOC) opportunity mapper
+ * Handles conversion of TOC suggestions to Tokowaka patches with HAST format
+ */
+export class TocMapper extends BaseOpportunityMapper {
+  constructor(log: any);
+  
+  getOpportunityType(): string;
+  requiresPrerender(): boolean;
+  suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string
+  ): TokawakaPatch[];
+  canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
+}
+
 /**
  * Registry for opportunity mappers
  */

package/src/index.js

@@ -122,7 +122,8 @@ class TokowakaClient {
       opportunity.getId(),
     );
 
-    if (patches.length === 0) {
+    // Check if configs without patches are allowed (e.g., prerender-only)
+    if (patches.length === 0 && !mapper.allowConfigsWithoutPatch()) {
       return null;
     }
 
@@ -445,7 +446,16 @@ class TokowakaClient {
       // Generate configuration for this URL with eligible suggestions only
       const newConfig = this.generateConfig(fullUrl, opportunity, urlSuggestions);
 
-      if (!newConfig || !newConfig.patches || newConfig.patches.length === 0) {
+      if (!newConfig) {
+        this.log.warn(`No config generated for URL: ${fullUrl}`);
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      // Check if mapper allows configs without patches (e.g., prerender-only config)
+      const allowsNoPatch = mapper.allowConfigsWithoutPatch() && newConfig.patches.length === 0;
+
+      if (!allowsNoPatch && (!newConfig.patches || newConfig.patches.length === 0)) {
         this.log.warn(`No eligible suggestions to deploy for URL: ${fullUrl}`);
         // eslint-disable-next-line no-continue
         continue;
@@ -534,7 +544,7 @@ class TokowakaClient {
       // eslint-disable-next-line no-await-in-loop
       const existingConfig = await this.fetchConfig(fullUrl);
 
-      if (!existingConfig || !existingConfig.patches) {
+      if (!existingConfig) {
         this.log.warn(`No existing configuration found for URL: ${fullUrl}`);
         // eslint-disable-next-line no-continue
         continue;
@@ -543,6 +553,40 @@ class TokowakaClient {
       // Extract suggestion IDs to remove for this URL
       const suggestionIdsToRemove = urlSuggestions.map((s) => s.getId());
 
+      // For prerender opportunities, disable prerender flag
+      if (opportunityType === 'prerender') {
+        this.log.info(`Rolling back prerender config for URL: ${fullUrl}`);
+
+        // Set prerender to false (keep other patches if they exist)
+        const updatedConfig = {
+          ...existingConfig,
+          prerender: false,
+        };
+
+        // Upload updated config to S3 for this URL
+        // eslint-disable-next-line no-await-in-loop
+        const s3Path = await this.uploadConfig(fullUrl, updatedConfig);
+        s3Paths.push(s3Path);
+
+        // Invalidate CDN cache
+        // eslint-disable-next-line no-await-in-loop
+        const cdnInvalidationResult = await this.invalidateCdnCache(
+          fullUrl,
+          this.env.TOKOWAKA_CDN_PROVIDER,
+        );
+        cdnInvalidations.push(cdnInvalidationResult);
+
+        totalRemovedCount += 1; // Count as 1 rollback
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      if (!existingConfig.patches) {
+        this.log.info(`No patches found in configuration for URL: ${fullUrl}`);
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
       // Use mapper to remove patches
       const updatedConfig = mapper.rollbackPatches(
         existingConfig,
@@ -551,7 +595,7 @@ class TokowakaClient {
       );
 
       if (updatedConfig.removedCount === 0) {
-        this.log.warn(`No patches found for URL: ${fullUrl}`);
+        this.log.warn(`No patches found for suggestions at URL: ${fullUrl}`);
         // eslint-disable-next-line no-continue
         continue;
       }
@@ -661,7 +705,17 @@ class TokowakaClient {
     this.log.debug(`Generating preview Tokowaka config for opportunity ${opportunity.getId()}`);
     const newConfig = this.generateConfig(previewUrl, opportunity, eligibleSuggestions);
 
-    if (!newConfig || !newConfig.patches || newConfig.patches.length === 0) {
+    if (!newConfig) {
+      this.log.warn('No config generated for preview');
+      return {
+        config: null,
+        succeededSuggestions: [],
+        failedSuggestions: suggestions,
+      };
+    }
+
+    /* c8 ignore next 9 */
+    if (newConfig.patches.length === 0 && !mapper.allowConfigsWithoutPatch()) {
       this.log.warn('No eligible suggestions to preview');
       return {
         config: null,

package/src/mappers/base-mapper.js

@@ -68,6 +68,18 @@ export default class BaseOpportunityMapper {
     throw new Error('canDeploy() must be implemented by subclass');
   }
 
+  /**
+   * Determines if configurations without patches are allowed for this opportunity type
+   * By default, configurations must have at least one patch to be valid
+   * Override this method in subclasses if configs without patches are acceptable
+   * (e.g., prerender-only configs that just enable prerendering)
+   * @returns {boolean} - True if configs without patches are allowed
+   */
+  // eslint-disable-next-line class-methods-use-this
+  allowConfigsWithoutPatch() {
+    return false;
+  }
+
   /**
    * Helper method to create base patch structure
    * @protected

package/src/mappers/headings-mapper.js

@@ -85,7 +85,7 @@ export default class HeadingsMapper extends BaseOpportunityMapper {
     const checkType = data?.checkType;
 
     // Check if checkType is eligible
-    const eligibleCheckTypes = ['heading-empty', 'heading-missing-h1', 'heading-h1-length'];
+    const eligibleCheckTypes = ['heading-empty', 'heading-missing-h1', 'heading-h1-length', 'heading-order-invalid'];
     if (!eligibleCheckTypes.includes(checkType)) {
       return {
         eligible: false,
@@ -127,6 +127,21 @@ export default class HeadingsMapper extends BaseOpportunityMapper {
       }
     }
 
+    if (checkType === 'heading-order-invalid') {
+      if (data.transformRules?.action !== 'replaceWith') {
+        return {
+          eligible: false,
+          reason: `transformRules.action must be replaceWith for ${checkType}`,
+        };
+      }
+      if (data.transformRules?.valueFormat !== 'hast') {
+        return {
+          eligible: false,
+          reason: `transformRules.valueFormat must be hast for ${checkType}`,
+        };
+      }
+    }
+
     return { eligible: true };
   }
 }

package/src/mappers/mapper-registry.js

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

package/src/mappers/prerender-mapper.js

@@ -0,0 +1,78 @@
+/*
+ * 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 BaseOpportunityMapper from './base-mapper.js';
+
+/**
+ * Prerender mapper for prerender opportunities
+ * Handles prerender suggestions - these don't generate patches, just enable prerendering
+ */
+export default class PrerenderMapper extends BaseOpportunityMapper {
+  constructor(log) {
+    super(log);
+    this.opportunityType = 'prerender';
+    this.prerenderRequired = true;
+  }
+
+  getOpportunityType() {
+    return this.opportunityType;
+  }
+
+  requiresPrerender() {
+    return this.prerenderRequired;
+  }
+
+  /**
+   * Prerender allows configurations without patches
+   * Prerender-only configs just enable prerendering without DOM modifications
+   * @returns {boolean} - True, prerender allows configs without patches
+   */
+  // eslint-disable-next-line class-methods-use-this
+  allowConfigsWithoutPatch() {
+    return true;
+  }
+
+  /**
+   * Converts suggestions to Tokowaka patches
+   * For prerender, we don't generate patches - just mark prerender as required
+   * @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} - Empty array (prerender doesn't use patches)
+   */
+  // eslint-disable-next-line class-methods-use-this, no-unused-vars
+  suggestionsToPatches(urlPath, suggestions, opportunityId) {
+    // Prerender suggestions don't generate patches
+    // They just enable prerendering for the URL
+    // Return empty array so no patches are created
+    return [];
+  }
+
+  /**
+   * Checks if a prerender 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 URL exists
+    if (!hasText(data?.url)) {
+      return { eligible: false, reason: 'url is required' };
+    }
+
+    // All prerender suggestions with valid URLs are eligible
+    return { eligible: true };
+  }
+}

package/src/mappers/toc-mapper.js

@@ -0,0 +1,116 @@
+/*
+ * 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 Table of Contents (TOC) opportunity
+ * Handles conversion of TOC suggestions to Tokowaka patches
+ */
+export default class TocMapper extends BaseOpportunityMapper {
+  constructor(log) {
+    super(log);
+    this.opportunityType = 'toc';
+    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(`TOC 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: transformRules.value,
+        valueFormat: 'hast',
+        target: TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
+      };
+
+      patches.push(patch);
+    });
+
+    return patches;
+  }
+
+  /**
+   * Checks if a TOC 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();
+    const checkType = data?.checkType;
+
+    // Check if checkType is eligible
+    if (checkType !== 'toc') {
+      return {
+        eligible: false,
+        reason: `Only toc checkType can be deployed. This suggestion has checkType: ${checkType}`,
+      };
+    }
+
+    // Validate required fields
+    if (!hasText(data.transformRules?.selector)) {
+      return { eligible: false, reason: 'transformRules.selector is required' };
+    }
+
+    if (!data.transformRules?.value) {
+      return { eligible: false, reason: 'transformRules.value is required' };
+    }
+
+    if (data.transformRules?.valueFormat !== 'hast') {
+      return {
+        eligible: false,
+        reason: 'transformRules.valueFormat must be hast for toc',
+      };
+    }
+
+    // Validate action
+    const validActions = ['insertBefore', 'insertAfter'];
+    if (!validActions.includes(data.transformRules?.action)) {
+      return {
+        eligible: false,
+        reason: `transformRules.action must be one of ${validActions.join(', ')} for toc`,
+      };
+    }
+
+    return { eligible: true };
+  }
+}