@grafana/faro-react-native 1.0.0-alpha.1

package/dist/esm/instrumentations/startup/index.js

@@ -0,0 +1,118 @@
+import { AppState, NativeModules } from 'react-native';
+import { BaseInstrumentation, VERSION } from '@grafana/faro-core';
+const { FaroReactNativeModule } = NativeModules;
+/**
+ * Measures React Native app startup time for both cold and warm starts.
+ *
+ * Uses native OS APIs for cold start and AppState for warm start:
+ * - iOS: sysctl() to query kernel for process start time
+ * - Android: Process.getStartElapsedRealtime() from Android OS (API 24+)
+ *
+ * Implementation aligned with Faro Flutter SDK:
+ * https://github.com/grafana/faro-flutter-sdk
+ *
+ * **Key Features**:
+ * - ✅ NO AppDelegate/MainActivity setup required - OS tracks process start automatically!
+ * - ✅ Cold start: appStartDuration from native, coldStart: 1
+ * - ✅ Warm start: appStartDuration (time to first frame after resume), coldStart: 0
+ *
+ * **Metrics Captured** (matches Flutter SDK format):
+ * - Cold start: `appStartDuration`, `coldStart: 1`
+ * - Warm start: `appStartDuration`, `coldStart: 0`
+ *
+ * **Requirements**:
+ * - iOS 13.4+ (any iOS that supports React Native)
+ * - Android API 24+ (Android 7.0 Nougat, ~99% of devices as of 2025)
+ *
+ * @example
+ * ```tsx
+ * import { initializeFaro } from '@grafana/faro-react-native';
+ *
+ * initializeFaro({
+ *   app: { name: 'my-app', version: '1.0.0' },
+ *   url: 'https://your-collector.com',
+ * });
+ * ```
+ * StartupInstrumentation is included by default via makeRNConfig.
+ */
+export class StartupInstrumentation extends BaseInstrumentation {
+    constructor(options = {}) {
+        super();
+        this.options = options;
+        this.name = '@grafana/faro-react-native:instrumentation-startup';
+        this.version = VERSION;
+        /** 0 = came from background (warm start eligible), null = never backgrounded */
+        this.warmStartTimestamp = null;
+    }
+    initialize() {
+        if (this.options.enabled === false) {
+            return;
+        }
+        this.captureColdStartMetrics();
+        this.setupWarmStartTracking();
+    }
+    /**
+     * Captures cold start duration from native (process start to Faro init).
+     * Matches Flutter SDK: appStartDuration + coldStart: 1
+     */
+    captureColdStartMetrics() {
+        try {
+            if (!(FaroReactNativeModule === null || FaroReactNativeModule === void 0 ? void 0 : FaroReactNativeModule.getAppStartDuration)) {
+                this.logWarn('Native module not available. Startup instrumentation requires native module. ' +
+                    'Run `cd ios && pod install` and rebuild the app.');
+                return;
+            }
+            const appStartDuration = FaroReactNativeModule.getAppStartDuration();
+            if (appStartDuration === 0) {
+                this.logWarn('App startup duration is 0. This may indicate unsupported Android version (< API 24) ' +
+                    'or an issue with the native module.');
+                return;
+            }
+            const values = {
+                appStartDuration,
+                coldStart: 1,
+            };
+            setTimeout(() => {
+                this.api.pushMeasurement({ type: 'app_startup', values }, { skipDedupe: true });
+            }, 100);
+            this.logInfo(`Cold start metrics captured: ${appStartDuration}ms`);
+        }
+        catch (error) {
+            this.logError('Failed to capture cold start metrics', error);
+        }
+    }
+    /**
+     * Tracks warm start: when app resumes from background, measures time to first frame.
+     * Matches Flutter SDK: setWarmStart on resume, getWarmStart after postFrameCallback.
+     */
+    setupWarmStartTracking() {
+        this.appStateSubscription = AppState.addEventListener('change', (nextAppState) => {
+            if (nextAppState === 'background' || nextAppState === 'inactive') {
+                this.warmStartTimestamp = 0; // Sentinel: next 'active' is a warm start
+            }
+            else if (nextAppState === 'active' && this.warmStartTimestamp === 0) {
+                // Came from background: measure time from resume to first frame
+                const resumeTimestamp = Date.now();
+                this.warmStartTimestamp = null;
+                requestAnimationFrame(() => {
+                    const appStartDuration = Date.now() - resumeTimestamp;
+                    if (appStartDuration > 0) {
+                        this.api.pushMeasurement({
+                            type: 'app_startup',
+                            values: { appStartDuration, coldStart: 0 },
+                        }, { skipDedupe: true });
+                        this.logInfo(`Warm start metrics captured: ${appStartDuration}ms`);
+                    }
+                });
+            }
+        });
+    }
+    unpatch() {
+        if (this.appStateSubscription) {
+            this.appStateSubscription.remove();
+            this.appStateSubscription = undefined;
+            this.warmStartTimestamp = null;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/instrumentations/startup/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/instrumentations/startup/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { AppState, NativeModules } from 'react-native';\n\nimport { BaseInstrumentation, VERSION } from '@grafana/faro-core';\n\nimport type { StartupInstrumentationOptions } from './types';\n\nconst { FaroReactNativeModule } = NativeModules;\n\n/**\n * Measures React Native app startup time for both cold and warm starts.\n *\n * Uses native OS APIs for cold start and AppState for warm start:\n * - iOS: sysctl() to query kernel for process start time\n * - Android: Process.getStartElapsedRealtime() from Android OS (API 24+)\n *\n * Implementation aligned with Faro Flutter SDK:\n * https://github.com/grafana/faro-flutter-sdk\n *\n * **Key Features**:\n * - ✅ NO AppDelegate/MainActivity setup required - OS tracks process start automatically!\n * - ✅ Cold start: appStartDuration from native, coldStart: 1\n * - ✅ Warm start: appStartDuration (time to first frame after resume), coldStart: 0\n *\n * **Metrics Captured** (matches Flutter SDK format):\n * - Cold start: `appStartDuration`, `coldStart: 1`\n * - Warm start: `appStartDuration`, `coldStart: 0`\n *\n * **Requirements**:\n * - iOS 13.4+ (any iOS that supports React Native)\n * - Android API 24+ (Android 7.0 Nougat, ~99% of devices as of 2025)\n *\n * @example\n * ```tsx\n * import { initializeFaro } from '@grafana/faro-react-native';\n *\n * initializeFaro({\n *   app: { name: 'my-app', version: '1.0.0' },\n *   url: 'https://your-collector.com',\n * });\n * ```\n * StartupInstrumentation is included by default via makeRNConfig.\n */\nexport class StartupInstrumentation extends BaseInstrumentation {\n  readonly name = '@grafana/faro-react-native:instrumentation-startup';\n  readonly version = VERSION;\n\n  /** 0 = came from background (warm start eligible), null = never backgrounded */\n  private warmStartTimestamp: number | null = null;\n  private appStateSubscription: ReturnType<typeof AppState.addEventListener> | undefined;\n\n  constructor(private options: StartupInstrumentationOptions = {}) {\n    super();\n  }\n\n  initialize(): void {\n    if (this.options.enabled === false) {\n      return;\n    }\n\n    this.captureColdStartMetrics();\n    this.setupWarmStartTracking();\n  }\n\n  /**\n   * Captures cold start duration from native (process start to Faro init).\n   * Matches Flutter SDK: appStartDuration + coldStart: 1\n   */\n  private captureColdStartMetrics(): void {\n    try {\n      if (!FaroReactNativeModule?.getAppStartDuration) {\n        this.logWarn(\n          'Native module not available. Startup instrumentation requires native module. ' +\n            'Run `cd ios && pod install` and rebuild the app.'\n        );\n        return;\n      }\n\n      const appStartDuration = FaroReactNativeModule.getAppStartDuration();\n\n      if (appStartDuration === 0) {\n        this.logWarn(\n          'App startup duration is 0. This may indicate unsupported Android version (< API 24) ' +\n            'or an issue with the native module.'\n        );\n        return;\n      }\n\n      const values: Record<string, number> = {\n        appStartDuration,\n        coldStart: 1,\n      };\n\n      setTimeout(() => {\n        this.api.pushMeasurement({ type: 'app_startup', values }, { skipDedupe: true });\n      }, 100);\n\n      this.logInfo(`Cold start metrics captured: ${appStartDuration}ms`);\n    } catch (error) {\n      this.logError('Failed to capture cold start metrics', error);\n    }\n  }\n\n  /**\n   * Tracks warm start: when app resumes from background, measures time to first frame.\n   * Matches Flutter SDK: setWarmStart on resume, getWarmStart after postFrameCallback.\n   */\n  private setupWarmStartTracking(): void {\n    this.appStateSubscription = AppState.addEventListener('change', (nextAppState) => {\n      if (nextAppState === 'background' || nextAppState === 'inactive') {\n        this.warmStartTimestamp = 0; // Sentinel: next 'active' is a warm start\n      } else if (nextAppState === 'active' && this.warmStartTimestamp === 0) {\n        // Came from background: measure time from resume to first frame\n        const resumeTimestamp = Date.now();\n        this.warmStartTimestamp = null;\n\n        requestAnimationFrame(() => {\n          const appStartDuration = Date.now() - resumeTimestamp;\n          if (appStartDuration > 0) {\n            this.api.pushMeasurement(\n              {\n                type: 'app_startup',\n                values: { appStartDuration, coldStart: 0 },\n              },\n              { skipDedupe: true }\n            );\n            this.logInfo(`Warm start metrics captured: ${appStartDuration}ms`);\n          }\n        });\n      }\n    });\n  }\n\n  unpatch(): void {\n    if (this.appStateSubscription) {\n      this.appStateSubscription.remove();\n      this.appStateSubscription = undefined;\n      this.warmStartTimestamp = null;\n    }\n  }\n}\n"]}

package/dist/esm/instrumentations/startup/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/instrumentations/startup/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/instrumentations/startup/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Configuration options for StartupInstrumentation\n */\nexport interface StartupInstrumentationOptions {\n  /**\n   * Enable startup timing measurement\n   * @default true\n   */\n  enabled?: boolean;\n}\n"]}

package/dist/esm/instrumentations/userActions/httpRequestMonitor.js

@@ -0,0 +1,49 @@
+import { Observable } from '@grafana/faro-core';
+/**
+ * Monitor for HTTP requests happening during user actions
+ * Tracks fetch requests to correlate with user actions
+ */
+export function monitorHttpRequests() {
+    const global = globalThis;
+    if (!global.__FARO_HTTP_MONITOR__) {
+        // Initialize the monitoring observable if it doesn't exist
+        const observable = new Observable();
+        global.__FARO_HTTP_MONITOR__ = {
+            observable,
+            notifyStart: (request) => {
+                try {
+                    observable.notify({ type: 'http_request_start', request });
+                }
+                catch (_err) {
+                    // Ignore notification errors
+                }
+            },
+            notifyEnd: (request) => {
+                try {
+                    observable.notify({ type: 'http_request_end', request });
+                }
+                catch (_err) {
+                    // Ignore notification errors
+                }
+            },
+        };
+    }
+    return global.__FARO_HTTP_MONITOR__.observable;
+}
+/**
+ * Notify the HTTP monitor that a request has started
+ * Should be called from HttpInstrumentation
+ */
+export function notifyHttpRequestStart(request) {
+    var _a, _b;
+    (_b = (_a = globalThis.__FARO_HTTP_MONITOR__) === null || _a === void 0 ? void 0 : _a.notifyStart) === null || _b === void 0 ? void 0 : _b.call(_a, request);
+}
+/**
+ * Notify the HTTP monitor that a request has ended
+ * Should be called from HttpInstrumentation
+ */
+export function notifyHttpRequestEnd(request) {
+    var _a, _b;
+    (_b = (_a = globalThis.__FARO_HTTP_MONITOR__) === null || _a === void 0 ? void 0 : _a.notifyEnd) === null || _b === void 0 ? void 0 : _b.call(_a, request);
+}
+//# sourceMappingURL=httpRequestMonitor.js.map

package/dist/esm/instrumentations/userActions/httpRequestMonitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpRequestMonitor.js","sourceRoot":"","sources":["../../../../src/instrumentations/userActions/httpRequestMonitor.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQhD;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IAQjC,MAAM,MAAM,GAAG,UAA+B,CAAC;IAE/C,IAAI,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC;QAClC,2DAA2D;QAC3D,MAAM,UAAU,GAAG,IAAI,UAAU,EAAsB,CAAC;QACxD,MAAM,CAAC,qBAAqB,GAAG;YAC7B,UAAU;YACV,WAAW,EAAE,CAAC,OAAkC,EAAE,EAAE;gBAClD,IAAI,CAAC;oBACH,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,CAAC,CAAC;gBAC7D,CAAC;gBAAC,OAAO,IAAI,EAAE,CAAC;oBACd,6BAA6B;gBAC/B,CAAC;YACH,CAAC;YACD,SAAS,EAAE,CAAC,OAAkC,EAAE,EAAE;gBAChD,IAAI,CAAC;oBACH,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC;gBAC3D,CAAC;gBAAC,OAAO,IAAI,EAAE,CAAC;oBACd,6BAA6B;gBAC/B,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,qBAAqB,CAAC,UAAU,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAkC;;IACvE,MAAA,MAAA,UAAU,CAAC,qBAAqB,0CAAE,WAAW,mDAAG,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAkC;;IACrE,MAAA,MAAA,UAAU,CAAC,qBAAqB,0CAAE,SAAS,mDAAG,OAAO,CAAC,CAAC;AACzD,CAAC","sourcesContent":["export interface HttpRequestMessagePayload {\n  requestId: string;\n  url: string;\n  method: string;\n  startTime: number;\n  endTime?: number;\n  status?: number;\n}\n\n// Declare global HTTP monitor interface\ndeclare global {\n  var __FARO_HTTP_MONITOR__:\n    | {\n        notifyStart?: (request: HttpRequestMessagePayload) => void;\n        notifyEnd?: (request: HttpRequestMessagePayload) => void;\n      }\n    | undefined;\n}\n\nimport { Observable } from '@grafana/faro-core';\n\nexport type HttpRequestMessage =\n  | { type: 'http_request_start'; request: HttpRequestMessagePayload }\n  | { type: 'http_request_end'; request: HttpRequestMessagePayload };\n\ntype HttpRequestObservable = Observable<HttpRequestMessage>;\n\n/**\n * Monitor for HTTP requests happening during user actions\n * Tracks fetch requests to correlate with user actions\n */\nexport function monitorHttpRequests(): HttpRequestObservable {\n  interface GlobalWithMonitor {\n    __FARO_HTTP_MONITOR__?: {\n      observable: Observable<HttpRequestMessage>;\n      notifyStart: (request: HttpRequestMessagePayload) => void;\n      notifyEnd: (request: HttpRequestMessagePayload) => void;\n    };\n  }\n  const global = globalThis as GlobalWithMonitor;\n\n  if (!global.__FARO_HTTP_MONITOR__) {\n    // Initialize the monitoring observable if it doesn't exist\n    const observable = new Observable<HttpRequestMessage>();\n    global.__FARO_HTTP_MONITOR__ = {\n      observable,\n      notifyStart: (request: HttpRequestMessagePayload) => {\n        try {\n          observable.notify({ type: 'http_request_start', request });\n        } catch (_err) {\n          // Ignore notification errors\n        }\n      },\n      notifyEnd: (request: HttpRequestMessagePayload) => {\n        try {\n          observable.notify({ type: 'http_request_end', request });\n        } catch (_err) {\n          // Ignore notification errors\n        }\n      },\n    };\n  }\n\n  return global.__FARO_HTTP_MONITOR__.observable;\n}\n\n/**\n * Notify the HTTP monitor that a request has started\n * Should be called from HttpInstrumentation\n */\nexport function notifyHttpRequestStart(request: HttpRequestMessagePayload): void {\n  globalThis.__FARO_HTTP_MONITOR__?.notifyStart?.(request);\n}\n\n/**\n * Notify the HTTP monitor that a request has ended\n * Should be called from HttpInstrumentation\n */\nexport function notifyHttpRequestEnd(request: HttpRequestMessagePayload): void {\n  globalThis.__FARO_HTTP_MONITOR__?.notifyEnd?.(request);\n}\n"]}

package/dist/esm/instrumentations/userActions/index.js

@@ -0,0 +1,62 @@
+import { BaseInstrumentation, userActionsMessageBus, VERSION, } from '@grafana/faro-core';
+import { UserActionController } from './userActionController';
+/**
+ * User Actions instrumentation for React Native
+ *
+ * Tracks user interactions when components use the withFaroUserAction HOC
+ * or call the trackUserAction helper directly.
+ *
+ * Features:
+ * - Intelligent duration tracking based on activity
+ * - HTTP request correlation
+ * - Automatic lifecycle management
+ * - Halt state for pending async operations
+ *
+ * @example
+ * ```tsx
+ * import { withFaroUserAction } from '@grafana/faro-react-native';
+ *
+ * const TrackedButton = withFaroUserAction(TouchableOpacity, 'button_pressed');
+ *
+ * <TrackedButton onPress={handlePress}>
+ *   <Text>Click me</Text>
+ * </TrackedButton>
+ * ```
+ */
+export class UserActionInstrumentation extends BaseInstrumentation {
+    constructor() {
+        super(...arguments);
+        this.name = '@grafana/faro-react-native:instrumentation-user-action';
+        this.version = VERSION;
+    }
+    initialize() {
+        this.logInfo('User action instrumentation initialized with enhanced tracking');
+        // Subscribe to user action events from the message bus
+        this._userActionSub = userActionsMessageBus.subscribe(({ type, userAction }) => {
+            if (type === 'user_action_start') {
+                this.logDebug(`User action started: ${userAction.name}`);
+                this.processUserActionStarted(userAction);
+            }
+        });
+    }
+    /**
+     * Process a started user action by attaching a controller
+     * The controller handles intelligent duration tracking and HTTP correlation
+     */
+    processUserActionStarted(userAction) {
+        try {
+            const internalUserAction = userAction;
+            const controller = new UserActionController(internalUserAction);
+            controller.attach();
+        }
+        catch (error) {
+            this.logError('Error attaching user action controller:', error);
+        }
+    }
+    unpatch() {
+        var _a;
+        (_a = this._userActionSub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this._userActionSub = undefined;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/instrumentations/userActions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/instrumentations/userActions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EAInB,qBAAqB,EACrB,OAAO,GACR,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,yBAA0B,SAAQ,mBAAmB;IAAlE;;QACW,SAAI,GAAG,wDAAwD,CAAC;QAChE,YAAO,GAAG,OAAO,CAAC;IAkC7B,CAAC;IA9BC,UAAU;QACR,IAAI,CAAC,OAAO,CAAC,gEAAgE,CAAC,CAAC;QAE/E,uDAAuD;QACvD,IAAI,CAAC,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE;YAC7E,IAAI,IAAI,KAAK,mBAAmB,EAAE,CAAC;gBACjC,IAAI,CAAC,QAAQ,CAAC,wBAAwB,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;gBACzD,IAAI,CAAC,wBAAwB,CAAC,UAAU,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACK,wBAAwB,CAAC,UAA+B;QAC9D,IAAI,CAAC;YACH,MAAM,kBAAkB,GAAG,UAAoD,CAAC;YAChF,MAAM,UAAU,GAAG,IAAI,oBAAoB,CAAC,kBAAkB,CAAC,CAAC;YAChE,UAAU,CAAC,MAAM,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,QAAQ,CAAC,yCAAyC,EAAE,KAAK,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,OAAO;;QACL,MAAA,IAAI,CAAC,cAAc,0CAAE,WAAW,EAAE,CAAC;QACnC,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;IAClC,CAAC;CACF","sourcesContent":["import {\n  BaseInstrumentation,\n  type Subscription,\n  type UserActionInterface,\n  type UserActionInternalInterface,\n  userActionsMessageBus,\n  VERSION,\n} from '@grafana/faro-core';\n\nimport { UserActionController } from './userActionController';\n\n/**\n * User Actions instrumentation for React Native\n *\n * Tracks user interactions when components use the withFaroUserAction HOC\n * or call the trackUserAction helper directly.\n *\n * Features:\n * - Intelligent duration tracking based on activity\n * - HTTP request correlation\n * - Automatic lifecycle management\n * - Halt state for pending async operations\n *\n * @example\n * ```tsx\n * import { withFaroUserAction } from '@grafana/faro-react-native';\n *\n * const TrackedButton = withFaroUserAction(TouchableOpacity, 'button_pressed');\n *\n * <TrackedButton onPress={handlePress}>\n *   <Text>Click me</Text>\n * </TrackedButton>\n * ```\n */\nexport class UserActionInstrumentation extends BaseInstrumentation {\n  readonly name = '@grafana/faro-react-native:instrumentation-user-action';\n  readonly version = VERSION;\n\n  private _userActionSub?: Subscription;\n\n  initialize(): void {\n    this.logInfo('User action instrumentation initialized with enhanced tracking');\n\n    // Subscribe to user action events from the message bus\n    this._userActionSub = userActionsMessageBus.subscribe(({ type, userAction }) => {\n      if (type === 'user_action_start') {\n        this.logDebug(`User action started: ${userAction.name}`);\n        this.processUserActionStarted(userAction);\n      }\n    });\n  }\n\n  /**\n   * Process a started user action by attaching a controller\n   * The controller handles intelligent duration tracking and HTTP correlation\n   */\n  private processUserActionStarted(userAction: UserActionInterface): void {\n    try {\n      const internalUserAction = userAction as unknown as UserActionInternalInterface;\n      const controller = new UserActionController(internalUserAction);\n      controller.attach();\n    } catch (error) {\n      this.logError('Error attaching user action controller:', error);\n    }\n  }\n\n  unpatch(): void {\n    this._userActionSub?.unsubscribe();\n    this._userActionSub = undefined;\n  }\n}\n"]}

package/dist/esm/instrumentations/userActions/userActionController.js

@@ -0,0 +1,137 @@
+import { Observable, UserActionState } from '@grafana/faro-core';
+import { monitorHttpRequests } from './httpRequestMonitor';
+const defaultFollowUpActionTimeRange = 100; // 100ms after activity stops
+const defaultHaltTimeout = 10 * 1000; // 10 seconds max wait for HTTP
+function isRequestStartMessage(msg) {
+    return msg.type === 'http_request_start';
+}
+function isRequestEndMessage(msg) {
+    return msg.type === 'http_request_end';
+}
+function startTimeout(callback, timeout) {
+    return setTimeout(callback, timeout);
+}
+/**
+ * Controller for managing user action lifecycle in React Native
+ *
+ * Responsibilities:
+ * - Monitor HTTP requests triggered by user actions
+ * - Intelligently determine when a user action is complete
+ * - Handle "halt" state for pending async operations
+ * - Auto-end actions after timeout
+ */
+export class UserActionController {
+    constructor(userAction) {
+        this.userAction = userAction;
+        this.http = monitorHttpRequests();
+        this.runningRequests = new Map();
+        this.isHalted = false;
+    }
+    /**
+     * Attach the controller to start monitoring
+     */
+    attach() {
+        // Subscribe to HTTP requests while action is active/halting
+        this.allMonitorsSub = new Observable()
+            .merge(this.http)
+            .takeWhile(() => {
+            const state = this.userAction.getState();
+            return [UserActionState.Started, UserActionState.Halted].includes(state);
+        })
+            .filter((msg) => {
+            // If the user action is in halt state, we only keep listening to ended http requests
+            if (this.isHalted && !(isRequestEndMessage(msg) && this.runningRequests.has(msg.request.requestId))) {
+                return false;
+            }
+            return true;
+        })
+            .subscribe((msg) => {
+            if (isRequestStartMessage(msg)) {
+                // Track started HTTP requests
+                this.runningRequests.set(msg.request.requestId, msg.request);
+            }
+            if (isRequestEndMessage(msg)) {
+                this.runningRequests.delete(msg.request.requestId);
+            }
+            // Clear any existing follow-up timeout
+            this.clearFollowUpTimeout();
+            // If we have pending HTTP requests, don't schedule follow-up yet
+            if (this.runningRequests.size > 0) {
+                // Enter halt state if we have pending requests
+                if (this.userAction.getState() === UserActionState.Started) {
+                    this.halt();
+                }
+            }
+            else {
+                // No pending requests, schedule action end
+                this.scheduleFollowUpAction();
+            }
+        });
+        // Start initial follow-up timeout
+        this.scheduleFollowUpAction();
+    }
+    /**
+     * Put the action in halt state (waiting for async operations)
+     */
+    halt() {
+        if (this.userAction.getState() === UserActionState.Started && !this.isHalted) {
+            this.userAction.halt();
+            this.isHalted = true;
+            // Start halt timeout - max time to wait for pending operations
+            this.haltTid = startTimeout(() => {
+                this.end();
+            }, defaultHaltTimeout);
+        }
+    }
+    /**
+     * End the user action
+     */
+    end() {
+        this.clearFollowUpTimeout();
+        this.clearHaltTimeout();
+        // Skip if already ended (e.g. user called action.end() manually) - avoids duplicate events
+        const state = this.userAction.getState();
+        if (state === UserActionState.Ended || state === UserActionState.Cancelled) {
+            this.cleanup();
+            return;
+        }
+        this.userAction.end();
+        this.cleanup();
+    }
+    /**
+     * Schedule the follow-up action to end the user action
+     */
+    scheduleFollowUpAction() {
+        this.clearFollowUpTimeout();
+        this.followUpTid = startTimeout(() => {
+            this.end();
+        }, defaultFollowUpActionTimeRange);
+    }
+    /**
+     * Clear the follow-up timeout
+     */
+    clearFollowUpTimeout() {
+        if (this.followUpTid !== undefined) {
+            clearTimeout(this.followUpTid);
+            this.followUpTid = undefined;
+        }
+    }
+    /**
+     * Clear the halt timeout
+     */
+    clearHaltTimeout() {
+        if (this.haltTid !== undefined) {
+            clearTimeout(this.haltTid);
+            this.haltTid = undefined;
+        }
+    }
+    /**
+     * Clean up subscriptions
+     */
+    cleanup() {
+        var _a;
+        (_a = this.allMonitorsSub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this.allMonitorsSub = undefined;
+    }
+}
+//# sourceMappingURL=userActionController.js.map

package/dist/esm/instrumentations/userActions/userActionController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userActionController.js","sourceRoot":"","sources":["../../../../src/instrumentations/userActions/userActionController.ts"],"names":[],"mappings":"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","sourcesContent":["import { Observable, UserActionState } from '@grafana/faro-core';\nimport type { Subscription, UserActionInternalInterface } from '@grafana/faro-core';\n\nimport { type HttpRequestMessage, type HttpRequestMessagePayload, monitorHttpRequests } from './httpRequestMonitor';\n\nconst defaultFollowUpActionTimeRange = 100; // 100ms after activity stops\nconst defaultHaltTimeout = 10 * 1000; // 10 seconds max wait for HTTP\n\nfunction isRequestStartMessage(\n  msg: HttpRequestMessage\n): msg is { type: 'http_request_start'; request: HttpRequestMessagePayload } {\n  return msg.type === 'http_request_start';\n}\n\nfunction isRequestEndMessage(\n  msg: HttpRequestMessage\n): msg is { type: 'http_request_end'; request: HttpRequestMessagePayload } {\n  return msg.type === 'http_request_end';\n}\n\nfunction startTimeout(callback: () => void, timeout: number): number {\n  return setTimeout(callback, timeout) as unknown as number;\n}\n\n/**\n * Controller for managing user action lifecycle in React Native\n *\n * Responsibilities:\n * - Monitor HTTP requests triggered by user actions\n * - Intelligently determine when a user action is complete\n * - Handle \"halt\" state for pending async operations\n * - Auto-end actions after timeout\n */\nexport class UserActionController {\n  private readonly http = monitorHttpRequests();\n\n  private allMonitorsSub?: Subscription;\n  private followUpTid?: number;\n  private haltTid?: number;\n\n  private runningRequests = new Map<string, HttpRequestMessagePayload>();\n  private isHalted = false;\n\n  constructor(private userAction: UserActionInternalInterface) {}\n\n  /**\n   * Attach the controller to start monitoring\n   */\n  attach(): void {\n    // Subscribe to HTTP requests while action is active/halting\n    this.allMonitorsSub = new Observable()\n      .merge(this.http)\n      .takeWhile(() => {\n        const state = this.userAction.getState();\n        return [UserActionState.Started, UserActionState.Halted].includes(state);\n      })\n      .filter((msg) => {\n        // If the user action is in halt state, we only keep listening to ended http requests\n        if (this.isHalted && !(isRequestEndMessage(msg) && this.runningRequests.has(msg.request.requestId))) {\n          return false;\n        }\n\n        return true;\n      })\n      .subscribe((msg) => {\n        if (isRequestStartMessage(msg)) {\n          // Track started HTTP requests\n          this.runningRequests.set(msg.request.requestId, msg.request);\n        }\n\n        if (isRequestEndMessage(msg)) {\n          this.runningRequests.delete(msg.request.requestId);\n        }\n\n        // Clear any existing follow-up timeout\n        this.clearFollowUpTimeout();\n\n        // If we have pending HTTP requests, don't schedule follow-up yet\n        if (this.runningRequests.size > 0) {\n          // Enter halt state if we have pending requests\n          if (this.userAction.getState() === UserActionState.Started) {\n            this.halt();\n          }\n        } else {\n          // No pending requests, schedule action end\n          this.scheduleFollowUpAction();\n        }\n      });\n\n    // Start initial follow-up timeout\n    this.scheduleFollowUpAction();\n  }\n\n  /**\n   * Put the action in halt state (waiting for async operations)\n   */\n  private halt(): void {\n    if (this.userAction.getState() === UserActionState.Started && !this.isHalted) {\n      this.userAction.halt();\n      this.isHalted = true;\n\n      // Start halt timeout - max time to wait for pending operations\n      this.haltTid = startTimeout(() => {\n        this.end();\n      }, defaultHaltTimeout);\n    }\n  }\n\n  /**\n   * End the user action\n   */\n  private end(): void {\n    this.clearFollowUpTimeout();\n    this.clearHaltTimeout();\n\n    // Skip if already ended (e.g. user called action.end() manually) - avoids duplicate events\n    const state = this.userAction.getState();\n    if (state === UserActionState.Ended || state === UserActionState.Cancelled) {\n      this.cleanup();\n      return;\n    }\n\n    this.userAction.end();\n    this.cleanup();\n  }\n\n  /**\n   * Schedule the follow-up action to end the user action\n   */\n  private scheduleFollowUpAction(): void {\n    this.clearFollowUpTimeout();\n\n    this.followUpTid = startTimeout(() => {\n      this.end();\n    }, defaultFollowUpActionTimeRange);\n  }\n\n  /**\n   * Clear the follow-up timeout\n   */\n  private clearFollowUpTimeout(): void {\n    if (this.followUpTid !== undefined) {\n      clearTimeout(this.followUpTid);\n      this.followUpTid = undefined;\n    }\n  }\n\n  /**\n   * Clear the halt timeout\n   */\n  private clearHaltTimeout(): void {\n    if (this.haltTid !== undefined) {\n      clearTimeout(this.haltTid);\n      this.haltTid = undefined;\n    }\n  }\n\n  /**\n   * Clean up subscriptions\n   */\n  private cleanup(): void {\n    this.allMonitorsSub?.unsubscribe();\n    this.allMonitorsSub = undefined;\n  }\n}\n"]}

package/dist/esm/instrumentations/userActions/withFaroUserAction.js

@@ -0,0 +1,99 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import React, {} from 'react';
+import { faro } from '@grafana/faro-core';
+/**
+ * Higher-Order Component that wraps React Native touchable components
+ * to automatically track user interactions.
+ *
+ * @param Component - The component to wrap (e.g., TouchableOpacity, Button, etc.)
+ * @param defaultActionName - The default name for this action
+ *
+ * @example
+ * ```tsx
+ * import { TouchableOpacity } from 'react-native';
+ * import { withFaroUserAction } from '@grafana/faro-react-native';
+ *
+ * const TrackedButton = withFaroUserAction(TouchableOpacity, 'submit_form');
+ *
+ * function MyForm() {
+ *   return (
+ *     <TrackedButton onPress={handleSubmit}>
+ *       <Text>Submit</Text>
+ *     </TrackedButton>
+ *   );
+ * }
+ * ```
+ */
+export function withFaroUserAction(Component, defaultActionName) {
+    return function FaroTrackedComponent(props) {
+        const { faroActionName, faroContext, onPress } = props, restProps = __rest(props, ["faroActionName", "faroContext", "onPress"]);
+        const handlePress = (event) => {
+            var _a, _b, _c, _d;
+            try {
+                // Use the prop-specific name or fall back to the default
+                const actionName = faroActionName || defaultActionName;
+                // End any active user action before starting a new one to avoid "already running" errors
+                // (e.g. when user taps another button before the previous action's HTTP request completes)
+                // getActiveUserAction returns UserActionInterface but the runtime object is the full
+                // UserAction implementing UserActionInternalInterface (with end)
+                const activeAction = (_b = (_a = faro === null || faro === void 0 ? void 0 : faro.api) === null || _a === void 0 ? void 0 : _a.getActiveUserAction) === null || _b === void 0 ? void 0 : _b.call(_a);
+                activeAction === null || activeAction === void 0 ? void 0 : activeAction.end();
+                // Start a user action - UserActionInstrumentation subscribes to the message bus
+                // and attaches UserActionController for auto-ending and HTTP correlation
+                (_d = (_c = faro === null || faro === void 0 ? void 0 : faro.api) === null || _c === void 0 ? void 0 : _c.startUserAction) === null || _d === void 0 ? void 0 : _d.call(_c, actionName, faroContext || {}, { triggerName: 'press' });
+            }
+            catch (error) {
+                // Don't let tracking errors break the app
+                console.warn('[Faro] Error tracking user action:', error);
+            }
+            // Always call the original onPress handler
+            onPress === null || onPress === void 0 ? void 0 : onPress(event);
+        };
+        return React.createElement(Component, Object.assign(Object.assign({}, restProps), { onPress: handlePress }));
+    };
+}
+/**
+ * Manually track a user action without using the HOC
+ *
+ * @param actionName - The name of the action
+ * @param context - Optional context to attach
+ *
+ * @example
+ * ```tsx
+ * import { trackUserAction } from '@grafana/faro-react-native';
+ *
+ * function handleComplexAction() {
+ *   const action = trackUserAction('complex_workflow', { step: '1' });
+ *
+ *   // Do work...
+ *   doSomething();
+ *
+ *   // End the action when done
+ *   action?.end();
+ * }
+ * ```
+ */
+export function trackUserAction(actionName, context) {
+    var _a, _b, _c, _d;
+    try {
+        // End any active user action before starting a new one
+        const activeAction = (_b = (_a = faro === null || faro === void 0 ? void 0 : faro.api) === null || _a === void 0 ? void 0 : _a.getActiveUserAction) === null || _b === void 0 ? void 0 : _b.call(_a);
+        activeAction === null || activeAction === void 0 ? void 0 : activeAction.end();
+        return (_d = (_c = faro === null || faro === void 0 ? void 0 : faro.api) === null || _c === void 0 ? void 0 : _c.startUserAction) === null || _d === void 0 ? void 0 : _d.call(_c, actionName, context || {}, { triggerName: 'manual' });
+    }
+    catch (error) {
+        console.warn('[Faro] Error tracking user action:', error);
+        return undefined;
+    }
+}
+//# sourceMappingURL=withFaroUserAction.js.map

package/dist/esm/instrumentations/userActions/withFaroUserAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withFaroUserAction.js","sourceRoot":"","sources":["../../../../src/instrumentations/userActions/withFaroUserAction.tsx"],"names":[],"mappings":";;;;;;;;;;;AAAA,OAAO,KAAK,EAAE,EAAsB,MAAM,OAAO,CAAC;AAGlD,OAAO,EAAE,IAAI,EAAoC,MAAM,oBAAoB,CAAC;AAmB5E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAA2B,EAC3B,iBAAyB;IAEzB,OAAO,SAAS,oBAAoB,CAAC,KAAkC;QACrE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,OAAO,KAAmB,KAAK,EAAnB,SAAS,UAAK,KAAK,EAA9D,4CAAsD,CAAQ,CAAC;QAErE,MAAM,WAAW,GAAG,CAAC,KAA4B,EAAE,EAAE;;YACnD,IAAI,CAAC;gBACH,yDAAyD;gBACzD,MAAM,UAAU,GAAG,cAAc,IAAI,iBAAiB,CAAC;gBAEvD,yFAAyF;gBACzF,2FAA2F;gBAC3F,qFAAqF;gBACrF,iEAAiE;gBACjE,MAAM,YAAY,GAAG,MAAA,MAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,GAAG,0CAAE,mBAAmB,kDAA+C,CAAC;gBACnG,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,GAAG,EAAE,CAAC;gBAEpB,gFAAgF;gBAChF,yEAAyE;gBACzE,MAAA,MAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,GAAG,0CAAE,eAAe,mDAAG,UAAU,EAAE,WAAW,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;YACxF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,0CAA0C;gBAC1C,OAAO,CAAC,IAAI,CAAC,oCAAoC,EAAE,KAAK,CAAC,CAAC;YAC5D,CAAC;YAED,2CAA2C;YAC3C,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAG,KAAK,CAAC,CAAC;QACnB,CAAC,CAAC;QAEF,OAAO,KAAK,CAAC,aAAa,CAAC,SAAS,kCAC9B,SAAe,KACnB,OAAO,EAAE,WAAW,IACpB,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB,EAAE,OAAgC;;IAClF,IAAI,CAAC;QACH,uDAAuD;QACvD,MAAM,YAAY,GAAG,MAAA,MAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,GAAG,0CAAE,mBAAmB,kDAA+C,CAAC;QACnG,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,GAAG,EAAE,CAAC;QACpB,OAAO,MAAA,MAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,GAAG,0CAAE,eAAe,mDAAG,UAAU,EAAE,OAAO,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC5F,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,oCAAoC,EAAE,KAAK,CAAC,CAAC;QAC1D,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC","sourcesContent":["import React, { type ComponentType } from 'react';\nimport type { GestureResponderEvent } from 'react-native';\n\nimport { faro, type UserActionInternalInterface } from '@grafana/faro-core';\n\nexport interface WithFaroUserActionProps {\n  /**\n   * Optional: Override the action name for this specific instance\n   */\n  faroActionName?: string;\n\n  /**\n   * Optional: Additional context to attach to the user action\n   */\n  faroContext?: Record<string, string>;\n\n  /**\n   * The original onPress handler\n   */\n  onPress?: (event: GestureResponderEvent) => void;\n}\n\n/**\n * Higher-Order Component that wraps React Native touchable components\n * to automatically track user interactions.\n *\n * @param Component - The component to wrap (e.g., TouchableOpacity, Button, etc.)\n * @param defaultActionName - The default name for this action\n *\n * @example\n * ```tsx\n * import { TouchableOpacity } from 'react-native';\n * import { withFaroUserAction } from '@grafana/faro-react-native';\n *\n * const TrackedButton = withFaroUserAction(TouchableOpacity, 'submit_form');\n *\n * function MyForm() {\n *   return (\n *     <TrackedButton onPress={handleSubmit}>\n *       <Text>Submit</Text>\n *     </TrackedButton>\n *   );\n * }\n * ```\n */\nexport function withFaroUserAction<P extends Record<string, unknown>>(\n  Component: ComponentType<P>,\n  defaultActionName: string\n): ComponentType<P & WithFaroUserActionProps> {\n  return function FaroTrackedComponent(props: P & WithFaroUserActionProps) {\n    const { faroActionName, faroContext, onPress, ...restProps } = props;\n\n    const handlePress = (event: GestureResponderEvent) => {\n      try {\n        // Use the prop-specific name or fall back to the default\n        const actionName = faroActionName || defaultActionName;\n\n        // End any active user action before starting a new one to avoid \"already running\" errors\n        // (e.g. when user taps another button before the previous action's HTTP request completes)\n        // getActiveUserAction returns UserActionInterface but the runtime object is the full\n        // UserAction implementing UserActionInternalInterface (with end)\n        const activeAction = faro?.api?.getActiveUserAction?.() as UserActionInternalInterface | undefined;\n        activeAction?.end();\n\n        // Start a user action - UserActionInstrumentation subscribes to the message bus\n        // and attaches UserActionController for auto-ending and HTTP correlation\n        faro?.api?.startUserAction?.(actionName, faroContext || {}, { triggerName: 'press' });\n      } catch (error) {\n        // Don't let tracking errors break the app\n        console.warn('[Faro] Error tracking user action:', error);\n      }\n\n      // Always call the original onPress handler\n      onPress?.(event);\n    };\n\n    return React.createElement(Component, {\n      ...(restProps as P),\n      onPress: handlePress,\n    });\n  };\n}\n\n/**\n * Manually track a user action without using the HOC\n *\n * @param actionName - The name of the action\n * @param context - Optional context to attach\n *\n * @example\n * ```tsx\n * import { trackUserAction } from '@grafana/faro-react-native';\n *\n * function handleComplexAction() {\n *   const action = trackUserAction('complex_workflow', { step: '1' });\n *\n *   // Do work...\n *   doSomething();\n *\n *   // End the action when done\n *   action?.end();\n * }\n * ```\n */\nexport function trackUserAction(actionName: string, context?: Record<string, string>) {\n  try {\n    // End any active user action before starting a new one\n    const activeAction = faro?.api?.getActiveUserAction?.() as UserActionInternalInterface | undefined;\n    activeAction?.end();\n    return faro?.api?.startUserAction?.(actionName, context || {}, { triggerName: 'manual' });\n  } catch (error) {\n    console.warn('[Faro] Error tracking user action:', error);\n    return undefined;\n  }\n}\n"]}

package/dist/esm/instrumentations/utils/actionContext.js

@@ -0,0 +1,28 @@
+import { faro, UserActionState, } from '@grafana/faro-core';
+/**
+ * PushEvent options with action context for linking events to user actions.
+ * When an active user action exists, adds payload.action so events appear in
+ * Grafana's user action table (e.g. HTTP Errors column).
+ */
+export function getPushEventOptionsWithActionContext() {
+    var _a, _b, _c;
+    try {
+        const currentAction = (_b = (_a = faro.api) === null || _a === void 0 ? void 0 : _a.getActiveUserAction) === null || _b === void 0 ? void 0 : _b.call(_a);
+        const state = (_c = currentAction === null || currentAction === void 0 ? void 0 : currentAction.getState) === null || _c === void 0 ? void 0 : _c.call(currentAction);
+        if (currentAction && (state === UserActionState.Started || state === UserActionState.Halted)) {
+            const name = currentAction.name;
+            const parentId = currentAction.parentId;
+            return {
+                customPayloadTransformer: (payload) => {
+                    payload.action = { name, parentId };
+                    return payload;
+                },
+            };
+        }
+    }
+    catch (_) {
+        // Silently fail - don't log to avoid instrumentation loops
+    }
+    return undefined;
+}
+//# sourceMappingURL=actionContext.js.map

package/dist/esm/instrumentations/utils/actionContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionContext.js","sourceRoot":"","sources":["../../../../src/instrumentations/utils/actionContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,IAAI,EAGJ,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,oCAAoC;;IAClD,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,MAAA,MAAA,IAAI,CAAC,GAAG,0CAAE,mBAAmB,kDAAI,CAAC;QACxD,MAAM,KAAK,GAAG,MAAC,aAAwD,aAAxD,aAAa,uBAAb,aAAa,CAA6C,QAAQ,6DAAI,CAAC;QACtF,IAAI,aAAa,IAAI,CAAC,KAAK,KAAK,eAAe,CAAC,OAAO,IAAI,KAAK,KAAK,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7F,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC;YAChC,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC;YACxC,OAAO;gBACL,wBAAwB,EAAE,CAAC,OAAmB,EAAc,EAAE;oBAC5D,OAAO,CAAC,MAAM,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;oBACpC,OAAO,OAAO,CAAC;gBACjB,CAAC;aACF,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,2DAA2D;IAC7D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["import {\n  type EventEvent,\n  faro,\n  type PushEventOptions,\n  type UserActionInternalInterface,\n  UserActionState,\n} from '@grafana/faro-core';\n\n/**\n * PushEvent options with action context for linking events to user actions.\n * When an active user action exists, adds payload.action so events appear in\n * Grafana's user action table (e.g. HTTP Errors column).\n */\nexport function getPushEventOptionsWithActionContext(): PushEventOptions | undefined {\n  try {\n    const currentAction = faro.api?.getActiveUserAction?.();\n    const state = (currentAction as unknown as UserActionInternalInterface)?.getState?.();\n    if (currentAction && (state === UserActionState.Started || state === UserActionState.Halted)) {\n      const name = currentAction.name;\n      const parentId = currentAction.parentId;\n      return {\n        customPayloadTransformer: (payload: EventEvent): EventEvent => {\n          payload.action = { name, parentId };\n          return payload;\n        },\n      };\n    }\n  } catch (_) {\n    // Silently fail - don't log to avoid instrumentation loops\n  }\n  return undefined;\n}\n"]}

package/dist/esm/instrumentations/view/index.js

@@ -0,0 +1,42 @@
+import { BaseInstrumentation, EVENT_VIEW_CHANGED, unknownString, VERSION } from '@grafana/faro-core';
+/**
+ * View instrumentation for React Native
+ * Tracks screen/view changes
+ *
+ * This instrumentation listens to meta changes and emits VIEW_CHANGED events
+ * when the screen/view changes. The actual screen tracking is handled by
+ * the navigation integration utilities (useFaroNavigation hook).
+ */
+export class ViewInstrumentation extends BaseInstrumentation {
+    constructor() {
+        super(...arguments);
+        this.name = '@grafana/faro-react-native:instrumentation-view';
+        this.version = VERSION;
+    }
+    sendViewChangedEvent(meta) {
+        var _a, _b, _c, _d;
+        const view = meta.view;
+        if (view && view.name !== ((_a = this.notifiedView) === null || _a === void 0 ? void 0 : _a.name)) {
+            this.api.pushEvent(EVENT_VIEW_CHANGED, {
+                fromView: (_c = (_b = this.notifiedView) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : unknownString,
+                toView: (_d = view.name) !== null && _d !== void 0 ? _d : unknownString,
+            }, undefined, { skipDedupe: true });
+            this.notifiedView = view;
+        }
+    }
+    initialize() {
+        const unsubscribe = this.metas.addListener(this.sendViewChangedEvent.bind(this));
+        this.metaUnsubscribe = typeof unsubscribe === 'function' ? unsubscribe : undefined;
+        this.logInfo('View instrumentation initialized');
+    }
+    /**
+     * Clean up meta listener
+     */
+    unpatch() {
+        if (this.metaUnsubscribe) {
+            this.metaUnsubscribe();
+            this.metaUnsubscribe = undefined;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/instrumentations/view/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/instrumentations/view/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGrG;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,mBAAmB;IAA5D;;QACW,SAAI,GAAG,iDAAiD,CAAC;QACzD,YAAO,GAAG,OAAO,CAAC;IAwC7B,CAAC;IAjCS,oBAAoB,CAAC,IAAU;;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAEvB,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,MAAK,MAAA,IAAI,CAAC,YAAY,0CAAE,IAAI,CAAA,EAAE,CAAC;YAClD,IAAI,CAAC,GAAG,CAAC,SAAS,CAChB,kBAAkB,EAClB;gBACE,QAAQ,EAAE,MAAA,MAAA,IAAI,CAAC,YAAY,0CAAE,IAAI,mCAAI,aAAa;gBAClD,MAAM,EAAE,MAAA,IAAI,CAAC,IAAI,mCAAI,aAAa;aACnC,EACD,SAAS,EACT,EAAE,UAAU,EAAE,IAAI,EAAE,CACrB,CAAC;YAEF,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,UAAU;QACR,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACjF,IAAI,CAAC,eAAe,GAAG,OAAO,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;QACnF,IAAI,CAAC,OAAO,CAAC,kCAAkC,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,IAAI,CAAC,eAAe,EAAE,CAAC;YACvB,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;QACnC,CAAC;IACH,CAAC;CACF","sourcesContent":["import { BaseInstrumentation, EVENT_VIEW_CHANGED, unknownString, VERSION } from '@grafana/faro-core';\nimport type { Meta, MetaView } from '@grafana/faro-core';\n\n/**\n * View instrumentation for React Native\n * Tracks screen/view changes\n *\n * This instrumentation listens to meta changes and emits VIEW_CHANGED events\n * when the screen/view changes. The actual screen tracking is handled by\n * the navigation integration utilities (useFaroNavigation hook).\n */\nexport class ViewInstrumentation extends BaseInstrumentation {\n  readonly name = '@grafana/faro-react-native:instrumentation-view';\n  readonly version = VERSION;\n\n  // previously notified view, to ensure we don't send view changed\n  // event twice for the same view\n  private notifiedView: MetaView | undefined;\n  private metaUnsubscribe: (() => void) | undefined;\n\n  private sendViewChangedEvent(meta: Meta): void {\n    const view = meta.view;\n\n    if (view && view.name !== this.notifiedView?.name) {\n      this.api.pushEvent(\n        EVENT_VIEW_CHANGED,\n        {\n          fromView: this.notifiedView?.name ?? unknownString,\n          toView: view.name ?? unknownString,\n        },\n        undefined,\n        { skipDedupe: true }\n      );\n\n      this.notifiedView = view;\n    }\n  }\n\n  initialize(): void {\n    const unsubscribe = this.metas.addListener(this.sendViewChangedEvent.bind(this));\n    this.metaUnsubscribe = typeof unsubscribe === 'function' ? unsubscribe : undefined;\n    this.logInfo('View instrumentation initialized');\n  }\n\n  /**\n   * Clean up meta listener\n   */\n  unpatch(): void {\n    if (this.metaUnsubscribe) {\n      this.metaUnsubscribe();\n      this.metaUnsubscribe = undefined;\n    }\n  }\n}\n"]}