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

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

@@ -0,0 +1,143 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StartupInstrumentation = void 0;
+var react_native_1 = require("react-native");
+var faro_core_1 = require("@grafana/faro-core");
+var FaroReactNativeModule = react_native_1.NativeModules.FaroReactNativeModule;
+/**
+ * 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.
+ */
+var StartupInstrumentation = /** @class */ (function (_super) {
+    __extends(StartupInstrumentation, _super);
+    function StartupInstrumentation(options) {
+        if (options === void 0) { options = {}; }
+        var _this = _super.call(this) || this;
+        _this.options = options;
+        _this.name = '@grafana/faro-react-native:instrumentation-startup';
+        _this.version = faro_core_1.VERSION;
+        /** 0 = came from background (warm start eligible), null = never backgrounded */
+        _this.warmStartTimestamp = null;
+        return _this;
+    }
+    StartupInstrumentation.prototype.initialize = function () {
+        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
+     */
+    StartupInstrumentation.prototype.captureColdStartMetrics = function () {
+        var _this = this;
+        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;
+            }
+            var 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;
+            }
+            var values_1 = {
+                appStartDuration: appStartDuration,
+                coldStart: 1,
+            };
+            setTimeout(function () {
+                _this.api.pushMeasurement({ type: 'app_startup', values: values_1 }, { skipDedupe: true });
+            }, 100);
+            this.logInfo("Cold start metrics captured: ".concat(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.
+     */
+    StartupInstrumentation.prototype.setupWarmStartTracking = function () {
+        var _this = this;
+        this.appStateSubscription = react_native_1.AppState.addEventListener('change', function (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
+                var resumeTimestamp_1 = Date.now();
+                _this.warmStartTimestamp = null;
+                requestAnimationFrame(function () {
+                    var appStartDuration = Date.now() - resumeTimestamp_1;
+                    if (appStartDuration > 0) {
+                        _this.api.pushMeasurement({
+                            type: 'app_startup',
+                            values: { appStartDuration: appStartDuration, coldStart: 0 },
+                        }, { skipDedupe: true });
+                        _this.logInfo("Warm start metrics captured: ".concat(appStartDuration, "ms"));
+                    }
+                });
+            }
+        });
+    };
+    StartupInstrumentation.prototype.unpatch = function () {
+        if (this.appStateSubscription) {
+            this.appStateSubscription.remove();
+            this.appStateSubscription = undefined;
+            this.warmStartTimestamp = null;
+        }
+    };
+    return StartupInstrumentation;
+}(faro_core_1.BaseInstrumentation));
+exports.StartupInstrumentation = StartupInstrumentation;
+//# sourceMappingURL=index.js.map

package/dist/cjs/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/cjs/instrumentations/startup/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/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/cjs/instrumentations/userActions/httpRequestMonitor.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.monitorHttpRequests = monitorHttpRequests;
+exports.notifyHttpRequestStart = notifyHttpRequestStart;
+exports.notifyHttpRequestEnd = notifyHttpRequestEnd;
+var faro_core_1 = require("@grafana/faro-core");
+/**
+ * Monitor for HTTP requests happening during user actions
+ * Tracks fetch requests to correlate with user actions
+ */
+function monitorHttpRequests() {
+    var global = globalThis;
+    if (!global.__FARO_HTTP_MONITOR__) {
+        // Initialize the monitoring observable if it doesn't exist
+        var observable_1 = new faro_core_1.Observable();
+        global.__FARO_HTTP_MONITOR__ = {
+            observable: observable_1,
+            notifyStart: function (request) {
+                try {
+                    observable_1.notify({ type: 'http_request_start', request: request });
+                }
+                catch (_err) {
+                    // Ignore notification errors
+                }
+            },
+            notifyEnd: function (request) {
+                try {
+                    observable_1.notify({ type: 'http_request_end', request: 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
+ */
+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
+ */
+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/cjs/instrumentations/userActions/httpRequestMonitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpRequestMonitor.js","sourceRoot":"","sources":["../../../../src/instrumentations/userActions/httpRequestMonitor.ts"],"names":[],"mappings":";;AA+BA,kDAiCC;AAMD,wDAEC;AAMD,oDAEC;AA7DD,gDAAgD;AAQhD;;;GAGG;AACH,SAAgB,mBAAmB;IAQjC,IAAM,MAAM,GAAG,UAA+B,CAAC;IAE/C,IAAI,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC;QAClC,2DAA2D;QAC3D,IAAM,YAAU,GAAG,IAAI,sBAAU,EAAsB,CAAC;QACxD,MAAM,CAAC,qBAAqB,GAAG;YAC7B,UAAU,cAAA;YACV,WAAW,EAAE,UAAC,OAAkC;gBAC9C,IAAI,CAAC;oBACH,YAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,SAAA,EAAE,CAAC,CAAC;gBAC7D,CAAC;gBAAC,OAAO,IAAI,EAAE,CAAC;oBACd,6BAA6B;gBAC/B,CAAC;YACH,CAAC;YACD,SAAS,EAAE,UAAC,OAAkC;gBAC5C,IAAI,CAAC;oBACH,YAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,SAAA,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,SAAgB,sBAAsB,CAAC,OAAkC;;IACvE,MAAA,MAAA,UAAU,CAAC,qBAAqB,0CAAE,WAAW,mDAAG,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,SAAgB,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/cjs/instrumentations/userActions/index.js

@@ -0,0 +1,86 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserActionInstrumentation = void 0;
+var faro_core_1 = require("@grafana/faro-core");
+var userActionController_1 = require("./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>
+ * ```
+ */
+var UserActionInstrumentation = /** @class */ (function (_super) {
+    __extends(UserActionInstrumentation, _super);
+    function UserActionInstrumentation() {
+        var _this = _super !== null && _super.apply(this, arguments) || this;
+        _this.name = '@grafana/faro-react-native:instrumentation-user-action';
+        _this.version = faro_core_1.VERSION;
+        return _this;
+    }
+    UserActionInstrumentation.prototype.initialize = function () {
+        var _this = this;
+        this.logInfo('User action instrumentation initialized with enhanced tracking');
+        // Subscribe to user action events from the message bus
+        this._userActionSub = faro_core_1.userActionsMessageBus.subscribe(function (_a) {
+            var type = _a.type, userAction = _a.userAction;
+            if (type === 'user_action_start') {
+                _this.logDebug("User action started: ".concat(userAction.name));
+                _this.processUserActionStarted(userAction);
+            }
+        });
+    };
+    /**
+     * Process a started user action by attaching a controller
+     * The controller handles intelligent duration tracking and HTTP correlation
+     */
+    UserActionInstrumentation.prototype.processUserActionStarted = function (userAction) {
+        try {
+            var internalUserAction = userAction;
+            var controller = new userActionController_1.UserActionController(internalUserAction);
+            controller.attach();
+        }
+        catch (error) {
+            this.logError('Error attaching user action controller:', error);
+        }
+    };
+    UserActionInstrumentation.prototype.unpatch = function () {
+        var _a;
+        (_a = this._userActionSub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this._userActionSub = undefined;
+    };
+    return UserActionInstrumentation;
+}(faro_core_1.BaseInstrumentation));
+exports.UserActionInstrumentation = UserActionInstrumentation;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/instrumentations/userActions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAAA,gDAO4B;AAE5B,+DAA8D;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAA+C,6CAAmB;IAAlE;;QACW,UAAI,GAAG,wDAAwD,CAAC;QAChE,aAAO,GAAG,mBAAO,CAAC;;IAkC7B,CAAC;IA9BC,8CAAU,GAAV;QAAA,iBAUC;QATC,IAAI,CAAC,OAAO,CAAC,gEAAgE,CAAC,CAAC;QAE/E,uDAAuD;QACvD,IAAI,CAAC,cAAc,GAAG,iCAAqB,CAAC,SAAS,CAAC,UAAC,EAAoB;gBAAlB,IAAI,UAAA,EAAE,UAAU,gBAAA;YACvE,IAAI,IAAI,KAAK,mBAAmB,EAAE,CAAC;gBACjC,KAAI,CAAC,QAAQ,CAAC,+BAAwB,UAAU,CAAC,IAAI,CAAE,CAAC,CAAC;gBACzD,KAAI,CAAC,wBAAwB,CAAC,UAAU,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACK,4DAAwB,GAAhC,UAAiC,UAA+B;QAC9D,IAAI,CAAC;YACH,IAAM,kBAAkB,GAAG,UAAoD,CAAC;YAChF,IAAM,UAAU,GAAG,IAAI,2CAAoB,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,2CAAO,GAAP;;QACE,MAAA,IAAI,CAAC,cAAc,0CAAE,WAAW,EAAE,CAAC;QACnC,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;IAClC,CAAC;IACH,gCAAC;AAAD,CAAC,AApCD,CAA+C,+BAAmB,GAoCjE;AApCY,8DAAyB","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/cjs/instrumentations/userActions/userActionController.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserActionController = void 0;
+var faro_core_1 = require("@grafana/faro-core");
+var httpRequestMonitor_1 = require("./httpRequestMonitor");
+var defaultFollowUpActionTimeRange = 100; // 100ms after activity stops
+var 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
+ */
+var UserActionController = /** @class */ (function () {
+    function UserActionController(userAction) {
+        this.userAction = userAction;
+        this.http = (0, httpRequestMonitor_1.monitorHttpRequests)();
+        this.runningRequests = new Map();
+        this.isHalted = false;
+    }
+    /**
+     * Attach the controller to start monitoring
+     */
+    UserActionController.prototype.attach = function () {
+        var _this = this;
+        // Subscribe to HTTP requests while action is active/halting
+        this.allMonitorsSub = new faro_core_1.Observable()
+            .merge(this.http)
+            .takeWhile(function () {
+            var state = _this.userAction.getState();
+            return [faro_core_1.UserActionState.Started, faro_core_1.UserActionState.Halted].includes(state);
+        })
+            .filter(function (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(function (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() === faro_core_1.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)
+     */
+    UserActionController.prototype.halt = function () {
+        var _this = this;
+        if (this.userAction.getState() === faro_core_1.UserActionState.Started && !this.isHalted) {
+            this.userAction.halt();
+            this.isHalted = true;
+            // Start halt timeout - max time to wait for pending operations
+            this.haltTid = startTimeout(function () {
+                _this.end();
+            }, defaultHaltTimeout);
+        }
+    };
+    /**
+     * End the user action
+     */
+    UserActionController.prototype.end = function () {
+        this.clearFollowUpTimeout();
+        this.clearHaltTimeout();
+        // Skip if already ended (e.g. user called action.end() manually) - avoids duplicate events
+        var state = this.userAction.getState();
+        if (state === faro_core_1.UserActionState.Ended || state === faro_core_1.UserActionState.Cancelled) {
+            this.cleanup();
+            return;
+        }
+        this.userAction.end();
+        this.cleanup();
+    };
+    /**
+     * Schedule the follow-up action to end the user action
+     */
+    UserActionController.prototype.scheduleFollowUpAction = function () {
+        var _this = this;
+        this.clearFollowUpTimeout();
+        this.followUpTid = startTimeout(function () {
+            _this.end();
+        }, defaultFollowUpActionTimeRange);
+    };
+    /**
+     * Clear the follow-up timeout
+     */
+    UserActionController.prototype.clearFollowUpTimeout = function () {
+        if (this.followUpTid !== undefined) {
+            clearTimeout(this.followUpTid);
+            this.followUpTid = undefined;
+        }
+    };
+    /**
+     * Clear the halt timeout
+     */
+    UserActionController.prototype.clearHaltTimeout = function () {
+        if (this.haltTid !== undefined) {
+            clearTimeout(this.haltTid);
+            this.haltTid = undefined;
+        }
+    };
+    /**
+     * Clean up subscriptions
+     */
+    UserActionController.prototype.cleanup = function () {
+        var _a;
+        (_a = this.allMonitorsSub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this.allMonitorsSub = undefined;
+    };
+    return UserActionController;
+}());
+exports.UserActionController = UserActionController;
+//# sourceMappingURL=userActionController.js.map

package/dist/cjs/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/cjs/instrumentations/userActions/withFaroUserAction.js

@@ -0,0 +1,117 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+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;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFaroUserAction = withFaroUserAction;
+exports.trackUserAction = trackUserAction;
+var react_1 = __importDefault(require("react"));
+var faro_core_1 = require("@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>
+ *   );
+ * }
+ * ```
+ */
+function withFaroUserAction(Component, defaultActionName) {
+    return function FaroTrackedComponent(props) {
+        var faroActionName = props.faroActionName, faroContext = props.faroContext, onPress = props.onPress, restProps = __rest(props, ["faroActionName", "faroContext", "onPress"]);
+        var handlePress = function (event) {
+            var _a, _b, _c, _d;
+            try {
+                // Use the prop-specific name or fall back to the default
+                var 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)
+                var activeAction = (_b = (_a = faro_core_1.faro === null || faro_core_1.faro === void 0 ? void 0 : faro_core_1.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_core_1.faro === null || faro_core_1.faro === void 0 ? void 0 : faro_core_1.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_1.default.createElement(Component, __assign(__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();
+ * }
+ * ```
+ */
+function trackUserAction(actionName, context) {
+    var _a, _b, _c, _d;
+    try {
+        // End any active user action before starting a new one
+        var activeAction = (_b = (_a = faro_core_1.faro === null || faro_core_1.faro === void 0 ? void 0 : faro_core_1.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_core_1.faro === null || faro_core_1.faro === void 0 ? void 0 : faro_core_1.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/cjs/instrumentations/userActions/withFaroUserAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withFaroUserAction.js","sourceRoot":"","sources":["../../../../src/instrumentations/userActions/withFaroUserAction.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,gDAoCC;AAuBD,0CAUC;AAlHD,gDAAkD;AAGlD,gDAA4E;AAmB5E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,kBAAkB,CAChC,SAA2B,EAC3B,iBAAyB;IAEzB,OAAO,SAAS,oBAAoB,CAAC,KAAkC;QAC7D,IAAA,cAAc,GAAyC,KAAK,eAA9C,EAAE,WAAW,GAA4B,KAAK,YAAjC,EAAE,OAAO,GAAmB,KAAK,QAAxB,EAAK,SAAS,UAAK,KAAK,EAA9D,4CAAsD,CAAF,CAAW;QAErE,IAAM,WAAW,GAAG,UAAC,KAA4B;;YAC/C,IAAI,CAAC;gBACH,yDAAyD;gBACzD,IAAM,UAAU,GAAG,cAAc,IAAI,iBAAiB,CAAC;gBAEvD,yFAAyF;gBACzF,2FAA2F;gBAC3F,qFAAqF;gBACrF,iEAAiE;gBACjE,IAAM,YAAY,GAAG,MAAA,MAAA,gBAAI,aAAJ,gBAAI,uBAAJ,gBAAI,CAAE,GAAG,0CAAE,mBAAmB,kDAA+C,CAAC;gBACnG,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,GAAG,EAAE,CAAC;gBAEpB,gFAAgF;gBAChF,yEAAyE;gBACzE,MAAA,MAAA,gBAAI,aAAJ,gBAAI,uBAAJ,gBAAI,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,eAAK,CAAC,aAAa,CAAC,SAAS,wBAC9B,SAAe,KACnB,OAAO,EAAE,WAAW,IACpB,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,eAAe,CAAC,UAAkB,EAAE,OAAgC;;IAClF,IAAI,CAAC;QACH,uDAAuD;QACvD,IAAM,YAAY,GAAG,MAAA,MAAA,gBAAI,aAAJ,gBAAI,uBAAJ,gBAAI,CAAE,GAAG,0CAAE,mBAAmB,kDAA+C,CAAC;QACnG,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,GAAG,EAAE,CAAC;QACpB,OAAO,MAAA,MAAA,gBAAI,aAAJ,gBAAI,uBAAJ,gBAAI,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"]}