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

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.0.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.0.3...@adobe/spacecat-shared-tokowaka-client-v1.0.4) (2025-11-15)
+
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#1131](https://github.com/adobe/spacecat-shared/issues/1131)) ([d4a3f4a](https://github.com/adobe/spacecat-shared/commit/d4a3f4a653e59e9bdde7926ea8f1a2f9b68739ff))
+
+# [@adobe/spacecat-shared-tokowaka-client-v1.0.3](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.0.2...@adobe/spacecat-shared-tokowaka-client-v1.0.3) (2025-11-13)
+
+
+### Bug Fixes
+
+* add faq mapper for edge deploy API ([#1083](https://github.com/adobe/spacecat-shared/issues/1083)) ([4c7ff9d](https://github.com/adobe/spacecat-shared/commit/4c7ff9db3312e76fa8965a2d53a699528975f414))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.0.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.0.1...@adobe/spacecat-shared-tokowaka-client-v1.0.2) (2025-11-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Tokowaka Client for SpaceCat - Edge optimization config management",
   "type": "module",
   "engines": {
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "@adobe/spacecat-shared-utils": "1.66.1",
-    "@aws-sdk/client-cloudfront": "3.927.0",
-    "@aws-sdk/client-s3": "3.927.0",
+    "@aws-sdk/client-cloudfront": "3.932.0",
+    "@aws-sdk/client-s3": "3.932.0",
     "mdast-util-from-markdown": "2.0.2",
     "mdast-util-to-hast": "12.3.0"
   },

package/src/index.d.ts

@@ -21,7 +21,7 @@ export interface TokawakaPatch {
   currValue?: string;
   target: 'ai-bots' | 'bots' | 'all';
   opportunityId: string;
-  suggestionId: string;
+  suggestionId?: string;
   prerenderRequired: boolean;
   lastUpdated: number;
 }
@@ -108,12 +108,14 @@ export abstract class BaseOpportunityMapper {
   abstract requiresPrerender(): boolean;
   
   /**
-   * Converts a suggestion to a Tokowaka patch
+   * Converts suggestions to Tokowaka patches
    */
-  abstract suggestionToPatch(
-    suggestion: Suggestion,
-    opportunityId: string
-  ): TokawakaPatch | null;
+  abstract suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string,
+    existingConfig: TokowakaConfig | null
+  ): TokawakaPatch[];
   
   /**
    * Checks if a suggestion can be deployed for this opportunity type
@@ -142,7 +144,11 @@ export class HeadingsMapper extends BaseOpportunityMapper {
   
   getOpportunityType(): string;
   requiresPrerender(): boolean;
-  suggestionToPatch(suggestion: Suggestion, opportunityId: string): TokawakaPatch | null;
+  suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string
+  ): TokawakaPatch[];
   canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
 }
 
@@ -155,13 +161,36 @@ export class ContentSummarizationMapper extends BaseOpportunityMapper {
   
   getOpportunityType(): string;
   requiresPrerender(): boolean;
-  suggestionToPatch(suggestion: Suggestion, opportunityId: string): TokawakaPatch | null;
+  suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string
+  ): TokawakaPatch[];
+  canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
+}
+
+/**
+ * FAQ opportunity mapper
+ * Handles conversion of FAQ suggestions to Tokowaka patches
+ */
+export class FaqMapper extends BaseOpportunityMapper {
+  constructor(log: any);
+  
+  getOpportunityType(): string;
+  requiresPrerender(): boolean;
   canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
   
   /**
-   * Converts markdown text to HAST (Hypertext Abstract Syntax Tree) format
+   * Creates patches for FAQ suggestions
+   * First patch is heading (h2) if it doesn't exist, then individual FAQ divs
+   * @throws {Error} if suggestionToPatch is called directly
    */
-  markdownToHast(markdown: string): object;
+  suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string,
+    existingConfig: TokowakaConfig | null
+  ): TokawakaPatch[];
 }
 
 /**

package/src/index.js

@@ -11,9 +11,13 @@
  */
 
 import { GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
-import { hasText, isNonEmptyObject, isValidUrl } from '@adobe/spacecat-shared-utils';
+import { hasText, isNonEmptyObject } from '@adobe/spacecat-shared-utils';
 import MapperRegistry from './mappers/mapper-registry.js';
 import CdnClientRegistry from './cdn/cdn-client-registry.js';
+import { mergePatches } from './utils/patch-utils.js';
+import { getTokowakaConfigS3Path } from './utils/s3-utils.js';
+import { groupSuggestionsByUrlPath, filterEligibleSuggestions } from './utils/suggestion-utils.js';
+import { getEffectiveBaseURL } from './utils/site-utils.js';
 
 const HTTP_BAD_REQUEST = 400;
 const HTTP_INTERNAL_SERVER_ERROR = 500;
@@ -83,20 +87,14 @@ class TokowakaClient {
    * Generates Tokowaka site configuration from suggestions
    * @param {Object} site - Site entity
    * @param {Object} opportunity - Opportunity entity
-   * @param {Array} suggestions - Array of suggestion entities
+   * @param {Array} suggestionsToDeploy - Array of suggestion entities to deploy
    * @returns {Object} - Tokowaka configuration object
    */
-  generateConfig(site, opportunity, suggestions) {
+  generateConfig(site, opportunity, suggestionsToDeploy) {
     const opportunityType = opportunity.getType();
     const siteId = site.getId();
+    const baseURL = getEffectiveBaseURL(site);
 
-    // Get baseURL, respecting overrideBaseURL from fetchConfig if it exists
-    const overrideBaseURL = site.getConfig()?.getFetchConfig?.()?.overrideBaseURL;
-    const baseURL = (overrideBaseURL && isValidUrl(overrideBaseURL))
-      ? overrideBaseURL
-      : site.getBaseURL();
-
-    // Get mapper for this opportunity type
     const mapper = this.mapperRegistry.getMapper(opportunityType);
     if (!mapper) {
       throw this.#createError(
@@ -107,38 +105,17 @@ class TokowakaClient {
     }
 
     // Group suggestions by URL
-    const suggestionsByUrl = suggestions.reduce((acc, suggestion) => {
-      const data = suggestion.getData();
-      const url = data?.url;
-
-      if (!url) {
-        this.log.warn(`Suggestion ${suggestion.getId()} does not have a URL, skipping`);
-        return acc;
-      }
-
-      let urlPath;
-      try {
-        urlPath = new URL(url, baseURL).pathname;
-      } catch (e) {
-        this.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;
-    }, {});
+    const suggestionsByUrl = groupSuggestionsByUrlPath(suggestionsToDeploy, baseURL, this.log);
 
     // Generate patches for each URL using the mapper
     const tokowakaOptimizations = {};
 
     Object.entries(suggestionsByUrl).forEach(([urlPath, urlSuggestions]) => {
-      const patches = urlSuggestions.map((suggestion) => {
-        const patch = mapper.suggestionToPatch(suggestion, opportunity.getId());
-        return patch;
-      }).filter((patch) => patch !== null);
+      const patches = mapper.suggestionsToPatches(
+        urlPath,
+        urlSuggestions,
+        opportunity.getId(),
+      );
 
       if (patches.length > 0) {
         tokowakaOptimizations[urlPath] = {
@@ -183,7 +160,7 @@ class TokowakaClient {
       throw this.#createError('Tokowaka API key is required', HTTP_BAD_REQUEST);
     }
 
-    const s3Path = `opportunities/${siteTokowakaKey}`;
+    const s3Path = getTokowakaConfigS3Path(siteTokowakaKey);
 
     try {
       const command = new GetObjectCommand({
@@ -212,7 +189,9 @@ class TokowakaClient {
 
   /**
    * Merges existing configuration with new configuration
-   * For each URL path, checks if opportunityId+suggestionId combination exists:
+   * For each URL path, checks patch key:
+   * - Patches are identified by opportunityId+suggestionId
+   * - Heading patches (no suggestionId) are identified by opportunityId:heading
    * - If exists: updates the patch
    * - If not exists: adds new patch to the array
    * @param {Object} existingConfig - Existing configuration from S3
@@ -245,30 +224,10 @@ class TokowakaClient {
         const existingPatches = existingOptimization.patches || [];
         const newPatches = newOptimization.patches || [];
 
-        // Create a map of existing patches by opportunityId+suggestionId
-        const patchMap = new Map();
-        existingPatches.forEach((patch, index) => {
-          const key = `${patch.opportunityId}:${patch.suggestionId}`;
-          patchMap.set(key, { patch, index });
-        });
-
-        // Process new patches
-        const mergedPatches = [...existingPatches];
-        let updateCount = 0;
-        let addCount = 0;
-
-        newPatches.forEach((newPatch) => {
-          const key = `${newPatch.opportunityId}:${newPatch.suggestionId}`;
-          const existing = patchMap.get(key);
-
-          if (existing) {
-            mergedPatches[existing.index] = newPatch;
-            updateCount += 1;
-          } else {
-            mergedPatches.push(newPatch);
-            addCount += 1;
-          }
-        });
+        const { patches: mergedPatches, updateCount, addCount } = mergePatches(
+          existingPatches,
+          newPatches,
+        );
 
         mergedConfig.tokowakaOptimizations[urlPath] = {
           ...existingOptimization,
@@ -298,7 +257,7 @@ class TokowakaClient {
       throw this.#createError('Config object is required', HTTP_BAD_REQUEST);
     }
 
-    const s3Path = `opportunities/${siteTokowakaKey}`;
+    const s3Path = getTokowakaConfigS3Path(siteTokowakaKey);
 
     try {
       const command = new PutObjectCommand({
@@ -330,7 +289,7 @@ class TokowakaClient {
       throw this.#createError('Tokowaka API key and provider are required', HTTP_BAD_REQUEST);
     }
     try {
-      const pathsToInvalidate = [`/opportunities/${apiKey}`];
+      const pathsToInvalidate = [`/${getTokowakaConfigS3Path(apiKey)}`];
       this.log.debug(`Invalidating CDN cache for ${pathsToInvalidate.length} paths via ${provider}`);
       const cdnClient = this.cdnClientRegistry.getClient(provider);
       if (!cdnClient) {
@@ -353,7 +312,7 @@ class TokowakaClient {
    * Deploys suggestions to Tokowaka by generating config and uploading to S3
    * @param {Object} site - Site entity
    * @param {Object} opportunity - Opportunity entity
-   * @param {Array} suggestions - Array of suggestion entities
+   * @param {Array} suggestions - Array of suggestion entities to deploy
    * @returns {Promise<Object>} - Deployment result with succeeded/failed suggestions
    */
   async deploySuggestions(site, opportunity, suggestions) {
@@ -378,22 +337,15 @@ class TokowakaClient {
     }
 
     // Validate which suggestions can be deployed using mapper's canDeploy method
-    const eligibleSuggestions = [];
-    const ineligibleSuggestions = [];
-
-    suggestions.forEach((suggestion) => {
-      const eligibility = mapper.canDeploy(suggestion);
-      if (eligibility.eligible) {
-        eligibleSuggestions.push(suggestion);
-      } else {
-        ineligibleSuggestions.push({
-          suggestion,
-          reason: eligibility.reason || 'Suggestion cannot be deployed',
-        });
-      }
-    });
-
-    this.log.debug(`Deploying ${eligibleSuggestions.length} eligible suggestions (${ineligibleSuggestions.length} ineligible)`);
+    const {
+      eligible: eligibleSuggestions,
+      ineligible: ineligibleSuggestions,
+    } = filterEligibleSuggestions(suggestions, mapper);
+
+    this.log.debug(
+      `Deploying ${eligibleSuggestions.length} eligible suggestions `
+      + `(${ineligibleSuggestions.length} ineligible)`,
+    );
 
     if (eligibleSuggestions.length === 0) {
       this.log.warn('No eligible suggestions to deploy');
@@ -409,7 +361,11 @@ class TokowakaClient {
 
     // Generate configuration with eligible suggestions only
     this.log.debug(`Generating Tokowaka config for site ${site.getId()}, opportunity ${opportunity.getId()}`);
-    const newConfig = this.generateConfig(site, opportunity, eligibleSuggestions);
+    const newConfig = this.generateConfig(
+      site,
+      opportunity,
+      eligibleSuggestions,
+    );
 
     if (Object.keys(newConfig.tokowakaOptimizations).length === 0) {
       this.log.warn('No eligible suggestions to deploy');
@@ -419,10 +375,8 @@ class TokowakaClient {
       };
     }
 
-    // Merge with existing config if it exists
-    const config = existingConfig
-      ? this.mergeConfigs(existingConfig, newConfig)
-      : newConfig;
+    // Merge with existing config
+    const config = this.mergeConfigs(existingConfig, newConfig);
 
     // Upload to S3
     this.log.info(`Uploading Tokowaka config for ${eligibleSuggestions.length} suggestions`);

package/src/mappers/base-mapper.js

@@ -40,16 +40,17 @@ export default class BaseOpportunityMapper {
   }
 
   /**
-   * Converts a suggestion to a Tokowaka patch
+   * Converts suggestions to Tokowaka patches
    * @abstract
-   * @param {Object} _ - Suggestion entity with getId() and getData() methods
-   * @param {string} __ - Opportunity ID
-   * @returns {Object|null} - Patch object or null if conversion fails
+   * @param {string} _ - URL path for the suggestions
+   * @param {Array} __ - Array of suggestion entities for the same URL
+   * @param {string} ___ - Opportunity ID
+   * @returns {Array} - Array of Tokowaka patch objects
    */
   // eslint-disable-next-line no-unused-vars
-  suggestionToPatch(_, __) {
-    this.log.error('suggestionToPatch() must be implemented by subclass');
-    throw new Error('suggestionToPatch() must be implemented by subclass');
+  suggestionsToPatches(_, __, ___) {
+    this.log.error('suggestionsToPatches() must be implemented by subclass');
+    throw new Error('suggestionsToPatches() must be implemented by subclass');
   }
 
   /**
@@ -73,8 +74,17 @@ export default class BaseOpportunityMapper {
    * @returns {Object} - Base patch object
    */
   createBasePatch(suggestion, opportunityId) {
-    const updatedAt = suggestion.getUpdatedAt();
-    const lastUpdated = updatedAt ? new Date(updatedAt).getTime() : Date.now();
+    const data = suggestion.getData();
+    const updatedAt = data?.scrapedAt
+      || data?.transformRules?.scrapedAt
+      || suggestion.getUpdatedAt();
+
+    // Parse timestamp, fallback to Date.now() if invalid
+    let lastUpdated = Date.now();
+    if (updatedAt) {
+      const parsed = new Date(updatedAt).getTime();
+      lastUpdated = Number.isNaN(parsed) ? Date.now() : parsed;
+    }
 
     return {
       opportunityId,

package/src/mappers/content-summarization-mapper.js

@@ -10,11 +10,10 @@
  * governing permissions and limitations under the License.
  */
 
-import { toHast } from 'mdast-util-to-hast';
-import { fromMarkdown } from 'mdast-util-from-markdown';
 import { hasText } from '@adobe/spacecat-shared-utils';
 import { TARGET_USER_AGENTS_CATEGORIES } from '../constants.js';
 import BaseOpportunityMapper from './base-mapper.js';
+import { markdownToHast } from '../utils/markdown-utils.js';
 
 /**
  * Mapper for content opportunity
@@ -37,43 +36,47 @@ export default class ContentSummarizationMapper extends BaseOpportunityMapper {
   }
 
   /**
-   * Converts markdown text to HAST (Hypertext Abstract Syntax Tree) format
-   * @param {string} markdown - Markdown text
-   * @returns {Object} - HAST object
+   * 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
    */
-  // eslint-disable-next-line class-methods-use-this
-  markdownToHast(markdown) {
-    const mdast = fromMarkdown(markdown);
-    return toHast(mdast);
-  }
+  suggestionsToPatches(urlPath, suggestions, opportunityId) {
+    const patches = [];
 
-  suggestionToPatch(suggestion, opportunityId) {
-    const eligibility = this.canDeploy(suggestion);
-    if (!eligibility.eligible) {
-      this.log.warn(`Content-Summarization suggestion ${suggestion.getId()} cannot be deployed: ${eligibility.reason}`);
-      return null;
-    }
+    suggestions.forEach((suggestion) => {
+      const eligibility = this.canDeploy(suggestion);
+      if (!eligibility.eligible) {
+        this.log.warn(`Content-Summarization suggestion ${suggestion.getId()} cannot be deployed: ${eligibility.reason}`);
+        return;
+      }
 
-    const data = suggestion.getData();
-    const { summarizationText, transformRules } = data;
-
-    // Convert markdown to HAST
-    let hastValue;
-    try {
-      hastValue = this.markdownToHast(summarizationText);
-    } catch (error) {
-      this.log.error(`Failed to convert markdown to HAST for suggestion ${suggestion.getId()}: ${error.message}`);
-      return null;
-    }
+      const data = suggestion.getData();
+      const { summarizationText, transformRules } = data;
+
+      // Convert markdown to HAST
+      let hastValue;
+      try {
+        hastValue = markdownToHast(summarizationText);
+      } catch (error) {
+        this.log.error(`Failed to convert markdown to HAST for suggestion ${suggestion.getId()}: ${error.message}`);
+        return;
+      }
+
+      const patch = {
+        ...this.createBasePatch(suggestion, opportunityId),
+        op: transformRules.action,
+        selector: transformRules.selector,
+        value: hastValue,
+        valueFormat: 'hast',
+        target: TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
+      };
+
+      patches.push(patch);
+    });
 
-    return {
-      ...this.createBasePatch(suggestion, opportunityId),
-      op: transformRules.action,
-      selector: transformRules.selector,
-      value: hastValue,
-      valueFormat: 'hast',
-      target: TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
-    };
+    return patches;
   }
 
   /**

package/src/mappers/faq-mapper.js

@@ -0,0 +1,204 @@
+/*
+ * 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 } from '@adobe/spacecat-shared-utils';
+import { TARGET_USER_AGENTS_CATEGORIES } from '../constants.js';
+import BaseOpportunityMapper from './base-mapper.js';
+import { markdownToHast } from '../utils/markdown-utils.js';
+
+/**
+* Mapper for FAQ opportunity
+* Handles conversion of FAQ suggestions to Tokowaka patches
+*/
+export default class FaqMapper extends BaseOpportunityMapper {
+  constructor(log) {
+    super(log);
+    this.opportunityType = 'faq';
+    this.prerenderRequired = true;
+    this.validActions = ['insertAfter', 'insertBefore', 'appendChild'];
+  }
+
+  getOpportunityType() {
+    return this.opportunityType;
+  }
+
+  requiresPrerender() {
+    return this.prerenderRequired;
+  }
+
+  /**
+  * Builds FAQ item HTML structure (div with h3 and answer)
+  * Structure: <div><h3>question</h3>answer-content</div>
+  * @param {Object} suggestion - Suggestion entity
+  * @returns {Object} - HAST object for the FAQ item
+  * @private
+  */
+  // eslint-disable-next-line class-methods-use-this
+  buildFaqItemHast(suggestion) {
+    const data = suggestion.getData();
+    const { item } = data;
+
+    // Convert answer markdown to HAST
+    const answerHast = markdownToHast(item.answer);
+
+    // Build structure: <div><h3>question</h3>answer-hast-children</div>
+    return {
+      type: 'element',
+      tagName: 'div',
+      properties: {},
+      children: [
+        {
+          type: 'element',
+          tagName: 'h3',
+          properties: {},
+          children: [{ type: 'text', value: item.question }],
+        },
+        ...answerHast.children, // Spread answer HAST children directly
+      ],
+    };
+  }
+
+  /**
+  * Creates individual patches for FAQ suggestions
+  * Always creates heading (h2) patch with latest timestamp, then individual FAQ divs
+  * @param {string} urlPath - URL path for current suggestions
+  * @param {Array} suggestions - Array of suggestion entities for the same URL (to be deployed)
+  * @param {string} opportunityId - Opportunity ID
+  * @returns {Array} - Array of patch objects
+  */
+  suggestionsToPatches(
+    urlPath,
+    suggestions,
+    opportunityId,
+  ) {
+    if (!urlPath || !Array.isArray(suggestions) || suggestions.length === 0) {
+      this.log.error('Invalid parameters for FAQ mapper.suggestionsToPatches');
+      return [];
+    }
+
+    // Filter eligible suggestions
+    const eligibleSuggestions = suggestions.filter((suggestion) => {
+      const eligibility = this.canDeploy(suggestion);
+      if (!eligibility.eligible) {
+        this.log.warn(`FAQ suggestion ${suggestion.getId()} cannot be deployed: ${eligibility.reason}`);
+        return false;
+      }
+      return true;
+    });
+
+    if (eligibleSuggestions.length === 0) {
+      this.log.warn('No eligible FAQ suggestions to deploy');
+      return [];
+    }
+
+    const patches = [];
+
+    // Get transformRules and headingText from first suggestion
+    const firstSuggestion = eligibleSuggestions[0];
+    const firstData = firstSuggestion.getData();
+    const { headingText = 'FAQs', transformRules } = firstData;
+
+    // Calculate the most recent lastUpdated from all eligible suggestions
+    // The heading patch should have the same timestamp as the newest FAQ
+    const maxLastUpdated = Math.max(...eligibleSuggestions.map((suggestion) => {
+      const data = suggestion.getData();
+      const updatedAt = data?.scrapedAt
+        || data?.transformRules?.scrapedAt
+        || suggestion.getUpdatedAt();
+
+      if (updatedAt) {
+        const parsed = new Date(updatedAt).getTime();
+        return Number.isNaN(parsed) ? Date.now() : parsed;
+      }
+      return Date.now();
+    }));
+
+    // Always create/update heading patch with latest timestamp
+    // mergePatches will replace existing heading if it already exists
+    this.log.debug(`Creating/updating heading patch for ${urlPath}`);
+
+    const headingHast = {
+      type: 'element',
+      tagName: 'h2',
+      properties: {},
+      children: [{ type: 'text', value: headingText }],
+    };
+
+    patches.push({
+      opportunityId,
+      // No suggestionId for FAQ heading patch
+      prerenderRequired: this.requiresPrerender(),
+      lastUpdated: maxLastUpdated,
+      op: transformRules.action,
+      selector: transformRules.selector,
+      value: headingHast,
+      valueFormat: 'hast',
+      target: TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
+    });
+
+    // Create individual FAQ patches
+    eligibleSuggestions.forEach((suggestion) => {
+      try {
+        const faqItemHast = this.buildFaqItemHast(suggestion);
+
+        patches.push({
+          ...this.createBasePatch(suggestion, opportunityId),
+          op: transformRules.action,
+          selector: transformRules.selector,
+          value: faqItemHast,
+          valueFormat: 'hast',
+          target: TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
+        });
+      } catch (error) {
+        this.log.error(`Failed to build FAQ HAST for suggestion ${suggestion.getId()}: ${error.message}`);
+      }
+    });
+
+    return patches;
+  }
+
+  /**
+  * Checks if a FAQ suggestion can be deployed
+  * @param {Object} suggestion - Suggestion object
+  * @returns {Object} { eligible: boolean, reason?: string }
+  */
+  canDeploy(suggestion) {
+    const data = suggestion.getData();
+
+    // Check shouldOptimize flag first
+    if (data?.shouldOptimize !== true) {
+      return { eligible: false, reason: 'shouldOptimize flag is not true' };
+    }
+
+    if (!data?.item?.question || !data?.item?.answer) {
+      return { eligible: false, reason: 'item.question and item.answer are required' };
+    }
+
+    if (!data.transformRules) {
+      return { eligible: false, reason: 'transformRules is required' };
+    }
+
+    if (!hasText(data.transformRules.selector)) {
+      return { eligible: false, reason: 'transformRules.selector is required' };
+    }
+
+    if (!this.validActions.includes(data.transformRules.action)) {
+      return { eligible: false, reason: 'transformRules.action must be insertAfter, insertBefore, or appendChild' };
+    }
+
+    if (!isValidUrl(data.url)) {
+      return { eligible: false, reason: `url ${data.url} is not a valid URL` };
+    }
+
+    return { eligible: true };
+  }
+}