@adobe/spacecat-shared-tokowaka-client 1.12.3 → 1.13.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-tokowaka-client-v1.13.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.13.0...@adobe/spacecat-shared-tokowaka-client-v1.13.1) (2026-04-04)
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#1506](https://github.com/adobe/spacecat-shared/issues/1506)) ([a4516f6](https://github.com/adobe/spacecat-shared/commit/a4516f68dcb8b2efffc2a0c1e2ec2770347c163d))
+
+## [@adobe/spacecat-shared-tokowaka-client-v1.13.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.12.3...@adobe/spacecat-shared-tokowaka-client-v1.13.0) (2026-04-01)
+
+### Features
+
+* experimentation engine ([#1446](https://github.com/adobe/spacecat-shared/issues/1446)) ([44bff63](https://github.com/adobe/spacecat-shared/commit/44bff6350c18db58d8fbffde8de05074269ec969))
+
 ## [@adobe/spacecat-shared-tokowaka-client-v1.12.3](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.12.2...@adobe/spacecat-shared-tokowaka-client-v1.12.3) (2026-03-28)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.12.3",
+  "version": "1.13.1",
   "description": "Tokowaka Client for SpaceCat - Edge optimization config management",
   "type": "module",
   "engines": {
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "@adobe/spacecat-shared-utils": "1.81.1",
-    "@aws-sdk/client-cloudfront": "3.1019.0",
-    "@aws-sdk/client-s3": "3.1019.0",
+    "@aws-sdk/client-cloudfront": "3.1024.0",
+    "@aws-sdk/client-s3": "3.1024.0",
     "hast-util-from-html": "2.0.3",
     "mdast-util-from-markdown": "2.0.3",
     "mdast-util-to-hast": "13.2.1",

package/src/index.js

@@ -34,6 +34,11 @@ const HTTP_BAD_REQUEST = 400;
 const HTTP_INTERNAL_SERVER_ERROR = 500;
 const HTTP_NOT_IMPLEMENTED = 501;
 
+/** Matches SpaceCat API eligibility for edge deploy (non-domain-wide). */
+function isEdgeDeployableSuggestionStatus(status) {
+  return status === 'NEW' || status === 'PENDING_VALIDATION';
+}
+
 /**
  * Tokowaka Client - Manages edge optimization configurations
  */
@@ -54,11 +59,10 @@ class TokowakaClient {
       return context.tokowakaClient;
     }
 
-    // s3ClientWrapper puts s3Client at context.s3.s3Client, so check both locations
     const client = new TokowakaClient({
       bucketName,
       previewBucketName,
-      s3Client: s3?.s3Client,
+      s3Client: s3?.s3Client ?? context.s3Client,
       env,
     }, log);
     context.tokowakaClient = client;
@@ -1197,6 +1201,215 @@ class TokowakaClient {
     );
     /* c8 ignore stop */
   }
+
+  /**
+   * Deploys suggestions to edge, handling both regular and domain-wide suggestions.
+   *
+   * Regular suggestions are deployed via deploySuggestions(). Domain-wide suggestions
+   * update the site metaconfig's prerender allowList. Suggestions covered by domain-wide
+   * patterns (in the same batch or across the whole opportunity) are automatically marked.
+   *
+   * @param {Object} params
+   * @param {Object} params.site - Site entity
+   * @param {Object} params.opportunity - Opportunity entity
+   * @param {Array}  params.targetSuggestions - Suggestions selected for this deployment
+   * @param {Array}  params.allSuggestions - All suggestions for the opportunity
+   * @param {string} [params.updatedBy='edge-deploy'] - Value for updatedBy on saved suggestions
+   * @returns {Promise<Object>} { succeededSuggestions, failedSuggestions, coveredSuggestions }
+   *   - succeededSuggestions: suggestion entities that were deployed
+   *   - failedSuggestions: { suggestion, reason } items that couldn't be deployed
+   *   - coveredSuggestions: suggestion entities auto-marked via domain-wide patterns
+   */
+  async deployToEdge({
+    site,
+    opportunity,
+    targetSuggestions,
+    allSuggestions,
+    updatedBy = 'edge-deploy',
+  }) {
+    const validSuggestions = [];
+    const domainWideSuggestions = [];
+
+    targetSuggestions.forEach((suggestion) => {
+      const data = suggestion.getData();
+      if (data?.isDomainWide === true) {
+        const { allowedRegexPatterns } = data;
+        if (Array.isArray(allowedRegexPatterns) && allowedRegexPatterns.length > 0) {
+          domainWideSuggestions.push({ suggestion, allowedRegexPatterns });
+        }
+      } else if (isEdgeDeployableSuggestionStatus(suggestion.getStatus())) {
+        validSuggestions.push(suggestion);
+      }
+    });
+
+    // Filter valid suggestions that are covered by domain-wide patterns in the same batch
+    const skippedInBatch = [];
+    if (domainWideSuggestions.length > 0 && validSuggestions.length > 0) {
+      const allPatterns = [];
+      domainWideSuggestions.forEach(({ allowedRegexPatterns }) => {
+        allowedRegexPatterns.forEach((pattern) => {
+          try {
+            allPatterns.push(new RegExp(pattern));
+          } catch {
+            this.log.warn(`[edge-deploy] Skipping domain-wide pattern ${pattern} - invalid regex`);
+          }
+        });
+      });
+
+      const remaining = [];
+      validSuggestions.forEach((s) => {
+        const url = s.getData()?.url;
+        if (url && allPatterns.some((regex) => regex.test(url))) {
+          skippedInBatch.push(s);
+          this.log.info(`[edge-deploy] Skipping suggestion ${s.getId()} - covered by domain-wide pattern`);
+        } else {
+          remaining.push(s);
+        }
+      });
+      validSuggestions.length = 0;
+      validSuggestions.push(...remaining);
+    }
+
+    let succeededSuggestions = [];
+    const failedSuggestions = [];
+
+    // Deploy regular suggestions via tokowaka
+    if (validSuggestions.length > 0) {
+      try {
+        const result = await this.deploySuggestions(site, opportunity, validSuggestions);
+        const deploymentTimestamp = Date.now();
+
+        succeededSuggestions = await Promise.all(
+          result.succeededSuggestions.map(async (s) => {
+            const currentData = s.getData();
+            const updated = { ...currentData, edgeDeployed: deploymentTimestamp };
+            if (updated.edgeOptimizeStatus === 'STALE') {
+              delete updated.edgeOptimizeStatus;
+            }
+            s.setData(updated);
+            s.setUpdatedBy(updatedBy);
+            await s.save();
+            return s;
+          }),
+        );
+
+        // ineligible suggestions get statusCode 400 — they weren't deployable
+        result.failedSuggestions.forEach((item) => {
+          failedSuggestions.push({ ...item, statusCode: 400 });
+          this.log.info(`[edge-deploy] ${opportunity.getType()} suggestion ${item.suggestion.getId()} is ineligible: ${item.reason}`);
+        });
+      } catch (error) {
+        this.log.error(`[edge-deploy] Error deploying suggestions: ${error.message}`, error);
+        throw error;
+      }
+    }
+
+    // Deploy domain-wide suggestions via metaconfig
+    const coveredSuggestions = [];
+    if (domainWideSuggestions.length > 0) {
+      const baseURL = site.getBaseURL();
+      const skippedInBatchIds = new Set(skippedInBatch.map((s) => s.getId()));
+
+      for (const { suggestion, allowedRegexPatterns } of domainWideSuggestions) {
+        // Fix #1: compile + validate regexes before any upload/save so a bad pattern
+        // never causes a suggestion to land in both succeeded and failed lists.
+        const regexPatterns = [];
+        for (const pattern of allowedRegexPatterns) {
+          try {
+            regexPatterns.push(new RegExp(pattern));
+          } catch {
+            this.log.warn(`[edge-deploy] Invalid regex pattern "${pattern}" for domain-wide suggestion ${suggestion.getId()}, skipping`);
+          }
+        }
+
+        try {
+          // eslint-disable-next-line no-await-in-loop
+          let metaconfig = await this.fetchMetaconfig(baseURL);
+          if (!metaconfig) {
+            metaconfig = { siteId: site.getId() };
+          }
+          metaconfig.prerender = { allowList: allowedRegexPatterns };
+          // eslint-disable-next-line no-await-in-loop
+          await this.uploadMetaconfig(baseURL, metaconfig);
+
+          const deploymentTimestamp = Date.now();
+          suggestion.setData({ ...suggestion.getData(), edgeDeployed: deploymentTimestamp });
+          suggestion.setUpdatedBy(updatedBy);
+          // eslint-disable-next-line no-await-in-loop
+          await suggestion.save();
+          succeededSuggestions.push(suggestion);
+
+          if (regexPatterns.length > 0) {
+            const covered = allSuggestions.filter((s) => {
+              if (s.getId() === suggestion.getId()) return false;
+              if (skippedInBatchIds.has(s.getId())) return false;
+              if (!isEdgeDeployableSuggestionStatus(s.getStatus())) {
+                return false;
+              }
+              if (s.getData()?.isDomainWide === true) {
+                return false;
+              }
+              const url = s.getData()?.url;
+              return url && regexPatterns.some((r) => r.test(url));
+            });
+
+            if (covered.length > 0) {
+              try {
+                // eslint-disable-next-line no-await-in-loop
+                await Promise.all(covered.map(async (cs) => {
+                  cs.setData({
+                    ...cs.getData(),
+                    edgeDeployed: deploymentTimestamp,
+                    coveredByDomainWide: suggestion.getId(),
+                  });
+                  cs.setUpdatedBy(updatedBy);
+                  return cs.save();
+                }));
+                coveredSuggestions.push(...covered);
+              } catch (coverError) {
+                this.log.warn(`[edge-deploy] Failed to mark covered suggestions for domain-wide ${suggestion.getId()}: ${coverError.message}`);
+              }
+            }
+          }
+        } catch (error) {
+          this.log.error(`[edge-deploy] Error deploying domain-wide suggestion ${suggestion.getId()}: ${error.message}`, error);
+          // statusCode 500 — deploy itself failed, not an eligibility issue
+          failedSuggestions.push({ suggestion, reason: error.message, statusCode: 500 });
+        }
+      }
+    }
+
+    // Mark same-batch skipped suggestions individually so a single save failure
+    // surfaces as a per-item failure rather than swallowing the whole batch.
+    if (skippedInBatch.length > 0) {
+      const deploymentTimestamp = Date.now();
+      const results = await Promise.allSettled(skippedInBatch.map(async (s) => {
+        s.setData({
+          ...s.getData(),
+          edgeDeployed: deploymentTimestamp,
+          coveredByDomainWide: 'same-batch-deployment',
+          skippedInDeployment: true,
+        });
+        s.setUpdatedBy(updatedBy);
+        await s.save();
+        return s;
+      }));
+
+      results.forEach((result, i) => {
+        const s = skippedInBatch[i];
+        if (result.status === 'fulfilled') {
+          succeededSuggestions.push(s);
+          coveredSuggestions.push(s);
+        } else {
+          this.log.warn(`[edge-deploy] Failed to mark same-batch skipped suggestion ${s.getId()}`
+          + ` - ${result.reason?.message}`);
+          failedSuggestions.push({ suggestion: s, reason: 'Failed to mark as covered by domain-wide', statusCode: 500 });
+        }
+      });
+    }
+
+    return { succeededSuggestions, failedSuggestions, coveredSuggestions };
+  }
 }
 
 // Export the client as default and base classes for custom implementations

package/test/index.test.js

@@ -156,6 +156,22 @@ describe('TokowakaClient', () => {
       expect(createdClient.previewBucketName).to.equal('test-preview-bucket');
     });
 
+    it('should create client from context using context.s3Client directly', () => {
+      const context = {
+        env: {
+          TOKOWAKA_SITE_CONFIG_BUCKET: 'test-bucket',
+          TOKOWAKA_PREVIEW_BUCKET: 'test-preview-bucket',
+        },
+        s3Client,
+        log,
+      };
+
+      const createdClient = TokowakaClient.createFrom(context);
+
+      expect(createdClient).to.be.instanceOf(TokowakaClient);
+      expect(context.tokowakaClient).to.equal(createdClient);
+    });
+
     it('should reuse existing client from context', () => {
       const existingClient = new TokowakaClient(
         { bucketName: 'test-bucket', s3Client },
@@ -4253,4 +4269,470 @@ describe('TokowakaClient', () => {
       });
     });
   });
+
+  describe('deployToEdge', () => {
+    let deploySuggestionsStub;
+    let fetchMetaconfigStub;
+    let uploadMetaconfigStub;
+
+    function makeSuggestion(id, data, status = 'NEW') {
+      let storedData = { ...data };
+      let storedUpdatedBy;
+      return {
+        getId: () => id,
+        getStatus: () => status,
+        getData: () => storedData,
+        setData: (d) => { storedData = d; },
+        setUpdatedBy: (v) => { storedUpdatedBy = v; },
+        getUpdatedBy: () => storedUpdatedBy,
+        save: sinon.stub().resolves(),
+      };
+    }
+
+    beforeEach(() => {
+      deploySuggestionsStub = sinon.stub(client, 'deploySuggestions');
+      fetchMetaconfigStub = sinon.stub(client, 'fetchMetaconfig');
+      uploadMetaconfigStub = sinon.stub(client, 'uploadMetaconfig').resolves();
+    });
+
+    it('should deploy regular suggestions only', async () => {
+      const s1 = makeSuggestion('s1', { url: 'https://example.com/page1', transformRules: { action: 'replace', selector: 'h1' } });
+      const s2 = makeSuggestion('s2', { url: 'https://example.com/page2', transformRules: { action: 'replace', selector: 'h2' } });
+
+      deploySuggestionsStub.resolves({
+        succeededSuggestions: [s1, s2],
+        failedSuggestions: [],
+      });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [s1, s2],
+        allSuggestions: [s1, s2],
+        updatedBy: 'test-user',
+      });
+
+      expect(result.succeededSuggestions).to.have.length(2);
+      expect(result.failedSuggestions).to.have.length(0);
+      expect(result.coveredSuggestions).to.have.length(0);
+      expect(s1.save).to.have.been.called;
+      expect(s1.getUpdatedBy()).to.equal('test-user');
+    });
+
+    it('should deploy regular suggestions in PENDING_VALIDATION status', async () => {
+      const s1 = makeSuggestion('s1', { url: 'https://example.com/page1', transformRules: {} }, 'PENDING_VALIDATION');
+
+      deploySuggestionsStub.resolves({
+        succeededSuggestions: [s1],
+        failedSuggestions: [],
+      });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [s1],
+        allSuggestions: [s1],
+        updatedBy: 'test-user',
+      });
+
+      expect(result.succeededSuggestions).to.have.length(1);
+      expect(deploySuggestionsStub).to.have.been.calledOnce;
+      expect(s1.save).to.have.been.called;
+    });
+
+    it('should clear edgeOptimizeStatus STALE when deploying', async () => {
+      const s1 = makeSuggestion('s1', { url: 'https://example.com/page1', transformRules: {}, edgeOptimizeStatus: 'STALE' });
+
+      deploySuggestionsStub.resolves({
+        succeededSuggestions: [s1],
+        failedSuggestions: [],
+      });
+
+      await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [s1],
+        allSuggestions: [s1],
+      });
+
+      expect(s1.getData()).to.not.have.property('edgeOptimizeStatus');
+    });
+
+    it('should mark ineligible suggestions as failed with statusCode 400', async () => {
+      const s1 = makeSuggestion('s1', { url: 'https://example.com/page1' });
+      const ineligible = { suggestion: s1, reason: 'not eligible' };
+
+      deploySuggestionsStub.resolves({
+        succeededSuggestions: [],
+        failedSuggestions: [ineligible],
+      });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [s1],
+        allSuggestions: [s1],
+      });
+
+      expect(result.failedSuggestions).to.have.length(1);
+      expect(result.failedSuggestions[0].statusCode).to.equal(400);
+      expect(result.failedSuggestions[0].reason).to.equal('not eligible');
+    });
+
+    it('should re-throw errors from deploySuggestions', async () => {
+      const s1 = makeSuggestion('s1', { url: 'https://example.com/page1' });
+      deploySuggestionsStub.rejects(new Error('deploy error'));
+
+      try {
+        await client.deployToEdge({
+          site: mockSite,
+          opportunity: mockOpportunity,
+          targetSuggestions: [s1],
+          allSuggestions: [s1],
+        });
+        expect.fail('Should have thrown');
+      } catch (error) {
+        expect(error.message).to.equal('deploy error');
+      }
+    });
+
+    it('should deploy domain-wide suggestion and update metaconfig', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123', prerender: true });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw],
+      });
+
+      expect(uploadMetaconfigStub).to.have.been.calledOnce;
+      expect(result.succeededSuggestions).to.include(dw);
+      expect(dw.getData()).to.have.property('edgeDeployed');
+    });
+
+    it('should create new metaconfig when none exists for domain-wide', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+
+      fetchMetaconfigStub.resolves(null);
+
+      await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw],
+      });
+
+      const uploadCall = uploadMetaconfigStub.firstCall.args[1];
+      expect(uploadCall).to.have.property('siteId', 'site-123');
+    });
+
+    it('should mark non-batch suggestions covered by domain-wide patterns', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const covered = makeSuggestion('covered1', { url: 'https://example.com/page1' });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw, covered],
+      });
+
+      expect(result.coveredSuggestions).to.include(covered);
+      expect(covered.getData()).to.have.property('coveredByDomainWide', 'dw1');
+    });
+
+    it('should not mark already-domain-wide suggestions as covered', async () => {
+      const dw1 = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const dw2 = makeSuggestion('dw2', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/other/.*'],
+        url: 'https://example.com/other/page',
+      });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw1],
+        allSuggestions: [dw1, dw2],
+      });
+
+      // dw2 is domain-wide so should not appear in coveredSuggestions
+      expect(result.coveredSuggestions).to.not.include(dw2);
+    });
+
+    it('should not mark non-NEW suggestions as covered', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const approved = makeSuggestion('ap1', { url: 'https://example.com/page1' }, 'APPROVED');
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw, approved],
+      });
+
+      expect(result.coveredSuggestions).to.not.include(approved);
+    });
+
+    it('should warn but continue when covered-suggestion save fails', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const covered = makeSuggestion('covered1', { url: 'https://example.com/page1' });
+      covered.save = sinon.stub().rejects(new Error('DB error'));
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw, covered],
+      });
+
+      // domain-wide itself still succeeded
+      expect(result.succeededSuggestions).to.include(dw);
+      // covered is not in either list — the error was swallowed with a warning
+      expect(result.coveredSuggestions).to.not.include(covered);
+      expect(log.warn).to.have.been.called;
+    });
+
+    it('should mark domain-wide as failed with statusCode 500 when metaconfig upload fails', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+      uploadMetaconfigStub.rejects(new Error('upload failed'));
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw],
+      });
+
+      expect(result.succeededSuggestions).to.not.include(dw);
+      expect(result.failedSuggestions).to.have.length(1);
+      expect(result.failedSuggestions[0].statusCode).to.equal(500);
+      expect(result.failedSuggestions[0].reason).to.equal('upload failed');
+    });
+
+    it('should skip invalid regex in same-batch pattern filtering without throwing', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['[invalid', '^https://example\\.com/.*'],
+      });
+      const regular = makeSuggestion('r1', { url: 'https://example.com/page1' });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw, regular],
+        allSuggestions: [dw, regular],
+      });
+
+      // valid pattern matches regular, so it's skipped in batch
+      expect(result.coveredSuggestions).to.include(regular);
+    });
+
+    it('should skip domain-wide suggestion with no valid allowedRegexPatterns', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: [],
+      });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw],
+      });
+
+      expect(result.succeededSuggestions).to.have.length(0);
+      expect(result.failedSuggestions).to.have.length(0);
+      expect(uploadMetaconfigStub).to.not.have.been.called;
+    });
+
+    it('should warn and skip invalid regex patterns for domain-wide', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['[invalid', '^https://example\\.com/.*'],
+      });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw],
+      });
+
+      expect(log.warn).to.have.been.called;
+      expect(uploadMetaconfigStub).to.have.been.calledOnce;
+    });
+
+    it('should skip same-batch regular suggestions covered by domain-wide patterns', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const regular = makeSuggestion('r1', { url: 'https://example.com/page1' });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw, regular],
+        allSuggestions: [dw, regular],
+      });
+
+      // regular was in same batch as domain-wide, should be marked covered
+      expect(result.coveredSuggestions).to.include(regular);
+      expect(regular.getData()).to.have.property('coveredByDomainWide', 'same-batch-deployment');
+      expect(regular.getData()).to.have.property('skippedInDeployment', true);
+      // deploySuggestions should NOT have been called for the regular suggestion
+      expect(deploySuggestionsStub).to.not.have.been.called;
+    });
+
+    it('should surface same-batch save failures as failed suggestions with statusCode 500', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const regular = makeSuggestion('r1', { url: 'https://example.com/page1' });
+      regular.save = sinon.stub().rejects(new Error('save failed'));
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw, regular],
+        allSuggestions: [dw, regular],
+      });
+
+      expect(result.failedSuggestions.some((f) => f.suggestion === regular)).to.be.true;
+      expect(result.failedSuggestions.find((f) => f.suggestion === regular).statusCode)
+        .to.equal(500);
+      expect(result.coveredSuggestions).to.not.include(regular);
+      expect(log.warn).to.have.been.called;
+    });
+
+    it('should use default updatedBy when not provided', 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(s1.getUpdatedBy()).to.equal('edge-deploy');
+    });
+
+    it('should deploy regular suggestion alongside domain-wide when URL does not match pattern', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/special/.*'],
+      });
+      // URL does not match the domain-wide pattern, so stays in validSuggestions
+      const regular = makeSuggestion('r1', { url: 'https://example.com/other/page' });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+      deploySuggestionsStub.resolves({
+        succeededSuggestions: [regular],
+        failedSuggestions: [],
+      });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw, regular],
+        allSuggestions: [dw, regular],
+      });
+
+      expect(deploySuggestionsStub).to.have.been.calledOnce;
+      expect(result.succeededSuggestions).to.include(regular);
+      expect(result.coveredSuggestions).to.not.include(regular);
+    });
+
+    it('should not call deploySuggestions when all regular suggestions are skipped in batch', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const r1 = makeSuggestion('r1', { url: 'https://example.com/page1' });
+      const r2 = makeSuggestion('r2', { url: 'https://example.com/page2' });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw, r1, r2],
+        allSuggestions: [dw, r1, r2],
+      });
+
+      expect(deploySuggestionsStub).to.not.have.been.called;
+    });
+
+    it('should not include same-batch skipped suggestions in covered-by-pattern check', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const skipped = makeSuggestion('r1', { url: 'https://example.com/page1' });
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw, skipped],
+        allSuggestions: [dw, skipped],
+      });
+
+      // skipped is in same batch, it should be in coveredSuggestions once (via same-batch path)
+      // but NOT doubly added via the per-suggestion covered-marking path
+      const skippedInCovered = result.coveredSuggestions.filter((s) => s.getId() === 'r1');
+      expect(skippedInCovered).to.have.length(1);
+    });
+  });
 });