@reactionary/source 0.3.2 → 0.3.3

package/core/src/client/client-builder.ts

@@ -6,6 +6,7 @@ import {
   RequestContextSchema,
   type RequestContext,
 } from '../schemas/session.schema.js';
+import { MulticastProductRecommendationsProvider, type ProductRecommendationsProvider } from '../providers/product-recommendations.provider.js';
 
 type CapabilityFactory<T> = (cache: Cache, context: RequestContext) => T;
 
@@ -52,6 +53,8 @@ export class ClientBuilder<TClient = Client> {
 
     const mergedAnalytics: AnalyticsProvider[] = [];
 
+    const mergedProductRecommendationsProviders: ProductRecommendationsProvider[] = [];
+
     for (const factory of this.factories) {
       const provider = factory(sharedCache, this.context);
       client = {
@@ -62,12 +65,17 @@ export class ClientBuilder<TClient = Client> {
       if (provider.analytics) {
         mergedAnalytics.push(provider.analytics);
       }
+
+      if (provider.productRecommendations) {
+        mergedProductRecommendationsProviders.push(provider.productRecommendations);
+      }
     }
 
     // Add cache to complete the client
     const completeClient = {
       ...client,
       analytics: new MulticastAnalyticsProvider(sharedCache, this.context, mergedAnalytics),
+      productRecommendations: new MulticastProductRecommendationsProvider(sharedCache, this.context, mergedProductRecommendationsProviders),
       cache: sharedCache,
     } as TClient & { cache: Cache };
 

package/core/src/client/client.ts

@@ -8,10 +8,14 @@ import type { Cache } from "../cache/cache.interface.js";
 import type { CategoryProvider } from "../providers/category.provider.js";
 import type { AnalyticsProvider, CheckoutProvider, OrderProvider, ProfileProvider, StoreProvider } from "../providers/index.js";
 import type { OrderSearchProvider } from "../providers/order-search.provider.js";
+import type { ProductRecommendationsProvider } from "../providers/product-recommendations.provider.js";
+import type { ProductAssociationsProvider } from "../providers/product-associations.provider.js";
 
 export interface Client {
     product: ProductProvider,
     productSearch: ProductSearchProvider,
+    productRecommendations: ProductRecommendationsProvider,
+    productAssociations: ProductAssociationsProvider,
     identity: IdentityProvider,
     cache: Cache,
     cart: CartProvider,

package/core/src/providers/index.ts

@@ -9,6 +9,8 @@ export * from './price.provider.js';
 export * from './product.provider.js';
 export * from './profile.provider.js';
 export * from './product-search.provider.js';
+export * from './product-recommendations.provider.js';
+export * from './product-associations.provider.js';
 export * from './store.provider.js';
 export * from './order.provider.js'
 export * from './order-search.provider.js'

package/core/src/providers/product-associations.provider.ts

@@ -0,0 +1,49 @@
+import type { ProductIdentifier, ProductVariantIdentifier } from "../schemas/index.js";
+import type { ProductAssociationsGetAccessoriesQuery, ProductAssociationsGetSparepartsQuery, ProductAssociationsGetReplacementsQuery } from "../schemas/queries/product-associations.query.js";
+import { BaseProvider } from "./base.provider.js";
+
+
+/**
+ * The product association provider is responsible for providing evidence based associations between products, such as
+ * accessories, spareparts, and replacements. These associations are typically used to provide recommendations to customers on the product detail page, but can also be used in other contexts such as the cart or post-purchase, but
+ * do not carry any personalization concept to them.
+ */
+export abstract class ProductAssociationsProvider extends BaseProvider {
+
+  /**
+   * Returns a list of product identifiers which are accessories to the given product.
+   * Accessories in are products in their own right, but are commonly purchased alongside or recommended as complementary to the main product. Examples of accessories include:
+   * - A phone case for a smartphone
+   * - A camera bag for a camera
+   *
+   *
+   * Usecase:
+   * - PDP: Accessories for this product
+   */
+  public abstract getAccessories(query: ProductAssociationsGetAccessoriesQuery): Promise<ProductVariantIdentifier[]>;
+
+  /**
+   * Returns a list of product identifiers which are spareparts to the given product.
+   * Spareparts are products which are necessary for the use of the main product, but are not typically purchased alongside it. Examples of spareparts include:
+   *
+   * Usecase:
+   * - PDP: Accessories for this product
+   */
+  public abstract getSpareparts(query: ProductAssociationsGetSparepartsQuery): Promise<ProductVariantIdentifier[]>;
+
+
+  /**
+   * This product is replaced by these equivalent or newer products
+   * @param query
+   */
+  public abstract getReplacements(query: ProductAssociationsGetReplacementsQuery): Promise<ProductVariantIdentifier[]>;
+
+
+  getResourceName(): string {
+    return 'product-associations';
+  }
+
+
+
+
+}

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

@@ -0,0 +1,150 @@
+import type { Cache } from '../cache/cache.interface.js';
+import { Reactionary } from "../decorators/reactionary.decorator.js";
+import { success, type ProductRecommendation, type ProductRecommendationsByCollectionQuery, type RequestContext, type Result } from "../schemas/index.js";
+import { ProductRecommendationsQuerySchema, type ProductRecommendationAlgorithmAlsoViewedProductsQuery, type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery, type ProductRecommendationAlgorithmPopuplarProductsQuery, type ProductRecommendationAlgorithmRelatedProductsQuery, type ProductRecommendationAlgorithmSimilarProductsQuery, type ProductRecommendationAlgorithmTopPicksProductsQuery, type ProductRecommendationAlgorithmTrendingInCategoryQuery, type ProductRecommendationsQuery } from "../schemas/queries/product-recommendations.query.js";
+import { BaseProvider } from "./base.provider.js";
+
+export abstract class ProductRecommendationsProvider extends BaseProvider {
+
+  /**
+   * returns a list of recommended products, based on the selected algorithm and the provided query parameters. The recommendations should be relevant to the product specified in the query, and can be personalized based on the customer segments or contexts provided. The provider should return a list of product variant identifiers that are recommended for the given product, which can then be used to fetch the full product details from the product provider if needed.
+   *   *
+   * Usecase:
+   *   - PDP - "Customers who viewed this product also viewed"
+   *   - Cart - "You might also like"
+   *   - Post-purchase - "Customers who bought this product also bought"
+   *   - Article page: "Products related to the product mentioned in this article"
+   * @param query
+   */
+  public async getRecommendations(query: ProductRecommendationsQuery): Promise<Result<ProductRecommendation[]>> {
+    if (query.algorithm === 'frequentlyBoughtTogether') {
+      return success(await this.getFrequentlyBoughtTogetherRecommendations(query));
+    }
+
+    if (query.algorithm === 'similar') {
+      return success(await this.getSimilarProductsRecommendations(query));
+    }
+
+    if (query.algorithm === 'related') {
+      return success(await this.getRelatedProductsRecommendations(query));
+    }
+
+    if (query.algorithm === 'trendingInCategory') {
+      return success(await this.getTrendingInCategoryRecommendations(query));
+    }
+
+    if (query.algorithm === 'popular') {
+      return success(await this.getPopularProductsRecommendations(query));
+    }
+
+    if (query.algorithm === 'topPicks') {
+      return success(await this.getTopPicksProductsRecommendations(query));
+    }
+
+    if (query.algorithm === 'alsoViewed') {
+      return success(await this.getAlsoViewedProductsRecommendations(query));
+    }
+    return success([]);
+  }
+
+  public async getCollection(query: ProductRecommendationsByCollectionQuery): Promise<Result<ProductRecommendation[]>> {
+    return success([]);
+  }
+
+  protected async getFrequentlyBoughtTogetherRecommendations(query: ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery): Promise<ProductRecommendation[]> {
+     return [];
+  }
+
+  protected async getSimilarProductsRecommendations(query: ProductRecommendationAlgorithmSimilarProductsQuery): Promise<ProductRecommendation[]> {
+    return [];
+  }
+
+  protected async getTrendingInCategoryRecommendations(query: ProductRecommendationAlgorithmTrendingInCategoryQuery): Promise<ProductRecommendation[]> {
+    return [];
+  }
+
+  protected async getRelatedProductsRecommendations(query: ProductRecommendationAlgorithmRelatedProductsQuery): Promise<ProductRecommendation[]> {
+    return [];
+  }
+
+  protected async getPopularProductsRecommendations(query: ProductRecommendationAlgorithmPopuplarProductsQuery): Promise<ProductRecommendation[]> {
+    return [];
+  }
+
+  protected async getTopPicksProductsRecommendations(query: ProductRecommendationAlgorithmTopPicksProductsQuery): Promise<ProductRecommendation[]> {
+    return [];
+  }
+
+  protected async getAlsoViewedProductsRecommendations(query: ProductRecommendationAlgorithmAlsoViewedProductsQuery): Promise<ProductRecommendation[]> {
+    return [];
+  }
+
+
+  protected override getResourceName(): string {
+    return 'product-recommendations';
+  }
+
+
+}
+
+
+
+export class MulticastProductRecommendationsProvider extends ProductRecommendationsProvider {
+  protected providers: Array<ProductRecommendationsProvider>;
+
+  constructor(
+    cache: Cache,
+    requestContext: RequestContext,
+    providers: Array<ProductRecommendationsProvider>
+  ) {
+    super(cache, requestContext);
+
+    this.providers = providers;
+  }
+
+  @Reactionary({
+    inputSchema: ProductRecommendationsQuerySchema,
+  })
+  public override  async getRecommendations(query: ProductRecommendationsQuery): Promise<Result<ProductRecommendation[]>> {
+    const output = [];
+    for (const provider of this.providers) {
+      const providerOutput = await provider.getRecommendations(query);
+      if (providerOutput.success) {
+
+        output.push(...providerOutput.value);
+      } else {
+        // For other types of errors, we might want to log them or handle them differently
+        console.error(`Error from provider ${provider.constructor.name}:`, providerOutput.error);
+        return providerOutput
+      }
+      if (output.length >= query.numberOfRecommendations) {
+        break;
+      }
+    }
+    return success(output.slice(0, query.numberOfRecommendations));
+  }
+
+  public override async getCollection(query: ProductRecommendationsByCollectionQuery): Promise<Result<ProductRecommendation[]>> {
+    const output = [];
+    for (const provider of this.providers) {
+      const providerOutput = await provider.getCollection(query);
+      if (providerOutput.success) {
+        output.push(...providerOutput.value);
+      } else {
+        if (providerOutput.error.type === 'NotFound') {
+          // If the error is a NotFound error, we can ignore it and continue to the next provider
+          continue;
+        } else {
+          // For other types of errors, we might want to log them or handle them differently
+          console.error(`Error from provider ${provider.constructor.name}:`, providerOutput.error);
+          return providerOutput;
+        }
+      }
+      if (output.length >= query.numberOfRecommendations) {
+        break;
+      }
+    }
+    return success(output.slice(0, query.numberOfRecommendations));
+  }
+
+}

package/core/src/schemas/capabilities.schema.ts

@@ -5,6 +5,8 @@ import type { Client } from '../client/client.js';
 export const CapabilitiesSchema = z.looseObject({
     product: z.boolean(),
     productSearch: z.boolean(),
+    productAssociations: z.boolean(),
+    productRecommendations: z.boolean(),
     analytics: z.boolean(),
     identity: z.boolean(),
     cart: z.boolean(),

package/core/src/schemas/models/identifiers.model.ts

@@ -118,6 +118,11 @@ export const PickupPointIdentifierSchema = z.looseObject({
     key: z.string(),
 });
 
+export const ProductRecommendationIdentifierSchema = z.looseObject({
+    key: z.string(),
+    algorithm: z.string(),
+});
+
 
 export const ProductSearchIdentifierSchema = z.looseObject({
   term: z.string().describe('The search term used to find products.'),
@@ -141,6 +146,7 @@ export const OrderSearchIdentifierSchema = z.looseObject({
   paginationOptions: PaginationOptionsSchema.describe('Pagination options for the search results.'),
 });
 
+
 export type OrderSearchIdentifier = InferType<typeof OrderSearchIdentifierSchema>;
 export type ProductIdentifier = InferType<typeof ProductIdentifierSchema>;
 export type ProductVariantIdentifier = InferType<typeof ProductVariantIdentifierSchema>;
@@ -178,6 +184,7 @@ export type ProductOptionIdentifier = InferType<typeof ProductOptionIdentifierSc
 export type ProductOptionValueIdentifier = InferType<typeof ProductOptionValueIdentifierSchema>;
 export type ProductAttributeIdentifier = InferType<typeof ProductAttributeIdentifierSchema>;
 export type ProductAttributeValueIdentifier = InferType<typeof ProductAttributeValueIdentifierSchema>;
+export type ProductRecommendationIdentifier = InferType<typeof ProductRecommendationIdentifierSchema>;
 
 export type IdentifierType =
   | ProductIdentifier
@@ -191,6 +198,7 @@ export type IdentifierType =
   | CategoryIdentifier
   | WebStoreIdentifier
   | InventoryIdentifier
+  | ProductRecommendationIdentifier
   | FulfillmentCenterIdentifier
   | IdentityIdentifier
   | ShippingMethodIdentifier

package/core/src/schemas/models/index.ts

@@ -18,3 +18,4 @@ export * from './cost.model.js';
 export * from './checkout.model.js';
 export * from './payment.model.js';
 export * from './order-search.model.js'
+export * from './product-recommendations.model.js';

package/core/src/schemas/models/product-recommendations.model.ts

@@ -0,0 +1,10 @@
+import z from "zod";
+import { ProductIdentifierSchema, ProductRecommendationIdentifierSchema, ProductVariantIdentifierSchema } from "./identifiers.model.js";
+
+export const ProductRecommendationSchema = z.looseObject({
+    recommendationIdentifier: ProductRecommendationIdentifierSchema.describe('The identifier for the product recommendation, which includes a key and an algorithm and any other vendor specific/instance specific data '),
+    product: ProductIdentifierSchema.describe('The identifier for the recommended product.'),
+});
+
+
+export type ProductRecommendation = z.infer<typeof ProductRecommendationSchema>;

package/core/src/schemas/queries/index.ts

@@ -12,3 +12,5 @@ export * from './store.query.js';
 export * from './order.query.js';
 export * from './checkout.query.js';
 export * from './order-search.query.js'
+export * from './product-recommendations.query.js';
+export * from './product-associations.query.js';

package/core/src/schemas/queries/product-associations.query.ts

@@ -0,0 +1,23 @@
+import z from "zod";
+import { BaseQuerySchema } from "./base.query.js";
+import { ProductIdentifierSchema, ProductVariantIdentifierSchema } from "../models/identifiers.model.js";
+import { CartItemSchema } from "../models/cart.model.js";
+
+export const ProductAssociationsGetAccessoriesQuerySchema = BaseQuerySchema.extend({
+  forProductVariant: ProductVariantIdentifierSchema.describe('The product variant identifier for which to get accessory recommendations. The provider should return recommendations that are relevant to this product, e.g., products that are frequently bought together, products that are similar in style or category, or products that are popular among users with similar preferences.'),
+  numberOfAccessories: z.number().min(1).max(12).describe('The number of accessory recommendations requested. The provider may return fewer than this number, but should not return more.'),
+});
+
+export const ProductAssociationsGetSparepartsQuerySchema = BaseQuerySchema.extend({
+  forProductVariant: ProductVariantIdentifierSchema.describe('The product variant identifier for which to get similar item recommendations. The provider should return recommendations that are relevant to this product, e.g., products that are frequently bought together, products that are similar in style or category, or products that are popular among users with similar preferences.'),
+});
+
+export const ProductAssociationsGetReplacementsQuerySchema = BaseQuerySchema.extend({
+  forProductVariant: ProductVariantIdentifierSchema.describe('The product variant identifier for which to get replacement recommendations. The provider should return recommendations that are relevant to this product, e.g., products that are frequently bought together, products that are similar in style or category, or products that are popular among users with similar preferences.'),
+});
+
+
+
+export type ProductAssociationsGetAccessoriesQuery = z.infer<typeof ProductAssociationsGetAccessoriesQuerySchema>;
+export type ProductAssociationsGetSparepartsQuery = z.infer<typeof ProductAssociationsGetSparepartsQuerySchema>;
+export type ProductAssociationsGetReplacementsQuery = z.infer<typeof ProductAssociationsGetReplacementsQuerySchema>;

package/core/src/schemas/queries/product-recommendations.query.ts

@@ -0,0 +1,72 @@
+import z from "zod";
+import type { InferType } from "../../zod-utils.js";
+import { CategoryIdentifierSchema, ProductIdentifierSchema } from "../models/identifiers.model.js";
+import { BaseQuerySchema } from "./base.query.js";
+
+export const ProductRecommendationBaseQuerySchema = BaseQuerySchema.extend({
+  numberOfRecommendations: z.number().min(1).max(12).describe('The number of recommendations requested. The provider may return fewer than this number, but should not return more.'),
+  labels: z.array(z.string()).optional().describe('The customer segments, quirks, chirps or other labels to which the recommendations can optimize themselves to be relevant. This can be used by the provider to personalize the recommendations based on the preferences and behaviors of users in these segments.'),
+});
+
+export const ProductRecommendationsByCollectionQuerySchema = ProductRecommendationBaseQuerySchema.extend({
+  collectionName: z.string().describe('The name of the collection for which to get product recommendations. This is to access either manually curated lists, or interface marketing rules engines that define zones by name'),
+  sourceProduct: z.array(ProductIdentifierSchema).optional().describe('The products on screen or in the context you are asking for the recommendations. Could be all the variants from the current cart (resolved into their products), or just the variant of the PDP, or the 4 first products of a category.'),
+  sourceCategory: CategoryIdentifierSchema.optional().describe('The category identifier to use as a seed for the recommendations. The provider should return recommendations that are relevant to this category, e.g., products that are frequently bought together, products that are similar in style or category, or products that are popular among users with similar preferences. This is optional, as the collection may already be curated to be relevant to a specific product or category, but it can be used by the provider to further personalize the recommendations based on the preferences and behaviors of users who have interacted with this category.'),
+});
+
+export const ProductRecommendationProductBasedBaseQuerySchema = ProductRecommendationBaseQuerySchema.extend({
+  sourceProduct: ProductIdentifierSchema.describe('The product identifiers for which to get recommendations. The provider should return recommendations that are relevant to these products, e.g., products that are frequently bought together, products that are similar in style or category, or products that are popular among users with similar preferences.'),
+});
+
+export const ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuerySchema = ProductRecommendationProductBasedBaseQuerySchema.extend({
+  algorithm: z.literal('frequentlyBoughtTogether').describe('The provider should return recommendations based on products that are frequently bought together with the source products. The provider should leverage the Request Context to personalize the recommendations as much as possible, taking into account factors such as the user\'s browsing history, purchase history, and demographic information.'),
+});
+
+export const ProductRecommendationAlgorithmSimilarProductsQuerySchema = ProductRecommendationProductBasedBaseQuerySchema.extend({
+  algorithm: z.literal('similar').describe('The provider should return recommendations based on products that are similar to the source products either visually or data wise'),
+});
+
+export const ProductRecommendationAlgorithmRelatedProductsQuerySchema = ProductRecommendationProductBasedBaseQuerySchema.extend({
+  algorithm: z.literal('related').describe('The provider should return recommendations based on products that are related to the source products. '),
+});
+
+export const ProductRecommendationAlgorithmTrendingInCategoryQuerySchema = ProductRecommendationBaseQuerySchema.extend({
+  algorithm: z.literal('trendingInCategory').describe('The provider should return recommendations based on products that are trending in the specified category. The provider should leverage the Request Context to personalize the recommendations as much as possible, taking into account factors such as the user\'s browsing history, purchase history, and demographic information.'),
+  sourceCategory: CategoryIdentifierSchema.describe('The category identifier for which to get trending product recommendations. The provider should return recommendations that are relevant to this category, e.g., products that are frequently bought together, products that are similar in style or category, or products that are popular among users with similar preferences.'),
+});
+
+
+// unsure if we need both Popular and TopPicks, as they are quite similar. Maybe we can merge them into one algorithm with a parameter to specify the type of popularity? For now, I'll keep them separate for clarity.
+export const ProductRecommendationAlgorithmPopuplarProductsQuerySchema = ProductRecommendationBaseQuerySchema.extend({
+  algorithm: z.literal('popular').describe('The provider should return recommendations based on products that are popular among users. The provider should leverage the Request Context to personalize the recommendations as much as possible, taking into account factors such as the user\'s browsing history, purchase history, and demographic information.'),
+});
+
+export const ProductRecommendationAlgorithmTopPicksProductsQuerySchema = ProductRecommendationBaseQuerySchema.extend({
+  algorithm: z.literal('topPicks').describe('The provider should return recommendations based on products that are top picks among users. The provider should leverage the Request Context to personalize the recommendations as much as possible, taking into account factors such as the user\'s browsing history, purchase history, and demographic information.') ,
+});
+
+export const ProductRecommendationAlgorithmAlsoViewedProductsQuerySchema = ProductRecommendationProductBasedBaseQuerySchema.extend({
+  algorithm: z.literal('alsoViewed').describe('The provider should return recommendations based on products that are also viewed by users. The provider should leverage the Request Context to personalize the recommendations as much as possible, taking into account factors such as the user\'s browsing history, purchase history, and demographic information.') ,
+});
+
+
+
+export const ProductRecommendationsQuerySchema = z.discriminatedUnion('algorithm', [
+  ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuerySchema,
+  ProductRecommendationAlgorithmTrendingInCategoryQuerySchema,
+  ProductRecommendationAlgorithmSimilarProductsQuerySchema,
+  ProductRecommendationAlgorithmRelatedProductsQuerySchema,
+  ProductRecommendationAlgorithmPopuplarProductsQuerySchema,
+  ProductRecommendationAlgorithmTopPicksProductsQuerySchema,
+  ProductRecommendationAlgorithmAlsoViewedProductsQuerySchema
+]);
+
+export type ProductRecommendationsQuery = InferType<typeof ProductRecommendationsQuerySchema>;
+export type ProductRecommendationsByCollectionQuery = InferType<typeof ProductRecommendationsByCollectionQuerySchema>;
+export type ProductRecommendationAlgorithmTopPicksProductsQuery = InferType<typeof ProductRecommendationAlgorithmTopPicksProductsQuerySchema>;
+export type ProductRecommendationAlgorithmPopuplarProductsQuery = InferType<typeof ProductRecommendationAlgorithmPopuplarProductsQuerySchema>;
+export type ProductRecommendationAlgorithmTrendingInCategoryQuery = InferType<typeof ProductRecommendationAlgorithmTrendingInCategoryQuerySchema>;
+export type ProductRecommendationAlgorithmRelatedProductsQuery = InferType<typeof ProductRecommendationAlgorithmRelatedProductsQuerySchema>;
+export type ProductRecommendationAlgorithmSimilarProductsQuery= InferType<typeof ProductRecommendationAlgorithmSimilarProductsQuerySchema>;
+export type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery = InferType<typeof ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuerySchema>;
+export type ProductRecommendationAlgorithmAlsoViewedProductsQuery = InferType<typeof ProductRecommendationAlgorithmAlsoViewedProductsQuerySchema>;

package/documentation/docs/7-marketing.md

@@ -1,3 +1,98 @@
 # Adding the personal touch
 
+Reactionary supports many mechanisms by which to make the customer journey unique to a customer. The main mechanism is via the `ProductRecommendationsProvider` which offers 7 unique ways to find some relevant products to display for the user.
+
+It is assumed, that any basic-direct-assign logic (ie editor has picked 4 products to show) is already handled at the CMS level. The Reactionary provider is for the usecase where you want a dynamic result back, based on the users behavior, tags, or whatever you have.
+
+The supported algorithms are
+
+```
+- Frequently-Bought-Together (Product based)
+- Trending-In-Category (Category based)
+- Similar (Product)
+- Related-Items (Product)
+- Popular-Products (User)
+- Top-Picks-For-You (User)
+- Also-Viewed (Product, User)
+```
+
+Reactionary supports having multiple providers of product recommendations, each of which will be asked in order, until the result is fully populated. 
+Every provider might not support every algorithm though.
+
+But, the point of this is, that you can either hardcode something on the PDP
+
+```ts
+const recommendations = client.productRecommendations.getRecommendations({
+  algorithm: 'similar',
+  numberOfRecommendations: 8,
+  labels: [ 
+    (
+      isLoggedIn: 'Registered' : 'Guest',
+      registeredThisSession? 'FirstSession': 'ReturningCustomer', 
+      customerSegments.map(x => x.name), 
+      new Date().getHour() > 12? "Afternoon": "Morning",
+      getTemperatureAround(context.clientIp) < 20: 'Cold': 'Warm' 
+    )
+  ]
+});
+
+if (recommendations.success)  {
+  // we can now resolve them
+const allProducts = Promise.all(
+    recommendations.value.products.map(x => client.product.getByID(x)).map(x => x.successs? x.value : null )).filter(y => !!y);
+  // and draw them...
+}
+```
+
+Instead of using the full `client.product` you could have resolved it via the `.productSearch` to get a smaller data-footprint. However, since you are hopefully just about to navigate to one of these pages, it might be better for overall cache performance to use the full data model.
+
+
+
+
+## Collections
+
+Some systems offer named access to a potentially rules based selection of products. An example is the HCL Commerce espot system, where your frontpage migth have a spot called "Newest arrivals", and behind the scenes some rules engine decides what to show there.
+
+It can also be simply the name of a CMS entity, or other system specific functionality.
+
+You can call that as well here:
+
+```ts
+const recommendations = client.productRecommendations.getCollection({
+  collectionName: 'newest-arrivals',
+  numberOfRecommendations: 8,
+  labels: [ 
+    (
+      isLoggedIn: 'Registered' : 'Guest',
+      registeredThisSession? 'FirstSession': 'ReturningCustomer', 
+      customerSegments.map(x => x.name), 
+      new Date().getHour() > 12? "Afternoon": "Morning",
+      getTemperatureAround(context.clientIp) < 20: 'Cold': 'Warm' 
+    )
+  ]
+});
+
+if (recommendations.success)  {
+  // we can now resolve them
+const allProducts = Promise.all(
+    recommendations.value.products.map(x => client.product.getByID(x)).map(x => x.successs? x.value : null )).filter(y => !!y);
+  // and draw them...
+}
+```
+
+### Configuration
+Since not every system can provide every recommendation algorithm, Reactionary supports enabling this capability on multiple providers.
+
+So if you have both algolia and medusa, you can set `productRecommendations: true` on both, and the system will then ask each system in turn until the required number of results have been gathered.
+
+
+
+## Design decisions
+Since not all systems can deliver full product data back, we are initially only returning the IDs of the products, so you have to use the `product` provider to resolve it into something displayable.
+
+Later, we might add a discriminator, allowing the same bare-bones/tile-ready data to be returned from this, as is returned from the product search.
+
+It was also decided to have the source and target unit be a product (Forest Ranger T-Shirt), and not the individual sku (Forest Ranger T-Shirt, Yellow, Size-32).
+
+This is from emperical studies showign that you will get more results from the toplevel product, than from a rarely used SKU.
 

package/examples/node/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@reactionary/examples-node",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "main": "index.js",
   "types": "src/index.d.ts",
   "dependencies": {
-    "@reactionary/core": "0.3.2",
-    "@reactionary/provider-commercetools": "0.3.2",
-    "@reactionary/provider-algolia": "0.3.2",
-    "@reactionary/provider-medusa": "0.3.2",
-    "@reactionary/provider-meilisearch": "0.3.2"
+    "@reactionary/core": "0.3.3",
+    "@reactionary/provider-commercetools": "0.3.3",
+    "@reactionary/provider-algolia": "0.3.3",
+    "@reactionary/provider-medusa": "0.3.3",
+    "@reactionary/provider-meilisearch": "0.3.3"
   },
   "type": "module"
 }

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.2",
+  "version": "0.3.3",
   "license": "MIT",
   "private": false,
   "dependencies": {

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,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/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';

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

@@ -0,0 +1,89 @@
+import {
+  type Cache,
+  ProductRecommendationsProvider,
+  type ProductRecommendation,
+  type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery,
+  type ProductRecommendationAlgorithmSimilarProductsQuery,
+  type ProductRecommendationAlgorithmRelatedProductsQuery,
+  type ProductRecommendationAlgorithmTrendingInCategoryQuery,
+  type RequestContext,
+} from '@reactionary/core';
+import { MeiliSearch, type Hits, type RecordAny, type SearchParams, type SearchResponse } from 'meilisearch';
+import type { MeilisearchConfiguration } from '../schema/configuration.schema.js';
+
+interface MeilisearchRecommendHit {
+  id: string;
+}
+
+/**
+ * MeilisearchProductRecommendationsProvider
+ *
+ * Provides product recommendations using Meilisearch's hybrid search and filtering capabilities.
+ * Supports frequentlyBoughtTogether, similar, related, and trendingInCategory algorithms.
+ *
+ * Note: This implementation uses semantic search (if AI embedding is enabled) and facet-based filtering.
+ * For production use, consider implementing more sophisticated recommendation logic or integrating
+ * with a dedicated recommendation engine.
+ */
+export class MeilisearchProductRecommendationsProvider extends ProductRecommendationsProvider {
+  protected config: MeilisearchConfiguration;
+
+  constructor(config: MeilisearchConfiguration, cache: Cache, context: RequestContext) {
+    super(cache, context);
+    this.config = config;
+  }
+
+  /**
+   * Get similar product recommendations
+   * Uses semantic search to find visually or data-wise similar products
+   */
+  protected override async getSimilarProductsRecommendations(
+    query: ProductRecommendationAlgorithmSimilarProductsQuery
+  ): Promise<ProductRecommendation[]> {
+    const client = new MeiliSearch({
+      host: this.config.apiUrl,
+      apiKey: this.config.apiKey,
+    });
+
+    const index = client.index(this.config.indexName);
+
+    if (!this.config.useAIEmbedding) {
+      console.warn('AI embedding is not enabled in configuration. Similar product recommendations will be based on keyword matching, which may not provide optimal results.');
+      return [];
+    }
+
+    try {
+      const searchOptions: SearchParams = {
+        limit: query.numberOfRecommendations,
+      };
+
+      const response = await index.searchSimilarDocuments<MeilisearchRecommendHit>({
+        id: query.sourceProduct.key,
+        limit: query.numberOfRecommendations,
+        embedder: this.config.useAIEmbedding,
+      });
+
+
+      return this.parseRecommendations(response, 'similar');
+    } catch (error) {
+      console.error('Error fetching similar product recommendations:', error);
+      return [];
+    }
+  }
+
+
+  /**
+   * Maps Meilisearch search results to ProductRecommendation format
+   */
+  protected parseRecommendations(recommendation: SearchResponse<MeilisearchRecommendHit>, algorithm: string): ProductRecommendation[] {
+    return recommendation.hits.map((hit) => ({
+      recommendationIdentifier: {
+        key: hit.id,
+        algorithm,
+      },
+      product: {
+        key: hit.id,
+      },
+    }));
+  }
+}

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

@@ -3,6 +3,7 @@ import type { z } from 'zod';
 
 export const MeilisearchCapabilitiesSchema = CapabilitiesSchema.pick({
     productSearch: true,
+    productRecommendations: true,
     orderSearch: true,
     analytics: true
 }).partial();