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

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@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)
+
+
+### Bug Fixes
+
+* update tokowaka s3 config with patches ([#1263](https://github.com/adobe/spacecat-shared/issues/1263)) ([59605e9](https://github.com/adobe/spacecat-shared/commit/59605e9b75b7289029bd14e1832e594ea565296d))
+
+# [@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)
 
 

package/README.md

@@ -64,10 +64,12 @@ Creates a client instance from a context object.
 
 #### `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.
+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)
@@ -212,7 +214,17 @@ Domain-level metaconfig (created once per domain, shared by all URLs):
 {
   "siteId": "abc-123",
   "apiKeys": ["tokowaka-api-key-1"],
-  "prerender": true
+  "tokowakaEnabled": true,
+  "enhancements": true,
+  "prerender": {
+    "allowList": [],
+    "denyList": ["/*"]
+  },
+  "patches": {
+    "/products/item": true,
+    "/about": true,
+    "/contact": true
+  }
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "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.js

@@ -10,12 +10,19 @@
  * 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,
+  normalizePath,
+} from './utils/s3-utils.js';
 import { groupSuggestionsByUrlPath, filterEligibleSuggestions } from './utils/suggestion-utils.js';
 import { getEffectiveBaseURL } from './utils/site-utils.js';
 import { fetchHtmlWithWarmup, calculateForwardedHost } from './utils/custom-html-utils.js';
@@ -92,6 +99,44 @@ class TokowakaClient {
     return error;
   }
 
+  /**
+   * Updates the metaconfig with deployed endpoint paths
+   * @param {Object} metaconfig - Existing metaconfig object
+   * @param {Array<string>} deployedUrls - Array of successfully deployed URLs
+   * @param {string} baseUrl - Base URL for uploading metaconfig
+   * @returns {Promise<void>}
+   * @private
+   */
+  async #updateMetaconfigWithDeployedPaths(metaconfig, deployedUrls, baseUrl) {
+    if (!Array.isArray(deployedUrls) || deployedUrls.length === 0) {
+      return;
+    }
+
+    try {
+      // Initialize patches field if it doesn't exist
+      const updatedMetaconfig = {
+        ...metaconfig,
+        patches: { ...(metaconfig.patches || {}) },
+      };
+
+      // Extract normalized paths from deployed URLs and add to patches object
+      deployedUrls.forEach((url) => {
+        const urlObj = new URL(url);
+        const normalizedPath = normalizePath(urlObj.pathname);
+        updatedMetaconfig.patches[normalizedPath] = true;
+      });
+
+      await this.uploadMetaconfig(baseUrl, updatedMetaconfig);
+      this.log.info(`Updated metaconfig with ${deployedUrls.length} deployed endpoint(s)`);
+    } catch (error) {
+      this.log.error(`Failed to update metaconfig with deployed paths: ${error.message}`, error);
+      throw this.#createError(
+        `Failed to update metaconfig with deployed paths: ${error.message}`,
+        HTTP_INTERNAL_SERVER_ERROR,
+      );
+    }
+  }
+
   /**
    * Gets the list of CDN providers from environment configuration
    * Supports both single provider (string) and multiple providers (comma-separated string or array)
@@ -219,6 +264,56 @@ 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)
@@ -545,6 +640,9 @@ class TokowakaClient {
 
     this.log.info(`Uploaded Tokowaka configs for ${s3Paths.length} URLs`);
 
+    // Update metaconfig with deployed paths
+    await this.#updateMetaconfigWithDeployedPaths(metaconfig, deployedUrls, baseURL);
+
     // Invalidate CDN cache for all deployed URLs at once
     const cdnInvalidations = await this.invalidateCdnCache({ urls: deployedUrls });
 

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 = {
@@ -944,6 +1030,161 @@ describe('TokowakaClient', () => {
       expect(result.failedSuggestions[0].suggestion.getId()).to.equal('sugg-2');
     });
 
+    it('should update metaconfig patches field with deployed endpoints', async () => {
+      mockSuggestions = [
+        {
+          getId: () => 'sugg-1',
+          getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+          getData: () => ({
+            url: 'https://example.com/page1',
+            recommendedAction: 'Page 1 Heading',
+            checkType: 'heading-empty',
+            transformRules: {
+              action: 'replace',
+              selector: 'h1',
+            },
+          }),
+        },
+        {
+          getId: () => 'sugg-2',
+          getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+          getData: () => ({
+            url: 'https://example.com/page2',
+            recommendedAction: 'Page 2 Heading',
+            checkType: 'heading-empty',
+            transformRules: {
+              action: 'replace',
+              selector: 'h1',
+            },
+          }),
+        },
+      ];
+
+      const result = await client.deploySuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+      );
+
+      expect(result.succeededSuggestions).to.have.length(2);
+      // Verify uploadMetaconfig was called to update the metaconfig
+      expect(client.uploadMetaconfig).to.have.been.called;
+      // Check that the last call included the patches field
+      const { lastCall } = client.uploadMetaconfig;
+      expect(lastCall.args[1]).to.have.property('patches');
+      expect(lastCall.args[1].patches).to.deep.equal({
+        '/page1': true,
+        '/page2': true,
+      });
+    });
+
+    it('should add to existing patches in metaconfig when deploying new endpoints', async () => {
+      // Set up metaconfig with existing patches
+      // Reset the stub to provide consistent behavior
+      client.fetchMetaconfig.reset();
+      client.fetchMetaconfig.resolves({
+        siteId: 'site-123',
+        prerender: true,
+        patches: {
+          '/existing-page': true,
+        },
+      });
+
+      mockSuggestions = [
+        {
+          getId: () => 'sugg-1',
+          getUpdatedAt: () => '2025-01-15T10:00:00.000Z',
+          getData: () => ({
+            url: 'https://example.com/new-page',
+            recommendedAction: 'New Heading',
+            checkType: 'heading-empty',
+            transformRules: {
+              action: 'replace',
+              selector: 'h1',
+            },
+          }),
+        },
+      ];
+
+      await client.deploySuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+      );
+
+      // Verify the updated metaconfig includes both existing and new patches
+      const { lastCall } = client.uploadMetaconfig;
+      expect(lastCall.args[1].patches).to.deep.equal({
+        '/existing-page': true,
+        '/new-page': true,
+      });
+    });
+
+    it('should throw error when metaconfig update fails', async () => {
+      // Make uploadMetaconfig fail during the update
+      client.uploadMetaconfig.rejects(new Error('S3 upload error'));
+
+      try {
+        await client.deploySuggestions(
+          mockSite,
+          mockOpportunity,
+          mockSuggestions,
+        );
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error.message).to.include('Failed to update metaconfig with deployed paths');
+        expect(error.status).to.equal(500);
+      }
+    });
+
+    it('should return early when no eligible suggestions to deploy', async () => {
+      // All suggestions are ineligible
+      mockSuggestions = [
+        {
+          getId: () => 'sugg-1',
+          getData: () => ({
+            url: 'https://example.com/page1',
+            recommendedAction: 'New Heading',
+            checkType: 'heading-missing', // Not eligible
+          }),
+        },
+      ];
+
+      const result = await client.deploySuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+      );
+
+      // No suggestions deployed - returns early before metaconfig check
+      expect(result.succeededSuggestions).to.have.length(0);
+      expect(result.failedSuggestions).to.have.length(1);
+      // fetchMetaconfig should not be called at all (returns before that point)
+      expect(client.fetchMetaconfig).to.not.have.been.called;
+      // uploadMetaconfig should not be called at all
+      expect(client.uploadMetaconfig).to.not.have.been.called;
+    });
+
+    it('should not update metaconfig when all URLs fail to generate configs', async () => {
+      // Stub generateConfig to return null (no config generated)
+      sinon.stub(client, 'generateConfig').returns(null);
+
+      const result = await client.deploySuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+      );
+
+      // Suggestions are marked as succeeded (eligible) but no configs uploaded
+      expect(result.succeededSuggestions).to.have.length(2);
+      expect(result.s3Paths).to.have.length(0); // No configs uploaded
+      // fetchMetaconfig called once for initial check, but not for update
+      // since no URLs were actually deployed (deployedUrls is empty)
+      expect(client.fetchMetaconfig).to.have.been.calledOnce;
+      // uploadMetaconfig should not be called at all
+      expect(client.uploadMetaconfig).to.not.have.been.called;
+    });
+
     it('should skip URL when generateConfig returns no patches', async () => {
       // Stub mapper to return empty patches for the first call, normal for subsequent calls
       const mapper = client.mapperRegistry.getMapper('headings');