@grafana/faro-react-native 1.3.0 → 1.4.0

package/src/instrumentations/session/index.ts

@@ -1,26 +1,135 @@
-import { BaseInstrumentation, dateNow, EVENT_SESSION_START, genShortID, VERSION } from '@grafana/faro-core';
-import type { Config, Meta, MetaSession, TransportItem } from '@grafana/faro-core';
+import { BaseInstrumentation, dateNow, EVENT_SESSION_START, faro, VERSION } from '@grafana/faro-core';
+import type {
+  API,
+  BeforeSendHook,
+  Config,
+  Meta,
+  Metas,
+  MetaSession,
+  TransportItem,
+  Transports,
+  UserActionInternalInterface,
+} from '@grafana/faro-core';
 
 import type { ReactNativeFullConfig, ReactNativeSessionTrackingConfig } from '../../config/types';
 
+import { clearDirectSessionActivityHandler, registerDirectSessionActivityHandler } from './directSessionActivity';
+import { classifySessionActivity, isRecoveredCrashItem, SessionActivityKind } from './sessionActivity';
 import { minimalSessionDeviceAttributes, type SessionAttributes } from './sessionAttributes';
 import { type FaroUserSession, getSessionManagerByConfig, isSampled } from './sessionManager';
 import { MAX_SESSION_PERSISTENCE_TIME } from './sessionManager/sessionConstants';
 import { createUserSessionObject, isUserSessionValid } from './sessionManager/sessionManagerUtils';
-import type { SessionManager } from './sessionManager/types';
+import type { SessionManager, SessionManagerInstance } from './sessionManager/types';
+
+const SESSION_INSTRUMENTATION_NAME = '@grafana/faro-react-native:instrumentation-session';
+
+// Track the current session hook per transport so superseded hooks yield to a
+// replacement. The shared fallback preserves sampling decisions captured on
+// queued items after the owning instrumentation has detached.
+const activeSessionBeforeSendHooks = new WeakMap<Transports, BeforeSendHook>();
+const sessionSamplingFallbackHooks = new WeakMap<Transports, BeforeSendHook>();
+
+function applySessionSampling(item: TransportItem, fallbackSamplingDecision?: boolean): TransportItem | null {
+  const attributes = item.meta.session?.attributes;
+  const samplingAttribute = attributes?.['isSampled'] ?? fallbackSamplingDecision?.toString();
+
+  if (samplingAttribute === 'false') {
+    return null;
+  }
+
+  if (samplingAttribute !== 'true') {
+    return item;
+  }
+
+  const sampledItem: TransportItem = {
+    ...item,
+    meta: {
+      ...item.meta,
+      session: item.meta.session
+        ? {
+            ...item.meta.session,
+            attributes: item.meta.session.attributes ? { ...item.meta.session.attributes } : undefined,
+          }
+        : undefined,
+    },
+  };
+
+  const sampledAttributes = sampledItem.meta.session?.attributes;
+  delete sampledAttributes?.['isSampled'];
+
+  if (Object.keys(sampledAttributes ?? {}).length === 0) {
+    delete sampledItem.meta.session?.attributes;
+  }
+
+  return sampledItem;
+}
+
+function ensureSessionSamplingFallback(transports: Transports): void {
+  if (sessionSamplingFallbackHooks.has(transports)) {
+    return;
+  }
+
+  const fallbackHook: BeforeSendHook = (item) =>
+    activeSessionBeforeSendHooks.has(transports) ? item : applySessionSampling(item);
+
+  transports.addBeforeSendHooks(fallbackHook);
+  sessionSamplingFallbackHooks.set(transports, fallbackHook);
+}
+
+function removeInternalSamplingAttribute(session: MetaSession | undefined): MetaSession | undefined {
+  if (session?.attributes?.['isSampled'] == null) {
+    return session;
+  }
+
+  const attributes = { ...session.attributes };
+  delete attributes['isSampled'];
+
+  return {
+    ...session,
+    attributes: Object.keys(attributes).length === 0 ? undefined : attributes,
+  };
+}
+
+/**
+ * Starts a new linked session at an application-defined boundary.
+ *
+ * Call this after changing or clearing the current user for logout, account
+ * changes, or another boundary that must not share a session. Calls made
+ * before Faro initializes, after teardown, or while session tracking is
+ * disabled have no effect.
+ */
+export function startNewSession(): void {
+  const instrumentation = faro?.instrumentations?.instrumentations.find(
+    ({ name }) => name === SESSION_INSTRUMENTATION_NAME
+  );
+
+  if (
+    instrumentation != null &&
+    'startNewSession' in instrumentation &&
+    typeof instrumentation.startNewSession === 'function'
+  ) {
+    instrumentation.startNewSession();
+  }
+}
 
 /**
  * Session instrumentation for React Native
  * Manages persistent or volatile sessions with expiration and inactivity tracking
  */
 export class SessionInstrumentation extends BaseInstrumentation {
-  readonly name = '@grafana/faro-react-native:instrumentation-session';
+  readonly name = SESSION_INSTRUMENTATION_NAME;
   readonly version = VERSION;
 
   // previously notified session, to ensure we don't send session start
   // event twice for the same session
   private notifiedSession: MetaSession | undefined;
-  private sessionManagerInstance: InstanceType<SessionManager> | undefined;
+  private sessionManagerInstance: SessionManagerInstance | undefined;
+  private isResettingSession = false;
+  private unregisterDirectSessionActivity: (() => void) | undefined;
+  private sessionMetaListenerMetas: Metas | undefined;
+  private beforeSendHookApi: API | undefined;
+  private beforeSendHook: BeforeSendHook | undefined;
+  private beforeSendHookTransports: Transports | undefined;
 
   private getDefaultSessionDeviceAttributes(): SessionAttributes {
     const cfg = this.config as ReactNativeFullConfig;
@@ -30,7 +139,7 @@ export class SessionInstrumentation extends BaseInstrumentation {
     return minimalSessionDeviceAttributes();
   }
 
-  private sendSessionStartEvent(meta: Meta): void {
+  private readonly sendSessionStartEvent = (meta: Meta): void => {
     const session = meta.session;
 
     if (session && session.id !== this.notifiedSession?.id) {
@@ -39,6 +148,11 @@ export class SessionInstrumentation extends BaseInstrumentation {
       // automatically
       this.api.pushEvent(EVENT_SESSION_START, {}, undefined, { skipDedupe: true });
     }
+  };
+
+  private registerSessionMetaListener(): void {
+    this.metas.addListener(this.sendSessionStartEvent);
+    this.sessionMetaListenerMetas = this.metas;
   }
 
   private createInitialSession(
@@ -55,7 +169,10 @@ export class SessionInstrumentation extends BaseInstrumentation {
 
     if (sessionsConfig.persistent && storedUserSession) {
       const now = dateNow();
-      const shouldClearPersistentSession = storedUserSession.lastActivity < now - maxPersistenceMs;
+      const shouldClearPersistentSession =
+        storedUserSession.started > now ||
+        storedUserSession.lastActivity > now ||
+        storedUserSession.lastActivity <= now - maxPersistenceMs;
 
       if (shouldClearPersistentSession) {
         SessionManagerClass.removeUserSession();
@@ -68,7 +185,7 @@ export class SessionInstrumentation extends BaseInstrumentation {
     let emitSessionStartOnInit: boolean;
     let initialSession: FaroUserSession;
 
-    if (isUserSessionValid(storedUserSession)) {
+    if (!sessionsConfig.persistent && isUserSessionValid(storedUserSession)) {
       const sessionId = storedUserSession?.sessionId;
 
       initialSession = createUserSessionObject({
@@ -91,7 +208,7 @@ export class SessionInstrumentation extends BaseInstrumentation {
           ...sessionsConfig.session?.attributes,
           // Merge with stored attributes
           ...storedUserSessionMeta?.attributes,
-          // Default attributes take precedence (matching Flutter SDK behavior)
+          // Default attributes take precedence
           ...defaultAttributes,
           // For valid resumed sessions we do not want to recalculate the sampling decision on each init phase.
           isSampled: initialSession.isSampled.toString(),
@@ -101,23 +218,24 @@ export class SessionInstrumentation extends BaseInstrumentation {
 
       emitSessionStartOnInit = false;
     } else {
-      const sessionId = sessionsConfig.session?.id ?? genShortID();
-
       initialSession = createUserSessionObject({
-        sessionId,
+        sessionId: sessionsConfig.session?.id,
         isSampled: isSampled(),
       });
 
+      const sessionId = initialSession.sessionId;
+      const previousSessionId = storedUserSession?.sessionId === sessionId ? undefined : storedUserSession?.sessionId;
       const overrides = sessionsConfig.session?.overrides;
 
       initialSession.sessionMeta = {
         id: sessionId,
         attributes: {
-          isSampled: initialSession.isSampled.toString(),
           // Start with custom attributes from config
           ...sessionsConfig.session?.attributes,
-          // Default attributes take precedence (matching Flutter SDK behavior)
+          // Default attributes take precedence
           ...defaultAttributes,
+          isSampled: initialSession.isSampled.toString(),
+          ...(previousSessionId == null ? {} : { previousSession: previousSessionId }),
         },
         // new session we don't care about previous overrides
         ...(overrides ? { overrides } : {}),
@@ -129,51 +247,80 @@ export class SessionInstrumentation extends BaseInstrumentation {
     return { initialSession, emitSessionStartOnInit };
   }
 
-  private registerBeforeSendHook(SessionManagerClass: SessionManager) {
-    const { updateSession } = new SessionManagerClass();
+  private registerBeforeSendHook(SessionManagerClass: SessionManager): void {
+    const registeredTransports = this.transports;
+    ensureSessionSamplingFallback(registeredTransports);
 
-    this.transports?.addBeforeSendHooks((item: TransportItem) => {
-      updateSession();
-
-      const attributes = item.meta.session?.attributes;
-
-      // Only filter out items when session is explicitly NOT sampled (isSampled='false')
-      // If isSampled='true', remove the attribute before sending (it's internal)
-      // If no isSampled attribute, pass through the item unchanged
-      if (attributes?.['isSampled'] === 'false') {
-        // Session is not sampled - drop this item
-        return null;
+    const beforeSendHook: BeforeSendHook = (item: TransportItem) => {
+      const activeBeforeSendHook = activeSessionBeforeSendHooks.get(registeredTransports);
+      if (activeBeforeSendHook != null && activeBeforeSendHook !== beforeSendHook) {
+        return item;
       }
 
-      if (attributes?.['isSampled'] === 'true') {
-        // Session is sampled - remove internal isSampled attribute before sending
-        let newItem: TransportItem = JSON.parse(JSON.stringify(item));
-
-        const newAttributes = newItem.meta.session?.attributes;
-        delete newAttributes?.['isSampled'];
-
-        if (Object.keys(newAttributes ?? {}).length === 0) {
-          delete newItem.meta.session?.attributes;
+      let nextItem = item;
+      let fallbackSamplingDecision: boolean | undefined;
+      const sessionManager = this.beforeSendHook === beforeSendHook ? this.sessionManagerInstance : undefined;
+
+      if (sessionManager != null) {
+        const storedSession = SessionManagerClass.fetchUserSession();
+        const recoveredCrash = isRecoveredCrashItem(item, storedSession?.sessionId);
+        // Ending an active action can send telemetry synchronously. Keep that
+        // telemetry on the current session until the explicit reset completes.
+        const checkedSession = recoveredCrash
+          ? null
+          : this.isResettingSession
+            ? storedSession
+            : sessionManager.checkSession(classifySessionActivity(item), storedSession);
+
+        if (checkedSession?.sessionMeta != null && item.meta.session?.id !== checkedSession.sessionId) {
+          nextItem = {
+            ...item,
+            meta: {
+              ...item.meta,
+              session: checkedSession.sessionMeta,
+            },
+          };
         }
 
-        return newItem;
+        // New crash records carry the crash-time decision. Older records may not,
+        // so retain the previous behavior and use the live session's stable
+        // decision rather than implicitly sampling every recovered crash.
+        fallbackSamplingDecision = recoveredCrash ? storedSession?.isSampled : checkedSession?.isSampled;
       }
 
-      // No isSampled attribute or other value - pass through unchanged
-      return item;
-    });
+      return applySessionSampling(nextItem, fallbackSamplingDecision);
+    };
+
+    this.beforeSendHook = beforeSendHook;
+    this.beforeSendHookApi = this.api;
+    this.beforeSendHookTransports = registeredTransports;
+    registeredTransports.addBeforeSendHooks(beforeSendHook);
+    activeSessionBeforeSendHooks.set(registeredTransports, beforeSendHook);
   }
 
   initialize(): void {
+    // BaseInstrumentation instances can be registered more than once. Detach
+    // every resource from the previous Faro instance before binding the next.
+    this.unpatch();
+
     const sessionTrackingConfig = this.config.sessionTracking;
 
+    // A new initialization owns direct-activity routing, including when
+    // session tracking is disabled.
+    clearDirectSessionActivityHandler();
+
     if (!sessionTrackingConfig?.enabled) {
-      this.metas.addListener(this.sendSessionStartEvent.bind(this));
+      this.registerSessionMetaListener();
       return;
     }
 
     const SessionManagerClass = getSessionManagerByConfig(sessionTrackingConfig);
 
+    // Constructing a manager registers an AppState subscription and a metas
+    // listener, so exactly one instance is created and reused. It is also the
+    // instance `unpatch()` cleans up.
+    this.sessionManagerInstance = new SessionManagerClass(this.metas);
+
     this.registerBeforeSendHook(SessionManagerClass);
 
     const { initialSession, emitSessionStartOnInit } = this.createInitialSession(
@@ -186,21 +333,97 @@ export class SessionInstrumentation extends BaseInstrumentation {
     this.notifiedSession = initialSessionMeta;
     this.api.setSession(initialSessionMeta);
 
-    this.sessionManagerInstance = new SessionManagerClass();
-
     if (emitSessionStartOnInit) {
       this.api.pushEvent(EVENT_SESSION_START, {}, undefined, { skipDedupe: true });
     }
 
-    this.metas.addListener(this.sendSessionStartEvent.bind(this));
+    this.unregisterDirectSessionActivity = registerDirectSessionActivityHandler(() => {
+      this.sessionManagerInstance?.checkSession(SessionActivityKind.Meaningful);
+    });
+
+    this.registerSessionMetaListener();
+  }
+
+  /** Starts a new linked session immediately. */
+  startNewSession(): void {
+    if (this.sessionManagerInstance == null || this.isResettingSession) {
+      return;
+    }
+
+    this.isResettingSession = true;
+    try {
+      try {
+        const activeAction = this.api.getActiveUserAction?.() as UserActionInternalInterface | undefined;
+        activeAction?.end();
+      } catch (error) {
+        this.logWarn('Failed to end the active user action before resetting the session:', error);
+      }
+
+      this.sessionManagerInstance.resetSession();
+    } finally {
+      this.isResettingSession = false;
+    }
   }
 
   /**
    * Clean up session manager listeners
    */
   unpatch(): void {
-    if (this.sessionManagerInstance && 'unpatch' in this.sessionManagerInstance) {
-      this.sessionManagerInstance.unpatch();
+    this.unregisterDirectSessionActivity?.();
+    this.unregisterDirectSessionActivity = undefined;
+
+    const beforeSendHook = this.beforeSendHook;
+    const beforeSendHookApi = this.beforeSendHookApi;
+    const beforeSendHookTransports = this.beforeSendHookTransports;
+    const ownedActiveHook =
+      beforeSendHook != null &&
+      beforeSendHookTransports != null &&
+      activeSessionBeforeSendHooks.get(beforeSendHookTransports) === beforeSendHook;
+
+    // Stop the manager's metas synchronization before removing the internal
+    // sampling marker. Keep the session hook active during that update so any
+    // surviving metas listener that emits telemetry is still attributed and
+    // filtered with the current session.
+    this.sessionManagerInstance?.unpatch();
+
+    try {
+      if (ownedActiveHook && beforeSendHookApi) {
+        const session = beforeSendHookApi.getSession();
+        const sessionWithoutSamplingAttribute = removeInternalSamplingAttribute(session);
+        if (sessionWithoutSamplingAttribute !== session) {
+          this.isResettingSession = true;
+          try {
+            beforeSendHookApi.setSession(sessionWithoutSamplingAttribute);
+          } finally {
+            this.isResettingSession = false;
+          }
+        }
+      }
+    } finally {
+      this.beforeSendHook = undefined;
+      this.beforeSendHookApi = undefined;
+      this.beforeSendHookTransports = undefined;
+      if (beforeSendHook && beforeSendHookTransports) {
+        if (ownedActiveHook) {
+          activeSessionBeforeSendHooks.delete(beforeSendHookTransports);
+        }
+        beforeSendHookTransports.removeBeforeSendHooks(beforeSendHook);
+      }
+
+      this.sessionManagerInstance = undefined;
+
+      const sessionMetaListenerMetas = this.sessionMetaListenerMetas;
+      this.sessionMetaListenerMetas = undefined;
+      if (sessionMetaListenerMetas) {
+        sessionMetaListenerMetas.removeListener(this.sendSessionStartEvent);
+      }
+
+      this.notifiedSession = undefined;
+      this.isResettingSession = false;
     }
   }
+
+  destroy(): void {
+    this.unpatch();
+  }
 }

package/src/instrumentations/session/persistentColdStart.test.ts

@@ -0,0 +1,196 @@
+import { NativeModules } from 'react-native';
+
+import { EVENT_SESSION_START, initializeFaro } from '@grafana/faro-core';
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import { SessionInstrumentation } from './index';
+import {
+  MmkvPersistentSessionsManager,
+  resetMmkvSingletonForTests,
+} from './sessionManager/MmkvPersistentSessionsManager';
+import { MAX_SESSION_PERSISTENCE_TIME, STORAGE_KEY } from './sessionManager/sessionConstants';
+import { resetSessionProcessForTests } from './sessionProcess';
+
+const mockMmkvValues = new Map<string, string>();
+const mockMmkv = {
+  getString: jest.fn((key: string) => mockMmkvValues.get(key)),
+  set: jest.fn((key: string, value: string) => mockMmkvValues.set(key, value)),
+  remove: jest.fn((key: string) => mockMmkvValues.delete(key)),
+};
+const mockCreateMMKV = jest.fn(() => mockMmkv);
+const originalNativeModule = NativeModules.FaroReactNativeModule;
+
+jest.mock('react-native-mmkv', () => ({
+  createMMKV: mockCreateMMKV,
+}));
+
+const now = new Date('2026-08-14T12:00:00.000Z').getTime();
+
+function persistedSession({
+  currentSessionId = 'persisted-session',
+  startedAt = now - 10_000,
+  lastActivityAt = now - 1,
+}: {
+  currentSessionId?: string;
+  startedAt?: number;
+  lastActivityAt?: number;
+} = {}) {
+  return JSON.stringify({
+    schemaVersion: 1,
+    currentSessionId,
+    previousSessionId: 'older-session',
+    startedAt,
+    lastActivityAt,
+    isSampled: false,
+  });
+}
+
+function initializePersistentSession() {
+  const transport = new MockTransport();
+  const faro = initializeFaro(
+    mockConfig({
+      transports: [transport],
+      instrumentations: [new SessionInstrumentation()],
+      sessionTracking: {
+        enabled: true,
+        persistent: true,
+        generateSessionId: () => 'new-session',
+      },
+    })
+  );
+
+  return { faro, transport };
+}
+
+describe('persistent session cold starts', () => {
+  beforeAll(() => {
+    jest.useFakeTimers();
+    jest.setSystemTime(now);
+  });
+
+  beforeEach(() => {
+    NativeModules.FaroReactNativeModule = {
+      claimSessionPersistence: () => true,
+      getSessionProcessIdentifier: () => 'com.example.myapp',
+      isMainSessionProcess: () => true,
+      releaseSessionPersistence: () => true,
+    };
+    jest.clearAllMocks();
+    mockMmkvValues.clear();
+    resetMmkvSingletonForTests();
+    resetSessionProcessForTests();
+    delete (globalThis as Record<string, unknown>)['faro'];
+  });
+
+  afterAll(() => {
+    NativeModules.FaroReactNativeModule = originalNativeModule;
+    resetSessionProcessForTests();
+    jest.useRealTimers();
+  });
+
+  it('starts an unlinked session when stored state is missing', () => {
+    const { faro } = initializePersistentSession();
+
+    expect(faro.metas.value.session?.id).toBe('new-session');
+    expect(faro.metas.value.session?.attributes?.['previousSession']).toBeUndefined();
+  });
+
+  it('creates a new session linked to a valid persisted session', () => {
+    mockMmkvValues.set(STORAGE_KEY, persistedSession());
+
+    const { faro, transport } = initializePersistentSession();
+
+    expect(faro.metas.value.session?.id).toBe('new-session');
+    expect(faro.metas.value.session?.attributes?.['previousSession']).toBe('persisted-session');
+    const sessionStartEvents = transport.items.filter(
+      (item) => item.type === 'event' && 'name' in item.payload && item.payload.name === EVENT_SESSION_START
+    );
+    expect(sessionStartEvents).toHaveLength(1);
+    expect(sessionStartEvents[0]?.meta.session?.attributes?.['previousSession']).toBe('persisted-session');
+  });
+
+  it('does not load MMKV when persistence is disabled', () => {
+    initializeFaro(
+      mockConfig({
+        transports: [new MockTransport()],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    expect(mockCreateMMKV).not.toHaveBeenCalled();
+  });
+
+  it('does not link expired persisted state', () => {
+    const lastActivityAt = now - MAX_SESSION_PERSISTENCE_TIME;
+    mockMmkvValues.set(STORAGE_KEY, persistedSession({ startedAt: lastActivityAt - 10_000, lastActivityAt }));
+
+    const { faro } = initializePersistentSession();
+
+    expect(faro.metas.value.session?.id).toBe('new-session');
+    expect(faro.metas.value.session?.attributes?.['previousSession']).toBeUndefined();
+    expect(mockMmkv.remove).toHaveBeenCalledWith(STORAGE_KEY);
+  });
+
+  it('does not link future-dated persisted state', () => {
+    mockMmkvValues.set(STORAGE_KEY, persistedSession({ startedAt: now + 1, lastActivityAt: now + 1 }));
+
+    const { faro } = initializePersistentSession();
+
+    expect(faro.metas.value.session?.attributes?.['previousSession']).toBeUndefined();
+    expect(mockMmkv.remove).toHaveBeenCalledWith(STORAGE_KEY);
+  });
+
+  it('does not link a configured session ID to itself', () => {
+    mockMmkvValues.set(STORAGE_KEY, persistedSession({ currentSessionId: 'new-session' }));
+
+    const { faro } = initializePersistentSession();
+
+    expect(faro.metas.value.session?.id).toBe('new-session');
+    expect(faro.metas.value.session?.attributes?.['previousSession']).toBeUndefined();
+  });
+
+  it.each([
+    ['corrupt', '{not-json'],
+    [
+      'unsupported',
+      JSON.stringify({
+        schemaVersion: 99,
+        currentSessionId: 'persisted-session',
+        previousSessionId: null,
+        startedAt: now - 10_000,
+        lastActivityAt: now - 1,
+        isSampled: true,
+      }),
+    ],
+  ])('starts cleanly when persisted state is %s', (_name, value) => {
+    mockMmkvValues.set(STORAGE_KEY, value);
+
+    const { faro } = initializePersistentSession();
+
+    expect(faro.metas.value.session?.id).toBe('new-session');
+    expect(faro.metas.value.session?.attributes?.['previousSession']).toBeUndefined();
+    expect(mockMmkv.remove).toHaveBeenCalledWith(STORAGE_KEY);
+  });
+
+  it('stores only the new session and its link after initialization', () => {
+    mockMmkvValues.set(STORAGE_KEY, persistedSession());
+
+    initializePersistentSession();
+
+    const storedSession = mockMmkvValues.get(STORAGE_KEY);
+    expect(storedSession).toBeDefined();
+    expect(JSON.parse(storedSession ?? '')).toStrictEqual({
+      schemaVersion: 1,
+      currentSessionId: 'new-session',
+      previousSessionId: 'persisted-session',
+      startedAt: now,
+      lastActivityAt: now,
+      isSampled: true,
+    });
+    expect(MmkvPersistentSessionsManager.fetchUserSession()?.sessionId).toBe('new-session');
+  });
+});

package/src/instrumentations/session/sessionActivity.test.ts

@@ -0,0 +1,68 @@
+import { EVENT_VIEW_CHANGED, TransportItemType } from '@grafana/faro-core';
+import type { TransportItem } from '@grafana/faro-core';
+
+import { EVENT_NAVIGATION } from '../../navigation/utils';
+import { EVENT_APP_STATE_CHANGED } from '../appState';
+
+import { classifySessionActivity, isRecoveredCrashItem, SessionActivityKind } from './sessionActivity';
+
+function item(type: TransportItemType, payload: Record<string, unknown>, sessionId = 'current'): TransportItem {
+  return {
+    type,
+    payload: payload as TransportItem['payload'],
+    meta: { session: { id: sessionId } },
+  };
+}
+
+describe('session activity classification', () => {
+  it.each([
+    ['view changes', item(TransportItemType.EVENT, { name: EVENT_VIEW_CHANGED })],
+    ['navigation', item(TransportItemType.EVENT, { name: EVENT_NAVIGATION })],
+    [
+      'foreground returns',
+      item(TransportItemType.EVENT, {
+        name: EVENT_APP_STATE_CHANGED,
+        attributes: { fromState: 'background', toState: 'active' },
+      }),
+    ],
+    ['tracked actions', item(TransportItemType.EXCEPTION, { action: { name: 'checkout' } })],
+  ])('treats %s as meaningful', (_name, transportItem) => {
+    expect(classifySessionActivity(transportItem)).toBe(SessionActivityKind.Meaningful);
+  });
+
+  it.each([
+    ['generic events', item(TransportItemType.EVENT, { name: 'poll_complete' })],
+    ['unmarked HTTP events', item(TransportItemType.EVENT, { name: 'faro.tracing.fetch' })],
+    [
+      'background lifecycle events',
+      item(TransportItemType.EVENT, {
+        name: EVENT_APP_STATE_CHANGED,
+        attributes: { toState: 'background' },
+      }),
+    ],
+    [
+      'returns from an inactive overlay',
+      item(TransportItemType.EVENT, {
+        name: EVENT_APP_STATE_CHANGED,
+        attributes: { fromState: 'inactive', toState: 'active' },
+      }),
+    ],
+    ['logs', item(TransportItemType.LOG, { message: 'heartbeat' })],
+    ['errors', item(TransportItemType.EXCEPTION, { type: 'error', value: 'failure' })],
+    ['measurements', item(TransportItemType.MEASUREMENT, { type: 'cpu', values: { usage: 1 } })],
+    ['traces', item(TransportItemType.TRACE, { trace_id: 'trace-id' })],
+  ])('treats %s as passive', (_name, transportItem) => {
+    expect(classifySessionActivity(transportItem)).toBe(SessionActivityKind.Passive);
+  });
+
+  it('recognizes a fatal crash recovered from a previous session', () => {
+    const recoveredCrash = item(
+      TransportItemType.EXCEPTION,
+      { fatal: true, type: 'crash', value: 'native crash' },
+      'previous'
+    );
+
+    expect(isRecoveredCrashItem(recoveredCrash, 'current')).toBe(true);
+    expect(isRecoveredCrashItem(recoveredCrash, 'previous')).toBe(false);
+  });
+});