@adobe/spacecat-shared-tokowaka-client 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@adobe/spacecat-shared-tokowaka-client-v1.10.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.9.0...@adobe/spacecat-shared-tokowaka-client-v1.10.0) (2026-02-26)
+
+### Features
+
+* LLMO-2805 Stage config addition api changes ([#1370](https://github.com/adobe/spacecat-shared/issues/1370)) ([0789f4a](https://github.com/adobe/spacecat-shared/commit/0789f4af95433b733c86638a79c184850804dba9))
+
 ## [@adobe/spacecat-shared-tokowaka-client-v1.9.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.8.0...@adobe/spacecat-shared-tokowaka-client-v1.9.0) (2026-02-24)
 
 ### Features

package/package.json

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

package/src/index.js

@@ -230,11 +230,13 @@ class TokowakaClient {
   }
 
   /**
-   * Fetches domain-level metaconfig from S3
+   * Internal method to fetch domain-level metaconfig from S3 with metadata
    * @param {string} url - Full URL (used to extract domain)
-   * @returns {Promise<Object|null>} - Metaconfig object or null if not found
+   * @returns {Promise<Object|null>} - Object with metaconfig and s3Metadata,
+   *   or null if not found
+   * @private
    */
-  async fetchMetaconfig(url) {
+  async #fetchMetaconfigWithMetadata(url) {
     if (!hasText(url)) {
       throw this.#createError('URL is required', HTTP_BAD_REQUEST);
     }
@@ -254,7 +256,11 @@ class TokowakaClient {
       const metaconfig = JSON.parse(bodyContents);
 
       this.log.debug(`Successfully fetched metaconfig from s3://${bucketName}/${s3Path} in ${Date.now() - fetchStartTime}ms`);
-      return metaconfig;
+
+      return {
+        metaconfig,
+        s3Metadata: response.Metadata || {},
+      };
     } catch (error) {
       // If metaconfig doesn't exist (NoSuchKey), return null
       if (error.name === 'NoSuchKey' || error.Code === 'NoSuchKey') {
@@ -268,6 +274,16 @@ class TokowakaClient {
     }
   }
 
+  /**
+   * Fetches domain-level metaconfig from S3
+   * @param {string} url - Full URL (used to extract domain)
+   * @returns {Promise<Object|null>} - Metaconfig object or null if not found
+   */
+  async fetchMetaconfig(url) {
+    const result = await this.#fetchMetaconfigWithMetadata(url);
+    return result?.metaconfig ?? null;
+  }
+
   /**
    * Generates an API key for Tokowaka based on domain
    * @param {string} domain - Domain name (e.g., 'example.com')
@@ -289,7 +305,13 @@ class TokowakaClient {
    * @param {string} url - Full URL (used to extract domain)
    * @param {string} siteId - Site ID
    * @param {Object} options - Optional configuration
-   * @param {boolean} options.enhancements - Whether to enable enhancements (default: true)
+   * @param {boolean} options.enhancements - Whether to enable enhancements
+   *   (default: true)
+   * @param {Object} metadata - Optional S3 user-defined metadata for
+   *   audit trail and behavior flags
+   * @param {string} metadata.lastModifiedBy - User who modified the config
+   * @param {boolean} metadata.isStageDomain - Whether this is a staging
+   *   domain (enables wildcard prerender)
    * @returns {Promise<Object>} - Object with s3Path and metaconfig
    */
   async createMetaconfig(url, siteId, options = {}, metadata = {}) {
@@ -318,7 +340,19 @@ class TokowakaClient {
       patches: {},
     };
 
-    const s3Path = await this.uploadMetaconfig(url, metaconfig, metadata);
+    // Handle staging domain with automatic prerender configuration
+    const isStageDomain = metadata.isStageDomain === true;
+    if (isStageDomain) {
+      metaconfig.prerender = { allowList: ['/*'] };
+    }
+
+    // Persist isStageDomain in S3 metadata for future updates
+    const s3Metadata = {
+      ...metadata,
+      ...(isStageDomain && { isStageDomain: 'true' }),
+    };
+
+    const s3Path = await this.uploadMetaconfig(url, metaconfig, s3Metadata);
     this.log.info(`Created new Tokowaka metaconfig for ${normalizedHostName} at ${s3Path}`);
 
     return metaconfig;
@@ -330,6 +364,11 @@ class TokowakaClient {
    * @param {string} url - Full URL (used to extract domain)
    * @param {string} siteId - Site ID
    * @param {Object} options - Optional configuration
+   * @param {Object} metadata - Optional S3 user-defined metadata for
+   *   audit trail and behavior flags
+   * @param {string} metadata.lastModifiedBy - User who modified the config
+   * @param {boolean} metadata.isStageDomain - Whether this is a staging
+   *   domain (enables wildcard prerender)
    * @returns {Promise<Object>} - Object with s3Path and metaconfig
    */
   async updateMetaconfig(url, siteId, options = {}, metadata = {}) {
@@ -337,10 +376,11 @@ class TokowakaClient {
       throw this.#createError('URL is required', HTTP_BAD_REQUEST);
     }
 
-    const existingMetaconfig = await this.fetchMetaconfig(url);
-    if (!existingMetaconfig) {
+    const raw = await this.#fetchMetaconfigWithMetadata(url);
+    if (!raw?.metaconfig) {
       throw this.#createError('Metaconfig does not exist for this URL', HTTP_BAD_REQUEST);
     }
+    const { metaconfig: existingMetaconfig, s3Metadata: existingS3Metadata } = raw;
 
     if (!hasText(siteId)) {
       throw this.#createError('Site ID is required', HTTP_BAD_REQUEST);
@@ -356,10 +396,17 @@ class TokowakaClient {
       ?? existingMetaconfig.forceFail
       ?? false;
 
-    const hasPrerender = isNonEmptyObject(options.prerender)
+    // Handle staging domain: check from metadata or from existing S3 metadata (S3 lowercases keys)
+    const isStageDomain = metadata.isStageDomain === true
+      || existingS3Metadata.isstagedomain === 'true';
+
+    const hasPrerender = isStageDomain
+      || isNonEmptyObject(options.prerender)
       || isNonEmptyObject(existingMetaconfig.prerender);
-    const prerender = options.prerender
-      ?? existingMetaconfig.prerender;
+
+    const prerender = isStageDomain
+      ? { allowList: ['/*'] }
+      : (options.prerender ?? existingMetaconfig.prerender);
 
     const metaconfig = {
       ...existingMetaconfig,
@@ -372,8 +419,14 @@ class TokowakaClient {
       ...(hasPrerender && { prerender }),
     };
 
-    const s3Path = await this.uploadMetaconfig(url, metaconfig, metadata);
-    this.log.info(`Updated Tokowaka metaconfig for ${normalizedHostName} at ${s3Path}`);
+    // Persist isStageDomain in S3 metadata for future updates
+    const s3Metadata = {
+      ...metadata,
+      ...(isStageDomain && { isStageDomain: 'true' }),
+    };
+
+    const uploadedPath = await this.uploadMetaconfig(url, metaconfig, s3Metadata);
+    this.log.info(`Updated Tokowaka metaconfig for ${normalizedHostName} at ${uploadedPath}`);
 
     return metaconfig;
   }

package/test/index.test.js

@@ -649,6 +649,56 @@ describe('TokowakaClient', () => {
       const uploadCommand = s3Client.send.secondCall.args[0];
       expect(uploadCommand.input.Metadata).to.be.undefined;
     });
+
+    it('should NOT include prerender when isStageDomain is not true in metadata', 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);
+
+      const result = await client.createMetaconfig(url, siteId);
+
+      expect(result).to.not.have.property('prerender');
+
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      const body = JSON.parse(uploadCommand.input.Body);
+      expect(body).to.not.have.property('prerender');
+    });
+
+    it('should set prerender with allowList when isStageDomain is true in metadata', async () => {
+      const siteId = 'site-123';
+      const url = 'https://staging.example.com/page1';
+      const noSuchKeyError = new Error('NoSuchKey');
+      noSuchKeyError.name = 'NoSuchKey';
+      s3Client.send.onFirstCall().rejects(noSuchKeyError);
+
+      const result = await client.createMetaconfig(url, siteId, {}, { isStageDomain: true });
+
+      expect(result).to.have.property('prerender');
+      expect(result.prerender).to.deep.equal({ allowList: ['/*'] });
+
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      const body = JSON.parse(uploadCommand.input.Body);
+      expect(body.prerender).to.deep.equal({ allowList: ['/*'] });
+      expect(uploadCommand.input.Metadata).to.deep.equal({ isStageDomain: 'true' });
+    });
+
+    it('should NOT set prerender when isStageDomain is false in metadata', 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);
+
+      const result = await client.createMetaconfig(url, siteId, {}, { isStageDomain: false });
+
+      expect(result).to.not.have.property('prerender');
+
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      const body = JSON.parse(uploadCommand.input.Body);
+      expect(body).to.not.have.property('prerender');
+    });
   });
 
   describe('updateMetaconfig', () => {
@@ -661,11 +711,12 @@ describe('TokowakaClient', () => {
     };
 
     beforeEach(() => {
-      // Mock fetchMetaconfig to return existing config
+      // Mock fetchMetaconfig to return existing config with metadata
       s3Client.send.onFirstCall().resolves({
         Body: {
           transformToString: sinon.stub().resolves(JSON.stringify(existingMetaconfig)),
         },
+        Metadata: {},
       });
       // Mock uploadMetaconfig S3 upload
       s3Client.send.onSecondCall().resolves();
@@ -1431,6 +1482,84 @@ describe('TokowakaClient', () => {
       const uploadCommand = s3Client.send.secondCall.args[0];
       expect(uploadCommand.input.Metadata).to.be.undefined;
     });
+
+    it('should set prerender with allowList when isStageDomain is true in metadata', async () => {
+      const siteId = 'site-456';
+      const url = 'https://staging.example.com';
+
+      const result = await client.updateMetaconfig(url, siteId, {}, { isStageDomain: true });
+
+      expect(result).to.have.property('prerender');
+      expect(result.prerender).to.deep.equal({ allowList: ['/*'] });
+
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      const body = JSON.parse(uploadCommand.input.Body);
+      expect(body.prerender).to.deep.equal({ allowList: ['/*'] });
+      expect(uploadCommand.input.Metadata).to.deep.equal({ isStageDomain: 'true' });
+    });
+
+    it('should override existing prerender when isStageDomain is true in metadata', async () => {
+      const siteId = 'site-456';
+      const url = 'https://staging.example.com';
+      const existingMetaconfigWithPrerender = {
+        ...existingMetaconfig,
+        prerender: { allowList: ['/old-path/*'] },
+      };
+
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(existingMetaconfigWithPrerender)),
+        },
+        Metadata: {},
+      });
+
+      const result = await client.updateMetaconfig(url, siteId, {}, { isStageDomain: true });
+
+      expect(result).to.have.property('prerender');
+      expect(result.prerender).to.deep.equal({ allowList: ['/*'] });
+
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      const body = JSON.parse(uploadCommand.input.Body);
+      expect(body.prerender).to.deep.equal({ allowList: ['/*'] });
+    });
+
+    it('should preserve existing prerender when isStageDomain is not in metadata', async () => {
+      const siteId = 'site-456';
+      const url = 'https://www.example.com';
+      const existingMetaconfigWithPrerender = {
+        ...existingMetaconfig,
+        prerender: { allowList: ['/path/*'] },
+      };
+
+      s3Client.send.onFirstCall().resolves({
+        Body: {
+          transformToString: sinon.stub().resolves(JSON.stringify(existingMetaconfigWithPrerender)),
+        },
+        Metadata: {},
+      });
+
+      const result = await client.updateMetaconfig(url, siteId, {});
+
+      expect(result).to.have.property('prerender');
+      expect(result.prerender).to.deep.equal({ allowList: ['/path/*'] });
+
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      const body = JSON.parse(uploadCommand.input.Body);
+      expect(body.prerender).to.deep.equal({ allowList: ['/path/*'] });
+    });
+
+    it('should NOT set prerender when isStageDomain is false in metadata', async () => {
+      const siteId = 'site-456';
+      const url = 'https://www.example.com';
+
+      const result = await client.updateMetaconfig(url, siteId, {}, { isStageDomain: false });
+
+      expect(result).to.not.have.property('prerender');
+
+      const uploadCommand = s3Client.send.secondCall.args[0];
+      const body = JSON.parse(uploadCommand.input.Body);
+      expect(body).to.not.have.property('prerender');
+    });
   });
 
   describe('uploadConfig', () => {