@reactionary/hcl 0.9.7 → 0.9.11

package/core/initialize.js

@@ -1,5 +1,6 @@
 import {
   CategoryPaginatedResultSchema,
+  IdentitySchema,
   ProductSchema
 } from "@reactionary/core";
 import { HclCategorySchema } from "../schema/category.schema.js";
@@ -14,20 +15,40 @@ import {
 } from "./initialize.types.js";
 import { HclClient } from "./client.js";
 import {
+  HclCartFactory,
   HclCategoryFactory,
+  HclCheckoutFactory,
+  HclIdentityFactory,
+  HclInventoryFactory,
+  HclPriceFactory,
   HclProductFactory,
   HclProductSearchFactory
 } from "../factories/index.js";
+import { HclCartCapability } from "../capabilities/cart.capability.js";
+import { HclCheckoutCapability } from "../capabilities/checkout.capability.js";
 import { HclProductCapability } from "../capabilities/product.capability.js";
 import { HclCategoryCapability } from "../capabilities/category.capability.js";
 import { HclProductSearchCapability } from "../capabilities/product-search.capability.js";
-import { ProductSearchResultSchema } from "@reactionary/core";
+import { HclPriceCapability } from "../capabilities/price.capability.js";
+import { HclInventoryCapability } from "../capabilities/inventory.capability.js";
+import { HclIdentityCapability } from "../capabilities/identity.capability.js";
+import {
+  CartIdentifierSchema,
+  CartPaginatedSearchResultSchema,
+  CartSchema,
+  CheckoutSchema,
+  InventorySchema,
+  PaymentMethodSchema,
+  PriceSchema,
+  ProductSearchResultSchema,
+  ShippingMethodSchema
+} from "@reactionary/core";
 function withHclCapabilities(configuration, capabilities) {
   return (cache, context) => {
     const client = {};
     const config = HclConfigurationSchema.parse(configuration);
     const caps = HclCapabilitiesSchema.parse(capabilities);
-    const hclClient = new HclClient(config);
+    const hclClient = new HclClient(config, context);
     const buildCapabilityArgs = (factory) => ({
       cache,
       context,
@@ -35,9 +56,48 @@ function withHclCapabilities(configuration, capabilities) {
       hclClient,
       factory
     });
+    if (caps.cart?.enabled) {
+      client.cart = resolveCapabilityWithFactory(
+        capabilities.cart,
+        {
+          factory: new HclCartFactory(
+            CartSchema,
+            CartIdentifierSchema,
+            CartPaginatedSearchResultSchema
+          ),
+          capability: (args) => new HclCartCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
+    if (caps.checkout?.enabled) {
+      client.checkout = resolveCapabilityWithFactory(
+        capabilities.checkout,
+        {
+          factory: new HclCheckoutFactory(
+            CheckoutSchema,
+            ShippingMethodSchema,
+            PaymentMethodSchema
+          ),
+          capability: (args) => new HclCheckoutCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
     if (caps.product?.enabled) {
       client.product = resolveCapabilityWithFactory(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         capabilities.product,
         {
           factory: new HclProductFactory(ProductSchema),
@@ -54,7 +114,6 @@ function withHclCapabilities(configuration, capabilities) {
     }
     if (caps.category?.enabled) {
       client.category = resolveCapabilityWithFactory(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         capabilities.category,
         {
           factory: new HclCategoryFactory(
@@ -74,7 +133,6 @@ function withHclCapabilities(configuration, capabilities) {
     }
     if (caps.productSearch?.enabled) {
       client.productSearch = resolveCapabilityWithFactory(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         capabilities.productSearch,
         {
           factory: new HclProductSearchFactory(ProductSearchResultSchema),
@@ -89,6 +147,54 @@ function withHclCapabilities(configuration, capabilities) {
         buildCapabilityArgs
       );
     }
+    if (caps.price?.enabled) {
+      client.price = resolveCapabilityWithFactory(
+        capabilities.price,
+        {
+          factory: new HclPriceFactory(PriceSchema),
+          capability: (args) => new HclPriceCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
+    if (caps.inventory?.enabled) {
+      client.inventory = resolveCapabilityWithFactory(
+        capabilities.inventory,
+        {
+          factory: new HclInventoryFactory(InventorySchema),
+          capability: (args) => new HclInventoryCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
+    if (caps.identity?.enabled) {
+      client.identity = resolveCapabilityWithFactory(
+        capabilities.identity,
+        {
+          factory: new HclIdentityFactory(IdentitySchema),
+          capability: (args) => new HclIdentityCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
     return client;
   };
 }

package/core/session-keys.js

@@ -0,0 +1,14 @@
+const SESSION_KEY_WC_TOKEN = "hcl.WCToken";
+const SESSION_KEY_WC_TRUSTED_TOKEN = "hcl.WCTrustedToken";
+const SESSION_KEY_USER_ID = "hcl.userId";
+const SESSION_KEY_IDENTITY_TYPE = "hcl.identityType";
+const SESSION_KEY_PERSONALIZATION_ID = "hcl.personalizationID";
+const SESSION_KEY_PRICE_RULE_ID = "hcl.priceRuleId";
+export {
+  SESSION_KEY_IDENTITY_TYPE,
+  SESSION_KEY_PERSONALIZATION_ID,
+  SESSION_KEY_PRICE_RULE_ID,
+  SESSION_KEY_USER_ID,
+  SESSION_KEY_WC_TOKEN,
+  SESSION_KEY_WC_TRUSTED_TOKEN
+};

package/factories/cart/cart.factory.js

@@ -0,0 +1,135 @@
+import {
+  CartIdentifierSchema,
+  CartPaginatedSearchResultSchema
+} from "@reactionary/core";
+class HclCartFactory {
+  constructor(cartSchema, cartIdentifierSchema = CartIdentifierSchema, cartPaginatedSearchResultSchema = CartPaginatedSearchResultSchema) {
+    this.cartSchema = cartSchema;
+    this.cartIdentifierSchema = cartIdentifierSchema;
+    this.cartPaginatedSearchResultSchema = cartPaginatedSearchResultSchema;
+  }
+  parseCart(context, data) {
+    const cart = data;
+    const currency = cart.totalProductPriceCurrency ?? cart.grandTotalCurrency ?? "USD";
+    return this.cartSchema.parse({
+      identifier: { key: cart.orderId },
+      user: { userId: cart.buyerId ?? "" },
+      company: cart.orgUniqueID ? { id: cart.orgUniqueID } : void 0,
+      name: cart.orderDescription ?? context.session["hcl.cartName"] ?? "",
+      description: "",
+      items: (cart.orderItem ?? []).map((item) => ({
+        identifier: { key: item.orderItemId },
+        product: { key: item.productId ?? "" },
+        variant: { sku: item.partNumber },
+        quantity: Number(item.quantity),
+        price: {
+          unitPrice: {
+            value: Number(item.unitPrice),
+            currency: item.currency
+          },
+          totalPrice: {
+            value: Number(item.orderItemPrice),
+            currency: item.currency
+          },
+          unitDiscount: { value: 0, currency: item.currency },
+          totalDiscount: { value: 0, currency: item.currency }
+        }
+      })),
+      price: {
+        grandTotal: {
+          value: Number(cart.grandTotal ?? "0"),
+          currency
+        },
+        totalProductPrice: {
+          value: Number(cart.totalProductPrice ?? "0"),
+          currency
+        },
+        totalShipping: {
+          value: Number(cart.totalShippingCharge ?? "0"),
+          currency
+        },
+        totalTax: {
+          value: Number(cart.totalSalesTax ?? "0"),
+          currency
+        },
+        totalDiscount: {
+          value: Math.abs(Number(cart.totalAdjustment ?? "0")),
+          currency
+        },
+        totalSurcharge: { value: 0, currency }
+      },
+      appliedPromotions: (cart.adjustment ?? []).filter((adj) => adj.usage === "Discount").map((adj) => ({
+        code: adj.code,
+        isCouponCode: (cart.promotionCode ?? []).some(
+          (pc) => pc.code === adj.code
+        ),
+        name: adj.description ?? adj.code,
+        description: adj.description ?? "",
+        amount: {
+          value: Math.abs(Number(adj.amount)),
+          currency: adj.currency
+        }
+      }))
+    });
+  }
+  parseCartIdentifier(_context, data) {
+    const cart = data;
+    return this.cartIdentifierSchema.parse({
+      key: cart.orderId
+    });
+  }
+  parseCartPaginatedSearchResult(context, data, _query) {
+    const pageSize = _query.search.paginationOptions.pageSize;
+    const pageNumber = _query.search.paginationOptions.pageNumber;
+    const orderList = data;
+    if (Array.isArray(orderList.Order)) {
+      const orders = orderList.Order;
+      const total = Number(orderList.recordSetTotal ?? orders.length);
+      const items = orders.map((order) => {
+        const parsed = this.parseCart(context, order);
+        return {
+          ...parsed,
+          numItems: (order.orderItem ?? []).length,
+          lastModifiedDate: order.lastUpdateDate ?? ""
+        };
+      });
+      return this.cartPaginatedSearchResultSchema.parse({
+        identifier: _query.search,
+        items,
+        totalCount: total,
+        totalPages: Math.ceil(total / Math.max(1, pageSize)),
+        pageSize,
+        pageNumber
+      });
+    }
+    const cart = data;
+    if (!cart.orderId) {
+      return this.cartPaginatedSearchResultSchema.parse({
+        identifier: _query.search,
+        items: [],
+        totalCount: 0,
+        totalPages: 0,
+        pageSize,
+        pageNumber
+      });
+    }
+    const parsedCart = this.parseCart(context, cart);
+    return this.cartPaginatedSearchResultSchema.parse({
+      identifier: _query.search,
+      items: [
+        {
+          ...parsedCart,
+          numItems: (cart.orderItem ?? []).length,
+          lastModifiedDate: cart.lastUpdateDate ?? ""
+        }
+      ],
+      totalCount: 1,
+      totalPages: 1,
+      pageSize,
+      pageNumber
+    });
+  }
+}
+export {
+  HclCartFactory
+};

package/factories/checkout/checkout.factory.js

@@ -0,0 +1,131 @@
+import {
+  ShippingMethodSchema,
+  PaymentMethodSchema
+} from "@reactionary/core";
+class HclCheckoutFactory {
+  constructor(checkoutSchema, shippingMethodSchema = ShippingMethodSchema, paymentMethodSchema = PaymentMethodSchema) {
+    this.checkoutSchema = checkoutSchema;
+    this.shippingMethodSchema = shippingMethodSchema;
+    this.paymentMethodSchema = paymentMethodSchema;
+  }
+  parseCheckout(context, data) {
+    const cart = data;
+    const currency = cart.totalProductPriceCurrency ?? cart.grandTotalCurrency ?? "USD";
+    const shipModeId = cart.shipModeId ?? (cart.orderItem ?? [])[0]?.shipModeId;
+    const shippingInstruction = shipModeId ? {
+      shippingMethod: { key: shipModeId },
+      pickupPoint: "",
+      instructions: "",
+      consentForUnattendedDelivery: false
+    } : void 0;
+    const billingEmail = cart.x_billingAddress?.email1 ?? (cart.paymentInstruction ?? []).flatMap((pi) => pi.protocolData ?? []).find((pd) => pd.name === "email1")?.value ?? context.session["hcl.notificationEmail"] ?? "noreply@checkout.example.com";
+    const paymentInstructions = (cart.paymentInstruction ?? []).map((pi) => ({
+      identifier: { key: pi.piId },
+      paymentMethod: {
+        method: pi.payMethodId,
+        name: pi.payMethodId,
+        paymentProcessor: pi.payMethodId
+      },
+      amount: {
+        value: Number(pi.piAmount ?? "0"),
+        currency: pi.currency ?? currency
+      },
+      protocolData: (pi.protocolData ?? []).map((pd) => ({
+        key: pd.name,
+        value: pd.value
+      })),
+      status: "pending"
+    }));
+    const parseAddress = (addr) => {
+      if (!addr)
+        return void 0;
+      return {
+        identifier: { key: addr.addressId ?? "" },
+        firstName: addr.firstName ?? "",
+        lastName: addr.lastName ?? "",
+        streetAddress: (addr.addressLine ?? [])[0] ?? "",
+        streetNumber: "",
+        city: addr.city ?? "",
+        region: addr.state ?? "",
+        postalCode: addr.zipCode ?? "",
+        countryCode: addr.country ?? ""
+      };
+    };
+    return this.checkoutSchema.parse({
+      identifier: { key: cart.orderId },
+      originalCartReference: { key: cart.orderId },
+      resultingOrder: cart.resultingOrderKey ? { key: cart.resultingOrderKey } : void 0,
+      items: (cart.orderItem ?? []).map((item) => ({
+        identifier: { key: item.orderItemId },
+        variant: { sku: item.partNumber },
+        quantity: Number(item.quantity),
+        price: {
+          unitPrice: {
+            value: Number(item.unitPrice),
+            currency: item.currency
+          },
+          totalPrice: {
+            value: Number(item.orderItemPrice),
+            currency: item.currency
+          },
+          unitDiscount: { value: 0, currency: item.currency },
+          totalDiscount: { value: 0, currency: item.currency }
+        }
+      })),
+      price: {
+        grandTotal: { value: Number(cart.grandTotal ?? "0"), currency },
+        totalProductPrice: {
+          value: Number(cart.totalProductPrice ?? "0"),
+          currency
+        },
+        totalShipping: {
+          value: Number(cart.totalShippingCharge ?? "0"),
+          currency
+        },
+        totalTax: { value: Number(cart.totalSalesTax ?? "0"), currency },
+        totalDiscount: {
+          value: Math.abs(Number(cart.totalAdjustment ?? "0")),
+          currency
+        },
+        totalSurcharge: { value: 0, currency }
+      },
+      name: context.session["hcl.cartName"] ?? "",
+      description: "",
+      shippingAddress: parseAddress(cart.x_shippingAddress),
+      billingAddress: parseAddress(cart.x_billingAddress),
+      shippingInstruction,
+      paymentInstructions,
+      pointOfContact: {
+        email: billingEmail,
+        phone: cart.x_billingAddress?.phone1
+      },
+      readyForFinalization: paymentInstructions.length > 0 && !!cart.shipModeId
+    });
+  }
+  parseShippingMethod(_context, data) {
+    const mode = data;
+    return this.shippingMethodSchema.parse({
+      identifier: { key: mode.shipModeId },
+      name: mode.shipModeDescription || mode.shipModeCode,
+      description: mode.shipModeDescription || mode.shipModeCode,
+      price: { value: 0, currency: "USD" },
+      deliveryTime: mode.field2 ?? "",
+      carrier: mode.carrier
+    });
+  }
+  parsePaymentMethod(_context, data) {
+    const method = data;
+    return this.paymentMethodSchema.parse({
+      identifier: {
+        method: method.paymentMethodName,
+        name: method.description ?? method.paymentMethodName,
+        paymentProcessor: method.paymentMethodName
+      },
+      description: method.description ?? method.paymentMethodName,
+      isPunchOut: false
+    });
+  }
+}
+export {
+  HclCheckoutFactory
+};

package/factories/identity/identity.factory.js

@@ -0,0 +1,12 @@
+class HclIdentityFactory {
+  identitySchema;
+  constructor(identitySchema) {
+    this.identitySchema = identitySchema;
+  }
+  parseIdentity(_context, data) {
+    return this.identitySchema.parse(data);
+  }
+}
+export {
+  HclIdentityFactory
+};

package/factories/index.js

@@ -1,3 +1,8 @@
+export * from "./cart/cart.factory.js";
+export * from "./checkout/checkout.factory.js";
 export * from "./product/product.factory.js";
 export * from "./category/category.factory.js";
 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";

package/factories/inventory/inventory.factory.js

@@ -0,0 +1,38 @@
+const HCL_STATUS_AVAILABLE = "Available";
+class HclInventoryFactory {
+  inventorySchema;
+  constructor(inventorySchema) {
+    this.inventorySchema = inventorySchema;
+  }
+  /**
+   * Map an HclInventoryAvailabilityItem to an Inventory model.
+   * The `data.sku` is used for the identifier since WCS items carry only an
+   * internal `productId`, not the human-readable part number.
+   */
+  parseInventory(_context, data) {
+    const { item, sku, fulfilmentCenterKey } = data;
+    const identifier = {
+      variant: { sku },
+      fulfillmentCenter: { key: fulfilmentCenterKey || "online" }
+    };
+    return this.inventorySchema.parse({
+      identifier,
+      quantity: Number(item.availableQuantity ?? "0"),
+      status: item.inventoryStatus === HCL_STATUS_AVAILABLE ? "inStock" : "outOfStock"
+    });
+  }
+  /** Create an empty (out-of-stock) inventory when no matching record was found. */
+  createEmpty(sku, fulfilmentCenterKey) {
+    return this.inventorySchema.parse({
+      identifier: {
+        variant: { sku },
+        fulfillmentCenter: { key: fulfilmentCenterKey || "online" }
+      },
+      quantity: 0,
+      status: "outOfStock"
+    });
+  }
+}
+export {
+  HclInventoryFactory
+};

package/factories/price/price.factory.js

@@ -0,0 +1,39 @@
+class HclPriceFactory {
+  priceSchema;
+  constructor(priceSchema) {
+    this.priceSchema = priceSchema;
+  }
+  /**
+   * Map a price response item to a Price model.
+   * Supports both /price (EntitledPrice with capital `UnitPrice`) and
+   * /display_price (resultList with lowercase `unitPrice`) response shapes.
+   * The `item.partNumber` is used as the variant SKU identifier.
+   */
+  parsePrice(_context, data) {
+    const { item } = data;
+    const entitledItem = item;
+    const displayItem = item;
+    const priceEntry = entitledItem.UnitPrice?.[0]?.price ?? displayItem.unitPrice?.[0]?.price;
+    return this.priceSchema.parse({
+      identifier: { variant: { sku: item.partNumber ?? "" } },
+      unitPrice: {
+        value: priceEntry?.value ?? -1,
+        currency: priceEntry?.currency ?? ""
+      },
+      onSale: false,
+      tieredPrices: []
+    });
+  }
+  /** Create an empty (placeholder) price when no result was found for a SKU. */
+  createEmpty(sku, currency) {
+    return this.priceSchema.parse({
+      identifier: { variant: { sku } },
+      unitPrice: { value: -1, currency },
+      onSale: false,
+      tieredPrices: []
+    });
+  }
+}
+export {
+  HclPriceFactory
+};

package/index.js

@@ -6,6 +6,11 @@ export * from "./core/client.js";
 export * from "./core/initialize.js";
 export * from "./core/initialize.types.js";
 export * from "./factories/index.js";
+export * from "./capabilities/cart.capability.js";
+export * from "./capabilities/checkout.capability.js";
 export * from "./capabilities/product.capability.js";
 export * from "./capabilities/category.capability.js";
 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";

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@reactionary/hcl",
-  "version": "0.9.7",
+  "version": "0.9.11",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",
   "dependencies": {
-    "@reactionary/core": "0.9.7",
-    "zod": "4.1.9",
-    "vitest": "^4.0.9",
-    "@nx/vite": "22.4.5"
+    "@reactionary/core": "0.9.11",
+    "debug": "^4.4.3",
+    "zod": "4.1.9"
+  },
+  "devDependencies": {
+    "@nx/vite": "22.4.5",
+    "vitest": "^4.0.9"
   },
   "sideEffects": false
 }

package/schema/capabilities.schema.js

@@ -12,6 +12,7 @@ const HclCapabilitiesSchema = CapabilitiesSchema.pick({
   product: true,
   price: true,
   inventory: true,
+  identity: true,
   productSearch: true
 }).extend({
   cart: OverridableCapabilitySchema.optional(),
@@ -20,6 +21,7 @@ const HclCapabilitiesSchema = CapabilitiesSchema.pick({
   product: OverridableCapabilitySchema.optional(),
   price: OverridableCapabilitySchema.optional(),
   inventory: OverridableCapabilitySchema.optional(),
+  identity: OverridableCapabilitySchema.optional(),
   productSearch: OverridableCapabilitySchema.optional()
 }).partial();
 export {

package/schema/configuration.schema.js

@@ -16,6 +16,9 @@ const HclConfigurationSchema = z.looseObject({
   apiUrl: z.string().meta({
     description: "The base origin URL for the HCL Commerce server (e.g. https://example.com)."
   }),
+  searchApiUrl: z.string().optional().meta({
+    description: "The base origin URL for the HCL Commerce Search API server, if different from apiUrl."
+  }),
   storeId: z.string().meta({ description: "The HCL Commerce store identifier." }),
   catalogId: z.string().optional().meta({ description: "The HCL Commerce catalog identifier." }),
   /**
@@ -26,7 +29,15 @@ const HclConfigurationSchema = z.looseObject({
   localeMap: z.record(z.string(), z.string()).default({ "en-US": "-1" }).meta({
     description: "Mapping from BCP 47 locale (RequestContext.languageContext.locale) to HCL langId."
   }),
-  profiles: HclProfilesSchema
+  profiles: HclProfilesSchema,
+  /**
+   * Optional price rule ID passed to /display_price?q=byPartNumbersAndPriceRuleId.
+   * When omitted the server applies its default configured price rule.
+   * In Karkkainen this is '10003'.
+   */
+  priceRuleId: z.string().optional().meta({
+    description: "Price rule ID for /display_price WCS calls. Optional \u2014 the server uses its default rule when absent."
+  })
 });
 export {
   HclConfigurationSchema