@dreamhorizonorg/pulse-react-native 0.0.1 → 0.0.3

package/src/navigation/index.ts

@@ -0,0 +1,335 @@
+import { AppState, type AppStateStatus } from 'react-native';
+import type { RefObject } from 'react';
+import type {
+  NavigationContainer,
+  NavigationIntegrationOptions,
+  NavigationRoute,
+} from './navigation.interface';
+import { DEFAULT_NAVIGATION_OPTIONS } from './navigation.interface';
+import { pushRecentRouteKey, LOG_TAGS } from './utils';
+import { discardSpan } from '../trace';
+import {
+  createScreenLoadTracker,
+  type ScreenLoadState,
+  INITIAL_SCREEN_LOAD_STATE,
+} from './screen-load';
+import {
+  createScreenInteractiveTracker,
+  markContentReady,
+  clearGlobalMarkContentReady,
+  type ScreenInteractiveState,
+  INITIAL_SCREEN_INTERACTIVE_STATE,
+} from './screen-interactive';
+import {
+  createScreenSessionTracker,
+  type ScreenSessionState,
+  INITIAL_SCREEN_SESSION_STATE,
+} from './screen-session';
+import { useNavigationTracking as useNavigationTrackingBase } from './useNavigationTracking';
+import { isSupportedPlatform } from '../initialization';
+import PulseReactNativeOtel from '../NativePulseReactNativeOtel';
+import { getFeaturesFromRemoteConfig } from '../config';
+import {
+  PULSE_FEATURE_NAMES,
+  type NavigationFeatureName,
+} from '../pulse.constants';
+
+export type { NavigationRoute, NavigationIntegrationOptions };
+export { DEFAULT_NAVIGATION_OPTIONS } from './navigation.interface';
+
+export interface ReactNavigationIntegration {
+  registerNavigationContainer: (
+    maybeNavigationContainer: unknown
+  ) => () => void;
+  markContentReady: () => void;
+}
+
+function resolveNavigationFeatureState(
+  features: ReturnType<typeof getFeaturesFromRemoteConfig>,
+  featureName: NavigationFeatureName,
+  optionValue: boolean
+): boolean {
+  if (features !== undefined && features !== null)
+    return features[featureName] ?? optionValue;
+  return optionValue;
+}
+
+export function createReactNavigationIntegration(
+  options?: NavigationIntegrationOptions
+): ReactNavigationIntegration {
+  const features = getFeaturesFromRemoteConfig();
+
+  const screenSessionTracking = resolveNavigationFeatureState(
+    features,
+    PULSE_FEATURE_NAMES.SCREEN_SESSION,
+    options?.screenSessionTracking ??
+      DEFAULT_NAVIGATION_OPTIONS.screenSessionTracking
+  );
+
+  const screenNavigationTracking = resolveNavigationFeatureState(
+    features,
+    PULSE_FEATURE_NAMES.RN_SCREEN_LOAD,
+    options?.screenNavigationTracking ??
+      DEFAULT_NAVIGATION_OPTIONS.screenNavigationTracking
+  );
+
+  const screenInteractiveTracking = resolveNavigationFeatureState(
+    features,
+    PULSE_FEATURE_NAMES.RN_SCREEN_INTERACTIVE,
+    options?.screenInteractiveTracking ??
+      DEFAULT_NAVIGATION_OPTIONS.screenInteractiveTracking
+  );
+
+  let navigationContainer: NavigationContainer | undefined;
+  let recentRouteKeys: string[] = [];
+  let isInitialized = false;
+  let appStateSubscription: { remove: () => void } | undefined;
+
+  const screenLoadState: ScreenLoadState = {
+    ...INITIAL_SCREEN_LOAD_STATE,
+  };
+
+  const screenInteractiveState: ScreenInteractiveState = {
+    ...INITIAL_SCREEN_INTERACTIVE_STATE,
+  };
+
+  const screenSessionState: ScreenSessionState = {
+    ...INITIAL_SCREEN_SESSION_STATE,
+  };
+
+  const screenInteractiveTracker = createScreenInteractiveTracker(
+    screenInteractiveTracking,
+    screenInteractiveState,
+    navigationContainer
+  );
+
+  const screenLoadTracker = createScreenLoadTracker(
+    screenNavigationTracking,
+    screenLoadState,
+    () => recentRouteKeys,
+    (key: string) => {
+      recentRouteKeys = pushRecentRouteKey(recentRouteKeys, key);
+    },
+    undefined
+  );
+
+  const screenSessionTracker = createScreenSessionTracker(
+    screenSessionTracking,
+    screenSessionState
+  );
+
+  const setCurrentScreenName = (screenName: string): void => {
+    if (isSupportedPlatform()) {
+      PulseReactNativeOtel.setCurrentScreenName(screenName);
+    }
+  };
+
+  const onNavigationDispatch = (): void => {
+    try {
+      if (screenInteractiveTracking) {
+        screenInteractiveTracker.discardScreenInteractive(
+          'user navigated away'
+        );
+      }
+
+      if (
+        screenSessionTracking &&
+        screenSessionState.screenSessionSpan &&
+        navigationContainer
+      ) {
+        const currentRoute = navigationContainer.getCurrentRoute();
+        screenSessionTracker.endScreenSession(currentRoute?.name);
+      }
+
+      screenLoadTracker.startNavigationSpan();
+    } catch (error) {
+      console.warn(
+        `${LOG_TAGS.NAVIGATION} Error in onNavigationDispatch:`,
+        error
+      );
+
+      if (screenLoadState.navigationSpan?.spanId) {
+        discardSpan(screenLoadState.navigationSpan.spanId);
+        screenLoadState.navigationSpan = undefined;
+      }
+    }
+  };
+
+  const onStateChange = (): void => {
+    try {
+      if (!navigationContainer) {
+        return;
+      }
+
+      const currentRoute = navigationContainer.getCurrentRoute();
+      if (!currentRoute) {
+        return;
+      }
+
+      if (currentRoute.name) {
+        setCurrentScreenName(currentRoute.name);
+      }
+
+      screenLoadTracker.handleStateChange(currentRoute);
+
+      const appState = AppState.currentState as AppStateStatus;
+      if (
+        appState &&
+        screenSessionTracker.shouldStartSession(currentRoute, appState)
+      ) {
+        screenSessionTracker.startScreenSession(currentRoute);
+      }
+
+      if (screenInteractiveTracking) {
+        screenInteractiveTracker.startScreenInteractive(currentRoute);
+      }
+    } catch (error) {
+      console.warn(`${LOG_TAGS.NAVIGATION} Error in onStateChange:`, error);
+      if (screenLoadState.navigationSpan?.spanId) {
+        discardSpan(screenLoadState.navigationSpan.spanId);
+        screenLoadState.navigationSpan = undefined;
+      }
+    }
+  };
+
+  const handleAppStateChange = (nextAppState: AppStateStatus): void => {
+    try {
+      screenSessionTracker.handleAppStateChange(
+        nextAppState,
+        navigationContainer
+      );
+    } catch (error) {
+      console.warn(
+        `${LOG_TAGS.NAVIGATION} Error in handleAppStateChange:`,
+        error
+      );
+    }
+  };
+
+  const registerNavigationContainer = (
+    maybeNavigationContainer: unknown
+  ): (() => void) => {
+    try {
+      let container: NavigationContainer | undefined;
+      if (
+        typeof maybeNavigationContainer === 'object' &&
+        maybeNavigationContainer !== null &&
+        'current' in maybeNavigationContainer
+      ) {
+        container = maybeNavigationContainer.current as NavigationContainer;
+      } else {
+        container = maybeNavigationContainer as NavigationContainer;
+      }
+
+      if (!container) {
+        console.warn(`${LOG_TAGS.NAVIGATION} Invalid navigation container ref`);
+        return () => {};
+      }
+
+      if (isInitialized && navigationContainer === container) {
+        return () => {
+          if (screenSessionTracking && screenSessionState.screenSessionSpan) {
+            const currentRoute = container.getCurrentRoute();
+            screenSessionTracker.endScreenSession(currentRoute?.name);
+          }
+        };
+      }
+
+      navigationContainer = container;
+
+      const updatedInteractiveTracker = createScreenInteractiveTracker(
+        screenInteractiveTracking,
+        screenInteractiveState,
+        navigationContainer
+      );
+
+      navigationContainer.addListener(
+        '__unsafe_action__',
+        onNavigationDispatch
+      );
+      navigationContainer.addListener('state', onStateChange);
+
+      const unmountCleanup = (): void => {
+        if (screenSessionTracking && screenSessionState.screenSessionSpan) {
+          const currentRoute = container.getCurrentRoute();
+          screenSessionTracker.endScreenSession(currentRoute?.name);
+        }
+
+        if (screenInteractiveTracking) {
+          screenInteractiveTracker.discardScreenInteractive(
+            'navigation container unmounted'
+          );
+        }
+
+        screenLoadTracker.endNavigationSpan();
+
+        if (navigationContainer === container) {
+          if (appStateSubscription) {
+            appStateSubscription.remove();
+            appStateSubscription = undefined;
+          }
+          navigationContainer = undefined;
+          isInitialized = false;
+
+          clearGlobalMarkContentReady(
+            updatedInteractiveTracker.markContentReady
+          );
+        }
+      };
+
+      const currentRoute = container.getCurrentRoute();
+      if (currentRoute) {
+        screenLoadState.latestRoute = currentRoute;
+        recentRouteKeys = pushRecentRouteKey(recentRouteKeys, currentRoute.key);
+        if (currentRoute.name) {
+          setCurrentScreenName(currentRoute.name);
+        }
+
+        const appState = AppState.currentState as AppStateStatus;
+        if (
+          appState &&
+          screenSessionTracker.shouldStartSession(currentRoute, appState)
+        ) {
+          screenSessionTracker.startScreenSession(currentRoute);
+        }
+
+        if (screenInteractiveTracking) {
+          updatedInteractiveTracker.startScreenInteractive(currentRoute);
+        }
+      }
+
+      appStateSubscription = AppState.addEventListener(
+        'change',
+        handleAppStateChange
+      );
+      isInitialized = true;
+
+      return unmountCleanup;
+    } catch (error) {
+      console.error(
+        `${LOG_TAGS.NAVIGATION} Error registering container:`,
+        error
+      );
+      return () => {};
+    }
+  };
+
+  return {
+    registerNavigationContainer,
+    markContentReady: screenInteractiveTracker.markContentReady,
+  };
+}
+
+export { markContentReady };
+
+export function useNavigationTracking(
+  navigationRef: RefObject<any>,
+  options?: NavigationIntegrationOptions
+): () => void {
+  const { createNavigationIntegrationWithConfig } = require('../config');
+  return useNavigationTrackingBase(
+    navigationRef,
+    options,
+    createNavigationIntegrationWithConfig
+  );
+}

package/src/navigation/navigation.interface.ts

@@ -0,0 +1,26 @@
+export interface NavigationRoute {
+  name: string;
+  key: string;
+  params?: Record<string, any>;
+}
+
+export interface NavigationContainer {
+  addListener: (
+    type: string,
+    listener: (event?: unknown) => void
+  ) => { remove: () => void } | void;
+  getCurrentRoute: () => NavigationRoute | undefined;
+}
+
+export interface NavigationIntegrationOptions {
+  screenSessionTracking?: boolean;
+  screenNavigationTracking?: boolean;
+  screenInteractiveTracking?: boolean;
+}
+
+export const DEFAULT_NAVIGATION_OPTIONS: Required<NavigationIntegrationOptions> =
+  {
+    screenSessionTracking: true,
+    screenNavigationTracking: true,
+    screenInteractiveTracking: false,
+  };

package/src/navigation/screen-interactive.ts

@@ -0,0 +1,149 @@
+import { Pulse, type Span } from '../index';
+import { Platform } from 'react-native';
+import { SPAN_NAMES, ATTRIBUTE_KEYS, PULSE_TYPES } from '../pulse.constants';
+import { discardSpan } from '../trace';
+import type {
+  NavigationRoute,
+  NavigationContainer,
+} from './navigation.interface';
+import { LOG_TAGS } from './utils';
+
+export interface ScreenInteractiveState {
+  screenInteractiveSpan: Span | undefined;
+  currentInteractiveRouteKey: string | undefined;
+}
+
+export const INITIAL_SCREEN_INTERACTIVE_STATE: ScreenInteractiveState = {
+  screenInteractiveSpan: undefined,
+  currentInteractiveRouteKey: undefined,
+};
+
+let globalMarkContentReady: (() => void) | undefined;
+
+export function createScreenInteractiveTracker(
+  enabled: boolean,
+  state: ScreenInteractiveState,
+  navigationContainer: NavigationContainer | undefined
+) {
+  const discardScreenInteractive = (reason: string): void => {
+    if (state.screenInteractiveSpan) {
+      console.log(
+        `${LOG_TAGS.SCREEN_INTERACTIVE} screen_interactive span discarded: ${reason} (routeKey: ${state.currentInteractiveRouteKey})`
+      );
+      if (state.screenInteractiveSpan.spanId) {
+        discardSpan(state.screenInteractiveSpan.spanId);
+      }
+      state.screenInteractiveSpan = undefined;
+      state.currentInteractiveRouteKey = undefined;
+    }
+  };
+
+  const startScreenInteractive = (route: NavigationRoute): void => {
+    if (!enabled) {
+      return;
+    }
+
+    if (
+      state.screenInteractiveSpan &&
+      state.currentInteractiveRouteKey === route.key
+    ) {
+      return;
+    }
+
+    if (state.screenInteractiveSpan) {
+      discardScreenInteractive('previous span replaced by new navigation');
+    }
+
+    state.screenInteractiveSpan = Pulse.startSpan(
+      SPAN_NAMES.SCREEN_INTERACTIVE,
+      {
+        attributes: {
+          [ATTRIBUTE_KEYS.PULSE_TYPE]: PULSE_TYPES.SCREEN_INTERACTIVE,
+          [ATTRIBUTE_KEYS.SCREEN_NAME]: route.name,
+          [ATTRIBUTE_KEYS.ROUTE_KEY]: route.key,
+          [ATTRIBUTE_KEYS.PLATFORM]: Platform.OS,
+        },
+        inheritContext: false,
+      }
+    );
+    state.currentInteractiveRouteKey = route.key;
+    console.log(`${LOG_TAGS.SCREEN_INTERACTIVE} ${route.name} started`);
+  };
+
+  const endScreenInteractive = (routeName?: string): void => {
+    if (state.screenInteractiveSpan) {
+      state.screenInteractiveSpan.end();
+      if (routeName) {
+        console.log(`${LOG_TAGS.SCREEN_INTERACTIVE} ${routeName} ended`);
+      }
+      state.screenInteractiveSpan = undefined;
+      state.currentInteractiveRouteKey = undefined;
+    }
+  };
+
+  const handleMarkContentReady = (): void => {
+    try {
+      if (!enabled) {
+        console.warn(
+          `${LOG_TAGS.SCREEN_INTERACTIVE} markContentReady called but screenInteractiveTracking is disabled`
+        );
+        return;
+      }
+
+      if (!state.screenInteractiveSpan) {
+        return;
+      }
+
+      const currentRoute = navigationContainer?.getCurrentRoute();
+      if (!currentRoute) {
+        console.warn(
+          `${LOG_TAGS.SCREEN_INTERACTIVE} markContentReady called but no current route found`
+        );
+        discardScreenInteractive('no current route');
+        return;
+      }
+
+      if (currentRoute.key !== state.currentInteractiveRouteKey) {
+        console.warn(
+          `${LOG_TAGS.SCREEN_INTERACTIVE} markContentReady called for wrong screen. Expected routeKey: ${state.currentInteractiveRouteKey}, Current: ${currentRoute.key}`
+        );
+        discardScreenInteractive('route key mismatch');
+        return;
+      }
+
+      endScreenInteractive(currentRoute.name);
+    } catch (error) {
+      console.error(
+        `${LOG_TAGS.SCREEN_INTERACTIVE} Error in markContentReady:`,
+        error
+      );
+    }
+  };
+
+  globalMarkContentReady = handleMarkContentReady;
+
+  return {
+    startScreenInteractive,
+    endScreenInteractive,
+    discardScreenInteractive,
+    markContentReady: handleMarkContentReady,
+  };
+}
+
+export function markContentReady(): void {
+  if (globalMarkContentReady) {
+    globalMarkContentReady();
+  } else {
+    console.warn(
+      `${LOG_TAGS.NAVIGATION} markContentReady called but navigation integration not initialized`
+    );
+  }
+}
+
+export function clearGlobalMarkContentReady(
+  markContentReadyFn: () => void
+): void {
+  if (globalMarkContentReady === markContentReadyFn) {
+    globalMarkContentReady = undefined;
+  }
+}

package/src/navigation/screen-load.ts

@@ -0,0 +1,97 @@
+import { Pulse, type Span } from '../index';
+import { Platform } from 'react-native';
+import { SPAN_NAMES, ATTRIBUTE_KEYS, PULSE_TYPES } from '../pulse.constants';
+import type { NavigationRoute } from './navigation.interface';
+import { LOG_TAGS } from './utils';
+
+export interface ScreenLoadState {
+  navigationSpan: Span | undefined;
+  latestRoute: NavigationRoute | undefined;
+}
+
+export const INITIAL_SCREEN_LOAD_STATE: ScreenLoadState = {
+  navigationSpan: undefined,
+  latestRoute: undefined,
+};
+
+export function createScreenLoadTracker(
+  enabled: boolean,
+  state: ScreenLoadState,
+  getRecentRouteKeys: () => string[],
+  pushRecentRouteKey: (key: string) => void,
+  onLoadEnd?: (route: NavigationRoute) => void
+) {
+  const startNavigationSpan = (): void => {
+    if (!enabled) {
+      return;
+    }
+
+    state.navigationSpan = Pulse.startSpan(SPAN_NAMES.NAVIGATED, {
+      attributes: {
+        [ATTRIBUTE_KEYS.PULSE_TYPE]: PULSE_TYPES.SCREEN_LOAD,
+        [ATTRIBUTE_KEYS.PLATFORM]: Platform.OS as 'android' | 'ios',
+      },
+    });
+    console.log(`${LOG_TAGS.SCREEN_LOAD} started`);
+  };
+
+  const endNavigationSpan = (
+    currentRoute?: NavigationRoute,
+    previousRoute?: NavigationRoute,
+    routeHasBeenSeen?: boolean
+  ): void => {
+    if (state.navigationSpan) {
+      const route = currentRoute || state.latestRoute;
+
+      if (route) {
+        const hasBeenSeen =
+          routeHasBeenSeen !== undefined
+            ? routeHasBeenSeen
+            : getRecentRouteKeys().includes(route.key);
+
+        state.navigationSpan.setAttributes({
+          [ATTRIBUTE_KEYS.SCREEN_NAME]: route.name,
+          [ATTRIBUTE_KEYS.LAST_SCREEN_NAME]: previousRoute?.name || undefined,
+          [ATTRIBUTE_KEYS.ROUTE_HAS_BEEN_SEEN]: hasBeenSeen,
+          [ATTRIBUTE_KEYS.ROUTE_KEY]: route.key,
+        });
+      }
+
+      state.navigationSpan.end();
+      state.navigationSpan = undefined;
+
+      if (route) {
+        console.log(`${LOG_TAGS.SCREEN_LOAD} ${route.name} ended`);
+        if (onLoadEnd) {
+          onLoadEnd(route);
+        }
+      }
+    }
+  };
+
+  const handleStateChange = (currentRoute: NavigationRoute): void => {
+    if (!enabled || !state.navigationSpan) {
+      return;
+    }
+
+    const previousRoute = state.latestRoute;
+
+    if (previousRoute && previousRoute.key === currentRoute.key) {
+      const routeHasBeenSeen = getRecentRouteKeys().includes(currentRoute.key);
+      endNavigationSpan(currentRoute, previousRoute, routeHasBeenSeen);
+      return;
+    }
+
+    const routeHasBeenSeen = getRecentRouteKeys().includes(currentRoute.key);
+    state.latestRoute = currentRoute;
+    pushRecentRouteKey(currentRoute.key);
+
+    endNavigationSpan(currentRoute, previousRoute, routeHasBeenSeen);
+  };
+
+  return {
+    startNavigationSpan,
+    endNavigationSpan,
+    handleStateChange,
+  };
+}

package/src/navigation/screen-session.ts

@@ -0,0 +1,87 @@
+import { Pulse, type Span } from '../index';
+import { type AppStateStatus, Platform } from 'react-native';
+import { SPAN_NAMES, ATTRIBUTE_KEYS, PULSE_TYPES } from '../pulse.constants';
+import type {
+  NavigationRoute,
+  NavigationContainer,
+} from './navigation.interface';
+import { LOG_TAGS } from './utils';
+
+export interface ScreenSessionState {
+  screenSessionSpan: Span | undefined;
+  currentScreenKey: string | undefined;
+}
+
+export const INITIAL_SCREEN_SESSION_STATE: ScreenSessionState = {
+  screenSessionSpan: undefined,
+  currentScreenKey: undefined,
+};
+
+export function createScreenSessionTracker(
+  enabled: boolean,
+  state: ScreenSessionState
+) {
+  const startScreenSession = (route: NavigationRoute): void => {
+    state.screenSessionSpan = Pulse.startSpan(SPAN_NAMES.SCREEN_SESSION, {
+      attributes: {
+        [ATTRIBUTE_KEYS.PULSE_TYPE]: PULSE_TYPES.SCREEN_SESSION,
+        [ATTRIBUTE_KEYS.SCREEN_NAME]: route.name,
+        [ATTRIBUTE_KEYS.ROUTE_KEY]: route.key,
+        [ATTRIBUTE_KEYS.PLATFORM]: Platform.OS as 'android' | 'ios',
+      },
+    });
+    state.currentScreenKey = route.key;
+    console.log(`${LOG_TAGS.SCREEN_SESSION} ${route.name} started`);
+  };
+
+  const endScreenSession = (routeName?: string): void => {
+    if (state.screenSessionSpan) {
+      state.screenSessionSpan.end();
+      if (routeName) {
+        console.log(`${LOG_TAGS.SCREEN_SESSION} ${routeName} ended`);
+      }
+      state.screenSessionSpan = undefined;
+      state.currentScreenKey = undefined;
+    }
+  };
+
+  const handleAppStateChange = (
+    nextAppState: AppStateStatus,
+    navigationContainer: NavigationContainer | undefined
+  ): void => {
+    if (!enabled) {
+      return;
+    }
+
+    if (nextAppState === 'background' || nextAppState === 'inactive') {
+      if (state.screenSessionSpan) {
+        const currentRoute = navigationContainer?.getCurrentRoute();
+        endScreenSession(currentRoute?.name);
+      }
+    } else if (nextAppState === 'active') {
+      const currentRoute = navigationContainer?.getCurrentRoute();
+      if (currentRoute && !state.screenSessionSpan) {
+        startScreenSession(currentRoute);
+      }
+    }
+  };
+
+  const shouldStartSession = (
+    currentRoute: NavigationRoute,
+    appState: AppStateStatus
+  ): boolean => {
+    return (
+      enabled &&
+      appState === 'active' &&
+      !state.screenSessionSpan &&
+      state.currentScreenKey !== currentRoute.key
+    );
+  };
+
+  return {
+    startScreenSession,
+    endScreenSession,
+    handleAppStateChange,
+    shouldStartSession,
+  };
+}