@reactionary/source 0.3.1 → 0.3.3

package/providers/algolia/src/test/analytics.spec.ts

@@ -0,0 +1,138 @@
+import { describe, it, assert } from 'vitest';
+import { AlgoliaAnalyticsProvider } from '../providers/analytics.provider.js';
+import { createInitialRequestContext, NoOpCache } from '@reactionary/core';
+import type { AlgoliaConfiguration } from '../schema/configuration.schema.js';
+import { AlgoliaProductSearchProvider } from '../providers/product-search.provider.js';
+
+describe('Analytics event tracking', async () => {
+  const config = {
+    apiKey: process.env['ALGOLIA_API_KEY'] || '',
+    appId: process.env['ALGOLIA_APP_ID'] || '',
+    indexName: process.env['ALGOLIA_INDEX'] || '',
+  } satisfies AlgoliaConfiguration;
+  const cache = new NoOpCache();
+  const context = createInitialRequestContext();
+
+  const search = new AlgoliaProductSearchProvider(cache, context, config);
+  const analytics = new AlgoliaAnalyticsProvider(cache, context, config);
+  const searchResult = await search.queryByTerm({
+    search: {
+      facets: [],
+      filters: [],
+      paginationOptions: {
+        pageNumber: 1,
+        pageSize: 10,
+      },
+      term: 'q',
+    },
+  });
+
+  if (!searchResult.success) {
+    assert.fail();
+  }
+
+  it('can track summary clicks', async () => {
+    await analytics.track({
+      event: 'product-summary-click',
+      product: searchResult.value.items[0].identifier,
+      position: 1,
+      source: {
+        type: 'search',
+        identifier: searchResult.value.identifier,
+      },
+    });
+  });
+
+  it('can track summary views', async () => {
+    await analytics.track({
+      event: 'product-summary-view',
+      products: searchResult.value.items.map((x) => x.identifier),
+      source: {
+        type: 'search',
+        identifier: searchResult.value.identifier,
+      },
+    });
+  });
+
+  it('can track add to cart', async () => {
+    await analytics.track({
+      event: 'product-cart-add',
+      product: searchResult.value.items[0].identifier,
+      source: {
+        type: 'search',
+        identifier: searchResult.value.identifier,
+      },
+    });
+  });
+
+  it('can track purchase', async () => {
+    await analytics.track({
+      event: 'purchase',
+      order: {
+        identifier: {
+          key: crypto.randomUUID(),
+        },
+        inventoryStatus: 'Allocated',
+        items: [
+          {
+            identifier: {
+              key: crypto.randomUUID(),
+            },
+            inventoryStatus: 'Allocated',
+            price: {
+              unitPrice: {
+                currency: 'USD',
+                value: 50,
+              },
+              totalDiscount: {
+                currency: 'USD',
+                value: 0,
+              },
+              totalPrice: {
+                currency: 'USD',
+                value: 50,
+              },
+              unitDiscount: {
+                currency: 'USD',
+                value: 0,
+              },
+            },
+            quantity: 1,
+            variant: searchResult.value.items[0].variants[0].variant,
+          },
+        ],
+        orderStatus: 'Shipped',
+        paymentInstructions: [],
+        price: {
+          grandTotal: {
+            currency: 'USD',
+            value: 50,
+          },
+          totalDiscount: {
+            currency: 'USD',
+            value: 0,
+          },
+          totalProductPrice: {
+            currency: 'USD',
+            value: 50,
+          },
+          totalShipping: {
+            currency: 'USD',
+            value: 0,
+          },
+          totalSurcharge: {
+            currency: 'USD',
+            value: 0,
+          },
+          totalTax: {
+            currency: 'USD',
+            value: 0,
+          },
+        },
+        userId: {
+            userId: crypto.randomUUID()
+        }
+      },
+    });
+  });
+});

package/providers/commercetools/src/providers/identity.provider.ts

@@ -15,7 +15,6 @@ import {
   success,
 } from '@reactionary/core';
 import type { CommercetoolsConfiguration } from '../schema/configuration.schema.js';
-import type z from 'zod';
 import type { CommercetoolsAPI } from '../core/client.js';
 
 export class CommercetoolsIdentityProvider extends IdentityProvider {
@@ -41,6 +40,8 @@ export class CommercetoolsIdentityProvider extends IdentityProvider {
   public override async getSelf(payload: IdentityQuerySelf): Promise<Result<Identity>> {
     const identity = await this.commercetools.introspect();
 
+    this.updateIdentityContext(identity);
+
     return success(identity);
   }
 
@@ -54,6 +55,8 @@ export class CommercetoolsIdentityProvider extends IdentityProvider {
       payload.password
     );
 
+    this.updateIdentityContext(identity);
+
     return success(identity);
   }
 
@@ -63,6 +66,8 @@ export class CommercetoolsIdentityProvider extends IdentityProvider {
   public override async logout(payload: Record<string, never>): Promise<Result<Identity>> {
     const identity = await this.commercetools.logout();
 
+    this.updateIdentityContext(identity);
+
     return success(identity);
   }
 
@@ -78,6 +83,8 @@ export class CommercetoolsIdentityProvider extends IdentityProvider {
       payload.password
     );
 
+    this.updateIdentityContext(identity);
+
     return success(identity);
   }
 }

package/providers/commercetools/src/test/caching.spec.ts

@@ -8,7 +8,7 @@ import {
   type ProductSearchQueryByTerm,
 } from '@reactionary/core';
 import { CommercetoolsProductProvider } from '../providers/product.provider.js';
-import { CommercetoolsClient } from '../core/client.js';
+import { CommercetoolsAPI } from '../core/client.js';
 import { CommercetoolsSearchProvider } from '../providers/product-search.provider.js';
 
 describe('Caching', () => {
@@ -16,7 +16,7 @@ describe('Caching', () => {
     const config = getCommercetoolsTestConfiguration();
     const context = createInitialRequestContext();
     const cache = new MemoryCache();
-    const client = new CommercetoolsClient(config, context);
+    const client = new CommercetoolsAPI(config, context);
     const provider = new CommercetoolsProductProvider(config, cache, context, client);
 
     const identifier = {
@@ -48,7 +48,7 @@ describe('Caching', () => {
     const config = getCommercetoolsTestConfiguration();
     const context = createInitialRequestContext();
     const cache = new MemoryCache();
-    const client = new CommercetoolsClient(config, context);
+    const client = new CommercetoolsAPI(config, context);
     const provider = new CommercetoolsSearchProvider(config, cache, context, client);
 
     const query = {

package/providers/commercetools/src/test/identity.spec.ts

@@ -1,6 +1,6 @@
 import 'dotenv/config';
 import { describe, expect, it } from 'vitest';
-import { CommercetoolsClient } from '../core/client.js';
+import { CommercetoolsAPI } from '../core/client.js';
 import { getCommercetoolsTestConfiguration } from './test-utils.js';
 import {
   createInitialRequestContext,
@@ -12,7 +12,7 @@ import type { CommercetoolsConfiguration } from '../schema/configuration.schema.
 function setup() {
   const config = getCommercetoolsTestConfiguration();
   const context = createInitialRequestContext();
-  const root = new CommercetoolsClient(config, context);
+  const root = new CommercetoolsAPI(config, context);
 
   return {
     config,

package/providers/google-analytics/package.json

@@ -7,12 +7,6 @@
     "@reactionary/core": "0.0.1",
     "zod": "4.1.9"
   },
-  "devDependencies": {
-    "vitest": "*",
-    "@vitest/ui": "*",
-    "@vitest/coverage-v8": "*",
-    "vite-tsconfig-paths": "*"
-  },
   "type": "module",
   "sideEffects": false
 }

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/identity.provider.ts

@@ -19,7 +19,6 @@ import {
   success,
 } from '@reactionary/core';
 import type { MedusaConfiguration } from '../schema/configuration.schema.js';
-import type z from 'zod';
 import type { MedusaAPI } from '../core/client.js';
 import createDebug from 'debug';
 
@@ -60,7 +59,10 @@ export class MedusaIdentityProvider extends IdentityProvider {
 
       if (!token) {
         debug('No active session token found, returning anonymous identity');
-        return success(this.createAnonymousIdentity());
+        const identity = this.createAnonymousIdentity();
+        this.updateIdentityContext(identity);
+
+        return success(identity);
       }
 
       // Try to fetch customer details to verify authentication
@@ -68,18 +70,30 @@ export class MedusaIdentityProvider extends IdentityProvider {
 
       if (customerResponse.customer) {
         debug('Customer authenticated:', customerResponse.customer.email);
-        return success({
+
+        const identity = {
           id: {
             userId: customerResponse.customer.id,
           },
           type: 'Registered',
-        } satisfies RegisteredIdentity);
+        } satisfies RegisteredIdentity;
+
+        this.updateIdentityContext(identity);
+
+        return success(identity);
       }
 
-      return success(this.createAnonymousIdentity());
+      const identity = this.createAnonymousIdentity();
+      this.updateIdentityContext(identity);
+
+      return success(identity);
     } catch (error) {
       debug('getSelf failed, returning anonymous identity:', error);
-      return success(this.createAnonymousIdentity());
+
+      const identity = this.createAnonymousIdentity();
+      this.updateIdentityContext(identity);
+
+      return success(identity);
     }
   }
 
@@ -87,13 +101,17 @@ export class MedusaIdentityProvider extends IdentityProvider {
     inputSchema: IdentityMutationLoginSchema,
     outputSchema: IdentitySchema,
   })
-  public override async login(payload: IdentityMutationLogin): Promise<Result<Identity>> {
+  public override async login(
+    payload: IdentityMutationLogin
+  ): Promise<Result<Identity>> {
     debug('Attempting login for user:', payload.username);
-    const identity = await this.medusaApi.login(
+    const identity = (await this.medusaApi.login(
       payload.username,
       payload.password,
       this.context
-    ) satisfies Identity;
+    )) satisfies Identity;
+
+    this.updateIdentityContext(identity);
 
     return success(identity);
   }
@@ -102,10 +120,14 @@ export class MedusaIdentityProvider extends IdentityProvider {
     inputSchema: IdentityMutationLogoutSchema,
     outputSchema: IdentitySchema,
   })
-  public override async logout(_payload: IdentityMutationLogout): Promise<Result<Identity>> {
+  public override async logout(
+    _payload: IdentityMutationLogout
+  ): Promise<Result<Identity>> {
     debug('Logging out user');
     const identity = await this.medusaApi.logout(this.context);
 
+    this.updateIdentityContext(identity);
+
     return success(identity);
   }
 
@@ -132,6 +154,8 @@ export class MedusaIdentityProvider extends IdentityProvider {
       this.context
     );
 
+    this.updateIdentityContext(identity);
+
     return success(identity);
   }
 }

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