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

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.0.5](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.0.4...@adobe/spacecat-shared-tokowaka-client-v1.0.5) (2025-11-21)
+
+
+### Bug Fixes
+
+* edge preview feature for Tokowaka ([#1124](https://github.com/adobe/spacecat-shared/issues/1124)) ([cd2a06f](https://github.com/adobe/spacecat-shared/commit/cd2a06f62e3ca9e8c2b87e1810d420a06a002526))
+
 # [@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)
 
 

package/package.json

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

package/src/index.js

@@ -18,6 +18,7 @@ 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';
+import { fetchHtmlWithWarmup } from './utils/custom-html-utils.js';
 
 const HTTP_BAD_REQUEST = 400;
 const HTTP_INTERNAL_SERVER_ERROR = 500;
@@ -34,7 +35,10 @@ class TokowakaClient {
    */
   static createFrom(context) {
     const { env, log = console, s3 } = context;
-    const { TOKOWAKA_SITE_CONFIG_BUCKET: bucketName } = env;
+    const {
+      TOKOWAKA_SITE_CONFIG_BUCKET: bucketName,
+      TOKOWAKA_PREVIEW_BUCKET: previewBucketName,
+    } = env;
 
     if (context.tokowakaClient) {
       return context.tokowakaClient;
@@ -43,6 +47,7 @@ class TokowakaClient {
     // s3ClientWrapper puts s3Client at context.s3.s3Client, so check both locations
     const client = new TokowakaClient({
       bucketName,
+      previewBucketName,
       s3Client: s3?.s3Client,
       env,
     }, log);
@@ -54,11 +59,14 @@ class TokowakaClient {
    * Constructor
    * @param {Object} config - Configuration object
    * @param {string} config.bucketName - S3 bucket name for configs
+   * @param {string} config.previewBucketName - S3 bucket name for preview configs
    * @param {Object} config.s3Client - AWS S3 client
    * @param {Object} config.env - Environment variables (for CDN credentials)
    * @param {Object} log - Logger instance
    */
-  constructor({ bucketName, s3Client, env = {} }, log) {
+  constructor({
+    bucketName, previewBucketName, s3Client, env = {},
+  }, log) {
     this.log = log;
 
     if (!hasText(bucketName)) {
@@ -69,7 +77,8 @@ class TokowakaClient {
       throw this.#createError('S3 client is required', HTTP_BAD_REQUEST);
     }
 
-    this.bucketName = bucketName;
+    this.deployBucketName = bucketName;
+    this.previewBucketName = previewBucketName;
     this.s3Client = s3Client;
     this.env = env;
 
@@ -164,7 +173,7 @@ class TokowakaClient {
 
     try {
       const command = new GetObjectCommand({
-        Bucket: this.bucketName,
+        Bucket: this.deployBucketName,
         Key: s3Path,
       });
 
@@ -172,12 +181,12 @@ class TokowakaClient {
       const bodyContents = await response.Body.transformToString();
       const config = JSON.parse(bodyContents);
 
-      this.log.debug(`Successfully fetched existing Tokowaka config from s3://${this.bucketName}/${s3Path}`);
+      this.log.debug(`Successfully fetched existing Tokowaka config from s3://${this.deployBucketName}/${s3Path}`);
       return config;
     } catch (error) {
       // If config doesn't exist (NoSuchKey), return null
       if (error.name === 'NoSuchKey' || error.Code === 'NoSuchKey') {
-        this.log.debug(`No existing Tokowaka config found at s3://${this.bucketName}/${s3Path}`);
+        this.log.debug(`No existing Tokowaka config found at s3://${this.deployBucketName}/${s3Path}`);
         return null;
       }
 
@@ -246,9 +255,10 @@ class TokowakaClient {
    * Uploads Tokowaka configuration to S3
    * @param {string} siteTokowakaKey - Tokowaka API key (used as S3 key prefix)
    * @param {Object} config - Tokowaka configuration object
+   * @param {boolean} isPreview - Whether to upload to preview path (default: false)
    * @returns {Promise<string>} - S3 key of uploaded config
    */
-  async uploadConfig(siteTokowakaKey, config) {
+  async uploadConfig(siteTokowakaKey, config, isPreview = false) {
     if (!hasText(siteTokowakaKey)) {
       throw this.#createError('Tokowaka API key is required', HTTP_BAD_REQUEST);
     }
@@ -257,18 +267,18 @@ class TokowakaClient {
       throw this.#createError('Config object is required', HTTP_BAD_REQUEST);
     }
 
-    const s3Path = getTokowakaConfigS3Path(siteTokowakaKey);
+    const s3Path = getTokowakaConfigS3Path(siteTokowakaKey, isPreview);
 
     try {
       const command = new PutObjectCommand({
-        Bucket: this.bucketName,
+        Bucket: isPreview ? this.previewBucketName : this.deployBucketName,
         Key: s3Path,
         Body: JSON.stringify(config, null, 2),
         ContentType: 'application/json',
       });
 
       await this.s3Client.send(command);
-      this.log.info(`Successfully uploaded Tokowaka config to s3://${this.bucketName}/${s3Path}`);
+      this.log.info(`Successfully uploaded Tokowaka config to s3://${this.deployBucketName}/${s3Path}`);
 
       return s3Path;
     } catch (error) {
@@ -282,14 +292,15 @@ class TokowakaClient {
    * Currently supports CloudFront only
    * @param {string} apiKey - Tokowaka API key
    * @param {string} provider - CDN provider name (default: 'cloudfront')
+   * @param {boolean} isPreview - Whether to invalidate preview path (default: false)
    * @returns {Promise<Object|null>} - CDN invalidation result or null if skipped
    */
-  async invalidateCdnCache(apiKey, provider) {
+  async invalidateCdnCache(apiKey, provider, isPreview = false) {
     if (!hasText(apiKey) || !hasText(provider)) {
       throw this.#createError('Tokowaka API key and provider are required', HTTP_BAD_REQUEST);
     }
     try {
-      const pathsToInvalidate = [`/${getTokowakaConfigS3Path(apiKey)}`];
+      const pathsToInvalidate = [`/${getTokowakaConfigS3Path(apiKey, isPreview)}`];
       this.log.debug(`Invalidating CDN cache for ${pathsToInvalidate.length} paths via ${provider}`);
       const cdnClient = this.cdnClientRegistry.getClient(provider);
       if (!cdnClient) {
@@ -395,6 +406,185 @@ class TokowakaClient {
       failedSuggestions: ineligibleSuggestions,
     };
   }
+
+  /**
+   * Previews suggestions by generating config and uploading to preview path
+   * Unlike deploySuggestions, this does NOT merge with existing config
+   * @param {Object} site - Site entity
+   * @param {Object} opportunity - Opportunity entity
+   * @param {Array} suggestions - Array of suggestion entities to preview
+   * @param {Object} options - Optional configuration for HTML fetching
+   * @returns {Promise<Object>} - Preview result with config and succeeded/failed suggestions
+   */
+  async previewSuggestions(site, opportunity, suggestions, options = {}) {
+    // Get site's Tokowaka API key
+    const { apiKey, forwardedHost } = site.getConfig()?.getTokowakaConfig() || {};
+
+    if (!hasText(apiKey) || !hasText(forwardedHost)) {
+      throw this.#createError(
+        'Site does not have a Tokowaka API key or forwarded host 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,
+      );
+    }
+
+    // TOKOWAKA_EDGE_URL is mandatory for preview
+    const tokowakaEdgeUrl = this.env.TOKOWAKA_EDGE_URL;
+    if (!hasText(tokowakaEdgeUrl)) {
+      throw this.#createError(
+        'TOKOWAKA_EDGE_URL is required for preview functionality',
+        HTTP_INTERNAL_SERVER_ERROR,
+      );
+    }
+
+    // Validate which suggestions can be deployed using mapper's canDeploy method
+    const {
+      eligible: eligibleSuggestions,
+      ineligible: ineligibleSuggestions,
+    } = filterEligibleSuggestions(suggestions, mapper);
+
+    this.log.debug(
+      `Previewing ${eligibleSuggestions.length} eligible suggestions `
+      + `(${ineligibleSuggestions.length} ineligible)`,
+    );
+
+    if (eligibleSuggestions.length === 0) {
+      this.log.warn('No eligible suggestions to preview');
+      return {
+        config: null,
+        succeededSuggestions: [],
+        failedSuggestions: ineligibleSuggestions,
+      };
+    }
+
+    // Fetch existing deployed configuration from production S3
+    this.log.debug(`Fetching existing deployed Tokowaka config for site ${site.getId()}`);
+    const existingConfig = await this.fetchConfig(apiKey, false);
+
+    // Generate configuration with eligible preview suggestions
+    this.log.debug(`Generating preview Tokowaka config for site ${site.getId()}, opportunity ${opportunity.getId()}`);
+    const newConfig = this.generateConfig(
+      site,
+      opportunity,
+      eligibleSuggestions,
+    );
+
+    if (Object.keys(newConfig.tokowakaOptimizations).length === 0) {
+      this.log.warn('No eligible suggestions to preview');
+      return {
+        config: null,
+        succeededSuggestions: [],
+        failedSuggestions: suggestions,
+      };
+    }
+
+    // Get the preview URL from the first suggestion
+    const previewUrl = eligibleSuggestions[0].getData()?.url;
+
+    // Merge with existing deployed config to include already-deployed patches for this URL
+    let config = newConfig;
+    if (existingConfig && previewUrl) {
+      // Extract the URL path from the preview URL
+      const urlPath = new URL(previewUrl).pathname;
+
+      // Check if there are already deployed patches for this URL
+      const existingUrlOptimization = existingConfig.tokowakaOptimizations?.[urlPath];
+
+      if (existingUrlOptimization && existingUrlOptimization.patches?.length > 0) {
+        this.log.info(
+          `Found ${existingUrlOptimization.patches.length} deployed patches for ${urlPath}, `
+          + 'merging with preview suggestions',
+        );
+
+        // Create a filtered existing config with only the URL being previewed
+        const filteredExistingConfig = {
+          ...existingConfig,
+          tokowakaOptimizations: {
+            [urlPath]: existingUrlOptimization,
+          },
+        };
+
+        // Merge the existing deployed patches with new preview suggestions
+        config = this.mergeConfigs(filteredExistingConfig, newConfig);
+
+        this.log.debug(
+          `Preview config now has ${config.tokowakaOptimizations[urlPath].patches.length} total patches`,
+        );
+      } else {
+        this.log.info(`No deployed patches found for ${urlPath}, using only preview suggestions`);
+      }
+    }
+
+    // Upload to preview S3 path (replaces any existing preview config)
+    this.log.info(`Uploading preview Tokowaka config with ${eligibleSuggestions.length} new suggestions`);
+    const s3Path = await this.uploadConfig(apiKey, config, true);
+
+    // Invalidate CDN cache for preview path
+    const cdnInvalidationResult = await this.invalidateCdnCache(
+      apiKey,
+      this.env.TOKOWAKA_CDN_PROVIDER,
+      true,
+    );
+
+    // Fetch HTML content for preview
+    let originalHtml = null;
+    let optimizedHtml = null;
+
+    if (previewUrl) {
+      try {
+        // Fetch original HTML
+        originalHtml = await fetchHtmlWithWarmup(
+          previewUrl,
+          apiKey,
+          forwardedHost,
+          tokowakaEdgeUrl,
+          this.log,
+          false,
+          options,
+        );
+        // Then fetch optimized HTML
+        optimizedHtml = await fetchHtmlWithWarmup(
+          previewUrl,
+          apiKey,
+          forwardedHost,
+          tokowakaEdgeUrl,
+          this.log,
+          true,
+          options,
+        );
+        this.log.info('Successfully fetched both original and optimized HTML for preview');
+      } catch (error) {
+        this.log.error(`Failed to fetch HTML for preview: ${error.message}`);
+        throw this.#createError(
+          `Preview failed: Unable to fetch HTML - ${error.message}`,
+          HTTP_INTERNAL_SERVER_ERROR,
+        );
+      }
+    }
+
+    return {
+      s3Path,
+      config,
+      cdnInvalidation: cdnInvalidationResult,
+      succeededSuggestions: eligibleSuggestions,
+      failedSuggestions: ineligibleSuggestions,
+      html: {
+        url: previewUrl,
+        originalHtml,
+        optimizedHtml,
+      },
+    };
+  }
 }
 
 // Export the client as default and base classes for custom implementations

package/src/utils/custom-html-utils.js

@@ -0,0 +1,194 @@
+/*
+ * 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';
+
+/**
+ * Helper function to wait for a specified duration
+ * @param {number} ms - Milliseconds to wait
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Makes an HTTP request with retry logic
+ * Retries until max retries are exhausted or x-tokowaka-cache header is present
+ * @param {string} url - URL to fetch
+ * @param {Object} options - Fetch options
+ * @param {number} maxRetries - Maximum number of retries
+ * @param {number} retryDelayMs - Delay between retries in milliseconds
+ * @param {Object} log - Logger instance
+ * @param {string} fetchType - Context for logging (e.g., "optimized" or "original")
+ * @returns {Promise<Response>} - Fetch response
+ */
+async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetchType) {
+  for (let attempt = 1; attempt <= maxRetries + 1; attempt += 1) {
+    try {
+      log.debug(`Retry attempt ${attempt}/${maxRetries} for ${fetchType} HTML`);
+
+      // eslint-disable-next-line no-await-in-loop
+      const response = await fetch(url, options);
+
+      log.debug(`Response status (attempt ${attempt}): ${response.status} ${response.statusText}`);
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      // Check for x-tokowaka-cache header - if present, stop retrying
+      const cacheHeader = response.headers.get('x-tokowaka-cache');
+      if (cacheHeader) {
+        log.debug(`Cache header found (x-tokowaka-cache: ${cacheHeader}), stopping retry logic`);
+        return response;
+      }
+
+      // If no cache header and we haven't exhausted retries, continue
+      if (attempt < maxRetries + 1) {
+        log.debug(`No cache header found on attempt ${attempt}, will retry...`);
+        // Wait before retrying
+        log.debug(`Waiting ${retryDelayMs}ms before retry...`);
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(retryDelayMs);
+      } else {
+        // Last attempt without cache header - throw error
+        log.error(`Max retries (${maxRetries}) exhausted without cache header`);
+        throw new Error(`Cache header (x-tokowaka-cache) not found after ${maxRetries} retries`);
+      }
+    } catch (error) {
+      log.warn(`Attempt ${attempt} failed for ${fetchType} HTML, error: ${error.message}`);
+
+      // If this was the last attempt, throw the error
+      if (attempt === maxRetries + 1) {
+        throw error;
+      }
+
+      // Wait before retrying
+      log.debug(`Waiting ${retryDelayMs}ms before retry...`);
+      // eslint-disable-next-line no-await-in-loop
+      await sleep(retryDelayMs);
+    }
+  }
+  throw new Error(`Failed to fetch ${fetchType} HTML after ${maxRetries} retries`);
+}
+
+/**
+ * Fetches HTML content from Tokowaka edge with warmup call and retry logic
+ * Makes an initial warmup call, waits, then makes the actual call with retries
+ * @param {string} url - Full URL to fetch
+ * @param {string} apiKey - Tokowaka API key
+ * @param {string} forwardedHost - Host to forward in x-forwarded-host header
+ * @param {string} tokowakaEdgeUrl - Tokowaka edge URL
+ * @param {boolean} isOptimized - Whether to fetch optimized HTML (with preview param)
+ * @param {Object} log - Logger instance
+ * @param {Object} options - Additional options
+ * @param {number} options.warmupDelayMs - Delay after warmup call (default: 2000ms)
+ * @param {number} options.maxRetries - Maximum number of retries for actual call (default: 2)
+ * @param {number} options.retryDelayMs - Delay between retries (default: 1000ms)
+ * @returns {Promise<string>} - HTML content
+ * @throws {Error} - If validation fails or fetch fails after retries
+ */
+export async function fetchHtmlWithWarmup(
+  url,
+  apiKey,
+  forwardedHost,
+  tokowakaEdgeUrl,
+  log,
+  isOptimized = false,
+  options = {},
+) {
+  // Validate required parameters
+  if (!hasText(url)) {
+    throw new Error('URL is required for fetching HTML');
+  }
+
+  if (!hasText(apiKey)) {
+    throw new Error('Tokowaka API key is required for fetching HTML');
+  }
+
+  if (!hasText(forwardedHost)) {
+    throw new Error('Forwarded host is required for fetching HTML');
+  }
+
+  if (!hasText(tokowakaEdgeUrl)) {
+    throw new Error('TOKOWAKA_EDGE_URL is not configured');
+  }
+
+  // Default options
+  const {
+    warmupDelayMs = 2000,
+    maxRetries = 3,
+    retryDelayMs = 1000,
+  } = options;
+
+  const fetchType = isOptimized ? 'optimized' : 'original';
+
+  // Parse the URL to extract path and construct full URL
+  const urlObj = new URL(url);
+  const urlPath = urlObj.pathname + urlObj.search;
+
+  // Add tokowakaPreview param for optimized HTML
+  let fullUrl = `${tokowakaEdgeUrl}${urlPath}`;
+  if (isOptimized) {
+    const separator = urlPath.includes('?') ? '&' : '?';
+    fullUrl = `${fullUrl}${separator}tokowakaPreview=true`;
+  }
+
+  const headers = {
+    'x-forwarded-host': forwardedHost,
+    'x-tokowaka-api-key': apiKey,
+    'x-tokowaka-url': urlPath,
+  };
+
+  const fetchOptions = {
+    method: 'GET',
+    headers,
+  };
+
+  try {
+    // Warmup call (no retry logic for warmup)
+    log.debug(`Making warmup call for ${fetchType} HTML with URL: ${fullUrl}`);
+
+    const warmupResponse = await fetch(fullUrl, fetchOptions);
+
+    log.debug(`Warmup response status: ${warmupResponse.status} ${warmupResponse.statusText}`);
+    // Consume the response body to free up the connection
+    await warmupResponse.text();
+    log.debug(`Warmup call completed, waiting ${warmupDelayMs}ms...`);
+
+    // Wait before actual call
+    await sleep(warmupDelayMs);
+
+    // Actual call with retry logic
+    log.debug(`Making actual call for ${fetchType} HTML (max ${maxRetries} retries) with URL: ${fullUrl}`);
+
+    const response = await fetchWithRetry(
+      fullUrl,
+      fetchOptions,
+      maxRetries,
+      retryDelayMs,
+      log,
+      fetchType,
+    );
+
+    const html = await response.text();
+    log.debug(`Successfully fetched ${fetchType} HTML (${html.length} bytes)`);
+    return html;
+  } catch (error) {
+    const errorMsg = `Failed to fetch ${fetchType} HTML after ${maxRetries} retries: ${error.message}`;
+    log.error(errorMsg);
+    throw new Error(errorMsg);
+  }
+}

package/src/utils/s3-utils.js

@@ -13,8 +13,12 @@
 /**
  * Generates S3 path for Tokowaka configuration
  * @param {string} apiKey - Tokowaka API key
+ * @param {boolean} isPreview - Whether this is a preview path
  * @returns {string} - S3 path
  */
-export function getTokowakaConfigS3Path(apiKey) {
+export function getTokowakaConfigS3Path(apiKey, isPreview = false) {
+  if (isPreview) {
+    return `preview/opportunities/${apiKey}`;
+  }
   return `opportunities/${apiKey}`;
 }