@reactionary/source 0.3.2 → 0.3.4

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

@@ -0,0 +1,140 @@
+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);
+    });
+  });
+
+
+
+describe.each([PrimaryProvider.ALGOLIA])(
+  'Product Recommendations - Related - %s',
+  (provider) => {
+    let client: ReturnType<typeof createClient>;
+
+    beforeEach(() => {
+      client = createClient(provider);
+    });
+
+    it('should be able to return a list of products for recommendation - Related ', async () => {
+      const result = await client.productRecommendations.getRecommendations({
+        algorithm: 'related',
+        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: 'related',
+        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.2",
+  "version": "0.3.4",
   "license": "MIT",
   "private": false,
   "dependencies": {
@@ -16,7 +16,7 @@
     "@opentelemetry/sdk-trace-base": "^2.0.1",
     "@opentelemetry/sdk-trace-node": "^2.0.1",
     "@upstash/redis": "^1.34.9",
-    "algoliasearch": "^5.23.4",
+    "algoliasearch": "^5.48.0",
     "debug": "^4.4.3",
     "dotenv": "^17.2.2",
     "meilisearch": "^0.55.0",

package/providers/algolia/package.json

@@ -5,7 +5,7 @@
   "types": "src/index.d.ts",
   "dependencies": {
     "@reactionary/core": "0.0.1",
-    "algoliasearch": "^5.23.4",
+    "algoliasearch": "^5.48.0",
     "zod": "4.1.9"
   },
   "type": "module",

package/providers/algolia/src/core/initialize.ts

@@ -3,9 +3,11 @@ import { AlgoliaProductSearchProvider } from "../providers/product-search.provid
 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) {
@@ -16,6 +18,10 @@ export function withAlgoliaCapabilities<T extends AlgoliaCapabilities>(configura
             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/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,236 @@
+import {
+  type Cache,
+  ProductRecommendationsProvider,
+  type ProductRecommendation,
+  type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery,
+  type ProductRecommendationAlgorithmSimilarProductsQuery,
+  type ProductRecommendationAlgorithmRelatedProductsQuery,
+  type ProductRecommendationAlgorithmTrendingInCategoryQuery,
+  type RequestContext,
+  type ProductRecommendationsQuery,
+} from '@reactionary/core';
+import {
+  liteClient,
+  type BoughtTogetherQuery,
+  type LookingSimilarQuery,
+  type RecommendationsResults,
+  type RecommendSearchParams,
+  type RelatedQuery,
+  type TrendingItemsQuery,
+  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 class AlgoliaProductRecommendationsProvider extends ProductRecommendationsProvider {
+  protected config: AlgoliaConfiguration;
+  protected client: LiteClient;
+
+  constructor(config: AlgoliaConfiguration, cache: Cache, context: RequestContext) {
+    super(cache, context);
+    this.config = config;
+    this.client = liteClient(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[]> {
+
+    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 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')
+          } 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[]> {
+
+    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')
+          } 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[]> {
+
+    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')
+          } 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[]> {
+    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')
+          } 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/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>;

package/providers/medusa/src/core/initialize.ts

@@ -12,6 +12,7 @@ import { MedusaOrderSearchProvider } from "../providers/order-search.provider.js
 import { MedusaOrderProvider } from "../providers/order.provider.js";
 import { MedusaPriceProvider } from "../providers/price.provider.js";
 import { MedusaSearchProvider } from "../providers/product-search.provider.js";
+import { MedusaProductRecommendationsProvider } from "../providers/product-recommendations.provider.js";
 import { MedusaProductProvider } from "../providers/product.provider.js";
 import { MedusaProfileProvider } from "../providers/profile.provider.js";
 import { MedusaCapabilitiesSchema, type MedusaCapabilities } from "../schema/capabilities.schema.js";
@@ -23,6 +24,7 @@ export function withMedusaCapabilities<T extends MedusaCapabilities>(
     capabilities: T
 ) {
     return (cache: Cache, context: RequestContext): ClientFromCapabilities<T> => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const client: any = {};
         const config = MedusaConfigurationSchema.parse(configuration);
         const caps = MedusaCapabilitiesSchema.parse(capabilities);
@@ -34,6 +36,10 @@ export function withMedusaCapabilities<T extends MedusaCapabilities>(
             client.productSearch = new MedusaSearchProvider(configuration, cache, context, medusaApi);
         }
 
+        if (caps.productRecommendations) {
+            client.productRecommendations = new MedusaProductRecommendationsProvider(configuration, cache, context, medusaApi);
+        }
+
         if (caps.category) {
             client.category = new MedusaCategoryProvider(configuration, cache, context, medusaApi);
         }

package/providers/medusa/src/index.ts

@@ -10,4 +10,5 @@ export * from './providers/order.provider.js';
 export * from './providers/order-search.provider.js';
 export * from './providers/price.provider.js';
 export * from './providers/product-search.provider.js';
+export * from './providers/product-recommendations.provider.js';
 export * from './providers/profile.provider.js';

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

@@ -0,0 +1,117 @@
+import {
+  type Cache,
+  ProductRecommendationsProvider,
+  type ProductRecommendation,
+  type ProductRecommendationsByCollectionQuery,
+  type RequestContext,
+  type Result,
+  success, error,
+  NotFoundErrorSchema,
+  type NotFoundError,
+  errorToString,
+} from '@reactionary/core';
+import createDebug from 'debug';
+import type { MedusaAPI } from '../core/client.js';
+import type { MedusaConfiguration } from '../schema/configuration.schema.js';
+
+const debug = createDebug('reactionary:medusa:product-recommendations');
+
+/**
+ * MedusaProductRecommendationsProvider
+ *
+ * Provides product recommendations using Medusa's collection-based product grouping.
+ * Only overrides the getCollection method to fetch products from Medusa collections.
+ *
+ * Note: This implementation leverages Medusa's product collections feature to provide
+ * curated product recommendations. Collections are typically manually managed or
+ * created through Medusa's admin panel or API.
+ */
+export class MedusaProductRecommendationsProvider extends ProductRecommendationsProvider {
+  protected config: MedusaConfiguration;
+  protected medusaApi: MedusaAPI;
+
+  constructor(config: MedusaConfiguration, cache: Cache, context: RequestContext, medusaApi: MedusaAPI) {
+    super(cache, context);
+    this.config = config;
+    this.medusaApi = medusaApi;
+  }
+
+  /**
+   * Get product recommendations from a Medusa collection
+   *
+   * This method fetches products from a specific Medusa collection by name or handle.
+   * It's useful for displaying curated product lists like "Featured Products",
+   * "New Arrivals", "Best Sellers", etc.
+   */
+  public override async getCollection(
+    query: ProductRecommendationsByCollectionQuery
+  ): Promise<Result<ProductRecommendation[]>> {
+    const client = await this.medusaApi.getClient();
+
+    try {
+      if (debug.enabled) {
+        debug(`Fetching collection: ${query.collectionName}`);
+      }
+
+      // First, find the collection by handle/name
+      const collectionsResponse = await client.store.collection.list({
+        handle: query.collectionName,
+        limit: 1,
+      });
+
+      if (!collectionsResponse.collections || collectionsResponse.collections.length === 0) {
+        if (debug.enabled) {
+          debug(`Collection not found: ${query.collectionName}`);
+        }
+        return error<NotFoundError>({
+          type: 'NotFound',
+          identifier: query.collectionName
+        });
+      }
+
+      const collection = collectionsResponse.collections[0];
+
+      if (debug.enabled) {
+        debug(`Found collection: ${collection.title} (${collection.id})`);
+      }
+
+      // Fetch products from the collection
+      const productsResponse = await client.store.product.list({
+        collection_id: [collection.id],
+        limit: query.numberOfRecommendations,
+        fields: '+variants.id,+variants.sku',
+      });
+
+      if (debug.enabled) {
+        debug(`Found ${productsResponse.products.length} products in collection`);
+      }
+
+      // Map products to recommendations
+      const recommendations: ProductRecommendation[] = [];
+
+      for (const product of productsResponse.products) {
+        recommendations.push({
+          recommendationIdentifier: {
+            key: `${collection.id}_${product.id}`,
+            algorithm: 'collection',
+          },
+          product: {
+            key: product.id
+          },
+        });
+      }
+
+      if (debug.enabled) {
+        debug(`Returning ${recommendations.length} recommendations`);
+      }
+
+      return success(recommendations);
+    } catch (error) {
+      if (debug.enabled) {
+        debug(`Error fetching collection recommendations: %O`, error);
+      }
+      console.error('Error fetching collection recommendations:', error);
+      return success([]);
+    }
+  }
+}

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

@@ -3,6 +3,7 @@ import type { z } from 'zod';
 
 export const MedusaCapabilitiesSchema = CapabilitiesSchema.pick({
     productSearch: true,
+    productRecommendations: true,
     cart: true,
     checkout: true,
     category: true,

package/providers/meilisearch/src/core/initialize.ts

@@ -1,17 +1,23 @@
 import type { Cache, ClientFromCapabilities, RequestContext } from "@reactionary/core";
 import { MeilisearchSearchProvider } from "../providers/product-search.provider.js";
+import { MeilisearchProductRecommendationsProvider } from "../providers/product-recommendations.provider.js";
 import { MeilisearchOrderSearchProvider } from "../providers/order-search.provider.js";
 import type { MeilisearchCapabilities } from "../schema/capabilities.schema.js";
 import type { MeilisearchConfiguration } from "../schema/configuration.schema.js";
 
 export function withMeilisearchCapabilities<T extends MeilisearchCapabilities>(configuration: MeilisearchConfiguration, 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 MeilisearchSearchProvider(configuration, cache, context);
         }
 
+        if (capabilities.productRecommendations) {
+            client.productRecommendations = new MeilisearchProductRecommendationsProvider(configuration, cache, context);
+        }
+
         if (capabilities.orderSearch) {
             client.orderSearch = new MeilisearchOrderSearchProvider(configuration, cache, context);
         }

package/providers/meilisearch/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 './providers/order-search.provider.js';
 
 export * from './schema/configuration.schema.js';

package/providers/meilisearch/src/providers/index.ts

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