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

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

@@ -0,0 +1,62 @@
+import { type ComponentType } from 'react';
+import type { GestureResponderEvent } from 'react-native';
+export interface WithFaroUserActionProps {
+    /**
+     * Optional: Override the action name for this specific instance
+     */
+    faroActionName?: string;
+    /**
+     * Optional: Additional context to attach to the user action
+     */
+    faroContext?: Record<string, string>;
+    /**
+     * The original onPress handler
+     */
+    onPress?: (event: GestureResponderEvent) => void;
+}
+/**
+ * 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 declare function withFaroUserAction<P extends Record<string, unknown>>(Component: ComponentType<P>, defaultActionName: string): ComponentType<P & WithFaroUserActionProps>;
+/**
+ * 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 declare function trackUserAction(actionName: string, context?: Record<string, string>): import("@grafana/faro-core").UserActionInterface | undefined;

package/dist/types/instrumentations/utils/actionContext.d.ts

@@ -0,0 +1,7 @@
+import { type PushEventOptions } 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 declare function getPushEventOptionsWithActionContext(): PushEventOptions | undefined;

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

@@ -0,0 +1,21 @@
+import { BaseInstrumentation } 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 declare class ViewInstrumentation extends BaseInstrumentation {
+    readonly name = "@grafana/faro-react-native:instrumentation-view";
+    readonly version = "2.2.3";
+    private notifiedView;
+    private metaUnsubscribe;
+    private sendViewChangedEvent;
+    initialize(): void;
+    /**
+     * Clean up meta listener
+     */
+    unpatch(): void;
+}

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

@@ -0,0 +1,22 @@
+import { BaseInstrumentation } from '@grafana/faro-core';
+/**
+ * XMLHttpRequest instrumentation for React Native
+ *
+ * Tracks XHR and axios (which uses XHR) calls and emits faro.tracing.fetch events.
+ * Same format as HttpInstrumentation for Grafana HTTP insights compatibility.
+ */
+export declare class XHRInstrumentation extends BaseInstrumentation {
+    readonly name = "@grafana/faro-react-native:instrumentation-xhr";
+    readonly version = "2.2.3";
+    private originalOpen?;
+    private originalSend?;
+    private ignoredUrls;
+    private requests;
+    constructor(options?: {
+        ignoredUrls?: RegExp[];
+    });
+    initialize(): void;
+    unpatch(): void;
+    private isUrlIgnored;
+    private patchXHR;
+}

package/dist/types/metas/page.d.ts

@@ -0,0 +1,9 @@
+import type { MetaPage } from '@grafana/faro-core';
+/**
+ * Returns empty page meta for React Native.
+ * This overrides the default page meta from faro-core which is web-specific.
+ * In React Native, we use view meta for screen tracking instead.
+ */
+export declare function getPageMeta(): () => {
+    page?: MetaPage;
+};

package/dist/types/metas/screen.d.ts

@@ -0,0 +1,24 @@
+import { type Meta, type MetaItem } from '@grafana/faro-core';
+type CreateScreenMetaProps = {
+    generateScreenId?: (screenName: string) => string;
+    initialScreenMeta?: Meta['page'];
+};
+/**
+ * Screen meta for React Native
+ * Tracks the current screen name instead of URL (as in web page meta)
+ */
+export declare function createScreenMeta({ generateScreenId, initialScreenMeta }?: CreateScreenMetaProps): MetaItem<Pick<Meta, 'page'>>;
+/**
+ * Updates the current screen name
+ * Called by navigation instrumentation when screen changes
+ */
+export declare function setCurrentScreen(screenName: string): void;
+/**
+ * Gets the current screen name
+ */
+export declare function getCurrentScreen(): string | undefined;
+/**
+ * Default screen meta with no custom configuration
+ */
+export declare const getScreenMeta: () => MetaItem<Pick<Meta, "page">>;
+export {};

package/dist/types/metas/sdk.d.ts

@@ -0,0 +1,6 @@
+import type { Meta, MetaItem } from '@grafana/faro-core';
+/**
+ * SDK meta for React Native
+ * Provides information about the Faro SDK and its integrations
+ */
+export declare const getSdkMeta: () => MetaItem<Pick<Meta, "sdk">>;

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

@@ -0,0 +1,3 @@
+export { useFaroNavigation } from './useFaroNavigation';
+export { createNavigationStateChangeHandler, getCurrentRoute, getRouteName, onNavigationStateChange } from './utils';
+export type { ReactNavigationConfig, ReactNavigationDependencies } from './types';

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

@@ -0,0 +1,21 @@
+import type { NavigationState, PartialState } from '@react-navigation/native';
+/**
+ * React Navigation dependencies that need to be provided by the user
+ */
+export interface ReactNavigationDependencies {
+    useNavigation: () => {
+        navigate: (name: string, params?: object) => void;
+    };
+    useRoute: () => {
+        key: string;
+        name: string;
+        params?: object;
+    };
+    useNavigationState: <T>(selector: (state: NavigationState | PartialState<NavigationState>) => T) => T;
+}
+/**
+ * Configuration for React Navigation integration
+ */
+export interface ReactNavigationConfig {
+    dependencies: ReactNavigationDependencies;
+}

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

@@ -0,0 +1,29 @@
+import type { NavigationContainerRef } from '@react-navigation/native';
+/**
+ * Hook to integrate Faro with React Navigation
+ *
+ * This hook automatically tracks navigation changes and updates Faro's view meta.
+ * It works with both NavigationContainer refs and the useNavigationContainerRef hook.
+ *
+ * @param navigationRef - Reference to the NavigationContainer
+ *
+ * @example
+ * ```
+ * import { useNavigationContainerRef } from '@react-navigation/native';
+ * import { useFaroNavigation } from '@grafana/faro-react-native';
+ *
+ * function App() {
+ *   const navigationRef = useNavigationContainerRef();
+ *   useFaroNavigation(navigationRef);
+ *
+ *   return (
+ *     <NavigationContainer ref={navigationRef}>
+ *       // your navigation
+ *     </NavigationContainer>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFaroNavigation(navigationRef: {
+    current: NavigationContainerRef<any> | null;
+}): void;

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

@@ -0,0 +1,32 @@
+import type { NavigationState, PartialState, Route } from '@react-navigation/native';
+/**
+ * Gets the currently active route from navigation state
+ */
+export declare function getCurrentRoute(state: NavigationState | PartialState<NavigationState> | undefined): Route<string> | undefined;
+/**
+ * Extracts the route name from a route object
+ */
+export declare function getRouteName(route: Route<string> | undefined): string | undefined;
+/**
+ * Handles navigation state changes and updates Faro with the new screen
+ * @param state - The current navigation state
+ */
+export declare function onNavigationStateChange(state: NavigationState | undefined): void;
+/**
+ * Creates a navigation state change handler
+ * Use this with NavigationContainer's onStateChange prop
+ *
+ * @example
+ * ```
+ * import { NavigationContainer } from '@react-navigation/native';
+ * import { createNavigationStateChangeHandler } from '@grafana/faro-react-native';
+ *
+ * const onStateChange = createNavigationStateChangeHandler();
+ *
+ * // In your component:
+ * <NavigationContainer onStateChange={onStateChange}>
+ *   // your navigation
+ * </NavigationContainer>
+ * ```
+ */
+export declare function createNavigationStateChangeHandler(): (state: NavigationState | undefined) => void;

package/dist/types/navigation/v6/index.d.ts

@@ -0,0 +1,12 @@
+import { BaseInstrumentation } from '@grafana/faro-core';
+import type { ReactNavigationConfig } from '../types';
+/**
+ * React Navigation v6 instrumentation for Faro
+ * Tracks navigation events and screen changes
+ */
+export declare class ReactNativeNavigationIntegration extends BaseInstrumentation {
+    readonly name = "@grafana/faro-react-native-navigation";
+    readonly version = "1.0.0";
+    constructor(_config?: ReactNavigationConfig);
+    initialize(): void;
+}

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

@@ -0,0 +1,4 @@
+export { mockReactNativeModules } from './mockReactNativeModules';
+export { mockAsyncStorage } from './mockAsyncStorage';
+export { mockDeviceInfo } from './mockDeviceInfo';
+export { mockAppState } from './mockAppState';

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

@@ -0,0 +1,8 @@
+import { type AppStateStatus } from 'react-native';
+/**
+ * Mock AppState for testing
+ */
+export declare function mockAppState(): {
+    setCurrentState: (state: AppStateStatus) => void;
+    triggerChange: (state: AppStateStatus) => void;
+};

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

@@ -0,0 +1,7 @@
+/**
+ * Mock AsyncStorage for testing
+ */
+export declare function mockAsyncStorage(): {
+    storage: Record<string, string>;
+    mockClear: () => void;
+};

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

@@ -0,0 +1,4 @@
+/**
+ * Mock react-native-device-info for testing
+ */
+export declare function mockDeviceInfo(): void;

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

@@ -0,0 +1,4 @@
+/**
+ * Mock React Native global modules for testing
+ */
+export declare function mockReactNativeModules(): void;

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

@@ -0,0 +1,14 @@
+/**
+ * Jest setup file for React Native tests
+ * Mocks third-party React Native dependencies
+ */
+declare const mockAsyncStorageImpl: {
+    getItem: jest.Mock<Promise<any>, [key: string], any>;
+    setItem: jest.Mock<Promise<void>, [key: string, value: string], any>;
+    removeItem: jest.Mock<Promise<void>, [key: string], any>;
+    clear: jest.Mock<Promise<void>, [], any>;
+    getAllKeys: jest.Mock<Promise<string[]>, [], any>;
+    multiGet: jest.Mock<Promise<any[][]>, [keys: string[]], any>;
+    multiSet: jest.Mock<Promise<void>, [keyValuePairs: [string, string][]], any>;
+    multiRemove: jest.Mock<Promise<void>, [keys: string[]], any>;
+};

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

@@ -0,0 +1,23 @@
+import type { TransportItem } from '@grafana/faro-core';
+export type SendFn = (items: TransportItem[]) => void;
+export interface BatchExecutorOptions {
+    itemLimit?: number;
+    sendTimeout?: number;
+    paused?: boolean;
+}
+export declare class RNBatchExecutor {
+    private readonly itemLimit;
+    private readonly sendTimeout;
+    private signalBuffer;
+    private sendFn;
+    private paused;
+    private flushInterval?;
+    private appStateSubscription?;
+    constructor(sendFn: SendFn, options?: BatchExecutorOptions);
+    addItem(item: TransportItem): void;
+    start(): void;
+    pause(): void;
+    cleanup(): void;
+    groupItems(items: TransportItem[]): TransportItem[][];
+    private flush;
+}

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

@@ -0,0 +1,2 @@
+export { ConsoleTransport } from './transport';
+export type { ConsoleTransportOptions } from './types';

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

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

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

@@ -0,0 +1,4 @@
+import type { LogLevel } from '@grafana/faro-core';
+export interface ConsoleTransportOptions {
+    level?: LogLevel;
+}

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

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

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

@@ -0,0 +1,34 @@
+import { BaseTransport } from '@grafana/faro-core';
+import type { Patterns, PromiseBuffer, TransportItem } from '@grafana/faro-core';
+import type { FetchTransportOptions } from './types';
+export declare class FetchTransport extends BaseTransport {
+    private options;
+    readonly name = "@grafana/faro-react-native:transport-fetch";
+    readonly version = "2.2.3";
+    promiseBuffer: PromiseBuffer<Response | void>;
+    private readonly rateLimitBackoffMs;
+    private readonly getNow;
+    private disabledUntil;
+    private consecutiveFailures;
+    private sessionReadyPromise;
+    private sessionReadyResolve;
+    private sessionReady;
+    private metasListenerRegistered;
+    constructor(options: FetchTransportOptions);
+    /**
+     * Register a listener for metas changes to detect when session becomes available.
+     * Uses faro-core's metas listener pattern instead of polling with setTimeout.
+     */
+    private registerSessionListener;
+    /**
+     * Wait for session to be available before sending.
+     * This prevents 400 errors from the collector due to missing X-Faro-Session-Id header.
+     *
+     * Only waits if session tracking is enabled. If disabled, returns immediately.
+     */
+    private waitForSession;
+    send(items: TransportItem[]): Promise<void>;
+    getIgnoreUrls(): Patterns;
+    isBatched(): boolean;
+    private getRetryAfterDate;
+}

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

@@ -0,0 +1,13 @@
+export interface FetchTransportRequestOptions extends Omit<RequestInit, 'body' | 'headers'> {
+    headers?: Record<string, string>;
+}
+export interface FetchTransportOptions {
+    url: string;
+    apiKey?: string;
+    bufferSize?: number;
+    concurrency?: number;
+    defaultRateLimitBackoffMs?: number;
+    getNow?: ClockFn;
+    requestOptions?: FetchTransportRequestOptions;
+}
+export type ClockFn = () => number;

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

@@ -0,0 +1,26 @@
+import type { ConnectivityService } from './types';
+/**
+ * Service for detecting network connectivity changes.
+ *
+ * Uses @react-native-community/netinfo when available, otherwise falls back
+ * to basic fetch-based connectivity detection.
+ *
+ * Implementation follows Flutter SDK's InternetConnectivityService pattern.
+ */
+export declare class DefaultConnectivityService implements ConnectivityService {
+    private _isOnline;
+    private readonly subscribers;
+    private unsubscribeNetInfo;
+    private checkIntervalId;
+    private readonly checkIntervalMs;
+    constructor(checkIntervalMs?: number);
+    get isOnline(): boolean;
+    subscribe(callback: (isOnline: boolean) => void): () => void;
+    dispose(): void;
+    private initialize;
+    private initializeWithNetInfo;
+    private initializeWithPolling;
+    private checkConnectivity;
+    private setOnline;
+    private notifySubscribers;
+}

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

@@ -0,0 +1,31 @@
+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.
+ *
+ * Uses a mutex pattern for thread-safe file access.
+ */
+export declare class AsyncStorageOfflineCache implements OfflineCache {
+    private readonly storageKey;
+    private readonly maxCacheSize;
+    private lockPromise;
+    constructor(options?: {
+        storageKeyPrefix?: string;
+        maxCacheSize?: number;
+    });
+    write(payload: CachedPayload): Promise<void>;
+    readAll(): Promise<CachedPayload[]>;
+    clear(): Promise<void>;
+    removeByTimestamps(timestamps: number[]): Promise<void>;
+    getCount(): Promise<number>;
+    /**
+     * Execute an operation with a mutex lock to ensure thread-safe access.
+     * Follows Flutter SDK's Completer-based lock pattern.
+     */
+    private withLock;
+    private readAllInternal;
+    private writeAll;
+    private isValidCachedPayload;
+}

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

@@ -0,0 +1,4 @@
+export { OfflineTransport } from './transport';
+export { AsyncStorageOfflineCache } from './OfflineCache';
+export { DefaultConnectivityService } from './ConnectivityService';
+export type { CachedPayload, ConnectivityService, OfflineCache, OfflineTransportOptions } from './types';

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

@@ -0,0 +1,83 @@
+import { BaseTransport } from '@grafana/faro-core';
+import type { Patterns, Transport, TransportItem } from '@grafana/faro-core';
+import type { OfflineTransportOptions } from './types';
+/**
+ * OfflineTransport - Caches telemetry when offline and replays when online.
+ *
+ * This transport wraps other transports and provides offline caching functionality.
+ * 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)
+ * - Respects maxCacheDuration to skip expired entries
+ * - Uses mutex pattern for thread-safe cache access
+ * - Excludes itself when replaying to prevent infinite loops
+ *
+ * @example
+ * ```typescript
+ * import { initializeFaro, FetchTransport, OfflineTransport } from '@grafana/faro-react-native';
+ *
+ * initializeFaro({
+ *   url: 'https://collector.example.com',
+ *   transports: [
+ *     new OfflineTransport({
+ *       maxCacheDurationMs: 3 * 24 * 60 * 60 * 1000, // 3 days
+ *     }),
+ *     new FetchTransport({ url: 'https://collector.example.com' }),
+ *   ],
+ * });
+ * ```
+ */
+export declare class OfflineTransport extends BaseTransport {
+    readonly name = "@grafana/faro-react-native:transport-offline";
+    readonly version = "2.2.3";
+    private readonly cache;
+    private readonly connectivityService;
+    private readonly maxCacheDurationMs;
+    private readonly otherTransports;
+    private unsubscribeConnectivity;
+    private isReplaying;
+    constructor(options?: OfflineTransportOptions);
+    /**
+     * Send telemetry items.
+     *
+     * When offline, items are cached for later replay.
+     * When online, this transport does nothing (other transports handle sending).
+     */
+    send(items: TransportItem | TransportItem[]): Promise<void>;
+    getIgnoreUrls(): Patterns;
+    isBatched(): boolean;
+    /**
+     * Register other transports for replay.
+     * Called by the transport system after initialization.
+     */
+    setOtherTransports(transports: Transport[]): void;
+    /**
+     * Get the current number of cached payloads.
+     */
+    getCachedCount(): Promise<number>;
+    /**
+     * Manually trigger replay of cached payloads.
+     * Useful for testing or when you want to force a replay attempt.
+     */
+    forceReplay(): Promise<void>;
+    /**
+     * Clear all cached payloads.
+     */
+    clearCache(): Promise<void>;
+    /**
+     * Clean up resources.
+     */
+    dispose(): void;
+    /**
+     * Replay cached payloads through other transports.
+     * Follows Flutter SDK's _readFromFile pattern.
+     */
+    private replayCachedPayloads;
+    /**
+     * Send items to all other registered transports.
+     * Follows Flutter SDK's _sendCachedData pattern.
+     */
+    private sendToOtherTransports;
+}

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

@@ -0,0 +1,85 @@
+import type { TransportItem } from '@grafana/faro-core';
+/**
+ * Configuration options for the OfflineTransport.
+ */
+export interface OfflineTransportOptions {
+    /**
+     * Maximum duration to keep cached events.
+     * Events older than this will be discarded on replay.
+     * Default: 3 days (259200000ms)
+     */
+    maxCacheDurationMs?: number;
+    /**
+     * Maximum number of events to cache.
+     * Oldest events will be discarded when limit is reached.
+     * Default: 1000
+     */
+    maxCacheSize?: number;
+    /**
+     * Interval in milliseconds to check connectivity and replay cached events.
+     * Default: 30000 (30 seconds)
+     */
+    connectivityCheckIntervalMs?: number;
+    /**
+     * Storage key prefix for AsyncStorage.
+     * Default: 'faro_offline_cache'
+     */
+    storageKeyPrefix?: string;
+}
+/**
+ * A cached telemetry payload with timestamp for expiration checking.
+ */
+export interface CachedPayload {
+    /**
+     * Timestamp when the payload was cached (milliseconds since epoch).
+     */
+    timestamp: number;
+    /**
+     * The transport items to be sent.
+     */
+    items: TransportItem[];
+}
+/**
+ * Interface for connectivity detection service.
+ */
+export interface ConnectivityService {
+    /**
+     * Whether the device currently has network connectivity.
+     */
+    readonly isOnline: boolean;
+    /**
+     * Subscribe to connectivity changes.
+     * @param callback Function called when connectivity state changes.
+     * @returns Unsubscribe function.
+     */
+    subscribe(callback: (isOnline: boolean) => void): () => void;
+    /**
+     * Clean up resources.
+     */
+    dispose(): void;
+}
+/**
+ * Interface for offline cache storage.
+ */
+export interface OfflineCache {
+    /**
+     * Write a payload to the cache.
+     */
+    write(payload: CachedPayload): Promise<void>;
+    /**
+     * Read all cached payloads.
+     */
+    readAll(): Promise<CachedPayload[]>;
+    /**
+     * Clear all cached payloads.
+     */
+    clear(): Promise<void>;
+    /**
+     * Remove specific payloads by their timestamps.
+     */
+    removeByTimestamps(timestamps: number[]): Promise<void>;
+    /**
+     * Get the number of cached payloads.
+     */
+    getCount(): Promise<number>;
+}