@reactionary/provider-algolia 0.3.2 → 0.3.4

package/core/initialize.js

@@ -1,5 +1,6 @@
 import { AlgoliaProductSearchProvider } from "../providers/product-search.provider.js";
 import { AlgoliaAnalyticsProvider } from "../providers/analytics.provider.js";
+import { AlgoliaProductRecommendationsProvider } from "../providers/product-recommendations.provider.js";
 function withAlgoliaCapabilities(configuration, capabilities) {
   return (cache, context) => {
     const client = {};
@@ -9,6 +10,9 @@ function withAlgoliaCapabilities(configuration, capabilities) {
     if (capabilities.analytics) {
       client.analytics = new AlgoliaAnalyticsProvider(cache, context, configuration);
     }
+    if (capabilities.productRecommendations) {
+      client.productRecommendations = new AlgoliaProductRecommendationsProvider(configuration, cache, context);
+    }
     return client;
   };
 }

package/index.js

@@ -1,4 +1,5 @@
 export * from "./core/initialize.js";
 export * from "./providers/product-search.provider.js";
+export * from "./providers/product-recommendations.provider.js";
 export * from "./schema/configuration.schema.js";
 export * from "./schema/capabilities.schema.js";

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@reactionary/provider-algolia",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "main": "index.js",
   "types": "src/index.d.ts",
   "dependencies": {
-    "@reactionary/core": "0.3.2",
-    "algoliasearch": "^5.23.4",
+    "@reactionary/core": "0.3.4",
+    "algoliasearch": "^5.48.0",
     "zod": "4.1.9"
   },
   "type": "module",

package/providers/index.js

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

package/providers/product-recommendations.provider.js

@@ -0,0 +1,170 @@
+import {
+  ProductRecommendationsProvider
+} from "@reactionary/core";
+import {
+  liteClient
+} from "algoliasearch/lite";
+class AlgoliaProductRecommendationsProvider extends ProductRecommendationsProvider {
+  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) {
+    return {
+      recommendationIdentifier,
+      product: {
+        key: hit.objectID
+      }
+    };
+  }
+}
+export {
+  AlgoliaProductRecommendationsProvider
+};

package/schema/capabilities.schema.js

@@ -1,7 +1,8 @@
 import { CapabilitiesSchema } from "@reactionary/core";
 const AlgoliaCapabilitiesSchema = CapabilitiesSchema.pick({
   productSearch: true,
-  analytics: true
+  analytics: true,
+  productRecommendations: true
 }).partial();
 export {
   AlgoliaCapabilitiesSchema

package/schema/product-recommendation.schema.js

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

package/src/index.d.ts

@@ -1,4 +1,5 @@
 export * from './core/initialize.js';
 export * from './providers/product-search.provider.js';
+export * from './providers/product-recommendations.provider.js';
 export * from './schema/configuration.schema.js';
 export * from './schema/capabilities.schema.js';

package/src/providers/index.d.ts

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

package/src/providers/product-recommendations.provider.d.ts

@@ -0,0 +1,58 @@
+import { type Cache, ProductRecommendationsProvider, type ProductRecommendation, type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery, type ProductRecommendationAlgorithmSimilarProductsQuery, type ProductRecommendationAlgorithmRelatedProductsQuery, type ProductRecommendationAlgorithmTrendingInCategoryQuery, type RequestContext, type ProductRecommendationsQuery } 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';
+interface AlgoliaRecommendHit {
+    objectID: string;
+    sku?: string;
+    [key: string]: unknown;
+}
+/**
+ * AlgoliaProductRecommendationsProvider
+ *
+ * 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 AlgoliaProductRecommendationsProvider extends ProductRecommendationsProvider {
+    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): {
+        [x: string]: unknown;
+        recommendationIdentifier: {
+            [x: string]: unknown;
+            key: string;
+            algorithm: string;
+        };
+        product: {
+            [x: string]: unknown;
+            key: string;
+        };
+    }[];
+    /**
+     * Maps Algolia recommendation results to ProductRecommendation format
+     */
+    protected parseSingle(hit: AlgoliaRecommendHit, recommendationIdentifier: AlgoliaProductRecommendationIdentifier): ProductRecommendation;
+}
+export {};

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

@@ -2,5 +2,6 @@ import type { z } from 'zod';
 export declare const AlgoliaCapabilitiesSchema: z.ZodObject<{
     analytics: z.ZodOptional<z.ZodBoolean>;
     productSearch: z.ZodOptional<z.ZodBoolean>;
+    productRecommendations: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>;
 export type AlgoliaCapabilities = z.infer<typeof AlgoliaCapabilitiesSchema>;

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

@@ -0,0 +1,8 @@
+import 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.z.core.$loose>;
+export type AlgoliaProductRecommendationIdentifier = z.infer<typeof AlgoliaProductSearchIdentifierSchema>;