@envive-ai/react-hooks 0.1.0

package/src/enabled-features.ts

@@ -0,0 +1,83 @@
+import Logger from 'src/application/logging/logger';
+import { LocalStorageService } from 'src/application/service/localStorageService';
+import { getOrgInfo } from 'src/application/models';
+import { OrgConfig } from 'src/application/models/api/orgConfigResults';
+import { FeatureFlagService } from 'src/application/service/featureFlagService';
+
+
+type EnabledFeaturesValues = {
+  envive: boolean;
+  salesAgent: boolean;
+};
+class EnabledFeatures {
+  private static values: EnabledFeaturesValues | undefined = undefined;
+
+  static async get(
+    orgConfig: OrgConfig,
+    featureFlagService: FeatureFlagService,
+  ): Promise<EnabledFeaturesValues> {
+    if (this.values !== undefined) {
+      return this.values;
+    }
+
+    const isSpiffyEnabled = async (orgConfig: OrgConfig, featureFlagService: FeatureFlagService): Promise<boolean> => {
+      // "spiffy_on" is the highest precedence override and typically used for development/testing
+      // skip all other checks if it is "true"
+      if (LocalStorageService.getSpiffyOnFeatureFlag() === 'true') {
+        Logger.logDebug(`[spiffy-ai] spiffy enabled by "spiffy_on" override`);
+        return true;
+      }
+
+      if (LocalStorageService.getSpiffyOnFeatureFlag() === 'false') {
+        Logger.logDebug(`[spiffy-ai] envive disabled by "envive_on" override`);
+        return false;
+      }
+    
+      if (window._spiffy?.show != null && !window._spiffy.show) {
+        Logger.logDebug(`[spiffy-ai] spiffy disabled by window._spiffy.show`);
+        return false;
+      }
+    
+      if (!featureFlagService.isClientSessionEnabled()) {
+        Logger.logDebug(`[spiffy-ai] spiffy disabled by feature flag`);
+        return false;
+      }
+    
+      // this is for when visibility is controlled by the merchant
+      if (window._spiffy?.show != null && window._spiffy.show) {
+        Logger.logDebug(`[spiffy-ai] spiffy enabled by window._spiffy.show`);
+        return true;
+      }
+    
+      // otherwise, spiffy controls the visibility of the experience through a feature flag
+      const orgInfo = await getOrgInfo(orgConfig.org.org.shortName);
+      if (orgInfo.alwaysEnabledMerchants) {
+        Logger.logDebug(`[spiffy-ai] spiffy enabled by org config and feature flag`);
+        return true;
+      }
+    
+      if (featureFlagService.isClientSessionEnabled()) {
+        Logger.logDebug(`[spiffy-ai] spiffy is enabled by feature flag`);
+        return true;
+      }
+    
+      Logger.logDebug(`[spiffy-ai] spiffy is disabled because not all checks have passed`);
+      return false;
+    };
+  
+    const isSalesAgentEnabled = isSpiffyEnabled;
+
+    this.values = {
+      envive: await isSpiffyEnabled(orgConfig, featureFlagService),
+      salesAgent: await isSalesAgentEnabled(orgConfig, featureFlagService),
+    };
+
+    return this.values;
+  }
+
+  static reset() {
+    this.values = undefined;
+  }
+}
+
+export { EnabledFeatures };

package/src/events/event-types.ts

@@ -0,0 +1,11 @@
+export enum SpiffyEvent {
+  AMPLITUDE_EVENT = 'SPIFFY_AMPLITUDE_EVENT',
+  APP_INITIALIZED = 'SPIFFY_APP_INITIALIZED',
+  CALL_MERCHANT_APP = 'SPIFFY_CALL_MERCHANT_APP',
+  MOUNTING_MERCHANT_APP = 'SPIFFY_MOUNTING_MERCHANT_APP',
+  CHAT_FACTORY_INITIALIZED = 'SPIFFY_CHAT_FACTORY_INITIALIZED',
+  FLOATING_CHAT_RENDERING = 'SPIFFY_FLOATING_CHAT_RENDERING',
+  FLOATING_CHAT_NOT_RENDERING = 'SPIFFY_FLOATING_CHAT_NOT_RENDERING',
+  FLOATING_CHAT_BUTTON_RENDERING = 'SPIFFY_FLOATING_CHAT_BUTTON_RENDERING',
+  SHADOW_DOM_CONTAINER_READY = 'SPIFFY_SHADOW_DOM_CONTAINER_READY',
+}

package/src/events/index.ts

@@ -0,0 +1,52 @@
+export { SpiffyEvent } from './event-types';
+
+/**
+ * A singleton class for dispatching Spiffy events to the document object.
+ * Provides functionality for adding default event data, managing listeners,
+ * and dispatching events.
+ * 
+ * TODO: could add observability to the listeners, would need to track listeners
+ * internally.
+ */
+export class EventsDispatcher {
+
+  static eventData: Record<string, any> = {};
+
+  /**
+   * Adds event data to the eventData object, which is included by default for
+   * every event dispatched. E.g. could add in userId, variantInfo, etc. But
+   * make sure it is JSON serializable.
+   */
+  static addEventData(data: Record<string, any>) {
+    this.eventData = { ...this.eventData, ...data };
+  }
+
+  /**
+   * Dispatches an event with the given name and detail. If includeDefault is
+   * false, the default event data is excluded.
+   * @param eventName - the name of the event to dispatch, should be all caps
+   *   and start with SPIFFY_, e.g. "SPIFFY_FLOATING_CONTAINER_CREATED"
+   * @param detail - optional parameter to include extra event data
+   * @param includeDefault - optional parameter to exclude the default event
+   *   data
+   */
+  static dispatch(eventName: string, detail?: Record<string, any>, includeDefault?: boolean) {
+    if (detail === undefined) {
+      detail = {};
+    }
+    if (includeDefault === undefined) {
+      includeDefault = true;
+    }
+    const eventData = includeDefault ? { ...this.eventData, ...detail } : detail;
+    const event = new CustomEvent(eventName, { detail: eventData, bubbles: true, composed: true, cancelable: false });
+    window.dispatchEvent(event);
+  }
+
+  static addListener(eventName: string, listener: (event: Event) => void) {
+    window.addEventListener(eventName, listener, { once: false, passive: false, capture: false });
+  }
+
+  static removeListener(eventName: string, listener: (event: Event) => void) {
+    window.removeEventListener(eventName, listener);
+  }
+}

package/src/events/registerAnalyticsListeners.ts

@@ -0,0 +1,49 @@
+import { AmplitudeAdapter, SpiffyMetricsEventName } from 'src/adapters/amplitude';
+import { getAtomStore } from 'src/atoms/atomStore';
+import {
+  pageLoadOffsetTimeAtom,
+  performanceMetricsAtom,
+  resetPerformanceMetricsAtom,
+} from 'src/atoms/chat';
+
+const registerPerformanceMetricsListener = () => {
+  const atomStore = getAtomStore();
+  const performanceMetrics = atomStore.get(performanceMetricsAtom);
+  const pageLoadOffsetTime = atomStore.get(pageLoadOffsetTimeAtom);
+
+  const handleVisibilityChange = () => {
+    if (document.visibilityState === 'hidden' && performanceMetrics.size > 0) {
+      const perfMetricsProperties = Object.fromEntries(
+        Array.from(performanceMetrics.entries()).map(([key, value]) => [
+          `performanceMetrics.${key}`,
+          value,
+        ]),
+      );
+
+      AmplitudeAdapter.trackEvent({
+        eventName: SpiffyMetricsEventName.PerformanceMetrics,
+        eventProps: {
+          ...perfMetricsProperties,
+          'performance_metrics.page_load_offset_ms': pageLoadOffsetTime,
+        },
+      });
+      resetPerformanceMetricsAtom();
+    }
+  };
+
+  // do not use anything other than visibilitychange to detect when a page or
+  // session has ended as other events may not fire in all browsers/devices
+  window.addEventListener('visibilitychange', handleVisibilityChange);
+
+  return () => {
+    window.removeEventListener('visibilitychange', handleVisibilityChange);
+  };
+};
+
+export const registerAnalyticsListeners = () => {
+  const cleanupPerformanceMetricsListener = registerPerformanceMetricsListener();
+
+  return () => {
+    cleanupPerformanceMetricsListener();
+  };
+};

package/src/extension.ts

@@ -0,0 +1,63 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+
+import Logger from './application/logging/logger';
+
+export type ExtensionInfo = {
+  isLoading: boolean;
+  isInjected: boolean;
+  error?: string | null;
+};
+
+enum MessageTypes {
+  ExtensionInfoUpdate = 'spiffy-extension-info-update',
+}
+
+export const EXTENSION_ID = 'ohickcjdalobhoohmnpjnmgaalphmdje';
+
+const sendMessageToExtensionHost = (type: MessageTypes, payload: ExtensionInfo) => {
+  if (!window.chrome?.runtime) {
+    return Logger.logDebug(
+      '[spiffy-ai] Extension runtime is not exposed, so not sending message',
+      undefined,
+    );
+  }
+
+  return window.chrome.runtime
+    .sendMessage(EXTENSION_ID, { msg: type, ...payload })
+    .then((_response: any) => {
+      if (window.chrome.runtime.lastError) {
+        Logger.logError(window.chrome.runtime.lastError, undefined);
+      } else {
+        Logger.logDebug('[spiffy-ai] Received response from extension host');
+      }
+    })
+    .catch(() => {
+      Logger.logDebug('[spiffy-ai] Unable to log extension message', type, payload);
+    });
+};
+
+export const tellExtensionInjectionIsLoading = () => {
+  return sendMessageToExtensionHost(MessageTypes.ExtensionInfoUpdate, {
+    isLoading: true,
+    isInjected: false,
+    error: null,
+  });
+};
+
+// This is being used in the dynamic script we build and run in the browser.
+export const tellExtensionAboutInjectionError = (error: Error) => {
+  return sendMessageToExtensionHost(MessageTypes.ExtensionInfoUpdate, {
+    isLoading: false,
+    isInjected: false,
+    error: error.message,
+  });
+};
+
+// This is being used in the dynamic script we build and run in the browser.
+export const tellExtensionAboutSuccessfullInjection = () => {
+  return sendMessageToExtensionHost(MessageTypes.ExtensionInfoUpdate, {
+    isLoading: false,
+    isInjected: true,
+    error: null,
+  });
+};

package/src/hooks/index.ts

@@ -0,0 +1,22 @@
+export * from "./useBlockBackButton";
+export * from "./useChatToggle";
+export * from "./useCustomerSupportHandoff";
+export * from "./useDebounce";
+export * from "./useDynamicVariants";
+export * from "./useElementObserver";
+export * from "./useFileUpload";
+export * from "./useGrabAndScroll";
+export * from "./useHideElements";
+export * from "./useHorizontalScrollAnimation";
+export * from "./useImageResolver";
+export * from "./useIntersection";
+export * from "./useIsSmallScreen";
+export * from "./useMessageFilter";
+export * from "./useMessageScrollObserver";
+export * from "./useReducedMotionWithOverride";
+export * from "./useSearch";
+export * from "./useSnapCalculator";
+export * from "./useSnapControl";
+export * from "./useSystemSettingsContext";
+export * from "./useTrackComponentVisibleEvent";
+export * from "./useUpdateAnalyticsProps";

package/src/hooks/useBlockBackButton.ts

@@ -0,0 +1,29 @@
+import { useEffect } from "react";
+
+export const useBlockBackButton = (enabled: boolean, callback: () => void) => {
+
+  useEffect(() => {
+    if (enabled && window) {
+
+      if (window.history.scrollRestoration) {
+        window.history.scrollRestoration = "manual"
+      }
+
+      window.history.pushState(null, document.title, window.location.href);
+      window.onpopstate = (e) => {
+        e.preventDefault();
+        window.history.pushState(null, document.title, window.location.href);
+        callback?.()
+      };
+    }
+
+    return () => {
+      if (enabled && window) {
+        window.history.back()
+        window.onpopstate = null
+        window.history.scrollRestoration = "auto";
+      }
+    }
+  }, [enabled])
+
+}

package/src/hooks/useChatToggle.ts

@@ -0,0 +1,66 @@
+import { useAtomValue, useSetAtom } from "jotai";
+import { ChatElementDisplayLocation } from "src/application/models/chatElementDisplayLocation";
+import { chatAtom, chatOnToggleAtom } from "src/atoms/chat";
+import {
+  AmplitudeAdapter,
+  SpiffyMetricsEventName,
+} from "src/adapters/amplitude";
+
+export const useChatToggle = () => {
+  const onToggle = useSetAtom(chatOnToggleAtom);
+  const { isOpen } = useAtomValue(chatAtom);
+
+  const toggle = (
+    triggerLocation: ChatElementDisplayLocation,
+    triggerId?: string
+  ) => {
+    if (!isOpen) {
+      AmplitudeAdapter.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatComponentExpanded,
+        eventProps: {
+          message_metadata: {
+            trigger_location: triggerLocation,
+            trigger_id: triggerId,
+          },
+        },
+      });
+    } else {
+      AmplitudeAdapter.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatComponentCollapsed,
+        eventProps: {
+          message_metadata: {
+            trigger_location: triggerLocation,
+            trigger_id: triggerId,
+          },
+        },
+      });
+    }
+
+    onToggle();
+  };
+
+  const openChat = (
+    triggerLocation: ChatElementDisplayLocation,
+    triggerId?: string
+  ) => {
+    if (!isOpen) {
+      toggle(triggerLocation, triggerId);
+    }
+  };
+
+  const closeChat = (
+    triggerLocation: ChatElementDisplayLocation,
+    triggerId?: string
+  ) => {
+    if (isOpen) {
+      toggle(triggerLocation, triggerId);
+    }
+  };
+
+  return {
+    toggle,
+    isOpen,
+    openChat,
+    closeChat,
+  };
+};

package/src/hooks/useCustomerSupportHandoff.ts

@@ -0,0 +1,39 @@
+import Logger from 'src/application/logging/logger';
+import { useCallback } from 'react';
+
+/**
+ * Hook to call the `click` method of the merchant's customer support chat widget.
+ *
+ * @param onSwitchToAgent a function to override the function returned by the hook. This is mainly to
+ * preserve backward compatibility for merchants not using Kustomer and will be removed when all
+ * CS integrations are handled.
+ *
+ * @returns a function that searches for the customer support chat widget and calls the `click` method.
+ */
+export const useCustomerSupportHandoff = (onSwitchToAgent?: () => void) => {
+  // TODO handle Gorgias
+
+  const onKustomerSwitch = useCallback(() => {
+    const kustomerElement = document.getElementById('kustomer-ui-sdk-iframe');
+
+    if (kustomerElement == null || !(kustomerElement instanceof HTMLIFrameElement)) {
+      Logger.logError('[spiffy-ai] Kustomer iFrame element not found', undefined);
+      return;
+    }
+
+    const kustomerButton = kustomerElement.contentWindow?.document?.getElementById('rootChatIcon');
+
+    if (kustomerButton == null) {
+      Logger.logError('[spiffy-ai] Kustomer button not found', undefined);
+      return;
+    }
+
+    kustomerButton.click();
+  }, []);
+
+  if (onSwitchToAgent != null) {
+    return { onSwitch: onSwitchToAgent };
+  }
+
+  return { onSwitch: onKustomerSwitch };
+};

package/src/hooks/useDebounce.ts

@@ -0,0 +1,17 @@
+import { useState, useEffect } from 'react';
+
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/hooks/useDynamicVariants.ts

@@ -0,0 +1,210 @@
+import Logger from 'src/application/logging/logger';
+import { useEffect, useRef, useCallback, useState } from 'react';
+import { useAtom, useAtomValue, useSetAtom } from 'jotai';
+import { variantInfoAtom } from 'src/atoms/app';
+import { PageVariantService } from 'src/application/service/pageVariantService';
+import { orgPageConfigAtom } from 'src/atoms/org/orgPageConfig';
+import { hasParsedVariantInfoAtom, supportedEventAtom } from 'src/atoms/app/variant';
+import { SpiffyMetricsEventName, AmplitudeAdapter } from 'src/adapters/amplitude';
+import { orgUIConfigAtom } from 'src/atoms/org/orgUIConfig';
+import { createAppLoadedEvent, createVisitUserEvent } from 'src/hooks/utils';
+import { queueUserEventAtom } from 'src/atoms/chat/messageQueue';
+import { UserEvent } from 'src/application/models';
+import { UserEventCategory } from '@spiffy-ai/commerce-api-client';
+
+// consider putting this in the org config
+const DEBOUNCE_DELAY_MS = 300;
+
+// a debounced function that sets the location href to prevent rapidly changing urls from
+// causing the variant info to be changed too early
+const debounce = (func: () => void, delay: number): (() => void) => {
+  let timeoutId: NodeJS.Timeout;
+
+  return () => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => func(), delay);
+  };
+};
+
+const isUserEventEqual = (event1: UserEvent | null, event2: UserEvent | null) => {
+  if (!event1 || !event2) {
+    return false;
+  }
+  if (event1.category !== event2.category) {
+    return false;
+  }
+  if (
+    event1.category === UserEventCategory.Search &&
+    event2.category === UserEventCategory.Search
+  ) {
+    return event1.attributes.searchTerm === event2.attributes.searchTerm;
+  }
+  if (
+    event1.category === UserEventCategory.PdpVisit &&
+    event2.category === UserEventCategory.PdpVisit
+  ) {
+    return event1.attributes.productId === event2.attributes.productId;
+  }
+  if (
+    event1.category === UserEventCategory.PlpVisit &&
+    event2.category === UserEventCategory.PlpVisit &&
+    'id' in event1.attributes.attributes &&
+    'id' in event2.attributes.attributes
+  ) {
+    return event1.attributes.attributes.id === event2.attributes.attributes.id;
+  }
+  if (
+    event1.category === UserEventCategory.PageVisit &&
+    event2.category === UserEventCategory.PageVisit
+  ) {
+    return event1.attributes.url === event2.attributes.url;
+  }
+  return false;
+};
+
+export const useDynamicVariants = () => {
+  const orgUIConfig = useAtomValue(orgUIConfigAtom);
+  const locationHrefRef = useRef<string>(window.location.href);
+  const setVariantInfo = useSetAtom(variantInfoAtom);
+  const setSupportedEvent = useSetAtom(supportedEventAtom);
+  const queueUserEvent = useSetAtom(queueUserEventAtom);
+  const [mostRecentUserEvent, setMostRecentUserEvent] = useState<UserEvent | null>(null);
+
+  const orgPageConfig = useAtomValue(orgPageConfigAtom);
+  const debouncedFunc = useRef<(() => void) | null>(null);
+  // we need to fetch org info before we can get the variant info. this prevents the rest of the application
+  // logic from running before that happens. More specifically, we want to have all org and variant states
+  // settled before mounting the ChatContextProvider which will start the session.
+  const [hasParsedVariantInfo, setHasParsedVariantInfo] = useAtom(hasParsedVariantInfoAtom);
+  const animationFrameRef = useRef<number | null>(null);
+  const isBeforeUnload = useRef(false);
+
+  const handleLocationChange = () => {
+    if (animationFrameRef.current) {
+      cancelAnimationFrame(animationFrameRef.current);
+    }
+
+    animationFrameRef.current = requestAnimationFrame(() => {
+      if (locationHrefRef.current !== window.location.href) {
+        debouncedFunc.current?.();
+      }
+    });
+  };
+
+  const handlePageChange = useCallback(async () => {
+    if (isBeforeUnload.current) {
+      return;
+    }
+
+    if (!orgPageConfig) {
+      Logger.logWarn(
+        '[spiffy-ai] orgPageConfig not found. skipping page change handling',
+        undefined,
+      );
+      return;
+    }
+
+    const parsedVariantInfo = await PageVariantService.getVariantInfoWithPageConfig(orgPageConfig);
+
+    if (parsedVariantInfo) {
+      Logger.logDebug('[spiffy-ai] variantInfo changed', parsedVariantInfo);
+      const [newVariantInfo, pageVariantConfig] = parsedVariantInfo;
+
+      setVariantInfo(newVariantInfo);
+      setHasParsedVariantInfo(true);
+
+      const visitEvent = createVisitUserEvent({ variantInfo: newVariantInfo });
+      if (visitEvent && !isUserEventEqual(mostRecentUserEvent, visitEvent)) {
+        setMostRecentUserEvent(visitEvent);
+        queueUserEvent(createAppLoadedEvent());
+        queueUserEvent(visitEvent);
+      }
+
+      const supportedEvent = await PageVariantService.checkSupportedEvent(pageVariantConfig);
+      console.log('useDynamicVariants - supportedEvent', supportedEvent);
+      setSupportedEvent(supportedEvent);
+      AmplitudeAdapter.trackEvent({
+        eventName: SpiffyMetricsEventName.SupportedEvent,
+        eventProps: {
+          ...supportedEvent,
+        },
+      });
+    } else {
+      setHasParsedVariantInfo(false);
+    }
+  }, [
+    orgPageConfig,
+    setVariantInfo,
+    setHasParsedVariantInfo,
+    setSupportedEvent,
+    queueUserEvent,
+    mostRecentUserEvent,
+    setMostRecentUserEvent,
+  ]);
+
+  useEffect(() => {
+    debouncedFunc.current = debounce(() => {
+      locationHrefRef.current = window.location.href;
+      handlePageChange();
+    }, DEBOUNCE_DELAY_MS);
+
+    return () => {
+      debouncedFunc.current = null;
+    };
+  }, [handlePageChange]);
+
+  useEffect(() => {
+    // when navigation happens, the url is updated before the page is unloaded & reloaded
+    // this causes the variant info to be changed first and triggering the hook that fetches
+    // next responses. On non-SPA's, this handler prevents variant info from being updated
+    // and lets the usual initialization sequence update it instead. On SPA's, this is not called
+    // and handleLocationChange is called instead
+    const handleBeforeUnload = () => {
+      setSupportedEvent(undefined);
+      isBeforeUnload.current = true;
+    };
+
+    window.addEventListener('click', handleLocationChange);
+    window.addEventListener('popstate', handleLocationChange);
+    window.addEventListener('beforeunload', handleBeforeUnload);
+
+    return () => {
+      window.removeEventListener('click', handleLocationChange);
+      window.removeEventListener('popstate', handleLocationChange);
+      window.removeEventListener('beforeunload', handleBeforeUnload);
+      // TODO: this is causing the supportedEvent to be undefined for Magento customers
+      // Why is unclear however...
+      // setSupportedEvent(undefined);
+
+      if (animationFrameRef.current) {
+        cancelAnimationFrame(animationFrameRef.current);
+      }
+    };
+  }, [handlePageChange, setSupportedEvent]);
+
+  useEffect(() => {
+    // handle the initial page load and when the variant info is overridden
+    if (!hasParsedVariantInfo) {
+      handlePageChange();
+    }
+  }, [hasParsedVariantInfo, handlePageChange]);
+
+  useEffect(() => {
+    let windowInterval: number | null = null;
+    const { merchantVariantSettings } = orgUIConfig;
+
+    if (merchantVariantSettings?.dynamicVariants?.enabled) {
+      const refreshInterval = merchantVariantSettings?.dynamicVariants?.refreshInterval;
+      windowInterval = window.setInterval(() => {
+        handleLocationChange();
+      }, refreshInterval);
+    }
+
+    return () => {
+      if (windowInterval) {
+        window.clearInterval(windowInterval);
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+};