@reactionary/source 0.3.1 → 0.3.3

package/examples/node/src/capabilities/product-recommendations.spec.ts

@@ -0,0 +1,96 @@
+import 'dotenv/config';
+import { assert, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createClient, PrimaryProvider } from '../utils.js';
+import type { ProductSearchQueryCreateNavigationFilter } from '@reactionary/core';
+
+const testData = {
+  product: {
+    id: 'product_10959528',
+    name: 'Manhattan 170703 cable accessory Cable kit',
+    image: 'https://images.icecat.biz/img/norm/high/10959528-2837.jpg',
+    sku: '0766623170703',
+    slug: 'manhattan-170703-cable-accessory-cable-kit-10959528',
+  },
+  productWithMultiVariants: {
+    slug: 'hp-gk859aa-mouse-office-bluetooth-laser-1600-dpi-1377612',
+  },
+};
+
+describe.each([PrimaryProvider.MEDUSA])(
+  'Product Recommendations - Collections - %s',
+  (provider) => {
+    let client: ReturnType<typeof createClient>;
+
+    beforeEach(() => {
+      client = createClient(provider);
+    });
+
+    it('should be able to return a list of products for a collection', async () => {
+      const result = await client.productRecommendations.getCollection({
+        collectionName: 'newest-arrivals',
+        numberOfRecommendations: 10,
+      });
+
+      if (!result.success) {
+        assert.fail(JSON.stringify(result.error));
+      }
+
+      expect(result.value.length).toBeGreaterThan(0);
+    });
+
+    it('should return an empty result for an unknown collection', async () => {
+      const result = await client.productRecommendations.getCollection({
+        collectionName: 'Unknown Collection',
+        numberOfRecommendations: 10,
+      });
+
+      if (!result.success) {
+        assert.fail(JSON.stringify(result.error));
+      }
+
+      expect(result.value.length).toBe(0);
+    });
+  });
+
+
+describe.each([PrimaryProvider.MEILISEARCH])(
+  'Product Recommendations - Similar - %s',
+  (provider) => {
+    let client: ReturnType<typeof createClient>;
+
+    beforeEach(() => {
+      client = createClient(provider);
+    });
+
+    it('should be able to return a list of products for recommendation - Similar ', async () => {
+      const result = await client.productRecommendations.getRecommendations({
+        algorithm: 'similar',
+        sourceProduct: {
+          key: testData.product.id,
+        },
+        numberOfRecommendations: 10,
+      });
+
+      if (!result.success) {
+        assert.fail(JSON.stringify(result.error));
+      }
+
+      expect(result.value.length).toBeGreaterThan(0);
+    });
+
+    it('should return an empty result for an unknown sku', async () => {
+      const result = await client.productRecommendations.getRecommendations({
+        algorithm: 'similar',
+        sourceProduct: {
+          key: 'unknown-product-id',
+        },
+        numberOfRecommendations: 10,
+      });
+
+      if (!result.success) {
+        assert.fail(JSON.stringify(result.error));
+      }
+
+      expect(result.value.length).toBe(0);
+    });
+  });

package/examples/node/src/utils.ts

@@ -91,6 +91,7 @@ export function createClient(provider: PrimaryProvider) {
           order: true,
           price: true,
           productSearch: true,
+          productRecommendations: true,
           orderSearch: true,
           store: true,
           profile: true
@@ -124,6 +125,7 @@ export function createClient(provider: PrimaryProvider) {
     builder = builder.withCapability(
       withAlgoliaCapabilities(getAlgoliaTestConfiguration(), {
         productSearch: true,
+        productRecommendations: true,
       })
     );
   }
@@ -133,6 +135,7 @@ export function createClient(provider: PrimaryProvider) {
       withMeilisearchCapabilities(getMeilisearchTestConfiguration(), {
         productSearch: true,
         orderSearch: true,
+        productRecommendations: true,
       }),
     );
     builder = builder.withCapability(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/source",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "license": "MIT",
   "private": false,
   "dependencies": {

package/providers/algolia/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/providers/algolia/src/core/initialize.ts

@@ -1,21 +1,27 @@
 import type { Cache, ClientFromCapabilities, RequestContext } from "@reactionary/core";
-import { AlgoliaSearchProvider } from "../providers/product-search.provider.js";
+import { AlgoliaProductSearchProvider } from "../providers/product-search.provider.js";
 import type { AlgoliaCapabilities } from "../schema/capabilities.schema.js";
 import type { AlgoliaConfiguration } from "../schema/configuration.schema.js";
 import { AlgoliaAnalyticsProvider } from "../providers/analytics.provider.js";
+import { AlgoliaProductRecommendationsProvider } from "../providers/product-recommendations.provider.js";
 
 export function withAlgoliaCapabilities<T extends AlgoliaCapabilities>(configuration: AlgoliaConfiguration, capabilities: T) {
     return (cache: Cache, context: RequestContext): ClientFromCapabilities<T> => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const client: any = {};
 
         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/providers/algolia/src/index.ts

@@ -1,5 +1,6 @@
 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/providers/algolia/src/providers/analytics.provider.ts

@@ -8,12 +8,12 @@ import {
   type RequestContext,
 } from '@reactionary/core';
 import {
-  insightsClient,
   type InsightsClient,
   type ViewedObjectIDs,
   type ClickedObjectIDsAfterSearch,
   type AddedToCartObjectIDsAfterSearch,
   type PurchasedObjectIDs,
+  algoliasearch,
 } from 'algoliasearch';
 import type { AlgoliaConfiguration } from '../schema/configuration.schema.js';
 import type { AlgoliaProductSearchIdentifier } from '../schema/search.schema.js';
@@ -30,7 +30,7 @@ export class AlgoliaAnalyticsProvider extends AnalyticsProvider {
     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({});
   }
 
   protected override async processProductAddToCart(
@@ -48,7 +48,7 @@ export class AlgoliaAnalyticsProvider extends AnalyticsProvider {
           .key,
       } satisfies AddedToCartObjectIDsAfterSearch;
 
-      this.client.pushEvents({
+      const response = await this.client.pushEvents({
         events: [algoliaEvent],
       });
     }
@@ -69,7 +69,7 @@ export class AlgoliaAnalyticsProvider extends AnalyticsProvider {
           .key,
       } satisfies ClickedObjectIDsAfterSearch;
 
-      this.client.pushEvents({
+      const response = await this.client.pushEvents({
         events: [algoliaEvent],
       });
     }
@@ -87,7 +87,7 @@ export class AlgoliaAnalyticsProvider extends AnalyticsProvider {
         userToken: this.context.session.identityContext.personalizationKey,
       } satisfies ViewedObjectIDs;
 
-      this.client.pushEvents({
+      const response = await this.client.pushEvents({
         events: [algoliaEvent],
       });
     }
@@ -96,16 +96,18 @@ export class AlgoliaAnalyticsProvider extends AnalyticsProvider {
   protected override async processPurchase(
     event: AnalyticsMutationPurchaseEvent
   ): Promise<void> {
+    // TODO: Figure out how to handle the problem below. From the order we have the SKUs,
+    // but in Algolia we have the products indexed, and we can't really resolve it here...
     const algoliaEvent = {
       eventName: 'purchase',
       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,
     } satisfies PurchasedObjectIDs;
 
-    this.client.pushEvents({
+    const response = await this.client.pushEvents({
       events: [algoliaEvent],
     });
   }

package/providers/algolia/src/providers/index.ts

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

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

@@ -0,0 +1,234 @@
+import {
+  type Cache,
+  ProductRecommendationsProvider,
+  type ProductRecommendation,
+  type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery,
+  type ProductRecommendationAlgorithmSimilarProductsQuery,
+  type ProductRecommendationAlgorithmRelatedProductsQuery,
+  type ProductRecommendationAlgorithmTrendingInCategoryQuery,
+  type RequestContext,
+  type ProductRecommendationsQuery,
+} from '@reactionary/core';
+import { recommendClient, type BoughtTogetherQuery, type LookingSimilarQuery, type RecommendationsResults, type RecommendClient, type RecommendSearchParams, type RelatedQuery, type TrendingItemsQuery } 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 class AlgoliaProductRecommendationsProvider extends ProductRecommendationsProvider {
+  protected config: AlgoliaConfiguration;
+
+  constructor(config: AlgoliaConfiguration, cache: Cache, context: RequestContext) {
+    super(cache, context);
+    this.config = config;
+  }
+
+  protected getRecommendClient(): RecommendClient {
+    return recommendClient(this.config.appId, this.config.apiKey);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  protected getRecommendationThreshold(_algorithm: string): number {
+    // Default threshold can be customized per algorithm if needed
+    // The parameter is currently unused but kept for future algorithm-specific threshold customization
+    return 10;
+  }
+
+  protected getQueryParametersForRecommendations(algorithm: string): RecommendSearchParams {
+    return  {
+      userToken: this.context.session.identityContext?.personalizationKey || 'anonymous',
+      analytics: true,
+      analyticsTags: ['reactionary', algorithm],
+      clickAnalytics: true
+    } satisfies RecommendSearchParams;
+  }
+
+  /**
+   * Get frequently bought together recommendations using Algolia Recommend
+   */
+  protected override async getFrequentlyBoughtTogetherRecommendations(
+    query: ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery
+  ): Promise<ProductRecommendation[]> {
+    const client = this.getRecommendClient();
+
+    try {
+      // Note: Algolia's Recommend API requires setting up AI Recommend models
+      // This implementation uses the getRecommendations method from the recommend client
+      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')
+          } satisfies BoughtTogetherQuery,
+        ],
+
+      });
+
+      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
+   */
+  protected override async getSimilarProductsRecommendations(
+    query: ProductRecommendationAlgorithmSimilarProductsQuery
+  ): Promise<ProductRecommendation[]> {
+    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')
+          } satisfies LookingSimilarQuery
+        ],
+      });
+
+      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
+   */
+  protected override async getRelatedProductsRecommendations(
+    query: ProductRecommendationAlgorithmRelatedProductsQuery
+  ): Promise<ProductRecommendation[]> {
+    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')
+          } satisfies RelatedQuery,
+        ],
+      });
+
+      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
+   */
+  protected override async getTrendingInCategoryRecommendations(
+    query: ProductRecommendationAlgorithmTrendingInCategoryQuery
+  ): Promise<ProductRecommendation[]> {
+    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')
+          } satisfies TrendingItemsQuery,
+        ],
+      });
+
+      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 [];
+    }
+  }
+
+
+  protected parseRecommendation(res: RecommendationsResults, query: ProductRecommendationsQuery) {
+    const result = [];
+    for(const hit of res.hits as AlgoliaRecommendHit[]) {
+      const recommendationIdentifier = {
+        key: res.queryID || 'x',
+        algorithm: query.algorithm,
+        abTestID: res.abTestID,
+        abTestVariantID: res.abTestVariantID
+      } satisfies AlgoliaProductRecommendationIdentifier
+      const recommendation = this.parseSingle(hit, recommendationIdentifier)
+      result.push(recommendation);
+    }
+    return result;
+  }
+
+  /**
+   * Maps Algolia recommendation results to ProductRecommendation format
+   */
+  protected parseSingle(hit: AlgoliaRecommendHit, recommendationIdentifier: AlgoliaProductRecommendationIdentifier): ProductRecommendation {
+    return {
+      recommendationIdentifier,
+      product: {
+        key: hit.objectID,
+      },
+    } satisfies ProductRecommendation;
+  }
+}

package/providers/algolia/src/providers/product-search.provider.ts

@@ -40,10 +40,10 @@ interface AlgoliaNativeRecord {
 }
 
 
-export class AlgoliaSearchProvider extends ProductSearchProvider {
+export class AlgoliaProductSearchProvider extends ProductSearchProvider {
   protected config: AlgoliaConfiguration;
 
-  constructor(config: AlgoliaConfiguration, cache: Cache, context: RequestContext) {
+  constructor(cache: Cache, context: RequestContext, config: AlgoliaConfiguration) {
     super(cache, context);
     this.config = config;
   }
@@ -195,7 +195,8 @@ export class AlgoliaSearchProvider extends ProductSearchProvider {
         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,
@@ -203,7 +204,7 @@ export class AlgoliaSearchProvider extends ProductSearchProvider {
       totalPages: body.nbPages || 0,
       items: items,
       facets,
-    } satisfies ProductSearchResult;
+    } satisfies AlgoliaProductSearchResult;
 
     return result;
   }

package/providers/algolia/src/schema/capabilities.schema.ts

@@ -3,7 +3,8 @@ import type { z } from 'zod';
 
 export const AlgoliaCapabilitiesSchema = CapabilitiesSchema.pick({
     productSearch: true,
-    analytics: true
+    analytics: true,
+    productRecommendations: true
 }).partial();
 
 export type AlgoliaCapabilities = z.infer<typeof AlgoliaCapabilitiesSchema>;

package/providers/algolia/src/schema/product-recommendation.schema.ts

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