@adobe/spacecat-shared-tokowaka-client 1.4.7 → 1.5.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.5.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.0...@adobe/spacecat-shared-tokowaka-client-v1.5.1) (2026-01-20)
+
+
+### Bug Fixes
+
+* rename tokowaka to edge-optimize in preview api ([#1269](https://github.com/adobe/spacecat-shared/issues/1269)) ([d40caa4](https://github.com/adobe/spacecat-shared/commit/d40caa46d2bb72506e45081a263f4513fce4ce41))
+
+# [@adobe/spacecat-shared-tokowaka-client-v1.5.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.4.7...@adobe/spacecat-shared-tokowaka-client-v1.5.0) (2026-01-15)
+
+
+### Features
+
+* add TokowakaKVClient for fetching stale suggestions from edge o… ([#1262](https://github.com/adobe/spacecat-shared/issues/1262)) ([e8d440b](https://github.com/adobe/spacecat-shared/commit/e8d440bcc462419b4c82d3415f3a83dfde5195f1))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.4.7](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.4.6...@adobe/spacecat-shared-tokowaka-client-v1.4.7) (2026-01-14)
 
 

package/package.json

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

package/src/fastly-kv-client.js

@@ -0,0 +1,197 @@
+/*
+ * Copyright 2026 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 {
+  tracingFetch as fetch,
+  hasText,
+  isNonEmptyArray,
+} from '@adobe/spacecat-shared-utils';
+
+const FASTLY_KV_API_BASE = 'https://api.fastly.com/resources/stores/kv';
+const DEFAULT_PAGE_SIZE = 100;
+const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * Client for interacting with Fastly KV Store used by Tokowaka.
+ * Used to fetch stale suggestion IDs for cleanup.
+ *
+ * Key format: `${suggestionId}`
+ * Value format: { url: string, status: 'stale' | 'live' }
+ */
+export class FastlyKVClient {
+  /**
+   * Creates a new FastlyKVClient instance.
+   * @param {object} env - Environment variables containing FASTLY_KV_STORE_ID and FASTLY_API_TOKEN
+   * @param {object} log - Logger instance
+   */
+  constructor(env, log) {
+    if (!hasText(env?.FASTLY_KV_STORE_ID)) {
+      throw new Error('FASTLY_KV_STORE_ID environment variable is required');
+    }
+    if (!hasText(env?.FASTLY_API_TOKEN)) {
+      throw new Error('FASTLY_API_TOKEN environment variable is required');
+    }
+
+    this.storeId = env.FASTLY_KV_STORE_ID;
+    this.apiToken = env.FASTLY_API_TOKEN;
+    this.log = log;
+    this.timeout = env.FASTLY_KV_TIMEOUT || DEFAULT_TIMEOUT;
+  }
+
+  /**
+   * Creates the authorization headers for Fastly API requests.
+   * @returns {object} Headers object
+   */
+  #getHeaders() {
+    return {
+      'Fastly-Key': this.apiToken,
+      Accept: 'application/json',
+    };
+  }
+
+  /**
+   * Retrieves the value for a specific key from the KV store.
+   *
+   * @param {string} key - The key to retrieve
+   * @returns {Promise<{url: string, status: string}|null>} The parsed value or null if not found
+   */
+  async #getValue(key) {
+    const url = `${FASTLY_KV_API_BASE}/${this.storeId}/keys/${encodeURIComponent(key)}`;
+
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: this.#getHeaders(),
+      timeout: this.timeout,
+    });
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Failed to get value from KV Store: ${response.status} - ${errorText}`);
+    }
+
+    const text = await response.text();
+
+    try {
+      return JSON.parse(text);
+    } catch {
+      this.log.warn(`Failed to parse value for key ${key} as JSON`);
+      return { url: text, status: 'unknown' };
+    }
+  }
+
+  /**
+   * Lists stale keys from a single page of the KV store.
+   *
+   * @param {object} [options] - Options for listing keys
+   * @param {number} [options.pageSize=100] - Number of keys to fetch per page
+   * @param {string} [options.cursor] - Cursor for pagination
+   * @returns {Promise<{keys: Array<object>, cursor: string|null}>}
+   */
+  async #listStaleKeysPage(options = {}) {
+    const { pageSize = DEFAULT_PAGE_SIZE, cursor } = options;
+    const staleEntries = [];
+
+    const url = new URL(`${FASTLY_KV_API_BASE}/${this.storeId}/keys`);
+    url.searchParams.set('limit', pageSize.toString());
+    if (cursor) {
+      url.searchParams.set('cursor', cursor);
+    }
+
+    const response = await fetch(url.toString(), {
+      method: 'GET',
+      headers: this.#getHeaders(),
+      timeout: this.timeout,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Failed to list keys from KV Store: ${response.status} - ${errorText}`);
+    }
+
+    const result = await response.json();
+    const { data: keys = [], meta = {} } = result;
+
+    for (const keyName of keys) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const value = await this.#getValue(keyName);
+
+        const normalizedStatus = typeof value?.status === 'string'
+          ? value.status.trim().toLowerCase()
+          : '';
+
+        if (normalizedStatus === 'stale' && hasText(keyName)) {
+          staleEntries.push({
+            key: keyName,
+            suggestionId: keyName,
+            url: value.url,
+          });
+        }
+      } catch (error) {
+        this.log.warn(`Failed to fetch value for key ${keyName}: ${error.message}`);
+      }
+    }
+
+    return {
+      keys: staleEntries,
+      cursor: meta.next_cursor || null,
+    };
+  }
+
+  /**
+   * Lists all stale suggestion IDs from the KV store, handling pagination automatically.
+   *
+   * @param {object} [options] - Options for listing keys
+   * @param {number} [options.pageSize=100] - Number of keys to fetch per page
+   * @param {number} [options.maxPages=100] - Maximum number of pages to fetch (safety limit)
+   * @returns {Promise<Array<{key: string, suggestionId: string, url: string}>>}
+   */
+  async listAllStaleKeys(options = {}) {
+    const { pageSize = DEFAULT_PAGE_SIZE, maxPages = 100 } = options;
+    const allStaleKeys = [];
+    let cursor = null;
+    let pageCount = 0;
+
+    this.log.info('Starting to fetch stale keys from Fastly KV Store');
+
+    do {
+      // eslint-disable-next-line no-await-in-loop
+      const result = await this.#listStaleKeysPage({ pageSize, cursor });
+
+      if (isNonEmptyArray(result.keys)) {
+        allStaleKeys.push(...result.keys);
+      }
+
+      cursor = result.cursor;
+      pageCount += 1;
+
+      this.log.debug(
+        `Fetched page ${pageCount}, found ${result.keys.length} stale keys, total: ${allStaleKeys.length}`,
+      );
+
+      if (pageCount >= maxPages) {
+        this.log.warn(`Reached maximum page limit (${maxPages}), stopping pagination`);
+        break;
+      }
+    } while (cursor);
+
+    this.log.info(`Completed fetching stale keys: ${allStaleKeys.length} total from ${pageCount} pages`);
+
+    return allStaleKeys;
+  }
+}
+
+export default FastlyKVClient;

package/src/index.d.ts

@@ -128,6 +128,25 @@ export interface Suggestion {
   getUpdatedAt(): string;
 }
 
+export interface FastlyKVEntry {
+  key: string;
+  suggestionId: string;
+  url: string;
+}
+
+export class FastlyKVClient {
+  constructor(env: {
+    FASTLY_KV_STORE_ID: string;
+    FASTLY_API_TOKEN: string;
+    FASTLY_KV_TIMEOUT?: number;
+  }, log: any);
+
+  listAllStaleKeys(options?: {
+    pageSize?: number;
+    maxPages?: number;
+  }): Promise<FastlyKVEntry[]>;
+}
+
 /**
  * Base class for opportunity mappers
  * Extend this class to create custom mappers for new opportunity types

package/src/index.js

@@ -27,6 +27,8 @@ import { groupSuggestionsByUrlPath, filterEligibleSuggestions } from './utils/su
 import { getEffectiveBaseURL } from './utils/site-utils.js';
 import { fetchHtmlWithWarmup, calculateForwardedHost } from './utils/custom-html-utils.js';
 
+export { FastlyKVClient } from './fastly-kv-client.js';
+
 const HTTP_BAD_REQUEST = 400;
 const HTTP_INTERNAL_SERVER_ERROR = 500;
 const HTTP_NOT_IMPLEMENTED = 501;
@@ -304,7 +306,7 @@ class TokowakaClient {
       siteId,
       apiKeys: [apiKey],
       tokowakaEnabled: options.tokowakaEnabled ?? true,
-      enhancements: false,
+      enhancements: options.enhancements ?? false,
     };
 
     const s3Path = await this.uploadMetaconfig(url, metaconfig);
@@ -808,8 +810,8 @@ class TokowakaClient {
     }
 
     // TOKOWAKA_EDGE_URL is mandatory for preview
-    const tokowakaEdgeUrl = this.env.TOKOWAKA_EDGE_URL;
-    if (!hasText(tokowakaEdgeUrl)) {
+    const edgeUrl = this.env.TOKOWAKA_EDGE_URL;
+    if (!hasText(edgeUrl)) {
       throw this.#createError(
         'TOKOWAKA_EDGE_URL is required for preview functionality',
         HTTP_INTERNAL_SERVER_ERROR,
@@ -929,7 +931,7 @@ class TokowakaClient {
         previewUrl,
         apiKey,
         forwardedHost,
-        tokowakaEdgeUrl,
+        edgeUrl,
         this.log,
         false,
         options,
@@ -939,7 +941,7 @@ class TokowakaClient {
         previewUrl,
         apiKey,
         forwardedHost,
-        tokowakaEdgeUrl,
+        edgeUrl,
         this.log,
         true,
         options,

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

@@ -25,7 +25,7 @@ function sleep(ms) {
 
 /**
  * Makes an HTTP request with retry logic
- * Retries until max retries are exhausted or x-tokowaka-cache header is present
+ * Retries until max retries are exhausted or x-edge-optimize-cache header is present
  * @param {string} url - URL to fetch
  * @param {Object} options - Fetch options
  * @param {number} maxRetries - Maximum number of retries
@@ -48,10 +48,10 @@ async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetch
         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');
+      // Check for x-edge-optimize-cache header - if present, stop retrying
+      const cacheHeader = response.headers.get('x-edge-optimize-cache');
       if (cacheHeader) {
-        log.debug(`Cache header found (x-tokowaka-cache: ${cacheHeader}), stopping retry logic`);
+        log.debug(`Cache header found (x-edge-optimize-cache: ${cacheHeader}), stopping retry logic`);
         return response;
       }
 
@@ -65,7 +65,7 @@ async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetch
       } 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`);
+        throw new Error(`Cache header (x-edge-optimize-cache) not found after ${maxRetries} retries`);
       }
     } catch (error) {
       log.warn(`Attempt ${attempt} failed for ${fetchType} HTML, error: ${error.message}`);
@@ -86,12 +86,12 @@ async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetch
 }
 
 /**
- * Fetches HTML content from Tokowaka edge with warmup call and retry logic
+ * Fetches HTML content from 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} apiKey - Edge Optimize API key
  * @param {string} forwardedHost - Host to forward in x-forwarded-host header
- * @param {string} tokowakaEdgeUrl - Tokowaka edge URL
+ * @param {string} edgeUrl - Edge URL
  * @param {boolean} isOptimized - Whether to fetch optimized HTML (with preview param)
  * @param {Object} log - Logger instance
  * @param {Object} options - Additional options
@@ -105,7 +105,7 @@ export async function fetchHtmlWithWarmup(
   url,
   apiKey,
   forwardedHost,
-  tokowakaEdgeUrl,
+  edgeUrl,
   log,
   isOptimized = false,
   options = {},
@@ -116,14 +116,14 @@ export async function fetchHtmlWithWarmup(
   }
 
   if (!hasText(apiKey)) {
-    throw new Error('Tokowaka API key is required for fetching HTML');
+    throw new Error('Edge Optimize API key is required for fetching HTML');
   }
 
   if (!hasText(forwardedHost)) {
     throw new Error('Forwarded host is required for fetching HTML');
   }
 
-  if (!hasText(tokowakaEdgeUrl)) {
+  if (!hasText(edgeUrl)) {
     throw new Error('TOKOWAKA_EDGE_URL is not configured');
   }
 
@@ -139,18 +139,18 @@ 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 = `${tokowakaEdgeUrl}${urlPath}`;
+  let fullUrl = `${edgeUrl}${urlPath}`;
 
   const headers = {
     'x-forwarded-host': forwardedHost,
-    'x-tokowaka-api-key': apiKey,
-    'x-tokowaka-url': urlPath,
+    'x-edge-optimize-api-key': apiKey,
+    'x-edge-optimize-url': urlPath,
   };
 
   if (isOptimized) {
     // Add tokowakaPreview param for optimized HTML
     fullUrl = `${fullUrl}?tokowakaPreview=true`;
-    headers['x-tokowaka-url'] = `${urlPath}?tokowakaPreview=true`;
+    headers['x-edge-optimize-url'] = `${urlPath}?tokowakaPreview=true`;
   }
 
   const fetchOptions = {

package/test/fastly-kv-client.test.js

@@ -0,0 +1,254 @@
+/*
+ * Copyright 2026 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.
+ */
+
+/* eslint-env mocha */
+
+import { expect } from 'chai';
+import sinon from 'sinon';
+import nock from 'nock';
+import { FastlyKVClient } from '../src/fastly-kv-client.js';
+
+describe('FastlyKVClient', () => {
+  let sandbox;
+  let log;
+  let env;
+
+  const FASTLY_KV_API_BASE = 'https://api.fastly.com/resources/stores/kv';
+  const TEST_STORE_ID = 'test-store-id';
+  const TEST_API_TOKEN = 'test-api-token';
+
+  beforeEach(() => {
+    sandbox = sinon.createSandbox();
+    log = {
+      debug: sandbox.spy(),
+      info: sandbox.spy(),
+      warn: sandbox.spy(),
+      error: sandbox.spy(),
+    };
+    env = {
+      FASTLY_KV_STORE_ID: TEST_STORE_ID,
+      FASTLY_API_TOKEN: TEST_API_TOKEN,
+    };
+  });
+
+  afterEach(() => {
+    sandbox.restore();
+    nock.cleanAll();
+  });
+
+  describe('constructor', () => {
+    it('should create a client with valid configuration', () => {
+      const client = new FastlyKVClient(env, log);
+      expect(client.storeId).to.equal(TEST_STORE_ID);
+      expect(client.apiToken).to.equal(TEST_API_TOKEN);
+    });
+
+    it('should throw error if FASTLY_KV_STORE_ID is missing', () => {
+      delete env.FASTLY_KV_STORE_ID;
+      expect(() => new FastlyKVClient(env, log))
+        .to.throw('FASTLY_KV_STORE_ID environment variable is required');
+    });
+
+    it('should throw error if FASTLY_API_TOKEN is missing', () => {
+      delete env.FASTLY_API_TOKEN;
+      expect(() => new FastlyKVClient(env, log))
+        .to.throw('FASTLY_API_TOKEN environment variable is required');
+    });
+
+    it('should throw error if env is null', () => {
+      expect(() => new FastlyKVClient(null, log))
+        .to.throw('FASTLY_KV_STORE_ID environment variable is required');
+    });
+  });
+
+  describe('listAllStaleKeys', () => {
+    it('should fetch all pages of stale keys', async () => {
+      const client = new FastlyKVClient(env, log);
+      const keysPage1 = ['sugg-1'];
+      const keysPage2 = ['sugg-2'];
+      const staleValue = { url: 'https://example.com', status: 'stale' };
+
+      // Page 1
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query({ limit: '100' })
+        .reply(200, { data: keysPage1, meta: { next_cursor: 'cursor-1' } });
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keysPage1[0])}`)
+        .reply(200, JSON.stringify(staleValue));
+
+      // Page 2
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query({ limit: '100', cursor: 'cursor-1' })
+        .reply(200, { data: keysPage2, meta: {} });
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keysPage2[0])}`)
+        .reply(200, JSON.stringify(staleValue));
+
+      const result = await client.listAllStaleKeys();
+
+      expect(result).to.have.lengthOf(2);
+      expect(result[0].suggestionId).to.equal('sugg-1');
+      expect(result[1].suggestionId).to.equal('sugg-2');
+    });
+
+    it('should filter out non-stale keys', async () => {
+      const client = new FastlyKVClient(env, log);
+      const keys = ['sugg-stale', 'sugg-live'];
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query({ limit: '100' })
+        .reply(200, { data: keys, meta: {} });
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keys[0])}`)
+        .reply(200, JSON.stringify({ url: 'https://example.com/stale', status: 'stale' }));
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keys[1])}`)
+        .reply(200, JSON.stringify({ url: 'https://example.com/live', status: 'live' }));
+
+      const result = await client.listAllStaleKeys();
+
+      expect(result).to.have.lengthOf(1);
+      expect(result[0].suggestionId).to.equal('sugg-stale');
+      expect(result[0].url).to.equal('https://example.com/stale');
+    });
+
+    it('should respect maxPages limit', async () => {
+      const client = new FastlyKVClient(env, log);
+      const staleValue = { url: 'https://example.com', status: 'stale' };
+
+      // Always return a next cursor to simulate infinite pages
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query(true)
+        .times(3)
+        .reply(200, { data: ['sugg-1'], meta: { next_cursor: 'next' } });
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent('sugg-1')}`)
+        .times(3)
+        .reply(200, JSON.stringify(staleValue));
+
+      const result = await client.listAllStaleKeys({ maxPages: 3 });
+
+      expect(result).to.have.lengthOf(3);
+      expect(log.warn.calledWith(sinon.match(/Reached maximum page limit/))).to.be.true;
+    });
+
+    it('should return empty array if no stale keys found', async () => {
+      const client = new FastlyKVClient(env, log);
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query({ limit: '100' })
+        .reply(200, { data: [], meta: {} });
+
+      const result = await client.listAllStaleKeys();
+
+      expect(result).to.have.lengthOf(0);
+    });
+
+    it('should continue processing if individual key fetch fails', async () => {
+      const client = new FastlyKVClient(env, log);
+      const keys = ['sugg-fail', 'sugg-success'];
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query({ limit: '100' })
+        .reply(200, { data: keys, meta: {} });
+
+      // First key fails
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keys[0])}`)
+        .reply(500, 'Error');
+
+      // Second key succeeds
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keys[1])}`)
+        .reply(200, JSON.stringify({ url: 'https://example.com', status: 'stale' }));
+
+      const result = await client.listAllStaleKeys();
+
+      expect(result).to.have.lengthOf(1);
+      expect(result[0].suggestionId).to.equal('sugg-success');
+      expect(log.warn.called).to.be.true;
+    });
+
+    it('should handle non-JSON response gracefully', async () => {
+      const client = new FastlyKVClient(env, log);
+      const keys = ['sugg-1'];
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query({ limit: '100' })
+        .reply(200, { data: keys, meta: {} });
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keys[0])}`)
+        .reply(200, 'plain-text-value');
+
+      const result = await client.listAllStaleKeys();
+
+      // Non-JSON response gets status 'unknown', which is not 'stale', so filtered out
+      expect(result).to.have.lengthOf(0);
+      expect(log.warn.called).to.be.true;
+    });
+
+    it('should skip keys that return 404', async () => {
+      const client = new FastlyKVClient(env, log);
+      const keys = ['sugg-deleted', 'sugg-exists'];
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query({ limit: '100' })
+        .reply(200, { data: keys, meta: {} });
+
+      // First key returns 404
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keys[0])}`)
+        .reply(404, 'Not Found');
+
+      // Second key exists and is stale
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys/${encodeURIComponent(keys[1])}`)
+        .reply(200, JSON.stringify({ url: 'https://example.com', status: 'stale' }));
+
+      const result = await client.listAllStaleKeys();
+
+      // Only the existing stale key should be returned
+      expect(result).to.have.lengthOf(1);
+      expect(result[0].suggestionId).to.equal('sugg-exists');
+    });
+
+    it('should throw error when listing keys fails', async () => {
+      const client = new FastlyKVClient(env, log);
+
+      nock(FASTLY_KV_API_BASE)
+        .get(`/${TEST_STORE_ID}/keys`)
+        .query({ limit: '100' })
+        .reply(500, 'Internal Server Error');
+
+      try {
+        await client.listAllStaleKeys();
+        expect.fail('Should have thrown an error');
+      } catch (error) {
+        expect(error.message).to.include('Failed to list keys from KV Store');
+      }
+    });
+  });
+});

package/test/index.test.js

@@ -1924,7 +1924,7 @@ describe('TokowakaClient', () => {
         status: 200,
         statusText: 'OK',
         headers: {
-          get: (name) => (name === 'x-tokowaka-cache' ? 'HIT' : null),
+          get: (name) => (name === 'x-edge-optimize-cache' ? 'HIT' : null),
         },
         text: async () => '<html><body>Test HTML</body></html>',
       });

package/test/mappers/faq-mapper.test.js

@@ -744,7 +744,6 @@ Overall, Bulk positions itself as a better choice for sports nutrition through i
               question: 'Old Q?',
               answer: 'Old A.',
             },
-            tokowakaDeployed: 1704884400000,
             transformRules: {
               action: 'appendChild',
               selector: 'main',
@@ -1154,7 +1153,7 @@ Overall, Bulk positions itself as a better choice for sports nutrition through i
     });
   });
 
-  describe('tokowakaDeployed filtering', () => {
+  describe('edgeDeployed filtering', () => {
     it('should always create heading patch even when FAQ already deployed for URL', () => {
       const newSuggestion = {
         getId: () => 'sugg-new-1',

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

@@ -94,7 +94,7 @@ describe('HTML Utils', () => {
         );
         expect.fail('Should have thrown error');
       } catch (error) {
-        expect(error.message).to.equal('Tokowaka API key is required for fetching HTML');
+        expect(error.message).to.equal('Edge Optimize API key is required for fetching HTML');
       }
     });
 
@@ -104,7 +104,7 @@ describe('HTML Utils', () => {
         status: 200,
         statusText: 'OK',
         headers: {
-          get: (name) => (name === 'x-tokowaka-cache' ? 'HIT' : null),
+          get: (name) => (name === 'x-edge-optimize-cache' ? 'HIT' : null),
         },
         text: async () => '<html>Test HTML</html>',
       });
@@ -129,7 +129,7 @@ describe('HTML Utils', () => {
         status: 200,
         statusText: 'OK',
         headers: {
-          get: (name) => (name === 'x-tokowaka-cache' ? 'HIT' : null),
+          get: (name) => (name === 'x-edge-optimize-cache' ? 'HIT' : null),
         },
         text: async () => '<html>Optimized HTML</html>',
       });
@@ -285,7 +285,7 @@ describe('HTML Utils', () => {
       }
     });
 
-    it('should stop retrying when x-tokowaka-cache header is found', async () => {
+    it('should stop retrying when x-edge-optimize-cache header is found', async () => {
       // Warmup succeeds
       fetchStub.onCall(0).resolves({
         ok: true,
@@ -312,7 +312,7 @@ describe('HTML Utils', () => {
         status: 200,
         statusText: 'OK',
         headers: {
-          get: (name) => (name === 'x-tokowaka-cache' ? 'HIT' : null),
+          get: (name) => (name === 'x-edge-optimize-cache' ? 'HIT' : null),
         },
         text: async () => '<html>Cached HTML</html>',
       });
@@ -385,7 +385,7 @@ describe('HTML Utils', () => {
         expect.fail('Should have thrown error');
       } catch (error) {
         expect(error.message).to.include('Failed to fetch original HTML');
-        expect(error.message).to.include('Cache header (x-tokowaka-cache) not found after 2 retries');
+        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
@@ -409,7 +409,7 @@ describe('HTML Utils', () => {
         status: 200,
         statusText: 'OK',
         headers: {
-          get: (name) => (name === 'x-tokowaka-cache' ? 'HIT' : null),
+          get: (name) => (name === 'x-edge-optimize-cache' ? 'HIT' : null),
         },
         text: async () => '<html>Cached HTML</html>',
       });