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

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@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
+
+* **AGENTCOM-266:** add commerce page enrichment mapper for tokowaka edge deployment ([#1369](https://github.com/adobe/spacecat-shared/issues/1369)) ([357f2f4](https://github.com/adobe/spacecat-shared/commit/357f2f44cd8da19272a7638b55870873388840c9))
+
 ## [@adobe/spacecat-shared-tokowaka-client-v1.8.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.7.8...@adobe/spacecat-shared-tokowaka-client-v1.8.0) (2026-02-18)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.8.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/src/mappers/commerce-page-enrichment-mapper.js

@@ -0,0 +1,128 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { hasText } from '@adobe/spacecat-shared-utils';
+import { TARGET_USER_AGENTS_CATEGORIES } from '../constants.js';
+import BaseOpportunityMapper from './base-mapper.js';
+
+const SCHEMA_ORG_DIRECT_FIELDS = {
+  sku: 'sku',
+  name: 'name',
+  material: 'material',
+  category: 'category',
+  color_family: 'color',
+  'pdp.description_plain': 'description',
+};
+
+const EXCLUDED_FIELDS = new Set([
+  'rationale',
+]);
+
+function toJsonLd(enrichmentData) {
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+  };
+
+  const additionalProperties = [];
+
+  for (const [key, value] of Object.entries(enrichmentData)) {
+    if (!EXCLUDED_FIELDS.has(key) && value != null) {
+      if (key === 'brand' && typeof value === 'string') {
+        jsonLd.brand = { '@type': 'Brand', name: value };
+      } else if (key === 'facts.facets.category_path' && Array.isArray(value)) {
+        jsonLd.category = value.join(' > ');
+      } else if (SCHEMA_ORG_DIRECT_FIELDS[key]) {
+        jsonLd[SCHEMA_ORG_DIRECT_FIELDS[key]] = value;
+      } else {
+        additionalProperties.push({
+          '@type': 'PropertyValue',
+          name: key,
+          value,
+        });
+      }
+    }
+  }
+
+  if (additionalProperties.length > 0) {
+    jsonLd.additionalProperty = additionalProperties;
+  }
+
+  return jsonLd;
+}
+
+export default class CommercePageEnrichmentMapper extends BaseOpportunityMapper {
+  constructor(log) {
+    super(log);
+    this.opportunityType = 'commerce-product-page-enrichment';
+    this.prerenderRequired = true;
+  }
+
+  getOpportunityType() {
+    return this.opportunityType;
+  }
+
+  requiresPrerender() {
+    return this.prerenderRequired;
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  canDeploy(suggestion) {
+    const data = suggestion.getData();
+
+    if (!hasText(data?.patchValue)) {
+      return { eligible: false, reason: 'patchValue is required' };
+    }
+
+    if (!hasText(data?.url)) {
+      return { eligible: false, reason: 'url is required' };
+    }
+
+    try {
+      JSON.parse(data.patchValue);
+    } catch {
+      return { eligible: false, reason: 'patchValue must be valid JSON' };
+    }
+
+    return { eligible: true };
+  }
+
+  suggestionsToPatches(urlPath, suggestions, opportunityId) {
+    const patches = [];
+
+    suggestions.forEach((suggestion) => {
+      const eligibility = this.canDeploy(suggestion);
+      if (!eligibility.eligible) {
+        this.log.warn(`Commerce page enrichment suggestion ${suggestion.getId()} cannot be deployed: ${eligibility.reason}`);
+        return;
+      }
+
+      const data = suggestion.getData();
+      const enrichmentData = JSON.parse(data.patchValue);
+
+      const jsonLd = toJsonLd(enrichmentData);
+
+      patches.push({
+        ...this.createBasePatch(suggestion, opportunityId),
+        op: 'appendChild',
+        selector: 'head',
+        value: jsonLd,
+        valueFormat: 'json',
+        target: TARGET_USER_AGENTS_CATEGORIES.AI_BOTS,
+        tag: 'script',
+        attrs: { type: 'application/ld+json' },
+      });
+    });
+
+    return patches;
+  }
+}

package/src/mappers/mapper-registry.js

@@ -17,6 +17,7 @@ import ReadabilityMapper from './readability-mapper.js';
 import TocMapper from './toc-mapper.js';
 import GenericMapper from './generic-mapper.js';
 import PrerenderMapper from './prerender-mapper.js';
+import CommercePageEnrichmentMapper from './commerce-page-enrichment-mapper.js';
 import SemanticValueVisibilityMapper from './semantic-value-visibility-mapper.js';
 
 /**
@@ -43,6 +44,7 @@ export default class MapperRegistry {
       TocMapper,
       GenericMapper,
       PrerenderMapper,
+      CommercePageEnrichmentMapper,
       SemanticValueVisibilityMapper,
     ];
 

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', () => {

package/test/mappers/commerce-page-enrichment-mapper.test.js

@@ -0,0 +1,453 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/* eslint-env mocha */
+
+import { expect } from 'chai';
+import sinon from 'sinon';
+import CommercePageEnrichmentMapper from '../../src/mappers/commerce-page-enrichment-mapper.js';
+
+describe('CommercePageEnrichmentMapper', () => {
+  let mapper;
+  let log;
+
+  beforeEach(() => {
+    log = {
+      debug: sinon.stub(),
+      info: sinon.stub(),
+      warn: sinon.stub(),
+      error: sinon.stub(),
+    };
+    mapper = new CommercePageEnrichmentMapper(log);
+  });
+
+  describe('getOpportunityType', () => {
+    it('should return commerce-product-page-enrichment', () => {
+      expect(mapper.getOpportunityType()).to.equal('commerce-product-page-enrichment');
+    });
+  });
+
+  describe('requiresPrerender', () => {
+    it('should return true', () => {
+      expect(mapper.requiresPrerender()).to.be.true;
+    });
+  });
+
+  describe('allowConfigsWithoutPatch', () => {
+    it('should return false', () => {
+      expect(mapper.allowConfigsWithoutPatch()).to.be.false;
+    });
+  });
+
+  describe('canDeploy', () => {
+    const validPatchValue = JSON.stringify({
+      sku: 'HT5695',
+      'pdp.description_plain': 'A product description.',
+    });
+
+    it('should return eligible for suggestion with patchValue and url', () => {
+      const suggestion = {
+        getData: () => ({
+          patchValue: validPatchValue,
+          url: 'https://www.lovesac.com/products/seat-cover-set',
+        }),
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({ eligible: true });
+    });
+
+    it('should return eligible when transformRules is absent', () => {
+      const suggestion = {
+        getData: () => ({
+          patchValue: validPatchValue,
+          url: 'https://www.lovesac.com/products/seat-cover-set',
+          format: 'json',
+          tag: 'div',
+        }),
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({ eligible: true });
+    });
+
+    it('should return eligible when transformRules is null', () => {
+      const suggestion = {
+        getData: () => ({
+          patchValue: validPatchValue,
+          url: 'https://www.lovesac.com/products/seat-cover-set',
+          transformRules: null,
+        }),
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({ eligible: true });
+    });
+
+    it('should return ineligible when patchValue is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          url: 'https://example.com/page',
+        }),
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({
+        eligible: false,
+        reason: 'patchValue is required',
+      });
+    });
+
+    it('should return ineligible when patchValue is empty string', () => {
+      const suggestion = {
+        getData: () => ({
+          patchValue: '',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({
+        eligible: false,
+        reason: 'patchValue is required',
+      });
+    });
+
+    it('should return ineligible when url is missing', () => {
+      const suggestion = {
+        getData: () => ({
+          patchValue: validPatchValue,
+        }),
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({
+        eligible: false,
+        reason: 'url is required',
+      });
+    });
+
+    it('should return ineligible when url is empty string', () => {
+      const suggestion = {
+        getData: () => ({
+          patchValue: validPatchValue,
+          url: '',
+        }),
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({
+        eligible: false,
+        reason: 'url is required',
+      });
+    });
+
+    it('should return ineligible when patchValue is not valid JSON', () => {
+      const suggestion = {
+        getData: () => ({
+          patchValue: 'not valid json {{{',
+          url: 'https://example.com/page',
+        }),
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({
+        eligible: false,
+        reason: 'patchValue must be valid JSON',
+      });
+    });
+
+    it('should return ineligible when data is null', () => {
+      const suggestion = {
+        getData: () => null,
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({
+        eligible: false,
+        reason: 'patchValue is required',
+      });
+    });
+
+    it('should return ineligible when data is undefined', () => {
+      const suggestion = {
+        getData: () => undefined,
+      };
+
+      expect(mapper.canDeploy(suggestion)).to.deep.equal({
+        eligible: false,
+        reason: 'patchValue is required',
+      });
+    });
+  });
+
+  describe('suggestionsToPatches', () => {
+    const opportunityId = '03189e92-ac0f-4436-965a-0a7b55fc4101';
+    const suggestionId = '2fec9113-98e8-40b4-90e0-10aa9ce45abc';
+    const updatedAt = '2026-02-17T09:48:58.974Z';
+
+    function makeSuggestion(data, id = suggestionId) {
+      return {
+        getId: () => id,
+        getUpdatedAt: () => updatedAt,
+        getData: () => data,
+      };
+    }
+
+    it('should produce a JSON-LD patch appended to head', () => {
+      const suggestion = makeSuggestion({
+        patchValue: JSON.stringify({
+          sku: 'HT5695',
+          name: 'Seat Cover Set',
+          brand: 'Lovesac',
+          'pdp.description_plain': 'A great product.',
+        }),
+        url: 'https://www.lovesac.com/products/seat-cover-set',
+      });
+
+      const patches = mapper.suggestionsToPatches(
+        '/products/seat-cover-set',
+        [suggestion],
+        opportunityId,
+      );
+
+      expect(patches).to.have.length(1);
+      const patch = patches[0];
+
+      expect(patch.op).to.equal('appendChild');
+      expect(patch.selector).to.equal('head');
+      expect(patch.valueFormat).to.equal('json');
+      expect(patch.target).to.equal('ai-bots');
+      expect(patch.tag).to.equal('script');
+      expect(patch.attrs).to.deep.equal({ type: 'application/ld+json' });
+      expect(patch.opportunityId).to.equal(opportunityId);
+      expect(patch.suggestionId).to.equal(suggestionId);
+      expect(patch.prerenderRequired).to.be.true;
+      expect(patch.lastUpdated).to.be.a('number');
+    });
+
+    it('should produce valid schema.org Product JSON-LD', () => {
+      const suggestion = makeSuggestion({
+        patchValue: JSON.stringify({
+          sku: 'HT5695',
+          name: 'Seat Cover Set',
+          brand: 'Lovesac',
+          'pdp.description_plain': 'A great product.',
+          material: '100% polyester chenille',
+          'facts.facets.category_path': ['Home', 'Sactionals', 'Covers'],
+          color_family: 'Blue',
+        }),
+        url: 'https://www.lovesac.com/products/seat-cover-set',
+      });
+
+      const patches = mapper.suggestionsToPatches(
+        '/products/seat-cover-set',
+        [suggestion],
+        opportunityId,
+      );
+
+      const jsonLd = patches[0].value;
+      expect(jsonLd['@context']).to.equal('https://schema.org');
+      expect(jsonLd['@type']).to.equal('Product');
+      expect(jsonLd.sku).to.equal('HT5695');
+      expect(jsonLd.name).to.equal('Seat Cover Set');
+      expect(jsonLd.brand).to.deep.equal({ '@type': 'Brand', name: 'Lovesac' });
+      expect(jsonLd.description).to.equal('A great product.');
+      expect(jsonLd.material).to.equal('100% polyester chenille');
+      expect(jsonLd.category).to.equal('Home > Sactionals > Covers');
+      expect(jsonLd.color).to.equal('Blue');
+    });
+
+    it('should map unmapped fields to additionalProperty', () => {
+      const suggestion = makeSuggestion({
+        patchValue: JSON.stringify({
+          sku: 'HT5695',
+          'pdp.feature_bullets': ['Bullet 1', 'Bullet 2'],
+          'facts.attributes.fabric_care': 'Machine washable',
+          audience_tags: ['homeowners', 'families'],
+        }),
+        url: 'https://www.lovesac.com/products/seat-cover-set',
+      });
+
+      const patches = mapper.suggestionsToPatches(
+        '/products/seat-cover-set',
+        [suggestion],
+        opportunityId,
+      );
+
+      const jsonLd = patches[0].value;
+      expect(jsonLd.additionalProperty).to.be.an('array');
+
+      const bulletsProp = jsonLd.additionalProperty.find((p) => p.name === 'pdp.feature_bullets');
+      expect(bulletsProp).to.exist;
+      expect(bulletsProp.value).to.deep.equal(['Bullet 1', 'Bullet 2']);
+
+      const careProp = jsonLd.additionalProperty.find((p) => p.name === 'facts.attributes.fabric_care');
+      expect(careProp).to.exist;
+      expect(careProp.value).to.equal('Machine washable');
+    });
+
+    it('should handle minimal enrichment data (only sku)', () => {
+      const suggestion = makeSuggestion({
+        patchValue: JSON.stringify({ sku: 'MINIMAL' }),
+        url: 'https://example.com/products/minimal',
+      });
+
+      const patches = mapper.suggestionsToPatches(
+        '/products/minimal',
+        [suggestion],
+        opportunityId,
+      );
+
+      expect(patches).to.have.length(1);
+      const jsonLd = patches[0].value;
+      expect(jsonLd['@context']).to.equal('https://schema.org');
+      expect(jsonLd['@type']).to.equal('Product');
+      expect(jsonLd.sku).to.equal('MINIMAL');
+    });
+
+    it('should handle rich enrichment data with all field types', () => {
+      const suggestion = makeSuggestion({
+        patchValue: JSON.stringify({
+          sku: '4Seats5Sides',
+          name: '4 Seats + 5 Sides Sactional',
+          category: 'Sectional / Modular Sofa',
+          brand: 'Lovesac',
+          'pdp.description_plain': 'A modular sofa configuration.',
+          'pdp.feature_bullets': ['Includes 4 Seats', 'StealthTech eligible'],
+          'facts.facets.category_path': ['Furniture', 'Sectionals', 'Sactionals'],
+          'facts.variants.summary': ['Multiple fabric options'],
+          material: 'Corded Velvet',
+          dimensions_or_capacity: '35" W x 29" D',
+          care_instructions: ['Machine washable'],
+          color_family: 'Grey',
+          audience_tags: ['homeowners'],
+          use_context: ['living room'],
+          style_tags: ['modern'],
+          keyword_synonyms: ['modular couch'],
+          persona_phrases: ['for families'],
+        }),
+        url: 'https://www.lovesac.com/products/4-seats-5-sides',
+      });
+
+      const patches = mapper.suggestionsToPatches(
+        '/products/4-seats-5-sides',
+        [suggestion],
+        opportunityId,
+      );
+
+      expect(patches).to.have.length(1);
+      const jsonLd = patches[0].value;
+      expect(jsonLd.sku).to.equal('4Seats5Sides');
+      expect(jsonLd.name).to.equal('4 Seats + 5 Sides Sactional');
+      expect(jsonLd.category).to.equal('Furniture > Sectionals > Sactionals');
+      expect(jsonLd.brand).to.deep.equal({ '@type': 'Brand', name: 'Lovesac' });
+      expect(jsonLd.description).to.equal('A modular sofa configuration.');
+      expect(jsonLd.material).to.equal('Corded Velvet');
+      expect(jsonLd.color).to.equal('Grey');
+      expect(jsonLd.additionalProperty).to.be.an('array');
+      expect(jsonLd.additionalProperty.length).to.be.greaterThan(0);
+    });
+
+    it('should skip ineligible suggestions and log warning', () => {
+      const eligible = makeSuggestion({
+        patchValue: JSON.stringify({ sku: 'GOOD' }),
+        url: 'https://example.com/good',
+      }, 'good-id');
+
+      const ineligible = makeSuggestion({
+        patchValue: '',
+        url: 'https://example.com/bad',
+      }, 'bad-id');
+
+      const patches = mapper.suggestionsToPatches(
+        '/test',
+        [eligible, ineligible],
+        opportunityId,
+      );
+
+      expect(patches).to.have.length(1);
+      expect(patches[0].suggestionId).to.equal('good-id');
+      expect(log.warn.calledOnce).to.be.true;
+    });
+
+    it('should produce multiple patches for multiple suggestions', () => {
+      const s1 = makeSuggestion({
+        patchValue: JSON.stringify({ sku: 'SKU1' }),
+        url: 'https://example.com/page',
+      }, 'id-1');
+
+      const s2 = makeSuggestion({
+        patchValue: JSON.stringify({ sku: 'SKU2' }),
+        url: 'https://example.com/page',
+      }, 'id-2');
+
+      const patches = mapper.suggestionsToPatches(
+        '/page',
+        [s1, s2],
+        opportunityId,
+      );
+
+      expect(patches).to.have.length(2);
+      expect(patches[0].suggestionId).to.equal('id-1');
+      expect(patches[1].suggestionId).to.equal('id-2');
+    });
+
+    it('should not include rationale field in JSON-LD output', () => {
+      const suggestion = makeSuggestion({
+        patchValue: JSON.stringify({
+          sku: 'HT5695',
+          rationale: 'This should not appear in output',
+        }),
+        url: 'https://example.com/page',
+      });
+
+      const patches = mapper.suggestionsToPatches(
+        '/page',
+        [suggestion],
+        opportunityId,
+      );
+
+      const jsonLd = patches[0].value;
+      expect(jsonLd.rationale).to.be.undefined;
+      const rationaleProp = (jsonLd.additionalProperty || []).find((p) => p.name === 'rationale');
+      expect(rationaleProp).to.be.undefined;
+    });
+
+    it('should join category_path array with > separator', () => {
+      const suggestion = makeSuggestion({
+        patchValue: JSON.stringify({
+          sku: 'TEST',
+          'facts.facets.category_path': ['Home', 'Furniture', 'Sofas'],
+        }),
+        url: 'https://example.com/page',
+      });
+
+      const patches = mapper.suggestionsToPatches(
+        '/page',
+        [suggestion],
+        opportunityId,
+      );
+
+      expect(patches[0].value.category).to.equal('Home > Furniture > Sofas');
+    });
+
+    it('should use category field directly when facts.facets.category_path is absent', () => {
+      const suggestion = makeSuggestion({
+        patchValue: JSON.stringify({
+          sku: 'TEST',
+          category: 'Sectional / Modular Sofa',
+        }),
+        url: 'https://example.com/page',
+      });
+
+      const patches = mapper.suggestionsToPatches(
+        '/page',
+        [suggestion],
+        opportunityId,
+      );
+
+      expect(patches[0].value.category).to.equal('Sectional / Modular Sofa');
+    });
+  });
+});

package/test/mappers/mapper-registry.test.js

@@ -18,6 +18,7 @@ import sinon from 'sinon';
 import sinonChai from 'sinon-chai';
 import MapperRegistry from '../../src/mappers/mapper-registry.js';
 import HeadingsMapper from '../../src/mappers/headings-mapper.js';
+import CommercePageEnrichmentMapper from '../../src/mappers/commerce-page-enrichment-mapper.js';
 import BaseOpportunityMapper from '../../src/mappers/base-mapper.js';
 
 use(sinonChai);
@@ -115,6 +116,12 @@ describe('MapperRegistry', () => {
       expect(mapper).to.be.instanceOf(HeadingsMapper);
     });
 
+    it('should return commerce page enrichment mapper', () => {
+      const mapper = registry.getMapper('commerce-product-page-enrichment');
+
+      expect(mapper).to.be.instanceOf(CommercePageEnrichmentMapper);
+    });
+
     it('should return null for unsupported opportunity type', () => {
       const mapper = registry.getMapper('unsupported-type');
 
@@ -143,6 +150,7 @@ describe('MapperRegistry', () => {
 
       expect(types).to.be.an('array');
       expect(types).to.include('headings');
+      expect(types).to.include('commerce-product-page-enrichment');
     });
 
     it('should include custom registered mappers', () => {