@envive-ai/react-hooks 0.1.0

package/src/hooks/useSnapControl.ts

@@ -0,0 +1,155 @@
+import {
+  MotionValue,
+  transform,
+  useAnimate,
+  useMotionValue,
+  useTransform,
+  ValueAnimationTransition,
+} from 'framer-motion';
+import { useMemo, useState } from 'react';
+import { Unit, useSnapCalculator } from './useSnapCalculator';
+
+type SnapControl = {
+  animationKey?: MotionValue;
+  animation: ValueAnimationTransition;
+  height: number;
+  unit: Unit;
+  snaps: number[];
+  initSnap: number;
+  threshold?: number;
+  overlayOpacity: number;
+  onSnapComplete: (currentSnap: number, nextSnap: number, collapsed: boolean) => void;
+};
+
+const MIDDLE_SNAP_OFFSET = 5;
+const SNAP_DISTANCE_OFFSET = 50;
+
+export const useSnapControl = ({
+  animationKey,
+  animation,
+  height,
+  unit,
+  snaps,
+  initSnap,
+  onSnapComplete,
+  overlayOpacity,
+}: SnapControl) => {
+  const [scope, animate] = useAnimate();
+  const animatedY = animationKey || useMotionValue(-1);
+
+  const { swipeviewHeightPx, snapsToPixels, viewportHeightPx, getPixelToSnap, getSnapToPixel } =
+    useSnapCalculator(snaps, height, unit);
+
+  const contentHeight = useTransform(animatedY, [0, swipeviewHeightPx], [swipeviewHeightPx, 0]);
+
+  const snapOverlayReference = useMemo(
+    () => [
+      getSnapToPixel(snaps[0]),
+      getSnapToPixel(snaps[1]) - MIDDLE_SNAP_OFFSET,
+      getSnapToPixel(snaps[2]),
+    ],
+    [],
+  );
+
+  const displayOverlay = useTransform(() =>
+    animatedY.get() === -1
+      ? 'none'
+      : transform(animatedY.get(), snapOverlayReference, ['none', 'none', 'block']),
+  );
+
+  const opacityOverlay = useTransform(() =>
+    animatedY.get() === -1
+      ? 0
+      : transform(animatedY.get(), snapOverlayReference, [0, 0, overlayOpacity]),
+  );
+
+  const initSnapInPixels = snapsToPixels?.[initSnap];
+  const getInitSnap = () => snaps?.[initSnap];
+  const [currentSnap, setCurrentSnap] = useState<number>(getInitSnap());
+  const between = (x: number, min: number, max: number) => x >= min && x <= max;
+
+  const defineNextSnapByPosition = () => {
+    const scopeEl = scope.current;
+    const currentSnapRef = Math.abs(
+      viewportHeightPx - (swipeviewHeightPx - getSnapToPixel(currentSnap)),
+    );
+
+    const realGestureY =
+      scopeEl.getBoundingClientRect().y +
+      scopeEl.getBoundingClientRect().height -
+      (window.innerHeight - document.documentElement.clientHeight);
+
+    const isGoingUp = realGestureY < currentSnapRef;
+
+    const snapsToPixelsClone = Array.from(snapsToPixels);
+    isGoingUp
+      ? snapsToPixelsClone.sort((a, b) => b - a) /* desc*/
+      : snapsToPixelsClone.sort((a, b) => a - b); /* asc */
+
+    if (realGestureY != currentSnapRef) {
+      const snapReference = snapsToPixelsClone.find((snap) => {
+        const current = Math.abs(viewportHeightPx - (swipeviewHeightPx - snap));
+        return isGoingUp ? current < realGestureY : current > realGestureY;
+      });
+
+      if (snapReference === undefined) {
+        return snapsToPixelsClone.slice(-1)[0];
+      }
+
+      const prevSnapIndex = snapsToPixelsClone.indexOf(snapReference ?? -1);
+      const prevSnap = snapsToPixelsClone[prevSnapIndex - 1];
+      const prevSnapPx = Math.abs(viewportHeightPx - (swipeviewHeightPx - prevSnap));
+      const adjacentSnap = between(
+        realGestureY,
+        prevSnapPx - SNAP_DISTANCE_OFFSET,
+        prevSnapPx + SNAP_DISTANCE_OFFSET,
+      );
+
+      return adjacentSnap ? prevSnap : snapReference;
+    }
+
+    return getSnapToPixel(currentSnap);
+  };
+
+  const jumpTo = (snapPx: number) => {
+    const collapsed = snapPx === swipeviewHeightPx;
+    const nextSnap = getPixelToSnap(snapPx);
+    animate(
+      scope.current,
+      { y: snapPx },
+      {
+        ...animation,
+        onComplete: () => {
+          onSnapComplete(currentSnap, nextSnap, collapsed);
+          setCurrentSnap(nextSnap);
+        },
+      },
+    );
+
+    return {
+      nextSnap,
+      collapsed,
+    };
+  };
+
+  const resetControls = () => {
+    setCurrentSnap(getInitSnap());
+    return 0;
+  };
+
+  return {
+    scope,
+    animatedY,
+    animate,
+    swipeviewHeightPx,
+    initSnapInPixels,
+    contentHeight,
+    currentSnap,
+    displayOverlay,
+    opacityOverlay,
+    getSnapToPixel,
+    jumpTo,
+    defineNextSnapByPosition,
+    resetControls,
+  };
+};

package/src/hooks/useSystemSettingsContext.ts

@@ -0,0 +1,12 @@
+import { useContext } from 'react';
+import { SystemSettingsContext } from 'src/contexts';
+
+export const useSystemSettingsContext = () => {
+  const context = useContext(SystemSettingsContext);
+
+  if (!context) {
+    throw new Error('useSystemSettingsContext must be used within a SystemSettingsContextProvider');
+  }
+
+  return { ...context };
+};

package/src/hooks/useTrackComponentVisibleEvent.ts

@@ -0,0 +1,52 @@
+import { RefObject, useEffect, useRef } from 'react';
+import { SpiffyWidgets } from 'src/application/models/spiffyWidgets';
+import { useIntersection } from 'src/hooks/useIntersection';
+import { AmplitudeAdapter, SpiffyMetricsEventName } from 'src/adapters/amplitude';
+
+/**
+ * Tracks a component and logs an event to Amplitude when the component is visible.
+ *
+ * @param component - The component to track.
+ * @param element - The element to track visibility of.
+ * @param eventProps - Additional properties to include with the event.
+ * @param eventName - The Amplitude event name to track (defaults to ChatComponentVisible).
+ */
+export const useTrackComponentVisibleEvent = (
+  component: SpiffyWidgets,
+  element: RefObject<HTMLElement>,
+  eventProps?: Record<string, unknown>,
+  eventName: SpiffyMetricsEventName = SpiffyMetricsEventName.ChatComponentVisible,
+) => {
+  const isVisible = useIntersection(element, '0px');
+  const hasTrackedEvent = useRef(false);
+
+  const componentProps = (() => {
+    if (eventName === SpiffyMetricsEventName.ChatComponentVisible) {
+      return {
+        chat_component: component,
+        ...eventProps,
+      };
+    }
+    if (eventName === SpiffyMetricsEventName.SearchComponentVisible) {
+      return {
+        search_component: component,
+        ...eventProps,
+      };
+    }
+    // Default case for other event types
+    return {
+      component: component,
+      ...eventProps,
+    };
+  })();
+
+  useEffect(() => {
+    if (isVisible && !hasTrackedEvent.current) {
+      AmplitudeAdapter.trackEvent({
+        eventName: eventName,
+        eventProps: componentProps,
+      });
+      hasTrackedEvent.current = true;
+    }
+  }, [isVisible, component, eventProps, eventName, componentProps]);
+};

package/src/hooks/useUpdateAnalyticsProps.ts

@@ -0,0 +1,56 @@
+import { useAtomValue } from 'jotai';
+import { useEffect, useRef } from 'react';
+import { AmplitudeAdapter, SpiffyMetricsEventName } from 'src/adapters/amplitude';
+import { hasParsedVariantInfoAtom, variantInfoAtom } from 'src/atoms/app/variant';
+
+/**
+ * Updates the default analytics properties whenever the variant info changes. This hook also
+ * triggers any events that should be sent once per page visit.
+ */
+export const useUpdateAnalyticsProps = () => {
+  const variantInfo = useAtomValue(variantInfoAtom);
+  const amplitudeAdapterRef = useRef<AmplitudeAdapter | null>(null);
+  const hasInitialized = useRef(false);
+  const hasParsedVariantInfo = useAtomValue(hasParsedVariantInfoAtom);
+
+  useEffect(() => {
+    if (!amplitudeAdapterRef.current) {
+      amplitudeAdapterRef.current = AmplitudeAdapter.getSingletonInstanceOf();
+    }
+
+    const variantInfoWithPrefix = Object.fromEntries(
+      Object.entries(variantInfo).map(([key, value]) => [`variantInfo.${key}`, value]),
+    );
+
+    const defaultEventProperties: Record<string, unknown> = {
+      page_variant: variantInfo.variant, // TODO: should be removed over time, after migration
+      ...variantInfoWithPrefix,
+    };
+
+    // TODO: should be removed over time, after migration
+    if (variantInfo.variant === 'pdp') {
+      defaultEventProperties.product_id = variantInfo.productId;
+    }
+
+    // TODO: should be removed over time, after migration
+    if (variantInfo.variant === 'plp') {
+      defaultEventProperties.plp_id = variantInfo.plpId;
+    }
+
+    // TODO: should be removed over time, after migration
+    if (variantInfo.variant === 'page_visit') {
+      defaultEventProperties.page_visit_category = variantInfo.pageVisitCategory;
+      defaultEventProperties.page_visit_url = variantInfo.url;
+    }
+
+    amplitudeAdapterRef.current?.setSupplementalDefaultProps(defaultEventProperties);
+
+    // put any events that should be sent once per page visit here
+    if (!hasInitialized.current && hasParsedVariantInfo) {
+      AmplitudeAdapter.trackEvent({
+        eventName: SpiffyMetricsEventName.BundleLoaded,
+      });
+      hasInitialized.current = true;
+    }
+  }, [variantInfo, hasParsedVariantInfo]);
+};

package/src/hooks/utils.ts

@@ -0,0 +1,153 @@
+import {
+  PLPAttributeCategory,
+  UserEventCategory,
+} from "@spiffy-ai/commerce-api-client";
+import { SearchResult } from "src/application/models/api/search";
+import { UserEvent, VariantInfo } from "src/application/models";
+import { v4 as uuid } from "uuid";
+
+export const isElementPartiallyVisible = (el?: HTMLDivElement | null) => {
+  if (!el) return false;
+
+  const rect = el.getBoundingClientRect();
+  const windowHeight =
+    window.innerHeight || document.documentElement.clientHeight;
+  const windowWidth = window.innerWidth || document.documentElement.clientWidth;
+  const verticallyVisible =
+    Math.round(rect.top) < windowHeight && Math.round(rect.bottom) > 0;
+  const horizontallyVisible =
+    Math.round(rect.left) < windowWidth && Math.round(rect.right) > 0;
+  return verticallyVisible && horizontallyVisible;
+};
+
+export const createAppLoadedEvent = (): UserEvent => ({
+  eventId: uuid(),
+  createdAt: new Date().toISOString(),
+  category: UserEventCategory.AppLoaded,
+});
+
+export const createVisitUserEvent = ({
+  variantInfo,
+}: {
+  variantInfo: VariantInfo;
+}): UserEvent | undefined => {
+  // this is a pdp visit event
+  if (variantInfo.variant === "pdp" && variantInfo.productId != null) {
+    return {
+      eventId: uuid(),
+      createdAt: new Date().toISOString(),
+      category: UserEventCategory.PdpVisit,
+      attributes: {
+        productId: variantInfo.productId,
+        parentProductId: variantInfo.parentProductId ?? "",
+        url: variantInfo.url ?? "",
+      },
+    };
+  }
+
+  // this is a plp visit event
+  if (variantInfo.variant === "plp" && variantInfo.plpId != null) {
+    return {
+      eventId: uuid(),
+      createdAt: new Date().toISOString(),
+      category: UserEventCategory.PlpVisit,
+      attributes: {
+        category: PLPAttributeCategory.Id,
+        attributes: {
+          id: variantInfo.plpId,
+        },
+      },
+    };
+  }
+
+  if (variantInfo.variant === "page_visit") {
+    return {
+      eventId: uuid(),
+      createdAt: new Date().toISOString(),
+      category: UserEventCategory.PageVisit,
+      attributes: {
+        url: variantInfo.url,
+        pageVisitCategory: variantInfo.pageVisitCategory,
+      },
+    };
+  }
+  return undefined;
+};
+
+const parseTime = (time: string, timeZone: string) => {
+  const times = time.match(/^([0-1]?\d):([0-5]\d)(AM|PM)$/i);
+  const hours = times?.[1];
+  const minutes = times?.[2];
+  const period = times?.[3];
+
+  if (hours && minutes && period) {
+    const date = new Date();
+
+    // Adjust hours for AM/PM
+    let adjustedHours = 0;
+    if (period.toUpperCase() === "PM" && hours !== "12") {
+      adjustedHours = parseInt(hours) + 12;
+    }
+
+    if (period.toUpperCase() === "AM" && hours !== "12") {
+      adjustedHours = parseInt(hours);
+    }
+
+    // Create the date string with time zone
+    const formattedDate = `${date.toISOString().split("T")[0]}T${String(
+      adjustedHours
+    ).padStart(2, "0")}:${minutes}:00`;
+    return new Date(`${formattedDate}${timeZone}`);
+  }
+};
+
+export const isWithinBusinessHours = (
+  startTime: string,
+  endTime: string,
+  timeZone: string
+) => {
+  // Parse start and end times
+  const start = parseTime(startTime, timeZone);
+  let end = parseTime(endTime, timeZone);
+
+  if (!start || !end) {
+    return false;
+  }
+
+  let now = new Date();
+
+  // If the end date is greater than the start date, add a day to both of them
+  // This handles configurations such as startTime = 10:00PM and endTime = 7:00AM
+  if (end < start) {
+    end = new Date(end.getTime() + 24 * 60 * 60 * 1000);
+    now = new Date(now.getTime() + 24 * 60 * 60 * 1000);
+  }
+
+  // If the date conversion shifts the end date to the next day, consider comparing it across midnight
+  if (end.getUTCDate() > start.getUTCDate()) {
+    const crossingMidnight = new Date(now.getTime() + 24 * 60 * 60 * 1000);
+    return start <= now || crossingMidnight <= end;
+  }
+
+  // Check if the current time falls between start and end
+  return now >= start && now <= end;
+};
+
+export const enum SearchResultsState {
+  Loading,
+  Results,
+  NoResults,
+}
+
+export const getSearchResultsState = (
+  isLoadingSearch: boolean,
+  searchData: SearchResult | null
+): SearchResultsState => {
+  if (isLoadingSearch) {
+    return SearchResultsState.Loading;
+  }
+  if (searchData) {
+    return SearchResultsState.Results;
+  }
+  return SearchResultsState.NoResults;
+};

package/src/index.ts

@@ -0,0 +1,31 @@
+import Logger from 'src/application/logging/logger';
+import { EnvironmentService } from 'src/application/service/environmentService';
+import { getAtomStore } from 'src/atoms/atomStore';
+import {
+  appInitialStartTimeMsAtom,
+  pageLoadOffsetTimeAtom,
+} from 'src/atoms/chat';
+import { init } from 'src/initialize';
+
+// store the initial start time of the app in session storage. This is used to calculate
+// deltas for performance metrics downstream.
+const atomStore = getAtomStore();
+const appInitialStartTimeMs = Date.now();
+const pageLoadOffsetTime = window.performance?.now();
+
+Logger.logDebug(
+  `[spiffy-ai] storing appInitialStartTimeMs=${appInitialStartTimeMs} - offset ${pageLoadOffsetTime}`,
+);
+atomStore.set(appInitialStartTimeMsAtom, appInitialStartTimeMs.toString());
+atomStore.set(pageLoadOffsetTimeAtom, pageLoadOffsetTime.toString());
+
+const initApp = async () => {
+  const existing = window[EnvironmentService.getIdentifyingPrefix()] || {};
+  window[EnvironmentService.getIdentifyingPrefix()] = {
+    ...existing,
+    init,
+  };
+  await init();
+};
+
+initApp();

package/src/initialize.ts

@@ -0,0 +1,163 @@
+import Logger from "src/application/logging/logger";
+// this import brings in amplitude and a bunch of other large libraries
+import { EnvironmentService } from "src/application/service/environmentService";
+import {
+  LocalStorageKeys,
+  LocalStorageService,
+} from "src/application/service/localStorageService";
+import { UserIdentityService } from "src/application/service/userIdentityService";
+import { initWindowFrontendConfigOverridesApplyFunction } from "src/application/service/windowFrontendConfigService";
+import {
+  initAmplitude,
+  initDataLayerWrapper,
+} from "src/application/utils/analyticsUtils";
+import { getAtomStore } from "src/atoms/atomStore";
+import {
+  apiKeyAtom,
+  featureFlagServiceAtom,
+  getAsyncOrgConfig,
+} from "src/atoms/org/org";
+import { EnabledFeatures } from "src/enabled-features";
+import {
+  EXTENSION_ID,
+  tellExtensionAboutInjectionError,
+  tellExtensionInjectionIsLoading,
+} from "src/extension";
+
+const handleSpiffyOn = () => {
+  const spiffyOn = new URLSearchParams(window.location.search).get(
+    LocalStorageKeys.SpiffyOnOverride
+  );
+  const enviveOn = new URLSearchParams(window.location.search).get(
+    LocalStorageKeys.EnviveOnOverride
+  );
+
+  const isOn = spiffyOn === "true" || enviveOn === "true";
+  if (spiffyOn == null && enviveOn == null) {
+    return;
+  }
+
+  if (isOn === true) {
+    LocalStorageService.setSpiffyOnFeatureFlag(true);
+    return;
+  }
+
+  LocalStorageService.setSpiffyOnFeatureFlag(false);
+  // Do nothing for missing or other values
+};
+
+const getEntryPoint = (): string => {
+  // If `spiffy_main_file` query param is set - use an alternate file for injection
+  const queryParamName = `${EnvironmentService.getIdentifyingPrefix()}_main_file`;
+  const overrideParam = new URLSearchParams(window.location.search).get(
+    queryParamName
+  );
+  if (overrideParam) {
+    return overrideParam;
+  }
+  // #if (VITE_IS_LOCAL_ENV=="true")
+  return "/src/main.tsx";
+  // #else
+  return new URL("./main.js", import.meta.url).toString();
+  // #endif
+};
+
+const loadAndInit = async () => {
+  // #if (VITE_SPLIT_BUILD=="true")
+  const script = document.createElement("script");
+  script.innerHTML = `
+  import('${getEntryPoint()}').then(async ({ initApp, tellExtensionAboutInjectionError }) => {
+    try {
+      if (document.readyState === 'loading') {
+        console.log('[spiffy-ai] document.body is not defined, waiting for DOMContentLoaded');
+        document.addEventListener('DOMContentLoaded', initApp);
+      } else {
+        await initApp();
+      }
+    } catch (e) {
+      await tellExtensionAboutInjectionError(e);
+    }
+  }).catch(async (e) => {
+    if (window.chrome && window.chrome.runtime) {
+      await window.chrome.runtime.sendMessage(
+        '${EXTENSION_ID}',
+        { msg: "spiffy-extension-info-update", error: e.message, isLoading: false, isInjected: false },
+      );  
+    }
+  })`;
+  script.type = "module";
+  script.id = "spiffy-injection-script";
+  document.head.appendChild(script);
+  // #else
+  const { initApp } = await import("./main.tsx");
+  await initApp();
+  // #endif
+};
+
+/**
+ * Checks if Spiffy is enabled for the current merchant and initializes the main bundle.
+ * If Spiffy is disabled, it initializes analytics only.
+ *
+ * @param apiKeyOverride - Optional API key to use instead of the key configured for the
+ * merchant. This should only be used for local development to toggle between different
+ * merchants.
+ *
+ * @returns True if Spiffy is enabled, false otherwise.
+ */
+export const init = async (apiKeyOverride?: string) => {
+  if (window[EnvironmentService.getIdentifyingPrefix()]?.isInitialized) {
+    Logger.logDebug(`[spiffy-ai] Spiffy is already initialized`);
+    return true;
+  }
+
+  try {
+    await tellExtensionInjectionIsLoading();
+
+    handleSpiffyOn();
+    const atomStore = getAtomStore();
+    const apiKey = apiKeyOverride ?? atomStore.get(apiKeyAtom);
+    const orgConfig = await getAsyncOrgConfig(apiKey);
+
+    if (!orgConfig.org) {
+      throw new Error("orgConfig is required but is undefined");
+    }
+
+    if (!window._spiffy) {
+      window._spiffy = {};
+    }
+
+    const featureFlagService = atomStore.get(featureFlagServiceAtom);
+
+    const enabledFeatures = await EnabledFeatures.get(
+      orgConfig,
+      featureFlagService
+    );
+
+    // Force initialization of the AmplitudeAdapter now,
+    // so that we automatically immediately send a Page Viewed event,
+    // regardless of whether Spiffy is enabled or not.
+    initAmplitude();
+    initDataLayerWrapper();
+    // Attach a function so callers can explicitly apply overrides to FrontendConfig
+    initWindowFrontendConfigOverridesApplyFunction();
+    await UserIdentityService.identifyUser();
+
+    if (enabledFeatures.envive) {
+      // #if (VITE_IS_CODE_SPLIT_BUILD=="true")
+      const { initApp } = await import("./main");
+      await initApp();
+      // #else
+      await loadAndInit();
+      // #endif
+      return true;
+    }
+
+    await tellExtensionAboutInjectionError({
+      message: "Spiffy is disabled",
+    } as Error);
+    return false;
+  } catch (error: any) {
+    await tellExtensionAboutInjectionError(error);
+    throw error;
+  }
+};

package/src/interceptors/types.ts

@@ -0,0 +1,6 @@
+import { Response } from 'src/application/models';
+
+export interface MessageInterceptor {
+  execute: (response: Response) => void | Promise<void>;
+  blockExecution: () => boolean;
+}

package/src/interceptors/useFormEscalation.ts

@@ -0,0 +1,40 @@
+import { FormType, ResponseCategory } from '@spiffy-ai/commerce-api-client';
+import { useAtomValue, useSetAtom } from 'jotai';
+import { Response } from 'src/application/models';
+import { handleFormSubmittedAtom } from 'src/atoms/chat';
+import { apiKeyAtom, endpointURLAtom } from 'src/atoms/org/org';
+import { orgCustomerServiceService } from 'src/atoms/org/orgUIConfig';
+import { MessageInterceptor } from './types';
+
+export const useFormEscalation = (): MessageInterceptor => {
+  const handleFormSubmitted = useSetAtom(handleFormSubmittedAtom);
+  const customerServiceIntegration = useAtomValue(orgCustomerServiceService);
+  const apiKey = useAtomValue(apiKeyAtom);
+  const apiEndpoint = useAtomValue(endpointURLAtom);
+
+  const blockExecution = () => true;
+
+  const execute = async (response: Response) => {
+    if (
+      response.category === ResponseCategory.Form &&
+      response.attributes.formCategory?.formType === FormType.Escalation
+    ) {
+      const isEnabled = customerServiceIntegration.isEnabled();
+      const isBusinessHours = await customerServiceIntegration.isBusinessHours(apiKey, apiEndpoint);
+
+      handleFormSubmitted({
+        formResponseId: response.id,
+        formType: FormType.Escalation,
+        filledSchema: {
+          is_in_business_hours: isBusinessHours,
+          is_integration_enabled: isEnabled,
+        },
+      });
+    }
+  };
+
+  return {
+    execute,
+    blockExecution,
+  };
+};