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

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.19.0",
+  "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) => {
@@ -1590,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
@@ -1609,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);
@@ -1698,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', () => {
@@ -6618,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');
+    });
   });
 });