@reactionary/provider-algolia 0.3.1 → 0.3.3

package/README.md

@@ -38,11 +38,19 @@ You can have more, for use with facets, and additional searchable fields, but th
 
 The `objectID` corrosponds to your productIdentifier, and `variantID` should match your SKU
 
+## Analytics
 
-## Building
+The Algolia analytics provider maps the following tracked event types to data tracked in Algolia:
 
-Run `nx build provider-algolia` to build the library.
+- AnalyticsMutationProductSummaryViewEvent => ViewedObjectIDs
+- AnalyticsMutationProductSummaryClickEvent => ClickedObjectIDsAfterSearch / ClickedObjectIDs
+- AnalyticsMutationProductAddToCartEvent => AddedToCartObjectIDsAfterSearch / AddedToCartObjectIDs
+- AnalyticsMutationPurchaseEvent => PurchasedObjectIDs
 
-## Running unit tests
+The `AfterSearch` variants are (with the exception of purchase) preferred by the provider in the cases where Algolia is the source of the events. For search or recommendation this would typically be the case, but not necesarily for users arriving on a PDP as a direct target from a search or a link.
 
-Run `nx test provider-algolia` to execute the unit tests via [Jest](https://jestjs.io).
+Note that we do not map `PurchasedObjectIDsAfterSearch` as it would require us to persist the search query ID that lead to the add-to-cart occuring on the cart items. This currently seems like an excess burden to impose on the cart interface. 
+
+The `ConvertedObjectIDs` and `ConvertedObjectIDsAfterSearch` are not mapped as they seem superfluous by all accounts in a product-purchase based flow. They could likely be used for other types of conversions in a more general setup, such as a customer finishing reading an article.
+
+Finally the events that are related to filtering are not mapped, as they are by all accounts deprecated and no longer influence any of the recommendation or personalization features.

package/core/initialize.js

@@ -1,14 +1,18 @@
-import { AlgoliaSearchProvider } from "../providers/product-search.provider.js";
+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 = {};
     if (capabilities.productSearch) {
-      client.productSearch = new AlgoliaSearchProvider(configuration, cache, context);
+      client.productSearch = new AlgoliaProductSearchProvider(cache, context, configuration);
     }
     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,10 +1,10 @@
 {
   "name": "@reactionary/provider-algolia",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "main": "index.js",
   "types": "src/index.d.ts",
   "dependencies": {
-    "@reactionary/core": "0.3.1",
+    "@reactionary/core": "0.3.3",
     "algoliasearch": "^5.23.4",
     "zod": "4.1.9"
   },

package/providers/analytics.provider.js

@@ -2,13 +2,13 @@ import {
   AnalyticsProvider
 } from "@reactionary/core";
 import {
-  insightsClient
+  algoliasearch
 } from "algoliasearch";
 class AlgoliaAnalyticsProvider extends AnalyticsProvider {
   constructor(cache, requestContext, config) {
     super(cache, requestContext);
     this.config = config;
-    this.client = insightsClient(this.config.appId, this.config.apiKey);
+    this.client = algoliasearch(this.config.appId, this.config.apiKey).initInsights({});
   }
   async processProductAddToCart(event) {
     if (event.source && event.source.type === "search") {
@@ -21,7 +21,7 @@ class AlgoliaAnalyticsProvider extends AnalyticsProvider {
         userToken: this.context.session.identityContext.personalizationKey,
         queryID: event.source.identifier.key
       };
-      this.client.pushEvents({
+      const response = await this.client.pushEvents({
         events: [algoliaEvent]
       });
     }
@@ -37,7 +37,7 @@ class AlgoliaAnalyticsProvider extends AnalyticsProvider {
         positions: [event.position],
         queryID: event.source.identifier.key
       };
-      this.client.pushEvents({
+      const response = await this.client.pushEvents({
         events: [algoliaEvent]
       });
     }
@@ -51,7 +51,7 @@ class AlgoliaAnalyticsProvider extends AnalyticsProvider {
         objectIDs: event.products.map((x) => x.key),
         userToken: this.context.session.identityContext.personalizationKey
       };
-      this.client.pushEvents({
+      const response = await this.client.pushEvents({
         events: [algoliaEvent]
       });
     }
@@ -62,10 +62,10 @@ class AlgoliaAnalyticsProvider extends AnalyticsProvider {
       eventType: "conversion",
       eventSubtype: "purchase",
       index: this.config.indexName,
-      objectIDs: event.order.items.map((x) => x.identifier.key),
+      objectIDs: event.order.items.map((x) => x.variant.sku),
       userToken: this.context.session.identityContext.personalizationKey
     };
-    this.client.pushEvents({
+    const response = await this.client.pushEvents({
       events: [algoliaEvent]
     });
   }

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,174 @@
+import {
+  ProductRecommendationsProvider
+} from "@reactionary/core";
+import { recommendClient } from "algoliasearch";
+class AlgoliaProductRecommendationsProvider extends ProductRecommendationsProvider {
+  constructor(config, cache, context) {
+    super(cache, context);
+    this.config = config;
+  }
+  getRecommendClient() {
+    return recommendClient(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) {
+    const client = this.getRecommendClient();
+    try {
+      const response = await 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) {
+    const client = this.getRecommendClient();
+    try {
+      const response = await 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) {
+    const client = this.getRecommendClient();
+    try {
+      const response = await 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) {
+    const client = this.getRecommendClient();
+    try {
+      const response = await 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/providers/product-search.provider.js

@@ -23,8 +23,8 @@ import {
   success
 } from "@reactionary/core";
 import { algoliasearch } from "algoliasearch";
-class AlgoliaSearchProvider extends ProductSearchProvider {
-  constructor(config, cache, context) {
+class AlgoliaProductSearchProvider extends ProductSearchProvider {
+  constructor(cache, context, config) {
     super(cache, context);
     this.config = config;
   }
@@ -136,7 +136,9 @@ class AlgoliaSearchProvider extends ProductSearchProvider {
         term: query.search.term,
         facets: query.search.facets,
         filters: query.search.filters,
-        paginationOptions: query.search.paginationOptions
+        paginationOptions: query.search.paginationOptions,
+        index: body.index || "",
+        key: body.queryID || ""
       },
       pageNumber: (body.page || 0) + 1,
       pageSize: body.hitsPerPage || 0,
@@ -177,7 +179,7 @@ __decorateClass([
     inputSchema: ProductSearchQueryByTermSchema,
     outputSchema: ProductSearchResultSchema
   })
-], AlgoliaSearchProvider.prototype, "queryByTerm", 1);
+], AlgoliaProductSearchProvider.prototype, "queryByTerm", 1);
 export {
-  AlgoliaSearchProvider
+  AlgoliaProductSearchProvider
 };

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 RecommendClient, type RecommendSearchParams } from 'algoliasearch';
+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;
+    constructor(config: AlgoliaConfiguration, cache: Cache, context: RequestContext);
+    protected getRecommendClient(): RecommendClient;
+    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/providers/product-search.provider.d.ts

@@ -11,9 +11,9 @@ interface AlgoliaNativeRecord {
     name?: string;
     variants: Array<AlgoliaNativeVariant>;
 }
-export declare class AlgoliaSearchProvider extends ProductSearchProvider {
+export declare class AlgoliaProductSearchProvider extends ProductSearchProvider {
     protected config: AlgoliaConfiguration;
-    constructor(config: AlgoliaConfiguration, cache: Cache, context: RequestContext);
+    constructor(cache: Cache, context: RequestContext, config: AlgoliaConfiguration);
     queryByTerm(payload: ProductSearchQueryByTerm): Promise<Result<ProductSearchResult>>;
     createCategoryNavigationFilter(payload: ProductSearchQueryCreateNavigationFilter): Promise<Result<FacetValueIdentifier>>;
     protected parseSingle(body: AlgoliaNativeRecord): {
@@ -39,6 +39,8 @@ export declare class AlgoliaSearchProvider extends ProductSearchProvider {
                 pageNumber: number;
                 pageSize: number;
             };
+            index: string;
+            key: string;
         };
         pageNumber: number;
         pageSize: number;

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>;