mixpanel-react-native 3.0.9 → 3.1.0

package/claude/architecture/system-design.md

@@ -0,0 +1,339 @@
+# System Design: mixpanel-react-native
+
+## Architectural Overview
+
+The Mixpanel React Native library implements a **dual-path architecture** with sophisticated queue management, persistent state, and graceful fallback mechanisms. The system prioritizes data reliability over performance, ensuring no analytics events are lost.
+
+## 🏗️ High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Application Layer                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
+│  │   Mixpanel  │  │   People    │  │    MixpanelGroup        │  │
+│  │   (Events)  │  │ (Profiles)  │  │   (Group Analytics)     │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │ Public API (index.js)
+┌─────────────────────┴───────────────────────────────────────────┐
+│                   Implementation Router                        │
+│                                                                 │
+│  ┌─────────────────────┐      ┌─────────────────────────────┐   │
+│  │   Native Mode       │      │    JavaScript Mode          │   │
+│  │  (iOS Swift +       │ OR   │   (Pure JS Implementation)  │   │
+│  │  Android Java)      │      │                             │   │
+│  └─────────────────────┘      └─────────────────────────────┘   │
+└─────────────────────────────────┬───────────────────────────────┘
+                                  │
+┌─────────────────────────────────┴───────────────────────────────┐
+│                    Shared Infrastructure                       │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
+│  │ Queue Mgmt  │  │ Persistence │  │       Network           │  │
+│  │ (In-Memory  │  │  (Storage   │  │   (HTTP + Retry)        │  │
+│  │ + Durable)  │  │ Abstraction)│  │                         │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 🔄 Data Flow Architecture
+
+### 1. Event Tracking Flow
+
+```
+User Code
+    │ mixpanel.track("Event", {props})
+    │
+    ▼
+┌─────────────────────────────────────────────┐
+│           Input Validation Layer            │
+│  • Parameter validation (StringHelper)     │
+│  • Type checking (ObjectHelper)            │
+│  • Error throwing with helpful messages    │
+└─────────────────┬───────────────────────────┘
+                  │ ✓ Valid input
+                  ▼
+┌─────────────────────────────────────────────┐
+│         Implementation Router               │
+│  if (useNative && MixpanelReactNative) {   │
+│    → Native Implementation                 │
+│  } else {                                  │
+│    → JavaScript Implementation             │
+│  }                                         │
+└─────────────────┬───────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────┐
+│            Event Enrichment                 │
+│  • Add metadata (device info, lib version) │
+│  • Merge super properties                  │
+│  • Add identity fields (distinct_id, etc)  │
+│  • Calculate event timing if applicable    │
+│  • Add session metadata                    │
+└─────────────────┬───────────────────────────┘
+                  │ Enriched event object
+                  ▼
+┌─────────────────────────────────────────────┐
+│               Opt-out Check                 │
+│  if (persistent.getOptedOut(token)) {      │
+│    → Log skip message and return           │
+│  }                                         │
+└─────────────────┬───────────────────────────┘
+                  │ ✓ User opted in
+                  ▼
+┌─────────────────────────────────────────────┐
+│            Queue Management                 │
+│  • Add to in-memory queue                  │
+│  • Persist to storage (AsyncStorage)       │
+│  • Trigger batch processing if needed      │
+└─────────────────┬───────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────┐
+│             Batch Processing                │
+│  • Collect events in batches (default: 50) │
+│  • Process every 10s (JS) or 60s (native) │
+│  • Handle network requests with retries    │
+└─────────────────┬───────────────────────────┘
+                  │ HTTP POST to Mixpanel API
+                  ▼
+┌─────────────────────────────────────────────┐
+│              Mixpanel Servers               │
+└─────────────────────────────────────────────┘
+```
+
+### 2. Identity Management Flow
+
+```
+User Action: mixpanel.identify("user123")
+    │
+    ▼
+┌─────────────────────────────────────────────┐
+│            Validation Layer                 │
+│  StringHelper.isValid(distinctId)          │
+└─────────────────┬───────────────────────────┘
+                  │ ✓ Valid string
+                  ▼
+┌─────────────────────────────────────────────┐
+│         Persistence Layer Update            │
+│  • Update in-memory identity cache          │
+│  • Persist to AsyncStorage                  │
+│  • Set userId (for People Analytics)       │
+└─────────────────┬───────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────┐
+│          Queue Identity Update              │
+│  • Update existing USER queue records      │
+│  • Ensure consistent identity fields       │
+│  • Minimize object copying (performance)   │
+└─────────────────────────────────────────────┘
+```
+
+## 🏛️ System Layers
+
+### Layer 1: Public API (index.js)
+**Responsibility**: Type-safe interface with comprehensive validation
+
+```javascript
+// Clean, typed interface with validation
+export class Mixpanel {
+  track(eventName, properties) {
+    if (!StringHelper.isValid(eventName)) {
+      StringHelper.raiseError(PARAMS.EVENT_NAME);
+    }
+    // Route to implementation...
+  }
+}
+```
+
+**Key Characteristics**:
+- Input validation with helpful error messages
+- Implementation routing (native vs JS)
+- Promise-based API for async operations
+- TypeScript definitions for developer experience
+
+### Layer 2: Implementation Layer
+**Responsibility**: Platform-specific optimization
+
+#### Native Path (iOS Swift + Android Java)
+- Direct integration with official Mixpanel SDKs
+- Platform-optimized performance
+- Native queue management (60s flush interval)
+- iOS: Background flushing support
+
+#### JavaScript Path (mixpanel-main.js)
+- Pure JavaScript implementation
+- Expo and React Native Web compatibility
+- Aggressive flushing (10s interval)
+- Comprehensive retry logic
+
+### Layer 3: Core Processing (mixpanel-core.js)
+**Responsibility**: Shared business logic
+
+```javascript
+export const MixpanelCore = (storage) => {
+  // Queue processing with batching
+  const processQueue = async (token, type) => {
+    const batch = queue.slice(0, batchSize);
+    try {
+      await MixpanelNetwork.sendRequest({...});
+      // Remove successful items
+    } catch (error) {
+      handleBatchError(token, error, type, processBatch);
+    }
+  };
+};
+```
+
+**Key Features**:
+- Event queue management with batching
+- Automatic retry with exponential backoff
+- Corrupt data detection and removal
+- Session metadata injection
+
+### Layer 4: Persistence Layer (mixpanel-persistent.js)
+**Responsibility**: State management across app sessions
+
+```javascript
+export class MixpanelPersistent {
+  // Token-scoped state management
+  constructor(storageAdapter) {
+    this._identity = {};      // distinctId, deviceId, userId per token
+    this._superProperties = {}; // Global event properties per token
+    this._timeEvents = {};     // Event timing per token
+    this._optedOut = {};       // Opt-out status per token
+  }
+}
+```
+
+**Storage Strategy**:
+- Token-scoped keys: `MIXPANEL_{token}_{type}_{field}`
+- Lazy loading on first access
+- Write-through caching (memory + storage)
+- Graceful failure with in-memory fallback
+
+### Layer 5: Infrastructure Layer
+
+#### Queue Management (mixpanel-queue.js)
+```javascript
+export const MixpanelQueueManager = (() => {
+  let _queues = {}; // In-memory queues per token
+  
+  const enqueue = async (token, type, data) => {
+    _queues[token][type].push(data);
+    await updateQueueInStorage(token, type); // Persist immediately
+  };
+})();
+```
+
+**Queue Types**:
+- `EVENTS`: `/track/` - Analytics events
+- `USER`: `/engage/` - People profile updates  
+- `GROUPS`: `/groups/` - Group analytics updates
+
+#### Network Layer (mixpanel-network.js)
+```javascript
+export const MixpanelNetwork = (() => {
+  const sendRequest = async ({...params, retryCount = 0}) => {
+    try {
+      const response = await fetch(url, {...});
+      // Handle response...
+    } catch (error) {
+      if (retryCount < maxRetries) {
+        const backoff = Math.min(2 ** retryCount * 2000, 60000);
+        await new Promise(resolve => setTimeout(resolve, backoff));
+        return sendRequest({...params, retryCount: retryCount + 1});
+      }
+    }
+  };
+})();
+```
+
+**Retry Strategy**:
+- Exponential backoff: 2s, 4s, 8s, 16s, 32s, 60s (max)
+- Max 5 retries before giving up
+- 400 errors bypass retry (corrupted data)
+
+#### Storage Abstraction (mixpanel-storage.js)
+```javascript
+export class AsyncStorageAdapter {
+  constructor(storage) {
+    // Try AsyncStorage, fall back to in-memory
+    if (!storage) {
+      try {
+        this.storage = require("@react-native-async-storage/async-storage");
+      } catch {
+        this.storage = new InMemoryStorage();
+      }
+    }
+  }
+}
+```
+
+## 🔧 Configuration Management
+
+### Token-Scoped Configuration (mixpanel-config.js)
+```javascript
+export class MixpanelConfig {
+  static getInstance() { /* Singleton */ }
+  
+  // All configuration is per-token
+  setFlushBatchSize(token, batchSize) {
+    this._config[token] = {...this._config[token], batchSize};
+  }
+}
+```
+
+**Configuration Hierarchy**:
+1. User-provided values (highest priority)
+2. Default constants from mixpanel-constants.js
+3. Fallback values in getters
+
+## 🎯 Design Decisions & Trade-offs
+
+### 1. Reliability Over Performance
+**Decision**: Persist every event immediately to storage
+**Trade-off**: Storage I/O overhead vs. zero data loss
+**Justification**: Analytics data is business-critical
+
+### 2. Token-Based Multi-Tenancy
+**Decision**: Support multiple Mixpanel projects per app
+**Trade-off**: Memory overhead vs. flexibility
+**Justification**: Enterprise customers need project isolation
+
+### 3. Dual Implementation Strategy
+**Decision**: Maintain both native and JS implementations
+**Trade-off**: Code duplication vs. platform compatibility
+**Justification**: Expo support essential for adoption
+
+### 4. Aggressive Error Handling
+**Decision**: Validate all inputs, handle all errors
+**Trade-off**: Code verbosity vs. developer experience
+**Justification**: SDK failures should never crash apps
+
+### 5. Queue-Based Architecture
+**Decision**: Async event processing with batching
+**Trade-off**: Complexity vs. performance and reliability
+**Justification**: Network efficiency and offline support
+
+## 🚀 Performance Characteristics
+
+### Memory Usage
+- In-memory queues per token/type
+- LRU-style identity caching
+- Minimal object allocation during normal operation
+
+### Network Efficiency
+- Batched requests (50 events default)
+- Compression support (gzip)
+- Intelligent retry with backoff
+
+### Storage I/O
+- Write-through cache for all persistent data
+- JSON serialization for complex objects
+- Graceful fallback to in-memory storage
+
+### CPU Usage
+- Lazy initialization of expensive operations
+- Efficient queue processing with splice operations
+- Minimal validation overhead with helper classes

package/claude/codebase-map.md

@@ -0,0 +1,134 @@
+# Codebase Map: mixpanel-react-native
+
+## Executive Summary
+
+This is a React Native library implementing Mixpanel analytics with a **dual architecture strategy**: native iOS/Android modules for performance plus pure JavaScript fallback for Expo/Web compatibility. The codebase demonstrates sophisticated cross-platform patterns with token-based multi-instance support.
+
+## 🎯 Entry Points
+
+### Primary Library Interface
+- `index.js` - Main export exposing Mixpanel, People, and MixpanelGroup classes
+- `index.d.ts` - TypeScript definitions with comprehensive type coverage
+- `package.json` - Library metadata, dependencies (AsyncStorage, uuid, expo-crypto)
+
+### Configuration
+- `react-native.config.js` - React Native autolinking configuration for native modules
+- `MixpanelReactNative.podspec` - iOS CocoaPods specification
+
+## 🏗️ Core Architecture Components
+
+### Native Implementation (Performance Path)
+```
+ios/
+├── MixpanelReactNative.swift          # iOS bridge using Mixpanel Swift SDK
+├── MixpanelReactNative.m              # Objective-C bridge file
+├── AutomaticProperties.swift          # Device property collection
+├── MixpanelTypeHandler.swift          # Type conversion utilities
+└── Constants.swift                    # iOS-specific constants
+
+android/src/main/java/com/mixpanel/reactnative/
+├── MixpanelReactNativeModule.java     # Android bridge using Mixpanel Android SDK
+├── MixpanelReactNativePackage.java    # React Native package registration
+├── AutomaticProperties.java          # Device property collection
+└── ReactNativeHelper.java            # Utility functions
+```
+
+### JavaScript Implementation (Compatibility Path)
+```
+javascript/
+├── mixpanel-main.js                   # JS mode entry point - full API implementation
+├── mixpanel-core.js                   # Core tracking logic shared between modes
+├── mixpanel-queue.js                  # Event queue management with auto-flush
+├── mixpanel-network.js                # HTTP client with retry logic
+├── mixpanel-storage.js                # AsyncStorage abstraction layer
+├── mixpanel-persistent.js             # State persistence management
+├── mixpanel-config.js                 # Configuration management
+├── mixpanel-logger.js                 # Centralized logging system
+├── mixpanel-constants.js              # Shared constants and enums
+└── mixpanel-utils.js                  # Utility functions
+```
+
+## 🧪 Testing Infrastructure
+
+### Test Organization
+```
+__tests__/
+├── jest_setup.js                      # Test environment configuration
+├── core.test.js                       # Core functionality tests
+├── index.test.js                      # Main API tests
+├── main.test.js                       # JavaScript implementation tests
+├── network.test.js                    # HTTP client tests
+└── queue.test.js                      # Queue management tests
+
+__mocks__/
+└── @react-native-async-storage/       # AsyncStorage mock for testing
+    └── async-storage.js
+```
+
+### Test Patterns
+- **Comprehensive mocking**: All external dependencies (AsyncStorage, React Native modules)
+- **Jest configuration**: Custom setup with React Native preset
+- **Module isolation**: Each core component tested independently
+
+## 📱 Sample Applications
+
+### Development/Testing Apps
+```
+Samples/
+├── SimpleMixpanel/                     # Basic integration example (TypeScript)
+├── MixpanelDemo/                      # Full-featured demo app
+├── ContextAPIMixpanel/                # React Context API integration
+└── MixpanelExpo/                      # Expo-compatible example
+```
+
+Each sample includes complete React Native app structure with platform-specific builds.
+
+## 📚 Documentation
+
+### Generated Documentation
+```
+docs/                                   # JSDoc-generated API documentation
+├── index.html                         # Main documentation entry
+├── Mixpanel.html                      # Mixpanel class documentation
+├── People.html                        # People Analytics documentation
+└── MixpanelGroup.html                 # Group Analytics documentation
+```
+
+### Maintenance Scripts
+- `generate_docs.sh` - JSDoc documentation generation script
+- `release.py` - Release automation script
+
+## 🔍 Key Architectural Insights
+
+### Multi-Instance Design
+- **Token-based isolation**: Each Mixpanel project gets separate instance
+- **Shared infrastructure**: Common queue, network, and storage layers
+- **State persistence**: User IDs, super properties survive app restarts
+
+### Cross-Platform Strategy
+- **Automatic fallback**: Native → JavaScript mode based on availability
+- **Platform detection**: iOS/Android-specific behavior handling
+- **Unified API**: Same interface regardless of implementation mode
+
+### Performance Considerations
+- **Batched flushing**: Events sent in configurable batches (default 50)
+- **Background flushing**: Automatic data transmission on app state changes
+- **Memory management**: In-memory queues with persistent backup
+
+### Error Handling Philosophy
+- **Graceful degradation**: JavaScript mode as native fallback
+- **Input validation**: Comprehensive parameter checking with helpful errors
+- **Logging strategy**: Centralized, configurable logging system
+
+## 🔧 Configuration Patterns
+
+### React Native Integration
+- **Autolinking**: Automatic native module discovery
+- **Manual linking support**: Fallback for older RN versions
+- **Metro bundler**: Standard React Native build pipeline
+
+### Dependencies Strategy [Updated: 2025-05-30]
+- **Minimal external deps**: Only essential libraries (AsyncStorage, uuid, expo-crypto)
+- **Platform compatibility**: Enhanced Expo support with expo-crypto for UUID generation
+- **Version constraints**: Conservative dependency versioning
+- **Graceful fallbacks**: expo-crypto optional, falls back to uuid package