mixpanel-react-native 3.0.9 → 3.1.0

package/claude/technologies/react-native.md

@@ -0,0 +1,353 @@
+# React Native Integration Patterns
+
+## Overview
+
+The mixpanel-react-native library demonstrates sophisticated React Native integration patterns, including native module bridging, autolinking configuration, and cross-platform compatibility strategies.
+
+## 🔗 Native Module Bridge Architecture
+
+### Platform Registration
+
+#### iOS (CocoaPods Integration)
+```ruby
+# MixpanelReactNative.podspec
+Pod::Spec.new do |s|
+  s.name = "MixpanelReactNative"
+  s.platform = :ios, "11.0"
+  s.swift_version = '5.0'
+  s.source_files = "ios/*.{swift,h,m}"
+  
+  # Key dependencies
+  s.dependency "React-Core"
+  s.dependency "Mixpanel-swift", '5.0.0'  # Official Mixpanel iOS SDK
+end
+```
+
+**Key Insights**:
+- Minimum iOS 11.0 support
+- Swift 5.0 for modern language features
+- Direct dependency on official Mixpanel iOS SDK
+- Source files include both Swift and Objective-C bridge files
+
+#### Android (Gradle Integration)
+```gradle
+// android/build.gradle
+android {
+    compileSdkVersion 34
+    minSdkVersion 21      // Android 5.0+
+    targetSdkVersion 34
+    namespace "com.mixpanel.reactnative"  // AGP 7.0+ namespace
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-native:+'
+    implementation 'com.mixpanel.android:mixpanel-android:8.1.0'  // Official Android SDK
+}
+```
+
+**Key Insights**:
+- Modern Android API levels (21-34)
+- Namespace declaration for AGP 7.0+ compatibility
+- Direct integration with official Mixpanel Android SDK
+- Dynamic React Native version resolution
+
+### Autolinking Configuration
+
+```javascript
+// react-native.config.js
+module.exports = {
+  dependencies: {
+    'mixpanel-react-native': {
+      platforms: {
+        android: {
+          "sourceDir": "./node_modules/mixpanel-react-native/android",
+          "packageImportPath": "import com.mixpanel.reactnative.MixpanelReactNativePackage;",
+          "packageInstance": "new MixpanelReactNativePackage()"
+        },
+        ios: {
+          project: './node_modules/mixpanel-react-native/ios/MixpanelReactNative.xcodeproj',
+        }
+      }
+    }
+  }
+};
+```
+
+**Autolinking Strategy**:
+- Explicit configuration for both platforms
+- Custom package registration for Android
+- Xcode project specification for iOS
+- Supports React Native 0.60+ autolinking
+
+## 🏗️ Native Module Implementation Patterns
+
+### iOS Bridge Pattern (Swift + Objective-C)
+
+```swift
+// ios/MixpanelReactNative.swift
+@objc(MixpanelReactNative)
+open class MixpanelReactNative: NSObject {
+    
+    @objc static func requiresMainQueueSetup() -> Bool {
+        return false  // Background initialization OK
+    }
+    
+    @objc
+    func initialize(_ token: String,
+                    trackAutomaticEvents: Bool,
+                    optOutTrackingByDefault: Bool = false,
+                    properties: [String: Any],
+                    serverURL: String,
+                    useGzipCompression: Bool = false,
+                    resolver resolve: RCTPromiseResolveBlock,
+                    rejecter reject: RCTPromiseRejectBlock) -> Void {
+        // Native implementation using Mixpanel-swift SDK
+        Mixpanel.initialize(token: token, ...)
+        resolve(true)
+    }
+}
+```
+
+**Bridge Patterns**:
+- `@objc` decoration for React Native exposure
+- Promise-based async operations
+- Background-safe initialization
+- Direct parameter mapping to native SDK
+
+### Android Bridge Pattern (Java)
+
+```java
+// android/.../MixpanelReactNativeModule.java
+public class MixpanelReactNativeModule extends ReactContextBaseJavaModule {
+    
+    @ReactMethod
+    public void initialize(String token, 
+                          boolean trackAutomaticEvents, 
+                          boolean optOutTrackingDefault, 
+                          ReadableMap metadata, 
+                          String serverURL, 
+                          boolean useGzipCompression, 
+                          Promise promise) throws JSONException {
+        
+        // Convert React Native types to native
+        JSONObject mixpanelProperties = ReactNativeHelper.reactToJSON(metadata);
+        
+        // Initialize native SDK
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, 
+                                                      token, 
+                                                      optOutTrackingDefault, 
+                                                      mixpanelProperties, 
+                                                      null, 
+                                                      trackAutomaticEvents);
+        promise.resolve(null);
+    }
+}
+```
+
+**Bridge Patterns**:
+- `@ReactMethod` annotation for method exposure
+- Type conversion utilities (`ReactNativeHelper`)
+- Thread-safe instance management
+- Consistent Promise-based API
+
+## 🔄 Fallback Strategy Implementation
+
+### Implementation Router Pattern
+
+```javascript
+// index.js
+export class Mixpanel {
+  constructor(token, trackAutomaticEvents, useNative = true, storage) {
+    this.token = token;
+    this.trackAutomaticEvents = trackAutomaticEvents;
+
+    // Try native implementation first
+    if (useNative && MixpanelReactNative) {
+      this.mixpanelImpl = MixpanelReactNative;
+      return;
+    } else if (useNative) {
+      console.warn(
+        "MixpanelReactNative is not available; using JavaScript mode..."
+      );
+    }
+
+    // Fallback to JavaScript implementation
+    this.mixpanelImpl = new MixpanelMain(token, trackAutomaticEvents, storage);
+  }
+}
+```
+
+**Fallback Benefits**:
+- Graceful degradation when native modules unavailable
+- Expo compatibility (no native modules allowed)
+- Web support through React Native Web
+- Development environment flexibility
+
+## 📱 Platform-Specific Optimizations
+
+### iOS Optimizations
+
+```swift
+// ios/MixpanelReactNative.swift
+@objc
+func setFlushOnBackground(_ token: String,
+                         flushOnBackground: Bool,
+                         resolver resolve: RCTPromiseResolveBlock,
+                         rejecter reject: RCTPromiseRejectBlock) -> Void {
+    let instance = MixpanelReactNative.getMixpanelInstance(token)
+    instance?.flushOnBackground = flushOnBackground  // iOS-specific feature
+    resolve(nil)
+}
+```
+
+**iOS-Specific Features**:
+- Background flushing support
+- App lifecycle integration
+- Memory management optimization
+- Native SDK performance benefits
+
+### Android Optimizations
+
+```java
+// android/.../MixpanelReactNativeModule.java
+@ReactMethod
+public void setFlushBatchSize(final String token, Integer flushBatchSize, Promise promise) {
+    MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+    if (instance == null) {
+        promise.reject("Instance Error", "Failed to get Mixpanel instance");
+        return;
+    }
+    synchronized (instance) {  // Thread-safe operations
+        instance.setFlushBatchSize(flushBatchSize);
+        promise.resolve(null);
+    }
+}
+```
+
+**Android-Specific Features**:
+- Thread synchronization for safety
+- Context-aware initialization
+- Lifecycle-aware processing
+- Memory-efficient batching
+
+## 🛠️ Development & Build Configuration
+
+### Metro Configuration (Standard)
+
+```javascript
+// Samples/SimpleMixpanel/metro.config.js
+const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
+
+const config = {};  // Use defaults
+
+module.exports = mergeConfig(getDefaultConfig(__dirname), config);
+```
+
+**Build Strategy**:
+- Standard React Native Metro bundler
+- No custom transformations needed
+- Works with standard RN build pipeline
+
+### Babel Configuration (Standard)
+
+```javascript
+// Samples/SimpleMixpanel/babel.config.js
+module.exports = {
+  presets: ['module:@react-native/babel-preset'],
+};
+```
+
+**Transpilation Strategy**:
+- Standard React Native Babel preset
+- No custom plugins required
+- ES6+ feature support
+
+## 🧪 Testing Integration
+
+### Jest Configuration for React Native
+
+```javascript
+// package.json
+"jest": {
+  "modulePathIgnorePatterns": ["<rootDir>/Samples/"],
+  "testMatch": ["<rootDir>/__tests__/*.test.js"],
+  "setupFiles": ["<rootDir>/__tests__/jest_setup.js"],
+  "verbose": true,
+  "preset": "react-native"
+}
+```
+
+**Testing Strategy**:
+- React Native Jest preset
+- Custom setup for mocking
+- Isolated test environment
+- Sample apps excluded from tests
+
+### Native Module Mocking
+
+```javascript
+// __tests__/jest_setup.js
+jest.doMock("react-native", () => {
+  return Object.setPrototypeOf({
+    NativeModules: {
+      MixpanelReactNative: {
+        initialize: jest.fn(),
+        track: jest.fn(),
+        // ... complete API mock
+      },
+    },
+  }, ReactNative);
+});
+```
+
+**Mocking Strategy**:
+- Complete native module API mocking
+- Consistent with actual native interface
+- Enables testing without native dependencies
+
+## 🚀 Performance Considerations
+
+### Native vs JavaScript Mode
+
+| Aspect | Native Mode | JavaScript Mode |
+|--------|-------------|-----------------|
+| **Initialization** | Native SDK optimized | Custom implementation |
+| **Queue Management** | Native (60s flush) | JavaScript (10s flush) |
+| **Storage** | Platform-optimized | AsyncStorage |
+| **Network** | Native HTTP stack | Fetch API |
+| **Memory** | SDK-managed | Manual management |
+
+### Bundle Size Impact
+
+```javascript
+// The library is designed for minimal bundle impact:
+// - Core native bridge code only
+// - JavaScript fallback loaded conditionally
+// - No heavy dependencies in main bundle
+```
+
+## 📋 Best Practices Discovered
+
+### 1. Graceful Degradation
+Always provide JavaScript fallback for native functionality
+
+### 2. Promise-Based APIs
+Consistent async patterns across platforms
+
+### 3. Type Safety
+Comprehensive input validation before native calls
+
+### 4. Error Handling
+Native errors properly propagated to JavaScript
+
+### 5. Platform Detection
+Runtime detection of capabilities rather than build-time
+
+### 6. Memory Management
+Proper cleanup and instance management
+
+### 7. Thread Safety
+Synchronization for shared resources
+
+### 8. Configuration Flexibility
+Runtime configuration over build-time constants

package/claude/updates/architecture-impact-2025-05-30.md

@@ -0,0 +1,109 @@
+# Architecture Impact Assessment - 2025-05-30
+
+## Architectural Review
+
+### Has the fundamental architecture changed?
+**No** - The dual-path architecture (Native + JavaScript fallback) remains intact.
+
+### Component Evolution Assessment
+
+#### ✅ Layer Boundaries: **Still Respected**
+- Public API layer maintains validation responsibility
+- Implementation router still handles native vs JS routing
+- Core processing layer maintains business logic separation
+- Infrastructure layers remain independent
+
+#### ✅ New Integrations: **Expo Crypto Support**
+- **Type**: Cross-cutting concern
+- **Impact**: Minimal - follows existing fallback pattern
+- **Location**: Persistence layer only
+
+#### ✅ Component Responsibility: **Slightly Evolved**
+- **MixpanelPersistent**: Now handles token-specific initialization
+- **MixpanelCore**: Added identity queue management responsibility
+- **Impact**: Natural evolution, not breaking changes
+
+#### ✅ Data Flow: **Enhanced, Not Changed**
+- Identity management flow now includes queue update step
+- Profile data flow now filters null values
+- Overall flow architecture remains the same
+
+## Tactical Improvements
+
+### 1. Enhanced Expo Compatibility
+- **Change**: Added expo-crypto for UUID generation
+- **Impact**: Better Expo support without architectural change
+- **Pattern**: Follows existing graceful degradation philosophy
+
+### 2. Improved Queue Management
+- **Change**: Added `identifyUserQueue` to ensure proper queue state
+- **Impact**: Fixes edge case in identity management
+- **Pattern**: Tactical fix within existing architecture
+
+### 3. Network Optimization
+- **Change**: Optional gzip compression support
+- **Impact**: Performance improvement option
+- **Pattern**: Configuration extension, not architectural change
+
+### 4. Storage Robustness
+- **Change**: Better module resolution, token-specific initialization
+- **Impact**: More reliable storage handling
+- **Pattern**: Defensive programming enhancement
+
+## Architecture Diagram Updates
+
+The high-level architecture diagram in `system-design.md` remains accurate. Only minor annotation updates needed:
+
+### Event Tracking Flow - Add annotation:
+```
+┌─────────────────────────────────────────────┐
+│            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                    │
+│  • [NEW] Filter null identity values       │ ← Add this
+└─────────────────┬───────────────────────────┘
+```
+
+### Identity Management Flow - Add step:
+```
+┌─────────────────────────────────────────────┐
+│          Queue Identity Update              │
+│  • Update existing USER queue records      │
+│  • Ensure consistent identity fields       │
+│  • Minimize object copying (performance)   │
+│  • [NEW] Call identifyUserQueue()         │ ← Add this
+└─────────────────────────────────────────────┘
+```
+
+## Design Decision Updates
+
+### New Trade-off: Expo Compatibility vs Bundle Size
+**Decision**: Include expo-crypto as optional dependency
+**Trade-off**: Slightly larger bundle for better Expo support
+**Justification**: Expo is major React Native platform
+
+### Existing Trade-offs: **All Still Valid**
+- Reliability over performance ✓
+- Token-based multi-tenancy ✓
+- Dual implementation strategy ✓
+- Aggressive error handling ✓
+- Queue-based architecture ✓
+
+## Boundary Analysis
+
+### Maintained Boundaries
+- ✅ Native module boundary unchanged
+- ✅ Storage abstraction boundary intact
+- ✅ Network layer isolation preserved
+- ✅ Queue management encapsulation maintained
+
+### Evolved Boundaries
+- 🔄 Persistence layer now more token-aware (improvement)
+- 🔄 Core layer has slightly more queue knowledge (acceptable coupling)
+
+## Conclusion
+
+The changes represent **tactical improvements** within the existing architecture rather than strategic shifts. The fundamental design remains sound and the documented architecture in `system-design.md` requires only minor annotations rather than major revisions. The team is following the established patterns while making pragmatic improvements for reliability and compatibility.

package/claude/updates/change-analysis-2025-05-30.md

@@ -0,0 +1,42 @@
+# Change Analysis Report - 2025-05-30
+
+## Summary of Changes Since Initial Documentation
+
+### High-Activity Areas
+
+1. **JavaScript Implementation Layer**: 
+   - Files affected: 5 core files (mixpanel-main.js, mixpanel-core.js, mixpanel-persistent.js, mixpanel-queue.js, mixpanel-storage.js)
+   - Nature of changes: Bug fixes, feature additions, improved storage handling
+   - Pattern implications: Better token isolation, improved persistence management
+
+2. **Main API Interface**:
+   - Files affected: index.js, index.d.ts (implied)
+   - Nature of changes: New optional parameter for gzip compression
+   - Pattern implications: API evolution while maintaining backward compatibility
+
+3. **Test Infrastructure**:
+   - Files affected: Multiple test files, jest setup
+   - Nature of changes: Added expo-crypto mocking, improved test coverage
+   - Pattern implications: Enhanced testing for Expo compatibility
+
+### New Additions
+
+- **New Dependencies**: 
+  - `expo-crypto`: For UUID generation in Expo environments
+  
+- **New Features**:
+  - `useGzipCompression` parameter in init() method
+  - Improved identity queue management
+
+- **New Patterns**:
+  - Conditional property inclusion in profile data (using spread operator with conditions)
+  - Token-specific storage instance initialization
+
+### Deprecated/Removed
+- None identified in this update cycle
+
+### Areas Requiring Deep Analysis
+
+1. **Storage Pattern Evolution**: The change from global to token-specific storage initialization needs investigation
+2. **Identity Management**: New `identifyUserQueue` call suggests improved queue handling for user identification
+3. **Expo Compatibility**: Addition of expo-crypto indicates enhanced Expo support strategy

package/claude/updates/cursor-rules-audit-2025-05-30.md

@@ -0,0 +1,85 @@
+# Cursor Rules Audit Report - 2025-05-30
+
+## Rules Effectiveness Summary
+
+### Always Rules Status
+- Total size: ~450 lines of 500 limit
+- Rules needing update: 2
+- Rules to remove: 0
+- Space for new rules: ~50 lines available
+
+### Component Rules Coverage
+| Component Type | Has Rules | Patterns Covered | Gaps Identified |
+|----------------|-----------|------------------|-----------------|
+| Native Modules | ✓ | 8/9 patterns | Gzip compression parameter |
+| JavaScript Implementation | ✓ | 6/7 patterns | Identity queue management |
+| Storage Operations | ✓ | 9/10 patterns | Module resolution pattern |
+| Network Operations | ✓ | 5/5 patterns | All covered |
+| Testing | ✓ | 4/4 patterns | All covered |
+
+### Recommended Changes
+
+#### High Priority Updates
+
+1. **Rule**: `always/error-handling.mdc`
+   - **Issue**: UUID generation pattern has evolved to use expo-crypto
+   - **Action**: Update fallback pattern example
+   - **Impact**: Affects device ID generation in Expo environments
+
+2. **Rule**: `components/storage-operations.mdc`
+   - **Issue**: Storage module resolution needs update for ES6/CommonJS handling
+   - **Action**: Update AsyncStorageAdapter constructor pattern
+   - **Impact**: Affects storage initialization reliability
+
+3. **Rule**: `components/javascript-implementation.mdc`
+   - **Issue**: Missing identity queue management pattern
+   - **Action**: Add identifyUserQueue pattern
+   - **Impact**: Affects user identification flow
+
+#### New Rules Needed
+
+1. **Pattern**: Conditional property inclusion
+   - **Category**: Always rule (universal pattern)
+   - **Prevents**: Sending null values to API
+   - **Size estimate**: ~30 lines
+
+2. **Pattern**: Gzip compression support
+   - **Category**: Component rule (native modules)
+   - **Prevents**: Missing compression parameter
+   - **Size estimate**: ~20 lines
+
+#### Rules to Update (Minor)
+
+1. **Rule**: `always/core-conventions.mdc`
+   - **Issue**: Import formatting now uses consistent spacing
+   - **Action**: Update import examples
+   - **Impact**: Code consistency
+
+#### Rules to Deprecate
+- None identified - all existing rules remain relevant
+
+## Pattern Evolution Summary
+
+### Mature Patterns (Ready for Rules)
+- Conditional property inclusion using spread operator
+- UUID generation with expo-crypto fallback
+- Storage module resolution for ES6/CommonJS
+
+### Growing Patterns (Monitor for Future)
+- Identity queue management improvements
+- Token-specific storage initialization
+
+### Deprecated Patterns
+- None identified in this update cycle
+
+## Risk Assessment
+- **Low Risk**: All changes are backward compatible
+- **Medium Risk**: Storage module resolution change affects initialization
+- **No Breaking Changes**: All patterns maintain existing behavior
+
+## Recommendation Priority
+1. Update storage module resolution (prevents initialization failures)
+2. Add UUID generation fallback pattern (improves Expo support)
+3. Add conditional property pattern (prevents API issues)
+4. Update import formatting (consistency)
+5. Document gzip compression (new feature awareness)