@reactionary/source 0.3.0 → 0.3.2

package/documentation/docusaurus.config.js

@@ -0,0 +1,33 @@
+const path = require('path');
+
+module.exports = {
+  title: 'My Project',
+  tagline: 'Documentation',
+  url: 'https://your-site.com',
+  baseUrl: '/',
+  onBrokenLinks: 'throw',
+  staticDirectories: [path.resolve(__dirname, 'static')],
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+  markdown: {
+    format: 'md',
+  },
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          path: path.resolve(__dirname, 'docs'),
+          routeBasePath: '/',
+          sidebarPath: path.resolve(__dirname, 'sidebars.js'),
+        },
+        blog: false,
+        theme: {
+          customCss: path.resolve(__dirname, 'src/css/custom.css'),
+        },
+      },
+    ],
+  ],
+};

package/documentation/scripts/generate.ts

@@ -0,0 +1,52 @@
+import { zod2md } from 'zod2md';
+import { writeFileSync } from 'fs';
+import * as td from 'typedoc';
+import type { TypeDocOptions } from 'typedoc';
+import type { PluginOptions as MarkdownPluginOptions } from 'typedoc-plugin-markdown';
+import fs from 'fs/promises';
+import path from 'path';
+
+type TypedocWithMarkdownOptions = TypeDocOptions & MarkdownPluginOptions;
+
+const projects = [
+  {
+    entry: 'core/src/schemas/index.ts',
+    title: 'Schemas',
+    output: 'documentation/docs/schemas/schemas.md',
+  },
+];
+
+async function main() {
+  for (const project of projects) {
+    const markdown = await zod2md({
+      entry: project.entry,
+      title: `${project.title} Schemas`,
+      tsconfig: './core/tsconfig.lib.json',
+    });
+    writeFileSync(project.output, markdown);
+  }
+
+  const typedocConfig = {
+    entryPoints: ['core/src/providers/*.provider.ts'],
+    tsconfig: 'core/tsconfig.lib.json',
+    plugin: ['typedoc-plugin-markdown'],
+    out: 'documentation/docs/providers',
+    outputFileStrategy: 'modules',
+    categorizeByGroup: true,
+    readme: 'none',
+    membersWithOwnFile: [],
+    modulesFileName: undefined,
+  } satisfies TypedocWithMarkdownOptions;
+  const app = await td.Application.bootstrapWithPlugins(typedocConfig);
+
+  const project = await app.convert();
+  if (project) {
+    await app.generateOutputs(project);
+
+    await fs.rm(path.join('documentation/docs/providers', 'README.md'), {
+      force: true,
+    });
+  }
+}
+
+main();

package/documentation/sidebars.js

@@ -0,0 +1,8 @@
+module.exports = {
+  docs: [
+    {
+      type: 'autogenerated',
+      dirName: '.',
+    },
+  ],
+};

package/documentation/src/css/custom.css

@@ -0,0 +1,3 @@
+:root {
+  --ifm-color-primary: #2e8555;
+}

package/documentation/src/pages/index.js

@@ -0,0 +1,12 @@
+import Layout from '@theme/Layout';
+
+export default function Home() {
+  return (
+    <Layout title="Home">
+      <main style={{ padding: '2rem' }}>
+        <h1>Welcome to My Docs</h1>
+        <p>Get started by reading the <a href="/docs/intro">introduction</a>.</p>
+      </main>
+    </Layout>
+  );
+}

package/eslint.config.mjs

@@ -9,7 +9,7 @@ export default [
       '**/dist',
       '**/vite.config.*.timestamp*',
       '**/vitest.config.*.timestamp*',
-      '**/vitest.config.ts'
+      '**/vitest.config.ts',
     ],
   },
   {

package/examples/node/package.json

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

@@ -1,7 +1,5 @@
 import type {
   Cache,
-  ProductQueryById,
-  ProductQueryBySlug,
   RequestContext} from '@reactionary/core';
 import {
   ClientBuilder,

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,11 +1,14 @@
 {
   "name": "@reactionary/source",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "license": "MIT",
   "private": false,
   "dependencies": {
     "@commercetools/platform-sdk": "^8.16.0",
     "@commercetools/ts-client": "^4.2.1",
+    "@commercetools/ts-sdk-apm": "^4.0.0",
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/preset-classic": "^3.9.2",
     "@faker-js/faker": "^9.8.0",
     "@medusajs/js-sdk": "^2.13.0",
     "@opentelemetry/api": "^1.9.0",
@@ -19,7 +22,6 @@
     "meilisearch": "^0.55.0",
     "node-object-hash": "^3.1.1",
     "posthog-node": "^5.24.0",
-    "search-insights": "^2.17.3",
     "zod": "4.1.9"
   },
   "devDependencies": {
@@ -44,15 +46,23 @@
     "@types/debug": "^4.1.12",
     "@types/node": "^24.0.0",
     "@typescript-eslint/utils": "^8.33.1",
+    "@vitest/coverage-v8": "^4.0.0",
+    "docusaurus-plugin-typedoc": "^1.4.2",
+    "esbuild": "^0.19.2",
+    "jsonc-eslint-parser": "^2.1.0",
     "nx": "22.4.5",
-    "prettier": "^2.6.2",
+    "prettier": "~3.6.2",
     "ts-node": "10.9.1",
     "tslib": "^2.3.0",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.33.1",
+    "verdaccio": "^6.0.5",
     "vite": "7.1.9",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^4.0.9"
+    "vitest": "^4.0.9",
+    "zod2md": "^0.2.5"
   },
   "nx": {
     "includedScripts": []
@@ -62,5 +72,9 @@
     "provenance": false
   },
   "packageManager": "pnpm@8.15.9+sha512.499434c9d8fdd1a2794ebf4552b3b25c0a633abcee5bb15e7b5de90f32f47b513aca98cd5cfd001c31f0db454bc3804edccd578501e4ca293a6816166bbd9f81",
-  "scripts": {}
+  "scripts": {
+    "docs:start": "docusaurus start --config documentation/docusaurus.config.js",
+    "docs:build": "docusaurus build --config documentation/docusaurus.config.js",
+    "docs:generate": "node ./documentation/scripts/generate.ts"
+  }
 }

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/project.json

@@ -1,5 +1,5 @@
 {
-  "name": "provider-algolia",
+  "name": "algolia",
   "$schema": "../../node_modules/nx/schemas/project-schema.json",
   "sourceRoot": "providers/algolia/src",
   "projectType": "library",

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

@@ -1,14 +1,19 @@
 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";
 
 export function withAlgoliaCapabilities<T extends AlgoliaCapabilities>(configuration: AlgoliaConfiguration, capabilities: T) {
     return (cache: Cache, context: RequestContext): ClientFromCapabilities<T> => {
         const client: any = {};
 
         if (capabilities.productSearch) {
-            client.productSearch = new AlgoliaSearchProvider(configuration, cache, context);
+            client.productSearch = new AlgoliaProductSearchProvider(cache, context, configuration);
+        }
+
+        if (capabilities.analytics) {
+            client.analytics = new AlgoliaAnalyticsProvider(cache, context, configuration);
         }
 
         return client;

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

@@ -0,0 +1,114 @@
+import {
+  AnalyticsProvider,
+  type AnalyticsMutationProductAddToCartEvent,
+  type AnalyticsMutationProductSummaryClickEvent,
+  type AnalyticsMutationProductSummaryViewEvent,
+  type AnalyticsMutationPurchaseEvent,
+  type Cache,
+  type RequestContext,
+} from '@reactionary/core';
+import {
+  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';
+
+export class AlgoliaAnalyticsProvider extends AnalyticsProvider {
+  protected client: InsightsClient;
+  protected config: AlgoliaConfiguration;
+
+  constructor(
+    cache: Cache,
+    requestContext: RequestContext,
+    config: AlgoliaConfiguration
+  ) {
+    super(cache, requestContext);
+
+    this.config = config;
+    this.client = algoliasearch(this.config.appId, this.config.apiKey).initInsights({});
+  }
+
+  protected override async processProductAddToCart(
+    event: AnalyticsMutationProductAddToCartEvent
+  ) {
+    if (event.source && event.source.type === 'search') {
+      const algoliaEvent = {
+        eventName: 'addToCart',
+        eventType: 'conversion',
+        eventSubtype: 'addToCart',
+        index: this.config.indexName,
+        objectIDs: [event.product.key],
+        userToken: this.context.session.identityContext.personalizationKey,
+        queryID: (event.source.identifier as AlgoliaProductSearchIdentifier)
+          .key,
+      } satisfies AddedToCartObjectIDsAfterSearch;
+
+      const response = await this.client.pushEvents({
+        events: [algoliaEvent],
+      });
+    }
+  }
+
+  protected override async processProductSummaryClick(
+    event: AnalyticsMutationProductSummaryClickEvent
+  ) {
+    if (event.source && event.source.type === 'search') {
+      const algoliaEvent = {
+        eventName: 'click',
+        eventType: 'click',
+        index: this.config.indexName,
+        objectIDs: [event.product.key],
+        userToken: this.context.session.identityContext.personalizationKey,
+        positions: [event.position],
+        queryID: (event.source.identifier as AlgoliaProductSearchIdentifier)
+          .key,
+      } satisfies ClickedObjectIDsAfterSearch;
+
+      const response = await this.client.pushEvents({
+        events: [algoliaEvent],
+      });
+    }
+  }
+
+  protected override async processProductSummaryView(
+    event: AnalyticsMutationProductSummaryViewEvent
+  ) {
+    if (event.source && event.source.type === 'search') {
+      const algoliaEvent = {
+        eventName: 'view',
+        eventType: 'view',
+        index: this.config.indexName,
+        objectIDs: event.products.map((x) => x.key),
+        userToken: this.context.session.identityContext.personalizationKey,
+      } satisfies ViewedObjectIDs;
+
+      const response = await this.client.pushEvents({
+        events: [algoliaEvent],
+      });
+    }
+  }
+
+  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.variant.sku),
+      userToken: this.context.session.identityContext.personalizationKey,
+    } satisfies PurchasedObjectIDs;
+
+    const response = await this.client.pushEvents({
+      events: [algoliaEvent],
+    });
+  }
+}

package/providers/algolia/src/providers/index.ts

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

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/project.json

@@ -1,5 +1,5 @@
 {
-  "name": "provider-commercetools",
+  "name": "commercetools",
   "$schema": "../../node_modules/nx/schemas/project-schema.json",
   "sourceRoot": "providers/commercetools/src",
   "projectType": "library",

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

@@ -237,10 +237,7 @@ export class CommercetoolsProfileProvider extends ProfileProvider {
     if (addressToMakeDefault.id === customer.defaultBillingAddressId) {
       return error<InvalidInputError>({
         type: 'InvalidInput',
-        error: {
-          field: 'addressIdentifier',
-          message: 'Cannot set shipping address as default billing address',
-        }
+        error: 'Cannot set shipping address as default billing address'
       });
     }
 

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 = {