@reactionary/hcl 0.9.11 → 0.9.13

package/package.json

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

package/schema/capabilities.schema.js

@@ -13,7 +13,14 @@ const HclCapabilitiesSchema = CapabilitiesSchema.pick({
   price: true,
   inventory: true,
   identity: true,
-  productSearch: true
+  productSearch: true,
+  profile: true,
+  order: true,
+  orderSearch: true,
+  analytics: true,
+  productAssociations: true,
+  productRecommendations: true,
+  personalizationProfile: true
 }).extend({
   cart: OverridableCapabilitySchema.optional(),
   checkout: OverridableCapabilitySchema.optional(),
@@ -22,7 +29,14 @@ const HclCapabilitiesSchema = CapabilitiesSchema.pick({
   price: OverridableCapabilitySchema.optional(),
   inventory: OverridableCapabilitySchema.optional(),
   identity: OverridableCapabilitySchema.optional(),
-  productSearch: OverridableCapabilitySchema.optional()
+  productSearch: OverridableCapabilitySchema.optional(),
+  profile: OverridableCapabilitySchema.optional(),
+  order: 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/order-search.capability.d.ts

@@ -0,0 +1,13 @@
+import { type Cache, OrderSearchCapability, type OrderSearchFactory, type OrderSearchFactoryOutput, type OrderSearchFactoryWithOutput, type OrderSearchQueryByTerm, type RequestContext, type Result } from '@reactionary/core';
+import type { HclConfiguration } from '../schema/configuration.schema.js';
+import type { HclClient } from '../core/client.js';
+import type { HclOrderSearchFactory } from '../factories/order-search/order-search.factory.js';
+export declare class HclOrderSearchCapability<TFactory extends OrderSearchFactory = HclOrderSearchFactory> extends OrderSearchCapability<OrderSearchFactoryOutput<TFactory>> {
+    protected config: HclConfiguration;
+    protected client: HclClient;
+    protected factory: OrderSearchFactoryWithOutput<TFactory>;
+    constructor(cache: Cache, context: RequestContext, config: HclConfiguration, client: HclClient, factory: OrderSearchFactoryWithOutput<TFactory>);
+    queryByTerm(payload: OrderSearchQueryByTerm): Promise<Result<OrderSearchFactoryOutput<TFactory>>>;
+    protected orderByStatusUrl(statuses: string): string;
+    protected orderByStatusParams(maxResults: number, startIndex: number): URLSearchParams;
+}

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

@@ -0,0 +1,13 @@
+import { type Cache, type NotFoundError, OrderCapability, type OrderFactory, type OrderFactoryOutput, type OrderFactoryWithOutput, type OrderQueryById, type RequestContext, type Result } from '@reactionary/core';
+import type { HclConfiguration } from '../schema/configuration.schema.js';
+import type { HclClient } from '../core/client.js';
+import type { HclOrderFactory } from '../factories/order/order.factory.js';
+export declare class HclOrderCapability<TFactory extends OrderFactory = HclOrderFactory> extends OrderCapability<OrderFactoryOutput<TFactory>> {
+    protected config: HclConfiguration;
+    protected client: HclClient;
+    protected factory: OrderFactoryWithOutput<TFactory>;
+    constructor(cache: Cache, context: RequestContext, config: HclConfiguration, client: HclClient, factory: OrderFactoryWithOutput<TFactory>);
+    getById(payload: OrderQueryById): Promise<Result<OrderFactoryOutput<TFactory>, NotFoundError>>;
+    protected orderUrl(orderId: string): string;
+    protected orderParams(): URLSearchParams;
+}

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/capabilities/profile.capability.d.ts

@@ -0,0 +1,31 @@
+import { type Address, type Cache, type NotFoundError, ProfileCapability, type ProfileFactory, type ProfileFactoryOutput, type ProfileFactoryWithOutput, type ProfileMutationAddShippingAddress, type ProfileMutationMakeShippingAddressDefault, type ProfileMutationRemoveShippingAddress, type ProfileMutationSetBillingAddress, type ProfileMutationUpdate, type ProfileMutationUpdateShippingAddress, type ProfileQuerySelf, type RequestContext, type Result } from '@reactionary/core';
+import type { HclConfiguration } from '../schema/configuration.schema.js';
+import type { HclClient } from '../core/client.js';
+import type { HclProfileFactory } from '../factories/profile/profile.factory.js';
+import type { HclPersonResponse, HclWcsPersonContact } from '../schema/hcl.schema.js';
+export declare class HclProfileCapability<TFactory extends ProfileFactory = HclProfileFactory> extends ProfileCapability<ProfileFactoryOutput<TFactory>> {
+    protected config: HclConfiguration;
+    protected client: HclClient;
+    protected factory: ProfileFactoryWithOutput<TFactory>;
+    constructor(cache: Cache, context: RequestContext, config: HclConfiguration, client: HclClient, factory: ProfileFactoryWithOutput<TFactory>);
+    protected fetchPerson(): Promise<HclPersonResponse>;
+    protected fetchProfile(): Promise<ProfileFactoryOutput<TFactory>>;
+    protected toWcsContact(address: Address): Partial<HclWcsPersonContact>;
+    protected personSelfUrl(): string;
+    protected updatePersonPayload(email?: string, phone?: string): {
+        email1?: string;
+        phone1?: string;
+    };
+    protected personContactListUrl(): string;
+    protected contactUrl(nickName: string): string;
+    protected makeShippingAddressDefaultPayload(): {
+        primary: string;
+    };
+    getById(_payload: ProfileQuerySelf): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    update(payload: ProfileMutationUpdate): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    addShippingAddress(payload: ProfileMutationAddShippingAddress): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    updateShippingAddress(payload: ProfileMutationUpdateShippingAddress): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    removeShippingAddress(payload: ProfileMutationRemoveShippingAddress): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    makeShippingAddressDefault(payload: ProfileMutationMakeShippingAddressDefault): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    setBillingAddress(payload: ProfileMutationSetBillingAddress): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+}

package/src/core/initialize.types.d.ts

@@ -8,7 +8,10 @@ import type { HclProductSearchCapability } from '../capabilities/product-search.
 import type { HclPriceCapability } from '../capabilities/price.capability.js';
 import type { HclInventoryCapability } from '../capabilities/inventory.capability.js';
 import type { HclIdentityCapability } from '../capabilities/identity.capability.js';
-type OverridableCapabilityKey = 'product' | 'productSearch' | 'cart' | 'checkout' | 'category' | 'price' | 'inventory' | 'identity';
+import type { HclProfileCapability } from '../capabilities/profile.capability.js';
+import type { HclOrderCapability } from '../capabilities/order.capability.js';
+import type { HclOrderSearchCapability } from '../capabilities/order-search.capability.js';
+type OverridableCapabilityKey = 'product' | 'productSearch' | 'cart' | 'checkout' | 'category' | 'price' | 'inventory' | 'identity' | 'profile' | 'order' | 'orderSearch';
 type EnabledCapability<TCapability> = TCapability extends {
     enabled: true;
 } ? true : false;
@@ -28,6 +31,9 @@ type DefaultCapabilityMap = {
     price: HclPriceCapability;
     inventory: HclInventoryCapability;
     identity: HclIdentityCapability;
+    profile: HclProfileCapability;
+    order: HclOrderCapability;
+    orderSearch: HclOrderSearchCapability;
 };
 type CapabilityImplementationMap<T extends HclCapabilities> = {
     [K in OverridableCapabilityKey]: ExtractCapabilityImplementation<T[K], DefaultCapabilityMap[K]>;

package/src/factories/index.d.ts

@@ -6,3 +6,9 @@ export * from './product-search/product-search.factory.js';
 export * from './price/price.factory.js';
 export * from './inventory/inventory.factory.js';
 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/order/order.factory.d.ts

@@ -0,0 +1,11 @@
+import type { AnyOrderSchema, CostBreakDown, Currency, OrderFactory, OrderItem, OrderSchema, PaymentInstruction, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+import type { HclWcsOrderDetailResponse, HclWcsOrderItem, HclWcsPaymentInstruction } from '../../schema/hcl.schema.js';
+export declare class HclOrderFactory<TOrderSchema extends AnyOrderSchema = typeof OrderSchema> implements OrderFactory<TOrderSchema> {
+    readonly orderSchema: TOrderSchema;
+    constructor(orderSchema: TOrderSchema);
+    parseOrder(context: RequestContext, data: HclWcsOrderDetailResponse): z.output<TOrderSchema>;
+    protected parseOrderItem(_context: RequestContext, item: HclWcsOrderItem, defaultCurrency: Currency): OrderItem;
+    protected parseCostBreakdown(_context: RequestContext, data: HclWcsOrderDetailResponse, currency: Currency): CostBreakDown;
+    protected parsePaymentInstruction(_context: RequestContext, pi: HclWcsPaymentInstruction, defaultCurrency: Currency): PaymentInstruction;
+}

package/src/factories/order-search/order-search.factory.d.ts

@@ -0,0 +1,9 @@
+import type { AnyOrderSearchResultSchema, OrderSearchFactory, OrderSearchQueryByTerm, OrderSearchResultItem, OrderSearchResultSchema, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+import type { HclWcsCartResponse, HclWcsOrderListResponse } from '../../schema/hcl.schema.js';
+export declare class HclOrderSearchFactory<TOrderSearchResultSchema extends AnyOrderSearchResultSchema = typeof OrderSearchResultSchema> implements OrderSearchFactory<TOrderSearchResultSchema> {
+    readonly orderSearchResultSchema: TOrderSearchResultSchema;
+    constructor(orderSearchResultSchema: TOrderSearchResultSchema);
+    parseOrderSearchResult(context: RequestContext, data: HclWcsOrderListResponse, query: OrderSearchQueryByTerm): z.output<TOrderSearchResultSchema>;
+    protected parseOrderSearchResultItem(_context: RequestContext, item: HclWcsCartResponse): OrderSearchResultItem;
+}

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/factories/profile/profile.factory.d.ts

@@ -0,0 +1,9 @@
+import type { Address, AnyProfileSchema, ProfileFactory, ProfileSchema, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+import type { HclPersonResponse, HclWcsPersonContact } from '../../schema/hcl.schema.js';
+export declare class HclProfileFactory<TProfileSchema extends AnyProfileSchema = typeof ProfileSchema> implements ProfileFactory<TProfileSchema> {
+    readonly profileSchema: TProfileSchema;
+    constructor(profileSchema: TProfileSchema);
+    parseProfile(context: RequestContext, data: HclPersonResponse): z.output<TProfileSchema>;
+    protected parseAddress(_context: RequestContext, contact: HclWcsPersonContact): Address;
+}

package/src/index.d.ts

@@ -14,3 +14,10 @@ export * from './capabilities/product-search.capability.js';
 export * from './capabilities/price.capability.js';
 export * from './capabilities/inventory.capability.js';
 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, PriceFactory, PriceFactoryWithOutput, PriceCapability, ProductFactory, ProductFactoryWithOutput, ProductCapability, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability } 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';
@@ -43,6 +43,41 @@ export declare const HclCapabilitiesSchema: z.ZodObject<{
         factory: z.ZodOptional<z.ZodUnknown>;
         capability: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$loose>>>;
+    profile: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    order: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    orderSearch: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        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 {
@@ -67,3 +102,12 @@ export type HclPriceCapabilityConfig = HclCapabilityConfig<PriceFactoryWithOutpu
 export type HclProductCapabilityConfig = HclCapabilityConfig<ProductFactoryWithOutput<ProductFactory>, ProductCapability>;
 export type HclProductSearchCapabilityConfig = HclCapabilityConfig<ProductSearchFactoryWithOutput<ProductSearchFactory>, ProductSearchCapability>;
 export type HclIdentityCapabilityConfig = HclCapabilityConfig<IdentityFactoryWithOutput<IdentityFactory>, IdentityCapability>;
+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[];
     /**
@@ -427,6 +427,31 @@ export interface HclWcsIdentityResponse {
     personalizationID?: string;
     resourceName?: string;
 }
+/**
+ * A single entry in a WCS person address book (contact list).
+ * Returned as part of the GET /person/@self response (contact[] field)
+ * and used for POST/PUT /person/@self/contact operations.
+ */
+export interface HclWcsPersonContact {
+    /** Unique identifier / display name for this address (e.g. 'Home', 'Work', 'Billing'). */
+    nickName: string;
+    firstName?: string;
+    lastName?: string;
+    /** Street address lines. Index 0 = street, index 1 = apartment / second line. */
+    addressLine?: string[];
+    /** Alternative single-field address (some WCS endpoint variants). */
+    address1?: string;
+    city?: string;
+    stateOrProvinceName?: string;
+    zipCode?: string;
+    /** ISO country code, e.g. 'US'. */
+    country?: string;
+    phone1?: string;
+    email1?: string;
+    /** '1' marks this as the default / primary shipping address. */
+    primary?: string;
+    addressType?: string;
+}
 /**
  * Response from GET /wcs/resources/store/{storeId}/person/@self.
  * Only the fields we use are typed; the full WCS schema has many more.
@@ -439,9 +464,12 @@ export interface HclPersonResponse {
     email1?: string;
     firstName?: string;
     lastName?: string;
+    phone1?: string;
     resourceName?: string;
     /** Organization ID. `-2000` indicates the default anonymous org. */
     orgizationId?: string;
+    /** Address book entries embedded in the person/@self response. */
+    contact?: HclWcsPersonContact[];
 }
 /** A single order item embedded in a WCS cart/@self response. */
 export interface HclWcsOrderItem {
@@ -631,3 +659,96 @@ export interface HclWcsCreateOrderResponse {
     redirecturl?: string;
     viewTaskName?: string;
 }
+/**
+ * A full order as returned by GET /wcs/resources/store/{storeId}/order/{orderId}.
+ * Extends the cart response shape with the `placedDate` field that is only
+ * present on placed (non-active) orders.
+ */
+export interface HclWcsOrderDetailResponse extends HclWcsCartResponse {
+    /** Date/time when the order was placed, e.g. '2024-01-15T10:30:00.000Z'. */
+    placedDate?: string;
+}
+/**
+ * A single summary entry in a GET /wcs/resources/store/{storeId}/order/@history response.
+ * Contains only the fields available in the history list; use getById for full detail.
+ */
+export interface HclWcsOrderHistoryItem {
+    orderId: string;
+    /** WCS order status code, e.g. 'P', 'M', 'S', 'X'. */
+    status: string;
+    placedDate?: string;
+    grandTotal?: string;
+    grandTotalCurrency?: string;
+    totalProductPrice?: string;
+    orderDescription?: string;
+    buyerDistinguishedName?: string;
+}
+/**
+ * Top-level response from GET /wcs/resources/store/{storeId}/order/@history.
+ * Returns a paginated list of the buyer's past orders.
+ */
+export interface HclWcsOrderHistoryResponse {
+    Order?: HclWcsOrderHistoryItem[];
+    recordSetTotal?: string;
+    recordSetCount?: string;
+    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;
+}

package/src/test/test-utils.d.ts

@@ -5,12 +5,15 @@ export declare function createHclClient(contextOverrides?: Partial<RequestContex
     product?: true | undefined;
     productSearch?: true | undefined;
     price?: false | undefined;
+    order?: false | undefined;
     cart?: false | undefined;
     checkout?: false | undefined;
     identity?: false | undefined;
+    profile?: false | undefined;
     inventory?: false | undefined;
     category?: true | undefined;
-}>, "product" | "productSearch" | "price" | "cart" | "checkout" | "identity" | "inventory" | "category"> & {
+    orderSearch?: false | undefined;
+}>, "product" | "productSearch" | "price" | "order" | "cart" | "checkout" | "identity" | "profile" | "inventory" | "category" | "orderSearch"> & {
     product: import("../index.js").HclProductCapability<import("../index.js").HclProductFactory<import("zod").ZodObject<{
         identifier: import("zod").ZodObject<{
             key: import("zod").ZodString;