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

package/dist/esm/userPersistence/UserPersistence.js

@@ -0,0 +1,152 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import AsyncStorage from '@react-native-async-storage/async-storage';
+/**
+ * Default storage key for user data.
+ */
+const DEFAULT_STORAGE_KEY = 'faro_persisted_user';
+/**
+ * UserPersistence implementation using AsyncStorage.
+ *
+ * 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)
+ * - Stores user as JSON
+ * - Handles null/cleared users
+ *
+ * @example
+ * ```typescript
+ * import { createUserPersistence } from '@grafana/faro-react-native';
+ *
+ * // Load user on app start
+ * const persistence = createUserPersistence();
+ * const user = await persistence.loadUser();
+ *
+ * if (user) {
+ *   faro.api.setUser(user);
+ * }
+ *
+ * // Save user when logged in
+ * const loggedInUser = { id: '123', email: 'user@example.com' };
+ * await persistence.saveUser(loggedInUser);
+ *
+ * // Clear on logout
+ * await persistence.clearUser();
+ * ```
+ */
+export class AsyncStorageUserPersistence {
+    constructor(options = {}) {
+        var _a;
+        this.storageKey = (_a = options.storageKey) !== null && _a !== void 0 ? _a : DEFAULT_STORAGE_KEY;
+    }
+    loadUser() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const userJson = yield AsyncStorage.getItem(this.storageKey);
+                if (userJson === null) {
+                    return null;
+                }
+                const userData = JSON.parse(userJson);
+                if (!this.isValidMetaUser(userData)) {
+                    return null;
+                }
+                return userData;
+            }
+            catch (_a) {
+                return null;
+            }
+        });
+    }
+    saveUser(user) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                if (user === null || this.isCleared(user)) {
+                    yield this.clearUser();
+                    return;
+                }
+                const userJson = JSON.stringify(user);
+                yield AsyncStorage.setItem(this.storageKey, userJson);
+            }
+            catch (_a) {
+                // Log failure but don't throw
+            }
+        });
+    }
+    clearUser() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield AsyncStorage.removeItem(this.storageKey);
+            }
+            catch (_a) {
+                // Log failure but don't throw
+            }
+        });
+    }
+    hasPersistedUser() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const userJson = yield AsyncStorage.getItem(this.storageKey);
+                return userJson !== null;
+            }
+            catch (_a) {
+                return false;
+            }
+        });
+    }
+    /**
+     * Check if user is cleared (all fields empty/undefined).
+     */
+    isCleared(user) {
+        return !user.id && !user.email && !user.username && !user.fullName && !user.roles;
+    }
+    /**
+     * Validate that the parsed object is a valid MetaUser.
+     */
+    isValidMetaUser(obj) {
+        if (typeof obj !== 'object' || obj === null) {
+            return false;
+        }
+        // MetaUser has optional string fields, so any object is technically valid
+        // We just need to make sure it's an object
+        return true;
+    }
+}
+/**
+ * Factory function to create a UserPersistence instance.
+ */
+export function createUserPersistence(options = {}) {
+    return new AsyncStorageUserPersistence(options);
+}
+/**
+ * Global user persistence instance.
+ */
+let globalUserPersistence = null;
+/**
+ * Initialize the global user persistence.
+ */
+export function initializeUserPersistence(options = {}) {
+    globalUserPersistence = createUserPersistence(options);
+    return globalUserPersistence;
+}
+/**
+ * Get the global user persistence instance.
+ */
+export function getUserPersistence() {
+    return globalUserPersistence;
+}
+/**
+ * Set a custom user persistence instance.
+ */
+export function setUserPersistence(persistence) {
+    globalUserPersistence = persistence;
+}
+//# sourceMappingURL=UserPersistence.js.map

package/dist/esm/userPersistence/UserPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserPersistence.js","sourceRoot":"","sources":["../../../src/userPersistence/UserPersistence.ts"],"names":[],"mappings":"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","sourcesContent":["import AsyncStorage from '@react-native-async-storage/async-storage';\n\nimport type { MetaUser } from '@grafana/faro-core';\n\nimport type { UserPersistence, UserPersistenceOptions } from './types';\n\n/**\n * Default storage key for user data.\n */\nconst DEFAULT_STORAGE_KEY = 'faro_persisted_user';\n\n/**\n * UserPersistence implementation using AsyncStorage.\n *\n * Stores user information persistently so it can be restored on app restart.\n * This ensures early telemetry events include user identification.\n *\n * Implementation follows Flutter SDK's UserPersistence pattern:\n * - Uses AsyncStorage for persistence (matching Flutter's SharedPreferences)\n * - Stores user as JSON\n * - Handles null/cleared users\n *\n * @example\n * ```typescript\n * import { createUserPersistence } from '@grafana/faro-react-native';\n *\n * // Load user on app start\n * const persistence = createUserPersistence();\n * const user = await persistence.loadUser();\n *\n * if (user) {\n *   faro.api.setUser(user);\n * }\n *\n * // Save user when logged in\n * const loggedInUser = { id: '123', email: 'user@example.com' };\n * await persistence.saveUser(loggedInUser);\n *\n * // Clear on logout\n * await persistence.clearUser();\n * ```\n */\nexport class AsyncStorageUserPersistence implements UserPersistence {\n  private readonly storageKey: string;\n\n  constructor(options: UserPersistenceOptions = {}) {\n    this.storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;\n  }\n\n  async loadUser(): Promise<MetaUser | null> {\n    try {\n      const userJson = await AsyncStorage.getItem(this.storageKey);\n      if (userJson === null) {\n        return null;\n      }\n\n      const userData = JSON.parse(userJson);\n      if (!this.isValidMetaUser(userData)) {\n        return null;\n      }\n\n      return userData;\n    } catch {\n      return null;\n    }\n  }\n\n  async saveUser(user: MetaUser | null): Promise<void> {\n    try {\n      if (user === null || this.isCleared(user)) {\n        await this.clearUser();\n        return;\n      }\n\n      const userJson = JSON.stringify(user);\n      await AsyncStorage.setItem(this.storageKey, userJson);\n    } catch {\n      // Log failure but don't throw\n    }\n  }\n\n  async clearUser(): Promise<void> {\n    try {\n      await AsyncStorage.removeItem(this.storageKey);\n    } catch {\n      // Log failure but don't throw\n    }\n  }\n\n  async hasPersistedUser(): Promise<boolean> {\n    try {\n      const userJson = await AsyncStorage.getItem(this.storageKey);\n      return userJson !== null;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Check if user is cleared (all fields empty/undefined).\n   */\n  private isCleared(user: MetaUser): boolean {\n    return !user.id && !user.email && !user.username && !user.fullName && !user.roles;\n  }\n\n  /**\n   * Validate that the parsed object is a valid MetaUser.\n   */\n  private isValidMetaUser(obj: unknown): obj is MetaUser {\n    if (typeof obj !== 'object' || obj === null) {\n      return false;\n    }\n\n    // MetaUser has optional string fields, so any object is technically valid\n    // We just need to make sure it's an object\n    return true;\n  }\n}\n\n/**\n * Factory function to create a UserPersistence instance.\n */\nexport function createUserPersistence(options: UserPersistenceOptions = {}): UserPersistence {\n  return new AsyncStorageUserPersistence(options);\n}\n\n/**\n * Global user persistence instance.\n */\nlet globalUserPersistence: UserPersistence | null = null;\n\n/**\n * Initialize the global user persistence.\n */\nexport function initializeUserPersistence(options: UserPersistenceOptions = {}): UserPersistence {\n  globalUserPersistence = createUserPersistence(options);\n  return globalUserPersistence;\n}\n\n/**\n * Get the global user persistence instance.\n */\nexport function getUserPersistence(): UserPersistence | null {\n  return globalUserPersistence;\n}\n\n/**\n * Set a custom user persistence instance.\n */\nexport function setUserPersistence(persistence: UserPersistence | null): void {\n  globalUserPersistence = persistence;\n}\n"]}

package/dist/esm/userPersistence/index.js

@@ -0,0 +1,2 @@
+export { AsyncStorageUserPersistence, createUserPersistence, getUserPersistence, initializeUserPersistence, setUserPersistence, } from './UserPersistence';
+//# sourceMappingURL=index.js.map

package/dist/esm/userPersistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/userPersistence/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC","sourcesContent":["export {\n  AsyncStorageUserPersistence,\n  createUserPersistence,\n  getUserPersistence,\n  initializeUserPersistence,\n  setUserPersistence,\n} from './UserPersistence';\nexport type { UserPersistence, UserPersistenceOptions } from './types';\n"]}

package/dist/esm/userPersistence/types.js

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

package/dist/esm/userPersistence/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/userPersistence/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { MetaUser } from '@grafana/faro-core';\n\n/**\n * Interface for user data persistence.\n *\n * Handles saving and loading user data between app sessions.\n */\nexport interface UserPersistence {\n  /**\n   * Load the persisted user from storage.\n   * Returns null if no user has been persisted.\n   */\n  loadUser(): Promise<MetaUser | null>;\n\n  /**\n   * Save the user to storage.\n   * If user is null or cleared, any previously persisted user data is cleared.\n   */\n  saveUser(user: MetaUser | null): Promise<void>;\n\n  /**\n   * Clear any persisted user data.\n   */\n  clearUser(): Promise<void>;\n\n  /**\n   * Check if there is persisted user data.\n   */\n  hasPersistedUser(): Promise<boolean>;\n}\n\n/**\n * Options for creating a UserPersistence instance.\n */\nexport interface UserPersistenceOptions {\n  /**\n   * Storage key for persisting user data.\n   * Default: 'faro_persisted_user'\n   */\n  storageKey?: string;\n}\n"]}

package/dist/esm/util/performanceObserverPolyfill.js

@@ -0,0 +1,59 @@
+/**
+ * PerformanceObserver polyfill for React Native iOS
+ *
+ * React Native 0.84's native PerformanceObserver has a bug on iOS that throws
+ * `bad_variant_access` when the observer callback runs and calls getEntries().
+ * This happens in NativePerformance.createObserver when the native bridge
+ * returns data that causes a C++ variant access error.
+ *
+ * OpenTelemetry's FetchInstrumentation (and other libs) may use PerformanceObserver
+ * for resource timing. We provide a no-op polyfill on React Native iOS to prevent
+ * the crash while preserving refresh rate vitals and other functionality.
+ *
+ * @see https://github.com/facebook/react-native/issues (PerformanceObserver iOS)
+ */
+import { Platform } from 'react-native';
+const globalObj = (typeof globalThis !== 'undefined' && globalThis) ||
+    (typeof global !== 'undefined' && global) ||
+    (typeof window !== 'undefined' && window) ||
+    {};
+/**
+ * No-op PerformanceObserver that matches the Web API interface.
+ * Prevents crashes when React Native's native implementation throws.
+ */
+class NoopPerformanceObserver {
+    constructor(_callback) {
+        // Callback is never invoked - avoids triggering the native bug
+    }
+    observe(_options) {
+        // No-op
+    }
+    disconnect() {
+        // No-op
+    }
+    takeRecords() {
+        return [];
+    }
+}
+NoopPerformanceObserver.supportedEntryTypes = [];
+/**
+ * Apply polyfill on React Native iOS to prevent bad_variant_access crash.
+ * Must run before any code that might use PerformanceObserver.
+ */
+export function applyPerformanceObserverPolyfill() {
+    if (Platform.OS !== 'ios') {
+        return;
+    }
+    const record = globalObj;
+    const existing = record['PerformanceObserver'];
+    if (existing && existing.name === 'NoopPerformanceObserver') {
+        return; // Already applied
+    }
+    try {
+        record['PerformanceObserver'] = NoopPerformanceObserver;
+    }
+    catch (_a) {
+        // Ignore if global is frozen (e.g. in some test environments)
+    }
+}
+//# sourceMappingURL=performanceObserverPolyfill.js.map

package/dist/esm/util/performanceObserverPolyfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performanceObserverPolyfill.js","sourceRoot":"","sources":["../../../src/util/performanceObserverPolyfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,MAAM,SAAS,GACb,CAAC,OAAO,UAAU,KAAK,WAAW,IAAI,UAAU,CAAC;IACjD,CAAC,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC;IACzC,CAAC,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC;IACzC,EAAE,CAAC;AAqBL;;;GAGG;AACH,MAAM,uBAAuB;IAC3B,YACE,SAIS;QAET,+DAA+D;IACjE,CAAC;IAED,OAAO,CAAC,QAAkC;QACxC,QAAQ;IACV,CAAC;IAED,UAAU;QACR,QAAQ;IACV,CAAC;IAED,WAAW;QACT,OAAO,EAAE,CAAC;IACZ,CAAC;;AAEe,2CAAmB,GAAa,EAAE,CAAC;AAGrD;;;GAGG;AACH,MAAM,UAAU,gCAAgC;IAC9C,IAAI,QAAQ,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,SAAoC,CAAC;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAC/C,IAAI,QAAQ,IAAK,QAAyC,CAAC,IAAI,KAAK,yBAAyB,EAAE,CAAC;QAC9F,OAAO,CAAC,kBAAkB;IAC5B,CAAC;IAED,IAAI,CAAC;QACH,MAAM,CAAC,qBAAqB,CAAC,GAAG,uBAAuB,CAAC;IAC1D,CAAC;IAAC,WAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;AACH,CAAC","sourcesContent":["/**\n * PerformanceObserver polyfill for React Native iOS\n *\n * React Native 0.84's native PerformanceObserver has a bug on iOS that throws\n * `bad_variant_access` when the observer callback runs and calls getEntries().\n * This happens in NativePerformance.createObserver when the native bridge\n * returns data that causes a C++ variant access error.\n *\n * OpenTelemetry's FetchInstrumentation (and other libs) may use PerformanceObserver\n * for resource timing. We provide a no-op polyfill on React Native iOS to prevent\n * the crash while preserving refresh rate vitals and other functionality.\n *\n * @see https://github.com/facebook/react-native/issues (PerformanceObserver iOS)\n */\n\nimport { Platform } from 'react-native';\n\nconst globalObj =\n  (typeof globalThis !== 'undefined' && globalThis) ||\n  (typeof global !== 'undefined' && global) ||\n  (typeof window !== 'undefined' && window) ||\n  {};\n\ninterface PerformanceEntry {\n  readonly duration: number;\n  readonly entryType: string;\n  readonly name: string;\n  readonly startTime: number;\n}\n\ninterface PerformanceObserverEntryList {\n  getEntries(): PerformanceEntry[];\n  getEntriesByName(name: string, type?: string): PerformanceEntry[];\n  getEntriesByType(type: string): PerformanceEntry[];\n}\n\ninterface PerformanceObserverInit {\n  entryTypes?: string[];\n  type?: string;\n  buffered?: boolean;\n}\n\n/**\n * No-op PerformanceObserver that matches the Web API interface.\n * Prevents crashes when React Native's native implementation throws.\n */\nclass NoopPerformanceObserver {\n  constructor(\n    _callback: (\n      list: PerformanceObserverEntryList,\n      observer: NoopPerformanceObserver,\n      options?: PerformanceObserverInit\n    ) => void\n  ) {\n    // Callback is never invoked - avoids triggering the native bug\n  }\n\n  observe(_options?: PerformanceObserverInit): void {\n    // No-op\n  }\n\n  disconnect(): void {\n    // No-op\n  }\n\n  takeRecords(): PerformanceEntry[] {\n    return [];\n  }\n\n  static readonly supportedEntryTypes: string[] = [];\n}\n\n/**\n * Apply polyfill on React Native iOS to prevent bad_variant_access crash.\n * Must run before any code that might use PerformanceObserver.\n */\nexport function applyPerformanceObserverPolyfill(): void {\n  if (Platform.OS !== 'ios') {\n    return;\n  }\n\n  const record = globalObj as Record<string, unknown>;\n  const existing = record['PerformanceObserver'];\n  if (existing && (existing as unknown as { name?: string }).name === 'NoopPerformanceObserver') {\n    return; // Already applied\n  }\n\n  try {\n    record['PerformanceObserver'] = NoopPerformanceObserver;\n  } catch {\n    // Ignore if global is frozen (e.g. in some test environments)\n  }\n}\n"]}

package/dist/esm/utils/throttle.js

@@ -0,0 +1,34 @@
+/**
+ * Creates a throttled function that only invokes the provided function at most once per
+ * every `wait` milliseconds.
+ *
+ * @param func - The function to throttle
+ * @param wait - The number of milliseconds to throttle invocations to
+ * @returns A throttled version of the function
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic utility needs to accept any function signature
+export function throttle(func, wait) {
+    let timeout = null;
+    let previous = 0;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Need to preserve function context
+    return function (...args) {
+        const now = Date.now();
+        const remaining = wait - (now - previous);
+        if (remaining <= 0 || remaining > wait) {
+            if (timeout) {
+                clearTimeout(timeout);
+                timeout = null;
+            }
+            previous = now;
+            func.apply(this, args);
+        }
+        else if (!timeout) {
+            timeout = setTimeout(() => {
+                previous = Date.now();
+                timeout = null;
+                func.apply(this, args);
+            }, remaining);
+        }
+    };
+}
+//# sourceMappingURL=throttle.js.map

package/dist/esm/utils/throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.js","sourceRoot":"","sources":["../../../src/utils/throttle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wHAAwH;AACxH,MAAM,UAAU,QAAQ,CAAoC,IAAO,EAAE,IAAY;IAC/E,IAAI,OAAO,GAAyC,IAAI,CAAC;IACzD,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,mGAAmG;IACnG,OAAO,UAAqB,GAAG,IAAmB;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAC;QAE1C,IAAI,SAAS,IAAI,CAAC,IAAI,SAAS,GAAG,IAAI,EAAE,CAAC;YACvC,IAAI,OAAO,EAAE,CAAC;gBACZ,YAAY,CAAC,OAAO,CAAC,CAAC;gBACtB,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;YACD,QAAQ,GAAG,GAAG,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACzB,CAAC;aAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;gBACxB,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACtB,OAAO,GAAG,IAAI,CAAC;gBACf,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACzB,CAAC,EAAE,SAAS,CAAC,CAAC;QAChB,CAAC;IACH,CAAM,CAAC;AACT,CAAC","sourcesContent":["/**\n * Creates a throttled function that only invokes the provided function at most once per\n * every `wait` milliseconds.\n *\n * @param func - The function to throttle\n * @param wait - The number of milliseconds to throttle invocations to\n * @returns A throttled version of the function\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic utility needs to accept any function signature\nexport function throttle<T extends (...args: any[]) => any>(func: T, wait: number): T {\n  let timeout: ReturnType<typeof setTimeout> | null = null;\n  let previous = 0;\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Need to preserve function context\n  return function (this: any, ...args: Parameters<T>) {\n    const now = Date.now();\n    const remaining = wait - (now - previous);\n\n    if (remaining <= 0 || remaining > wait) {\n      if (timeout) {\n        clearTimeout(timeout);\n        timeout = null;\n      }\n      previous = now;\n      func.apply(this, args);\n    } else if (!timeout) {\n      timeout = setTimeout(() => {\n        previous = Date.now();\n        timeout = null;\n        func.apply(this, args);\n      }, remaining);\n    }\n  } as T;\n}\n"]}

package/dist/types/config/getRNInstrumentations.d.ts

@@ -0,0 +1,26 @@
+import type { Instrumentation } from '@grafana/faro-core';
+import type { ReactNativeConfig } from './types';
+/**
+ * Returns the default set of instrumentations for React Native.
+ *
+ * Reads all options from the Faro config (single source of truth).
+ * Property names are aligned with Flutter SDK FaroConfig:
+ * - cpuUsageVitals, memoryUsageVitals, anrTracking, refreshRateVitals
+ * - enableCrashReporting, enableErrorReporting
+ * - fetchVitalsInterval, ignoreUrls
+ *
+ * @example
+ * ```ts
+ * const config: ReactNativeConfig = {
+ *   app: { name: 'my-app', version: '1.0.0' },
+ *   cpuUsageVitals: true,
+ *   memoryUsageVitals: true,
+ *   anrTracking: true,
+ *   refreshRateVitals: true,
+ *   enableCrashReporting: true,
+ *   fetchVitalsInterval: 30000,
+ *   instrumentations: getRNInstrumentations(config),
+ * };
+ * ```
+ */
+export declare function getRNInstrumentations(config?: Partial<ReactNativeConfig>): Instrumentation[];

package/dist/types/config/makeRNConfig.d.ts

@@ -0,0 +1,9 @@
+import type { Config } from '@grafana/faro-core';
+import type { ReactNativeConfig } from './types';
+/**
+ * Creates a full Faro config from React Native flag-based config.
+ *
+ * Based on flags, builds instrumentations and transports automatically.
+ * Client just enables what they need; makeRNConfig does the rest.
+ */
+export declare function makeRNConfig(config: ReactNativeConfig): Config;

package/dist/types/config/sampling.d.ts

@@ -0,0 +1,133 @@
+import type { Meta } from '@grafana/faro-core';
+/**
+ * Context passed to sampling implementations.
+ *
+ * Provides access to the current metadata state at SDK initialization time,
+ * allowing sampling decisions based on session attributes, user info, app
+ * environment, and other metadata.
+ *
+ * This aligns with the Faro Flutter SDK's `SamplingContext` which provides
+ * `meta` to the sampler.
+ *
+ * @example
+ * ```ts
+ * sampling: SamplingFunction((context) => {
+ *   // Sample all beta users
+ *   if (context.meta.user?.attributes?.['role'] === 'beta') {
+ *     return 1;
+ *   }
+ *   // Sample 10% of production sessions
+ *   if (context.meta.app?.environment === 'production') {
+ *     return 0.1;
+ *   }
+ *   return 1;
+ * })
+ * ```
+ */
+export interface SamplingContext {
+    /** The current merged metadata state (session, user, app, sdk, view). */
+    meta: Meta;
+}
+/**
+ * Defines how sessions should be sampled.
+ *
+ * Implement this interface to provide custom sampling logic. Use one of the
+ * built-in implementations:
+ * - {@link SamplingRate} for a fixed sampling rate
+ * - {@link SamplingFunction} for dynamic sampling based on context
+ *
+ * @example
+ * ```ts
+ * // Fixed 10% sampling
+ * sessionTracking: {
+ *   sampling: new SamplingRate(0.1),
+ * }
+ *
+ * // Dynamic sampling based on context
+ * sessionTracking: {
+ *   sampling: new SamplingFunction((context) => {
+ *     if (context.meta.app?.environment === 'production') {
+ *       return 0.1;
+ *     }
+ *     return 1;
+ *   }),
+ * }
+ *
+ * // Custom implementation
+ * class BetaUserSampling implements Sampling {
+ *   resolve(context: SamplingContext): number {
+ *     return context.meta.user?.attributes?.['role'] === 'beta' ? 1 : 0.1;
+ *   }
+ * }
+ * sessionTracking: { sampling: new BetaUserSampling() }
+ * ```
+ */
+export interface Sampling {
+    /**
+     * Resolves the sampling rate for the given context.
+     *
+     * @param context - The current metadata state
+     * @returns A value between 0 and 1 (inclusive). Values are clamped to [0, 1].
+     *   - 1: Sample all sessions (100%)
+     *   - 0.5: Sample half of sessions (50%)
+     *   - 0: Sample no sessions (0%)
+     */
+    resolve(context: SamplingContext): number;
+}
+/**
+ * Fixed sampling rate.
+ *
+ * Use this when you want a constant sampling probability regardless of
+ * session context.
+ *
+ * @example
+ * ```ts
+ * sessionTracking: {
+ *   sampling: new SamplingRate(0.1), // 10% of sessions
+ * }
+ * ```
+ */
+export declare class SamplingRate implements Sampling {
+    readonly rate: number;
+    /**
+     * Creates a fixed sampling rate.
+     *
+     * @param rate - The fixed sampling rate (0 to 1). Values are clamped to [0, 1].
+     */
+    constructor(rate: number);
+    resolve(_context: SamplingContext): number;
+}
+/**
+ * Dynamic sampling based on context.
+ *
+ * Use this when you want to make sampling decisions based on session
+ * metadata like user attributes, app environment, or other context.
+ *
+ * @example
+ * ```ts
+ * sessionTracking: {
+ *   sampling: new SamplingFunction((context) => {
+ *     // Sample all beta users
+ *     if (context.meta.user?.attributes?.['role'] === 'beta') {
+ *       return 1;
+ *     }
+ *     // Sample 10% of production sessions
+ *     if (context.meta.app?.environment === 'production') {
+ *       return 0.1;
+ *     }
+ *     return 1;
+ *   }),
+ * }
+ * ```
+ */
+export declare class SamplingFunction implements Sampling {
+    private readonly fn;
+    /**
+     * Creates a dynamic sampler with the given function.
+     *
+     * @param fn - The function that determines the rate based on context.
+     *   Receives a {@link SamplingContext} and should return a rate between 0 and 1.
+     */
+    constructor(fn: (context: SamplingContext) => number);
+    resolve(context: SamplingContext): number;
+}

package/dist/types/config/types.d.ts

@@ -0,0 +1,68 @@
+import type { Config } from '@grafana/faro-core';
+import type { ANRInstrumentationOptions } from '../instrumentations/anr';
+import type { FrameMonitoringOptions } from '../instrumentations/frameMonitoring';
+import type { Sampling } from './sampling';
+/**
+ * React Native session tracking config.
+ * Extends Config['sessionTracking'] with sampling (Flutter-style) and RN-specific props.
+ * Excludes samplingRate and sampler in favor of sampling.
+ */
+export type ReactNativeSessionTrackingConfig = Omit<NonNullable<Config['sessionTracking']>, 'samplingRate' | 'sampler'> & {
+    /**
+     * Session sampling. Use {@link SamplingRate} for fixed rate or
+     * {@link SamplingFunction} for dynamic sampling.
+     */
+    sampling?: Sampling;
+};
+/**
+ * Flags for enabling optional built-in transports.
+ * FetchTransport is always instantiated when url is provided.
+ */
+export interface EnableTransportsConfig {
+    /** Enable OfflineTransport for caching when offline (default: false) */
+    offline?: boolean;
+    /** Enable ConsoleTransport to log telemetry to Metro console for debugging (default: false) */
+    console?: boolean;
+}
+/** RN-specific config: overrides + new props. Omit faro-core props we replace with RN equivalents. */
+type ReactNativeConfigOverrides = {
+    /** Application metadata (required) */
+    app: Config['app'];
+    sessionTracking?: ReactNativeSessionTrackingConfig;
+    url?: string;
+    apiKey?: string;
+    enableTransports?: EnableTransportsConfig;
+    /**
+     * Which HTTP instrumentations to enable. When tracing is disabled, these control
+     * HttpInstrumentation (fetch) and XHRInstrumentation (xhr). Default: both true.
+     */
+    enableHttpInstrumentation?: {
+        /** HttpInstrumentation - patches fetch API (default: true) */
+        fetch?: boolean;
+        /** XHRInstrumentation - patches XMLHttpRequest (default: true) */
+        xhr?: boolean;
+    };
+    enableTracing?: boolean;
+    /** Passed to TracingInstrumentation. See TracingInstrumentationOptions in @grafana/faro-react-native-tracing. */
+    tracingOptions?: Record<string, unknown>;
+    cpuUsageVitals?: boolean;
+    memoryUsageVitals?: boolean;
+    refreshRateVitals?: boolean;
+    fetchVitalsInterval?: number;
+    frameMonitoringOptions?: FrameMonitoringOptions;
+    enableErrorReporting?: boolean;
+    enableCrashReporting?: boolean;
+    anrTracking?: boolean;
+    anrOptions?: ANRInstrumentationOptions;
+    enableConsoleCapture?: boolean;
+    consoleCaptureOptions?: Config['consoleInstrumentation'];
+    enableUserActions?: boolean;
+    userActionsOptions?: Config['userActionsInstrumentation'];
+};
+/**
+ * React Native config: Config (omit replaced props) & overrides.
+ * Omit: sessionTracking, consoleInstrumentation, userActionsInstrumentation.
+ * instrumentations and transports inherited from Config for extras (built-ins come from flags).
+ */
+export type ReactNativeConfig = Partial<Omit<Config, 'sessionTracking' | 'consoleInstrumentation' | 'userActionsInstrumentation'>> & ReactNativeConfigOverrides;
+export {};

package/dist/types/dataCollection/DataCollectionPolicy.d.ts

@@ -0,0 +1,91 @@
+import type { DataCollectionPolicy, DataCollectionPolicyOptions } from './types';
+/**
+ * DataCollectionPolicy implementation using AsyncStorage.
+ *
+ * Controls whether telemetry data is collected and sent.
+ * The setting is persisted to AsyncStorage so it survives app restarts.
+ *
+ * Implementation follows Flutter SDK's DataCollectionPolicy pattern:
+ * - Uses AsyncStorage for persistence (matching Flutter's SharedPreferences)
+ * - Provides enable/disable methods
+ * - Initializes from persisted value or default
+ *
+ * @example
+ * ```typescript
+ * import { createDataCollectionPolicy } from '@grafana/faro-react-native';
+ *
+ * // Create and initialize the policy
+ * const policy = await createDataCollectionPolicy();
+ *
+ * // Check if enabled
+ * if (policy.isEnabled) {
+ *   // Data collection is allowed
+ * }
+ *
+ * // User opts out
+ * await policy.disable();
+ *
+ * // User opts back in
+ * await policy.enable();
+ * ```
+ */
+export declare class AsyncStorageDataCollectionPolicy implements DataCollectionPolicy {
+    private _isEnabled;
+    private readonly storageKey;
+    private readonly subscribers;
+    private constructor();
+    /**
+     * Create and initialize a DataCollectionPolicy.
+     *
+     * This async factory method loads the persisted value from AsyncStorage.
+     */
+    static create(options?: DataCollectionPolicyOptions): Promise<AsyncStorageDataCollectionPolicy>;
+    get isEnabled(): boolean;
+    enable(): Promise<void>;
+    disable(): Promise<void>;
+    subscribe(callback: (isEnabled: boolean) => void): () => void;
+    private initialize;
+    private persistSetting;
+    private notifySubscribers;
+}
+/**
+ * Factory function to create a DataCollectionPolicy.
+ *
+ * @example
+ * ```typescript
+ * const policy = await createDataCollectionPolicy();
+ * ```
+ */
+export declare function createDataCollectionPolicy(options?: DataCollectionPolicyOptions): Promise<DataCollectionPolicy>;
+/**
+ * Initialize the global data collection policy.
+ *
+ * This should be called early in app initialization, before initializeFaro().
+ *
+ * @example
+ * ```typescript
+ * import { initializeDataCollectionPolicy, getDataCollectionPolicy } from '@grafana/faro-react-native';
+ *
+ * // Early in app startup
+ * await initializeDataCollectionPolicy();
+ *
+ * // Later, check if collection is enabled
+ * const policy = getDataCollectionPolicy();
+ * if (policy?.isEnabled) {
+ *   // Initialize Faro
+ * }
+ * ```
+ */
+export declare function initializeDataCollectionPolicy(options?: DataCollectionPolicyOptions): Promise<DataCollectionPolicy>;
+/**
+ * Get the global data collection policy.
+ *
+ * Returns null if not initialized.
+ */
+export declare function getDataCollectionPolicy(): DataCollectionPolicy | null;
+/**
+ * Set a custom data collection policy.
+ *
+ * Useful for testing or custom implementations.
+ */
+export declare function setDataCollectionPolicy(policy: DataCollectionPolicy | null): void;

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

@@ -0,0 +1,2 @@
+export { AsyncStorageDataCollectionPolicy, createDataCollectionPolicy, getDataCollectionPolicy, initializeDataCollectionPolicy, setDataCollectionPolicy, } from './DataCollectionPolicy';
+export type { DataCollectionPolicy, DataCollectionPolicyOptions } from './types';

package/dist/types/dataCollection/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Interface for data collection policy management.
+ *
+ * Controls whether telemetry data is collected and sent.
+ * Useful for GDPR compliance and user privacy controls.
+ */
+export interface DataCollectionPolicy {
+    /**
+     * Whether data collection is currently enabled.
+     */
+    readonly isEnabled: boolean;
+    /**
+     * Enable telemetry data collection.
+     */
+    enable(): Promise<void>;
+    /**
+     * Disable telemetry data collection.
+     */
+    disable(): Promise<void>;
+    /**
+     * Subscribe to policy changes.
+     * @param callback Function called when policy changes.
+     * @returns Unsubscribe function.
+     */
+    subscribe(callback: (isEnabled: boolean) => void): () => void;
+}
+/**
+ * Options for creating a DataCollectionPolicy.
+ */
+export interface DataCollectionPolicyOptions {
+    /**
+     * Storage key for persisting the policy setting.
+     * Default: 'faro_enable_data_collection'
+     */
+    storageKey?: string;
+    /**
+     * Initial enabled state if no persisted value exists.
+     * Default: true
+     */
+    defaultEnabled?: boolean;
+}