@adobe/spacecat-shared-tokowaka-client 1.5.3 → 1.5.5

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.5.5](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.4...@adobe/spacecat-shared-tokowaka-client-v1.5.5) (2026-01-21)
+
+
+### Bug Fixes
+
+* remove details from tokowaka readme ([#1277](https://github.com/adobe/spacecat-shared/issues/1277)) ([14f3aa8](https://github.com/adobe/spacecat-shared/commit/14f3aa82cfbde56c6baebd1ad979980cbe24dd12))
+
+# [@adobe/spacecat-shared-tokowaka-client-v1.5.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.3...@adobe/spacecat-shared-tokowaka-client-v1.5.4) (2026-01-21)
+
+
+### Bug Fixes
+
+* edge preview api headers handling ([#1276](https://github.com/adobe/spacecat-shared/issues/1276)) ([e2a7ba8](https://github.com/adobe/spacecat-shared/commit/e2a7ba88df77ee7e369d39e623966b5760ac9d12))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.5.3](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.2...@adobe/spacecat-shared-tokowaka-client-v1.5.3) (2026-01-21)
 
 

package/README.md

@@ -17,148 +17,6 @@ const tokowakaClient = TokowakaClient.createFrom(context);
 const result = await tokowakaClient.deploySuggestions(site, opportunity, suggestions);
 ```
 
-## API Reference
-
-### TokowakaClient.createFrom(context)
-
-Creates a client instance from a context object.
-
-**Required context properties:**
-- `context.s3.s3Client` (S3Client): AWS S3 client instance
-- `context.log` (Object, optional): Logger instance
-- `context.env.TOKOWAKA_SITE_CONFIG_BUCKET` (string): S3 bucket name for deployed configurations
-- `context.env.TOKOWAKA_PREVIEW_BUCKET` (string): S3 bucket name for preview configurations
-- `context.env.TOKOWAKA_CDN_PROVIDER` (string | string[]): CDN provider(s) for cache invalidation
-- `context.env.TOKOWAKA_CDN_CONFIG` (string): JSON configuration for CDN clients
-- `context.env.TOKOWAKA_EDGE_URL` (string): Tokowaka edge URL for preview HTML fetching
-
-## Environment Variables
-
-**Required:**
-- `TOKOWAKA_SITE_CONFIG_BUCKET` - S3 bucket name for storing deployed configurations
-- `TOKOWAKA_PREVIEW_BUCKET` - S3 bucket name for storing preview configurations
-
-**Optional (for CDN invalidation):**
-- `TOKOWAKA_CDN_PROVIDER` - CDN provider name(s). Can be a single provider (e.g., "cloudfront") or multiple providers as comma-separated string (e.g., "cloudfront,fastly") or array
-- `TOKOWAKA_CDN_CONFIG` - JSON string with CDN-specific configuration for all providers:
-  ```json
-  {
-    "cloudfront": {
-      "distributionId": "<distribution-id>",
-      "region": "us-east-1"
-    },
-    "fastly": {
-      "serviceId": "<service-id>",
-      "apiToken": "<api-token>",
-      "distributionUrl": "https://<cloudfront-distribution>.cloudfront.net"
-    }
-  }
-  ```
-  
-  **Note for Fastly**: The `distributionUrl` is required and should be the full CloudFront distribution URL (e.g., `https://deftbrsarcsf4.cloudfront.net`). Fastly uses this to construct full URLs as surrogate keys for cache purging.
-
-**Optional (for preview functionality):**
-- `TOKOWAKA_EDGE_URL` - Tokowaka edge URL for fetching HTML content during preview
-
-### Main Methods
-
-#### `deploySuggestions(site, opportunity, suggestions)`
-
-Generates configuration and uploads to S3 **per URL**. **Automatically fetches existing configuration for each URL and merges** new suggestions with it. Invalidates CDN cache after upload. **Updates the metaconfig's `patches` field** to track deployed endpoints.
-
-**Architecture Change:** Creates one S3 file per URL instead of a single file with all URLs. This prevents files from growing too large over time.
-
-**Metaconfig Tracking:** After successful deployment, the method updates the domain-level metaconfig's `patches` object with the normalized paths of all deployed endpoints (e.g., `{ "/products/item": true }`). This provides a centralized registry of all deployed endpoints for the domain.
-
-**Returns:** `Promise<DeploymentResult>` with:
-- `s3Paths` - Array of S3 keys where configs were uploaded (one per URL)
-- `cdnInvalidations` - Array of CDN invalidation results (one per URL per provider)
-- `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 for each URL** and removes patches matching the provided suggestions. Invalidates CDN cache after upload.
-
-**Architecture Change:** Updates one S3 file per URL instead of a single file with all URLs.
-
-**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:
-- `s3Paths` - Array of S3 keys where configs were uploaded (one per URL)
-- `cdnInvalidations` - Array of CDN invalidation results (one per URL per provider)
-- `succeededSuggestions` - Array of rolled back suggestions
-- `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
-- `removedPatchesCount` - Total number of patches removed across all URLs
-
-#### `previewSuggestions(site, opportunity, suggestions, options)`
-
-Previews suggestions by uploading to preview S3 path and fetching HTML comparison. **All suggestions must belong to the same URL.**
-
-**Returns:** `Promise<PreviewResult>` with:
-- `s3Path` - S3 key where preview config was uploaded
-- `config` - Preview configuration object
-- `cdnInvalidations` - Array of CDN invalidation results (one per provider)
-- `succeededSuggestions` - Array of previewed suggestions
-- `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
-- `html` - Object with `url`, `originalHtml`, and `optimizedHtml`
-
-#### `fetchConfig(url, isPreview)`
-
-Fetches existing Tokowaka configuration from S3 for a specific URL.
-
-**Parameters:**
-- `url` - Full URL (e.g., 'https://www.example.com/products/item')
-- `isPreview` - Whether to fetch from preview path (default: false)
-
-**Returns:** `Promise<TokowakaConfig | null>` - Configuration object or null if not found
-
-#### `mergeConfigs(existingConfig, newConfig)`
-
-Merges existing configuration with new configuration. For each URL path, checks if `opportunityId` + `suggestionId` combination exists and either updates or adds patches accordingly.
-
-**Returns:** `TokowakaConfig` - Merged configuration
-
-#### `generateConfig(url, opportunity, suggestions)`
-
-Generates Tokowaka configuration from opportunity suggestions for a specific URL without uploading.
-
-**Parameters:**
-- `url` - Full URL for which to generate config
-- `opportunity` - Opportunity entity
-- `suggestions` - Array of suggestion entities
-
-#### `uploadConfig(url, config, isPreview)`
-
-Uploads configuration to S3 for a specific URL.
-
-**Parameters:**
-- `url` - Full URL (e.g., 'https://www.example.com/products/item')
-- `config` - Tokowaka configuration object
-- `isPreview` - Whether to upload to preview path (default: false)
-
-**Returns:** `Promise<string>` - S3 key of uploaded configuration
-
-## CDN Cache Invalidation
-
-The client invalidates CDN cache after uploading configurations. Failures are logged but don't block deployment.
-
-## Site Configuration
-
-Sites must have the `tokowakaConfig` field in their site-config to confirm that tokowaka is enabled for that particular site.
-
-```javascript
-{
-  ...
-  "tokowakaConfig": {
-    "enabled": true
-  }
-}
-```
-
 ## Supported Opportunity Types
 
 ### Headings
@@ -174,177 +32,3 @@ Sites must have the `tokowakaConfig` field in their site-config to confirm that
 ### Content Summarization
 
 **Deployment Eligibility:** Currently all suggestions for `summarization` opportunity can be deployed.
-
-## S3 Storage
-
-Configurations are now stored **per URL** with domain-level metadata:
-
-### Structure
-```
-s3://{TOKOWAKA_SITE_CONFIG_BUCKET}/opportunities/{normalized-domain}/
-├── config (domain-level metaconfig: siteId, prerender)
-├── {base64-encoded-path-1} (URL-specific patches)
-├── {base64-encoded-path-2} (URL-specific patches)
-└── ...
-```
-
-For preview configurations:
-```
-s3://{TOKOWAKA_PREVIEW_BUCKET}/preview/opportunities/{normalized-domain}/
-├── config
-├── {base64-encoded-path-1}
-└── ...
-```
-
-**Architecture Change:** Each URL has its own configuration file instead of one file per site. Domain-level metaconfig is stored separately to avoid duplication.
-
-**URL Normalization:**
-- Domain: Strips `www.` prefix (e.g., `www.example.com` → `example.com`)
-- Path: Removes trailing slash (except for root `/`), ensures starts with `/`, then base64 URL encodes
-
-**Example:**
-- URL: `https://www.example.com/products/item`
-- Metaconfig Path: `opportunities/example.com/config`
-- Patch Config Path: `opportunities/example.com/L3Byb2R1Y3RzL2l0ZW0`
-- Where `L3Byb2R1Y3RzL2l0ZW0` is base64 URL encoding of `/products/item`
-
-### Metaconfig File Structure
-Domain-level metaconfig (created once per domain, shared by all URLs):
-```json
-{
-  "siteId": "abc-123",
-  "apiKeys": ["tokowaka-api-key-1"],
-  "tokowakaEnabled": true,
-  "enhancements": true,
-  "prerender": {
-    "allowList": [],
-    "denyList": ["/*"]
-  },
-  "patches": {
-    "/products/item": true,
-    "/about": true,
-    "/contact": true
-  }
-}
-```
-
-### Configuration File Structure
-Per-URL configuration (flat structure):
-```json
-{
-  "url": "https://example.com/products/item",
-  "version": "1.0",
-  "forceFail": false,
-  "prerender": true,
-  "patches": [
-    {
-      "opportunityId": "abc-123",
-      "suggestionId": "xyz-789",
-      "prerenderRequired": true,
-      "lastUpdated": 1234567890,
-      "op": "insertAfter",
-      "selector": "main",
-      "value": { ... },
-      "valueFormat": "hast",
-      "target": "ai-bots"
-    }
-  ]
-}
-```
-
-**Note:** 
-- `siteId` is stored only in domain-level `config` (metaconfig)
-- `prerender` is stored in both metaconfig (domain-level) and patch files (URL-level)
-- The `baseURL` field has been renamed to `url`
-- The `tokowakaOptimizations` nested structure has been removed
-- The `tokowakaForceFail` field has been renamed to `forceFail`
-
-## CDN Cache Invalidation
-
-The client supports multiple CDN providers for cache invalidation with **intelligent batching** for optimal performance.
-
-### Batch Optimization
-
-When deploying or rolling back multiple URLs:
-- **Before**: Each URL triggered separate CDN invalidation calls (N URLs = N×2 API calls for 2 providers)
-- **After**: All URLs are collected and invalidated in a single batch call per provider (N URLs = 2 API calls for 2 providers)
-
-**Example Performance Improvement:**
-- 10 URLs with CloudFront + Fastly
-- Old: 20 API calls (10 per provider)
-- New: **2 API calls** (1 per provider)
-- **90% reduction in API calls!**
-
-### Supported CDN Providers
-
-#### CloudFront
-AWS CloudFront CDN invalidation using the AWS SDK.
-
-**Configuration:**
-```json
-{
-  "cloudfront": {
-    "distributionId": "E1234567890ABC",
-    "region": "us-east-1"
-  }
-}
-```
-
-#### Fastly
-Fastly CDN purging using surrogate key purging.
-
-**Configuration:**
-```json
-{
-  "fastly": {
-    "serviceId": "abc123xyz",
-    "apiToken": "your-fastly-api-token"
-  }
-}
-```
-
-### Multiple CDN Providers
-
-To invalidate cache on multiple CDNs simultaneously:
-
-**Environment Variable:**
-```bash
-TOKOWAKA_CDN_PROVIDER="cloudfront,fastly"
-# or as array in code: ["cloudfront", "fastly"]
-
-TOKOWAKA_CDN_CONFIG='{"cloudfront":{"distributionId":"...","region":"us-east-1"},"fastly":{"serviceId":"...","apiToken":"...","distributionUrl":"https://xxx.cloudfront.net"}}'
-```
-
-**Behavior:**
-- All URLs are batched into a single invalidation request per provider
-- All CDN providers are invalidated sequentially
-- Failures in one CDN don't block others
-- Each CDN returns its own result in the `cdnInvalidations` array
-- Results include status, provider name, and provider-specific details
-
-### Fastly Batch Purging
-
-The Fastly client uses surrogate key purging with full CloudFront URLs:
-- **Surrogate Keys**: Constructed as full CloudFront URLs (e.g., `https://xxx.cloudfront.net/opportunities/adobe.com/config`)
-- **Batch Purging**: All paths are sent in a single API call using the `Surrogate-Key` header (space-separated URLs)
-- **Configuration**: Requires `distributionUrl` in the Fastly config to construct full URLs
-- Significantly reduces API calls and improves performance for bulk operations
-
-**Example Fastly Configuration:**
-```json
-{
-  "serviceId": "abc123xyz",
-  "apiToken": "your-fastly-api-token",
-  "distributionUrl": "https://deftbrsarcsf4.cloudfront.net"
-}
-```
-
-This configuration allows Fastly to purge cache entries using URLs like:
-```
-fastly purge --key https://deftbrsarcsf4.cloudfront.net/opportunities/adobe.com/config
-```
-
-## Reference Material
-
-https://wiki.corp.adobe.com/display/AEMSites/Tokowaka+-+Spacecat+Integration
-https://wiki.corp.adobe.com/display/AEMSites/Tokowaka+Patch+Format

package/package.json

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

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

@@ -24,8 +24,11 @@ function sleep(ms) {
 }
 
 /**
- * Makes an HTTP request with retry logic
- * Retries until max retries are exhausted or x-edge-optimize-cache header is present
+ * Makes an HTTP request with retry logic for both original and optimized HTML.
+ * Header validation logic (same for both):
+ * - No proxy AND no cache header: Return response immediately (success)
+ * - Proxy header present BUT no cache header: Retry until cache header found
+ * - Cache header present (regardless of proxy): Return response (success)
  * @param {string} url - URL to fetch
  * @param {Object} options - Fetch options
  * @param {number} maxRetries - Maximum number of retries
@@ -48,23 +51,35 @@ async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetch
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
       }
 
-      // Check for x-edge-optimize-cache header - if present, stop retrying
+      // Check for edge optimize headers
       const cacheHeader = response.headers.get('x-edge-optimize-cache');
+      const proxyHeader = response.headers.get('x-edge-optimize-proxy');
+
+      log.debug(`Headers - cache: ${cacheHeader || 'none'}, proxy: ${proxyHeader || 'none'}`);
+
+      // Case 1: Cache header present (regardless of proxy) -> Success
       if (cacheHeader) {
         log.debug(`Cache header found (x-edge-optimize-cache: ${cacheHeader}), stopping retry logic`);
         return response;
       }
 
-      // If no cache header and we haven't exhausted retries, continue
+      // 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');
+        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...');
+
+      // If 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`);
+        // Last attempt - throw error
+        log.error(`Max retries (${maxRetries}) exhausted. Proxy header present but cache header not found`);
         throw new Error(`Cache header (x-edge-optimize-cache) not found after ${maxRetries} retries`);
       }
     } catch (error) {
@@ -145,6 +160,7 @@ export async function fetchHtmlWithWarmup(
     'x-forwarded-host': forwardedHost,
     'x-edge-optimize-api-key': apiKey,
     'x-edge-optimize-url': urlPath,
+    'Accept-Encoding': 'identity', // Disable compression to avoid content-length: 0 issue
   };
 
   if (isOptimized) {

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

@@ -154,6 +154,150 @@ describe('HTML Utils', () => {
       expect(actualUrl).to.equal('https://edge.example.com/page?tokowakaPreview=true');
     });
 
+    it('should return immediately for optimized HTML when no headers present', async () => {
+      // Warmup succeeds
+      fetchStub.onCall(0).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: () => null,
+        },
+        text: async () => 'warmup',
+      });
+      // First actual call - no headers, should succeed
+      fetchStub.onCall(1).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: () => null,
+        },
+        text: async () => '<html>No headers</html>',
+      });
+
+      const html = await fetchHtmlWithWarmup(
+        'https://example.com/page',
+        'api-key',
+        'host',
+        'https://edge.example.com',
+        log,
+        true, // isOptimized
+        { warmupDelayMs: 0, maxRetries: 3, retryDelayMs: 0 },
+      );
+
+      expect(html).to.equal('<html>No headers</html>');
+      // Should succeed immediately (warmup + 1 attempt)
+      expect(fetchStub.callCount).to.equal(2);
+    });
+
+    it('should throw error for optimized HTML when proxy present but cache not found after retries', async () => {
+      // Warmup succeeds
+      fetchStub.onCall(0).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: () => null,
+        },
+        text: async () => 'warmup',
+      });
+      // All actual calls have proxy but no cache header
+      fetchStub.onCall(1).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edge-optimize-proxy' ? 'true' : null),
+        },
+        text: async () => '<html>Proxy only 1</html>',
+      });
+      fetchStub.onCall(2).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edge-optimize-proxy' ? 'true' : null),
+        },
+        text: async () => '<html>Proxy only 2</html>',
+      });
+      fetchStub.onCall(3).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edge-optimize-proxy' ? 'true' : null),
+        },
+        text: async () => '<html>Proxy only 3</html>',
+      });
+
+      try {
+        await fetchHtmlWithWarmup(
+          'https://example.com/page',
+          'api-key',
+          'host',
+          'https://edge.example.com',
+          log,
+          true, // isOptimized
+          { warmupDelayMs: 0, maxRetries: 2, retryDelayMs: 0 },
+        );
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('Failed to fetch optimized HTML');
+        expect(error.message).to.include('Cache header (x-edge-optimize-cache) not found after 2 retries');
+      }
+
+      // Should have tried 3 times (initial + 2 retries) plus warmup
+      expect(fetchStub.callCount).to.equal(4);
+    });
+
+    it('should retry for optimized HTML when proxy present until cache found', async () => {
+      // Warmup succeeds
+      fetchStub.onCall(0).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: () => null,
+        },
+        text: async () => 'warmup',
+      });
+      // First call has only proxy header - should retry
+      fetchStub.onCall(1).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edge-optimize-proxy' ? 'true' : null),
+        },
+        text: async () => '<html>Proxy only</html>',
+      });
+      // Second call has cache header (proxy might still be there) - should succeed
+      fetchStub.onCall(2).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edge-optimize-cache' ? 'HIT' : null),
+        },
+        text: async () => '<html>Cached HTML</html>',
+      });
+
+      const html = await fetchHtmlWithWarmup(
+        'https://example.com/page',
+        'api-key',
+        'host',
+        'https://edge.example.com',
+        log,
+        true, // isOptimized
+        { warmupDelayMs: 0, maxRetries: 3, retryDelayMs: 0 },
+      );
+
+      expect(html).to.equal('<html>Cached HTML</html>');
+      // Should retry when only proxy present (warmup + 2 attempts)
+      expect(fetchStub.callCount).to.equal(3);
+    });
+
     it('should throw error when HTTP response is not ok', async () => {
       // Warmup succeeds
       fetchStub.onCall(0).resolves({
@@ -285,7 +429,7 @@ describe('HTML Utils', () => {
       }
     });
 
-    it('should stop retrying when x-edge-optimize-cache header is found', async () => {
+    it('should return immediately when no edge optimize headers are present', async () => {
       // Warmup succeeds
       fetchStub.onCall(0).resolves({
         ok: true,
@@ -296,7 +440,7 @@ describe('HTML Utils', () => {
         },
         text: async () => 'warmup',
       });
-      // First actual call - no cache header
+      // First actual call - no headers, should succeed immediately
       fetchStub.onCall(1).resolves({
         ok: true,
         status: 200,
@@ -304,17 +448,58 @@ describe('HTML Utils', () => {
         headers: {
           get: () => null,
         },
-        text: async () => '<html>No cache</html>',
+        text: async () => '<html>No headers</html>',
+      });
+
+      const html = await fetchHtmlWithWarmup(
+        'https://example.com/page',
+        'api-key',
+        'host',
+        'https://edge.example.com',
+        log,
+        false,
+        { warmupDelayMs: 0, maxRetries: 3, retryDelayMs: 0 },
+      );
+
+      expect(html).to.equal('<html>No headers</html>');
+      // Should succeed immediately without retry (warmup + 1 attempt)
+      expect(fetchStub.callCount).to.equal(2);
+    });
+
+    it('should retry when proxy header present without cache until cache is found', async () => {
+      // Warmup succeeds
+      fetchStub.onCall(0).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: () => null,
+        },
+        text: async () => 'warmup',
+      });
+      // First call has proxy header but no cache - should retry
+      fetchStub.onCall(1).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edge-optimize-proxy' ? 'true' : null),
+        },
+        text: async () => '<html>Proxy only</html>',
       });
-      // Second actual call - cache header found
+      // Second call has both headers - should succeed
       fetchStub.onCall(2).resolves({
         ok: true,
         status: 200,
         statusText: 'OK',
         headers: {
-          get: (name) => (name === 'x-edge-optimize-cache' ? 'HIT' : null),
+          get: (name) => {
+            if (name === 'x-edge-optimize-cache') return 'HIT';
+            if (name === 'x-edge-optimize-proxy') return 'true';
+            return null;
+          },
         },
-        text: async () => '<html>Cached HTML</html>',
+        text: async () => '<html>Both headers</html>',
       });
 
       const html = await fetchHtmlWithWarmup(
@@ -327,12 +512,12 @@ describe('HTML Utils', () => {
         { warmupDelayMs: 0, maxRetries: 3, retryDelayMs: 0 },
       );
 
-      expect(html).to.equal('<html>Cached HTML</html>');
-      // Should stop after finding cache header (warmup + 2 attempts)
+      expect(html).to.equal('<html>Both headers</html>');
+      // Should retry when only proxy present (warmup + 2 attempts)
       expect(fetchStub.callCount).to.equal(3);
     });
 
-    it('should throw error when cache header not found after max retries', async () => {
+    it('should throw error when proxy header present but cache not found after max retries', async () => {
       // Warmup succeeds
       fetchStub.onCall(0).resolves({
         ok: true,
@@ -343,33 +528,33 @@ describe('HTML Utils', () => {
         },
         text: async () => 'warmup',
       });
-      // All actual calls succeed but no cache header
+      // All actual calls have proxy but no cache header
       fetchStub.onCall(1).resolves({
         ok: true,
         status: 200,
         statusText: 'OK',
         headers: {
-          get: () => null,
+          get: (name) => (name === 'x-edge-optimize-proxy' ? 'true' : null),
         },
-        text: async () => '<html>No cache 1</html>',
+        text: async () => '<html>Proxy only 1</html>',
       });
       fetchStub.onCall(2).resolves({
         ok: true,
         status: 200,
         statusText: 'OK',
         headers: {
-          get: () => null,
+          get: (name) => (name === 'x-edge-optimize-proxy' ? 'true' : null),
         },
-        text: async () => '<html>No cache 2</html>',
+        text: async () => '<html>Proxy only 2</html>',
       });
       fetchStub.onCall(3).resolves({
         ok: true,
         status: 200,
         statusText: 'OK',
         headers: {
-          get: () => null,
+          get: (name) => (name === 'x-edge-optimize-proxy' ? 'true' : null),
         },
-        text: async () => '<html>No cache 3</html>',
+        text: async () => '<html>Proxy only 3</html>',
       });
 
       try {
@@ -428,6 +613,84 @@ describe('HTML Utils', () => {
       // Should not retry if cache header found on first attempt
       expect(fetchStub.callCount).to.equal(2); // warmup + 1 actual
     });
+
+    it('should return immediately when cache header is present (with or without proxy)', async () => {
+      // Warmup succeeds
+      fetchStub.onCall(0).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: () => null,
+        },
+        text: async () => 'warmup',
+      });
+      // First actual call has cache header (proxy may or may not be present)
+      fetchStub.onCall(1).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => {
+            if (name === 'x-edge-optimize-cache') return 'HIT';
+            if (name === 'x-edge-optimize-proxy') return 'true';
+            return null;
+          },
+        },
+        text: async () => '<html>Cache header present</html>',
+      });
+
+      const html = await fetchHtmlWithWarmup(
+        'https://example.com/page',
+        'api-key',
+        'host',
+        'https://edge.example.com',
+        log,
+        false,
+        { warmupDelayMs: 0, maxRetries: 3, retryDelayMs: 0 },
+      );
+
+      expect(html).to.equal('<html>Cache header present</html>');
+      // Should succeed immediately when cache header present (warmup + 1 attempt)
+      expect(fetchStub.callCount).to.equal(2);
+    });
+
+    it('should succeed when only cache header is present (no proxy header)', async () => {
+      // Warmup succeeds
+      fetchStub.onCall(0).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: () => null,
+        },
+        text: async () => 'warmup',
+      });
+      // First actual call has only cache header
+      fetchStub.onCall(1).resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edge-optimize-cache' ? 'HIT' : null),
+        },
+        text: async () => '<html>Cache only HTML</html>',
+      });
+
+      const html = await fetchHtmlWithWarmup(
+        'https://example.com/page',
+        'api-key',
+        'host',
+        'https://edge.example.com',
+        log,
+        false,
+        { warmupDelayMs: 0, maxRetries: 3, retryDelayMs: 0 },
+      );
+
+      expect(html).to.equal('<html>Cache only HTML</html>');
+      // Should succeed immediately with cache header only (warmup + 1 attempt)
+      expect(fetchStub.callCount).to.equal(2);
+    });
   });
 
   describe('calculateForwardedHost', () => {