@adobe/spacecat-shared-tokowaka-client 1.18.2 → 1.19.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-tokowaka-client-v1.19.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.19.0...@adobe/spacecat-shared-tokowaka-client-v1.19.1) (2026-06-21)
+
+### Bug Fixes
+
+* apply stale config in IVE edge deployment flow ([#1691](https://github.com/adobe/spacecat-shared/issues/1691)) ([9f07a9c](https://github.com/adobe/spacecat-shared/commit/9f07a9ccc73140249aad16e9c9d0d7f5cededf59))
+
+## [@adobe/spacecat-shared-tokowaka-client-v1.19.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.18.2...@adobe/spacecat-shared-tokowaka-client-v1.19.0) (2026-06-03)
+
+### Features
+
+* **tokowaka-client:** mark path-level suggestions as coveredByDomainWide on domain-wide deploy ([#1648](https://github.com/adobe/spacecat-shared/issues/1648)) ([9cc5992](https://github.com/adobe/spacecat-shared/commit/9cc5992bb98acf9da48a432fedfbec694d30fe23))
+
 ## [@adobe/spacecat-shared-tokowaka-client-v1.18.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.18.1...@adobe/spacecat-shared-tokowaka-client-v1.18.2) (2026-06-02)
 
 ### Bug Fixes

package/package.json

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

package/src/index.js

@@ -712,7 +712,8 @@ class TokowakaClient {
    * @param {Array} suggestions - Array of suggestion entities to deploy
    * @returns {Promise<Object>} - Deployment result with succeeded/failed suggestions
    */
-  async deploySuggestions(site, opportunity, suggestions) {
+  async deploySuggestions(site, opportunity, suggestions, metadata = {}) {
+    const { applyStale = false } = metadata;
     const opportunityType = opportunity.getType();
     const baseURL = getEffectiveBaseURL(site);
     const mapper = this.mapperRegistry.getMapper(opportunityType);
@@ -788,6 +789,10 @@ class TokowakaClient {
         continue;
       }
 
+      if (applyStale && newConfig.patches?.length > 0) {
+        newConfig.patches = newConfig.patches.map((patch) => ({ ...patch, applyStale: true }));
+      }
+
       // Merge with existing config for this URL
       const config = this.mergeConfigs(existingConfig, newConfig);
 
@@ -828,8 +833,15 @@ class TokowakaClient {
    * @returns {Promise<number>} Number of patches removed
    * @private
    */
-  // eslint-disable-next-line max-len
-  async #rollbackPerUrlConfig(fullUrl, urlSuggestions, opportunity, mapper, opportunityType, s3Paths, rolledBackUrls) {
+  async #rollbackPerUrlConfig(
+    fullUrl,
+    urlSuggestions,
+    opportunity,
+    mapper,
+    opportunityType,
+    s3Paths,
+    rolledBackUrls,
+  ) {
     const existingConfig = await this.fetchConfig(fullUrl);
     if (!existingConfig) {
       this.log.warn(`No existing configuration found for URL: ${fullUrl}`);
@@ -1427,9 +1439,11 @@ class TokowakaClient {
    * @returns {Promise<{ succeededSuggestions: Array, failedSuggestions: Array }>}
    * @private
    */
-  async #deployPerUrlSuggestions(site, opportunity, validSuggestions, updatedBy) {
+  // eslint-disable-next-line max-len
+  async #deployPerUrlSuggestions(site, opportunity, validSuggestions, updatedBy, metadata = {}) {
     try {
-      const result = await this.deploySuggestions(site, opportunity, validSuggestions);
+      // eslint-disable-next-line max-len
+      const result = await this.deploySuggestions(site, opportunity, validSuggestions, metadata);
       const deploymentTimestamp = Date.now();
 
       const succeeded = result.succeededSuggestions.map((s) => {
@@ -1532,12 +1546,14 @@ class TokowakaClient {
       if (!isEdgeDeployableSuggestionStatus(s.getStatus())) {
         return false;
       }
-      if (isPatternSuggestion(s)) {
-        return false;
-      }
       if (s.getData()?.edgeDeployed) {
         return false;
       }
+      // Path-level pattern suggestions (not domain-wide) are fully covered by a
+      // domain-wide deployment. Other pattern suggestions (including other DW ones) are not.
+      if (isPatternSuggestion(s)) {
+        return coverageField === 'coveredByDomainWide' && !s.getData()?.isDomainWide;
+      }
       const url = s.getData()?.url;
       return url && matchers.some((match) => match(url));
     });
@@ -1588,6 +1604,7 @@ class TokowakaClient {
     targetSuggestions,
     allSuggestions,
     updatedBy = 'edge-deploy',
+    metadata = {},
   }) {
     // Step 1: classify suggestions into pattern vs per-URL buckets.
     // eslint-disable-next-line max-len
@@ -1607,7 +1624,7 @@ class TokowakaClient {
     // Step 3: deploy per-URL suggestions via S3.
     if (validSuggestions.length > 0) {
       // eslint-disable-next-line max-len
-      const result = await this.#deployPerUrlSuggestions(site, opportunity, validSuggestions, updatedBy);
+      const result = await this.#deployPerUrlSuggestions(site, opportunity, validSuggestions, updatedBy, metadata);
       const { succeededSuggestions: perUrlSucceeded, failedSuggestions: perUrlFailed } = result;
       succeededSuggestions = perUrlSucceeded;
       failedSuggestions.push(...perUrlFailed);
@@ -1696,6 +1713,74 @@ class TokowakaClient {
 
     return { succeededSuggestions, failedSuggestions, coveredSuggestions };
   }
+
+  /**
+   * Strips the `applyStale` flag from patches in S3 for the given per-URL suggestions.
+   * Called when an experiment completes so edge reverts to normal (non-stale) behaviour.
+   * Pattern / domain-wide suggestions are skipped — they have no per-URL S3 config.
+   * CDN cache is invalidated for every URL whose config was actually modified.
+   *
+   * @param {Object} site - Site entity
+   * @param {Object} opportunity - Opportunity entity
+   * @param {Array}  suggestions - Suggestion entities to clear (may include pattern suggestions,
+   *   which are silently skipped)
+   * @returns {Promise<void>}
+   */
+  async clearApplyStaleFromPatches(site, opportunity, suggestions) {
+    const baseURL = getEffectiveBaseURL(site);
+
+    const perUrlSuggestions = suggestions.filter((s) => {
+      const data = s.getData();
+      return data?.url && !Array.isArray(data?.allowedRegexPatterns);
+    });
+
+    if (perUrlSuggestions.length === 0) {
+      return;
+    }
+
+    const suggestionsByUrl = groupSuggestionsByUrlPath(perUrlSuggestions, baseURL, this.log);
+    const clearedUrls = [];
+
+    for (const [urlPath, urlSuggestions] of Object.entries(suggestionsByUrl)) {
+      const fullUrl = new URL(urlPath, baseURL).toString();
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const existingConfig = await this.fetchConfig(fullUrl);
+        if (!existingConfig?.patches?.length) {
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+
+        const suggestionIds = new Set(urlSuggestions.map((s) => s.getId()));
+        let modified = false;
+        const updatedPatches = existingConfig.patches.map((patch) => {
+          if (suggestionIds.has(patch.suggestionId) && patch.applyStale) {
+            modified = true;
+            const { applyStale: _, ...rest } = patch;
+            return rest;
+          }
+          return patch;
+        });
+
+        if (modified) {
+          // eslint-disable-next-line no-await-in-loop
+          await this.uploadConfig(fullUrl, { ...existingConfig, patches: updatedPatches });
+          clearedUrls.push(fullUrl);
+        }
+      } catch (err) {
+        this.log.error(`[clear-apply-stale-failed] Failed to process URL ${fullUrl}: ${err.message}`, err);
+      }
+    }
+
+    if (clearedUrls.length > 0) {
+      try {
+        await this.invalidateCdnCache({ urls: clearedUrls });
+        this.log.info(`[clear-apply-stale] Cleared applyStale from ${clearedUrls.length} URL(s) and invalidated CDN`);
+      } catch (err) {
+        this.log.warn(`[clear-apply-stale-failed] CDN invalidation failed for ${clearedUrls.length} URL(s), S3 configs already updated: ${err.message}`, err);
+      }
+    }
+  }
 }
 
 // Export the client as default and base classes for custom implementations

package/test/index.test.js

@@ -2495,6 +2495,37 @@ describe('TokowakaClient', () => {
       expect(updatedPatch.suggestionId).to.equal('sugg-1');
       expect(updatedPatch.lastUpdated).to.be.greaterThan(1234567890);
     });
+
+    it('should add applyStale: true to all patches when applyStale option is true', async () => {
+      const result = await client.deploySuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+        { applyStale: true },
+      );
+
+      expect(result.s3Paths).to.have.length(1);
+      const uploadedConfig = JSON.parse(s3Client.send.firstCall.args[0].input.Body);
+      expect(uploadedConfig.patches).to.have.length(2);
+      uploadedConfig.patches.forEach((patch) => {
+        expect(patch.applyStale).to.equal(true);
+      });
+    });
+
+    it('should not add applyStale to patches when applyStale option is false', async () => {
+      const result = await client.deploySuggestions(
+        mockSite,
+        mockOpportunity,
+        mockSuggestions,
+        { applyStale: false },
+      );
+
+      expect(result.s3Paths).to.have.length(1);
+      const uploadedConfig = JSON.parse(s3Client.send.firstCall.args[0].input.Body);
+      uploadedConfig.patches.forEach((patch) => {
+        expect(patch.applyStale).to.be.undefined;
+      });
+    });
   });
 
   describe('rollbackSuggestions', () => {
@@ -3117,6 +3148,55 @@ describe('TokowakaClient', () => {
       expect(coveredData).to.not.have.property('coveredByDomainWide');
     });
 
+    it('cleans up coveredByDomainWide on path-level suggestions when rolling back domain-wide', async () => {
+      const prerenderOpportunity = { getId: () => 'opp-dw', getType: () => 'prerender' };
+      const dwSuggestion = {
+        getId: () => 'dw-1',
+        getData: () => ({
+          isDomainWide: true,
+          allowedRegexPatterns: ['/*'],
+          edgeDeployed: Date.now(),
+        }),
+        setData: sinon.stub(),
+        setUpdatedBy: sinon.stub(),
+        save: sinon.stub().resolves(),
+      };
+      const pathSuggestion = {
+        getId: () => 'path-1',
+        getData: () => ({
+          allowedRegexPatterns: ['/products/*'],
+          coveredByDomainWide: 'dw-1',
+        }),
+        setData: sinon.stub(),
+        setUpdatedBy: sinon.stub(),
+        save: sinon.stub().resolves(),
+      };
+
+      sinon.stub(client, 'fetchMetaconfig').resolves({
+        siteId: 'site-123',
+        prerender: { allowList: ['/*'] },
+      });
+      sinon.stub(client, 'uploadMetaconfig').resolves();
+
+      const result = await client.rollbackSuggestions(
+        mockSite,
+        prerenderOpportunity,
+        [dwSuggestion],
+        { allSuggestions: [dwSuggestion, pathSuggestion], updatedBy: 'test@example.com' },
+      );
+
+      expect(result.succeededSuggestions).to.include(dwSuggestion);
+      expect(pathSuggestion.setData.calledOnce).to.be.true;
+      const pathData = pathSuggestion.setData.firstCall.args[0];
+      expect(pathData).to.not.have.property('coveredByDomainWide');
+      expect(pathData).to.have.property('allowedRegexPatterns');
+      // Verify the cleaned-up path suggestion was actually persisted via saveMany
+      expect(client.dataAccess.Suggestion.saveMany).to.have.been.calledWith(
+        sinon.match((arr) => arr.includes(pathSuggestion)),
+        sinon.match.any,
+      );
+    });
+
     it('cleans up covered suggestions (coveredByPattern) when rolling back a path-level pattern', async () => {
       const prerenderOpportunity = { getId: () => 'opp-p', getType: () => 'prerender' };
       const pathSuggestion = {
@@ -5909,6 +5989,51 @@ describe('TokowakaClient', () => {
       expect(result.coveredSuggestions).to.not.include(dw2);
     });
 
+    it('should mark path-level pattern suggestions as coveredByDomainWide when domain-wide is deployed', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const pathLevel = makeSuggestion('path1', {
+        allowedRegexPatterns: ['/products/*'],
+      });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw, pathLevel],
+      });
+
+      expect(result.coveredSuggestions).to.include(pathLevel);
+      expect(pathLevel.getData()).to.have.property('coveredByDomainWide', 'dw1');
+    });
+
+    it('should not mark already-deployed path-level suggestions as coveredByDomainWide', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const pathLevel = makeSuggestion('path1', {
+        allowedRegexPatterns: ['/products/*'],
+        edgeDeployed: Date.now(),
+      });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw, pathLevel],
+      });
+
+      expect(result.coveredSuggestions).to.not.include(pathLevel);
+      expect(pathLevel.getData()).to.not.have.property('coveredByDomainWide');
+    });
+
     it('should not mark non-NEW suggestions as covered', async () => {
       const dw = makeSuggestion('dw1', {
         isDomainWide: true,
@@ -6524,5 +6649,186 @@ describe('TokowakaClient', () => {
       expect(result.failedSuggestions[0].reason).to.equal('Internal server error');
       expect(log.error).to.have.been.called;
     });
+
+    it('should pass applyStale: true to deploySuggestions when metadata.applyStale is true', async () => {
+      const s1 = makeSuggestion('s1', { url: 'https://example.com/page1', transformRules: {} });
+
+      deploySuggestionsStub.resolves({
+        succeededSuggestions: [s1],
+        failedSuggestions: [],
+      });
+
+      await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [s1],
+        allSuggestions: [s1],
+        metadata: { applyStale: true },
+      });
+
+      expect(deploySuggestionsStub).to.have.been.calledOnce;
+      const [,, , metadata] = deploySuggestionsStub.firstCall.args;
+      expect(metadata).to.deep.equal({ applyStale: true });
+    });
+
+    it('should pass empty metadata to deploySuggestions when metadata is absent', async () => {
+      const s1 = makeSuggestion('s1', { url: 'https://example.com/page1', transformRules: {} });
+
+      deploySuggestionsStub.resolves({
+        succeededSuggestions: [s1],
+        failedSuggestions: [],
+      });
+
+      await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [s1],
+        allSuggestions: [s1],
+      });
+
+      expect(deploySuggestionsStub).to.have.been.calledOnce;
+      const [,, , metadata] = deploySuggestionsStub.firstCall.args;
+      expect(metadata).to.deep.equal({});
+    });
+  });
+
+  describe('clearApplyStaleFromPatches', () => {
+    let fetchConfigStub;
+    let uploadConfigStub;
+    let invalidateCdnCacheStub;
+
+    function makeCompletedSuggestion(id, urlPath) {
+      return {
+        getId: () => id,
+        getData: () => ({ url: `https://example.com${urlPath}`, edgeDeployed: Date.now() }),
+      };
+    }
+
+    beforeEach(() => {
+      fetchConfigStub = sinon.stub(client, 'fetchConfig');
+      uploadConfigStub = sinon.stub(client, 'uploadConfig').resolves('s3-path');
+      invalidateCdnCacheStub = sinon.stub(client, 'invalidateCdnCache').resolves([]);
+    });
+
+    it('should strip applyStale from matching patches and invalidate CDN', async () => {
+      fetchConfigStub.resolves({
+        url: 'https://example.com/page1',
+        version: '1.0',
+        patches: [
+          {
+            op: 'replace', selector: 'h1', value: 'New', suggestionId: 'sugg-1', applyStale: true,
+          },
+          {
+            op: 'replace', selector: 'h2', value: 'Other', suggestionId: 'sugg-2', applyStale: true,
+          },
+        ],
+      });
+
+      const s1 = makeCompletedSuggestion('sugg-1', '/page1');
+      await client.clearApplyStaleFromPatches(mockSite, mockOpportunity, [s1]);
+
+      expect(uploadConfigStub).to.have.been.calledOnce;
+      const [, uploadedConfig] = uploadConfigStub.firstCall.args;
+      const patch1 = uploadedConfig.patches.find((p) => p.suggestionId === 'sugg-1');
+      expect(patch1).to.not.have.property('applyStale');
+      // sugg-2 not in suggestions list — applyStale untouched
+      const patch2 = uploadedConfig.patches.find((p) => p.suggestionId === 'sugg-2');
+      expect(patch2.applyStale).to.equal(true);
+      expect(invalidateCdnCacheStub).to.have.been.calledOnce;
+    });
+
+    it('should skip upload when no patches have applyStale', async () => {
+      fetchConfigStub.resolves({
+        url: 'https://example.com/page1',
+        version: '1.0',
+        patches: [
+          {
+            op: 'replace', selector: 'h1', value: 'New', suggestionId: 'sugg-1',
+          },
+        ],
+      });
+
+      const s1 = makeCompletedSuggestion('sugg-1', '/page1');
+      await client.clearApplyStaleFromPatches(mockSite, mockOpportunity, [s1]);
+
+      expect(uploadConfigStub).to.not.have.been.called;
+      expect(invalidateCdnCacheStub).to.not.have.been.called;
+    });
+
+    it('should skip URLs with no existing config', async () => {
+      fetchConfigStub.resolves(null);
+
+      const s1 = makeCompletedSuggestion('sugg-1', '/page1');
+      await client.clearApplyStaleFromPatches(mockSite, mockOpportunity, [s1]);
+
+      expect(uploadConfigStub).to.not.have.been.called;
+      expect(invalidateCdnCacheStub).to.not.have.been.called;
+    });
+
+    it('should silently skip pattern and domain-wide suggestions', async () => {
+      const patternSugg = {
+        getId: () => 'dw-1',
+        getData: () => ({ isDomainWide: true, allowedRegexPatterns: ['/.*'] }),
+      };
+
+      await client.clearApplyStaleFromPatches(mockSite, mockOpportunity, [patternSugg]);
+
+      expect(fetchConfigStub).to.not.have.been.called;
+      expect(uploadConfigStub).to.not.have.been.called;
+    });
+
+    it('should handle multiple URLs, only invalidate ones that changed', async () => {
+      fetchConfigStub.onFirstCall().resolves({
+        patches: [{ suggestionId: 'sugg-1', applyStale: true }],
+      });
+      fetchConfigStub.onSecondCall().resolves({
+        patches: [{ suggestionId: 'sugg-2' }],
+      });
+
+      const s1 = makeCompletedSuggestion('sugg-1', '/page1');
+      const s2 = makeCompletedSuggestion('sugg-2', '/page2');
+      await client.clearApplyStaleFromPatches(mockSite, mockOpportunity, [s1, s2]);
+
+      expect(uploadConfigStub).to.have.been.calledOnce;
+      expect(invalidateCdnCacheStub).to.have.been.calledOnce;
+      const { urls } = invalidateCdnCacheStub.firstCall.args[0];
+      expect(urls).to.have.length(1);
+      expect(urls[0]).to.include('/page1');
+    });
+
+    it('should do nothing when given no per-URL suggestions', async () => {
+      await client.clearApplyStaleFromPatches(mockSite, mockOpportunity, []);
+
+      expect(fetchConfigStub).to.not.have.been.called;
+    });
+
+    it('should log warning and return normally when CDN invalidation throws', async () => {
+      fetchConfigStub.resolves({
+        patches: [{ suggestionId: 'sugg-1', applyStale: true }],
+      });
+      invalidateCdnCacheStub.rejects(new Error('CDN rate limit'));
+
+      const s1 = makeCompletedSuggestion('sugg-1', '/page1');
+      await client.clearApplyStaleFromPatches(mockSite, mockOpportunity, [s1]);
+
+      expect(uploadConfigStub).to.have.been.calledOnce;
+    });
+
+    it('should log error and continue processing remaining URLs when one URL throws', async () => {
+      fetchConfigStub.onFirstCall().rejects(new Error('S3 transient error'));
+      fetchConfigStub.onSecondCall().resolves({
+        patches: [{ suggestionId: 'sugg-2', applyStale: true }],
+      });
+
+      const s1 = makeCompletedSuggestion('sugg-1', '/page1');
+      const s2 = makeCompletedSuggestion('sugg-2', '/page2');
+      await client.clearApplyStaleFromPatches(mockSite, mockOpportunity, [s1, s2]);
+
+      expect(uploadConfigStub).to.have.been.calledOnce;
+      expect(invalidateCdnCacheStub).to.have.been.calledOnce;
+      const { urls } = invalidateCdnCacheStub.firstCall.args[0];
+      expect(urls).to.have.length(1);
+      expect(urls[0]).to.include('/page2');
+    });
   });
 });