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

package/src/testUtils/setupTests.ts

@@ -0,0 +1,199 @@
+/**
+ * Jest setup file for React Native tests
+ * Mocks third-party React Native dependencies
+ */
+
+// Mock react-native-device-info
+jest.mock('react-native-device-info', () => {
+  const mockDeviceInfo = {
+    getBrand: jest.fn(() => 'Apple'),
+    getDeviceId: jest.fn(() => 'iPhone14,2'),
+    getModel: jest.fn(() => 'iPhone 13 Pro'),
+    getSystemName: jest.fn(() => 'iOS'),
+    getSystemVersion: jest.fn(() => '16.0'),
+    getVersion: jest.fn(() => '1.0.0'),
+    isTablet: jest.fn(() => false),
+    isEmulatorSync: jest.fn(() => false),
+    getTotalMemorySync: jest.fn(() => 6442450944), // 6GB in bytes
+    getUsedMemorySync: jest.fn(() => 2147483648), // 2GB in bytes
+    getBatteryLevel: jest.fn(() => Promise.resolve(0.75)),
+    getCarrier: jest.fn(() => Promise.resolve('T-Mobile')),
+    isPowerSaveMode: jest.fn(() => Promise.resolve(false)),
+    isBatteryCharging: jest.fn(() => Promise.resolve(false)),
+  };
+  return {
+    __esModule: true,
+    default: mockDeviceInfo,
+    ...mockDeviceInfo,
+  };
+});
+
+// Mock @react-native-async-storage/async-storage
+// Using a global storage object that can be accessed by tests
+(global as any).mockAsyncStorage = {};
+
+const mockAsyncStorageImpl = {
+  getItem: jest.fn((key: string) => {
+    const storage = (global as any).mockAsyncStorage;
+    return Promise.resolve(storage[key] ?? null);
+  }),
+  setItem: jest.fn((key: string, value: string) => {
+    const storage = (global as any).mockAsyncStorage;
+    storage[key] = value;
+    return Promise.resolve();
+  }),
+  removeItem: jest.fn((key: string) => {
+    const storage = (global as any).mockAsyncStorage;
+    delete storage[key];
+    return Promise.resolve();
+  }),
+  clear: jest.fn(() => {
+    (global as any).mockAsyncStorage = {};
+    return Promise.resolve();
+  }),
+  getAllKeys: jest.fn(() => {
+    const storage = (global as any).mockAsyncStorage;
+    return Promise.resolve(Object.keys(storage));
+  }),
+  multiGet: jest.fn((keys: string[]) => {
+    const storage = (global as any).mockAsyncStorage;
+    return Promise.resolve(keys.map((key) => [key, storage[key] ?? null]));
+  }),
+  multiSet: jest.fn((keyValuePairs: Array<[string, string]>) => {
+    const storage = (global as any).mockAsyncStorage;
+    keyValuePairs.forEach(([key, value]) => {
+      storage[key] = value;
+    });
+    return Promise.resolve();
+  }),
+  multiRemove: jest.fn((keys: string[]) => {
+    const storage = (global as any).mockAsyncStorage;
+    keys.forEach((key) => delete storage[key]);
+    return Promise.resolve();
+  }),
+};
+
+jest.mock('@react-native-async-storage/async-storage', () => ({
+  __esModule: true,
+  default: mockAsyncStorageImpl,
+}));
+
+// Ensure Platform.Version is properly mocked
+// The react-native preset mocks Platform, but we need to ensure Version is accessible
+jest.mock(
+  'react-native/Libraries/Utilities/Platform',
+  () => ({
+    OS: 'ios',
+    Version: '16.0',
+    select: jest.fn((obj) => obj.ios || obj.default),
+  }),
+  { virtual: true }
+);
+
+// Mock fetch API globals for HTTP instrumentation tests
+if (typeof global.Response === 'undefined') {
+  global.Response = class Response {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    body: any;
+
+    constructor(body?: BodyInit | null, init?: ResponseInit) {
+      this.body = body;
+      this.status = init?.status ?? 200;
+      this.statusText = init?.statusText ?? 'OK';
+      this.ok = this.status >= 200 && this.status < 300;
+    }
+  } as any;
+}
+
+if (typeof global.Request === 'undefined') {
+  global.Request = class Request {
+    url: string;
+    method: string;
+
+    constructor(input: RequestInfo | URL, init?: RequestInit) {
+      if (typeof input === 'string') {
+        this.url = input;
+        this.method = init?.method ?? 'GET';
+      } else if (input instanceof URL) {
+        this.url = input.href;
+        this.method = init?.method ?? 'GET';
+      } else {
+        // input is a Request object
+        const req = input as Request;
+        this.url = req.url;
+        this.method = init?.method ?? req.method ?? 'GET';
+      }
+    }
+  } as any;
+}
+
+if (typeof global.URL === 'undefined') {
+  global.URL = class URL {
+    href: string;
+
+    constructor(url: string) {
+      this.href = url;
+    }
+  } as any;
+}
+
+/**
+ * Minimal XMLHttpRequest for Jest (Node has no XHR). Patches in XHRInstrumentation
+ * tests attach to this prototype; send() completes asynchronously like a real request.
+ */
+if (typeof global.XMLHttpRequest === 'undefined') {
+  class MockXMLHttpRequest {
+    static readonly DONE = 4;
+
+    readyState = 0;
+    status = 200;
+    statusText = 'OK';
+    onreadystatechange: ((this: XMLHttpRequest, ev: Event) => unknown) | null = null;
+
+    private readonly listeners = new Map<string, Set<EventListener>>();
+
+    open(_method: string, _url: string | URL): void {
+      // Real open is replaced by instrumentation; baseline is a no-op.
+    }
+
+    send(_body?: Document | XMLHttpRequestBodyInit | null): void {
+      // Synchronous completion matches test doubles and ensures Faro pushEvent runs in the same turn as send().
+      this.readyState = MockXMLHttpRequest.DONE;
+      const ev = { type: 'readystatechange' } as Event;
+      if (this.onreadystatechange) {
+        this.onreadystatechange.call(this as unknown as XMLHttpRequest, ev);
+      }
+      const load = this.listeners.get('load');
+      if (load) {
+        load.forEach((fn) => {
+          fn.call(this as unknown as XMLHttpRequest, ev);
+        });
+      }
+    }
+
+    setRequestHeader(_name: string, _value: string): void {}
+
+    getResponseHeader(_name: string): string | null {
+      return null;
+    }
+
+    addEventListener(type: string, listener: EventListener): void {
+      let set = this.listeners.get(type);
+      if (!set) {
+        set = new Set();
+        this.listeners.set(type, set);
+      }
+      set.add(listener);
+    }
+
+    removeEventListener(type: string, listener: EventListener): void {
+      this.listeners.get(type)?.delete(listener);
+    }
+
+    abort(): void {}
+  }
+
+  global.XMLHttpRequest = MockXMLHttpRequest as unknown as typeof XMLHttpRequest;
+}

package/src/transports/batchExecutor.ts

@@ -0,0 +1,106 @@
+import { AppState } from 'react-native';
+import type { NativeEventSubscription } from 'react-native';
+
+import type { TransportItem } from '@grafana/faro-core';
+
+export type SendFn = (items: TransportItem[]) => void;
+
+export interface BatchExecutorOptions {
+  itemLimit?: number;
+  sendTimeout?: number;
+  paused?: boolean;
+}
+
+const DEFAULT_SEND_TIMEOUT_MS = 250;
+const DEFAULT_BATCH_ITEM_LIMIT = 50;
+
+export class RNBatchExecutor {
+  private readonly itemLimit: number;
+  private readonly sendTimeout: number;
+
+  private signalBuffer: TransportItem[] = [];
+  private sendFn: SendFn;
+  private paused: boolean;
+  private flushInterval?: ReturnType<typeof setInterval>;
+  private appStateSubscription?: NativeEventSubscription;
+
+  constructor(sendFn: SendFn, options?: BatchExecutorOptions) {
+    this.itemLimit = options?.itemLimit ?? DEFAULT_BATCH_ITEM_LIMIT;
+    this.sendTimeout = options?.sendTimeout ?? DEFAULT_SEND_TIMEOUT_MS;
+    this.paused = options?.paused || false;
+    this.sendFn = sendFn;
+
+    if (!this.paused) {
+      this.start();
+    }
+
+    // Send batched/buffered data when app goes to background
+    // This is the React Native equivalent of document.visibilitychange
+    this.appStateSubscription = AppState.addEventListener('change', (nextAppState) => {
+      if (nextAppState === 'background' || nextAppState === 'inactive') {
+        this.flush();
+      }
+    });
+  }
+
+  addItem(item: TransportItem): void {
+    if (this.paused) {
+      return;
+    }
+
+    this.signalBuffer.push(item);
+
+    if (this.signalBuffer.length >= this.itemLimit) {
+      this.flush();
+    }
+  }
+
+  start(): void {
+    this.paused = false;
+    if (this.sendTimeout > 0) {
+      // Use global setInterval (not window.setInterval)
+      this.flushInterval = setInterval(() => this.flush(), this.sendTimeout);
+    }
+  }
+
+  pause(): void {
+    this.paused = true;
+    if (this.flushInterval) {
+      clearInterval(this.flushInterval);
+    }
+  }
+
+  cleanup(): void {
+    this.pause();
+    if (this.appStateSubscription) {
+      this.appStateSubscription.remove();
+    }
+  }
+
+  groupItems(items: TransportItem[]): TransportItem[][] {
+    const itemMap = new Map<string, TransportItem[]>();
+    items.forEach((item) => {
+      const metaKey = JSON.stringify(item.meta);
+
+      let currentItems = itemMap.get(metaKey);
+      if (currentItems === undefined) {
+        currentItems = [item];
+      } else {
+        currentItems = [...currentItems, item];
+      }
+
+      itemMap.set(metaKey, currentItems);
+    });
+    return Array.from(itemMap.values());
+  }
+
+  private flush() {
+    if (this.paused || this.signalBuffer.length === 0) {
+      return;
+    }
+
+    const itemGroups = this.groupItems(this.signalBuffer);
+    itemGroups.forEach(this.sendFn);
+    this.signalBuffer = [];
+  }
+}

package/src/transports/console/index.ts

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

package/src/transports/console/transport.test.ts

@@ -0,0 +1,185 @@
+import { getTransportBody, LogEvent, LogLevel, TransportItem, TransportItemType } from '@grafana/faro-core';
+import { mockInternalLogger } from '@grafana/faro-test-utils';
+
+import { ConsoleTransport } from './transport';
+
+const mockSessionId = '123';
+
+const logItem: TransportItem<LogEvent> = {
+  type: TransportItemType.LOG,
+  payload: {
+    context: {},
+    level: LogLevel.INFO,
+    message: 'test message',
+    timestamp: new Date().toISOString(),
+  },
+  meta: {
+    session: { id: mockSessionId },
+  },
+};
+
+describe('ConsoleTransport', () => {
+  let transport: ConsoleTransport;
+  let consoleDebugSpy: jest.SpyInstance;
+  let consoleInfoSpy: jest.SpyInstance;
+  let consoleWarnSpy: jest.SpyInstance;
+  let consoleErrorSpy: jest.SpyInstance;
+  let consoleLogSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    // Spies will be created per-test after transport is instantiated
+  });
+
+  afterEach(() => {
+    consoleDebugSpy?.mockRestore();
+    consoleInfoSpy?.mockRestore();
+    consoleWarnSpy?.mockRestore();
+    consoleErrorSpy?.mockRestore();
+    consoleLogSpy?.mockRestore();
+  });
+
+  it('should have correct name and version', () => {
+    const transport = new ConsoleTransport();
+    expect(transport.name).toBe('@grafana/faro-react-native:transport-console');
+    expect(typeof transport.version).toBe('string');
+  });
+
+  it('should output to console.debug by default', () => {
+    transport = new ConsoleTransport();
+    transport.internalLogger = mockInternalLogger;
+    consoleDebugSpy = jest.spyOn(transport.unpatchedConsole, 'debug').mockImplementation();
+
+    transport.send(logItem);
+
+    expect(consoleDebugSpy).toHaveBeenCalledWith('New event', getTransportBody([logItem]));
+  });
+
+  it('should output to console.info when level is INFO', () => {
+    transport = new ConsoleTransport({ level: LogLevel.INFO });
+    transport.internalLogger = mockInternalLogger;
+    consoleInfoSpy = jest.spyOn(transport.unpatchedConsole, 'info').mockImplementation();
+
+    transport.send(logItem);
+
+    expect(consoleInfoSpy).toHaveBeenCalledWith('New event', getTransportBody([logItem]));
+  });
+
+  it('should output to console.warn when level is WARN', () => {
+    transport = new ConsoleTransport({ level: LogLevel.WARN });
+    transport.internalLogger = mockInternalLogger;
+    consoleWarnSpy = jest.spyOn(transport.unpatchedConsole, 'warn').mockImplementation();
+
+    transport.send(logItem);
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith('New event', getTransportBody([logItem]));
+  });
+
+  it('should output to console.error when level is ERROR', () => {
+    transport = new ConsoleTransport({ level: LogLevel.ERROR });
+    transport.internalLogger = mockInternalLogger;
+    consoleErrorSpy = jest.spyOn(transport.unpatchedConsole, 'error').mockImplementation();
+
+    transport.send(logItem);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith('New event', getTransportBody([logItem]));
+  });
+
+  it('should output to console.log when level is LOG', () => {
+    transport = new ConsoleTransport({ level: LogLevel.LOG });
+    transport.internalLogger = mockInternalLogger;
+    consoleLogSpy = jest.spyOn(transport.unpatchedConsole, 'log').mockImplementation();
+
+    transport.send(logItem);
+
+    expect(consoleLogSpy).toHaveBeenCalledWith('New event', getTransportBody([logItem]));
+  });
+
+  it('should handle different transport item types', () => {
+    transport = new ConsoleTransport();
+    transport.internalLogger = mockInternalLogger;
+    consoleDebugSpy = jest.spyOn(transport.unpatchedConsole, 'debug').mockImplementation();
+
+    const exceptionItem: TransportItem = {
+      type: TransportItemType.EXCEPTION,
+      payload: {
+        type: 'Error',
+        value: 'Test error',
+        stacktrace: {
+          frames: [],
+        },
+        timestamp: new Date().toISOString(),
+      },
+      meta: {
+        session: { id: mockSessionId },
+      },
+    };
+
+    transport.send(exceptionItem);
+
+    expect(consoleDebugSpy).toHaveBeenCalledWith('New event', getTransportBody([exceptionItem]));
+  });
+
+  it('should format output with session metadata', () => {
+    transport = new ConsoleTransport();
+    transport.internalLogger = mockInternalLogger;
+    consoleDebugSpy = jest.spyOn(transport.unpatchedConsole, 'debug').mockImplementation();
+
+    const itemWithMetadata: TransportItem<LogEvent> = {
+      ...logItem,
+      meta: {
+        session: { id: 'session-123' },
+        user: { id: 'user-456' },
+      },
+    };
+
+    transport.send(itemWithMetadata);
+
+    const expectedBody = getTransportBody([itemWithMetadata]);
+    expect(consoleDebugSpy).toHaveBeenCalledWith('New event', expectedBody);
+    expect(expectedBody.meta).toEqual({
+      session: { id: 'session-123' },
+      user: { id: 'user-456' },
+    });
+  });
+
+  it('isBatched returns false', () => {
+    const transport = new ConsoleTransport();
+    expect(transport.isBatched()).toBe(false);
+  });
+
+  it('should handle multiple sends', () => {
+    transport = new ConsoleTransport();
+    transport.internalLogger = mockInternalLogger;
+    consoleDebugSpy = jest.spyOn(transport.unpatchedConsole, 'debug').mockImplementation();
+
+    transport.send(logItem);
+    transport.send(logItem);
+    transport.send(logItem);
+
+    expect(consoleDebugSpy).toHaveBeenCalledTimes(3);
+  });
+
+  it('should properly format measurement items', () => {
+    transport = new ConsoleTransport({ level: LogLevel.INFO });
+    transport.internalLogger = mockInternalLogger;
+    consoleInfoSpy = jest.spyOn(transport.unpatchedConsole, 'info').mockImplementation();
+
+    const measurementItem: TransportItem = {
+      type: TransportItemType.MEASUREMENT,
+      payload: {
+        type: 'custom_metric',
+        values: {
+          value: 42,
+        },
+        timestamp: new Date().toISOString(),
+      },
+      meta: {
+        session: { id: mockSessionId },
+      },
+    };
+
+    transport.send(measurementItem);
+
+    expect(consoleInfoSpy).toHaveBeenCalledWith('New event', getTransportBody([measurementItem]));
+  });
+});

package/src/transports/console/transport.ts

@@ -0,0 +1,17 @@
+import { BaseTransport, getTransportBody, LogLevel, VERSION } from '@grafana/faro-core';
+import type { TransportItem } from '@grafana/faro-core';
+
+import type { ConsoleTransportOptions } from './types';
+
+export class ConsoleTransport extends BaseTransport {
+  readonly name = '@grafana/faro-react-native:transport-console';
+  readonly version = VERSION;
+
+  constructor(private options: ConsoleTransportOptions = {}) {
+    super();
+  }
+
+  send(item: TransportItem): void {
+    return this.unpatchedConsole[this.options.level ?? LogLevel.DEBUG]('New event', getTransportBody([item]));
+  }
+}

package/src/transports/console/types.ts

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

package/src/transports/fetch/index.ts

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