@adobe/spacecat-shared-tokowaka-client 1.0.6 → 1.1.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.1.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.0.6...@adobe/spacecat-shared-tokowaka-client-v1.1.0) (2025-11-25)
+
+
+### Features
+
+* edge rollback feature for tokowaka ([#1167](https://github.com/adobe/spacecat-shared/issues/1167)) ([b47fd05](https://github.com/adobe/spacecat-shared/commit/b47fd0518ae1fe220914bfd88810383a306775fd))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.0.6](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.0.5...@adobe/spacecat-shared-tokowaka-client-v1.0.6) (2025-11-22)
 
 

package/README.md

@@ -51,6 +51,22 @@ Generates configuration and uploads to S3. **Automatically fetches existing conf
 - `succeededSuggestions` - Array of deployed suggestions
 - `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
 
+#### `rollbackSuggestions(site, opportunity, suggestions)`
+
+Rolls back previously deployed suggestions by removing their patches from the configuration. **Automatically fetches existing configuration** and removes patches matching the provided suggestions. Invalidates CDN cache after upload.
+
+**Mapper-Specific Rollback Behavior:**
+- Each opportunity mapper handles its own rollback logic via `rollbackPatches()` method
+- **FAQ:** Automatically removes the "FAQs" heading patch if no FAQ suggestions remain for that URL
+- **Headings/Summarization:** Simple removal by suggestion ID (default behavior)
+
+**Returns:** `Promise<RollbackResult>` with:
+- `s3Path` - S3 key where config was uploaded
+- `cdnInvalidation` - CDN invalidation result (or error)
+- `succeededSuggestions` - Array of rolled back suggestions
+- `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
+- `removedPatchesCount` - Number of patches removed from the configuration
+
 #### `fetchConfig(apiKey)`
 
 Fetches existing Tokowaka configuration from S3.
@@ -94,7 +110,6 @@ s3://{TOKOWAKA_SITE_CONFIG_BUCKET}/opportunities/{tokowakaApiKey}
 
 **Note:** The configuration is stored as a JSON file containing the complete Tokowaka optimization config for the site.
 
-
 ## Reference Material
 
 https://wiki.corp.adobe.com/display/AEMSites/Tokowaka+-+Spacecat+Integration

package/package.json

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

package/src/index.js

@@ -407,6 +407,112 @@ class TokowakaClient {
     };
   }
 
+  /**
+   * Rolls back deployed suggestions by removing their patches from the configuration
+   * @param {Object} site - Site entity
+   * @param {Object} opportunity - Opportunity entity
+   * @param {Array} suggestions - Array of suggestion entities to rollback
+   * @returns {Promise<Object>} - Rollback result with succeeded/failed suggestions
+   */
+  async rollbackSuggestions(site, opportunity, suggestions) {
+    // Get site's Tokowaka API key
+    const { apiKey } = site.getConfig()?.getTokowakaConfig() || {};
+
+    if (!hasText(apiKey)) {
+      throw this.#createError(
+        'Site does not have a Tokowaka API key configured. Please onboard the site to Tokowaka first.',
+        HTTP_BAD_REQUEST,
+      );
+    }
+
+    const opportunityType = opportunity.getType();
+    const mapper = this.mapperRegistry.getMapper(opportunityType);
+    if (!mapper) {
+      throw this.#createError(
+        `No mapper found for opportunity type: ${opportunityType}. `
+        + `Supported types: ${this.mapperRegistry.getSupportedOpportunityTypes().join(', ')}`,
+        HTTP_NOT_IMPLEMENTED,
+      );
+    }
+
+    // Validate which suggestions can be rolled back
+    // For rollback, we use the same canDeploy check to ensure data integrity
+    const {
+      eligible: eligibleSuggestions,
+      ineligible: ineligibleSuggestions,
+    } = filterEligibleSuggestions(suggestions, mapper);
+
+    this.log.debug(
+      `Rolling back ${eligibleSuggestions.length} eligible suggestions `
+      + `(${ineligibleSuggestions.length} ineligible)`,
+    );
+
+    if (eligibleSuggestions.length === 0) {
+      this.log.warn('No eligible suggestions to rollback');
+      return {
+        succeededSuggestions: [],
+        failedSuggestions: ineligibleSuggestions,
+      };
+    }
+
+    // Fetch existing configuration from S3
+    this.log.debug(`Fetching existing Tokowaka config for site ${site.getId()}`);
+    const existingConfig = await this.fetchConfig(apiKey);
+
+    if (!existingConfig || !existingConfig.tokowakaOptimizations) {
+      this.log.warn('No existing configuration found to rollback from');
+      return {
+        succeededSuggestions: [],
+        failedSuggestions: eligibleSuggestions.map((suggestion) => ({
+          suggestion,
+          reason: 'No existing configuration found',
+        })),
+      };
+    }
+
+    // Extract suggestion IDs to remove
+    const suggestionIdsToRemove = eligibleSuggestions.map((s) => s.getId());
+    const updatedConfig = mapper.rollbackPatches(
+      existingConfig,
+      suggestionIdsToRemove,
+      opportunity.getId(),
+    );
+
+    if (updatedConfig.removedCount === 0) {
+      this.log.warn('No patches found matching the provided suggestion IDs');
+      return {
+        succeededSuggestions: [],
+        failedSuggestions: eligibleSuggestions.map((suggestion) => ({
+          suggestion,
+          reason: 'No patches found for this suggestion in the current configuration',
+        })),
+      };
+    }
+
+    this.log.info(`Removed ${updatedConfig.removedCount} patches from configuration`);
+
+    // Remove the removedCount property before uploading
+    const { removedCount, ...configToUpload } = updatedConfig;
+
+    // Upload updated config to S3
+    this.log.info(`Uploading updated Tokowaka config after rolling back ${eligibleSuggestions.length} suggestions`);
+    const s3Path = await this.uploadConfig(apiKey, configToUpload);
+
+    // Invalidate CDN cache (non-blocking, failures are logged but don't fail rollback)
+    const cdnInvalidationResult = await this.invalidateCdnCache(
+      apiKey,
+      this.env.TOKOWAKA_CDN_PROVIDER,
+    );
+
+    return {
+      s3Path,
+      cdnInvalidation: cdnInvalidationResult,
+      succeededSuggestions: eligibleSuggestions,
+      failedSuggestions: ineligibleSuggestions,
+      removedPatchesCount: removedCount,
+    };
+  }
+
   /**
    * Previews suggestions by generating config and uploading to preview path
    * Unlike deploySuggestions, this does NOT merge with existing config

package/src/mappers/base-mapper.js

@@ -10,6 +10,8 @@
  * governing permissions and limitations under the License.
  */
 
+import { removePatchesBySuggestionIds } from '../utils/patch-utils.js';
+
 /**
  * Base class for opportunity mappers
  * Each opportunity type should extend this class and implement the abstract methods
@@ -93,4 +95,24 @@ export default class BaseOpportunityMapper {
       lastUpdated,
     };
   }
+
+  /**
+   * Removes patches from configuration for given suggestions
+   * Default implementation simply removes patches matching the suggestion IDs.
+   * Override this method in subclasses if custom rollback logic is needed
+   * (e.g., FAQ mapper removes heading patch when no suggestions remain).
+   * @param {Object} config - Current Tokowaka configuration
+   * @param {Array<string>} suggestionIds - Suggestion IDs to remove
+   * @param {string} opportunityId - Opportunity ID
+   * @returns {Object} - Updated configuration with patches removed
+   */
+  // eslint-disable-next-line no-unused-vars
+  rollbackPatches(config, suggestionIds, opportunityId) {
+    if (!config || !config.tokowakaOptimizations) {
+      return config;
+    }
+
+    this.log.debug(`Removing patches for ${suggestionIds.length} suggestions`);
+    return removePatchesBySuggestionIds(config, suggestionIds);
+  }
 }

package/src/mappers/faq-mapper.js

@@ -14,6 +14,7 @@ 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';
+import { removePatchesBySuggestionIds } from '../utils/patch-utils.js';
 
 /**
 * Mapper for FAQ opportunity
@@ -201,4 +202,51 @@ export default class FaqMapper extends BaseOpportunityMapper {
 
     return { eligible: true };
   }
+
+  /**
+   * Removes patches from configuration for FAQ suggestions
+   * FAQ-specific logic: Also removes the heading patch when no FAQ suggestions remain for a URL
+   * @param {Object} config - Current Tokowaka configuration
+   * @param {Array<string>} suggestionIds - Suggestion IDs to remove
+   * @param {string} opportunityId - Opportunity ID
+   * @returns {Object} - Updated configuration with patches removed
+   */
+  rollbackPatches(config, suggestionIds, opportunityId) {
+    if (!config || !config.tokowakaOptimizations) {
+      return config;
+    }
+
+    const suggestionIdsSet = new Set(suggestionIds);
+    const additionalPatchKeys = [];
+
+    // Analyze each URL to determine if FAQ heading patch should be removed
+    Object.entries(config.tokowakaOptimizations).forEach(([urlPath, optimization]) => {
+      const { patches = [] } = optimization;
+
+      // Find FAQ patches for this opportunity
+      const opportunityPatches = patches.filter((p) => p.opportunityId === opportunityId);
+
+      // Get FAQ suggestion IDs that will remain after rollback (for this URL)
+      const remainingSuggestionIds = opportunityPatches
+        .filter((p) => p.suggestionId && !suggestionIdsSet.has(p.suggestionId))
+        .map((p) => p.suggestionId);
+
+      // If no FAQ suggestions remain for this URL, remove the heading patch too
+      if (remainingSuggestionIds.length === 0) {
+        this.log.debug(`No remaining FAQ suggestions for ${urlPath}, marking heading patch for removal`);
+        // Add heading patch key (opportunityId only, no suggestionId)
+        additionalPatchKeys.push(`${urlPath}:${opportunityId}`);
+      } else {
+        this.log.debug(`${remainingSuggestionIds.length} FAQ suggestions remain for ${urlPath}, keeping heading patch`);
+      }
+    });
+
+    // Remove FAQ suggestion patches and any orphaned heading patches
+    this.log.debug(
+      `Removing ${suggestionIds.length} FAQ suggestion patches `
+      + `and ${additionalPatchKeys.length} heading patches`,
+    );
+
+    return removePatchesBySuggestionIds(config, suggestionIds, additionalPatchKeys);
+  }
 }

package/src/utils/patch-utils.js

@@ -17,7 +17,7 @@
  * Patches with no suggestionId:
  *    → Key: opportunityId
  */
-function getPatchKey(patch) {
+export function getPatchKey(patch) {
   // Heading patch (no suggestionId): use special key
   if (!patch.suggestionId) {
     return `${patch.opportunityId}`;
@@ -64,3 +64,53 @@ export function mergePatches(existingPatches, newPatches) {
 
   return { patches: mergedPatches, updateCount, addCount };
 }
+
+/**
+ * Removes patches matching the given suggestion IDs from a config
+ * @param {Object} config - Tokowaka configuration object
+ * @param {Array<string>} suggestionIds - Array of suggestion IDs to remove
+ * @param {Array<string>} additionalPatchKeys - Optional array of additional patch keys to remove
+ * @returns {Object} - Updated configuration with patches removed
+ */
+export function removePatchesBySuggestionIds(config, suggestionIds, additionalPatchKeys = []) {
+  if (!config || !config.tokowakaOptimizations) {
+    return config;
+  }
+
+  const suggestionIdSet = new Set(suggestionIds);
+  const patchKeysToRemove = new Set(additionalPatchKeys);
+  const updatedOptimizations = {};
+  let removedCount = 0;
+
+  // Iterate through each URL path and filter out patches matching suggestionIds or patch keys
+  Object.entries(config.tokowakaOptimizations).forEach(([urlPath, optimization]) => {
+    const { patches = [] } = optimization;
+
+    // Filter out patches with matching suggestionIds or patch keys
+    const filteredPatches = patches.filter((patch) => {
+      const shouldRemoveBySuggestionId = suggestionIdSet.has(patch.suggestionId);
+      const patchKey = `${urlPath}:${getPatchKey(patch)}`;
+      const shouldRemoveByPatchKey = patchKeysToRemove.has(patchKey);
+
+      if (shouldRemoveBySuggestionId || shouldRemoveByPatchKey) {
+        removedCount += 1;
+        return false;
+      }
+      return true;
+    });
+
+    // Only keep URL paths that still have patches
+    if (filteredPatches.length > 0) {
+      updatedOptimizations[urlPath] = {
+        ...optimization,
+        patches: filteredPatches,
+      };
+    }
+  });
+
+  return {
+    ...config,
+    tokowakaOptimizations: updatedOptimizations,
+    removedCount,
+  };
+}