@adobe/spacecat-shared-tokowaka-client 1.7.4 → 1.7.6

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.7.6](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.7.5...@adobe/spacecat-shared-tokowaka-client-v1.7.6) (2026-02-09)
+
+
+### Bug Fixes
+
+* edge-preview api: ignore warmup call failure ([#1327](https://github.com/adobe/spacecat-shared/issues/1327)) ([fbc9f65](https://github.com/adobe/spacecat-shared/commit/fbc9f65bf96e408c878fa3b8b37fbbe29444e08f))
+
+# [@adobe/spacecat-shared-tokowaka-client-v1.7.5](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.7.4...@adobe/spacecat-shared-tokowaka-client-v1.7.5) (2026-02-05)
+
+
+### Bug Fixes
+
+* optimize edge-preview API ([#1319](https://github.com/adobe/spacecat-shared/issues/1319)) ([7f13b66](https://github.com/adobe/spacecat-shared/commit/7f13b666bd234a246a530e0f387feac143792b36))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.7.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.7.3...@adobe/spacecat-shared-tokowaka-client-v1.7.4) (2026-02-05)
 
 

package/package.json

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

package/src/index.js

@@ -238,6 +238,7 @@ class TokowakaClient {
       throw this.#createError('URL is required', HTTP_BAD_REQUEST);
     }
 
+    const fetchStartTime = Date.now();
     const s3Path = getTokowakaMetaconfigS3Path(url, this.log);
     const bucketName = this.deployBucketName;
 
@@ -251,7 +252,7 @@ class TokowakaClient {
       const bodyContents = await response.Body.transformToString();
       const metaconfig = JSON.parse(bodyContents);
 
-      this.log.debug(`Successfully fetched metaconfig from s3://${bucketName}/${s3Path}`);
+      this.log.debug(`Successfully fetched metaconfig from s3://${bucketName}/${s3Path} in ${Date.now() - fetchStartTime}ms`);
       return metaconfig;
     } catch (error) {
       // If metaconfig doesn't exist (NoSuchKey), return null
@@ -392,6 +393,7 @@ class TokowakaClient {
       throw this.#createError('Metaconfig object is required', HTTP_BAD_REQUEST);
     }
 
+    const uploadStartTime = Date.now();
     const s3Path = getTokowakaMetaconfigS3Path(url, this.log);
     const bucketName = this.deployBucketName;
 
@@ -411,7 +413,7 @@ class TokowakaClient {
       const command = new PutObjectCommand(putObjectParams);
 
       await this.s3Client.send(command);
-      this.log.info(`Successfully uploaded metaconfig to s3://${bucketName}/${s3Path}`);
+      this.log.info(`Successfully uploaded metaconfig to s3://${bucketName}/${s3Path} in ${Date.now() - uploadStartTime}ms`);
 
       // Invalidate CDN cache for the metaconfig (both CloudFront and Fastly)
       this.log.info('Invalidating CDN cache for uploaded metaconfig');
@@ -435,6 +437,7 @@ class TokowakaClient {
       throw this.#createError('URL is required', HTTP_BAD_REQUEST);
     }
 
+    const fetchStartTime = Date.now();
     const s3Path = getTokowakaConfigS3Path(url, this.log, isPreview);
     const bucketName = isPreview ? this.previewBucketName : this.deployBucketName;
 
@@ -448,7 +451,7 @@ class TokowakaClient {
       const bodyContents = await response.Body.transformToString();
       const config = JSON.parse(bodyContents);
 
-      this.log.debug(`Successfully fetched existing Tokowaka config from s3://${bucketName}/${s3Path}`);
+      this.log.debug(`Successfully fetched existing Tokowaka config from s3://${bucketName}/${s3Path} in ${Date.now() - fetchStartTime}ms`);
       return config;
     } catch (error) {
       // If config doesn't exist (NoSuchKey), return null
@@ -514,6 +517,7 @@ class TokowakaClient {
     if (!isNonEmptyObject(config)) {
       throw this.#createError('Config object is required', HTTP_BAD_REQUEST);
     }
+    const uploadStartTime = Date.now();
 
     const s3Path = getTokowakaConfigS3Path(url, this.log, isPreview);
     const bucketName = isPreview ? this.previewBucketName : this.deployBucketName;
@@ -527,7 +531,7 @@ class TokowakaClient {
       });
 
       await this.s3Client.send(command);
-      this.log.info(`Successfully uploaded Tokowaka config to s3://${bucketName}/${s3Path}`);
+      this.log.info(`Successfully uploaded Tokowaka config to s3://${bucketName}/${s3Path} in ${Date.now() - uploadStartTime}ms`);
 
       return s3Path;
     } catch (error) {
@@ -553,6 +557,7 @@ class TokowakaClient {
     providers = this.#getCdnProviders(),
     isPreview = false,
   }) {
+    const invalidationStartTime = Date.now();
     // Convert single provider to array for uniform handling
     const providerList = Array.isArray(providers) ? providers : [providers].filter(Boolean);
 
@@ -596,11 +601,12 @@ class TokowakaClient {
           continue;
         }
 
+        const startTime = Date.now();
         // eslint-disable-next-line no-await-in-loop
         const result = await cdnClient.invalidateCache(pathsToInvalidate);
         this.log.info(
           `CDN cache invalidation completed for ${provider}: `
-          + `${pathsToInvalidate.length} path(s)`,
+          + `${pathsToInvalidate.length} path(s), and took ${Date.now() - startTime}ms`,
         );
         results.push(result);
       } catch (error) {
@@ -612,6 +618,7 @@ class TokowakaClient {
         });
       }
     }
+    this.log.info(`CDN cache invalidation completed in total ${Date.now() - invalidationStartTime}ms`);
     return results;
   }
 
@@ -866,8 +873,10 @@ class TokowakaClient {
    * @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 = {}) {
+  async previewSuggestions(site, opportunity, suggestions = [], options = {}) {
     const opportunityType = opportunity.getType();
+    this.log.info(`Previewing ${suggestions.length} suggestions for `
+       + `${opportunityType} opportunity and URL ${site.getBaseURL()}`);
     const mapper = this.mapperRegistry.getMapper(opportunityType);
     if (!mapper) {
       throw this.#createError(
@@ -892,7 +901,7 @@ class TokowakaClient {
       ineligible: ineligibleSuggestions,
     } = filterEligibleSuggestions(suggestions, mapper);
 
-    this.log.debug(
+    this.log.info(
       `Previewing ${eligibleSuggestions.length} eligible suggestions `
       + `(${ineligibleSuggestions.length} ineligible)`,
     );
@@ -912,22 +921,24 @@ class TokowakaClient {
       throw this.#createError('Preview URL not found in suggestion data', HTTP_BAD_REQUEST);
     }
 
-    // Fetch metaconfig to get API key
-    const metaconfig = await this.fetchMetaconfig(previewUrl) || {};
+    // Fetch metaconfig and existing config in parallel
+    const [metaconfig, existingConfig] = await Promise.all([
+      this.fetchMetaconfig(previewUrl).catch(() => null),
+      this.fetchConfig(previewUrl, false),
+    ]);
 
     let apiKey;
-    if (Array.isArray(metaconfig.apiKeys) && metaconfig.apiKeys.length > 0) {
+    if (metaconfig && Array.isArray(metaconfig.apiKeys) && metaconfig.apiKeys.length > 0) {
       [apiKey] = metaconfig.apiKeys;
+      this.log.info('Using API key from metaconfig');
+    } else {
+      this.log.info('Proceeding with preview without API key');
     }
 
     const forwardedHost = calculateForwardedHost(previewUrl, this.log);
 
-    // Fetch existing deployed configuration for this URL from production S3
-    this.log.debug(`Fetching existing deployed Tokowaka config for URL: ${previewUrl}`);
-    const existingConfig = await this.fetchConfig(previewUrl, false);
-
     // Generate configuration with eligible preview suggestions
-    this.log.debug(`Generating preview Tokowaka config for opportunity ${opportunity.getId()}`);
+    this.log.info(`Generating preview Tokowaka config for opportunity ${opportunity.getId()}`);
     const newConfig = this.generateConfig(previewUrl, opportunity, eligibleSuggestions);
 
     if (!newConfig) {
@@ -965,7 +976,7 @@ class TokowakaClient {
       // Merge the existing deployed patches with new preview suggestions
       config = this.mergeConfigs(existingConfig, newConfig);
 
-      this.log.debug(
+      this.log.info(
         `Preview config now has ${config.patches.length} total patches`,
       );
     } else {
@@ -976,28 +987,34 @@ class TokowakaClient {
     this.log.info(`Uploading preview Tokowaka config with ${eligibleSuggestions.length} new suggestions`);
     const s3Path = await this.uploadConfig(previewUrl, config, true);
 
-    // Invalidate CDN cache for all providers in parallel (preview path)
-    const cdnInvalidationResults = await this.invalidateCdnCache({
-      urls: [previewUrl],
-      isPreview: true,
-    });
-
     // Fetch HTML content for preview
     let originalHtml = null;
     let optimizedHtml = null;
+    let cdnInvalidationResults = null;
 
     try {
-      // Fetch original HTML (without preview)
-      originalHtml = await fetchHtmlWithWarmup(
-        previewUrl,
-        apiKey,
-        forwardedHost,
-        edgeUrl,
-        this.log,
-        false,
-        options,
-      );
-      // Then fetch optimized HTML (with preview)
+      const fetchAndInvalidateStartTime = Date.now();
+      // Fetch original HTML and invalidate CDN cache in parallel to save time
+      [originalHtml, cdnInvalidationResults] = await Promise.all([
+        fetchHtmlWithWarmup(
+          previewUrl,
+          apiKey,
+          forwardedHost,
+          edgeUrl,
+          this.log,
+          false,
+          options,
+        ),
+        this.invalidateCdnCache({
+          urls: [previewUrl],
+          isPreview: true,
+        }),
+      ]);
+      this.log.info('Successfully fetched original HTML and invalidated CDN cache'
+        + ` in ${Date.now() - fetchAndInvalidateStartTime}ms`);
+
+      // Step 2: Fetch optimized HTML after CDN invalidation and original fetch complete
+      this.log.info('Fetching optimized HTML...');
       optimizedHtml = await fetchHtmlWithWarmup(
         previewUrl,
         apiKey,
@@ -1007,7 +1024,7 @@ class TokowakaClient {
         true,
         options,
       );
-      this.log.info('Successfully fetched both original and optimized HTML for preview');
+      this.log.info('Successfully fetched optimized HTML');
     } catch (error) {
       this.log.error(`Failed to fetch HTML for preview: ${error.message}`);
       throw this.#createError(

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

@@ -23,6 +23,20 @@ function sleep(ms) {
   });
 }
 
+async function fetchWithTimeout(url, options = {}, timeout = 3000) {
+  try {
+    return await fetch(url, {
+      ...options,
+      signal: AbortSignal.timeout(timeout),
+    });
+  } catch (error) {
+    if (error.name === 'TimeoutError') {
+      throw new Error(`Request timed out after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+
 /**
  * Makes an HTTP request with retry logic for both original and optimized HTML.
  * Header validation logic (same for both):
@@ -40,12 +54,14 @@ function sleep(ms) {
 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`);
+      log.info(`[${fetchType}] Retry attempt ${attempt}/${maxRetries + 1} for ${fetchType} HTML`);
 
       // eslint-disable-next-line no-await-in-loop
-      const response = await fetch(url, options);
+      const response = await fetchWithTimeout(url, options);
 
-      log.debug(`Response status (attempt ${attempt}): ${response.status} ${response.statusText}`);
+      // Log request ID for debugging
+      const requestId = response?.headers?.get('x-edgeoptimize-request-id');
+      log.info(`[${fetchType}] Response status (attempt ${attempt}): ${response.status} ${response.statusText}, x-edgeoptimize-request-id: ${requestId || 'none'}`);
 
       if (!response.ok) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -55,35 +71,35 @@ async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetch
       const cacheHeader = response.headers.get('x-edgeoptimize-cache');
       const proxyHeader = response.headers.get('x-edgeoptimize-proxy');
 
-      log.debug(`Headers - cache: ${cacheHeader || 'none'}, proxy: ${proxyHeader || 'none'}`);
+      log.info(`[${fetchType}] Headers - cache: ${cacheHeader || 'none'}, proxy: ${proxyHeader || 'none'}`);
 
       // Case 1: Cache header present (regardless of proxy) -> Success
       if (cacheHeader) {
-        log.debug(`Cache header found (x-edgeoptimize-cache: ${cacheHeader}), stopping retry logic`);
+        log.info(`[${fetchType}] Cache header found (x-edgeoptimize-cache: ${cacheHeader}), stopping retry logic`);
         return response;
       }
 
       // Case 2: No cache header AND no proxy header -> Success (return immediately)
       if (!proxyHeader) {
-        log.debug('No edge optimize headers found, proceeding as successful flow');
+        log.info(`[${fetchType}] No edge optimize headers found, proceeding as successful flow`);
         return response;
       }
 
       // Case 3: Proxy header present BUT no cache header -> Retry until cache found
-      log.debug('Proxy header present without cache header, will retry...');
+      log.info(`[${fetchType}] Proxy header present without cache header, will retry...`);
 
       // If we haven't exhausted retries, continue
       if (attempt < maxRetries + 1) {
-        log.debug(`Waiting ${retryDelayMs}ms before retry...`);
+        log.debug(`[${fetchType}] Waiting ${retryDelayMs}ms before retry...`);
         // eslint-disable-next-line no-await-in-loop
         await sleep(retryDelayMs);
       } else {
         // Last attempt - throw error
-        log.error(`Max retries (${maxRetries}) exhausted. Proxy header present but cache header not found`);
+        log.error(`[${fetchType}] Max retries (${maxRetries}) exhausted. Proxy header present but cache header not found`);
         throw new Error(`Cache header (x-edgeoptimize-cache) not found after ${maxRetries} retries`);
       }
     } catch (error) {
-      log.warn(`Attempt ${attempt} failed for ${fetchType} HTML, error: ${error.message}`);
+      log.warn(`[${fetchType}] Attempt ${attempt} failed for ${fetchType} HTML, error: ${error.message}`);
 
       // If this was the last attempt, throw the error
       if (attempt === maxRetries + 1) {
@@ -91,7 +107,7 @@ async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetch
       }
 
       // Wait before retrying
-      log.debug(`Waiting ${retryDelayMs}ms before retry...`);
+      log.debug(`[${fetchType}] Waiting ${retryDelayMs}ms before retry...`);
       // eslint-disable-next-line no-await-in-loop
       await sleep(retryDelayMs);
     }
@@ -110,11 +126,11 @@ async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetch
  * @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.warmupDelayMs - Delay after warmup call (default: 1000ms)
+ * @param {number} options.maxRetries - Maximum number of retries for actual call (default: 3)
  * @param {number} options.retryDelayMs - Delay between retries (default: 1000ms)
  * @returns {Promise<string>} - HTML content
- * @throws {Error} - If validation fails or fetch fails after retries
+ * @throws {Error} - If validation fails or fetch fails after retries or timeout
  */
 export async function fetchHtmlWithWarmup(
   url,
@@ -140,7 +156,7 @@ export async function fetchHtmlWithWarmup(
 
   // Default options
   const {
-    warmupDelayMs = 2000,
+    warmupDelayMs = isOptimized ? 750 : 0, // milliseconds
     maxRetries = 3,
     retryDelayMs = 1000,
   } = options;
@@ -150,7 +166,7 @@ export async function fetchHtmlWithWarmup(
   // Parse the URL to extract path and construct full URL
   const urlObj = new URL(url);
   const urlPath = urlObj.pathname;
-  let fullUrl = `${edgeUrl}${urlPath}`;
+  const fullUrl = `${edgeUrl}${urlPath}`;
 
   const headers = {
     'x-forwarded-host': forwardedHost,
@@ -160,9 +176,7 @@ export async function fetchHtmlWithWarmup(
   };
 
   if (isOptimized) {
-    // Add tokowakaPreview param for optimized HTML
-    fullUrl = `${fullUrl}?tokowakaPreview=true`;
-    headers['x-edgeoptimize-url'] = `${urlPath}?tokowakaPreview=true`;
+    headers['x-edgeoptimize-preview'] = 1;
   }
 
   const fetchOptions = {
@@ -172,21 +186,23 @@ export async function fetchHtmlWithWarmup(
 
   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
+    log.info(`[${fetchType}] Making warmup call for ${fetchType} HTML with URL: ${fullUrl}`);
+    const warmupStartTime = Date.now();
+    const warmupResponse = await fetchWithTimeout(fullUrl, fetchOptions);
+    log.debug(`[${fetchType}] Warmup response status: ${warmupResponse.status} ${warmupResponse.statusText}`);
     await warmupResponse.text();
-    log.debug(`Warmup call completed, waiting ${warmupDelayMs}ms...`);
+    log.info(`[${fetchType}] Warmup call completed in ${Date.now() - warmupStartTime}ms, waiting ${warmupDelayMs}ms...`);
+  } catch (warmupError) {
+    log.warn(`[${fetchType}] Warmup call failed (ignored): ${warmupError.message}`);
+  }
 
-    // Wait before actual call
-    await sleep(warmupDelayMs);
+  await sleep(warmupDelayMs);
 
+  try {
     // Actual call with retry logic
-    log.debug(`Making actual call for ${fetchType} HTML (max ${maxRetries} retries) with URL: ${fullUrl}`);
+    log.info(`[${fetchType}] Making actual call for ${fetchType} HTML (max ${maxRetries} retries) with URL: ${fullUrl}`);
 
+    const fetchStartTime = Date.now();
     const response = await fetchWithRetry(
       fullUrl,
       fetchOptions,
@@ -197,10 +213,10 @@ export async function fetchHtmlWithWarmup(
     );
 
     const html = await response.text();
-    log.debug(`Successfully fetched ${fetchType} HTML (${html.length} bytes)`);
+    log.info(`[${fetchType}] Successfully fetched ${fetchType} HTML (${html.length} bytes) in ${Date.now() - fetchStartTime}ms`);
     return html;
   } catch (error) {
-    const errorMsg = `Failed to fetch ${fetchType} HTML after ${maxRetries} retries: ${error.message}`;
+    const errorMsg = `[${fetchType}] Failed to fetch ${fetchType} HTML after ${maxRetries} retries: ${error.message}`;
     log.error(errorMsg);
     throw new Error(errorMsg);
   }

package/test/index.test.js

@@ -3153,7 +3153,7 @@ describe('TokowakaClient', () => {
           mockSite,
           mockOpportunity,
           mockSuggestions,
-          { warmupDelayMs: 0 },
+          { warmupDelayMs: 0, maxRetries: 0, retryDelayMs: 0 },
         );
         expect.fail('Should have thrown error');
       } catch (error) {

package/test/utils/html-utils.test.js

@@ -160,11 +160,68 @@ describe('HTML Utils', () => {
       expect(html).to.equal('<html>Optimized HTML</html>');
       expect(fetchStub.callCount).to.equal(2); // warmup + actual
 
-      // Verify original query params are dropped and only tokowakaPreview is present
+      // Verify original query params are dropped and preview header is set
       const actualUrl = fetchStub.secondCall.args[0];
+      const actualOptions = fetchStub.secondCall.args[1];
       expect(actualUrl).to.not.include('param=value');
-      expect(actualUrl).to.include('?tokowakaPreview=true');
-      expect(actualUrl).to.equal('https://edge.example.com/page?tokowakaPreview=true');
+      expect(actualUrl).to.equal('https://edge.example.com/page');
+      expect(actualOptions.headers['x-edgeoptimize-preview']).to.equal(1);
+    });
+
+    it('should use default warmup delay of 0ms for original HTML', async () => {
+      fetchStub.resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edgeoptimize-cache' ? 'HIT' : null),
+        },
+        text: async () => '<html>Test HTML</html>',
+      });
+
+      const startTime = Date.now();
+      const html = await fetchHtmlWithWarmup(
+        'https://example.com/page',
+        'api-key',
+        'host',
+        'https://edge.example.com',
+        log,
+        false, // isOptimized = false, should use 750ms default
+        {}, // No warmupDelayMs provided - should use default
+      );
+
+      const elapsed = Date.now() - startTime;
+      expect(html).to.equal('<html>Test HTML</html>');
+      expect(fetchStub.callCount).to.equal(2); // warmup + actual
+      expect(elapsed).to.be.below(700); // Should have waited ~750ms
+    });
+
+    it('should use default warmup delay of 750ms for optimized HTML', async () => {
+      fetchStub.resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edgeoptimize-cache' ? 'HIT' : null),
+        },
+        text: async () => '<html>Optimized HTML</html>',
+      });
+
+      const startTime = Date.now();
+      const html = await fetchHtmlWithWarmup(
+        'https://example.com/page',
+        'api-key',
+        'host',
+        'https://edge.example.com',
+        log,
+        true, // isOptimized = true, should use 0ms default
+        {}, // No warmupDelayMs provided - should use default
+      );
+
+      const elapsed = Date.now() - startTime;
+      expect(html).to.equal('<html>Optimized HTML</html>');
+      expect(fetchStub.callCount).to.equal(2); // warmup + actual
+      expect(elapsed).to.be.at.least(750); // Should not have waited (0ms warmup)
     });
 
     it('should return immediately for optimized HTML when no headers present', async () => {
@@ -370,10 +427,15 @@ describe('HTML Utils', () => {
           'https://edge.example.com',
           log,
           false,
-          { warmupDelayMs: 0, maxRetries: 2, retryDelayMs: 0 },
+          {
+            warmupDelayMs: 0,
+            maxRetries: 2,
+            retryDelayMs: 0,
+          },
         );
         expect.fail('Should have thrown error');
       } catch (error) {
+        expect(error.message).to.include('original HTML');
         expect(error.message).to.include('Failed to fetch original HTML');
         expect(error.message).to.include('Network error');
       }
@@ -401,10 +463,11 @@ describe('HTML Utils', () => {
           'https://edge.example.com',
           log,
           false,
-          { warmupDelayMs: 0, maxRetries: 0 },
+          { warmupDelayMs: 0, maxRetries: 0, timeoutMs: 10000 },
         );
         expect.fail('Should have thrown error');
       } catch (error) {
+        expect(error.message).to.include('original HTML');
         expect(error.message).to.include('Network error');
       }
 
@@ -442,6 +505,42 @@ describe('HTML Utils', () => {
       }
     });
 
+    it('should handle timeout errors properly', async () => {
+      // Create a timeout error
+      const timeoutError = new Error('The operation was aborted');
+      timeoutError.name = 'TimeoutError';
+
+      // Warmup succeeds
+      fetchStub.onCall(0).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: () => null,
+        },
+        text: async () => 'warmup',
+      });
+
+      // Actual call times out
+      fetchStub.onCall(1).rejects(timeoutError);
+
+      try {
+        await fetchHtmlWithWarmup(
+          'https://example.com/page',
+          'api-key',
+          'host',
+          'https://edge.example.com',
+          log,
+          false,
+          { warmupDelayMs: 0, maxRetries: 0, timeoutMs: 100 },
+        );
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('Failed to fetch original HTML');
+        expect(error.message).to.include('Request timed out after');
+      }
+    });
+
     it('should return immediately when no edge optimize headers are present', async () => {
       // Warmup succeeds
       fetchStub.onCall(0).resolves({