@reactionary/core 0.11.1 → 0.12.0

package/analytics/context.js

@@ -0,0 +1,173 @@
+import { error, success } from "../schemas/result.js";
+const DEFAULT_CONCURRENCY = 5;
+function notConfigured(name) {
+  return error({ type: "Generic", message: `The ${name} capability is not configured, so analytics cannot look it up` });
+}
+function notFound(identifier) {
+  return error({ type: "NotFound", identifier });
+}
+function memoize(fn, keyOf) {
+  const cache = /* @__PURE__ */ new Map();
+  return (arg) => {
+    const key = keyOf(arg);
+    const hit = cache.get(key);
+    if (hit) {
+      return hit;
+    }
+    const pending = fn(arg);
+    cache.set(key, pending);
+    return pending;
+  };
+}
+function memoizeOnce(fn) {
+  let pending;
+  return () => pending ??= fn();
+}
+async function mapLimit(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+function createAnalyticsContext(dependencies) {
+  const { capabilities, requestContext } = dependencies;
+  const concurrency = Math.max(1, dependencies.concurrency ?? DEFAULT_CONCURRENCY);
+  const productById = memoize(
+    async (id) => capabilities.product ? capabilities.product.getById({ identifier: id }) : notConfigured("product"),
+    (id) => id.key
+  );
+  const productBySku = memoize(
+    async (variant) => capabilities.product ? capabilities.product.getBySKU({ variant }) : notConfigured("product"),
+    (variant) => variant.sku
+  );
+  const categoryById = memoize(
+    async (id) => capabilities.category ? capabilities.category.getById({ id }) : notConfigured("category"),
+    (id) => id.key
+  );
+  const categoryPath = memoize(
+    async (id) => capabilities.category ? capabilities.category.getBreadcrumbPathToCategory({ id }) : notConfigured("category"),
+    (id) => id.key
+  );
+  const pricesForSku = memoize(
+    async (variant) => {
+      if (!capabilities.price) {
+        return notConfigured("price");
+      }
+      const [customer, list] = await Promise.all([
+        capabilities.price.getCustomerPrice({ variant }),
+        capabilities.price.getListPrice({ variant })
+      ]);
+      if (!customer.success && !list.success) {
+        return customer;
+      }
+      return success({
+        customer: customer.success ? customer.value : void 0,
+        list: list.success ? list.value : void 0
+      });
+    },
+    (variant) => variant.sku
+  );
+  const storeById = memoize(
+    async (id) => capabilities.store ? capabilities.store.getById({ identifier: id }) : notConfigured("store"),
+    (id) => id.key
+  );
+  const inventoryForSku = memoize(
+    async (variant) => {
+      if (!capabilities.inventory) {
+        return notConfigured("inventory");
+      }
+      const store = await storeById(requestContext.storeIdentifier);
+      if (!store.success) {
+        return store;
+      }
+      return capabilities.inventory.getBySKU({ variant, fulfilmentCenter: store.value.fulfillmentCenter });
+    },
+    (variant) => variant.sku
+  );
+  const activeCart = memoizeOnce(
+    async () => {
+      if (!capabilities.cart) {
+        return notConfigured("cart");
+      }
+      const id = await capabilities.cart.getActiveCartId();
+      if (!id.success) {
+        return id;
+      }
+      return capabilities.cart.getById({ cart: id.value });
+    }
+  );
+  const orderById = memoize(
+    async (id) => capabilities.order ? capabilities.order.getById({ order: id }) : notConfigured("order"),
+    (id) => id.key
+  );
+  const selfIdentity = memoizeOnce(
+    async () => capabilities.identity ? capabilities.identity.getSelf({}) : notConfigured("identity")
+  );
+  const selfProfile = memoizeOnce(
+    async () => {
+      if (!capabilities.profile) {
+        return notConfigured("profile");
+      }
+      const identity = requestContext.session.identityContext.identity;
+      if (identity.type === "Anonymous") {
+        return notFound(identity);
+      }
+      return capabilities.profile.getById({ identifier: identity.id });
+    }
+  );
+  const selfPersonalization = memoizeOnce(
+    async () => {
+      if (!capabilities.personalizationProfile) {
+        return notConfigured("personalizationProfile");
+      }
+      const marketing = requestContext.session.marketingContext.identifier;
+      return capabilities.personalizationProfile.getPersonalizationProfile({
+        identity: requestContext.session.identityContext.identity,
+        personalizationProfileIdentifier: marketing.key ? marketing : void 0
+      });
+    }
+  );
+  const selfCompany = memoizeOnce(
+    async () => {
+      if (!capabilities.company) {
+        return notConfigured("company");
+      }
+      const cart = await activeCart();
+      if (!cart.success) {
+        return cart;
+      }
+      if (!cart.value.company) {
+        return notFound(cart.value.identifier);
+      }
+      return capabilities.company.getById({ identifier: cart.value.company });
+    }
+  );
+  return {
+    products: {
+      byId: productById,
+      bySku: productBySku,
+      many: (ids) => mapLimit(ids, concurrency, productById)
+    },
+    categories: { byId: categoryById, path: categoryPath },
+    prices: { forSku: pricesForSku },
+    inventory: { forSku: inventoryForSku },
+    cart: { active: () => activeCart() },
+    orders: { byId: orderById },
+    stores: { byId: storeById },
+    self: {
+      identity: () => selfIdentity(),
+      profile: () => selfProfile(),
+      personalization: () => selfPersonalization(),
+      company: () => selfCompany()
+    }
+  };
+}
+export {
+  createAnalyticsContext
+};

package/analytics/dispatcher.js

@@ -0,0 +1,181 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { traceSpan } from "../decorators/reactionary.decorator.js";
+import {
+  AnalyticsEventMutationSchemas,
+  AnalyticsEventSchema,
+  AnalyticsMutationConsentChangedSchema,
+  AnalyticsSubscriberDescriptorSchema
+} from "../schemas/index.js";
+import { error, success } from "../schemas/result.js";
+const DEFAULT_CONSENT = { analytics: true, marketing: true };
+const insideHandler = new AsyncLocalStorage();
+function eventTypeMatches(pattern, type) {
+  if (pattern === "*") {
+    return true;
+  }
+  if (pattern.endsWith("*")) {
+    return type.startsWith(pattern.slice(0, -1));
+  }
+  return pattern === type;
+}
+function isPurposeAllowed(purpose, consent) {
+  if (purpose === "necessary") {
+    return true;
+  }
+  return purpose === "analytics" ? consent.analytics : consent.marketing;
+}
+class AnalyticsDispatcher {
+  requestContext;
+  subscribers;
+  createContext;
+  options;
+  defaultConsent;
+  queue = [];
+  flushScheduled = false;
+  tails = /* @__PURE__ */ new Map();
+  inflight = /* @__PURE__ */ new Set();
+  constructor(dependencies) {
+    this.requestContext = dependencies.requestContext;
+    this.createContext = dependencies.createContext;
+    this.options = dependencies.options ?? {};
+    this.defaultConsent = this.options.defaultConsent ?? DEFAULT_CONSENT;
+    const names = /* @__PURE__ */ new Set();
+    for (const subscriber of dependencies.subscribers) {
+      AnalyticsSubscriberDescriptorSchema.parse({ name: subscriber.name, types: subscriber.types, purpose: subscriber.purpose });
+      if (names.has(subscriber.name)) {
+        throw new Error(`Duplicate analytics subscriber name '${subscriber.name}'`);
+      }
+      names.add(subscriber.name);
+    }
+    this.subscribers = [...dependencies.subscribers];
+  }
+  /**
+   * Validates the input, captures request state, enqueues the event and schedules delivery.
+   * Never throws: invalid input and emits made from inside a subscriber are logged and dropped.
+   */
+  emit(type, input, options = {}) {
+    if (insideHandler.getStore()) {
+      console.warn(`Analytics event '${type}' was emitted from inside a subscriber and has been dropped`);
+      return error({ type: "InvalidInput", error: "Events cannot be emitted from inside an analytics subscriber" });
+    }
+    try {
+      const schema = AnalyticsEventMutationSchemas[type];
+      const mutation = schema.safeParse(input);
+      if (!mutation.success) {
+        const message = mutation.error.message;
+        console.warn(`Analytics event '${type}' had invalid input and has been dropped: ${message}`);
+        return error({ type: "InvalidInput", error: message });
+      }
+      if (type === "consent-changed") {
+        const change = AnalyticsMutationConsentChangedSchema.parse(input);
+        this.requestContext.session.consent = change.consent;
+      }
+      const { origin, properties, ...payload } = input;
+      const event = AnalyticsEventSchema.safeParse({
+        id: crypto.randomUUID(),
+        type,
+        occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+        origin,
+        properties,
+        context: this.snapshot(options),
+        payload
+      });
+      if (!event.success) {
+        console.warn(`Analytics event '${type}' could not be built and has been dropped: ${event.error.message}`);
+        return error({ type: "InvalidInput", error: event.error.message });
+      }
+      this.queue.push(event.data);
+      this.scheduleFlush();
+      return success({ eventId: event.data.id });
+    } catch (err) {
+      console.error(`Analytics event '${type}' failed to enqueue and has been dropped`, err);
+      return error({ type: "InvalidInput", error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  /**
+   * Delivers everything queued so far and resolves once all deliveries, including ones already in flight, are done.
+   * For scripts, tests and runtimes without `waitUntil`. Never rejects.
+   */
+  async flush() {
+    this.deliverQueued();
+    await Promise.all([...this.inflight]);
+  }
+  /**
+   * A fresh lookup context, for analytics code that has to resolve something before it can emit (the legacy adapter).
+   */
+  lookups() {
+    return this.createContext();
+  }
+  snapshot(options) {
+    const { session, languageContext, referrer, userAgent, clientIp, isBot } = this.requestContext;
+    return {
+      marketingIdentifier: { ...options.marketingIdentifier ?? session.marketingContext.identifier },
+      identity: session.identityContext.identity,
+      locale: languageContext.locale,
+      currency: languageContext.currencyCode,
+      consent: session.consent ?? this.defaultConsent,
+      page: referrer ? { referrer } : void 0,
+      userAgent: userAgent || void 0,
+      clientIp: clientIp || void 0,
+      isBot
+    };
+  }
+  scheduleFlush() {
+    if (this.flushScheduled) {
+      return;
+    }
+    this.flushScheduled = true;
+    const run = Promise.resolve().then(() => {
+      this.flushScheduled = false;
+      return this.flush();
+    }).catch((err) => console.error("Analytics flush failed", err));
+    try {
+      this.options.waitUntil?.(run);
+    } catch (err) {
+      console.error("Analytics waitUntil failed", err);
+    }
+  }
+  deliverQueued() {
+    const batch = this.queue;
+    if (batch.length === 0) {
+      return;
+    }
+    this.queue = [];
+    const ctx = this.createContext();
+    const deliveries = [];
+    for (const subscriber of this.subscribers) {
+      const events = batch.filter(
+        (event) => subscriber.types.some((pattern) => eventTypeMatches(pattern, event.type)) && isPurposeAllowed(subscriber.purpose, event.context.consent ?? this.defaultConsent)
+      );
+      if (events.length === 0) {
+        continue;
+      }
+      const tail = (this.tails.get(subscriber) ?? Promise.resolve()).then(() => this.runSubscriber(subscriber, events, ctx));
+      this.tails.set(subscriber, tail);
+      deliveries.push(tail);
+    }
+    const done = Promise.all(deliveries).then(() => void 0);
+    this.inflight.add(done);
+    void done.finally(() => this.inflight.delete(done));
+  }
+  async runSubscriber(subscriber, events, ctx) {
+    for (const event of events) {
+      try {
+        const outcome = await insideHandler.run(
+          true,
+          () => traceSpan(`AnalyticsSubscriber.${subscriber.name}.handle`, () => subscriber.handle(event, ctx))
+        );
+        if (outcome === "rejected") {
+          console.warn(`Analytics subscriber '${subscriber.name}' rejected '${event.type}' (${event.id})`);
+        }
+      } catch (err) {
+        console.error(`Analytics subscriber '${subscriber.name}' failed on '${event.type}' (${event.id})`, err);
+      }
+    }
+  }
+}
+export {
+  AnalyticsDispatcher,
+  eventTypeMatches,
+  isPurposeAllowed
+};

package/analytics/index.js

@@ -0,0 +1,6 @@
+export * from "./context.js";
+export * from "./dispatcher.js";
+export * from "./legacy-adapter.js";
+export * from "./origins.js";
+export * from "./recording-subscriber.js";
+export * from "./refs.js";

package/analytics/legacy-adapter.js

@@ -0,0 +1,48 @@
+import { error } from "../schemas/result.js";
+import { fromDirect, fromSearch } from "./origins.js";
+async function emitLegacyAnalyticsEvent(event, dispatcher) {
+  const identity = event.personalizationProfile ? { marketingIdentifier: event.personalizationProfile.identifier } : {};
+  switch (event.event) {
+    case "product-summary-view":
+      return event.source ? dispatcher.emit("search-results-viewed", { search: event.source.identifier, products: event.products }, identity) : dispatcher.emit("product-carousel-viewed", { carousel: { carouselName: "unknown" }, products: event.products }, identity);
+    case "product-summary-click":
+      return dispatcher.emit(
+        "product-clicked",
+        {
+          product: event.product,
+          origin: event.source ? fromSearch(event.source.identifier, event.position) : fromDirect()
+        },
+        identity
+      );
+    case "product-details-view":
+      return dispatcher.emit("product-viewed", { product: event.product }, identity);
+    case "product-cart-add": {
+      const lookups = dispatcher.lookups();
+      const [cart, product] = await Promise.all([lookups.cart.active(), lookups.products.byId(event.product)]);
+      if (!cart.success) {
+        return cart;
+      }
+      if (!product.success) {
+        return product;
+      }
+      return dispatcher.emit(
+        "cart-item-added",
+        {
+          cart: cart.value,
+          variant: { sku: product.value.mainVariant.identifier.sku },
+          quantity: 1,
+          // The legacy source carries no position, only the search that led here.
+          origin: event.source ? fromSearch(event.source.identifier, 0) : void 0
+        },
+        identity
+      );
+    }
+    case "purchase":
+      return dispatcher.emit("order-placed", { order: event.order }, identity);
+    default:
+      return error({ type: "Generic", message: "Unsupported legacy analytics event" });
+  }
+}
+export {
+  emitLegacyAnalyticsEvent
+};

package/analytics/origins.js

@@ -0,0 +1,64 @@
+function fromSearch(identifier, position) {
+  return { type: "search", identifier, position };
+}
+function fromAutocomplete(term, position) {
+  return { type: "autocomplete", term, position };
+}
+function fromCategory(categoryId, filters, position) {
+  return { type: "category", categoryId, filters, position };
+}
+function fromList(recommendationId, carouselName, position) {
+  return { type: "list", recommendationId, carouselName, position };
+}
+function fromAssociations(productId, kind, position) {
+  return { type: "associations", productId, kind, position };
+}
+function fromProductList(listId, position) {
+  return { type: "product-list", listId, position };
+}
+function fromPromotion(promotionId, slot) {
+  return { type: "promotion", promotionId, slot };
+}
+function fromContent(contentId, slot) {
+  return { type: "content", contentId, slot };
+}
+function fromCart(kind) {
+  return { type: "cart", kind };
+}
+function fromOrder(orderId) {
+  return { type: "order", orderId };
+}
+function fromQuickOrder(kind) {
+  return { type: "quick-order", kind };
+}
+function fromPDP(upstream) {
+  return { type: "pdp", upstream };
+}
+function fromDirect() {
+  return { type: "direct" };
+}
+function searchOriginOf(origin) {
+  if (origin?.type === "search") {
+    return origin;
+  }
+  if (origin?.type === "pdp") {
+    return searchOriginOf(origin.upstream);
+  }
+  return void 0;
+}
+export {
+  fromAssociations,
+  fromAutocomplete,
+  fromCart,
+  fromCategory,
+  fromContent,
+  fromDirect,
+  fromList,
+  fromOrder,
+  fromPDP,
+  fromProductList,
+  fromPromotion,
+  fromQuickOrder,
+  fromSearch,
+  searchOriginOf
+};

package/analytics/recording-subscriber.js

@@ -0,0 +1,26 @@
+class RecordingAnalyticsSubscriber {
+  constructor(name = "recording", types = ["*"], purpose = "necessary") {
+    this.name = name;
+    this.types = types;
+    this.purpose = purpose;
+  }
+  name;
+  types;
+  purpose;
+  events = [];
+  /** Lookup contexts the subscriber was handed, one per flush. */
+  contexts = [];
+  async handle(event, ctx) {
+    this.events.push(event);
+    if (!this.contexts.includes(ctx)) {
+      this.contexts.push(ctx);
+    }
+    return "accepted";
+  }
+  eventsOfType(type) {
+    return this.events.filter((event) => event.type === type);
+  }
+}
+export {
+  RecordingAnalyticsSubscriber
+};

package/analytics/refs.js

@@ -0,0 +1,14 @@
+function productKey(ref) {
+  return "key" in ref ? ref.key : ref.identifier.key;
+}
+function categoryKey(ref) {
+  return "key" in ref ? ref.key : ref.identifier.key;
+}
+function storeKey(ref) {
+  return "key" in ref ? ref.key : ref.identifier.key;
+}
+export {
+  categoryKey,
+  productKey,
+  storeKey
+};