@adobe/spacecat-shared-tokowaka-client 1.5.2 → 1.5.4

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@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)
+
+
+### Bug Fixes
+
+* update tokowaka config ([#1275](https://github.com/adobe/spacecat-shared/issues/1275)) ([06cedcd](https://github.com/adobe/spacecat-shared/commit/06cedcd3d6f5956d895f7dedb7579d2eefffe58e))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.5.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.1...@adobe/spacecat-shared-tokowaka-client-v1.5.2) (2026-01-21)
 
 

package/package.json

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

package/src/index.js

@@ -349,15 +349,21 @@ class TokowakaClient {
 
     // dont override api keys
     // if patches exist, they cannot reset to empty object
+    const hasForceFail = options.forceFail !== undefined
+      || existingMetaconfig.forceFail !== undefined;
+    const forceFail = options.forceFail
+      ?? existingMetaconfig.forceFail
+      ?? false;
+
     const metaconfig = {
       siteId,
       apiKeys: existingMetaconfig.apiKeys,
-      tokowakaEnabled: options.tokowakaEnabled ?? true,
-      enhancements: options.enhancements ?? true,
+      tokowakaEnabled: options.tokowakaEnabled ?? existingMetaconfig.tokowakaEnabled ?? true,
+      enhancements: options.enhancements ?? existingMetaconfig.enhancements ?? true,
       patches: isNonEmptyObject(options.patches)
         ? options.patches
         : (existingMetaconfig.patches ?? {}),
-      ...(options.forceFail && { forceFail: true }),
+      ...(hasForceFail && { forceFail }),
     };
 
     const s3Path = await this.uploadMetaconfig(url, metaconfig);

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/index.test.js

@@ -598,8 +598,9 @@ describe('TokowakaClient', () => {
       expect(result).to.have.property('siteId', siteId);
       expect(result).to.have.property('apiKeys');
       expect(result.apiKeys).to.deep.equal(['existing-api-key-123']);
-      expect(result).to.have.property('tokowakaEnabled', true);
-      expect(result).to.have.property('enhancements', true);
+      // Should preserve existing metaconfig values when options not provided
+      expect(result).to.have.property('tokowakaEnabled', false);
+      expect(result).to.have.property('enhancements', false);
       expect(result.patches).to.deep.equal({ 'existing-patch': 'value' });
       expect(result).to.not.have.property('forceFail');
     });
@@ -611,7 +612,7 @@ describe('TokowakaClient', () => {
       const result = await client.updateMetaconfig(url, siteId, { tokowakaEnabled: false });
 
       expect(result).to.have.property('tokowakaEnabled', false);
-      expect(result).to.have.property('enhancements', true);
+      expect(result).to.have.property('enhancements', false);
       expect(result.patches).to.deep.equal({ 'existing-patch': 'value' });
       expect(result).to.not.have.property('forceFail');
     });
@@ -623,8 +624,9 @@ describe('TokowakaClient', () => {
       const result = await client.updateMetaconfig(url, siteId, { tokowakaEnabled: true });
 
       expect(result).to.have.property('tokowakaEnabled', true);
-      expect(result).to.have.property('enhancements', true);
+      expect(result).to.have.property('enhancements', false);
       expect(result.patches).to.deep.equal({ 'existing-patch': 'value' });
+      expect(result).to.not.have.property('forceFail');
     });
 
     it('should update metaconfig with enhancements set to false', async () => {
@@ -633,9 +635,10 @@ describe('TokowakaClient', () => {
 
       const result = await client.updateMetaconfig(url, siteId, { enhancements: false });
 
-      expect(result).to.have.property('tokowakaEnabled', true);
+      expect(result).to.have.property('tokowakaEnabled', false);
       expect(result).to.have.property('enhancements', false);
       expect(result.patches).to.deep.equal({ 'existing-patch': 'value' });
+      expect(result).to.not.have.property('forceFail');
     });
 
     it('should update metaconfig with enhancements set to true explicitly', async () => {
@@ -644,9 +647,10 @@ describe('TokowakaClient', () => {
 
       const result = await client.updateMetaconfig(url, siteId, { enhancements: true });
 
-      expect(result).to.have.property('tokowakaEnabled', true);
+      expect(result).to.have.property('tokowakaEnabled', false);
       expect(result).to.have.property('enhancements', true);
       expect(result.patches).to.deep.equal({ 'existing-patch': 'value' });
+      expect(result).to.not.have.property('forceFail');
     });
 
     it('should override patches when non-empty patches object is provided', async () => {
@@ -708,13 +712,13 @@ describe('TokowakaClient', () => {
       expect(result).to.have.property('forceFail', true);
     });
 
-    it('should not include forceFail when set to false', async () => {
+    it('should include forceFail when set to false', async () => {
       const siteId = 'site-789';
       const url = 'https://example.com';
 
       const result = await client.updateMetaconfig(url, siteId, { forceFail: false });
 
-      expect(result).to.not.have.property('forceFail');
+      expect(result).to.have.property('forceFail', false);
     });
 
     it('should not include forceFail when undefined', async () => {
@@ -726,6 +730,38 @@ describe('TokowakaClient', () => {
       expect(result).to.not.have.property('forceFail');
     });
 
+    it('should use forceFail as false when options.forceFail is null and existingMetaconfig has no forceFail', async () => {
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId, { forceFail: null });
+
+      expect(result).to.have.property('forceFail', false);
+    });
+
+    it('should preserve existingMetaconfig forceFail when options.forceFail is null', async () => {
+      const configWithForceFail = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: true,
+        enhancements: true,
+        patches: {},
+        forceFail: true,
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithForceFail)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId, { forceFail: null });
+
+      expect(result).to.have.property('forceFail', true);
+    });
+
     it('should update metaconfig with multiple options', async () => {
       const siteId = 'site-789';
       const url = 'https://example.com';
@@ -855,6 +891,259 @@ describe('TokowakaClient', () => {
 
       expect(result.patches).to.deep.equal(singlePatch);
     });
+
+    it('should preserve existing patches when options.patches is null', async () => {
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId, { patches: null });
+
+      expect(result.patches).to.deep.equal({ 'existing-patch': 'value' });
+    });
+
+    it('should preserve tokowakaEnabled=true from existingMetaconfig when options not provided', async () => {
+      const configWithTokowakaEnabled = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: true,
+        enhancements: false,
+        patches: {},
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithTokowakaEnabled)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId);
+
+      expect(result).to.have.property('tokowakaEnabled', true);
+    });
+
+    it('should preserve enhancements=true from existingMetaconfig when options not provided', async () => {
+      const configWithEnhancements = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: false,
+        enhancements: true,
+        patches: {},
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithEnhancements)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId);
+
+      expect(result).to.have.property('enhancements', true);
+    });
+
+    it('should default tokowakaEnabled to true when not in existingMetaconfig or options', async () => {
+      const configWithoutTokowakaEnabled = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        enhancements: false,
+        patches: {},
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithoutTokowakaEnabled)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId);
+
+      expect(result).to.have.property('tokowakaEnabled', true);
+    });
+
+    it('should default enhancements to true when not in existingMetaconfig or options', async () => {
+      const configWithoutEnhancements = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: false,
+        patches: {},
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithoutEnhancements)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId);
+
+      expect(result).to.have.property('enhancements', true);
+    });
+
+    it('should preserve forceFail=true from existingMetaconfig when options not provided', async () => {
+      const configWithForceFail = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: true,
+        enhancements: true,
+        patches: {},
+        forceFail: true,
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithForceFail)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId);
+
+      expect(result).to.have.property('forceFail', true);
+    });
+
+    it('should override existingMetaconfig forceFail when explicitly set to false in options', async () => {
+      const configWithForceFail = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: true,
+        enhancements: true,
+        patches: {},
+        forceFail: true,
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithForceFail)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId, { forceFail: false });
+
+      expect(result).to.have.property('forceFail', false);
+    });
+
+    it('should override existingMetaconfig forceFail when explicitly set to true in options', async () => {
+      const configWithoutForceFail = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: true,
+        enhancements: true,
+        patches: {},
+        forceFail: false,
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithoutForceFail)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId, { forceFail: true });
+
+      expect(result).to.have.property('forceFail', true);
+    });
+
+    it('should preserve forceFail=false from existingMetaconfig when options not provided', async () => {
+      const configWithForceFail = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: true,
+        enhancements: true,
+        patches: {},
+        forceFail: false,
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithForceFail)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId);
+
+      expect(result).to.have.property('forceFail', false);
+    });
+
+    it('should override existingMetaconfig tokowakaEnabled=false when explicitly set to true', async () => {
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+      // existingMetaconfig has tokowakaEnabled: false
+
+      const result = await client.updateMetaconfig(url, siteId, { tokowakaEnabled: true });
+
+      expect(result).to.have.property('tokowakaEnabled', true);
+    });
+
+    it('should override existingMetaconfig enhancements=false when explicitly set to true', async () => {
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+      // existingMetaconfig has enhancements: false
+
+      const result = await client.updateMetaconfig(url, siteId, { enhancements: true });
+
+      expect(result).to.have.property('enhancements', true);
+    });
+
+    it('should handle case where options.forceFail and existingMetaconfig.forceFail are both true', async () => {
+      const configWithForceFail = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: true,
+        enhancements: true,
+        patches: {},
+        forceFail: true,
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithForceFail)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId, { forceFail: true });
+
+      expect(result).to.have.property('forceFail', true);
+    });
+
+    it('should handle case where options.forceFail and existingMetaconfig.forceFail are both false', async () => {
+      const configWithForceFail = {
+        siteId: 'site-456',
+        apiKeys: ['existing-api-key-123'],
+        tokowakaEnabled: true,
+        enhancements: true,
+        patches: {},
+        forceFail: false,
+      };
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(configWithForceFail)),
+        },
+      });
+
+      const siteId = 'site-789';
+      const url = 'https://example.com';
+
+      const result = await client.updateMetaconfig(url, siteId);
+
+      expect(result).to.have.property('forceFail', false);
+    });
   });
 
   describe('uploadConfig', () => {

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', () => {