@envive-ai/react-hooks 0.1.0

package/src/application/service/windowFrontendConfigService.ts

@@ -0,0 +1,104 @@
+import Logger from 'src/application/logging/logger';
+import { EnvironmentService } from 'src/application/service/environmentService';
+import { applyOverrides, Override } from 'src/application/utils/overrides';
+import { getAtomStore } from 'src/atoms/atomStore';
+import { colorsConfigAtom, frontendConfigAtom } from 'src/atoms/org/graphqlConfig';
+import { orgPageConfigAtom } from 'src/atoms/org/orgPageConfig';
+import { orgUIConfigAtom } from 'src/atoms/org/orgUIConfig';
+import { ColorMapping, OrgUIConfig, WidgetConfig, WidgetMountingConfig } from 'src/contexts/types';
+
+type CustomizableFrontendConfig = {
+  orgUIConfig: OrgUIConfig;
+  colorsConfig: ColorMapping;
+  mountingConfigs: Record<string, WidgetMountingConfig>;
+  widgetConfigs: Record<string, WidgetConfig>;
+};
+type FrontendConfigOverrides = Override<CustomizableFrontendConfig>;
+
+class WindowFrontendConfigService {
+  private static instance: WindowFrontendConfigService | undefined;
+
+  private isInitialized = false;
+
+  static getSingletonInstance(): WindowFrontendConfigService {
+    if (!this.instance) {
+      this.instance = new WindowFrontendConfigService();
+    }
+    return this.instance;
+  }
+
+  init() {
+    if (this.isInitialized) return;
+    this.isInitialized = true;
+
+    try {
+      const identifyingPrefix = EnvironmentService.getIdentifyingPrefix();
+      if (!window[identifyingPrefix]) {
+        window[identifyingPrefix] = {} as Window[typeof identifyingPrefix];
+      }
+
+      // Attach an explicit apply function to be called by the host page
+      const apply = (overrides: FrontendConfigOverrides[]) => {
+        Logger.logDebug('[spiffy-ai] applyFrontendConfigOverrides invoked');
+        WindowFrontendConfigService.applyOverridesToFrontendConfig(overrides);
+      };
+
+      window[identifyingPrefix].applyFrontendConfigOverrides = apply;
+
+      Logger.logDebug('[spiffy-ai] FrontendConfig overrides apply function attached');
+    } catch (e) {
+      Logger.logError('[spiffy-ai] Failed to attach FrontendConfig overrides apply function', e);
+    }
+  }
+
+  private static async applyOverridesToFrontendConfig(overrides: FrontendConfigOverrides[]) {
+    const atomStore = getAtomStore();
+    try {
+      // Get the current frontend config(s) from the atoms once
+      const frontendConfig = await atomStore.get(frontendConfigAtom);
+      // Get the orgPageConfig for widgetConfigs and mountingConfigs, but don't write to it
+      // If you use frontendConfigAtom to get the mountingConfigs and widgetConfigs,
+      // you will get {}, which are not the full version of the mountingConfigs and widgetConfigs
+      const orgPageConfig = await atomStore.get(orgPageConfigAtom);
+
+      let currentConfig: CustomizableFrontendConfig = {
+        orgUIConfig: atomStore.get(orgUIConfigAtom),
+        colorsConfig: (await atomStore.get(colorsConfigAtom)) as ColorMapping,
+        mountingConfigs: orgPageConfig.mountingConfigs,
+        widgetConfigs: orgPageConfig.widgetConfigs,
+      };
+
+      Logger.logInfo('[spiffy-ai] base config', {
+        baseConfig: currentConfig,
+      });
+
+      for (let i = 0; i < overrides.length; i += 1) {
+        const currentOverride = overrides[i];
+        currentConfig = applyOverrides<CustomizableFrontendConfig>(currentConfig, currentOverride, {
+          arrayStrategy: 'mergeByIndex',
+        });
+      }
+
+      // Update the atoms with the new frontend config(s)
+      atomStore.set(orgUIConfigAtom, currentConfig.orgUIConfig);
+      atomStore.set(colorsConfigAtom, currentConfig.colorsConfig);
+      // Write to the frontendConfigAtom to update the mountingConfigs and widgetConfigs
+      // This is the only way to update the mountingConfigs and widgetConfigs
+      // because the orgPageConfigAtom write only updates the pageVariants
+      atomStore.set(frontendConfigAtom, {
+        ...frontendConfig,
+        mountingConfigs: currentConfig.mountingConfigs,
+        widgetConfigs: currentConfig.widgetConfigs,
+      });
+
+      Logger.logInfo('[spiffy-ai] atoms updated via overrides', {
+        currentConfig,
+      });
+    } catch (e) {
+      Logger.logError('[spiffy-ai] Failed to apply FrontendConfig overrides', e);
+    }
+  }
+}
+
+export const initWindowFrontendConfigOverridesApplyFunction = () =>
+  WindowFrontendConfigService.getSingletonInstance().init();

package/src/application/utils/__tests__/divideArrays.test.ts

@@ -0,0 +1,14 @@
+// import { expect } from 'vitest';
+// import { divideArray } from '../divideArray';
+
+// describe('divideArray', () => {
+//   it('should divide an array into 3 rows', () => {
+//     const array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+//     const rows = divideArray(array, 3);
+//     expect(rows).toEqual([
+//       [1, 4, 7, 10],
+//       [2, 5, 8],
+//       [3, 6, 9],
+//     ]);
+//   });
+// });

package/src/application/utils/analyticsUtils.ts

@@ -0,0 +1,110 @@
+import Logger from 'src/application/logging/logger';
+import { AmplitudeAdapter, SpiffyMetricsEventName } from 'src/adapters/amplitude';
+import {
+  isLegacyUAEcommerceEvent,
+  isGA4EcommerceEvent,
+  isBaseEcommerceEvent,
+  BaseEcommerceEvent,
+} from 'src/application/models';
+
+const NORMALIZED_ADD_TO_CART_EVENT_NAMES = ['addtocart', 'addedtocart'];
+const CHECK_DATA_LAYER_INTERVAL_MS = 500;
+const CHECK_DATA_LAYER_MAX_ATTEMPTS = 10;
+
+/**
+ * Checks if a Google Analytics event is an add_to_cart event.
+ *
+ * @param event The event name to check.
+ *
+ * @returns True if the event is an add_to_cart event, false otherwise.
+ */
+const isAddToCartEvent = (event: string): boolean => {
+  const normalizedEvent = event.replace(/[-_]/g, '').toLowerCase();
+  return NORMALIZED_ADD_TO_CART_EVENT_NAMES.some((name) => normalizedEvent.includes(name));
+};
+
+/**
+ * Tracks an add_to_cart event in Amplitude.
+ *
+ * @param event The event to track.
+ */
+const handleAddToCartEvent = (event: BaseEcommerceEvent) => {
+  let eventProps: Record<string, unknown>;
+
+  if (isLegacyUAEcommerceEvent(event)) {
+    eventProps = {
+      items: event.ecommerce.add.products.map((product) => ({
+        item_name: product.name,
+        item_category: product.category,
+        price: product.price,
+        quantity: product.quantity,
+      })),
+      currency: event.ecommerce.add.currencyCode,
+      event_format_version: 'legacy_universal_analytics',
+    };
+  } else if (isGA4EcommerceEvent(event)) {
+    eventProps = {
+      items: event.ecommerce.items.map((item) => ({
+        item_name: item.item_name,
+        item_category: item.item_category,
+        price: item.price,
+        quantity: item.quantity,
+      })),
+      currency: event.ecommerce.currency,
+      event_format_version: 'google_analytics_4',
+    };
+  } else {
+    eventProps = {
+      event_properties: { ...event },
+      event_format_version: 'unknown',
+    };
+  }
+
+  AmplitudeAdapter.trackEvent({
+    eventName: SpiffyMetricsEventName.AddToCartClicked,
+    eventProps,
+  });
+};
+
+/**
+ * Wraps the window.dataLayer.push method to intercept add_to_cart events and send them to Amplitude.
+ * This function runs on an interval until the dataLayer is available.
+ */
+export const initDataLayerWrapper = () => {
+  let attempts = 0;
+
+  // currently, our bundle is always loaded after GTM has initialized GA/dataLayer
+  // we'll need this check here if/when we load spiffy before/outside of GTM
+  const checkAndInitialize = () => {
+    if (!window.dataLayer || !window.dataLayer.push) {
+      attempts += 1;
+
+      if (attempts >= CHECK_DATA_LAYER_MAX_ATTEMPTS) {
+        Logger.logDebug(
+          `[spiffy-ai] dataLayer not available after ${CHECK_DATA_LAYER_MAX_ATTEMPTS} attempts`,
+        );
+        return;
+      }
+
+      setTimeout(checkAndInitialize, CHECK_DATA_LAYER_INTERVAL_MS);
+      return;
+    }
+
+    Logger.logDebug('[spiffy-ai] dataLayer is available, wrapping push function...');
+    const originalPush = window.dataLayer.push;
+    window.dataLayer.push = (args: unknown) => {
+      if (isBaseEcommerceEvent(args) && isAddToCartEvent(args.event)) {
+        handleAddToCartEvent(args);
+      }
+
+      // IMPORTANT: call the original push method so that the event is still logged to GA
+      originalPush.apply(window.dataLayer, [args]);
+    };
+  };
+
+  checkAndInitialize();
+};
+
+export const initAmplitude = () => {
+  AmplitudeAdapter.getSingletonInstanceOf();
+};

package/src/application/utils/coreContextToApiContext.ts

@@ -0,0 +1,11 @@
+import { Context as ApiContext } from '@spiffy-ai/commerce-api-client';
+import { Context as CoreContext } from '../models';
+
+export const coreContextToApiContext = (context: CoreContext): ApiContext => ({
+  chat_id: context.chatId,
+  org_id: context.orgId,
+  user_id: context.userId,
+  org_short_name: context.orgShortName,
+  source: context.source,
+  env: context.env,
+});

package/src/application/utils/coreUserEventToApiUserEvent.ts

@@ -0,0 +1,106 @@
+import {
+  UserEvent as ApiUserEvent,
+  PLPAttributeCategory,
+  PLPIdAttributes,
+  UserEventCategory,
+} from '@spiffy-ai/commerce-api-client';
+import { UserEvent as CoreUserEvent } from '../models';
+
+export const coreUserEventToApiUserEvent = (data: CoreUserEvent): ApiUserEvent => {
+  if (
+    data.category === UserEventCategory.PdpVisit ||
+    data.category === UserEventCategory.AddToCart
+  ) {
+    return {
+      event_id: data.eventId,
+      created_at: data.createdAt,
+      category: data.category,
+      attributes: {
+        product_id: data.attributes.productId,
+        parent_product_id: data.attributes.parentProductId,
+        url: data.attributes.url,
+      },
+    };
+  }
+
+  if (data.category === UserEventCategory.PlpVisit) {
+    return {
+      event_id: data.eventId,
+      created_at: data.createdAt,
+      category: data.category,
+      attributes: {
+        category: PLPAttributeCategory.Id,
+        attributes: {
+          // we're only handling id attributes for now
+          id: (data.attributes.attributes as PLPIdAttributes).id,
+        },
+      },
+    };
+  }
+
+  if (data.category === UserEventCategory.QueryTyped) {
+    return {
+      event_id: data.eventId,
+      created_at: data.createdAt,
+      category: data.category,
+      attributes: {
+        query: data.attributes.query,
+      },
+    };
+  }
+
+  if (data.category === UserEventCategory.Search) {
+    return {
+      event_id: data.eventId,
+      created_at: data.createdAt,
+      category: data.category,
+      attributes: {
+        search_term: data.attributes.searchTerm,
+        selected_filters: data.attributes.selectedFilters,
+      },
+    };
+  }
+
+  if (data.category === UserEventCategory.SuggestionClicked) {
+    return {
+      event_id: data.eventId,
+      created_at: data.createdAt,
+      category: data.category,
+      attributes: {
+        suggestion_id: data.attributes.suggestionId,
+      },
+    };
+  }
+
+  if (data.category === UserEventCategory.PageVisit) {
+    return {
+      event_id: data.eventId,
+      created_at: data.createdAt,
+      category: data.category,
+      attributes: {
+        url: data.attributes.url,
+        page_visit_category: data.attributes.pageVisitCategory,
+      },
+    };
+  }
+
+  if (data.category === UserEventCategory.FormSubmitted) {
+    return {
+      event_id: data.eventId,
+      created_at: data.createdAt,
+      category: data.category,
+      attributes: {
+        filled_schema: { ...data.attributes.filledSchema },
+        form_response_id: data.attributes.formResponseId,
+        form_type: data.attributes.formType,
+      },
+    };
+  }
+
+  // This is the default app_loaded event, when we start to use app_unloaded we need to handle it here
+  return {
+    event_id: data.eventId,
+    created_at: data.createdAt,
+    category: data.category,
+  };
+};

package/src/application/utils/divideArray.ts

@@ -0,0 +1,7 @@
+export const divideArray = <T>(array: T[], size: number) => {
+  const rows = [];
+  for (let i = 0; i < size; i += 1) {
+    rows.push(array.filter((_: T, index: number) => index % size === i));
+  }
+  return rows;
+};

package/src/application/utils/domObserver.ts

@@ -0,0 +1,96 @@
+import { ElementObserver } from './elementObserver';
+import { NodeSelector } from './nodeSelector';
+
+/**
+ * This class manages a `MutationObserver` for the `document.body`. It monitors nodes that are
+ * added or removed from the DOM and notifies the observers for each observable element
+ * when they are ready to be watched.
+ *
+ * How that works:
+ *
+ * When the `observe` function is called, it attaches a `MutationObserver` to the `document.body` element.
+ * All changes to `document.body` are tracked by this observer. When changes are detected, the `MutationObserver`
+ * iterates through all added and removed nodes and checks if each node exists in the main map of observable elements.
+ *
+ * If a match is found, it notifies the corresponding `ElementObserver` instance to start monitoring changes for that element.
+ *
+ * The primary `MutationObserver` remains active until the `destroy` function is called. Calling `destroy` will disconnect all
+ * individual element observers and release any associated resources.
+ *
+ * There is no need to explicitly call the `observe` function. It is automatically invoked when a `useElementObserver` hook is instantiated.
+ *
+ */
+export class DOMObserver {
+  private static documentObserver: MutationObserver | null;
+  private static listeners: Map<string, ElementObserver> = new Map();
+
+  private static notifyAdition(records: MutationRecord[], nodeMapping: Map<Node, ElementObserver>) {
+    records.forEach((record) =>
+      record.addedNodes.forEach((node) => {
+        nodeMapping.get(node)?.watch(node);
+        nodeMapping.delete(node);
+      }),
+    );
+  }
+
+  private static notifyRemoval(records: MutationRecord[], nodeMapping: Map<Node, ElementObserver>) {
+    records.forEach((record) =>
+      record.removedNodes.forEach((node) => {
+        nodeMapping.get(node)?.destroy();
+        nodeMapping.delete(node);
+      }),
+    );
+  }
+
+  private static notifyChildrenChanges(nodeMapping: Map<Node, ElementObserver>) {
+    Array.from(nodeMapping.values()).forEach((observer) => observer.synchronize());
+  }
+
+  private static mapNodeInstancesToListeners(): Map<Node, ElementObserver> {
+    const nodeMapping = new Map<Node, ElementObserver>();
+    this.listeners.forEach((observer) => {
+      const node = observer.getNode() || observer.getSelector()?.parse();
+      if (node) {
+        nodeMapping.set(node, observer);
+      }
+    });
+    return nodeMapping;
+  }
+
+  static add(selector: NodeSelector): ElementObserver {
+    const node = selector.getPattern();
+    let elementObserver = this.listeners.get(node);
+    if (elementObserver) {
+      return elementObserver;
+    }
+
+    elementObserver = new ElementObserver(selector);
+    this.listeners.set(node, elementObserver);
+    return elementObserver;
+  }
+
+  static remove(selector: NodeSelector) {
+    const node = selector.getPattern();
+    this.listeners.get(node)?.destroy();
+    this.listeners.delete(node);
+  }
+
+  static observe() {
+    if (!this.documentObserver) {
+      this.documentObserver = new MutationObserver((mutations) => {
+        const nodeMapping = this.mapNodeInstancesToListeners();
+        this.notifyAdition(mutations, nodeMapping);
+        this.notifyRemoval(mutations, nodeMapping);
+        this.notifyChildrenChanges(nodeMapping);
+      });
+      this.documentObserver.observe(document.body, { childList: true, subtree: true });
+    }
+  }
+
+  static destroy() {
+    this.documentObserver?.disconnect();
+    this.listeners.forEach((listener) => listener.destroy());
+    this.listeners.clear();
+    this.documentObserver = null;
+  }
+}

package/src/application/utils/elementObserver.ts

@@ -0,0 +1,246 @@
+import { ReactElement } from 'react';
+import { createPortal } from 'react-dom';
+import { MouseEventTypes } from './mouseEventTypes';
+import { MutationHelper } from './mutationHelper';
+import { NodeSelector } from './nodeSelector';
+
+/**
+ * The `ElementObserver` class monitors all changes related to the specific element it is responsible for.
+ * It is automatically instantiated by the `useElementObserver` hook, which manages all instances of this class.
+ *
+ * How it works:
+ *
+ * Each instance of `ElementObserver` holds several pieces of information related to the node it is monitoring,
+ * such as the node's selector and its `MutationObserver`. This class is responsible for translating raw node
+ * changes into a more user-friendly format. For example, when the node is added to the DOM, the `ElementObserver`
+ * is notified by the `DOMObserver`, which triggers the `onAdd` callback function on the respective `useElementObserver`
+ * instance.
+ *
+ * Instances of `ElementObserver` are fully managed by the `useElementObserver` hook, requiring no additional configuration.
+ * When the hook is destroyed, its corresponding `ElementObserver` instance is automatically removed.
+ *
+ */
+export class ElementObserver {
+  private mutation: MutationObserver | null;
+
+  private node: HTMLElement | null;
+
+  private selector: NodeSelector;
+
+  private eventListeners: Map<keyof HTMLElementEventMap, EventListenerOrEventListenerObject>;
+
+  private classAdded: Map<string, () => void>;
+
+  private classRemoved: Map<string, () => void>;
+
+  private nodeDisplay: string;
+
+  private addFn: (el: HTMLElement | null) => void;
+
+  private removeFn: (el: HTMLElement | null) => void;
+
+  private changeFn: (el: HTMLElement | null) => void;
+
+  private classChangeFn: (classes?: DOMTokenList) => void;
+
+  private addChildFn?: () => void;
+
+  private removeChildFn?: () => void;
+
+  private resetFn: () => void;
+
+  constructor(selector: NodeSelector) {
+    this.selector = selector;
+    this.mutation = null;
+    this.node = null;
+    this.eventListeners = new Map();
+    this.classAdded = new Map();
+    this.classRemoved = new Map();
+    this.nodeDisplay = 'block';
+    this.addFn = () => {};
+    this.removeFn = () => {};
+    this.changeFn = () => {};
+    this.classChangeFn = () => {};
+    this.addChildFn = undefined;
+    this.removeChildFn = undefined;
+    this.resetFn = () => {};
+  }
+
+  private handleAttributes(mutationRecord: MutationRecord[]) {
+    mutationRecord.filter(MutationHelper.isClass).forEach((mutation) => {
+      MutationHelper.fireClassChange(mutation, this.node, this.classChangeFn);
+      MutationHelper.fireClassAdded(mutation, this.node, this.classAdded);
+      MutationHelper.fireClassRemoved(mutation, this.node, this.classRemoved);
+    });
+  }
+
+  private handleChildList(mutationRecord: MutationRecord[]) {
+    if (!this.addChildFn && !this.removeChildFn) {
+      return;
+    }
+
+    mutationRecord.filter(MutationHelper.isChildList).forEach((mutation) => {
+      MutationHelper.fireSubtreeChange(mutation.addedNodes, this.addChildFn);
+      MutationHelper.fireSubtreeChange(mutation.removedNodes, this.removeChildFn);
+    });
+  }
+
+  private addInitialListeners() {
+    this.eventListeners.forEach((v, k) => this.node?.addEventListener(k, v));
+  }
+
+  private clearEventListeners() {
+    this.eventListeners.forEach((v, k) => this.node?.removeEventListener(k, v));
+    this.eventListeners.clear();
+  }
+
+  private renew(newNode: Node | null) {
+    if (newNode) {
+      this.destroy();
+      this.watch(newNode);
+    }
+  }
+
+  getSelector() {
+    return this.selector;
+  }
+
+  getNode() {
+    return this.node;
+  }
+
+  synchronize() {
+    const parsedNode = this.getSelector().parse();
+
+    if (this.getNode() !== parsedNode) {
+      this.renew(parsedNode);
+      return;
+    }
+
+    if (!this.getNode() && parsedNode) {
+      this.watch(parsedNode);
+      return;
+    }
+
+    if (this.getNode() && !parsedNode) {
+      this.destroy();
+    }
+  }
+
+  init() {
+    const node = this.getSelector().parse();
+    if (node) {
+      this.watch(node);
+    }
+  }
+
+  watch(node: Node) {
+    if (!this.mutation) {
+      this.mutation = new MutationObserver((mutationRecord) => {
+        this.handleAttributes(mutationRecord);
+        this.handleChildList(mutationRecord);
+        this.changeFn(this.node);
+      });
+      this.mutation.observe(node, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeOldValue: true,
+      });
+      this.node = node as HTMLElement;
+      this.addFn(this.node);
+      this.addInitialListeners();
+    }
+  }
+
+  destroy() {
+    this.resetFn();
+    this.removeFn(this.node);
+    this.mutation?.disconnect();
+    this.clearEventListeners();
+    this.classAdded.clear();
+    this.classRemoved.clear();
+    this.mutation = null;
+    this.node = null;
+  }
+
+  render(fn: () => ReactElement) {
+    if (this.node) {
+      return createPortal(fn(), this.node);
+    }
+  }
+
+  fire(event: MouseEventTypes) {
+    if (this.node) {
+      this.node.dispatchEvent(
+        new MouseEvent(event, {
+          bubbles: true,
+          cancelable: true,
+          view: window,
+        }),
+      );
+    }
+  }
+
+  show() {
+    const display = this.node?.style.display;
+    if (this.node && display === 'none') {
+      this.node.style.display = this.nodeDisplay || 'block';
+    }
+  }
+
+  hide() {
+    const display = this.node?.style.display;
+    if (this.node && display !== 'none') {
+      this.nodeDisplay = display || 'block';
+      this.node.style.display = 'none';
+    }
+  }
+
+  registerEvent(event: keyof HTMLElementEventMap, fn: EventListenerOrEventListenerObject) {
+    if (this.node) {
+      const previousFn = this.eventListeners.get(event);
+      if (previousFn) {
+        this.node.removeEventListener(event, previousFn);
+      }
+      this.node.addEventListener(event, fn);
+    }
+    this.eventListeners.set(event, fn);
+  }
+
+  registerOnReset(fn: () => void) {
+    this.resetFn = fn;
+  }
+
+  registerOnChange(fn: (el: HTMLElement | null) => void) {
+    this.changeFn = fn;
+  }
+
+  registerOnAdd(fn: (el: HTMLElement | null) => void) {
+    this.addFn = fn;
+  }
+
+  registerOnRemove(fn: (el: HTMLElement | null) => void) {
+    this.removeFn = fn;
+  }
+
+  registerOnclassChange(fn: (classes?: DOMTokenList) => void) {
+    this.classChangeFn = fn;
+  }
+
+  registerOnAddChild(fn: (classes?: DOMTokenList) => void) {
+    this.addChildFn = fn;
+  }
+
+  registerOnRemoveChild(fn: (classes?: DOMTokenList) => void) {
+    this.removeChildFn = fn;
+  }
+
+  registerOnClassAdded(className: string, fn: () => void) {
+    this.classAdded.set(className, fn);
+  }
+
+  registerOnClassRemoved(className: string, fn: () => void) {
+    this.classRemoved.set(className, fn);
+  }
+}