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

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@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.9.0",
   "description": "Tokowaka Client for SpaceCat - Edge optimization config management",
   "type": "module",
   "engines": {

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