eventlog-rn 0.3.1

package/README.md

@@ -0,0 +1,64 @@
+# eventlog-rn
+
+> Functional, type-safe event logging SDK for React Native
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![Bundle Size](https://img.shields.io/badge/Bundle-11.7KB-success.svg)](https://bundlephobia.com/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## What is this?
+
+# eventlog-rn
+
+Functional, type-safe event logging SDK for React Native.
+
+Optimized for **reliability**, **performance**, and **ease of use**.
+
+## Features
+
+- **Type-Safe**: Full TypeScript support with generics.
+- **Batched Uploads**: Efficiently queues events to minimize network requests.
+- **Offline Support**: Caches events when offline and syncs when back online.
+- **Session Tracking**: Automatic session management.
+- **Built-in UI**: Inspect logs on-device with the included Viewer component.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install eventlog-rn react-native-mmkv
+```
+
+### 2. Initialize
+
+```typescript
+import { eventLog } from 'eventlog-rn';
+
+// Initialize at app launch based on your config
+eventLog.init({
+  // ...
+});
+```
+Network logging enabled by default!
+
+// 2. Log events
+eventLog.screen('HomeScreen');
+eventLog.action('button_clicked', { buttonId: 'checkout' });
+
+// 3. Export for debugging
+const result = await eventLog.export({ mode: 'repro' });
+
+// 4. View logs (optional)
+import { EventLogViewer, EventLogErrorBoundary } from 'eventlog-rn';
+
+// Wrap app for error handling
+<EventLogErrorBoundary>
+  <App />
+  <EventLogViewer />
+</EventLogErrorBoundary>
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,206 @@
+export { EventLogViewer, EventLogViewerProps } from './viewer/index.mjs';
+import React, { Component, ReactNode, ErrorInfo } from 'react';
+
+/**
+ * Type definitions for eventlog-rn/core
+ * Strict, immutable types following functional programming principles
+ */
+/**
+ * Storage adapter interface (AsyncStorage-compatible)
+ */
+type StorageAdapter = Readonly<{
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+}>;
+/**
+ * Event categories
+ */
+type EventCategory = 'screen' | 'action' | 'network' | 'error' | 'log';
+/**
+ * Log levels
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Event context (attached to all events)
+ */
+type EventContext = Readonly<{
+    readonly user?: Readonly<Record<string, unknown>>;
+    readonly deviceInfo?: Readonly<Record<string, unknown>>;
+    readonly [key: string]: unknown;
+}>;
+/**
+ * Immutable event structure
+ */
+type Event = Readonly<{
+    readonly eventId: string;
+    readonly sessionId: string;
+    readonly seq: number;
+    readonly timestamp: number;
+    readonly timestampISO: string;
+    readonly timezone: string;
+    readonly category: EventCategory;
+    readonly payload: unknown;
+    readonly context: EventContext;
+}>;
+/**
+ * Session information
+ */
+type Session = Readonly<{
+    readonly sessionId: string;
+    readonly sessionStart: number;
+    readonly startType: 'cold' | 'warm';
+    readonly seq: number;
+    readonly lastActivityTime: number;
+}>;
+/**
+ * Feature configuration
+ */
+type FeatureConfig = Readonly<{
+    readonly network?: Readonly<{
+        readonly enabled?: boolean;
+        readonly interceptFetch?: boolean;
+        readonly interceptAxios?: boolean;
+        readonly logRequestBody?: boolean;
+        readonly logResponseBody?: boolean;
+        readonly maxBodySize?: number;
+        readonly redactHeaders?: ReadonlyArray<string>;
+    }>;
+    readonly globalErrors?: Readonly<{
+        readonly enabled?: boolean;
+    }>;
+}>;
+/**
+ * Tracker configuration
+ */
+type EventLogConfig = Readonly<{
+    readonly autoDetect?: boolean;
+    readonly maxEvents?: number;
+    readonly maxAgeDays?: number;
+    readonly sessionTimeoutMinutes?: number;
+    readonly batchWriteDelayMs?: number;
+    readonly sanitize?: (event: Event) => Event;
+    readonly features?: FeatureConfig;
+}>;
+/**
+ * Export options
+ */
+type ExportOptions = Readonly<{
+    readonly mode: 'repro' | 'full';
+}>;
+/**
+ * Network event payload
+ */
+type NetworkEventPayload = Readonly<{
+    readonly url: string;
+    readonly method: string;
+    readonly status?: number;
+    readonly duration?: number;
+    readonly error?: string;
+    readonly requestHeaders?: Readonly<Record<string, string>>;
+    readonly responseHeaders?: Readonly<Record<string, string>>;
+    readonly requestBody?: unknown;
+    readonly responseBody?: unknown;
+}>;
+/**
+ * Error event payload
+ */
+type ErrorEventPayload = Readonly<{
+    readonly message: string;
+    readonly stack?: string;
+    readonly isFatal?: boolean;
+    readonly context?: unknown;
+}>;
+/**
+ * Result type for operations that can fail
+ */
+type Result<T, E = Error> = Readonly<{
+    readonly ok: true;
+    readonly value: T;
+}> | Readonly<{
+    readonly ok: false;
+    readonly error: E;
+}>;
+/**
+ * Event query for filtering
+ */
+type EventQuery = Readonly<{
+    readonly category?: ReadonlyArray<EventCategory>;
+    readonly timeRange?: Readonly<{
+        readonly start: number;
+        readonly end: number;
+    }>;
+    readonly sessionId?: string;
+    readonly search?: string;
+    readonly limit?: number;
+}>;
+/**
+ * EventLog API
+ */
+type EventLog = Readonly<{
+    readonly init: (config?: Partial<EventLogConfig>) => Promise<Result<void>>;
+    readonly isReady: () => boolean;
+    readonly screen: (name: string, params?: unknown) => Result<void>;
+    readonly action: (name: string, data?: unknown) => Result<void>;
+    readonly log: (level: LogLevel, message: string, data?: unknown) => Result<void>;
+    readonly error: (error: unknown, context?: unknown) => Result<void>;
+    readonly setUser: (user: Readonly<Record<string, unknown>>) => void;
+    readonly setContext: (key: string, value: unknown) => void;
+    readonly setDeviceInfo: (info: Readonly<Record<string, unknown>>) => void;
+    readonly export: (options: ExportOptions) => Promise<Result<string>>;
+    readonly clear: () => Promise<Result<void>>;
+    readonly getEvents: () => Result<ReadonlyArray<Event>>;
+    readonly query: (query: EventQuery) => Result<ReadonlyArray<Event>>;
+    readonly network: (payload: NetworkEventPayload) => Result<void>;
+}>;
+
+/**
+ * Main EventLog API - Functional implementation with closures
+ */
+
+/**
+ * Create EventLog instance (factory function with closure)
+ */
+declare const createEventLog: (config?: EventLogConfig) => EventLog;
+
+declare const eventLog: Readonly<{
+    readonly init: (config?: Partial<EventLogConfig>) => Promise<Result<void>>;
+    readonly isReady: () => boolean;
+    readonly screen: (name: string, params?: unknown) => Result<void>;
+    readonly action: (name: string, data?: unknown) => Result<void>;
+    readonly log: (level: LogLevel, message: string, data?: unknown) => Result<void>;
+    readonly error: (error: unknown, context?: unknown) => Result<void>;
+    readonly setUser: (user: Readonly<Record<string, unknown>>) => void;
+    readonly setContext: (key: string, value: unknown) => void;
+    readonly setDeviceInfo: (info: Readonly<Record<string, unknown>>) => void;
+    readonly export: (options: ExportOptions) => Promise<Result<string>>;
+    readonly clear: () => Promise<Result<void>>;
+    readonly getEvents: () => Result<ReadonlyArray<Event>>;
+    readonly query: (query: EventQuery) => Result<ReadonlyArray<Event>>;
+    readonly network: (payload: NetworkEventPayload) => Result<void>;
+}>;
+
+type EventLogErrorBoundaryProps = {
+    children: ReactNode;
+    fallback?: ReactNode;
+    onError?: (error: Error, info: ErrorInfo) => void;
+};
+type State = {
+    hasError: boolean;
+    error: Error | null;
+};
+/**
+ * EventLog Error Boundary
+ *
+ * Catches React render errors in its child component tree.
+ * Automatically logs them to the EventLog.
+ */
+declare class EventLogErrorBoundary extends Component<EventLogErrorBoundaryProps, State> {
+    constructor(props: EventLogErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    resetError: () => void;
+    render(): string | number | bigint | boolean | React.JSX.Element | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | null | undefined;
+}
+
+export { type ErrorEventPayload, type Event, type EventCategory, type EventContext, type EventLog, type EventLogConfig, EventLogErrorBoundary, type EventQuery, type ExportOptions, type LogLevel, type NetworkEventPayload, type Result, type Session, type StorageAdapter, createEventLog, eventLog };

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+export { EventLogViewer, EventLogViewerProps } from './viewer/index.js';
+import React, { Component, ReactNode, ErrorInfo } from 'react';
+
+/**
+ * Type definitions for eventlog-rn/core
+ * Strict, immutable types following functional programming principles
+ */
+/**
+ * Storage adapter interface (AsyncStorage-compatible)
+ */
+type StorageAdapter = Readonly<{
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+}>;
+/**
+ * Event categories
+ */
+type EventCategory = 'screen' | 'action' | 'network' | 'error' | 'log';
+/**
+ * Log levels
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Event context (attached to all events)
+ */
+type EventContext = Readonly<{
+    readonly user?: Readonly<Record<string, unknown>>;
+    readonly deviceInfo?: Readonly<Record<string, unknown>>;
+    readonly [key: string]: unknown;
+}>;
+/**
+ * Immutable event structure
+ */
+type Event = Readonly<{
+    readonly eventId: string;
+    readonly sessionId: string;
+    readonly seq: number;
+    readonly timestamp: number;
+    readonly timestampISO: string;
+    readonly timezone: string;
+    readonly category: EventCategory;
+    readonly payload: unknown;
+    readonly context: EventContext;
+}>;
+/**
+ * Session information
+ */
+type Session = Readonly<{
+    readonly sessionId: string;
+    readonly sessionStart: number;
+    readonly startType: 'cold' | 'warm';
+    readonly seq: number;
+    readonly lastActivityTime: number;
+}>;
+/**
+ * Feature configuration
+ */
+type FeatureConfig = Readonly<{
+    readonly network?: Readonly<{
+        readonly enabled?: boolean;
+        readonly interceptFetch?: boolean;
+        readonly interceptAxios?: boolean;
+        readonly logRequestBody?: boolean;
+        readonly logResponseBody?: boolean;
+        readonly maxBodySize?: number;
+        readonly redactHeaders?: ReadonlyArray<string>;
+    }>;
+    readonly globalErrors?: Readonly<{
+        readonly enabled?: boolean;
+    }>;
+}>;
+/**
+ * Tracker configuration
+ */
+type EventLogConfig = Readonly<{
+    readonly autoDetect?: boolean;
+    readonly maxEvents?: number;
+    readonly maxAgeDays?: number;
+    readonly sessionTimeoutMinutes?: number;
+    readonly batchWriteDelayMs?: number;
+    readonly sanitize?: (event: Event) => Event;
+    readonly features?: FeatureConfig;
+}>;
+/**
+ * Export options
+ */
+type ExportOptions = Readonly<{
+    readonly mode: 'repro' | 'full';
+}>;
+/**
+ * Network event payload
+ */
+type NetworkEventPayload = Readonly<{
+    readonly url: string;
+    readonly method: string;
+    readonly status?: number;
+    readonly duration?: number;
+    readonly error?: string;
+    readonly requestHeaders?: Readonly<Record<string, string>>;
+    readonly responseHeaders?: Readonly<Record<string, string>>;
+    readonly requestBody?: unknown;
+    readonly responseBody?: unknown;
+}>;
+/**
+ * Error event payload
+ */
+type ErrorEventPayload = Readonly<{
+    readonly message: string;
+    readonly stack?: string;
+    readonly isFatal?: boolean;
+    readonly context?: unknown;
+}>;
+/**
+ * Result type for operations that can fail
+ */
+type Result<T, E = Error> = Readonly<{
+    readonly ok: true;
+    readonly value: T;
+}> | Readonly<{
+    readonly ok: false;
+    readonly error: E;
+}>;
+/**
+ * Event query for filtering
+ */
+type EventQuery = Readonly<{
+    readonly category?: ReadonlyArray<EventCategory>;
+    readonly timeRange?: Readonly<{
+        readonly start: number;
+        readonly end: number;
+    }>;
+    readonly sessionId?: string;
+    readonly search?: string;
+    readonly limit?: number;
+}>;
+/**
+ * EventLog API
+ */
+type EventLog = Readonly<{
+    readonly init: (config?: Partial<EventLogConfig>) => Promise<Result<void>>;
+    readonly isReady: () => boolean;
+    readonly screen: (name: string, params?: unknown) => Result<void>;
+    readonly action: (name: string, data?: unknown) => Result<void>;
+    readonly log: (level: LogLevel, message: string, data?: unknown) => Result<void>;
+    readonly error: (error: unknown, context?: unknown) => Result<void>;
+    readonly setUser: (user: Readonly<Record<string, unknown>>) => void;
+    readonly setContext: (key: string, value: unknown) => void;
+    readonly setDeviceInfo: (info: Readonly<Record<string, unknown>>) => void;
+    readonly export: (options: ExportOptions) => Promise<Result<string>>;
+    readonly clear: () => Promise<Result<void>>;
+    readonly getEvents: () => Result<ReadonlyArray<Event>>;
+    readonly query: (query: EventQuery) => Result<ReadonlyArray<Event>>;
+    readonly network: (payload: NetworkEventPayload) => Result<void>;
+}>;
+
+/**
+ * Main EventLog API - Functional implementation with closures
+ */
+
+/**
+ * Create EventLog instance (factory function with closure)
+ */
+declare const createEventLog: (config?: EventLogConfig) => EventLog;
+
+declare const eventLog: Readonly<{
+    readonly init: (config?: Partial<EventLogConfig>) => Promise<Result<void>>;
+    readonly isReady: () => boolean;
+    readonly screen: (name: string, params?: unknown) => Result<void>;
+    readonly action: (name: string, data?: unknown) => Result<void>;
+    readonly log: (level: LogLevel, message: string, data?: unknown) => Result<void>;
+    readonly error: (error: unknown, context?: unknown) => Result<void>;
+    readonly setUser: (user: Readonly<Record<string, unknown>>) => void;
+    readonly setContext: (key: string, value: unknown) => void;
+    readonly setDeviceInfo: (info: Readonly<Record<string, unknown>>) => void;
+    readonly export: (options: ExportOptions) => Promise<Result<string>>;
+    readonly clear: () => Promise<Result<void>>;
+    readonly getEvents: () => Result<ReadonlyArray<Event>>;
+    readonly query: (query: EventQuery) => Result<ReadonlyArray<Event>>;
+    readonly network: (payload: NetworkEventPayload) => Result<void>;
+}>;
+
+type EventLogErrorBoundaryProps = {
+    children: ReactNode;
+    fallback?: ReactNode;
+    onError?: (error: Error, info: ErrorInfo) => void;
+};
+type State = {
+    hasError: boolean;
+    error: Error | null;
+};
+/**
+ * EventLog Error Boundary
+ *
+ * Catches React render errors in its child component tree.
+ * Automatically logs them to the EventLog.
+ */
+declare class EventLogErrorBoundary extends Component<EventLogErrorBoundaryProps, State> {
+    constructor(props: EventLogErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    resetError: () => void;
+    render(): string | number | bigint | boolean | React.JSX.Element | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | null | undefined;
+}
+
+export { type ErrorEventPayload, type Event, type EventCategory, type EventContext, type EventLog, type EventLogConfig, EventLogErrorBoundary, type EventQuery, type ExportOptions, type LogLevel, type NetworkEventPayload, type Result, type Session, type StorageAdapter, createEventLog, eventLog };