@grafana/faro-react-native 1.3.0 → 1.4.0

package/dist/types/instrumentations/startup/index.d.ts

@@ -7,15 +7,12 @@ import type { StartupInstrumentationOptions } from './types';
  * - 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):
+ * **Metrics Captured**:
  * - Cold start: `appStartDuration`, `coldStart: 1`
  * - Warm start: `appStartDuration`, `coldStart: 0`
  *
@@ -37,7 +34,7 @@ import type { StartupInstrumentationOptions } from './types';
 export declare class StartupInstrumentation extends BaseInstrumentation {
     private options;
     readonly name = "@grafana/faro-react-native:instrumentation-startup";
-    readonly version = "2.7.0";
+    readonly version = "2.8.2";
     /** 0 = came from background (warm start eligible), null = never backgrounded */
     private warmStartTimestamp;
     private appStateSubscription;
@@ -45,12 +42,11 @@ export declare class StartupInstrumentation extends BaseInstrumentation {
     initialize(): void;
     /**
      * Captures cold start duration from native (process start to Faro init).
-     * Matches Flutter SDK: appStartDuration + coldStart: 1
+     * Sends appStartDuration with coldStart: 1.
      */
     private captureColdStartMetrics;
     /**
      * Tracks warm start: when app resumes from background, measures time to first frame.
-     * Matches Flutter SDK: setWarmStart on resume, getWarmStart after postFrameCallback.
      */
     private setupWarmStartTracking;
     unpatch(): void;

package/dist/types/instrumentations/userActions/index.d.ts

@@ -24,7 +24,7 @@ import { BaseInstrumentation } from '@grafana/faro-core';
  */
 export declare class UserActionInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-user-action";
-    readonly version = "2.7.0";
+    readonly version = "2.8.2";
     private _userActionSub?;
     initialize(): void;
     /**

package/dist/types/instrumentations/view/index.d.ts

@@ -9,7 +9,7 @@ import { BaseInstrumentation } from '@grafana/faro-core';
  */
 export declare class ViewInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-view";
-    readonly version = "2.7.0";
+    readonly version = "2.8.2";
     private notifiedView;
     private metaUnsubscribe;
     private sendViewChangedEvent;

package/dist/types/instrumentations/xhr/index.d.ts

@@ -7,7 +7,7 @@ import { BaseInstrumentation } from '@grafana/faro-core';
  */
 export declare class XHRInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-xhr";
-    readonly version = "2.7.0";
+    readonly version = "2.8.2";
     private originalOpen?;
     private originalSend?;
     private ignoredUrls;

package/dist/types/navigation/utils.d.ts

@@ -1,4 +1,5 @@
 import type { NavigationState, PartialState, Route } from '@react-navigation/native';
+export declare const EVENT_NAVIGATION = "navigation";
 /**
  * Gets the currently active route from navigation state
  */

package/dist/types/testUtils/mockFaroReactNativeTracing.d.ts

@@ -5,6 +5,6 @@
 import { BaseInstrumentation } from '@grafana/faro-core';
 export declare class TracingInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native-tracing";
-    readonly version = "2.7.0";
+    readonly version = "2.8.2";
     initialize(): void;
 }

package/dist/types/transports/console/transport.d.ts

@@ -4,7 +4,7 @@ import type { ConsoleTransportOptions } from './types';
 export declare class ConsoleTransport extends BaseTransport {
     private options;
     readonly name = "@grafana/faro-react-native:transport-console";
-    readonly version = "2.7.0";
+    readonly version = "2.8.2";
     constructor(options?: ConsoleTransportOptions);
     send(item: TransportItem): void;
 }

package/dist/types/transports/fetch/index.d.ts

@@ -1,2 +1,2 @@
 export { FetchTransport } from './transport';
-export type { FetchTransportOptions, FetchTransportRequestOptions } from './types';
+export type { FetchTransportOptions, FetchTransportRequestOptions, FetchTransportSendOutcome, FetchTransportSendResult, } from './types';

package/dist/types/transports/fetch/transport.d.ts

@@ -1,10 +1,10 @@
 import { BaseTransport } from '@grafana/faro-core';
 import type { Patterns, PromiseBuffer, TransportItem } from '@grafana/faro-core';
-import type { FetchTransportOptions } from './types';
+import type { FetchTransportOptions, FetchTransportSendResult } from './types';
 export declare class FetchTransport extends BaseTransport {
     private options;
     readonly name = "@grafana/faro-react-native:transport-fetch";
-    readonly version = "2.7.0";
+    readonly version = "2.8.2";
     promiseBuffer: PromiseBuffer<Response | void>;
     private readonly rateLimitBackoffMs;
     private readonly getNow;
@@ -28,6 +28,13 @@ export declare class FetchTransport extends BaseTransport {
      */
     private waitForSession;
     send(items: TransportItem[]): Promise<void>;
+    /**
+     * Sends a batch and reports whether the collector accepted it.
+     * The request header uses the live session for collector accounting. Payload
+     * metadata remains independent so delayed signals can retain their original
+     * session.
+     */
+    sendWithResult(items: TransportItem[]): Promise<FetchTransportSendResult>;
     getIgnoreUrls(): Patterns;
     isBatched(): boolean;
     private getRetryAfterDate;

package/dist/types/transports/fetch/types.d.ts

@@ -11,3 +11,8 @@ export interface FetchTransportOptions {
     requestOptions?: FetchTransportRequestOptions;
 }
 export type ClockFn = () => number;
+export type FetchTransportSendOutcome = 'accepted' | 'rejected' | 'failed' | 'skipped';
+export interface FetchTransportSendResult {
+    outcome: FetchTransportSendOutcome;
+    status?: number;
+}

package/dist/types/transports/offline/ConnectivityService.d.ts

@@ -5,7 +5,7 @@ import type { ConnectivityService } from './types';
  * Uses @react-native-community/netinfo when available, otherwise falls back
  * to basic fetch-based connectivity detection.
  *
- * Implementation follows Flutter SDK's InternetConnectivityService pattern.
+ * Monitors network connectivity for offline transport flush behavior.
  */
 export declare class DefaultConnectivityService implements ConnectivityService {
     private _isOnline;

package/dist/types/transports/offline/OfflineCache.d.ts

@@ -3,7 +3,7 @@ import type { CachedPayload, OfflineCache } from './types';
  * File-based offline cache implementation using AsyncStorage.
  *
  * Stores cached telemetry payloads as JSONL (one JSON object per line)
- * following the Flutter SDK's offline transport pattern.
+ * Persistent offline telemetry cache backed by AsyncStorage.
  *
  * Uses a mutex pattern for thread-safe file access.
  */
@@ -22,7 +22,7 @@ export declare class AsyncStorageOfflineCache implements OfflineCache {
     getCount(): Promise<number>;
     /**
      * Execute an operation with a mutex lock to ensure thread-safe access.
-     * Follows Flutter SDK's Completer-based lock pattern.
+     * Async lock to serialize cache read/write operations.
      */
     private withLock;
     private readAllInternal;

package/dist/types/transports/offline/transport.d.ts

@@ -8,8 +8,7 @@ import type { OfflineTransportOptions } from './types';
  * When the device is offline, telemetry is cached to AsyncStorage.
  * When connectivity is restored, cached telemetry is replayed through the wrapped transports.
  *
- * Implementation follows Flutter SDK's OfflineTransport pattern:
- * - Uses AsyncStorage for persistent caching (matching Flutter's SharedPreferences)
+ * Uses AsyncStorage for persistent offline telemetry caching.
  * - Respects maxCacheDuration to skip expired entries
  * - Uses mutex pattern for thread-safe cache access
  * - Excludes itself when replaying to prevent infinite loops
@@ -31,7 +30,7 @@ import type { OfflineTransportOptions } from './types';
  */
 export declare class OfflineTransport extends BaseTransport {
     readonly name = "@grafana/faro-react-native:transport-offline";
-    readonly version = "2.7.0";
+    readonly version = "2.8.2";
     private readonly cache;
     private readonly connectivityService;
     private readonly maxCacheDurationMs;
@@ -72,12 +71,12 @@ export declare class OfflineTransport extends BaseTransport {
     dispose(): void;
     /**
      * Replay cached payloads through other transports.
-     * Follows Flutter SDK's _readFromFile pattern.
+     * Reads cached telemetry from AsyncStorage.
      */
     private replayCachedPayloads;
     /**
      * Send items to all other registered transports.
-     * Follows Flutter SDK's _sendCachedData pattern.
+     * Sends cached telemetry when connectivity is restored.
      */
     private sendToOtherTransports;
 }

package/dist/types/userPersistence/UserPersistence.d.ts

@@ -6,8 +6,7 @@ import type { UserPersistence, UserPersistenceOptions } from './types';
  * Stores user information persistently so it can be restored on app restart.
  * This ensures early telemetry events include user identification.
  *
- * Implementation follows Flutter SDK's UserPersistence pattern:
- * - Uses AsyncStorage for persistence (matching Flutter's SharedPreferences)
+ * Uses AsyncStorage for persistent user data across app sessions.
  * - Stores user as JSON
  * - Handles null/cleared users
  *

package/ios/FaroCrashReporter.swift

@@ -21,6 +21,17 @@ public class FaroCrashReporter: NSObject {
 
     private static var crashReporter: PLCrashReporter?
     private static var isEnabled = false
+    private static let stateLock = NSLock()
+    // activatedAt keeps the persisted context aligned with Android. iOS does not
+    // use it to match a pending PLCrashReporter report.
+    private static let sessionContextKeys = [
+        "sessionId",
+        "activatedAt",
+        "isSampled",
+        "appVersion",
+        "appRelease",
+        "appBundleId"
+    ]
 
     /// Signal descriptions for human-readable crash messages.
     private static let signalDescriptions: [String: String] = [
@@ -50,6 +61,12 @@ public class FaroCrashReporter: NSObject {
     ///
     /// - Returns: true if successfully enabled, false otherwise
     @objc public static func enable() -> Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return enableLocked()
+    }
+
+    private static func enableLocked() -> Bool {
         guard !isEnabled else {
             return true
         }
@@ -90,53 +107,145 @@ public class FaroCrashReporter: NSObject {
         }
     }
 
-    /// Gets crash reports from previous sessions as JSON strings.
+    /// Records the active Faro session in PLCrashReporter's crash-safe custom data.
     ///
-    /// Returns an array of JSON strings, each representing a crash report.
-    /// The JSON format matches the Android implementation for consistency.
-    /// After calling this method, pending crash reports are purged.
+    /// PLCrashReporter copies this data into the report at crash time, allowing a
+    /// recovered crash to retain its original session after the app restarts.
+    /// Keep this payload minimal because it is embedded in every crash report.
+    ///
+    /// - Parameter sessionContext: Sanitized session and app fields from JavaScript
+    /// - Returns: true when the context was stored, false when it was invalid
+    @objc public static func recordSessionContext(_ sessionContext: [String: Any]) -> Bool {
+        let sanitizedContext = sanitizeSessionContext(sessionContext)
+        guard sanitizedContext["sessionId"] != nil,
+              JSONSerialization.isValidJSONObject(sanitizedContext) else {
+            return false
+        }
+
+        do {
+            let data = try JSONSerialization.data(withJSONObject: sanitizedContext)
+            stateLock.lock()
+            defer { stateLock.unlock() }
+            guard enableLocked(), let reporter = crashReporter else {
+                return false
+            }
+            reporter.customData = data
+            return true
+        } catch {
+            print("[FaroCrashReporter] Failed to serialize crash session context: \(error)")
+            return false
+        }
+    }
+
+    /// Gets crash reports from previous sessions without deleting them.
+    ///
+    /// JavaScript acknowledges a report only after successful delivery or an
+    /// intentional local discard.
     ///
     /// - Returns: Array of crash report JSON strings, or nil if no crashes
-    @objc public static func getCrashReports() -> [String]? {
-        // Ensure crash reporter is enabled
-        guard enable() else {
+    @objc public static func getPendingCrashReports() -> [String]? {
+        guard let reporter = enabledReporter(), reporter.hasPendingCrashReport() else {
             return nil
         }
 
-        guard let reporter = crashReporter else {
+        do {
+            let data = try reporter.loadPendingCrashReportDataAndReturnError()
+            let reportId = reportIdentifier(for: data)
+
+            do {
+                let plcrReport = try PLCrashReport(data: data)
+                let crashReport = try FaroCrashReport(from: plcrReport)
+                if let json = exportCrashReportAsJSON(crashReport, reportId: reportId) {
+                    return [json]
+                }
+            } catch {
+                print("[FaroCrashReporter] Failed to parse pending crash report: \(error)")
+            }
+
+            // Return a stable marker so JavaScript can acknowledge an unreadable
+            // report rather than assigning it to the new session or retrying forever.
+            return [malformedReportJSON(reportId: reportId)]
+        } catch {
+            print("[FaroCrashReporter] Failed to load pending crash report: \(error)")
+            _ = purgeUnreadablePendingReport(reporter)
             return nil
         }
+    }
 
+    /// Purges the pending report only when its stable ID was acknowledged.
+    ///
+    /// - Parameter reportIds: Stable IDs handled by JavaScript
+    /// - Returns: true when no matching report remains or the matching report was purged
+    @objc public static func acknowledgeCrashReports(_ reportIds: [String]) -> Bool {
+        guard let reporter = enabledReporter() else {
+            return false
+        }
         guard reporter.hasPendingCrashReport() else {
-            return nil
+            return true
         }
 
-        var crashReports: [String] = []
+        let acknowledgedIds = Set(
+            reportIds
+                .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                .filter { !$0.isEmpty }
+        )
+        guard !acknowledgedIds.isEmpty else {
+            return true
+        }
 
         do {
             let data = try reporter.loadPendingCrashReportDataAndReturnError()
-            let plcrReport = try PLCrashReport(data: data)
-            let crashReport = try FaroCrashReport(from: plcrReport)
-
-            // Convert to JSON matching Android format
-            if let jsonString = exportCrashReportAsJSON(crashReport) {
-                crashReports.append(jsonString)
+            guard acknowledgedIds.contains(reportIdentifier(for: data)) else {
+                return true
             }
+            return reporter.purgePendingCrashReport()
         } catch {
-            print("[FaroCrashReporter] Failed to load crash report: \(error)")
+            print("[FaroCrashReporter] Failed to acknowledge pending crash report: \(error)")
+            return purgeUnreadablePendingReport(reporter)
         }
+    }
 
-        // Purge the crash report after loading
-        reporter.purgePendingCrashReport()
+    /// Gets crash reports from previous sessions as JSON strings.
+    ///
+    /// Returns an array of JSON strings, each representing a crash report.
+    /// The JSON format matches the Android implementation for consistency.
+    /// This legacy API eagerly purges returned reports for older JavaScript bundles
+    /// that cannot acknowledge delivery.
+    ///
+    /// - Returns: Array of crash report JSON strings, or nil if no crashes
+    @objc public static func getCrashReports() -> [String]? {
+        guard let crashReports = getPendingCrashReports() else {
+            return nil
+        }
 
-        return crashReports.isEmpty ? nil : crashReports
+        let reportIds = crashReports.compactMap(reportIdentifier(from:))
+        _ = acknowledgeCrashReports(reportIds)
+        return crashReports
     }
 
     // MARK: - Private Helpers
 
+    private static func enabledReporter() -> PLCrashReporter? {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        guard enableLocked() else {
+            return nil
+        }
+        return crashReporter
+    }
+
+    private static func purgeUnreadablePendingReport(_ reporter: PLCrashReporter) -> Bool {
+        let purged = reporter.purgePendingCrashReport()
+        if !purged {
+            print("[FaroCrashReporter] Failed to purge unreadable pending crash report")
+        }
+        return purged
+    }
+
     /// Converts a FaroCrashReport to JSON string matching the Android format.
-    private static func exportCrashReportAsJSON(_ crashReport: FaroCrashReport) -> String? {
+    private static func exportCrashReportAsJSON(_ crashReport: FaroCrashReport, reportId: String) -> String? {
         var json: [String: Any] = [:]
+        json["reportId"] = reportId
 
         // Reason - matches Android's "reason" field
         // For iOS, we use the signal name as the reason
@@ -176,6 +285,14 @@ public class FaroCrashReporter: NSObject {
             json["incidentId"] = incidentId
         }
 
+        if let sessionContext = decodeSessionContext(crashReport.contextData) {
+            for key in sessionContextKeys {
+                if let value = sessionContext[key] {
+                    json[key] = value
+                }
+            }
+        }
+
         // Convert to JSON string
         do {
             let jsonData = try JSONSerialization.data(withJSONObject: json, options: [])
@@ -186,6 +303,82 @@ public class FaroCrashReporter: NSObject {
         }
     }
 
+    private static func sanitizeSessionContext(_ context: [String: Any]) -> [String: Any] {
+        var sanitized: [String: Any] = [:]
+
+        if let sessionId = nonEmptyString(context["sessionId"]) {
+            sanitized["sessionId"] = sessionId
+        }
+        // Android uses activatedAt to map a crash to persisted session history.
+        // iOS keeps it in the shared context shape, although PLCrashReporter
+        // already snapshots the one active context directly into the report.
+        if let activatedAt = context["activatedAt"] as? NSNumber,
+           activatedAt.doubleValue.isFinite,
+           activatedAt.doubleValue > 0 {
+            sanitized["activatedAt"] = activatedAt
+        }
+        if let isSampled = context["isSampled"] as? NSNumber {
+            sanitized["isSampled"] = isSampled.boolValue
+        }
+        for key in ["appVersion", "appRelease", "appBundleId"] {
+            if let value = nonEmptyString(context[key]) {
+                sanitized[key] = value
+            }
+        }
+
+        return sanitized
+    }
+
+    private static func decodeSessionContext(_ data: Data?) -> [String: Any]? {
+        guard let data else {
+            return nil
+        }
+        do {
+            guard let context = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+                  nonEmptyString(context["sessionId"]) != nil else {
+                return nil
+            }
+            return sanitizeSessionContext(context)
+        } catch {
+            print("[FaroCrashReporter] Failed to decode crash session context: \(error)")
+            return nil
+        }
+    }
+
+    private static func nonEmptyString(_ value: Any?) -> String? {
+        guard let string = value as? String else {
+            return nil
+        }
+        let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func malformedReportJSON(reportId: String) -> String {
+        let data = try? JSONSerialization.data(withJSONObject: ["reportId": reportId])
+        return data.flatMap { String(data: $0, encoding: .utf8) } ?? "{\"reportId\":\"\(reportId)\"}"
+    }
+
+    private static func reportIdentifier(from crashReportJSON: String) -> String? {
+        guard let data = crashReportJSON.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return nil
+        }
+        return nonEmptyString(json["reportId"])
+    }
+
+    private static func reportIdentifier(for data: Data) -> String {
+        // PLCrashReporter stores a single immutable report. A deterministic hash
+        // gives both retrieval and acknowledgement the same stable opaque ID,
+        // including when the report itself cannot be parsed.
+        var hash: UInt64 = 14_695_981_039_346_656_037
+        for byte in data {
+            hash ^= UInt64(byte)
+            hash = hash &* 1_099_511_628_211
+        }
+        let hex = String(hash, radix: 16)
+        return "ios-\(String(repeating: "0", count: max(0, 16 - hex.count)))\(hex)"
+    }
+
     /// Creates a human-readable description of the crash.
     ///
     /// This returns just the descriptive portion. The TypeScript layer formats the

package/ios/FaroReactNative.swift

@@ -20,6 +20,15 @@ import Foundation
 /// but include improvements where applicable (e.g., better memory metric).
 @objc(FaroReactNative)
 public class FaroReactNative: NSObject {
+    /// Stable bundle identity used to isolate persisted session chains.
+    @objc public static func getSessionProcessIdentifier() -> String {
+        return Bundle.main.bundleIdentifier ?? ProcessInfo.processInfo.processName
+    }
+
+    /// App extensions have an NSExtension dictionary in their main bundle.
+    @objc public static func isMainSessionProcess() -> Bool {
+        return Bundle.main.object(forInfoDictionaryKey: "NSExtension") == nil
+    }
 
     // MARK: - App Startup Time
 
@@ -172,4 +181,19 @@ public class FaroReactNative: NSObject {
     @objc public static func getCrashReports() -> [String]? {
         return FaroCrashReporter.getCrashReports()
     }
+
+    /// Records the active Faro session in PLCrashReporter's custom crash data.
+    @objc public static func recordCrashSessionContext(_ sessionContext: [String: Any]) -> Bool {
+        return FaroCrashReporter.recordSessionContext(sessionContext)
+    }
+
+    /// Gets pending crash reports without deleting them.
+    @objc public static func getPendingCrashReports() -> [String]? {
+        return FaroCrashReporter.getPendingCrashReports()
+    }
+
+    /// Purges only the pending report whose stable ID was acknowledged.
+    @objc public static func acknowledgeCrashReports(_ reportIds: [String]) -> Bool {
+        return FaroCrashReporter.acknowledgeCrashReports(reportIds)
+    }
 }

package/ios/FaroReactNativeModule.h

@@ -1,4 +1,5 @@
 #import <React/RCTBridgeModule.h>
+#import <React/RCTInvalidating.h>
 
-@interface FaroReactNativeModule : NSObject <RCTBridgeModule>
+@interface FaroReactNativeModule : NSObject <RCTBridgeModule, RCTInvalidating>
 @end