@reactionary/source 0.3.0 → 0.3.2

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

@@ -1,7 +1,7 @@
 import type { Cache } from '../cache/cache.interface.js';
 import { NoOpCache } from '../cache/noop-cache.js';
 import type { Client } from './client.js';
-import type { AnalyticsProvider } from '../providers/analytics.provider.js';
+import { MulticastAnalyticsProvider, type AnalyticsProvider } from '../providers/analytics.provider.js';
 import {
   RequestContextSchema,
   type RequestContext,
@@ -60,18 +60,14 @@ export class ClientBuilder<TClient = Client> {
       };
 
       if (provider.analytics) {
-        mergedAnalytics.push(...provider.analytics);
+        mergedAnalytics.push(provider.analytics);
       }
     }
 
-    // Add merged analytics if any were collected
-    if (mergedAnalytics.length > 0) {
-      (client as Record<string, unknown>)['analytics'] = mergedAnalytics;
-    }
-
     // Add cache to complete the client
     const completeClient = {
       ...client,
+      analytics: new MulticastAnalyticsProvider(sharedCache, this.context, mergedAnalytics),
       cache: sharedCache,
     } as TClient & { cache: Cache };
 

package/core/src/client/client.ts

@@ -1,4 +1,3 @@
-import type { AnalyticsProvider } from "../providers/analytics.provider.js";
 import type { ProductProvider } from "../providers/product.provider.js";
 import type { ProductSearchProvider } from "../providers/product-search.provider.js";
 import type { IdentityProvider } from '../providers/identity.provider.js';
@@ -7,7 +6,7 @@ import type { PriceProvider } from "../providers/price.provider.js";
 import type { InventoryProvider } from "../providers/inventory.provider.js";
 import type { Cache } from "../cache/cache.interface.js";
 import type { CategoryProvider } from "../providers/category.provider.js";
-import type { CheckoutProvider, OrderProvider, ProfileProvider, StoreProvider } from "../providers/index.js";
+import type { AnalyticsProvider, CheckoutProvider, OrderProvider, ProfileProvider, StoreProvider } from "../providers/index.js";
 import type { OrderSearchProvider } from "../providers/order-search.provider.js";
 
 export interface Client {
@@ -17,7 +16,7 @@ export interface Client {
     cache: Cache,
     cart: CartProvider,
     checkout: CheckoutProvider,
-    analytics: Array<AnalyticsProvider>,
+    analytics: AnalyticsProvider,
     price: PriceProvider,
     inventory: InventoryProvider,
     category: CategoryProvider,

package/core/src/decorators/reactionary.decorator.ts

@@ -193,7 +193,7 @@ export function validateInput<T>(
   if (!parse.success) {
     validated = error<InvalidInputError>({
       type: 'InvalidInput',
-      error: parse.error,
+      error: JSON.stringify(z.flattenError(parse.error)),
     });
   }
 
@@ -218,7 +218,7 @@ export function validateOutput(
     if (!parse.success) {
       validated = error<InvalidOutputError>({
         type: 'InvalidOutput',
-        error: parse.error,
+        error: JSON.stringify(z.flattenError(parse.error)),
       });
     }
   }

package/core/src/initialization.ts

@@ -1,4 +1,5 @@
-import type { RequestContext } from "./schemas/session.schema.js";
+import type { AnonymousIdentity } from './schemas/index.js';
+import type { RequestContext } from './schemas/session.schema.js';
 
 export function createInitialRequestContext(): RequestContext {
   return {
@@ -15,8 +16,15 @@ export function createInitialRequestContext(): RequestContext {
       countyCode: '',
       cityCode: '',
     },
-    session: {},
-
+    session: {
+      identityContext: {
+        identity: {
+          type: 'Anonymous'
+        } satisfies AnonymousIdentity,
+        lastUpdated: new Date(),
+        personalizationKey: crypto.randomUUID(),
+      },
+    },
     correlationId: '',
     isBot: false,
     clientIp: '',

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

@@ -1,7 +1,82 @@
+import type { RequestContext } from '../schemas/session.schema.js';
 import { BaseProvider } from './base.provider.js';
+import type { Cache } from '../cache/cache.interface.js';
+import {
+  AnalyticsMutationSchema,
+  type AnalyticsMutation,
+  type AnalyticsMutationProductAddToCartEvent,
+  type AnalyticsMutationProductDetailsViewEvent,
+  type AnalyticsMutationProductSummaryClickEvent,
+  type AnalyticsMutationProductSummaryViewEvent,
+  type AnalyticsMutationPurchaseEvent,
+} from '../schemas/index.js';
+import { Reactionary } from '../decorators/reactionary.decorator.js';
 
 export abstract class AnalyticsProvider extends BaseProvider {
   protected override getResourceName(): string {
     return 'analytics';
   }
+
+  public async track(event: AnalyticsMutation): Promise<void> {
+    switch (event.event) {
+      case 'product-summary-view':
+        await this.processProductSummaryView(event);
+        break;
+      case 'product-summary-click':
+        await this.processProductSummaryClick(event);
+        break;
+      case 'product-details-view':
+        await this.processProductDetailsView(event);
+        break;
+      case 'product-cart-add':
+        await this.processProductAddToCart(event);
+        break;
+      case 'purchase':
+        await this.processPurchase(event)
+        break;
+    }
+  }
+
+  protected async processProductSummaryView(event: AnalyticsMutationProductSummaryViewEvent) {
+    // Default is no-op
+  }
+
+  protected async processProductSummaryClick(event: AnalyticsMutationProductSummaryClickEvent) {
+    // Default is no-op
+  }
+
+  protected async processProductDetailsView(event: AnalyticsMutationProductDetailsViewEvent) {
+    // Default is no-op
+  }
+
+  protected async processProductAddToCart(event: AnalyticsMutationProductAddToCartEvent) {
+    // Default is no-op
+  }
+
+  protected async processPurchase(event: AnalyticsMutationPurchaseEvent) {
+    // Default is no-op
+  }
+}
+
+export class MulticastAnalyticsProvider extends AnalyticsProvider {
+  protected providers: Array<AnalyticsProvider>;
+
+  constructor(
+    cache: Cache,
+    requestContext: RequestContext,
+    providers: Array<AnalyticsProvider>
+  ) {
+    super(cache, requestContext);
+
+    this.providers = providers;
+  }
+
+  @Reactionary({
+    inputSchema: AnalyticsMutationSchema,
+  })
+  public override async track(event: AnalyticsMutation) {
+    for (const provider of this.providers) {
+      provider.track(event);
+    }
+  }
 }

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

@@ -6,6 +6,9 @@ import type { CartQueryById } from "../schemas/queries/cart.query.js";
 import type { Result } from "../schemas/result.js";
 import { BaseProvider } from "./base.provider.js";
 
+/**
+ * @group Providers
+ */
 export abstract class CartProvider extends BaseProvider {
 
   /**

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

@@ -11,6 +11,7 @@ import { BaseProvider } from "./base.provider.js";
  *
  * We only allow fetching one hierachy level at a time, for now. This is to avoid development patterns of "fetch 5000 categories in one go.."
  *
+ * @group Foo
  */
 export abstract class CategoryProvider extends BaseProvider {
   /**

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/errors/invalid-input.error.ts

@@ -3,7 +3,7 @@ import type { InferType } from '../../zod-utils.js';
 
 export const InvalidInputErrorSchema = z.looseObject({
     type: z.literal('InvalidInput'),
-    error: z.ZodError
+    error: z.string(),
 });
 
 export type InvalidInputError = InferType<typeof InvalidInputErrorSchema>;

package/core/src/schemas/errors/invalid-output.error.ts

@@ -3,7 +3,7 @@ import type { InferType } from '../../zod-utils.js';
 
 export const InvalidOutputErrorSchema = z.looseObject({
     type: z.literal('InvalidOutput'),
-    error: z.ZodError
+    error: z.string()
 });
 
 export type InvalidOutputError = InferType<typeof InvalidOutputErrorSchema>;

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

@@ -127,6 +127,9 @@ export const ProductSearchIdentifierSchema = z.looseObject({
   categoryFilter: FacetValueIdentifierSchema.optional().describe('An optional category filter applied to the search results.'),
 });
 
+/**
+ * Bar
+ */
 export const OrderSearchIdentifierSchema = z.looseObject({
   term: z.string().describe('The search term used to find orders. Not all providers may support term-based search for orders.'),
   partNumber: z.array(z.string()).optional().describe('An optional list part number to filter orders by specific products. Will be ANDed together.'),

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { CartIdentifierSchema, CartItemIdentifierSchema, IdentityIdentifierSchema, OrderIdentifierSchema, OrderInventoryStatusSchema, OrderItemIdentifierSchema, OrderStatusSchema, ProductVariantIdentifierSchema } from '../models/identifiers.model.js';
+import { CartIdentifierSchema, IdentityIdentifierSchema, OrderIdentifierSchema, OrderInventoryStatusSchema, OrderItemIdentifierSchema, OrderStatusSchema, ProductVariantIdentifierSchema } from '../models/identifiers.model.js';
 import { BaseModelSchema } from './base.model.js';
 import { AddressSchema } from './profile.model.js';
 import { ShippingMethodSchema } from './shipping-method.model.js';
@@ -34,7 +34,7 @@ export const OrderSchema = BaseModelSchema.extend({
 });
 
 
-export type OrderStatus = InferType<typeof OrderStatusSchema>;
+export type OrderStatus = z.infer<typeof OrderStatusSchema>;
 export type OrderInventoryStatus = InferType<typeof OrderInventoryStatusSchema>;
 export type OrderItem = InferType<typeof OrderItemSchema>;
 export type Order = InferType<typeof OrderSchema>;

package/core/src/schemas/mutations/analytics/index.ts

@@ -0,0 +1,23 @@
+import z from 'zod';
+import type { InferType } from '../../../zod-utils.js';
+import { AnalyticsMutationProductAddToCartEventSchema } from './product-add-to-cart.mutation.js';
+import { AnalyticsMutationProductDetailsViewEventSchema } from './product-details-view.mutation.js';
+import { AnalyticsMutationProductSummaryClickEventSchema } from './product-summary-click.mutation.js';
+import { AnalyticsMutationProductSummaryViewEventSchema } from './product-summary-view.mutation.js';
+import { AnalyticsMutationPurchaseEventSchema } from './purchase.mutation.js';
+
+export const AnalyticsMutationSchema = z.discriminatedUnion('event', [
+  AnalyticsMutationProductSummaryViewEventSchema,
+  AnalyticsMutationProductSummaryClickEventSchema,
+  AnalyticsMutationProductDetailsViewEventSchema,
+  AnalyticsMutationProductAddToCartEventSchema,
+  AnalyticsMutationPurchaseEventSchema
+]);
+
+export type AnalyticsMutation = InferType<typeof AnalyticsMutationSchema>;
+
+export * from './product-add-to-cart.mutation.js';
+export * from './product-details-view.mutation.js';
+export * from './product-summary-click.mutation.js';
+export * from './product-summary-view.mutation.js';
+export * from './purchase.mutation.js';

package/core/src/schemas/mutations/analytics/product-add-to-cart.mutation.ts

@@ -0,0 +1,25 @@
+import z from 'zod';
+import {
+  ProductSearchIdentifierSchema,
+  ProductIdentifierSchema,
+} from '../../models/identifiers.model.js';
+import { BaseMutationSchema } from '../base.mutation.js';
+import type { InferType } from '../../../zod-utils.js';
+
+export const AnalyticsMutationProductAddToCartEventSchema =
+  BaseMutationSchema.extend({
+    event: z.literal('product-cart-add'),
+    source: z
+      .discriminatedUnion('type', [
+        z.object({
+          type: z.literal('search'),
+          identifier: ProductSearchIdentifierSchema,
+        }),
+      ])
+      .optional(),
+    product: ProductIdentifierSchema,
+  });
+
+export type AnalyticsMutationProductAddToCartEvent = InferType<
+  typeof AnalyticsMutationProductAddToCartEventSchema
+>;

package/core/src/schemas/mutations/analytics/product-details-view.mutation.ts

@@ -0,0 +1,14 @@
+import z from 'zod';
+import { ProductIdentifierSchema } from '../../models/identifiers.model.js';
+import { BaseMutationSchema } from '../base.mutation.js';
+import type { InferType } from '../../../zod-utils.js';
+
+export const AnalyticsMutationProductDetailsViewEventSchema =
+  BaseMutationSchema.extend({
+    event: z.literal('product-details-view'),
+    product: ProductIdentifierSchema,
+  });
+
+export type AnalyticsMutationProductDetailsViewEvent = InferType<
+  typeof AnalyticsMutationProductDetailsViewEventSchema
+>;

package/core/src/schemas/mutations/analytics/product-summary-click.mutation.ts

@@ -0,0 +1,26 @@
+import type { InferType } from '../../../zod-utils.js';
+import {
+  ProductIdentifierSchema,
+  ProductSearchIdentifierSchema,
+} from '../../models/identifiers.model.js';
+import { BaseMutationSchema } from '../base.mutation.js';
+import { z } from 'zod';
+
+export const AnalyticsMutationProductSummaryClickEventSchema =
+  BaseMutationSchema.extend({
+    event: z.literal('product-summary-click'),
+    product: ProductIdentifierSchema,
+    source: z
+      .discriminatedUnion('type', [
+        z.object({
+          type: z.literal('search'),
+          identifier: ProductSearchIdentifierSchema,
+        }),
+      ])
+      .optional(),
+    position: z.number().min(0),
+  });
+
+export type AnalyticsMutationProductSummaryClickEvent = InferType<
+  typeof AnalyticsMutationProductSummaryClickEventSchema
+>;

package/core/src/schemas/mutations/analytics/product-summary-view.mutation.ts

@@ -0,0 +1,25 @@
+import type { InferType } from '../../../zod-utils.js';
+import {
+  ProductIdentifierSchema,
+  ProductSearchIdentifierSchema,
+} from '../../models/identifiers.model.js';
+import { BaseMutationSchema } from '../base.mutation.js';
+import { z } from 'zod';
+
+export const AnalyticsMutationProductSummaryViewEventSchema =
+  BaseMutationSchema.extend({
+    event: z.literal('product-summary-view'),
+    source: z
+      .discriminatedUnion('type', [
+        z.object({
+          type: z.literal('search'),
+          identifier: ProductSearchIdentifierSchema,
+        }),
+      ])
+      .optional(),
+    products: z.array(ProductIdentifierSchema),
+  });
+
+export type AnalyticsMutationProductSummaryViewEvent = InferType<
+  typeof AnalyticsMutationProductSummaryViewEventSchema
+>;

package/core/src/schemas/mutations/analytics/purchase.mutation.ts

@@ -0,0 +1,14 @@
+import z from 'zod';
+import { BaseMutationSchema } from '../base.mutation.js';
+import type { InferType } from '../../../zod-utils.js';
+import { OrderSchema } from '../../models/order.model.js';
+
+export const AnalyticsMutationPurchaseEventSchema =
+  BaseMutationSchema.extend({
+    event: z.literal('purchase'),
+    order: OrderSchema
+  });
+
+export type AnalyticsMutationPurchaseEvent = InferType<
+  typeof AnalyticsMutationPurchaseEventSchema
+>;

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

@@ -1,4 +1,4 @@
-export * from './analytics.mutation.js';
+export * from './analytics/index.js';
 export * from './base.mutation.js';
 export * from './cart.mutation.js';
 export * from './identity.mutation.js';

package/core/src/schemas/queries/order-search.query.ts

@@ -2,6 +2,9 @@ import type { InferType } from "../../zod-utils.js";
 import { OrderSearchIdentifierSchema } from "../models/identifiers.model.js";
 import { BaseQuerySchema } from "./base.query.js";
 
+/**
+ * Foo
+ */
 export const OrderSearchQueryByTermSchema = BaseQuerySchema.extend({
     search: OrderSearchIdentifierSchema
 });

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { WebStoreIdentifierSchema } from './models/identifiers.model.js';
+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.
@@ -8,9 +9,17 @@ import { CurrencySchema } from './models/currency.model.js';
 export const LanguageContextSchema = z.looseObject( {
     locale: z.string().default('en-US'),
     currencyCode: CurrencySchema.default(() => CurrencySchema.parse({})),
-})
+});
+
+export const IdentityContextSchema = z.looseObject({
+    identity: IdentitySchema,
+    personalizationKey: z.string(),
+    lastUpdated: z.date()
+});
 
-export const SessionSchema = z.record(z.string(), z.any());
+export const SessionSchema = z.record(z.string(), z.any()).and(z.object({
+    identityContext: IdentityContextSchema
+}));
 
 export const TaxJurisdictionSchema = z.object( {
     countryCode: z.string().default('US'),
@@ -21,7 +30,6 @@ export const TaxJurisdictionSchema = z.object( {
 
 export const RequestContextSchema = z.looseObject( {
     session: SessionSchema.default(() => SessionSchema.parse({})).describe('Read/Write session storage. Caller is responsible for persisting any changes. Providers will prefix own values'),
-
     languageContext: LanguageContextSchema.default(() => LanguageContextSchema.parse({})).describe('ReadOnly. The language and locale context for the current request.'),
     storeIdentifier: WebStoreIdentifierSchema.default(() => WebStoreIdentifierSchema.parse({})).describe('ReadOnly. The identifier of the current web store making the request.'),
     taxJurisdiction: TaxJurisdictionSchema.default(() => TaxJurisdictionSchema.parse({})).describe('ReadOnly. The tax jurisdiction for the current request, typically derived from the store location or carts billing address'),
@@ -32,14 +40,18 @@ export const RequestContextSchema = z.looseObject( {
     clientIp: z.string().default('').describe('The IP address of the client making the request, if available. Mostly for logging purposes'),
     userAgent: z.string().default('').describe('The user agent string of the client making the request, if available.'),
     referrer: z.string().default('').describe('The referrer URL, if available.'),
-})
+});
 
 
 
 // Note, for this ONE type (which is effectively a dictionary), we currently don't want
 // to strip [key: string]: unknown, hence the manual zod infer over the helper.
 // Maybe there is a better solution, with a different typing for SessionSchema...
-export type Session = z.infer<typeof SessionSchema>;
-export type LanguageContext = z.infer<typeof LanguageContextSchema>;
-export type RequestContext = z.infer<typeof RequestContextSchema>;
-export type TaxJurisdiction = z.infer<typeof TaxJurisdictionSchema>;
+/**
+ * @see {@link SessionSchema}
+ */
+export type Session = z.infer<typeof SessionSchema> & { _?: never};
+export type LanguageContext = z.infer<typeof LanguageContextSchema> & { _?: never};
+export type RequestContext = z.infer<typeof RequestContextSchema> & { _?: never};
+export type TaxJurisdiction = z.infer<typeof TaxJurisdictionSchema> & { _?: never};
+export type IdentityContext = z.infer<typeof IdentityContextSchema> & { _?: never};

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

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import type { Capabilities, ClientFromCapabilities } from "../schemas/capabilities.schema.js";
+import type { Cache } from '../cache/cache.interface.js';
+import type { RequestContext } from "../schemas/session.schema.js";
+import { AnalyticsProvider } from "../providers/analytics.provider.js";
+import type { AnalyticsMutation } from "../schemas/index.js";
+import { NoOpCache } from "../cache/noop-cache.js";
+import { createInitialRequestContext } from "../initialization.js";
+import { ClientBuilder } from "../client/client-builder.js";
+import type { Client } from "../client/client.js";
+
+export class MockAnalyticsProvider extends AnalyticsProvider {
+    public events: Array<AnalyticsMutation> = [];
+
+    public override async track(event: AnalyticsMutation): Promise<void> {
+        this.events.push(event);
+    }
+}
+
+export interface MockConfiguration {
+    mock?: string;
+}
+
+export function withMockCapabilities<T extends Partial<Capabilities>>(
+  client: Partial<Client>
+) {
+  return (
+    cache: Cache,
+    context: RequestContext
+  ): ClientFromCapabilities<T> => {
+    return client as ClientFromCapabilities<T>
+  }
+};
+
+describe('Client Builder', () => {
+  it('should properly multicast analytics events to all analytics providers that register themselves', async () => {
+    const cache = new NoOpCache();
+    const context = createInitialRequestContext();
+    const builder = new ClientBuilder(context);
+    const analyticsProvider = new MockAnalyticsProvider(cache, context);
+    const secondaryAnalyticsProvider = new MockAnalyticsProvider(cache, context);
+    const client = builder
+        .withCache(cache)
+        .withCapability(withMockCapabilities({ analytics: analyticsProvider }))
+        .withCapability(withMockCapabilities({ analytics: secondaryAnalyticsProvider }))
+        .build();
+
+    const track = await client.analytics.track({
+        event: 'product-details-view',
+        product: {
+          key: 'P-1000'
+        }
+    });
+
+    expect(analyticsProvider.events.length).toBe(1);
+    expect(analyticsProvider.events[0].event).toBe('product-details-view');
+    expect(secondaryAnalyticsProvider.events.length).toBe(1);
+    expect(secondaryAnalyticsProvider.events[0].event).toBe('product-details-view');
+  });
+});

package/core/src/zod-utils.ts

@@ -16,4 +16,6 @@ export type StripIndexSignature<T> =
   } :
   T;
 
-export type InferType<T extends z.ZodTypeAny> = StripIndexSignature<z.infer<T>>;
+export type AvoidSimplification<T> = T & { _?: never }
+
+export type InferType<T extends z.ZodTypeAny> = AvoidSimplification<StripIndexSignature<z.infer<T>>>;

package/documentation/{1-purpose.md → docs/1-purpose.md}

@@ -1,3 +1,7 @@
+---
+slug: /
+---
+
 # Reactionary
 
 Reactionary is an oppinionated abstraction layer between UX developer and Backend developer in a Composable Commerce environment.

package/documentation/docs/8-tracking.md

@@ -0,0 +1,9 @@
+# Tracking customer interactions
+Reactionary takes the approach that tracking customer data should be structured and managed, as opposed to ad-hoc in the browser. The core implication of this is that tracking should happen as a centralized, first-party stream of data to the backend, which may then in turn delegate it to the interested parties. We take this approach for a few reasons:
+
+- Performance: the client should not have to load several megabytes of tracking scripts that may in turn bring in other tracking scripts as their first priority upon entering the site. This is treating the customer a product rather than a valued customer. The client should only send their tracking data ONCE, and the performance impact of having to collect it should be a minimal obstruction to their actual goal.
+- Control: the system should enforce mandatory requirements such as Do Not Track in a single place, and ensure that anonymization happens as required.
+- 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.