@reactionary/hcl 0.9.12 → 0.9.13

package/capabilities/analytics.capability.js

@@ -0,0 +1,98 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp(target, key, result);
+  return result;
+};
+import {
+  AnalyticsCapability,
+  AnalyticsMutationSchema,
+  AnalyticsResultSchema,
+  Reactionary
+} from "@reactionary/core";
+import { SESSION_KEY_PERSONALIZATION_ID } from "../core/session-keys.js";
+class HclAnalyticsCapability extends AnalyticsCapability {
+  constructor(cache, context, config, client) {
+    super(cache, context);
+    this.config = config;
+    this.client = client;
+  }
+  async track(event) {
+    return super.track(event);
+  }
+  async processProductSummaryView(event) {
+    try {
+      for (const product of event.products) {
+        await this.fireEvent({ productId: product.key });
+      }
+      return this.accepted();
+    } catch {
+      return this.rejected();
+    }
+  }
+  async processProductSummaryClick(event) {
+    try {
+      await this.fireEvent({ productId: event.product.key });
+      return this.accepted();
+    } catch {
+      return this.rejected();
+    }
+  }
+  async processProductDetailsView(event) {
+    try {
+      await this.fireEvent({ productId: event.product.key });
+      return this.accepted();
+    } catch {
+      return this.rejected();
+    }
+  }
+  async processProductAddToCart(event) {
+    try {
+      await this.fireEvent({ productId: event.product.key });
+      return this.accepted();
+    } catch {
+      return this.rejected();
+    }
+  }
+  async processPurchase(event) {
+    try {
+      for (const item of event.order.items) {
+        await this.fireEvent({ productId: item.variant.sku });
+      }
+      return this.accepted();
+    } catch {
+      return this.rejected();
+    }
+  }
+  async fireEvent(extra) {
+    await this.client.callPost(
+      this.getEventUrl(),
+      this.getEventBody(extra)
+    );
+  }
+  getEventUrl() {
+    return `${this.client.transactionBaseUrl}/event`;
+  }
+  getEventBody(extra) {
+    const personalizationID = this.context.session[SESSION_KEY_PERSONALIZATION_ID];
+    const body = { ...extra };
+    if (personalizationID) {
+      body["personalizationID"] = personalizationID;
+    }
+    return body;
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: AnalyticsMutationSchema,
+    outputSchema: AnalyticsResultSchema
+  })
+], HclAnalyticsCapability.prototype, "track", 1);
+export {
+  HclAnalyticsCapability
+};

package/capabilities/personalization-profile.capability.js

@@ -0,0 +1,85 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp(target, key, result);
+  return result;
+};
+import {
+  PersonalizationProfileCapability,
+  PersonalizationProfileQueryGetProfileSchema,
+  PersonalizationProfileSchema,
+  Reactionary,
+  success
+} from "@reactionary/core";
+import { SESSION_KEY_PERSONALIZATION_ID } from "../core/session-keys.js";
+class HclPersonalizationProfileCapability extends PersonalizationProfileCapability {
+  constructor(cache, context, config, client, factory) {
+    super(cache, context);
+    this.config = config;
+    this.client = client;
+    this.factory = factory;
+  }
+  async getPersonalizationProfile(_payload) {
+    const personalizationId = this.context.session[SESSION_KEY_PERSONALIZATION_ID];
+    if (!personalizationId) {
+      return success(
+        this.factory.parsePersonalizationProfile(this.context, {
+          personalizationId: "anonymous",
+          segments: []
+        })
+      );
+    }
+    const segments = await this.fetchSegments(personalizationId);
+    return success(
+      this.factory.parsePersonalizationProfile(this.context, {
+        personalizationId,
+        segments
+      })
+    );
+  }
+  /**
+   * Calls the WCS segment API to retrieve the customer segments for the given
+   * personalization ID. Returns an empty array when the API call fails or
+   * returns no segment data.
+   */
+  async fetchSegments(personalizationId) {
+    try {
+      const response = await this.client.callGet(
+        this.getSegmentsUrl(),
+        this.getSegmentsParams(personalizationId),
+        { allowUndefined: true }
+      );
+      if (!response?.MemberGroup) {
+        return [];
+      }
+      return response.MemberGroup.map((g) => g.displayName?.value).filter(
+        (name) => name !== void 0 && name.length > 0
+      );
+    } catch {
+      return [];
+    }
+  }
+  getSegmentsUrl() {
+    return `${this.client.transactionBaseUrl}/segment`;
+  }
+  getSegmentsParams(personalizationId) {
+    const params = new URLSearchParams();
+    params.set("q", "byPersonalizationId");
+    params.set("qPersonalizationId", personalizationId);
+    return params;
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: PersonalizationProfileQueryGetProfileSchema,
+    outputSchema: PersonalizationProfileSchema
+  })
+], HclPersonalizationProfileCapability.prototype, "getPersonalizationProfile", 1);
+export {
+  HclPersonalizationProfileCapability
+};

package/capabilities/product-associations.capability.js

@@ -0,0 +1,117 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp(target, key, result);
+  return result;
+};
+import {
+  ProductAssociationsCapability,
+  ProductAssociationSchema,
+  ProductAssociationsGetAccessoriesQuerySchema,
+  ProductAssociationsGetSparepartsQuerySchema,
+  ProductAssociationsGetReplacementsQuerySchema,
+  Reactionary,
+  success
+} from "@reactionary/core";
+import * as z from "zod";
+class HclProductAssociationsCapability extends ProductAssociationsCapability {
+  constructor(cache, context, config, client, factory) {
+    super(cache, context);
+    this.config = config;
+    this.client = client;
+    this.factory = factory;
+  }
+  async getAccessories(query) {
+    const associations = await this.fetchAssociations(
+      query.forProduct.key,
+      this.config.associationTypes.accessories,
+      query.numberOfAccessories
+    );
+    return success(
+      associations.map((a) => this.factory.parseAssociation(this.context, a))
+    );
+  }
+  async getSpareparts(query) {
+    const associations = await this.fetchAssociations(
+      query.forProduct.key,
+      this.config.associationTypes.spareparts,
+      query.numberOfSpareparts
+    );
+    return success(
+      associations.map((a) => this.factory.parseAssociation(this.context, a))
+    );
+  }
+  async getReplacements(query) {
+    const associations = await this.fetchAssociations(
+      query.forProduct.key,
+      this.config.associationTypes.replacements,
+      query.numberOfReplacements
+    );
+    return success(
+      associations.map((a) => this.factory.parseAssociation(this.context, a))
+    );
+  }
+  /**
+   * Fetches the product detail for the given part number and returns the
+   * `merchandisingAssociations` filtered to the requested association types,
+   * capped at `maxCount`.
+   */
+  async fetchAssociations(partNumber, types, maxCount) {
+    const response = await this.client.callGet(
+      this.getProductsUrl(),
+      this.getProductsParams(partNumber)
+    );
+    const product = (response.contents ?? response.catalogEntryView ?? [])[0];
+    if (!product?.merchandisingAssociations) {
+      return [];
+    }
+    return product.merchandisingAssociations.filter(
+      (a) => a.associationCodeType && types.includes(a.associationCodeType)
+    ).slice(0, maxCount);
+  }
+  getProductsUrl() {
+    return `${this.client.catalogBaseUrl}/api/v2/products`;
+  }
+  getProductsParams(partNumber) {
+    const params = new URLSearchParams();
+    params.set("storeId", this.config.storeId);
+    params.append("partNumber", partNumber);
+    params.set("profileName", this.config.profiles.product);
+    return params;
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductAssociationsGetAccessoriesQuerySchema,
+    outputSchema: z.array(ProductAssociationSchema),
+    cache: true,
+    cacheTimeToLiveInSeconds: 300,
+    currencyDependentCaching: false
+  })
+], HclProductAssociationsCapability.prototype, "getAccessories", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductAssociationsGetSparepartsQuerySchema,
+    outputSchema: z.array(ProductAssociationSchema),
+    cache: true,
+    cacheTimeToLiveInSeconds: 300,
+    currencyDependentCaching: false
+  })
+], HclProductAssociationsCapability.prototype, "getSpareparts", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductAssociationsGetReplacementsQuerySchema,
+    outputSchema: z.array(ProductAssociationSchema),
+    cache: true,
+    cacheTimeToLiveInSeconds: 300,
+    currencyDependentCaching: false
+  })
+], HclProductAssociationsCapability.prototype, "getReplacements", 1);
+export {
+  HclProductAssociationsCapability
+};

package/capabilities/product-recommendations.capability.js

@@ -0,0 +1,143 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp(target, key, result);
+  return result;
+};
+import {
+  ProductRecommendationsCapability,
+  ProductRecommendationsQuerySchema,
+  ProductRecommendationsByCollectionQuerySchema,
+  Reactionary,
+  success
+} from "@reactionary/core";
+class HclProductRecommendationsCapability extends ProductRecommendationsCapability {
+  constructor(cache, context, config, client, factory) {
+    super(cache, context);
+    this.config = config;
+    this.client = client;
+    this.factory = factory;
+  }
+  getRecommendations(...args) {
+    return super.getRecommendations(...args);
+  }
+  async getCollection(query) {
+    const params = {
+      productId: query.sourceProduct?.[0]?.key,
+      categoryId: query.sourceCategory?.key,
+      count: String(query.numberOfRecommendations)
+    };
+    const recommendations = await this.fetchEspot(
+      query.collectionName,
+      query.collectionName,
+      params
+    );
+    return success(recommendations.slice(0, query.numberOfRecommendations));
+  }
+  async getFrequentlyBoughtTogetherRecommendations(query) {
+    return this.fetchEspot(
+      this.config.espotNames.frequentlyBoughtTogether,
+      "frequentlyBoughtTogether",
+      {
+        productId: query.sourceProduct.key,
+        count: String(query.numberOfRecommendations)
+      }
+    );
+  }
+  async getSimilarProductsRecommendations(query) {
+    return this.fetchEspot(this.config.espotNames.similar, "similar", {
+      productId: query.sourceProduct.key,
+      count: String(query.numberOfRecommendations)
+    });
+  }
+  async getRelatedProductsRecommendations(query) {
+    return this.fetchEspot(this.config.espotNames.related, "related", {
+      productId: query.sourceProduct.key,
+      count: String(query.numberOfRecommendations)
+    });
+  }
+  async getTrendingInCategoryRecommendations(query) {
+    return this.fetchEspot(
+      this.config.espotNames.trendingInCategory,
+      "trendingInCategory",
+      {
+        categoryId: query.sourceCategory.key,
+        count: String(query.numberOfRecommendations)
+      }
+    );
+  }
+  async getPopularProductsRecommendations(query) {
+    return this.fetchEspot(this.config.espotNames.popular, "popular", {
+      count: String(query.numberOfRecommendations)
+    });
+  }
+  async getTopPicksProductsRecommendations(query) {
+    return this.fetchEspot(this.config.espotNames.topPicks, "topPicks", {
+      count: String(query.numberOfRecommendations)
+    });
+  }
+  async getAlsoViewedProductsRecommendations(query) {
+    return this.fetchEspot(this.config.espotNames.alsoViewed, "alsoViewed", {
+      productId: query.sourceProduct.key,
+      count: String(query.numberOfRecommendations)
+    });
+  }
+  /**
+   * Calls an HCL marketing spot (espot) by name and maps its catalog entry
+   * activity data to `ProductRecommendation[]` using the factory.
+   *
+   * Returns an empty array when the espot is not found (404) or returns no
+   * catalog entry data — allowing teams to configure only the espots they need.
+   */
+  async fetchEspot(name, algorithm, params = {}) {
+    const response = await this.client.callGet(
+      this.getEspotUrl(name),
+      this.getEspotParams(params),
+      { allowUndefined: true }
+    );
+    if (!response) {
+      return [];
+    }
+    const activities = response.MarketingSpotData?.[0]?.baseMarketingSpotActivityData ?? [];
+    return activities.filter(
+      (a) => a.baseMarketingSpotDataType === "CatalogEntry" || a.baseMarketingSpotDataType === "CatalogEntryId"
+    ).map(
+      (a) => this.factory.parseRecommendation(this.context, {
+        activityData: a,
+        algorithm
+      })
+    ).filter((r) => r.product.key !== "");
+  }
+  getEspotUrl(name) {
+    return `${this.client.transactionBaseUrl}/espot/${encodeURIComponent(name)}`;
+  }
+  getEspotParams(params) {
+    const searchParams = new URLSearchParams();
+    const count = params["count"];
+    if (count)
+      searchParams.set("DM_DisplayProducts", count);
+    if (params["productId"])
+      searchParams.set("productId", params["productId"]);
+    if (params["categoryId"])
+      searchParams.set("categoryId", params["categoryId"]);
+    return searchParams;
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductRecommendationsQuerySchema
+  })
+], HclProductRecommendationsCapability.prototype, "getRecommendations", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductRecommendationsByCollectionQuerySchema
+  })
+], HclProductRecommendationsCapability.prototype, "getCollection", 1);
+export {
+  HclProductRecommendationsCapability
+};

package/core/initialize.js

@@ -3,6 +3,9 @@ import {
   IdentitySchema,
   OrderSchema,
   OrderSearchResultSchema,
+  PersonalizationProfileSchema,
+  ProductAssociationSchema,
+  ProductRecommendationSchema,
   ProductSchema,
   ProfileSchema
 } from "@reactionary/core";
@@ -25,8 +28,11 @@ import {
   HclInventoryFactory,
   HclOrderFactory,
   HclOrderSearchFactory,
+  HclPersonalizationProfileFactory,
   HclPriceFactory,
+  HclProductAssociationsFactory,
   HclProductFactory,
+  HclProductRecommendationsFactory,
   HclProductSearchFactory,
   HclProfileFactory
 } from "../factories/index.js";
@@ -41,6 +47,10 @@ import { HclIdentityCapability } from "../capabilities/identity.capability.js";
 import { HclProfileCapability } from "../capabilities/profile.capability.js";
 import { HclOrderCapability } from "../capabilities/order.capability.js";
 import { HclOrderSearchCapability } from "../capabilities/order-search.capability.js";
+import { HclAnalyticsCapability } from "../capabilities/analytics.capability.js";
+import { HclProductAssociationsCapability } from "../capabilities/product-associations.capability.js";
+import { HclProductRecommendationsCapability } from "../capabilities/product-recommendations.capability.js";
+import { HclPersonalizationProfileCapability } from "../capabilities/personalization-profile.capability.js";
 import {
   CartIdentifierSchema,
   CartPaginatedSearchResultSchema,
@@ -252,6 +262,73 @@ function withHclCapabilities(configuration, capabilities) {
         buildCapabilityArgs
       );
     }
+    if (caps.analytics?.enabled) {
+      const analyticsCap = capabilities.analytics;
+      if (analyticsCap?.capability) {
+        client.analytics = analyticsCap.capability(
+          buildCapabilityArgs(void 0)
+        );
+      } else {
+        client.analytics = new HclAnalyticsCapability(
+          cache,
+          context,
+          config,
+          hclClient
+        );
+      }
+    }
+    if (caps.productAssociations?.enabled) {
+      client.productAssociations = resolveCapabilityWithFactory(
+        capabilities.productAssociations,
+        {
+          factory: new HclProductAssociationsFactory(ProductAssociationSchema),
+          capability: (args) => new HclProductAssociationsCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
+    if (caps.productRecommendations?.enabled) {
+      client.productRecommendations = resolveCapabilityWithFactory(
+        capabilities.productRecommendations,
+        {
+          factory: new HclProductRecommendationsFactory(
+            ProductRecommendationSchema
+          ),
+          capability: (args) => new HclProductRecommendationsCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
+    if (caps.personalizationProfile?.enabled) {
+      client.personalizationProfile = resolveCapabilityWithFactory(
+        capabilities.personalizationProfile,
+        {
+          factory: new HclPersonalizationProfileFactory(
+            PersonalizationProfileSchema
+          ),
+          capability: (args) => new HclPersonalizationProfileCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
     return client;
   };
 }

package/factories/index.js

@@ -9,3 +9,6 @@ export * from "./identity/identity.factory.js";
 export * from "./profile/profile.factory.js";
 export * from "./order/order.factory.js";
 export * from "./order-search/order-search.factory.js";
+export * from "./product-associations/product-associations.factory.js";
+export * from "./product-recommendations/product-recommendations.factory.js";
+export * from "./personalization-profile/personalization-profile.factory.js";

package/factories/personalization-profile/personalization-profile.factory.js

@@ -0,0 +1,16 @@
+class HclPersonalizationProfileFactory {
+  personalizationProfileSchema;
+  constructor(personalizationProfileSchema) {
+    this.personalizationProfileSchema = personalizationProfileSchema;
+  }
+  parsePersonalizationProfile(_context, data) {
+    return this.personalizationProfileSchema.parse({
+      identifier: { key: data.personalizationId },
+      segments: data.segments,
+      blurb: ""
+    });
+  }
+}
+export {
+  HclPersonalizationProfileFactory
+};

package/factories/product-associations/product-associations.factory.js

@@ -0,0 +1,16 @@
+class HclProductAssociationsFactory {
+  productAssociationSchema;
+  constructor(productAssociationSchema) {
+    this.productAssociationSchema = productAssociationSchema;
+  }
+  parseAssociation(_context, data) {
+    return this.productAssociationSchema.parse({
+      associationIdentifier: { key: data.partNumber },
+      associationReturnType: "idOnly",
+      product: { key: data.partNumber }
+    });
+  }
+}
+export {
+  HclProductAssociationsFactory
+};

package/factories/product-recommendations/product-recommendations.factory.js

@@ -0,0 +1,17 @@
+class HclProductRecommendationsFactory {
+  productRecommendationSchema;
+  constructor(productRecommendationSchema) {
+    this.productRecommendationSchema = productRecommendationSchema;
+  }
+  parseRecommendation(_context, data) {
+    const key = data.activityData.partNumber ?? data.activityData.contentId ?? "";
+    return this.productRecommendationSchema.parse({
+      recommendationIdentifier: { key, algorithm: data.algorithm },
+      recommendationReturnType: "idOnly",
+      product: { key }
+    });
+  }
+}
+export {
+  HclProductRecommendationsFactory
+};

package/index.js

@@ -17,3 +17,7 @@ export * from "./capabilities/identity.capability.js";
 export * from "./capabilities/profile.capability.js";
 export * from "./capabilities/order.capability.js";
 export * from "./capabilities/order-search.capability.js";
+export * from "./capabilities/analytics.capability.js";
+export * from "./capabilities/product-associations.capability.js";
+export * from "./capabilities/product-recommendations.capability.js";
+export * from "./capabilities/personalization-profile.capability.js";

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@reactionary/hcl",
-  "version": "0.9.12",
+  "version": "0.9.13",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",
   "dependencies": {
-    "@reactionary/core": "0.9.12",
+    "@reactionary/core": "0.9.13",
     "debug": "^4.4.3",
     "zod": "4.1.9"
   },

package/schema/capabilities.schema.js

@@ -16,7 +16,11 @@ const HclCapabilitiesSchema = CapabilitiesSchema.pick({
   productSearch: true,
   profile: true,
   order: true,
-  orderSearch: true
+  orderSearch: true,
+  analytics: true,
+  productAssociations: true,
+  productRecommendations: true,
+  personalizationProfile: true
 }).extend({
   cart: OverridableCapabilitySchema.optional(),
   checkout: OverridableCapabilitySchema.optional(),
@@ -28,7 +32,11 @@ const HclCapabilitiesSchema = CapabilitiesSchema.pick({
   productSearch: OverridableCapabilitySchema.optional(),
   profile: OverridableCapabilitySchema.optional(),
   order: OverridableCapabilitySchema.optional(),
-  orderSearch: OverridableCapabilitySchema.optional()
+  orderSearch: OverridableCapabilitySchema.optional(),
+  analytics: OverridableCapabilitySchema.optional(),
+  productAssociations: OverridableCapabilitySchema.optional(),
+  productRecommendations: OverridableCapabilitySchema.optional(),
+  personalizationProfile: OverridableCapabilitySchema.optional()
 }).partial();
 export {
   HclCapabilitiesSchema

package/schema/configuration.schema.js

@@ -37,7 +37,43 @@ const HclConfigurationSchema = z.looseObject({
    */
   priceRuleId: z.string().optional().meta({
     description: "Price rule ID for /display_price WCS calls. Optional \u2014 the server uses its default rule when absent."
-  })
+  }),
+  /**
+   * Maps Reactionary association types to the HCL `associationCodeType` values
+   * returned in `merchandisingAssociations` on product detail responses.
+   * Override to match custom HCL store configuration.
+   */
+  associationTypes: z.looseObject({
+    accessories: z.array(z.string()).default(["ACCESSORY"]),
+    spareparts: z.array(z.string()).default(["SPAREPART"]),
+    replacements: z.array(z.string()).default(["REPLACEMENT"])
+  }).default(() => ({
+    accessories: ["ACCESSORY"],
+    spareparts: ["SPAREPART"],
+    replacements: ["REPLACEMENT"]
+  })),
+  /**
+   * Names of HCL marketing spots used for product recommendation algorithms.
+   * Each algorithm calls the corresponding named espot via the WCS Transaction Service.
+   * These espots must be configured in HCL Commerce to return catalog entry data.
+   */
+  espotNames: z.looseObject({
+    frequentlyBoughtTogether: z.string().default("Reactionary_FrequentlyBoughtTogether"),
+    similar: z.string().default("Reactionary_SimilarProducts"),
+    related: z.string().default("Reactionary_RelatedProducts"),
+    trendingInCategory: z.string().default("Reactionary_TrendingInCategory"),
+    popular: z.string().default("Reactionary_Popular"),
+    topPicks: z.string().default("Reactionary_TopPicks"),
+    alsoViewed: z.string().default("Reactionary_AlsoViewed")
+  }).default(() => ({
+    frequentlyBoughtTogether: "Reactionary_FrequentlyBoughtTogether",
+    similar: "Reactionary_SimilarProducts",
+    related: "Reactionary_RelatedProducts",
+    trendingInCategory: "Reactionary_TrendingInCategory",
+    popular: "Reactionary_Popular",
+    topPicks: "Reactionary_TopPicks",
+    alsoViewed: "Reactionary_AlsoViewed"
+  }))
 });
 export {
   HclConfigurationSchema

package/src/capabilities/analytics.capability.d.ts

@@ -0,0 +1,17 @@
+import { AnalyticsCapability, type AnalyticsMutation, type AnalyticsMutationProductAddToCartEvent, type AnalyticsMutationProductDetailsViewEvent, type AnalyticsMutationProductSummaryClickEvent, type AnalyticsMutationProductSummaryViewEvent, type AnalyticsMutationPurchaseEvent, type AnalyticsResult, type Cache, type RequestContext } from '@reactionary/core';
+import type { HclConfiguration } from '../schema/configuration.schema.js';
+import type { HclClient } from '../core/client.js';
+export declare class HclAnalyticsCapability extends AnalyticsCapability {
+    protected readonly config: HclConfiguration;
+    protected readonly client: HclClient;
+    constructor(cache: Cache, context: RequestContext, config: HclConfiguration, client: HclClient);
+    track(event: AnalyticsMutation): Promise<AnalyticsResult>;
+    protected processProductSummaryView(event: AnalyticsMutationProductSummaryViewEvent): Promise<AnalyticsResult>;
+    protected processProductSummaryClick(event: AnalyticsMutationProductSummaryClickEvent): Promise<AnalyticsResult>;
+    protected processProductDetailsView(event: AnalyticsMutationProductDetailsViewEvent): Promise<AnalyticsResult>;
+    protected processProductAddToCart(event: AnalyticsMutationProductAddToCartEvent): Promise<AnalyticsResult>;
+    protected processPurchase(event: AnalyticsMutationPurchaseEvent): Promise<AnalyticsResult>;
+    protected fireEvent(extra: Record<string, string>): Promise<void>;
+    protected getEventUrl(): string;
+    protected getEventBody(extra: Record<string, string>): Record<string, string>;
+}

package/src/capabilities/personalization-profile.capability.d.ts

@@ -0,0 +1,19 @@
+import { PersonalizationProfileCapability, type Cache, type NotFoundError, type PersonalizationProfileFactory, type PersonalizationProfileFactoryOutput, type PersonalizationProfileFactoryWithOutput, type PersonalizationProfileQueryGetProfile, type RequestContext, type Result } from '@reactionary/core';
+import type { HclConfiguration } from '../schema/configuration.schema.js';
+import type { HclClient } from '../core/client.js';
+import type { HclPersonalizationProfileFactory } from '../factories/personalization-profile/personalization-profile.factory.js';
+export declare class HclPersonalizationProfileCapability<TFactory extends PersonalizationProfileFactory = HclPersonalizationProfileFactory> extends PersonalizationProfileCapability<PersonalizationProfileFactoryOutput<TFactory>> {
+    protected readonly config: HclConfiguration;
+    protected readonly client: HclClient;
+    protected readonly factory: PersonalizationProfileFactoryWithOutput<TFactory>;
+    constructor(cache: Cache, context: RequestContext, config: HclConfiguration, client: HclClient, factory: PersonalizationProfileFactoryWithOutput<TFactory>);
+    getPersonalizationProfile(_payload: PersonalizationProfileQueryGetProfile): Promise<Result<PersonalizationProfileFactoryOutput<TFactory>, NotFoundError>>;
+    /**
+     * Calls the WCS segment API to retrieve the customer segments for the given
+     * personalization ID. Returns an empty array when the API call fails or
+     * returns no segment data.
+     */
+    protected fetchSegments(personalizationId: string): Promise<string[]>;
+    protected getSegmentsUrl(): string;
+    protected getSegmentsParams(personalizationId: string): URLSearchParams;
+}

package/src/capabilities/product-associations.capability.d.ts

@@ -0,0 +1,22 @@
+import { ProductAssociationsCapability, type Cache, type ProductAssociationsFactory, type ProductAssociationsFactoryOutput, type ProductAssociationsFactoryWithOutput, type ProductAssociationsGetAccessoriesQuery, type ProductAssociationsGetReplacementsQuery, type ProductAssociationsGetSparepartsQuery, type RequestContext, type Result } from '@reactionary/core';
+import type { HclConfiguration } from '../schema/configuration.schema.js';
+import type { HclClient } from '../core/client.js';
+import type { HclAssociation } from '../schema/hcl.schema.js';
+import type { HclProductAssociationsFactory } from '../factories/product-associations/product-associations.factory.js';
+export declare class HclProductAssociationsCapability<TFactory extends ProductAssociationsFactory = HclProductAssociationsFactory> extends ProductAssociationsCapability<ProductAssociationsFactoryOutput<TFactory>> {
+    protected readonly config: HclConfiguration;
+    protected readonly client: HclClient;
+    protected readonly factory: ProductAssociationsFactoryWithOutput<TFactory>;
+    constructor(cache: Cache, context: RequestContext, config: HclConfiguration, client: HclClient, factory: ProductAssociationsFactoryWithOutput<TFactory>);
+    getAccessories(query: ProductAssociationsGetAccessoriesQuery): Promise<Result<ProductAssociationsFactoryOutput<TFactory>[]>>;
+    getSpareparts(query: ProductAssociationsGetSparepartsQuery): Promise<Result<ProductAssociationsFactoryOutput<TFactory>[]>>;
+    getReplacements(query: ProductAssociationsGetReplacementsQuery): Promise<Result<ProductAssociationsFactoryOutput<TFactory>[]>>;
+    /**
+     * Fetches the product detail for the given part number and returns the
+     * `merchandisingAssociations` filtered to the requested association types,
+     * capped at `maxCount`.
+     */
+    protected fetchAssociations(partNumber: string, types: string[], maxCount: number): Promise<HclAssociation[]>;
+    protected getProductsUrl(): string;
+    protected getProductsParams(partNumber: string): URLSearchParams;
+}

package/src/capabilities/product-recommendations.capability.d.ts

@@ -0,0 +1,29 @@
+import { ProductRecommendationsCapability, type Cache, type ProductRecommendation, type ProductRecommendationAlgorithmAlsoViewedProductsQuery, type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery, type ProductRecommendationAlgorithmPopuplarProductsQuery, type ProductRecommendationAlgorithmRelatedProductsQuery, type ProductRecommendationAlgorithmSimilarProductsQuery, type ProductRecommendationAlgorithmTopPicksProductsQuery, type ProductRecommendationAlgorithmTrendingInCategoryQuery, type ProductRecommendationsByCollectionQuery, type ProductRecommendationsFactory, type ProductRecommendationsFactoryWithOutput, type RequestContext, type Result } from '@reactionary/core';
+import type { HclConfiguration } from '../schema/configuration.schema.js';
+import type { HclClient } from '../core/client.js';
+import type { HclProductRecommendationsFactory } from '../factories/product-recommendations/product-recommendations.factory.js';
+export declare class HclProductRecommendationsCapability<TFactory extends ProductRecommendationsFactory = HclProductRecommendationsFactory> extends ProductRecommendationsCapability {
+    protected readonly config: HclConfiguration;
+    protected readonly client: HclClient;
+    protected readonly factory: ProductRecommendationsFactoryWithOutput<TFactory>;
+    constructor(cache: Cache, context: RequestContext, config: HclConfiguration, client: HclClient, factory: ProductRecommendationsFactoryWithOutput<TFactory>);
+    getRecommendations(...args: Parameters<ProductRecommendationsCapability['getRecommendations']>): Promise<Result<ProductRecommendation[]>>;
+    getCollection(query: ProductRecommendationsByCollectionQuery): Promise<Result<ProductRecommendation[]>>;
+    protected getFrequentlyBoughtTogetherRecommendations(query: ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery): Promise<ProductRecommendation[]>;
+    protected getSimilarProductsRecommendations(query: ProductRecommendationAlgorithmSimilarProductsQuery): Promise<ProductRecommendation[]>;
+    protected getRelatedProductsRecommendations(query: ProductRecommendationAlgorithmRelatedProductsQuery): Promise<ProductRecommendation[]>;
+    protected getTrendingInCategoryRecommendations(query: ProductRecommendationAlgorithmTrendingInCategoryQuery): Promise<ProductRecommendation[]>;
+    protected getPopularProductsRecommendations(query: ProductRecommendationAlgorithmPopuplarProductsQuery): Promise<ProductRecommendation[]>;
+    protected getTopPicksProductsRecommendations(query: ProductRecommendationAlgorithmTopPicksProductsQuery): Promise<ProductRecommendation[]>;
+    protected getAlsoViewedProductsRecommendations(query: ProductRecommendationAlgorithmAlsoViewedProductsQuery): Promise<ProductRecommendation[]>;
+    /**
+     * Calls an HCL marketing spot (espot) by name and maps its catalog entry
+     * activity data to `ProductRecommendation[]` using the factory.
+     *
+     * Returns an empty array when the espot is not found (404) or returns no
+     * catalog entry data — allowing teams to configure only the espots they need.
+     */
+    protected fetchEspot(name: string, algorithm: string, params?: Record<string, string | undefined>): Promise<ProductRecommendation[]>;
+    protected getEspotUrl(name: string): string;
+    protected getEspotParams(params: Record<string, string | undefined>): URLSearchParams;
+}

package/src/factories/index.d.ts

@@ -9,3 +9,6 @@ export * from './identity/identity.factory.js';
 export * from './profile/profile.factory.js';
 export * from './order/order.factory.js';
 export * from './order-search/order-search.factory.js';
+export * from './product-associations/product-associations.factory.js';
+export * from './product-recommendations/product-recommendations.factory.js';
+export * from './personalization-profile/personalization-profile.factory.js';

package/src/factories/personalization-profile/personalization-profile.factory.d.ts

@@ -0,0 +1,11 @@
+import type { AnyPersonalizationProfileSchema, PersonalizationProfileFactory, PersonalizationProfileSchema, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+export interface HclPersonalizationProfileData {
+    personalizationId: string;
+    segments: string[];
+}
+export declare class HclPersonalizationProfileFactory<TPersonalizationProfileSchema extends AnyPersonalizationProfileSchema = typeof PersonalizationProfileSchema> implements PersonalizationProfileFactory<TPersonalizationProfileSchema> {
+    readonly personalizationProfileSchema: TPersonalizationProfileSchema;
+    constructor(personalizationProfileSchema: TPersonalizationProfileSchema);
+    parsePersonalizationProfile(_context: RequestContext, data: HclPersonalizationProfileData): z.output<TPersonalizationProfileSchema>;
+}

package/src/factories/product-associations/product-associations.factory.d.ts

@@ -0,0 +1,8 @@
+import type { AnyProductAssociationSchema, ProductAssociationSchema, ProductAssociationsFactory, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+import type { HclAssociation } from '../../schema/hcl.schema.js';
+export declare class HclProductAssociationsFactory<TProductAssociationSchema extends AnyProductAssociationSchema = typeof ProductAssociationSchema> implements ProductAssociationsFactory<TProductAssociationSchema> {
+    readonly productAssociationSchema: TProductAssociationSchema;
+    constructor(productAssociationSchema: TProductAssociationSchema);
+    parseAssociation(_context: RequestContext, data: HclAssociation): z.output<TProductAssociationSchema>;
+}

package/src/factories/product-recommendations/product-recommendations.factory.d.ts

@@ -0,0 +1,12 @@
+import type { AnyProductRecommendationSchema, ProductRecommendationSchema, ProductRecommendationsFactory, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+import type { HclEspotActivityData } from '../../schema/hcl.schema.js';
+export interface HclEspotRecommendationData {
+    activityData: HclEspotActivityData;
+    algorithm: string;
+}
+export declare class HclProductRecommendationsFactory<TProductRecommendationSchema extends AnyProductRecommendationSchema = typeof ProductRecommendationSchema> implements ProductRecommendationsFactory<TProductRecommendationSchema> {
+    readonly productRecommendationSchema: TProductRecommendationSchema;
+    constructor(productRecommendationSchema: TProductRecommendationSchema);
+    parseRecommendation(_context: RequestContext, data: HclEspotRecommendationData): z.output<TProductRecommendationSchema>;
+}

package/src/index.d.ts

@@ -17,3 +17,7 @@ export * from './capabilities/identity.capability.js';
 export * from './capabilities/profile.capability.js';
 export * from './capabilities/order.capability.js';
 export * from './capabilities/order-search.capability.js';
+export * from './capabilities/analytics.capability.js';
+export * from './capabilities/product-associations.capability.js';
+export * from './capabilities/product-recommendations.capability.js';
+export * from './capabilities/personalization-profile.capability.js';

package/src/schema/capabilities.schema.d.ts

@@ -1,4 +1,4 @@
-import type { Cache, RequestContext, CartFactory, CartFactoryWithOutput, CartCapability, CategoryFactory, CategoryFactoryWithOutput, CategoryCapability, CheckoutFactory, CheckoutFactoryWithOutput, CheckoutCapability, IdentityFactory, IdentityFactoryWithOutput, IdentityCapability, InventoryFactory, InventoryFactoryWithOutput, InventoryCapability, OrderFactory, OrderFactoryWithOutput, OrderCapability, OrderSearchFactory, OrderSearchFactoryWithOutput, OrderSearchCapability, PriceFactory, PriceFactoryWithOutput, PriceCapability, ProductFactory, ProductFactoryWithOutput, ProductCapability, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability, ProfileFactory, ProfileFactoryWithOutput, ProfileCapability } from '@reactionary/core';
+import type { Cache, RequestContext, AnalyticsCapability, CartFactory, CartFactoryWithOutput, CartCapability, CategoryFactory, CategoryFactoryWithOutput, CategoryCapability, CheckoutFactory, CheckoutFactoryWithOutput, CheckoutCapability, IdentityFactory, IdentityFactoryWithOutput, IdentityCapability, InventoryFactory, InventoryFactoryWithOutput, InventoryCapability, OrderFactory, OrderFactoryWithOutput, OrderCapability, OrderSearchFactory, OrderSearchFactoryWithOutput, OrderSearchCapability, PersonalizationProfileCapability, PersonalizationProfileFactory, PersonalizationProfileFactoryWithOutput, PriceFactory, PriceFactoryWithOutput, PriceCapability, ProductAssociationsCapability, ProductAssociationsFactory, ProductAssociationsFactoryWithOutput, ProductFactory, ProductFactoryWithOutput, ProductCapability, ProductRecommendationsCapability, ProductRecommendationsFactory, ProductRecommendationsFactoryWithOutput, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability, ProfileFactory, ProfileFactoryWithOutput, ProfileCapability } from '@reactionary/core';
 import type { HclConfiguration } from './configuration.schema.js';
 import type { HclClient } from '../core/client.js';
 import * as z from 'zod';
@@ -58,6 +58,26 @@ export declare const HclCapabilitiesSchema: z.ZodObject<{
         factory: z.ZodOptional<z.ZodUnknown>;
         capability: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$loose>>>;
+    analytics: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    productAssociations: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    productRecommendations: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    personalizationProfile: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 export type HclCapabilities = z.infer<typeof HclCapabilitiesSchema>;
 export interface HclCapabilityFactoryArgs {
@@ -85,3 +105,9 @@ export type HclIdentityCapabilityConfig = HclCapabilityConfig<IdentityFactoryWit
 export type HclProfileCapabilityConfig = HclCapabilityConfig<ProfileFactoryWithOutput<ProfileFactory>, ProfileCapability>;
 export type HclOrderCapabilityConfig = HclCapabilityConfig<OrderFactoryWithOutput<OrderFactory>, OrderCapability>;
 export type HclOrderSearchCapabilityConfig = HclCapabilityConfig<OrderSearchFactoryWithOutput<OrderSearchFactory>, OrderSearchCapability>;
+/** Analytics does not use a factory — the capability writes events directly. */
+export type HclAnalyticsCapabilityConfig = HclCapabilityConfig<never, AnalyticsCapability>;
+export type HclProductAssociationsCapabilityConfig = HclCapabilityConfig<ProductAssociationsFactoryWithOutput<ProductAssociationsFactory>, ProductAssociationsCapability>;
+/** Product recommendations uses a factory to parse espot activity data into recommendations. */
+export type HclProductRecommendationsCapabilityConfig = HclCapabilityConfig<ProductRecommendationsFactoryWithOutput<ProductRecommendationsFactory>, ProductRecommendationsCapability>;
+export type HclPersonalizationProfileCapabilityConfig = HclCapabilityConfig<PersonalizationProfileFactoryWithOutput<PersonalizationProfileFactory>, PersonalizationProfileCapability>;

package/src/schema/configuration.schema.d.ts

@@ -21,5 +21,29 @@ export declare const HclConfigurationSchema: z.ZodObject<{
      * In Karkkainen this is '10003'.
      */
     priceRuleId: z.ZodOptional<z.ZodString>;
+    /**
+     * Maps Reactionary association types to the HCL `associationCodeType` values
+     * returned in `merchandisingAssociations` on product detail responses.
+     * Override to match custom HCL store configuration.
+     */
+    associationTypes: z.ZodDefault<z.ZodObject<{
+        accessories: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        spareparts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        replacements: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+    /**
+     * Names of HCL marketing spots used for product recommendation algorithms.
+     * Each algorithm calls the corresponding named espot via the WCS Transaction Service.
+     * These espots must be configured in HCL Commerce to return catalog entry data.
+     */
+    espotNames: z.ZodDefault<z.ZodObject<{
+        frequentlyBoughtTogether: z.ZodDefault<z.ZodString>;
+        similar: z.ZodDefault<z.ZodString>;
+        related: z.ZodDefault<z.ZodString>;
+        trendingInCategory: z.ZodDefault<z.ZodString>;
+        popular: z.ZodDefault<z.ZodString>;
+        topPicks: z.ZodDefault<z.ZodString>;
+        alsoViewed: z.ZodDefault<z.ZodString>;
+    }, z.core.$loose>>;
 }, z.core.$loose>;
 export type HclConfiguration = z.infer<typeof HclConfigurationSchema>;

package/src/schema/hcl.schema.d.ts

@@ -234,7 +234,7 @@ export interface HclProductResponse extends HclProductSearchItem {
     components?: HclProductResponse[];
     /** Quantity — only present on components array elements */
     quantity?: string;
-    merchandisingAssociations?: HclProductResponse[];
+    merchandisingAssociations?: HclAssociation[];
     attachments?: HclAttachment[];
     images?: HclImage[];
     /**
@@ -694,3 +694,61 @@ export interface HclWcsOrderHistoryResponse {
     recordSetStartNumber?: string;
     recordSetComplete?: string;
 }
+/**
+ * A product item returned within a `merchandisingAssociations` array on a
+ * HCL detail-profile product response. Extends the search item shape with
+ * an `associationCodeType` that identifies the semantic relationship.
+ *
+ * Known values: 'ACCESSORY', 'SPAREPART', 'REPLACEMENT', 'CROSSSELL', 'UPSELL', 'UPGRADE'
+ */
+export interface HclAssociation extends HclProductSearchItem {
+    /** The association type code. e.g. 'ACCESSORY', 'SPAREPART', 'REPLACEMENT'. */
+    associationCodeType?: string;
+    /** Display sequence for ordering associations within a type. */
+    associationSequence?: string;
+}
+/**
+ * A single activity data entry within a marketing spot response.
+ * When `baseMarketingSpotDataType` is 'CatalogEntry' or 'CatalogEntryId',
+ * the entry represents a product recommendation from the spot.
+ */
+export interface HclEspotActivityData {
+    /** 'CatalogEntry' | 'CatalogEntryId' | 'CatalogGroupId' | 'MarketingContent' */
+    baseMarketingSpotDataType?: string;
+    /** Internal HCL product uniqueID (numeric string). Present for CatalogEntry/CatalogEntryId types. */
+    contentId?: string;
+    /** Part number of the product, if returned inline by the spot configuration. */
+    partNumber?: string;
+    /** Display name of the product or content entry. */
+    contentName?: string;
+}
+/** A single marketing spot entry in a WCS espot response. */
+export interface HclEspotMarketingSpot {
+    eSpotName?: string;
+    baseMarketingSpotActivityData?: HclEspotActivityData[];
+}
+/** Top-level response from GET /wcs/resources/store/{storeId}/espot/{name}. */
+export interface HclEspotResponse {
+    MarketingSpotData?: HclEspotMarketingSpot[];
+}
+/** A single customer segment (member group) entry in a WCS segment response. */
+export interface HclSegmentMemberGroup {
+    id: string;
+    displayName?: {
+        language: number;
+        value: string;
+    };
+    description?: {
+        language: number;
+        value: string;
+    };
+    usage?: string[];
+}
+/** Top-level response from GET /wcs/resources/store/{storeId}/segment. */
+export interface HclSegmentResponse {
+    MemberGroup?: HclSegmentMemberGroup[];
+    recordSetTotal?: number;
+    recordSetCount?: number;
+    recordSetStartNumber?: number;
+    recordSetComplete?: boolean;
+}