@adobe/spacecat-shared-tokowaka-client 1.4.4 → 1.4.6

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.4.6](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.4.5...@adobe/spacecat-shared-tokowaka-client-v1.4.6) (2026-01-13)
+
+
+### Bug Fixes
+
+* add api to create/update s3 edge config ([#1260](https://github.com/adobe/spacecat-shared/issues/1260)) ([b5cfff2](https://github.com/adobe/spacecat-shared/commit/b5cfff29cdb6fa29e1b440f86eb86cf8dd471e43))
+
+# [@adobe/spacecat-shared-tokowaka-client-v1.4.5](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.4.4...@adobe/spacecat-shared-tokowaka-client-v1.4.5) (2026-01-07)
+
+
+### Bug Fixes
+
+* fetch api key from s3 and fix invalidation sequence ([#1251](https://github.com/adobe/spacecat-shared/issues/1251)) ([fe66bd6](https://github.com/adobe/spacecat-shared/commit/fe66bd6732dc200ab4df27babc1e0831f6187271))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.4.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.4.3...@adobe/spacecat-shared-tokowaka-client-v1.4.4) (2026-01-05)
 
 

package/README.md

@@ -146,21 +146,17 @@ The client invalidates CDN cache after uploading configurations. Failures are lo
 
 ## Site Configuration
 
-Sites must have the following configuration in their `tokowakaConfig`:
+Sites must have the `tokowakaConfig` field in their site-config to confirm that tokowaka is enabled for that particular site.
 
 ```javascript
 {
+  ...
   "tokowakaConfig": {
-    "apiKey": "legacy-key-kept-for-backward-compatibility", // Optional, kept for backward compatibility
-    "forwardedHost": "www.example.com"  // Required for preview functionality
+    "enabled": true
   }
 }
 ```
 
-**Note:** 
-- `apiKey` is optional and **not used** for S3 paths or HTTP headers (kept in schema for potential future use)
-- `forwardedHost` is **required** for preview functionality to fetch HTML from Tokowaka edge
-
 ## Supported Opportunity Types
 
 ### Headings
@@ -215,6 +211,7 @@ Domain-level metaconfig (created once per domain, shared by all URLs):
 ```json
 {
   "siteId": "abc-123",
+  "apiKeys": ["tokowaka-api-key-1"],
   "prerender": true
 }
 ```
@@ -308,7 +305,7 @@ TOKOWAKA_CDN_CONFIG='{"cloudfront":{"distributionId":"...","region":"us-east-1"}
 
 **Behavior:**
 - All URLs are batched into a single invalidation request per provider
-- All CDN providers are invalidated in parallel using `Promise.all()`
+- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Tokowaka Client for SpaceCat - Edge optimization config management",
   "type": "module",
   "engines": {
@@ -38,7 +38,8 @@
     "@aws-sdk/client-cloudfront": "3.940.0",
     "@aws-sdk/client-s3": "3.940.0",
     "mdast-util-from-markdown": "2.0.2",
-    "mdast-util-to-hast": "12.3.0"
+    "mdast-util-to-hast": "12.3.0",
+    "uuid": "11.0.5"
   },
   "devDependencies": {
     "aws-sdk-client-mock": "4.1.0",

package/src/index.d.ts

@@ -34,6 +34,7 @@ export const TARGET_USER_AGENTS_CATEGORIES: {
 
 export interface TokowakaMetaconfig {
   siteId: string;
+  apiKeys?: string[];
   prerender?: {
     allowList?: string[];
   } | boolean;

package/src/index.js

@@ -10,15 +10,17 @@
  * governing permissions and limitations under the License.
  */
 
+import crypto from 'crypto';
 import { GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
 import { hasText, isNonEmptyObject } from '@adobe/spacecat-shared-utils';
+import { v4 as uuidv4 } from 'uuid';
 import MapperRegistry from './mappers/mapper-registry.js';
 import CdnClientRegistry from './cdn/cdn-client-registry.js';
 import { mergePatches } from './utils/patch-utils.js';
-import { getTokowakaConfigS3Path, getTokowakaMetaconfigS3Path } from './utils/s3-utils.js';
+import { getTokowakaConfigS3Path, getTokowakaMetaconfigS3Path, getHostName } from './utils/s3-utils.js';
 import { groupSuggestionsByUrlPath, filterEligibleSuggestions } from './utils/suggestion-utils.js';
 import { getEffectiveBaseURL } from './utils/site-utils.js';
-import { fetchHtmlWithWarmup } from './utils/custom-html-utils.js';
+import { fetchHtmlWithWarmup, calculateForwardedHost } from './utils/custom-html-utils.js';
 
 const HTTP_BAD_REQUEST = 400;
 const HTTP_INTERNAL_SERVER_ERROR = 500;
@@ -219,10 +221,60 @@ class TokowakaClient {
     }
   }
 
+  /**
+   * Generates an API key for Tokowaka based on domain
+   * @param {string} domain - Domain name (e.g., 'example.com')
+   * @returns {string} - Base64 URL-encoded API key
+   * @private
+   */
+  /* eslint-disable class-methods-use-this */
+  #generateApiKey(normalizedHostName) {
+    const uuid = uuidv4();
+    return crypto
+      .createHash('sha256')
+      .update(`${uuid}${normalizedHostName}`)
+      .digest('base64url');
+  }
+
+  /**
+   * Creates and uploads domain-level metaconfig to S3
+   * Generates a new API key and creates the metaconfig structure
+   * @param {string} url - Full URL (used to extract domain)
+   * @param {string} siteId - Site ID
+   * @param {Object} options - Optional configuration
+   * @param {boolean} options.tokowakaEnabled - Whether to enable Tokowaka (default: true)
+   * @returns {Promise<Object>} - Object with s3Path and metaconfig
+   */
+  async createMetaconfig(url, siteId, options = {}) {
+    if (!hasText(url)) {
+      throw this.#createError('URL is required', HTTP_BAD_REQUEST);
+    }
+
+    if (!hasText(siteId)) {
+      throw this.#createError('Site ID is required', HTTP_BAD_REQUEST);
+    }
+
+    const normalizedHostName = getHostName(url, this.log);
+    const apiKey = this.#generateApiKey(normalizedHostName);
+
+    const metaconfig = {
+      siteId,
+      apiKeys: [apiKey],
+      tokowakaEnabled: options.tokowakaEnabled ?? true,
+      enhancements: false,
+    };
+
+    const s3Path = await this.uploadMetaconfig(url, metaconfig);
+
+    this.log.info(`Created new Tokowaka metaconfig for ${normalizedHostName} at ${s3Path}`);
+
+    return metaconfig;
+  }
+
   /**
    * Uploads domain-level metaconfig to S3
    * @param {string} url - Full URL (used to extract domain)
-   * @param {Object} metaconfig - Metaconfig object (siteId, prerender)
+   * @param {Object} metaconfig - Metaconfig object (siteId, apiKeys, prerender)
    * @returns {Promise<string>} - S3 key of uploaded metaconfig
    */
   async uploadMetaconfig(url, metaconfig) {
@@ -373,7 +425,7 @@ class TokowakaClient {
 
   /**
    * CDN cache invalidation method that supports invalidating URL configs
-   * or custom S3 paths across provided or default CDN providers
+   * or custom S3 paths across provided or default CDN providers.
    * @param {Object} options - Invalidation options
    * @param {Array<string>} options.urls - Array of full URLs to invalidate (for URL configs)
    * @param {Array<string>} options.paths - Custom S3 paths to invalidate directly
@@ -416,37 +468,37 @@ class TokowakaClient {
       + `via providers: ${providerList.join(', ')}`,
     );
 
-    // Invalidate all providers in parallel
-    const invalidationPromises = providerList.map(async (provider) => {
+    const results = [];
+    for (const provider of providerList) {
       try {
         const cdnClient = this.cdnClientRegistry.getClient(provider);
         if (!cdnClient) {
           this.log.warn(`No CDN client available for provider: ${provider}`);
-          return {
+          results.push({
             status: 'error',
             provider,
             message: `No CDN client available for provider: ${provider}`,
-          };
+          });
+          // eslint-disable-next-line no-continue
+          continue;
         }
 
+        // 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)`,
         );
-        return result;
+        results.push(result);
       } catch (error) {
         this.log.warn(`Failed to invalidate ${provider} CDN cache: ${error.message}`, error);
-        return {
+        results.push({
           status: 'error',
           provider,
           message: error.message,
-        };
+        });
       }
-    });
-
-    // Wait for all provider invalidations to complete
-    const results = await Promise.all(invalidationPromises);
+    }
     return results;
   }
 
@@ -699,17 +751,6 @@ class TokowakaClient {
    * @returns {Promise<Object>} - Preview result with config and succeeded/failed suggestions
    */
   async previewSuggestions(site, opportunity, suggestions, options = {}) {
-    // Get site's forwarded host for preview
-    const { forwardedHost, apiKey } = site.getConfig()?.getTokowakaConfig() || {};
-
-    if (!hasText(forwardedHost) || !hasText(apiKey)) {
-      throw this.#createError(
-        'Site does not have a Tokowaka API key or forwarded host configured. '
-        + 'Please onboard the site to Tokowaka first.',
-        HTTP_BAD_REQUEST,
-      );
-    }
-
     const opportunityType = opportunity.getType();
     const mapper = this.mapperRegistry.getMapper(opportunityType);
     if (!mapper) {
@@ -755,6 +796,29 @@ 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);
+
+    if (!metaconfig) {
+      throw this.#createError(
+        'No domain-level metaconfig found. '
+        + 'A domain-level metaconfig needs to be created first before previewing suggestions.',
+        HTTP_INTERNAL_SERVER_ERROR,
+      );
+    }
+
+    const { apiKeys } = metaconfig;
+    if (!Array.isArray(apiKeys) || apiKeys.length === 0 || !hasText(apiKeys[0])) {
+      throw this.#createError(
+        'Metaconfig does not have valid API keys configured. '
+        + 'Please ensure the metaconfig has at least one API key.',
+        HTTP_INTERNAL_SERVER_ERROR,
+      );
+    }
+
+    const apiKey = apiKeys[0];
+    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);

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

@@ -193,3 +193,29 @@ export async function fetchHtmlWithWarmup(
     throw new Error(errorMsg);
   }
 }
+
+export function calculateForwardedHost(url, logger = console) {
+  try {
+    const urlObj = new URL(url);
+    const { hostname } = urlObj;
+
+    // If hostname already starts with www., keep it as is
+    if (hostname.startsWith('www.')) {
+      logger.debug(`Forwarded host: ${hostname}`);
+      return hostname;
+    }
+
+    // Count dots to determine if it's a bare domain or has a subdomain
+    const dotCount = (hostname.match(/\./g) || []).length;
+
+    // If only 1 dot (bare domain like example.com), prepend www.
+    // If 2+ dots (subdomain like subdomain.example.com), keep as is
+    const forwardedHost = dotCount === 1 ? `www.${hostname}` : hostname;
+
+    logger.debug(`Forwarded host: ${forwardedHost}`);
+    return forwardedHost;
+  } catch (error) {
+    logger.error(`Error calculating forwarded host from URL ${url}: ${error.message}`);
+    throw new Error(`Error calculating forwarded host from URL ${url}: ${error.message}`);
+  }
+}

package/src/utils/s3-utils.js

@@ -35,10 +35,17 @@ export function normalizePath(pathname) {
  * @returns {string} - Normalized hostname
  * @throws {Error} - If hostname extraction fails
  */
-export function getHostName(url, logger) {
+export function getHostName(url, logger = console) {
   try {
-    const finalHostname = url.hostname.replace(/^www\./, '');
-    return finalHostname;
+    let urlObj;
+    if (url instanceof URL) {
+      urlObj = url;
+    } else if (typeof url === 'string') {
+      urlObj = new URL(url);
+    } else {
+      throw new TypeError('Input must be a URL or a string');
+    }
+    return urlObj.hostname.replace(/^www\./, '');
   } catch (error) {
     logger.error(`Error extracting host name: ${error.message}`);
     throw new Error(`Error extracting host name: ${url.toString()}`);

package/test/index.test.js

@@ -456,6 +456,92 @@ describe('TokowakaClient', () => {
     });
   });
 
+  describe('createMetaconfig', () => {
+    it('should create metaconfig with generated API key and default options', async () => {
+      const siteId = 'site-123';
+      const url = 'https://www.example.com/page1';
+
+      const result = await client.createMetaconfig(url, siteId);
+
+      expect(result).to.have.property('siteId', siteId);
+      expect(result).to.have.property('apiKeys');
+      expect(result.apiKeys).to.be.an('array').with.lengthOf(1);
+      expect(result.apiKeys[0]).to.be.a('string');
+      expect(result).to.have.property('tokowakaEnabled', true);
+      expect(result).to.have.property('enhancements', false);
+
+      // Verify uploadMetaconfig was called with correct metaconfig
+      expect(s3Client.send).to.have.been.calledOnce;
+      const command = s3Client.send.firstCall.args[0];
+      expect(command.input.Bucket).to.equal('test-bucket');
+      expect(command.input.Key).to.equal('opportunities/example.com/config');
+    });
+
+    it('should create metaconfig with tokowakaEnabled set to false', async () => {
+      const siteId = 'site-123';
+      const url = 'https://example.com';
+
+      const result = await client.createMetaconfig(url, siteId, { tokowakaEnabled: false });
+
+      expect(result).to.have.property('tokowakaEnabled', false);
+      expect(result).to.have.property('enhancements', false);
+      expect(result.apiKeys).to.have.lengthOf(1);
+    });
+
+    it('should create metaconfig with tokowakaEnabled set to true explicitly', async () => {
+      const siteId = 'site-123';
+      const url = 'https://example.com';
+
+      const result = await client.createMetaconfig(url, siteId, { tokowakaEnabled: true });
+
+      expect(result).to.have.property('tokowakaEnabled', true);
+      expect(result).to.have.property('enhancements', false);
+    });
+
+    it('should throw error if URL is missing', async () => {
+      try {
+        await client.createMetaconfig('', 'site-123');
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('URL is required');
+        expect(error.status).to.equal(400);
+      }
+    });
+
+    it('should throw error if siteId is missing', async () => {
+      try {
+        await client.createMetaconfig('https://example.com', '');
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('Site ID is required');
+        expect(error.status).to.equal(400);
+      }
+    });
+
+    it('should handle S3 upload failure', async () => {
+      const s3Error = new Error('S3 network error');
+      s3Client.send.rejects(s3Error);
+
+      try {
+        await client.createMetaconfig('https://example.com', 'site-123');
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('S3 upload failed');
+        expect(error.status).to.equal(500);
+      }
+    });
+
+    it('should strip www. from domain in metaconfig path', async () => {
+      const siteId = 'site-123';
+      const url = 'https://www.example.com/some/path';
+
+      await client.createMetaconfig(url, siteId);
+
+      const command = s3Client.send.firstCall.args[0];
+      expect(command.input.Key).to.equal('opportunities/example.com/config');
+    });
+  });
+
   describe('uploadConfig', () => {
     it('should upload config to S3', async () => {
       const config = {
@@ -1698,6 +1784,12 @@ describe('TokowakaClient', () => {
       // Stub fetchConfig to return null by default (no existing config)
       sinon.stub(client, 'fetchConfig').resolves(null);
 
+      // Stub fetchMetaconfig to return metaconfig with apiKeys array
+      sinon.stub(client, 'fetchMetaconfig').resolves({
+        siteId: 'site-123',
+        apiKeys: ['test-api-key-1', 'test-api-key-2'],
+      });
+
       // Add TOKOWAKA_EDGE_URL to env
       client.env.TOKOWAKA_EDGE_URL = 'https://edge-dev.tokowaka.now';
     });
@@ -1804,31 +1896,60 @@ describe('TokowakaClient', () => {
       }
     });
 
-    it('should throw error if site does not have forwardedHost', async () => {
-      mockSite.getConfig = () => ({
-        getTokowakaConfig: () => ({}),
+    it('should throw error if metaconfig does not exist', async () => {
+      client.fetchMetaconfig.resolves(null);
+
+      try {
+        await client.previewSuggestions(mockSite, mockOpportunity, mockSuggestions);
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('No domain-level metaconfig found');
+        expect(error.status).to.equal(500);
+      }
+    });
+
+    it('should throw error if metaconfig does not have apiKeys', async () => {
+      client.fetchMetaconfig.resolves({
+        siteId: 'site-123',
+        // apiKeys missing
       });
 
       try {
         await client.previewSuggestions(mockSite, mockOpportunity, mockSuggestions);
         expect.fail('Should have thrown error');
       } catch (error) {
-        expect(error.message).to.include('Site does not have a Tokowaka API key or forwarded host configured');
-        expect(error.status).to.equal(400);
+        expect(error.message).to.include('Metaconfig does not have valid API keys configured');
+        expect(error.status).to.equal(500);
       }
     });
 
-    it('should throw error if getTokowakaConfig returns null', async () => {
-      mockSite.getConfig = () => ({
-        getTokowakaConfig: () => null,
+    it('should throw error if metaconfig has empty apiKeys array', async () => {
+      client.fetchMetaconfig.resolves({
+        siteId: 'site-123',
+        apiKeys: [],
       });
 
       try {
         await client.previewSuggestions(mockSite, mockOpportunity, mockSuggestions);
         expect.fail('Should have thrown error');
       } catch (error) {
-        expect(error.message).to.include('Site does not have a Tokowaka API key or forwarded host configured');
-        expect(error.status).to.equal(400);
+        expect(error.message).to.include('Metaconfig does not have valid API keys configured');
+        expect(error.status).to.equal(500);
+      }
+    });
+
+    it('should throw error if metaconfig apiKeys first value is empty', async () => {
+      client.fetchMetaconfig.resolves({
+        siteId: 'site-123',
+        apiKeys: ['', 'test-api-key-2'],
+      });
+
+      try {
+        await client.previewSuggestions(mockSite, mockOpportunity, mockSuggestions);
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('Metaconfig does not have valid API keys configured');
+        expect(error.status).to.equal(500);
       }
     });
 

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

@@ -14,7 +14,7 @@
 
 import { expect } from 'chai';
 import sinon from 'sinon';
-import { fetchHtmlWithWarmup } from '../../src/utils/custom-html-utils.js';
+import { fetchHtmlWithWarmup, calculateForwardedHost } from '../../src/utils/custom-html-utils.js';
 
 describe('HTML Utils', () => {
   describe('fetchHtmlWithWarmup', () => {
@@ -429,4 +429,104 @@ describe('HTML Utils', () => {
       expect(fetchStub.callCount).to.equal(2); // warmup + 1 actual
     });
   });
+
+  describe('calculateForwardedHost', () => {
+    let log;
+
+    beforeEach(() => {
+      log = {
+        debug: sinon.stub(),
+        warn: sinon.stub(),
+        error: sinon.stub(),
+        info: sinon.stub(),
+      };
+    });
+
+    afterEach(() => {
+      sinon.restore();
+    });
+
+    it('should add www prefix to bare domain', async () => {
+      const result = calculateForwardedHost('https://example.com/page', log);
+      expect(result).to.equal('www.example.com');
+    });
+
+    it('should keep www prefix when already present', async () => {
+      const result = calculateForwardedHost('https://www.example.com/page', log);
+      expect(result).to.equal('www.example.com');
+    });
+
+    it('should keep subdomain without adding www', async () => {
+      const result = calculateForwardedHost('https://subdomain.example.com/page', log);
+      expect(result).to.equal('subdomain.example.com');
+    });
+
+    it('should keep www.subdomain as is', async () => {
+      const result = calculateForwardedHost('https://www.subdomain.example.com/page', log);
+      expect(result).to.equal('www.subdomain.example.com');
+    });
+
+    it('should add www to bare domain with port', async () => {
+      const result = calculateForwardedHost('https://example.com:8080/page', log);
+      expect(result).to.equal('www.example.com');
+    });
+
+    it('should keep www with port', async () => {
+      const result = calculateForwardedHost('https://www.example.com:8080/page', log);
+      expect(result).to.equal('www.example.com');
+    });
+
+    it('should handle URL with query parameters', async () => {
+      const result = calculateForwardedHost('https://example.com/page?param=value', log);
+      expect(result).to.equal('www.example.com');
+    });
+
+    it('should handle URL with hash fragment', async () => {
+      const result = calculateForwardedHost('https://example.com/page#section', log);
+      expect(result).to.equal('www.example.com');
+    });
+
+    it('should handle http protocol', async () => {
+      const result = calculateForwardedHost('http://example.com/page', log);
+      expect(result).to.equal('www.example.com');
+    });
+
+    it('should handle deep subdomains', async () => {
+      const result = calculateForwardedHost('https://level1.level2.example.com/page', log);
+      expect(result).to.equal('level1.level2.example.com');
+    });
+
+    it('should throw error for invalid URL', async () => {
+      try {
+        calculateForwardedHost('not-a-valid-url', log);
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('Error calculating forwarded host from URL');
+        expect(error.message).to.include('not-a-valid-url');
+        expect(log.error).to.have.been.calledOnce;
+      }
+    });
+
+    it('should throw error for empty URL', async () => {
+      try {
+        calculateForwardedHost('', log);
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('Error calculating forwarded host from URL');
+        expect(log.error).to.have.been.calledOnce;
+      }
+    });
+
+    it('should use console as default logger when not provided', async () => {
+      const result = calculateForwardedHost('https://example.com/page');
+      expect(result).to.equal('www.example.com');
+    });
+
+    it('should handle hostname with no dots (edge case)', async () => {
+      // This is an edge case for localhost or single-word hostnames
+      const result = calculateForwardedHost('http://localhost/page', log);
+      // No dots means dotCount = 0, so it won't match dotCount === 1, keeps as is
+      expect(result).to.equal('localhost');
+    });
+  });
 });