@reactionary/algolia 0.6.3

package/README.md

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

package/capabilities/analytics.capability.js

@@ -0,0 +1,77 @@
+import {
+  AnalyticsCapability
+} from "@reactionary/core";
+import {
+  algoliasearch
+} from "algoliasearch";
+class AlgoliaAnalyticsCapability extends AnalyticsCapability {
+  client;
+  config;
+  constructor(cache, requestContext, config) {
+    super(cache, requestContext);
+    this.config = config;
+    this.client = algoliasearch(this.config.appId, this.config.apiKey).initInsights({});
+  }
+  async processProductAddToCart(event) {
+    if (event.source && event.source.type === "search") {
+      const algoliaEvent = {
+        eventName: "addToCart",
+        eventType: "conversion",
+        eventSubtype: "addToCart",
+        index: this.config.indexName,
+        objectIDs: [event.product.key],
+        userToken: this.context.session.identityContext.personalizationKey,
+        queryID: event.source.identifier.key
+      };
+      await this.client.pushEvents({
+        events: [algoliaEvent]
+      });
+    }
+  }
+  async processProductSummaryClick(event) {
+    if (event.source && event.source.type === "search") {
+      const algoliaEvent = {
+        eventName: "click",
+        eventType: "click",
+        index: this.config.indexName,
+        objectIDs: [event.product.key],
+        userToken: this.context.session.identityContext.personalizationKey,
+        positions: [event.position],
+        queryID: event.source.identifier.key
+      };
+      await this.client.pushEvents({
+        events: [algoliaEvent]
+      });
+    }
+  }
+  async processProductSummaryView(event) {
+    if (event.source && event.source.type === "search") {
+      const algoliaEvent = {
+        eventName: "view",
+        eventType: "view",
+        index: this.config.indexName,
+        objectIDs: event.products.map((x) => x.key),
+        userToken: this.context.session.identityContext.personalizationKey
+      };
+      await this.client.pushEvents({
+        events: [algoliaEvent]
+      });
+    }
+  }
+  async processPurchase(event) {
+    const algoliaEvent = {
+      eventName: "purchase",
+      eventType: "conversion",
+      eventSubtype: "purchase",
+      index: this.config.indexName,
+      objectIDs: event.order.items.map((x) => x.variant.sku),
+      userToken: this.context.session.identityContext.personalizationKey
+    };
+    await this.client.pushEvents({
+      events: [algoliaEvent]
+    });
+  }
+}
+export {
+  AlgoliaAnalyticsCapability
+};

package/capabilities/index.js

@@ -0,0 +1,3 @@
+export * from "./analytics.capability.js";
+export * from "./product-search.capability.js";
+export * from "./product-recommendations.capability.js";

package/capabilities/product-recommendations.capability.js

@@ -0,0 +1,195 @@
+import {
+  ProductRecommendationsCapability,
+  ProductSearchResultItemVariantSchema,
+  ImageSchema
+} from "@reactionary/core";
+import {
+  liteClient
+} from "algoliasearch/lite";
+class AlgoliaProductRecommendationsCapability extends ProductRecommendationsCapability {
+  config;
+  client;
+  constructor(config, cache, context) {
+    super(cache, context);
+    this.config = config;
+    this.client = liteClient(this.config.appId, this.config.apiKey);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  getRecommendationThreshold(_algorithm) {
+    return 10;
+  }
+  getQueryParametersForRecommendations(algorithm) {
+    return {
+      userToken: this.context.session.identityContext?.personalizationKey || "anonymous",
+      analytics: true,
+      analyticsTags: ["reactionary", algorithm],
+      clickAnalytics: true
+    };
+  }
+  /**
+   * Get frequently bought together recommendations using Algolia Recommend
+   */
+  async getFrequentlyBoughtTogetherRecommendations(query) {
+    try {
+      const response = await this.client.getRecommendations({
+        requests: [
+          {
+            indexName: this.config.indexName,
+            model: "bought-together",
+            objectID: query.sourceProduct.key,
+            maxRecommendations: query.numberOfRecommendations,
+            threshold: this.getRecommendationThreshold("bought-together"),
+            queryParameters: this.getQueryParametersForRecommendations("bought-together")
+          }
+        ]
+      });
+      const result = [];
+      if (response.results) {
+        for (const res of response.results) {
+          result.push(...this.parseRecommendation(res, query));
+        }
+      }
+      return result;
+    } catch (error) {
+      console.error("Error fetching frequently bought together recommendations:", error);
+      return [];
+    }
+  }
+  /**
+   * Get similar product recommendations using Algolia Recommend
+   */
+  async getSimilarProductsRecommendations(query) {
+    try {
+      const response = await this.client.getRecommendations({
+        requests: [
+          {
+            indexName: this.config.indexName,
+            model: "looking-similar",
+            objectID: query.sourceProduct.key,
+            maxRecommendations: query.numberOfRecommendations,
+            threshold: this.getRecommendationThreshold("looking-similar"),
+            queryParameters: this.getQueryParametersForRecommendations("looking-similar")
+          }
+        ]
+      });
+      const result = [];
+      if (response.results) {
+        for (const res of response.results) {
+          result.push(...this.parseRecommendation(res, query));
+        }
+      }
+      return result;
+    } catch (error) {
+      console.error("Error fetching similar product recommendations:", error);
+      return [];
+    }
+  }
+  /**
+   * Get related product recommendations using Algolia Recommend
+   */
+  async getRelatedProductsRecommendations(query) {
+    try {
+      const response = await this.client.getRecommendations({
+        requests: [
+          {
+            indexName: this.config.indexName,
+            model: "related-products",
+            objectID: query.sourceProduct.key,
+            maxRecommendations: query.numberOfRecommendations,
+            threshold: this.getRecommendationThreshold("related-products"),
+            queryParameters: this.getQueryParametersForRecommendations("related-products")
+          }
+        ]
+      });
+      const result = [];
+      if (response.results) {
+        for (const res of response.results) {
+          result.push(...this.parseRecommendation(res, query));
+        }
+      }
+      return result;
+    } catch (error) {
+      console.error("Error fetching related product recommendations:", error);
+      return [];
+    }
+  }
+  /**
+   * Get trending in category recommendations using Algolia Recommend
+   */
+  async getTrendingInCategoryRecommendations(query) {
+    try {
+      const response = await this.client.getRecommendations({
+        requests: [
+          {
+            indexName: this.config.indexName,
+            model: "trending-items",
+            facetName: "categories",
+            facetValue: query.sourceCategory.key,
+            maxRecommendations: query.numberOfRecommendations,
+            threshold: this.getRecommendationThreshold("trending-items"),
+            queryParameters: this.getQueryParametersForRecommendations("trending-items")
+          }
+        ]
+      });
+      const result = [];
+      if (response.results) {
+        for (const res of response.results) {
+          result.push(...this.parseRecommendation(res, query));
+        }
+      }
+      return result;
+    } catch (error) {
+      console.error("Error fetching trending in category recommendations:", error);
+      return [];
+    }
+  }
+  parseRecommendation(res, query) {
+    const result = [];
+    for (const hit of res.hits) {
+      const recommendationIdentifier = {
+        key: res.queryID || "x",
+        algorithm: query.algorithm,
+        abTestID: res.abTestID,
+        abTestVariantID: res.abTestVariantID
+      };
+      const recommendation = this.parseSingle(hit, recommendationIdentifier);
+      result.push(recommendation);
+    }
+    return result;
+  }
+  /**
+   * Maps Algolia recommendation results to ProductRecommendation format
+   */
+  parseSingle(hit, recommendationIdentifier) {
+    const product = this.parseSearchResultItem(hit);
+    return {
+      recommendationIdentifier,
+      recommendationReturnType: "productSearchResultItem",
+      product
+    };
+  }
+  parseSearchResultItem(body) {
+    const product = {
+      identifier: { key: body.objectID },
+      name: body.name || body.objectID,
+      slug: body.slug || body.objectID,
+      variants: [...body.variants || []].map((variant) => this.parseVariant(variant, body))
+    };
+    return product;
+  }
+  parseVariant(variant, product) {
+    const result = ProductSearchResultItemVariantSchema.parse({
+      variant: {
+        sku: variant.sku
+      },
+      image: ImageSchema.parse({
+        sourceUrl: variant.image,
+        altText: product.name || ""
+      })
+    });
+    return result;
+  }
+}
+export {
+  AlgoliaProductRecommendationsCapability
+};

package/capabilities/product-search.capability.js

@@ -0,0 +1,94 @@
+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 {
+  FacetIdentifierSchema,
+  FacetValueIdentifierSchema,
+  ProductSearchCapability,
+  ProductSearchQueryByTermSchema,
+  ProductSearchResultSchema,
+  Reactionary,
+  success
+} from "@reactionary/core";
+import { algoliasearch } from "algoliasearch";
+class AlgoliaProductSearchCapability extends ProductSearchCapability {
+  config;
+  factory;
+  constructor(cache, context, config, factory) {
+    super(cache, context);
+    this.config = config;
+    this.factory = factory;
+  }
+  queryByTermPayload(payload) {
+    const facetsThatAreNotCategory = payload.search.facets.filter(
+      (x) => x.facet.key !== "categories"
+    );
+    const categoryFacet = payload.search.facets.find((x) => x.facet.key === "categories") || payload.search.categoryFilter;
+    const finalFilters = [...payload.search.filters || []];
+    const finalFacetFilters = [
+      ...facetsThatAreNotCategory.map((x) => `${x.facet.key}:${x.key}`)
+    ];
+    if (categoryFacet) {
+      finalFilters.push(`categories:"${categoryFacet.key}"`);
+    }
+    return {
+      indexName: this.config.indexName,
+      query: payload.search.term,
+      page: payload.search.paginationOptions.pageNumber - 1,
+      hitsPerPage: payload.search.paginationOptions.pageSize,
+      facets: ["*"],
+      analytics: true,
+      clickAnalytics: true,
+      facetFilters: finalFacetFilters,
+      filters: finalFilters.join(" AND ")
+    };
+  }
+  async queryByTerm(payload) {
+    const client = algoliasearch(this.config.appId, this.config.apiKey);
+    const remote = await client.search({
+      requests: [this.queryByTermPayload(payload)]
+    });
+    const input = remote.results[0];
+    const result = this.factory.parseSearchResult(this.context, input, payload);
+    for (const selectedFacet of payload.search.facets) {
+      const facet = result.facets.find(
+        (f) => f.identifier.key === selectedFacet.facet.key
+      );
+      if (!facet) {
+        continue;
+      }
+      const value = facet.values.find((v) => v.identifier.key === selectedFacet.key);
+      if (value) {
+        value.active = true;
+      }
+    }
+    return success(result);
+  }
+  async createCategoryNavigationFilter(payload) {
+    const facetIdentifier = FacetIdentifierSchema.parse({
+      key: "categories"
+    });
+    const facetValueIdentifier = FacetValueIdentifierSchema.parse({
+      facet: facetIdentifier,
+      key: payload.categoryPath.map((c) => c.name).join(" > ")
+    });
+    return success(facetValueIdentifier);
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductSearchQueryByTermSchema,
+    outputSchema: ProductSearchResultSchema
+  })
+], AlgoliaProductSearchCapability.prototype, "queryByTerm", 1);
+export {
+  AlgoliaProductSearchCapability
+};

package/core/initialize.js

@@ -0,0 +1,67 @@
+import { AlgoliaProductSearchCapability } from "../capabilities/product-search.capability.js";
+import { AlgoliaAnalyticsCapability } from "../capabilities/analytics.capability.js";
+import { AlgoliaProductRecommendationsCapability } from "../capabilities/product-recommendations.capability.js";
+import { AlgoliaProductSearchFactory } from "../factories/product-search/product-search.factory.js";
+import { AlgoliaProductSearchResultSchema } from "../schema/search.schema.js";
+import {
+  resolveCapabilityWithFactory,
+  resolveDirectCapability
+} from "./initialize.types.js";
+function withAlgoliaCapabilities(configuration, capabilities) {
+  return (cache, context) => {
+    const client = {};
+    if (capabilities.productSearch?.enabled) {
+      const defaultFactory = new AlgoliaProductSearchFactory(
+        AlgoliaProductSearchResultSchema
+      );
+      client.productSearch = resolveCapabilityWithFactory(
+        capabilities.productSearch,
+        {
+          factory: defaultFactory,
+          capability: (args) => new AlgoliaProductSearchCapability(
+            args.cache,
+            args.context,
+            args.config,
+            args.factory
+          )
+        },
+        (factory) => ({
+          cache,
+          context,
+          config: configuration,
+          factory
+        })
+      );
+    }
+    if (capabilities.analytics?.enabled) {
+      client.analytics = resolveDirectCapability(
+        capabilities.analytics,
+        (args) => new AlgoliaAnalyticsCapability(args.cache, args.context, args.config),
+        {
+          cache,
+          context,
+          config: configuration
+        }
+      );
+    }
+    if (capabilities.productRecommendations?.enabled) {
+      client.productRecommendations = resolveDirectCapability(
+        capabilities.productRecommendations,
+        (args) => new AlgoliaProductRecommendationsCapability(
+          args.config,
+          args.cache,
+          args.context
+        ),
+        {
+          cache,
+          context,
+          config: configuration
+        }
+      );
+    }
+    return client;
+  };
+}
+export {
+  withAlgoliaCapabilities
+};

package/core/initialize.types.js

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

package/factories/index.js

@@ -0,0 +1 @@
+export * from "./product-search/product-search.factory.js";

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

@@ -0,0 +1,124 @@
+import {
+  FacetIdentifierSchema,
+  FacetValueIdentifierSchema,
+  ImageSchema,
+  ProductSearchResultFacetSchema,
+  ProductSearchResultFacetValueSchema,
+  ProductSearchResultItemVariantSchema
+} from "@reactionary/core";
+class AlgoliaProductSearchFactory {
+  productSearchResultSchema;
+  constructor(productSearchResultSchema) {
+    this.productSearchResultSchema = productSearchResultSchema;
+  }
+  parseSearchResult(_context, data, query) {
+    const body = this.parseInput(data);
+    const items = body.hits.map((hit) => this.parseSingle(hit));
+    let facets = [];
+    for (const id in body.facets) {
+      const values = body.facets[id];
+      const facetId = FacetIdentifierSchema.parse({ key: id });
+      facets.push(this.parseFacet(facetId, values));
+    }
+    const selectedCategoryFacet = query.search.facets.find((x) => x.facet.key === "categories") || query.search.categoryFilter;
+    let subCategoryFacet;
+    if (selectedCategoryFacet) {
+      const valueDepth = selectedCategoryFacet.key.split(" > ").length;
+      subCategoryFacet = facets.find(
+        (f) => f.identifier.key === `hierarchy.lvl${valueDepth}`
+      );
+    } else {
+      subCategoryFacet = facets.find((f) => f.identifier.key === "hierarchy.lvl0");
+    }
+    if (subCategoryFacet) {
+      subCategoryFacet.identifier = FacetIdentifierSchema.parse({ key: "categories" });
+      subCategoryFacet.name = "Categories";
+      for (const value of subCategoryFacet.values) {
+        const pathParts = value.identifier.key.split(" > ");
+        value.identifier.facet = subCategoryFacet.identifier;
+        value.name = pathParts[pathParts.length - 1];
+      }
+    }
+    facets = facets.filter((f) => !f.identifier.key.startsWith("hierarchy.lvl"));
+    const result = {
+      identifier: {
+        term: query.search.term,
+        facets: query.search.facets,
+        filters: query.search.filters,
+        paginationOptions: query.search.paginationOptions,
+        index: body.index || "",
+        key: body.queryID || ""
+      },
+      pageNumber: (body.page || 0) + 1,
+      pageSize: body.hitsPerPage || 0,
+      totalCount: body.nbHits || 0,
+      totalPages: body.nbPages || 0,
+      items,
+      facets
+    };
+    return this.productSearchResultSchema.parse(result);
+  }
+  parseSingle(body) {
+    return {
+      identifier: { key: body.objectID },
+      name: body.name || body.objectID,
+      slug: body.slug || body.objectID,
+      variants: [...body.variants || []].map(
+        (variant) => this.parseVariant(variant, body)
+      )
+    };
+  }
+  parseVariant(variant, product) {
+    return ProductSearchResultItemVariantSchema.parse({
+      variant: {
+        sku: variant.sku
+      },
+      image: ImageSchema.parse({
+        sourceUrl: variant.image,
+        altText: product.name || ""
+      })
+    });
+  }
+  parseFacet(facetIdentifier, facetValues) {
+    const result = ProductSearchResultFacetSchema.parse({
+      identifier: facetIdentifier,
+      name: facetIdentifier.key,
+      values: []
+    });
+    for (const valueId in facetValues) {
+      const count = facetValues[valueId];
+      const facetValueIdentifier = FacetValueIdentifierSchema.parse({
+        facet: facetIdentifier,
+        key: valueId
+      });
+      result.values.push(this.parseFacetValue(facetValueIdentifier, valueId, count));
+    }
+    return result;
+  }
+  parseFacetValue(facetValueIdentifier, label, count) {
+    return ProductSearchResultFacetValueSchema.parse({
+      identifier: facetValueIdentifier,
+      name: label,
+      count,
+      active: false
+    });
+  }
+  parseInput(data) {
+    if (!this.isSearchResponse(data)) {
+      throw new Error("Invalid Algolia search response");
+    }
+    return data;
+  }
+  isSearchResponse(data) {
+    if (!data || typeof data !== "object") {
+      return false;
+    }
+    if (!("hits" in data) || !Array.isArray(data.hits)) {
+      return false;
+    }
+    return true;
+  }
+}
+export {
+  AlgoliaProductSearchFactory
+};

package/index.js

@@ -0,0 +1,5 @@
+export * from "./core/initialize.js";
+export * from "./capabilities/index.js";
+export * from "./factories/index.js";
+export * from "./schema/configuration.schema.js";
+export * from "./schema/capabilities.schema.js";

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@reactionary/algolia",
+  "version": "0.6.3",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "@reactionary/core": "0.6.3",
+    "zod": "4.1.9",
+    "algoliasearch": "^5.48.0",
+    "vitest": "^4.0.9",
+    "@nx/vite": "22.4.5"
+  },
+  "sideEffects": false
+}

package/schema/capabilities.schema.js

@@ -0,0 +1,23 @@
+import { CapabilitiesSchema } from "@reactionary/core";
+import * as z from "zod";
+const ProductSearchCapabilitySchema = z.looseObject({
+  enabled: z.boolean(),
+  factory: z.unknown().optional(),
+  capability: z.unknown().optional()
+});
+const CapabilityOverrideSchema = z.looseObject({
+  enabled: z.boolean(),
+  capability: z.unknown().optional()
+});
+const AlgoliaCapabilitiesSchema = CapabilitiesSchema.pick({
+  productSearch: true,
+  analytics: true,
+  productRecommendations: true
+}).extend({
+  productSearch: ProductSearchCapabilitySchema.optional(),
+  analytics: CapabilityOverrideSchema.optional(),
+  productRecommendations: CapabilityOverrideSchema.optional()
+}).partial();
+export {
+  AlgoliaCapabilitiesSchema
+};

package/schema/configuration.schema.js

@@ -0,0 +1,9 @@
+import * as z from "zod";
+const AlgoliaConfigurationSchema = z.looseObject({
+  appId: z.string(),
+  apiKey: z.string(),
+  indexName: z.string()
+});
+export {
+  AlgoliaConfigurationSchema
+};

package/schema/index.js

@@ -0,0 +1,3 @@
+export * from "./capabilities.schema.js";
+export * from "./configuration.schema.js";
+export * from "./search.schema.js";

package/schema/product-recommendation.schema.js

@@ -0,0 +1,9 @@
+import { ProductRecommendationIdentifierSchema } from "@reactionary/core";
+import * as z from "zod";
+const AlgoliaProductSearchIdentifierSchema = ProductRecommendationIdentifierSchema.extend({
+  abTestID: z.number().optional(),
+  abTestVariantID: z.number().optional()
+});
+export {
+  AlgoliaProductSearchIdentifierSchema
+};

package/schema/search.schema.js

@@ -0,0 +1,13 @@
+import { ProductSearchIdentifierSchema, ProductSearchResultSchema } from "@reactionary/core";
+import * as z from "zod";
+const AlgoliaProductSearchIdentifierSchema = ProductSearchIdentifierSchema.extend({
+  key: z.string(),
+  index: z.string()
+});
+const AlgoliaProductSearchResultSchema = ProductSearchResultSchema.extend({
+  identifier: AlgoliaProductSearchIdentifierSchema.default(() => AlgoliaProductSearchIdentifierSchema.parse({}))
+});
+export {
+  AlgoliaProductSearchIdentifierSchema,
+  AlgoliaProductSearchResultSchema
+};

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

@@ -0,0 +1,12 @@
+import { AnalyticsCapability, type AnalyticsMutationProductAddToCartEvent, type AnalyticsMutationProductSummaryClickEvent, type AnalyticsMutationProductSummaryViewEvent, type AnalyticsMutationPurchaseEvent, type Cache, type RequestContext } from '@reactionary/core';
+import { type InsightsClient } from 'algoliasearch';
+import type { AlgoliaConfiguration } from '../schema/configuration.schema.js';
+export declare class AlgoliaAnalyticsCapability extends AnalyticsCapability {
+    protected client: InsightsClient;
+    protected config: AlgoliaConfiguration;
+    constructor(cache: Cache, requestContext: RequestContext, config: AlgoliaConfiguration);
+    protected processProductAddToCart(event: AnalyticsMutationProductAddToCartEvent): Promise<void>;
+    protected processProductSummaryClick(event: AnalyticsMutationProductSummaryClickEvent): Promise<void>;
+    protected processProductSummaryView(event: AnalyticsMutationProductSummaryViewEvent): Promise<void>;
+    protected processPurchase(event: AnalyticsMutationPurchaseEvent): Promise<void>;
+}

package/src/capabilities/index.d.ts

@@ -0,0 +1,3 @@
+export * from './analytics.capability.js';
+export * from './product-search.capability.js';
+export * from './product-recommendations.capability.js';

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

@@ -0,0 +1,103 @@
+import { type Cache, ProductRecommendationsCapability, type ProductRecommendation, type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery, type ProductRecommendationAlgorithmSimilarProductsQuery, type ProductRecommendationAlgorithmRelatedProductsQuery, type ProductRecommendationAlgorithmTrendingInCategoryQuery, type RequestContext, type ProductRecommendationsQuery, type ProductSearchResultItemVariant } from '@reactionary/core';
+import { type RecommendationsResults, type RecommendSearchParams, type LiteClient } from 'algoliasearch/lite';
+import type { AlgoliaConfiguration } from '../schema/configuration.schema.js';
+import type { AlgoliaProductRecommendationIdentifier } from '../schema/product-recommendation.schema.js';
+import type { AlgoliaNativeRecord, AlgoliaNativeVariant } from '../schema/search.schema.js';
+/**
+ * AlgoliaProductRecommendationsCapability
+ *
+ * Provides product recommendations using Algolia's Recommend API.
+ * Supports frequentlyBoughtTogether, similar, related, and trendingInCategory algorithms.
+ *
+ * Note: This requires Algolia Recommend to be enabled and AI models to be trained.
+ * See: https://www.algolia.com/doc/guides/algolia-recommend/overview/
+ */
+export declare class AlgoliaProductRecommendationsCapability extends ProductRecommendationsCapability {
+    protected config: AlgoliaConfiguration;
+    protected client: LiteClient;
+    constructor(config: AlgoliaConfiguration, cache: Cache, context: RequestContext);
+    protected getRecommendationThreshold(_algorithm: string): number;
+    protected getQueryParametersForRecommendations(algorithm: string): RecommendSearchParams;
+    /**
+     * Get frequently bought together recommendations using Algolia Recommend
+     */
+    protected getFrequentlyBoughtTogetherRecommendations(query: ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery): Promise<ProductRecommendation[]>;
+    /**
+     * Get similar product recommendations using Algolia Recommend
+     */
+    protected getSimilarProductsRecommendations(query: ProductRecommendationAlgorithmSimilarProductsQuery): Promise<ProductRecommendation[]>;
+    /**
+     * Get related product recommendations using Algolia Recommend
+     */
+    protected getRelatedProductsRecommendations(query: ProductRecommendationAlgorithmRelatedProductsQuery): Promise<ProductRecommendation[]>;
+    /**
+     * Get trending in category recommendations using Algolia Recommend
+     */
+    protected getTrendingInCategoryRecommendations(query: ProductRecommendationAlgorithmTrendingInCategoryQuery): Promise<ProductRecommendation[]>;
+    protected parseRecommendation(res: RecommendationsResults, query: ProductRecommendationsQuery): (({
+        recommendationIdentifier: {
+            key: string;
+            algorithm: string;
+        };
+        recommendationReturnType: "idOnly";
+        product: {
+            key: string;
+        };
+    } & {
+        _?: never;
+    }) | ({
+        recommendationIdentifier: {
+            key: string;
+            algorithm: string;
+        };
+        recommendationReturnType: "productSearchResultItem";
+        product: {
+            identifier: {
+                key: string;
+            };
+            name: string;
+            slug: string;
+            variants: {
+                variant: {
+                    sku: string;
+                };
+                image: {
+                    sourceUrl: string;
+                    altText: string;
+                    width?: number | undefined;
+                    height?: number | undefined;
+                };
+                options?: {
+                    identifier: {
+                        key: string;
+                    };
+                    name: string;
+                    value: {
+                        identifier: {
+                            option: {
+                                key: string;
+                            };
+                            key: string;
+                        };
+                        label: string;
+                    };
+                } | undefined;
+            }[];
+        };
+    } & {
+        _?: never;
+    }))[];
+    /**
+     * Maps Algolia recommendation results to ProductRecommendation format
+     */
+    protected parseSingle(hit: AlgoliaNativeRecord, recommendationIdentifier: AlgoliaProductRecommendationIdentifier): ProductRecommendation;
+    protected parseSearchResultItem(body: AlgoliaNativeRecord): {
+        identifier: {
+            key: string;
+        };
+        name: string;
+        slug: string;
+        variants: ProductSearchResultItemVariant[];
+    };
+    protected parseVariant(variant: AlgoliaNativeVariant, product: AlgoliaNativeRecord): ProductSearchResultItemVariant;
+}

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

@@ -0,0 +1,21 @@
+import { type Cache, type FacetValueIdentifier, ProductSearchCapability, type ProductSearchFactory, type ProductSearchFactoryOutput, type ProductSearchFactoryWithOutput, type ProductSearchQueryByTerm, type ProductSearchQueryCreateNavigationFilter, type RequestContext, type Result } from '@reactionary/core';
+import type { AlgoliaConfiguration } from '../schema/configuration.schema.js';
+import type { AlgoliaProductSearchFactory } from '../factories/product-search/product-search.factory.js';
+export declare class AlgoliaProductSearchCapability<TFactory extends ProductSearchFactory = AlgoliaProductSearchFactory> extends ProductSearchCapability<ProductSearchFactoryOutput<TFactory>> {
+    protected config: AlgoliaConfiguration;
+    protected factory: ProductSearchFactoryWithOutput<TFactory>;
+    constructor(cache: Cache, context: RequestContext, config: AlgoliaConfiguration, factory: ProductSearchFactoryWithOutput<TFactory>);
+    protected queryByTermPayload(payload: ProductSearchQueryByTerm): {
+        indexName: string;
+        query: string;
+        page: number;
+        hitsPerPage: number;
+        facets: string[];
+        analytics: boolean;
+        clickAnalytics: boolean;
+        facetFilters: string[];
+        filters: string;
+    };
+    queryByTerm(payload: ProductSearchQueryByTerm): Promise<Result<ProductSearchFactoryOutput<TFactory>>>;
+    createCategoryNavigationFilter(payload: ProductSearchQueryCreateNavigationFilter): Promise<Result<FacetValueIdentifier>>;
+}

package/src/core/initialize.d.ts

@@ -0,0 +1,5 @@
+import type { Cache, RequestContext } from '@reactionary/core';
+import type { AlgoliaCapabilities } from '../schema/capabilities.schema.js';
+import type { AlgoliaConfiguration } from '../schema/configuration.schema.js';
+import { type AlgoliaClientFromCapabilities } from './initialize.types.js';
+export declare function withAlgoliaCapabilities<T extends AlgoliaCapabilities>(configuration: AlgoliaConfiguration, capabilities: T): (cache: Cache, context: RequestContext) => AlgoliaClientFromCapabilities<T>;

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

@@ -0,0 +1,43 @@
+import type { ClientFromCapabilities, ProductSearchFactory } from '@reactionary/core';
+import type { AlgoliaCapabilities } from '../schema/capabilities.schema.js';
+import type { AlgoliaProductSearchFactory } from '../factories/product-search/product-search.factory.js';
+import type { AlgoliaAnalyticsCapability } from '../capabilities/analytics.capability.js';
+import type { AlgoliaProductRecommendationsCapability } from '../capabilities/product-recommendations.capability.js';
+import type { AlgoliaProductSearchCapability } from '../capabilities/product-search.capability.js';
+type EnabledCapability<TCapability> = TCapability extends {
+    enabled: true;
+} ? true : false;
+type NormalizeConfiguredCapabilities<T extends AlgoliaCapabilities> = Omit<T, 'productSearch' | 'analytics' | 'productRecommendations'> & {
+    productSearch?: EnabledCapability<T['productSearch']>;
+    analytics?: EnabledCapability<T['analytics']>;
+    productRecommendations?: EnabledCapability<T['productRecommendations']>;
+};
+type ExtractCapabilityFactory<TCapability, TContract, TDefaultFactory> = TCapability extends {
+    enabled: true;
+    factory?: infer TFactory;
+} ? TFactory extends TContract ? TFactory : TDefaultFactory : TDefaultFactory;
+type ExtractCapabilityImplementation<TCapability, TDefaultCapability> = TCapability extends {
+    enabled: true;
+    capability?: infer TCapabilityFactory;
+} ? TCapabilityFactory extends (...args: unknown[]) => infer TResolvedCapability ? TResolvedCapability : TDefaultCapability : TDefaultCapability;
+type CapabilityOverride<TCapability, TKey extends string, TResolvedCapability> = TCapability extends {
+    enabled: true;
+} ? {
+    [K in TKey]: TResolvedCapability;
+} : Record<never, never>;
+type ProductSearchFactoryFor<T extends AlgoliaCapabilities> = ExtractCapabilityFactory<T['productSearch'], ProductSearchFactory, AlgoliaProductSearchFactory>;
+type ProductSearchCapabilityFor<T extends AlgoliaCapabilities> = ExtractCapabilityImplementation<T['productSearch'], AlgoliaProductSearchCapability<ProductSearchFactoryFor<T>>>;
+type AnalyticsCapabilityFor<T extends AlgoliaCapabilities> = ExtractCapabilityImplementation<T['analytics'], AlgoliaAnalyticsCapability>;
+type ProductRecommendationsCapabilityFor<T extends AlgoliaCapabilities> = ExtractCapabilityImplementation<T['productRecommendations'], AlgoliaProductRecommendationsCapability>;
+export type AlgoliaClientFromCapabilities<T extends AlgoliaCapabilities> = Omit<ClientFromCapabilities<NormalizeConfiguredCapabilities<T>>, 'productSearch' | 'analytics' | 'productRecommendations'> & CapabilityOverride<T['productSearch'], 'productSearch', ProductSearchCapabilityFor<T>> & CapabilityOverride<T['analytics'], 'analytics', AnalyticsCapabilityFor<T>> & CapabilityOverride<T['productRecommendations'], 'productRecommendations', ProductRecommendationsCapabilityFor<T>>;
+export declare function resolveCapabilityWithFactory<TFactory, TResolvedCapability, TCapabilityArgs>(capability: {
+    factory?: TFactory;
+    capability?: (args: TCapabilityArgs) => TResolvedCapability;
+} | undefined, defaults: {
+    factory: TFactory;
+    capability: (args: TCapabilityArgs) => TResolvedCapability;
+}, buildCapabilityArgs: (factory: TFactory) => TCapabilityArgs): TResolvedCapability;
+export declare function resolveDirectCapability<TResolvedCapability, TCapabilityArgs>(capability: {
+    capability?: (args: TCapabilityArgs) => TResolvedCapability;
+} | undefined, defaultCapability: (args: TCapabilityArgs) => TResolvedCapability, args: TCapabilityArgs): TResolvedCapability;
+export {};

package/src/factories/index.d.ts

@@ -0,0 +1 @@
+export * from './product-search/product-search.factory.js';

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

@@ -0,0 +1,16 @@
+import type { AnyProductSearchResultSchema, FacetIdentifier, FacetValueIdentifier, ProductSearchFactory, ProductSearchQueryByTerm, ProductSearchResultFacet, ProductSearchResultFacetValue, ProductSearchResultItem, ProductSearchResultItemVariant, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+import type { SearchResponse } from 'algoliasearch';
+import type { AlgoliaNativeRecord, AlgoliaNativeVariant } from '../../schema/search.schema.js';
+import type { AlgoliaProductSearchResultSchema } from '../../schema/search.schema.js';
+export declare class AlgoliaProductSearchFactory<TProductSearchResultSchema extends AnyProductSearchResultSchema = typeof AlgoliaProductSearchResultSchema> implements ProductSearchFactory<TProductSearchResultSchema> {
+    readonly productSearchResultSchema: TProductSearchResultSchema;
+    constructor(productSearchResultSchema: TProductSearchResultSchema);
+    parseSearchResult(_context: RequestContext, data: unknown, query: ProductSearchQueryByTerm): z.output<TProductSearchResultSchema>;
+    protected parseSingle(body: AlgoliaNativeRecord): ProductSearchResultItem;
+    protected parseVariant(variant: AlgoliaNativeVariant, product: AlgoliaNativeRecord): ProductSearchResultItemVariant;
+    protected parseFacet(facetIdentifier: FacetIdentifier, facetValues: Record<string, number>): ProductSearchResultFacet;
+    protected parseFacetValue(facetValueIdentifier: FacetValueIdentifier, label: string, count: number): ProductSearchResultFacetValue;
+    protected parseInput(data: unknown): SearchResponse<AlgoliaNativeRecord>;
+    protected isSearchResponse(data: unknown): data is SearchResponse<AlgoliaNativeRecord>;
+}

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './core/initialize.js';
+export * from './capabilities/index.js';
+export * from './factories/index.js';
+export * from './schema/configuration.schema.js';
+export * from './schema/capabilities.schema.js';

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

@@ -0,0 +1,44 @@
+import type { AnalyticsCapability, Cache, ProductRecommendationsCapability, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability, RequestContext } from '@reactionary/core';
+import type { AlgoliaConfiguration } from './configuration.schema.js';
+import * as z from 'zod';
+export declare const AlgoliaCapabilitiesSchema: z.ZodObject<{
+    productSearch: 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;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    productRecommendations: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export interface AlgoliaCapabilityFactoryArgs {
+    cache: Cache;
+    context: RequestContext;
+    config: AlgoliaConfiguration;
+}
+export interface AlgoliaProductSearchCapabilityFactoryArgs<TFactory extends ProductSearchFactory = ProductSearchFactory> extends AlgoliaCapabilityFactoryArgs {
+    factory: ProductSearchFactoryWithOutput<TFactory>;
+}
+export interface AlgoliaProductSearchCapabilityConfig<TFactory extends ProductSearchFactory = ProductSearchFactory, TCapability extends ProductSearchCapability = ProductSearchCapability> {
+    enabled: boolean;
+    factory?: ProductSearchFactoryWithOutput<TFactory>;
+    capability?: (args: AlgoliaProductSearchCapabilityFactoryArgs<TFactory>) => TCapability;
+}
+export interface AlgoliaAnalyticsCapabilityConfig<TCapability extends AnalyticsCapability = AnalyticsCapability> {
+    enabled: boolean;
+    capability?: (args: AlgoliaCapabilityFactoryArgs) => TCapability;
+}
+export interface AlgoliaProductRecommendationsCapabilityConfig<TCapability extends ProductRecommendationsCapability = ProductRecommendationsCapability> {
+    enabled: boolean;
+    capability?: (args: AlgoliaCapabilityFactoryArgs) => TCapability;
+}
+export type AlgoliaCapabilities<TProductSearchFactory extends ProductSearchFactory = ProductSearchFactory, TProductSearchCapability extends ProductSearchCapability = ProductSearchCapability, TAnalyticsCapability extends AnalyticsCapability = AnalyticsCapability, TProductRecommendationsCapability extends ProductRecommendationsCapability = ProductRecommendationsCapability> = {
+    productSearch?: AlgoliaProductSearchCapabilityConfig<TProductSearchFactory, TProductSearchCapability>;
+    analytics?: AlgoliaAnalyticsCapabilityConfig<TAnalyticsCapability>;
+    productRecommendations?: AlgoliaProductRecommendationsCapabilityConfig<TProductRecommendationsCapability>;
+};

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

@@ -0,0 +1,7 @@
+import * as z from 'zod';
+export declare const AlgoliaConfigurationSchema: z.ZodObject<{
+    appId: z.ZodString;
+    apiKey: z.ZodString;
+    indexName: z.ZodString;
+}, z.core.$loose>;
+export type AlgoliaConfiguration = z.infer<typeof AlgoliaConfigurationSchema>;

package/src/schema/index.d.ts

@@ -0,0 +1,3 @@
+export * from './capabilities.schema.js';
+export * from './configuration.schema.js';
+export * from './search.schema.js';

package/src/schema/product-recommendation.schema.d.ts

@@ -0,0 +1,8 @@
+import * as z from "zod";
+export declare const AlgoliaProductSearchIdentifierSchema: z.ZodObject<{
+    key: z.ZodString;
+    algorithm: z.ZodString;
+    abTestID: z.ZodOptional<z.ZodNumber>;
+    abTestVariantID: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type AlgoliaProductRecommendationIdentifier = z.infer<typeof AlgoliaProductSearchIdentifierSchema>;

package/src/schema/search.schema.d.ts

@@ -0,0 +1,113 @@
+import * as z from 'zod';
+export declare const AlgoliaProductSearchIdentifierSchema: z.ZodObject<{
+    term: z.ZodString;
+    facets: z.ZodArray<z.ZodObject<{
+        facet: z.ZodObject<{
+            key: z.ZodString;
+        }, z.core.$loose>;
+        key: z.ZodString;
+    }, z.core.$strip>>;
+    filters: z.ZodArray<z.ZodString>;
+    paginationOptions: z.ZodObject<{
+        pageNumber: z.ZodDefault<z.ZodNumber>;
+        pageSize: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>;
+    categoryFilter: z.ZodOptional<z.ZodObject<{
+        facet: z.ZodObject<{
+            key: z.ZodString;
+        }, z.core.$loose>;
+        key: z.ZodString;
+    }, z.core.$strip>>;
+    key: z.ZodString;
+    index: z.ZodString;
+}, z.core.$loose>;
+export declare const AlgoliaProductSearchResultSchema: z.ZodObject<{
+    pageNumber: z.ZodNumber;
+    pageSize: z.ZodNumber;
+    totalCount: z.ZodNumber;
+    totalPages: z.ZodNumber;
+    items: z.ZodArray<z.ZodObject<{
+        identifier: z.ZodObject<{
+            key: z.ZodString;
+        }, z.core.$loose>;
+        name: z.ZodString;
+        slug: z.ZodString;
+        variants: z.ZodArray<z.ZodObject<{
+            variant: z.ZodObject<{
+                sku: z.ZodString;
+            }, z.core.$loose>;
+            image: z.ZodObject<{
+                sourceUrl: z.ZodDefault<z.ZodString>;
+                altText: z.ZodDefault<z.ZodString>;
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>;
+            options: z.ZodOptional<z.ZodObject<{
+                identifier: z.ZodObject<{
+                    key: z.ZodString;
+                }, z.core.$loose>;
+                name: z.ZodString;
+                value: z.ZodObject<{
+                    identifier: z.ZodObject<{
+                        option: z.ZodObject<{
+                            key: z.ZodString;
+                        }, z.core.$loose>;
+                        key: z.ZodString;
+                    }, z.core.$loose>;
+                    label: z.ZodString;
+                }, z.core.$loose>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    facets: z.ZodArray<z.ZodObject<{
+        identifier: z.ZodObject<{
+            key: z.ZodString;
+        }, z.core.$loose>;
+        name: z.ZodString;
+        values: z.ZodArray<z.ZodObject<{
+            identifier: z.ZodObject<{
+                facet: z.ZodObject<{
+                    key: z.ZodString;
+                }, z.core.$loose>;
+                key: z.ZodString;
+            }, z.core.$strip>;
+            name: z.ZodString;
+            count: z.ZodNumber;
+            active: z.ZodBoolean;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    identifier: z.ZodDefault<z.ZodObject<{
+        term: z.ZodString;
+        facets: z.ZodArray<z.ZodObject<{
+            facet: z.ZodObject<{
+                key: z.ZodString;
+            }, z.core.$loose>;
+            key: z.ZodString;
+        }, z.core.$strip>>;
+        filters: z.ZodArray<z.ZodString>;
+        paginationOptions: z.ZodObject<{
+            pageNumber: z.ZodDefault<z.ZodNumber>;
+            pageSize: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$loose>;
+        categoryFilter: z.ZodOptional<z.ZodObject<{
+            facet: z.ZodObject<{
+                key: z.ZodString;
+            }, z.core.$loose>;
+            key: z.ZodString;
+        }, z.core.$strip>>;
+        key: z.ZodString;
+        index: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export type AlgoliaProductSearchResult = z.infer<typeof AlgoliaProductSearchResultSchema>;
+export type AlgoliaProductSearchIdentifier = z.infer<typeof AlgoliaProductSearchIdentifierSchema>;
+export interface AlgoliaNativeVariant {
+    sku: string;
+    image: string;
+}
+export interface AlgoliaNativeRecord {
+    objectID: string;
+    slug?: string;
+    name?: string;
+    variants: Array<AlgoliaNativeVariant>;
+}

package/src/test/client-builder-product-search-extension.example.d.ts

@@ -0,0 +1 @@
+export {};

package/test/client-builder-product-search-extension.example.js

@@ -0,0 +1,61 @@
+import {
+  ClientBuilder,
+  NoOpCache,
+  createInitialRequestContext
+} from "@reactionary/core";
+import * as z from "zod";
+import { withAlgoliaCapabilities } from "../core/initialize.js";
+import { AlgoliaProductSearchFactory } from "../factories/product-search/product-search.factory.js";
+import { AlgoliaProductSearchResultSchema } from "../schema/search.schema.js";
+const assertType = (_value) => {
+};
+const assertNotAny = (_value) => {
+};
+const ExtendedProductSearchResultSchema = AlgoliaProductSearchResultSchema.safeExtend(
+  {
+    extendedMeta: z.string()
+  }
+);
+class ExtendedAlgoliaProductSearchFactory extends AlgoliaProductSearchFactory {
+  constructor() {
+    super(ExtendedProductSearchResultSchema);
+  }
+  parseSearchResult(context, data, query) {
+    const base = super.parseSearchResult(context, data, query);
+    return this.productSearchResultSchema.parse({
+      ...base,
+      extendedMeta: "from-factory"
+    });
+  }
+}
+const config = {
+  appId: "ALGOLIA_APP_ID",
+  apiKey: "ALGOLIA_API_KEY",
+  indexName: "ALGOLIA_INDEX"
+};
+const client = new ClientBuilder(createInitialRequestContext()).withCache(new NoOpCache()).withCapability(
+  withAlgoliaCapabilities(config, {
+    productSearch: {
+      enabled: true,
+      factory: new ExtendedAlgoliaProductSearchFactory()
+    }
+  })
+).build();
+client.productSearch.queryByTerm({
+  search: {
+    term: "test",
+    facets: [],
+    filters: [],
+    paginationOptions: {
+      pageNumber: 1,
+      pageSize: 10
+    }
+  }
+}).then((result) => {
+  assertNotAny(result);
+  if (result.success) {
+    assertNotAny(result.value);
+    assertNotAny(result.value.extendedMeta);
+    assertType(result.value.extendedMeta);
+  }
+});