@reactionary/source 0.3.1 → 0.3.2

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/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/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.2",
   "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.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"
   },
   "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);
   });
 });

package/package.json

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

package/providers/algolia/README.md

@@ -38,11 +38,19 @@ You can have more, for use with facets, and additional searchable fields, but th
 
 The `objectID` corrosponds to your productIdentifier, and `variantID` should match your SKU
 
+## Analytics
 
-## Building
+The Algolia analytics provider maps the following tracked event types to data tracked in Algolia:
 
-Run `nx build provider-algolia` to build the library.
+- AnalyticsMutationProductSummaryViewEvent => ViewedObjectIDs
+- AnalyticsMutationProductSummaryClickEvent => ClickedObjectIDsAfterSearch / ClickedObjectIDs
+- AnalyticsMutationProductAddToCartEvent => AddedToCartObjectIDsAfterSearch / AddedToCartObjectIDs
+- AnalyticsMutationPurchaseEvent => PurchasedObjectIDs
 
-## Running unit tests
+The `AfterSearch` variants are (with the exception of purchase) preferred by the provider in the cases where Algolia is the source of the events. For search or recommendation this would typically be the case, but not necesarily for users arriving on a PDP as a direct target from a search or a link.
 
-Run `nx test provider-algolia` to execute the unit tests via [Jest](https://jestjs.io).
+Note that we do not map `PurchasedObjectIDsAfterSearch` as it would require us to persist the search query ID that lead to the add-to-cart occuring on the cart items. This currently seems like an excess burden to impose on the cart interface. 
+
+The `ConvertedObjectIDs` and `ConvertedObjectIDsAfterSearch` are not mapped as they seem superfluous by all accounts in a product-purchase based flow. They could likely be used for other types of conversions in a more general setup, such as a customer finishing reading an article.
+
+Finally the events that are related to filtering are not mapped, as they are by all accounts deprecated and no longer influence any of the recommendation or personalization features.

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

@@ -1,5 +1,5 @@
 import type { Cache, ClientFromCapabilities, RequestContext } from "@reactionary/core";
-import { AlgoliaSearchProvider } from "../providers/product-search.provider.js";
+import { AlgoliaProductSearchProvider } from "../providers/product-search.provider.js";
 import type { AlgoliaCapabilities } from "../schema/capabilities.schema.js";
 import type { AlgoliaConfiguration } from "../schema/configuration.schema.js";
 import { AlgoliaAnalyticsProvider } from "../providers/analytics.provider.js";
@@ -9,7 +9,7 @@ export function withAlgoliaCapabilities<T extends AlgoliaCapabilities>(configura
         const client: any = {};
 
         if (capabilities.productSearch) {
-            client.productSearch = new AlgoliaSearchProvider(configuration, cache, context);
+            client.productSearch = new AlgoliaProductSearchProvider(cache, context, configuration);
         }
 
         if (capabilities.analytics) {

package/providers/algolia/src/providers/analytics.provider.ts

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

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

@@ -40,10 +40,10 @@ interface AlgoliaNativeRecord {
 }
 
 
-export class AlgoliaSearchProvider extends ProductSearchProvider {
+export class AlgoliaProductSearchProvider extends ProductSearchProvider {
   protected config: AlgoliaConfiguration;
 
-  constructor(config: AlgoliaConfiguration, cache: Cache, context: RequestContext) {
+  constructor(cache: Cache, context: RequestContext, config: AlgoliaConfiguration) {
     super(cache, context);
     this.config = config;
   }
@@ -195,7 +195,8 @@ export class AlgoliaSearchProvider extends ProductSearchProvider {
         facets: query.search.facets,
         filters: query.search.filters,
         paginationOptions: query.search.paginationOptions,
-
+        index: body.index || '',
+        key: body.queryID || '',
       },
       pageNumber: (body.page || 0) + 1,
       pageSize: body.hitsPerPage || 0,
@@ -203,7 +204,7 @@ export class AlgoliaSearchProvider extends ProductSearchProvider {
       totalPages: body.nbPages || 0,
       items: items,
       facets,
-    } satisfies ProductSearchResult;
+    } satisfies AlgoliaProductSearchResult;
 
     return result;
   }

package/providers/algolia/src/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/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);
   }
 }