@reactionary/hcl 0.9.2

package/README.md

@@ -0,0 +1,11 @@
+# hcl
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build hcl` to build the library.
+
+## Running unit tests
+
+Run `nx test hcl` to execute the unit tests via [Vitest](https://vitest.dev/).

package/capabilities/category.capability.js

@@ -0,0 +1,170 @@
+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 {
+  CategoryCapability,
+  CategoryPaginatedResultSchema,
+  CategoryQueryByIdSchema,
+  CategoryQueryBySlugSchema,
+  CategoryQueryForBreadcrumbSchema,
+  CategoryQueryForChildCategoriesSchema,
+  CategoryQueryForTopCategoriesSchema,
+  CategorySchema,
+  Reactionary,
+  error,
+  success
+} from "@reactionary/core";
+import * as z from "zod";
+import { getLocaleParams } from "../core/locale-params.js";
+class HclCategoryCapability extends CategoryCapability {
+  constructor(cache, context, config, client, factory) {
+    super(cache, context);
+    this.config = config;
+    this.client = client;
+    this.factory = factory;
+  }
+  async getById(payload) {
+    const { langId } = getLocaleParams(this.config, this.context);
+    const response = await this.client.findCategories({
+      identifier: [payload.id.key],
+      langId
+    });
+    const data = response.contents?.[0];
+    if (!data) {
+      return error({ type: "NotFound", identifier: payload.id });
+    }
+    return success(this.factory.parseCategory(this.context, data));
+  }
+  async getBySlug(payload) {
+    const { langId } = getLocaleParams(this.config, this.context);
+    const token = await this.client.resolveSlug(payload.slug, langId);
+    if (!token || token.tokenName !== "CategoryToken" || !token.tokenExternalValue) {
+      return error({
+        type: "NotFound",
+        identifier: payload.slug
+      });
+    }
+    const response = await this.client.findCategories({
+      // tokenExternalValue is the external identifier (e.g. "LivingRoom").
+      // Use identifier= param so the key returned by the factory is consistent.
+      identifier: [token.tokenExternalValue],
+      langId
+    });
+    const data = response.contents?.[0];
+    if (!data) {
+      return error({
+        type: "NotFound",
+        identifier: payload.slug
+      });
+    }
+    return success(this.factory.parseCategory(this.context, data));
+  }
+  async getBreadcrumbPathToCategory(payload) {
+    const { langId } = getLocaleParams(this.config, this.context);
+    const leafResponse = await this.client.findCategories({
+      identifier: [payload.id.key],
+      langId
+    });
+    const leafData = leafResponse.contents?.[0];
+    if (!leafData) {
+      return success([]);
+    }
+    const parentId = leafData.parentCatalogGroupID;
+    const pathSegments = (typeof parentId === "string" ? parentId : parentId?.[0] ?? "").split("/").filter(Boolean);
+    const ancestorIds = pathSegments.slice(0, -1);
+    const ancestorsResp = ancestorIds.length > 0 ? await this.client.findCategories({ id: ancestorIds, langId }) : { contents: [] };
+    const byUniqueId = new Map(
+      (ancestorsResp.contents ?? []).map((c) => [c.uniqueID, c])
+    );
+    const path = [];
+    for (const id of ancestorIds) {
+      const data = byUniqueId.get(id);
+      if (data) {
+        path.push(this.factory.parseCategory(this.context, data));
+      }
+    }
+    path.push(this.factory.parseCategory(this.context, leafData));
+    return success(path);
+  }
+  async findChildCategories(payload) {
+    const { langId } = getLocaleParams(this.config, this.context);
+    const parentResp = await this.client.findCategories({
+      identifier: [payload.parentId.key],
+      langId
+    });
+    const parentUniqueId = parentResp.contents?.[0]?.uniqueID;
+    if (!parentUniqueId) {
+      return error({
+        type: "NotFound",
+        identifier: payload.parentId
+      });
+    }
+    const response = await this.client.findCategories({
+      parentCategoryId: parentUniqueId,
+      depthAndLimit: "1,0",
+      langId
+    });
+    const items = response.contents ?? [];
+    const paginated = this.factory.parseCategoryPaginatedResult(
+      this.context,
+      items,
+      payload
+    );
+    return success(paginated);
+  }
+  async findTopCategories(payload) {
+    const { langId } = getLocaleParams(this.config, this.context);
+    const response = await this.client.findCategories({
+      depthAndLimit: "1,0",
+      langId
+    });
+    const items = response.contents ?? [];
+    const paginated = this.factory.parseCategoryPaginatedResult(
+      this.context,
+      items,
+      payload
+    );
+    return success(paginated);
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: CategoryQueryByIdSchema,
+    outputSchema: CategorySchema
+  })
+], HclCategoryCapability.prototype, "getById", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: CategoryQueryBySlugSchema,
+    outputSchema: CategorySchema
+  })
+], HclCategoryCapability.prototype, "getBySlug", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: CategoryQueryForBreadcrumbSchema,
+    outputSchema: z.array(CategorySchema)
+  })
+], HclCategoryCapability.prototype, "getBreadcrumbPathToCategory", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: CategoryQueryForChildCategoriesSchema,
+    outputSchema: CategoryPaginatedResultSchema
+  })
+], HclCategoryCapability.prototype, "findChildCategories", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: CategoryQueryForTopCategoriesSchema,
+    outputSchema: CategoryPaginatedResultSchema
+  })
+], HclCategoryCapability.prototype, "findTopCategories", 1);
+export {
+  HclCategoryCapability
+};

package/capabilities/product-search.capability.js

@@ -0,0 +1,89 @@
+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 {
+  FacetValueIdentifierSchema,
+  ProductSearchCapability,
+  ProductSearchQueryByTermSchema,
+  ProductSearchQueryCreateNavigationFilterSchema,
+  ProductSearchResultSchema,
+  Reactionary,
+  success
+} from "@reactionary/core";
+import { getLocaleParams } from "../core/locale-params.js";
+class HclProductSearchCapability extends ProductSearchCapability {
+  constructor(cache, context, config, client, factory) {
+    super(cache, context);
+    this.config = config;
+    this.client = client;
+    this.factory = factory;
+  }
+  queryByTermPayload(payload) {
+    const { term, paginationOptions, categoryFilter, facets } = payload.search;
+    const { pageNumber, pageSize } = paginationOptions;
+    const { langId, currency } = getLocaleParams(this.config, this.context);
+    const categoryId = categoryFilter?.key || void 0;
+    return {
+      searchTerm: term || void 0,
+      categoryId,
+      limit: pageSize,
+      offset: (pageNumber - 1) * pageSize,
+      profileName: categoryId ? this.config.profiles.categoryBrowse : this.config.profiles.productSearch,
+      facets: facets.length > 0 ? facets.map((f) => f.key) : void 0,
+      langId,
+      currency
+    };
+  }
+  async queryByTerm(payload) {
+    const response = await this.client.findProducts(
+      this.queryByTermPayload(payload)
+    );
+    const value = this.factory.parseSearchResult(
+      this.context,
+      response,
+      payload
+    );
+    return success(value);
+  }
+  async createCategoryNavigationFilter(payload) {
+    const leaf = payload.categoryPath.at(-1);
+    const externalKey = leaf?.identifier.key ?? "";
+    let uniqueId = leaf?.uniqueId;
+    if (!uniqueId) {
+      const { langId } = getLocaleParams(this.config, this.context);
+      const catResp = await this.client.findCategories({
+        identifier: [externalKey],
+        langId
+      });
+      uniqueId = catResp.contents?.[0]?.uniqueID ?? externalKey;
+    }
+    const filter = {
+      facet: { key: "categories" },
+      key: uniqueId
+    };
+    return success(filter);
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductSearchQueryByTermSchema,
+    outputSchema: ProductSearchResultSchema
+  })
+], HclProductSearchCapability.prototype, "queryByTerm", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductSearchQueryCreateNavigationFilterSchema,
+    outputSchema: FacetValueIdentifierSchema
+  })
+], HclProductSearchCapability.prototype, "createCategoryNavigationFilter", 1);
+export {
+  HclProductSearchCapability
+};

package/capabilities/product.capability.js

@@ -0,0 +1,157 @@
+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 {
+  ProductCapability,
+  ProductQueryByIdSchema,
+  ProductQueryBySKUSchema,
+  ProductQueryBySlugSchema,
+  ProductSchema,
+  Reactionary,
+  error,
+  success
+} from "@reactionary/core";
+import { getLocaleParams } from "../core/locale-params.js";
+class HclProductCapability extends ProductCapability {
+  constructor(cache, context, config, client, factory) {
+    super(cache, context);
+    this.config = config;
+    this.client = client;
+    this.factory = factory;
+  }
+  async getById(payload) {
+    const { langId, currency } = getLocaleParams(this.config, this.context);
+    const response = await this.client.findProducts({
+      partNumber: [payload.identifier.key],
+      profileName: this.config.profiles.product,
+      langId,
+      currency
+    });
+    const products = response.contents ?? response.catalogEntryView ?? [];
+    const data = products[0];
+    if (!data) {
+      return error({
+        type: "NotFound",
+        identifier: payload.identifier
+      });
+    }
+    const value = this.factory.parseProduct(
+      this.context,
+      await this.withResolvedParentCategories(data, langId)
+    );
+    return success(value);
+  }
+  async getBySlug(payload) {
+    const { langId, currency } = getLocaleParams(this.config, this.context);
+    const token = await this.client.resolveSlug(payload.slug, langId);
+    if (!token || token.tokenName !== "ProductToken" || !token.tokenExternalValue) {
+      return error({
+        type: "NotFound",
+        identifier: payload.slug
+      });
+    }
+    const response = await this.client.findProducts({
+      partNumber: [token.tokenExternalValue],
+      profileName: this.config.profiles.product,
+      langId,
+      currency
+    });
+    const products = response.contents ?? response.catalogEntryView ?? [];
+    const data = products[0];
+    if (!data) {
+      return error({
+        type: "NotFound",
+        identifier: payload.slug
+      });
+    }
+    const value = this.factory.parseProduct(
+      this.context,
+      await this.withResolvedParentCategories(data, langId)
+    );
+    return success(value);
+  }
+  async getBySKU(payload) {
+    const { langId, currency } = getLocaleParams(this.config, this.context);
+    const response = await this.client.findProducts({
+      partNumber: [payload.variant.sku],
+      profileName: this.config.profiles.product,
+      langId,
+      currency
+    });
+    const products = response.contents ?? response.catalogEntryView ?? [];
+    const data = products[0];
+    if (!data) {
+      return error({
+        type: "NotFound",
+        identifier: payload.variant
+      });
+    }
+    const value = this.factory.parseProduct(
+      this.context,
+      await this.withResolvedParentCategories(data, langId)
+    );
+    return success(value);
+  }
+  /**
+   * Resolves `parentCatalogGroupID` path strings (e.g. "/10505/10507") to external
+   * category identifiers (e.g. "LivingRoomFurniture") so the factory receives
+   * human-readable keys rather than internal uniqueIDs.
+   */
+  async withResolvedParentCategories(data, langId) {
+    const rawIds = Array.isArray(data.parentCatalogGroupID) ? data.parentCatalogGroupID : data.parentCatalogGroupID ? [data.parentCatalogGroupID] : [];
+    const uniqueIds = [
+      ...new Set(
+        rawIds.map((p) => p.split("/").filter(Boolean).at(-1)).filter((id) => id !== void 0)
+      )
+    ];
+    if (uniqueIds.length === 0)
+      return data;
+    const catResp = await this.client.findCategories({ id: uniqueIds, langId });
+    const idToIdentifier = new Map(
+      (catResp.contents ?? []).map((c) => [c.uniqueID, c.identifier])
+    );
+    const resolvedIds = uniqueIds.map((id) => idToIdentifier.get(id) ?? id);
+    return { ...data, parentCatalogGroupID: resolvedIds };
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductQueryByIdSchema,
+    outputSchema: ProductSchema,
+    cache: true,
+    cacheTimeToLiveInSeconds: 300,
+    currencyDependentCaching: false,
+    localeDependentCaching: false
+  })
+], HclProductCapability.prototype, "getById", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductQueryBySlugSchema,
+    outputSchema: ProductSchema,
+    cache: true,
+    cacheTimeToLiveInSeconds: 300,
+    currencyDependentCaching: false,
+    localeDependentCaching: false
+  })
+], HclProductCapability.prototype, "getBySlug", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductQueryBySKUSchema,
+    outputSchema: ProductSchema,
+    cache: true,
+    cacheTimeToLiveInSeconds: 300,
+    currencyDependentCaching: false,
+    localeDependentCaching: false
+  })
+], HclProductCapability.prototype, "getBySKU", 1);
+export {
+  HclProductCapability
+};

package/core/client.js

@@ -0,0 +1,120 @@
+class HclClient {
+  constructor(config) {
+    this.config = config;
+    const origin = config.apiUrl.replace(/\/+$/, "");
+    const apiPath = "/search/resources/api/v2";
+    this.baseUrl = `${origin}${apiPath}`;
+  }
+  baseUrl;
+  async findProducts(query) {
+    const params = new URLSearchParams();
+    params.set("storeId", query.storeId ?? this.config.storeId);
+    const catalogId = query.catalogId ?? this.config.catalogId;
+    if (catalogId)
+      params.set("catalogId", catalogId);
+    if (query.langId)
+      params.set("langId", query.langId);
+    if (query.currency)
+      params.set("currency", query.currency);
+    if (query.categoryId)
+      params.set("categoryId", query.categoryId);
+    if (query.searchTerm)
+      params.set("searchTerm", query.searchTerm);
+    if (query.contractId)
+      params.set("contractId", query.contractId);
+    if (query.profileName)
+      params.set("profileName", query.profileName);
+    if (query.limit !== void 0)
+      params.set("limit", String(query.limit));
+    if (query.offset !== void 0)
+      params.set("offset", String(query.offset));
+    if (query.checkEntitlement !== void 0) {
+      params.set("checkEntitlement", String(query.checkEntitlement));
+    }
+    for (const id of query.id ?? []) {
+      params.append("id", id);
+    }
+    for (const partNumber of query.partNumber ?? []) {
+      params.append("partNumber", partNumber);
+    }
+    for (const facet of query.facets ?? []) {
+      params.append("facet", facet);
+    }
+    const url = `${this.baseUrl}/products?${params.toString()}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    });
+    if (!response.ok) {
+      throw new Error(
+        `HCL API error ${response.status} ${response.statusText} for URL: ${url}`
+      );
+    }
+    return response.json();
+  }
+  /**
+   * Resolve a URL slug to an HCL token (product partNumber, category ID, etc.).
+   * Calls GET /api/v2/urls?storeId=X&identifier=<slug>
+   * Returns undefined when the slug is not found (404).
+   */
+  async resolveSlug(slug, langId) {
+    const params = new URLSearchParams();
+    params.set("storeId", this.config.storeId);
+    params.append("identifier", slug);
+    if (langId)
+      params.set("langId", langId);
+    const url = `${this.baseUrl}/urls?${params.toString()}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    });
+    if (response.status === 404)
+      return void 0;
+    if (!response.ok) {
+      throw new Error(
+        `HCL URL resolve error ${response.status} ${response.statusText} for URL: ${url}`
+      );
+    }
+    const data = await response.json();
+    return data.contents?.[0];
+  }
+  /**
+   * Query categories from the HCL Commerce Query Service.
+   * Calls GET /api/v2/categories with the given query parameters.
+   */
+  async findCategories(query) {
+    const params = new URLSearchParams();
+    params.set("storeId", query.storeId ?? this.config.storeId);
+    const catalogId = query.catalogId ?? this.config.catalogId;
+    if (catalogId)
+      params.set("catalogId", catalogId);
+    if (query.langId)
+      params.set("langId", query.langId);
+    if (query.parentCategoryId)
+      params.set("parentCategoryId", query.parentCategoryId);
+    if (query.depthAndLimit)
+      params.set("depthAndLimit", query.depthAndLimit);
+    if (query.profileName)
+      params.set("profileName", query.profileName);
+    for (const id of query.id ?? []) {
+      params.append("id", id);
+    }
+    for (const identifier of query.identifier ?? []) {
+      params.append("identifier", identifier);
+    }
+    const url = `${this.baseUrl}/categories?${params.toString()}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    });
+    if (!response.ok) {
+      throw new Error(
+        `HCL API error ${response.status} ${response.statusText} for URL: ${url}`
+      );
+    }
+    return response.json();
+  }
+}
+export {
+  HclClient
+};

package/core/initialize.js

@@ -0,0 +1,97 @@
+import {
+  CategoryPaginatedResultSchema,
+  ProductSchema
+} from "@reactionary/core";
+import { HclCategorySchema } from "../schema/category.schema.js";
+import {
+  HclCapabilitiesSchema
+} from "../schema/capabilities.schema.js";
+import {
+  HclConfigurationSchema
+} from "../schema/configuration.schema.js";
+import {
+  resolveCapabilityWithFactory
+} from "./initialize.types.js";
+import { HclClient } from "./client.js";
+import {
+  HclCategoryFactory,
+  HclProductFactory,
+  HclProductSearchFactory
+} from "../factories/index.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";
+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 buildCapabilityArgs = (factory) => ({
+      cache,
+      context,
+      config,
+      hclClient,
+      factory
+    });
+    if (caps.product?.enabled) {
+      client.product = resolveCapabilityWithFactory(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        capabilities.product,
+        {
+          factory: new HclProductFactory(ProductSchema),
+          capability: (args) => new HclProductCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
+    if (caps.category?.enabled) {
+      client.category = resolveCapabilityWithFactory(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        capabilities.category,
+        {
+          factory: new HclCategoryFactory(
+            HclCategorySchema,
+            CategoryPaginatedResultSchema
+          ),
+          capability: (args) => new HclCategoryCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
+    if (caps.productSearch?.enabled) {
+      client.productSearch = resolveCapabilityWithFactory(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        capabilities.productSearch,
+        {
+          factory: new HclProductSearchFactory(ProductSearchResultSchema),
+          capability: (args) => new HclProductSearchCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.hclClient,
+            args.factory
+          )
+        },
+        buildCapabilityArgs
+      );
+    }
+    return client;
+  };
+}
+export {
+  withHclCapabilities
+};

package/core/initialize.types.js

@@ -0,0 +1,8 @@
+function resolveCapabilityWithFactory(capability, defaults, buildCapabilityArgs) {
+  const factory = capability?.factory ?? defaults.factory;
+  const capabilityFactory = capability?.capability ?? defaults.capability;
+  return capabilityFactory(buildCapabilityArgs(factory));
+}
+export {
+  resolveCapabilityWithFactory
+};

package/core/locale-params.js

@@ -0,0 +1,9 @@
+function getLocaleParams(config, context) {
+  return {
+    langId: config.localeMap[context.languageContext.locale],
+    currency: context.languageContext.currencyCode
+  };
+}
+export {
+  getLocaleParams
+};