@adobe/spacecat-shared-tokowaka-client 1.5.8 → 1.6.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.6.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.6.0...@adobe/spacecat-shared-tokowaka-client-v1.6.1) (2026-01-30)
+
+
+### Bug Fixes
+
+* api key now optional for edge-preview ([#1299](https://github.com/adobe/spacecat-shared/issues/1299)) ([76eb046](https://github.com/adobe/spacecat-shared/commit/76eb04640dab752a83909a51827abde1e41fc57e))
+
+# [@adobe/spacecat-shared-tokowaka-client-v1.6.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.8...@adobe/spacecat-shared-tokowaka-client-v1.6.0) (2026-01-29)
+
+
+### Features
+
+* new flag opted added in edgeoptimizeconfig ([#1294](https://github.com/adobe/spacecat-shared/issues/1294)) ([8386e38](https://github.com/adobe/spacecat-shared/commit/8386e3805e9e67c18e4569428bef7ac5723eb991))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.5.8](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.7...@adobe/spacecat-shared-tokowaka-client-v1.5.8) (2026-01-27)
 
 

package/package.json

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

package/src/index.js

@@ -290,7 +290,7 @@ class TokowakaClient {
    * @param {boolean} options.enhancements - Whether to enable enhancements (default: true)
    * @returns {Promise<Object>} - Object with s3Path and metaconfig
    */
-  async createMetaconfig(url, siteId, options = {}) {
+  async createMetaconfig(url, siteId, options = {}, metadata = {}) {
     if (!hasText(url)) {
       throw this.#createError('URL is required', HTTP_BAD_REQUEST);
     }
@@ -316,8 +316,7 @@ class TokowakaClient {
       patches: {},
     };
 
-    const s3Path = await this.uploadMetaconfig(url, metaconfig);
-
+    const s3Path = await this.uploadMetaconfig(url, metaconfig, metadata);
     this.log.info(`Created new Tokowaka metaconfig for ${normalizedHostName} at ${s3Path}`);
 
     return metaconfig;
@@ -331,7 +330,7 @@ class TokowakaClient {
    * @param {Object} options - Optional configuration
    * @returns {Promise<Object>} - Object with s3Path and metaconfig
    */
-  async updateMetaconfig(url, siteId, options = {}) {
+  async updateMetaconfig(url, siteId, options = {}, metadata = {}) {
     if (!hasText(url)) {
       throw this.#createError('URL is required', HTTP_BAD_REQUEST);
     }
@@ -371,8 +370,7 @@ class TokowakaClient {
       ...(hasPrerender && { prerender }),
     };
 
-    const s3Path = await this.uploadMetaconfig(url, metaconfig);
-
+    const s3Path = await this.uploadMetaconfig(url, metaconfig, metadata);
     this.log.info(`Updated Tokowaka metaconfig for ${normalizedHostName} at ${s3Path}`);
 
     return metaconfig;
@@ -382,9 +380,10 @@ class TokowakaClient {
    * Uploads domain-level metaconfig to S3
    * @param {string} url - Full URL (used to extract domain)
    * @param {Object} metaconfig - Metaconfig object (siteId, apiKeys, prerender)
+   * @param {Object} metadata - Optional S3 user-defined metadata (key-value pairs)
    * @returns {Promise<string>} - S3 key of uploaded metaconfig
-   */
-  async uploadMetaconfig(url, metaconfig) {
+  */
+  async uploadMetaconfig(url, metaconfig, metadata = {}) {
     if (!hasText(url)) {
       throw this.#createError('URL is required', HTTP_BAD_REQUEST);
     }
@@ -397,12 +396,19 @@ class TokowakaClient {
     const bucketName = this.deployBucketName;
 
     try {
-      const command = new PutObjectCommand({
+      const putObjectParams = {
         Bucket: bucketName,
         Key: s3Path,
         Body: JSON.stringify(metaconfig, null, 2),
         ContentType: 'application/json',
-      });
+      };
+
+      // Add user-defined metadata if provided
+      if (isNonEmptyObject(metadata)) {
+        putObjectParams.Metadata = metadata;
+      }
+
+      const command = new PutObjectCommand(putObjectParams);
 
       await this.s3Client.send(command);
       this.log.info(`Successfully uploaded metaconfig to s3://${bucketName}/${s3Path}`);
@@ -907,26 +913,13 @@ class TokowakaClient {
     }
 
     // Fetch metaconfig to get API key
-    const metaconfig = await this.fetchMetaconfig(previewUrl);
+    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,
-      );
+    let apiKey;
+    if (Array.isArray(metaconfig.apiKeys) && metaconfig.apiKeys.length > 0) {
+      [apiKey] = metaconfig.apiKeys;
     }
 
-    const apiKey = apiKeys[0];
     const forwardedHost = calculateForwardedHost(previewUrl, this.log);
 
     // Fetch existing deployed configuration for this URL from production S3

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

@@ -104,7 +104,7 @@ async function fetchWithRetry(url, options, maxRetries, retryDelayMs, log, fetch
  * 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 - Edge Optimize API key
+ * @param {string} apiKey - Edge Optimize API key (optional)
  * @param {string} forwardedHost - Host to forward in x-forwarded-host header
  * @param {string} edgeUrl - Edge URL
  * @param {boolean} isOptimized - Whether to fetch optimized HTML (with preview param)
@@ -130,10 +130,6 @@ export async function fetchHtmlWithWarmup(
     throw new Error('URL is required for fetching HTML');
   }
 
-  if (!hasText(apiKey)) {
-    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');
   }
@@ -158,7 +154,7 @@ export async function fetchHtmlWithWarmup(
 
   const headers = {
     'x-forwarded-host': forwardedHost,
-    'x-edgeoptimize-api-key': apiKey,
+    ...(apiKey && { 'x-edgeoptimize-api-key': apiKey }),
     'x-edgeoptimize-url': urlPath,
     'Accept-Encoding': 'identity', // Disable compression to avoid content-length: 0 issue
   };

package/test/index.test.js

@@ -454,6 +454,43 @@ describe('TokowakaClient', () => {
         expect(error.status).to.equal(500);
       }
     });
+
+    it('should upload metaconfig with user-defined metadata when provided', async () => {
+      const metaconfig = {
+        siteId: 'site-123',
+        prerender: true,
+      };
+      const metadata = {
+        'last-modified-by': 'john@example.com',
+        'created-by': 'admin',
+      };
+
+      const s3Path = await client.uploadMetaconfig('https://example.com/page1', metaconfig, metadata);
+
+      expect(s3Path).to.equal('opportunities/example.com/config');
+
+      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');
+      expect(command.input.ContentType).to.equal('application/json');
+      expect(JSON.parse(command.input.Body)).to.deep.equal(metaconfig);
+      expect(command.input.Metadata).to.deep.equal(metadata);
+    });
+
+    it('should upload metaconfig without Metadata field when metadata is empty object', async () => {
+      const metaconfig = {
+        siteId: 'site-123',
+        prerender: true,
+      };
+
+      const s3Path = await client.uploadMetaconfig('https://example.com/page1', metaconfig, {});
+
+      expect(s3Path).to.equal('opportunities/example.com/config');
+
+      const command = s3Client.send.firstCall.args[0];
+      expect(command.input.Bucket).to.equal('test-bucket');
+      expect(command.input.Metadata).to.be.undefined;
+    });
   });
 
   describe('createMetaconfig', () => {
@@ -567,6 +604,50 @@ describe('TokowakaClient', () => {
       const command = s3Client.send.firstCall.args[0];
       expect(command.input.Key).to.equal('opportunities/example.com/config');
     });
+
+    it('should include user-defined metadata when metadata is provided', async () => {
+      const siteId = 'site-123';
+      const url = 'https://www.example.com/page1';
+      const noSuchKeyError = new Error('NoSuchKey');
+      noSuchKeyError.name = 'NoSuchKey';
+      s3Client.send.onFirstCall().rejects(noSuchKeyError);
+
+      await client.createMetaconfig(url, siteId, {}, { 'last-modified-by': 'john@example.com' });
+
+      // Second call is the uploadMetaconfig
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      expect(uploadCommand.input.Metadata).to.deep.equal({
+        'last-modified-by': 'john@example.com',
+      });
+    });
+
+    it('should not include metadata when metadata is empty object', async () => {
+      const siteId = 'site-123';
+      const url = 'https://www.example.com/page1';
+      const noSuchKeyError = new Error('NoSuchKey');
+      noSuchKeyError.name = 'NoSuchKey';
+      s3Client.send.onFirstCall().rejects(noSuchKeyError);
+
+      await client.createMetaconfig(url, siteId, {}, {});
+
+      // Second call is the uploadMetaconfig
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      expect(uploadCommand.input.Metadata).to.be.undefined;
+    });
+
+    it('should not include metadata when metadata is not provided', async () => {
+      const siteId = 'site-123';
+      const url = 'https://www.example.com/page1';
+      const noSuchKeyError = new Error('NoSuchKey');
+      noSuchKeyError.name = 'NoSuchKey';
+      s3Client.send.onFirstCall().rejects(noSuchKeyError);
+
+      await client.createMetaconfig(url, siteId);
+
+      // Second call is the uploadMetaconfig
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      expect(uploadCommand.input.Metadata).to.be.undefined;
+    });
   });
 
   describe('updateMetaconfig', () => {
@@ -1308,6 +1389,47 @@ describe('TokowakaClient', () => {
       expect(result).to.have.property('prerender');
       expect(result.prerender).to.deep.equal(prerenderConfig);
     });
+
+    it('should include user-defined metadata when metadata is provided', async () => {
+      const siteId = 'site-456';
+      const url = 'https://www.example.com';
+
+      await client.updateMetaconfig(url, siteId, {
+        tokowakaEnabled: true,
+      }, { 'last-modified-by': 'jane@example.com' });
+
+      // Second call is the uploadMetaconfig
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      expect(uploadCommand.input.Metadata).to.deep.equal({
+        'last-modified-by': 'jane@example.com',
+      });
+    });
+
+    it('should not include metadata when metadata is empty object', async () => {
+      const siteId = 'site-456';
+      const url = 'https://www.example.com';
+
+      await client.updateMetaconfig(url, siteId, {
+        tokowakaEnabled: true,
+      }, {});
+
+      // Second call is the uploadMetaconfig
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      expect(uploadCommand.input.Metadata).to.be.undefined;
+    });
+
+    it('should not include metadata when metadata is not provided', async () => {
+      const siteId = 'site-456';
+      const url = 'https://www.example.com';
+
+      await client.updateMetaconfig(url, siteId, {
+        tokowakaEnabled: true,
+      });
+
+      // Second call is the uploadMetaconfig
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      expect(uploadCommand.input.Metadata).to.be.undefined;
+    });
   });
 
   describe('uploadConfig', () => {
@@ -2819,61 +2941,70 @@ describe('TokowakaClient', () => {
       }
     });
 
-    it('should throw error if metaconfig does not exist', async () => {
+    it('should preview suggestions successfully without metaconfig (optional)', async () => {
+      // Override the stub from beforeEach to return null
       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);
-      }
-    });
+      const result = await client.previewSuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+        { warmupDelayMs: 0 },
+      );
 
-    it('should throw error if metaconfig does not have apiKeys', async () => {
-      client.fetchMetaconfig.resolves({
-        siteId: 'site-123',
-        // apiKeys missing
-      });
+      expect(result.succeededSuggestions).to.have.length(2);
+      expect(result.failedSuggestions).to.have.length(0);
+      expect(result.config).to.exist;
+      expect(result.html).to.exist;
+      expect(result.html.originalHtml).to.equal('<html><body>Test HTML</body></html>');
+      expect(result.html.optimizedHtml).to.equal('<html><body>Test HTML</body></html>');
 
-      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);
-      }
+      // Verify fetch was called without API key (undefined)
+      expect(fetchStub.callCount).to.equal(4); // 2 warmup + 2 actual (original + optimized)
     });
 
-    it('should throw error if metaconfig has empty apiKeys array', async () => {
+    it('should preview suggestions successfully without apiKeys in metaconfig (optional)', async () => {
+      // Override the stub from beforeEach
       client.fetchMetaconfig.resolves({
         siteId: 'site-123',
-        apiKeys: [],
+        // apiKeys missing - should work without it
       });
 
-      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);
-      }
+      const result = await client.previewSuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+        { warmupDelayMs: 0 },
+      );
+
+      expect(result.succeededSuggestions).to.have.length(2);
+      expect(result.failedSuggestions).to.have.length(0);
+      expect(result.config).to.exist;
+      expect(result.html).to.exist;
+      expect(result.html.originalHtml).to.equal('<html><body>Test HTML</body></html>');
+      expect(result.html.optimizedHtml).to.equal('<html><body>Test HTML</body></html>');
+      expect(fetchStub.callCount).to.equal(4);
     });
 
-    it('should throw error if metaconfig apiKeys first value is empty', async () => {
+    it('should preview suggestions successfully with empty apiKeys array (optional)', async () => {
+      // Override the stub from beforeEach
       client.fetchMetaconfig.resolves({
         siteId: 'site-123',
-        apiKeys: ['', 'test-api-key-2'],
+        apiKeys: [],
       });
 
-      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);
-      }
+      const result = await client.previewSuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+        { warmupDelayMs: 0 },
+      );
+
+      expect(result.succeededSuggestions).to.have.length(2);
+      expect(result.failedSuggestions).to.have.length(0);
+      expect(result.config).to.exist;
+      expect(result.html).to.exist;
+      expect(fetchStub.callCount).to.equal(4);
     });
 
     it('should throw error for unsupported opportunity type', async () => {

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

@@ -82,20 +82,33 @@ describe('HTML Utils', () => {
       }
     });
 
-    it('should throw error when apiKey is missing', async () => {
-      try {
-        await fetchHtmlWithWarmup(
-          'https://example.com/page',
-          '',
-          'host',
-          'edge-url',
-          log,
-          false,
-        );
-        expect.fail('Should have thrown error');
-      } catch (error) {
-        expect(error.message).to.equal('Edge Optimize API key is required for fetching HTML');
-      }
+    it('should successfully fetch HTML without apiKey (optional parameter)', async () => {
+      fetchStub.resolves({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          get: (name) => (name === 'x-edgeoptimize-cache' ? 'HIT' : null),
+        },
+        text: async () => '<html>Test HTML without API key</html>',
+      });
+
+      const html = await fetchHtmlWithWarmup(
+        'https://example.com/page',
+        null, // apiKey is optional
+        'host',
+        'https://edge.example.com',
+        log,
+        false,
+        { warmupDelayMs: 0 },
+      );
+
+      expect(html).to.equal('<html>Test HTML without API key</html>');
+      expect(fetchStub.callCount).to.equal(2); // warmup + actual
+
+      // Verify that x-edgeoptimize-api-key header is not present
+      const fetchOptions = fetchStub.firstCall.args[1];
+      expect(fetchOptions.headers).to.not.have.property('x-edgeoptimize-api-key');
     });
 
     it('should successfully fetch HTML with all required parameters', async () => {