@reactionary/source 0.3.1 → 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/initialization.ts

@@ -1,3 +1,4 @@
+import type { AnonymousIdentity } from './schemas/index.js';
 import type { RequestContext } from './schemas/session.schema.js';
 
 export function createInitialRequestContext(): RequestContext {
@@ -17,7 +18,9 @@ export function createInitialRequestContext(): RequestContext {
     },
     session: {
       identityContext: {
-        identifier: { userId: '' },
+        identity: {
+          type: 'Anonymous'
+        } satisfies AnonymousIdentity,
         lastUpdated: new Date(),
         personalizationKey: crypto.randomUUID(),
       },

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

@@ -13,4 +13,9 @@ export abstract class IdentityProvider extends BaseProvider {
   protected override getResourceName(): string {
     return 'identity';
   }
+
+  protected updateIdentityContext(identity: Identity) {
+    this.context.session.identityContext.lastUpdated = new Date();
+    this.context.session.identityContext.identity = identity;
+  }
 }

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/core/src/schemas/session.schema.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { IdentityIdentifierSchema, WebStoreIdentifierSchema } from './models/identifiers.model.js';
 import { CurrencySchema } from './models/currency.model.js';
+import { IdentitySchema } from './models/identity.model.js';
 
 /**
  * The language and locale context for the current request.
@@ -11,7 +12,7 @@ export const LanguageContextSchema = z.looseObject( {
 });
 
 export const IdentityContextSchema = z.looseObject({
-    identifier: IdentityIdentifierSchema,
+    identity: IdentitySchema,
     personalizationKey: z.string(),
     lastUpdated: z.date()
 });

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/documentation/docs/8-tracking.md

@@ -6,4 +6,4 @@ Reactionary takes the approach that tracking customer data should be structured
 - Structure: it should be possible to reason about what is tracked on the site, how it is tracked and when it is tracked without having to visit seven different tag managers.
 - Security: pulling in all the embedded and inline scripts from every tag manager is a security incident waiting to happen.
 
-To this end the client exposes a single provider in the form of `client.analytics`. This client is internally responsible for delegating events to all relevant subscribers capabilities used to build the client. This means that a single call to record a pageview or attribution will be enough, even if that data internally needs to be multiplexed to GA4, Algolia and Posthog as an example.
+To this end the client exposes a single provider in the form of `client.analytics`. This client is internally responsible for delegating events to all relevant subscribers capabilities used to build the client. This means that a single call to record a pageview or attribution will be enough, even if that data internally needs to be multiplexed to GA4, Algolia and Posthog as an example.

package/examples/node/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@reactionary/examples-node",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "main": "index.js",
   "types": "src/index.d.ts",
   "dependencies": {
-    "@reactionary/core": "0.3.1",
-    "@reactionary/provider-commercetools": "0.3.1",
-    "@reactionary/provider-algolia": "0.3.1",
-    "@reactionary/provider-medusa": "0.3.1",
-    "@reactionary/provider-meilisearch": "0.3.1"
+    "@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/basic/client-creation.spec.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { ClientBuilder, createInitialRequestContext, NoOpCache } from '@reactionary/core';
 import { FakeProductProvider, withFakeCapabilities  } from '@reactionary/provider-fake';
 import { CommercetoolsCartProvider, withCommercetoolsCapabilities } from '@reactionary/provider-commercetools';
-import { AlgoliaSearchProvider, withAlgoliaCapabilities } from '@reactionary/provider-algolia';
+import { AlgoliaProductSearchProvider, withAlgoliaCapabilities } from '@reactionary/provider-algolia';
 
 describe('client creation', () => {
   it('should be able to mix providers and get a valid, typed client', async () => {
@@ -48,6 +48,6 @@ describe('client creation', () => {
 
     expect(client.cart).toBeInstanceOf(CommercetoolsCartProvider);
     expect(client.product).toBeInstanceOf(FakeProductProvider);
-    expect(client.productSearch).toBeInstanceOf(AlgoliaSearchProvider);
+    expect(client.productSearch).toBeInstanceOf(AlgoliaProductSearchProvider);
   });
 });