mixpanel-react-native 3.0.9 → 3.1.0

package/.github/prompts/implement-tests.prompt.md

@@ -0,0 +1,466 @@
+---
+mode: 'agent'
+tools: ['codebase', 'terminal']
+description: 'Implement comprehensive tests for dual-implementation features'
+---
+
+Implement comprehensive tests for the feature: "${input:featureName}" in the Mixpanel React Native library.
+
+## Testing Workflow
+
+Create complete test coverage following our dual-implementation testing patterns:
+
+### 1. Test File Setup
+Create test file: `__tests__/${input:featureName}.test.js`
+
+```javascript
+import { jest } from "@jest/globals";
+
+// Import required mocks (automatically loaded from jest_setup.js)
+const { MixpanelQueueManager } = require("mixpanel-react-native/javascript/mixpanel-queue");
+const { MixpanelNetwork } = require("mixpanel-react-native/javascript/mixpanel-network");
+
+describe('${input:featureName} Tests', () => {
+  let mixpanel;
+  
+  beforeEach(() => {
+    jest.clearAllMocks();
+    MixpanelQueueManager._queues = {};
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+  });
+  
+  // Test sections will be added below
+});
+```
+
+### 2. Input Validation Tests (MANDATORY)
+```javascript
+describe('Input Validation', () => {
+  beforeEach(() => {
+    mixpanel = new Mixpanel('test-token', true);
+  });
+
+  // Test ALL invalid string inputs
+  const invalidStrings = ['', null, undefined, '   ', 123, {}, [], Symbol('test')];
+  
+  invalidStrings.forEach((invalid) => {
+    it(`should reject invalid string parameter: ${JSON.stringify(invalid)}`, () => {
+      expect(() => {
+        mixpanel.${input:featureName}(invalid, {});
+      }).toThrow('parameter is not a valid string');
+    });
+  });
+
+  // Test ALL invalid object inputs
+  const invalidObjects = ['string', 123, true, () => {}, Symbol('test')];
+  
+  invalidObjects.forEach((invalid) => {
+    it(`should reject invalid object parameter: ${typeof invalid}`, () => {
+      expect(() => {
+        mixpanel.${input:featureName}('valid', invalid);
+      }).toThrow('properties is not a valid json object');
+    });
+  });
+
+  // Test edge cases
+  it('should allow null and undefined optional parameters', () => {
+    expect(() => {
+      mixpanel.${input:featureName}('valid', null);
+      mixpanel.${input:featureName}('valid', undefined);
+    }).not.toThrow();
+  });
+
+  it('should reject whitespace-only strings', () => {
+    expect(() => {
+      mixpanel.${input:featureName}('   ', {});
+    }).toThrow('parameter is not a valid string');
+  });
+});
+```
+
+### 3. Native Mode Tests (REQUIRED)
+```javascript
+describe('Native Mode', () => {
+  beforeEach(() => {
+    // Force native mode
+    mixpanel = new Mixpanel('test-token', true, true);
+  });
+
+  it('should call native implementation', () => {
+    const parameter = 'test_parameter';
+    const properties = { testProp: 'testValue' };
+
+    mixpanel.${input:featureName}(parameter, properties);
+
+    expect(MixpanelReactNative.${input:featureName}).toHaveBeenCalledWith(
+      'test-token',
+      parameter,
+      expect.objectContaining({
+        ...properties,
+        // Should include metadata
+        mp_lib: 'react-native',
+        $lib_version: expect.any(String)
+      })
+    );
+  });
+
+  it('should handle native implementation promises', async () => {
+    MixpanelReactNative.${input:featureName}.mockResolvedValue();
+
+    await expect(
+      mixpanel.${input:featureName}('parameter', {})
+    ).resolves.toBeUndefined();
+
+    expect(MixpanelReactNative.${input:featureName}).toHaveBeenCalledWith(
+      'test-token',
+      'parameter',
+      expect.any(Object)
+    );
+  });
+
+  it('should handle native implementation errors', async () => {
+    const error = new Error('Native error');
+    MixpanelReactNative.${input:featureName}.mockRejectedValue(error);
+
+    await expect(
+      mixpanel.${input:featureName}('parameter', {})
+    ).rejects.toThrow('Native error');
+  });
+
+  it('should verify implementation type', () => {
+    expect(mixpanel.mixpanelImpl).toBe(MixpanelReactNative);
+  });
+});
+```
+
+### 4. JavaScript Mode Tests (REQUIRED)
+```javascript
+describe('JavaScript Mode', () => {
+  beforeEach(() => {
+    // Force JavaScript mode
+    mixpanel = new Mixpanel('test-token', true, false);
+  });
+
+  it('should use JavaScript implementation', () => {
+    expect(mixpanel.mixpanelImpl).toBeInstanceOf(MixpanelMain);
+    expect(mixpanel.mixpanelImpl).not.toBe(MixpanelReactNative);
+  });
+
+  it('should queue events for batch processing', async () => {
+    const parameter = 'test_parameter';
+    const properties = { prop: 'value' };
+
+    mixpanel.${input:featureName}(parameter, properties);
+
+    // Verify event was added to queue
+    expect(MixpanelQueueManager.enqueue).toHaveBeenCalledWith(
+      'test-token',
+      MixpanelType.EVENTS,
+      expect.objectContaining({
+        event: parameter,
+        properties: expect.objectContaining(properties)
+      })
+    );
+  });
+
+  it('should respect opt-out status', async () => {
+    // Mock opt-out status
+    const mockPersistent = {
+      getOptedOut: jest.fn().mockReturnValue(true)
+    };
+    MixpanelPersistent.getInstance.mockReturnValue(mockPersistent);
+
+    mixpanel.${input:featureName}('parameter', {});
+
+    // Should not queue event when opted out
+    expect(MixpanelQueueManager.enqueue).not.toHaveBeenCalled();
+  });
+
+  it('should enrich events with complete metadata', async () => {
+    // Set up context
+    await mixpanel.identify('user123');
+    await mixpanel.registerSuperProperties({ segment: 'premium' });
+
+    mixpanel.${input:featureName}('parameter', { amount: 99.99 });
+
+    expect(MixpanelQueueManager.enqueue).toHaveBeenCalledWith(
+      'test-token',
+      MixpanelType.EVENTS,
+      expect.objectContaining({
+        event: 'parameter',
+        properties: expect.objectContaining({
+          // Event properties
+          amount: 99.99,
+          // Super properties
+          segment: 'premium',
+          // Identity properties
+          distinct_id: 'user123',
+          // Metadata
+          mp_lib: 'react-native',
+          $lib_version: expect.any(String),
+          // Session metadata
+          $mp_metadata: expect.objectContaining({
+            $mp_session_id: expect.any(String),
+            $mp_event_id: expect.any(String)
+          })
+        })
+      })
+    );
+  });
+});
+```
+
+### 5. Error Handling Tests (CRITICAL)
+```javascript
+describe('Error Handling', () => {
+  beforeEach(() => {
+    mixpanel = new Mixpanel('test-token', true, false);
+  });
+
+  it('should handle storage failures gracefully', async () => {
+    const storageError = new Error('Storage unavailable');
+    AsyncStorage.setItem.mockRejectedValue(storageError);
+
+    // Should not throw error
+    await expect(
+      mixpanel.${input:featureName}('parameter', { prop: 'value' })
+    ).resolves.toBeUndefined();
+
+    // Should log error
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('error setting item in storage')
+    );
+  });
+
+  it('should handle network failures with retry', async () => {
+    const networkError = new Error('Network timeout');
+    global.fetch
+      .mockRejectedValueOnce(networkError)
+      .mockResolvedValueOnce({
+        status: 200,
+        json: () => Promise.resolve(1)
+      });
+
+    await MixpanelNetwork.sendRequest({
+      token: 'test-token',
+      endpoint: '/track/',
+      data: [{ event: 'test' }],
+      serverURL: 'https://api.mixpanel.com',
+      useIPAddressForGeoLocation: true
+    });
+
+    expect(global.fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('should handle corrupted storage data', async () => {
+    AsyncStorage.getItem.mockResolvedValue('invalid-json{');
+
+    const result = await mixpanel.getSuperProperties();
+
+    expect(result).toEqual({});
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to parse')
+    );
+  });
+
+  it('should handle serialization errors', () => {
+    const circularRef = {};
+    circularRef.self = circularRef;
+
+    expect(() => {
+      mixpanel.${input:featureName}('parameter', { circular: circularRef });
+    }).toThrow(); // Should throw during validation, not silently fail
+  });
+});
+```
+
+### 6. Integration Tests
+```javascript
+describe('Integration Tests', () => {
+  beforeEach(async () => {
+    mixpanel = new Mixpanel('test-token', true, false);
+    await mixpanel.init();
+  });
+
+  it('should work with complete tracking pipeline', async () => {
+    // Set up user context
+    await mixpanel.identify('user123');
+    await mixpanel.registerSuperProperties({ user_segment: 'premium' });
+
+    // Test the feature
+    mixpanel.${input:featureName}('test_parameter', { amount: 99.99, currency: 'USD' });
+
+    // Verify complete event structure
+    expect(MixpanelQueueManager.enqueue).toHaveBeenCalledWith(
+      'test-token',
+      MixpanelType.EVENTS,
+      expect.objectContaining({
+        event: 'test_parameter',
+        properties: expect.objectContaining({
+          amount: 99.99,
+          currency: 'USD',
+          user_segment: 'premium',
+          distinct_id: 'user123',
+          mp_lib: 'react-native',
+          $lib_version: expect.any(String)
+        })
+      })
+    );
+  });
+
+  it('should handle queue processing and network requests', async () => {
+    // Add multiple events to queue
+    for (let i = 0; i < 5; i++) {
+      mixpanel.${input:featureName}(`parameter_${i}`, { index: i });
+    }
+
+    // Mock successful network response
+    global.fetch.mockResolvedValue({
+      status: 200,
+      json: () => Promise.resolve(1)
+    });
+
+    // Trigger queue processing
+    await mixpanel.flush();
+
+    // Verify network request was made
+    expect(global.fetch).toHaveBeenCalledWith(
+      expect.stringContaining('https://api.mixpanel.com/track/'),
+      expect.objectContaining({
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded'
+        },
+        body: expect.stringContaining('data=')
+      })
+    );
+
+    // Verify queue was cleared after successful send
+    expect(MixpanelQueueManager.spliceQueue).toHaveBeenCalledWith(
+      'test-token',
+      MixpanelType.EVENTS,
+      0,
+      5 // All 5 events should be removed
+    );
+  });
+});
+```
+
+### 7. Multi-Token Tests
+```javascript
+describe('Multi-Token Support', () => {
+  it('should isolate data between different tokens', async () => {
+    const mixpanel1 = new Mixpanel('token1', true, false);
+    const mixpanel2 = new Mixpanel('token2', true, false);
+
+    await mixpanel1.init();
+    await mixpanel2.init();
+
+    // Set different properties for each token
+    await mixpanel1.registerSuperProperties({ source: 'app1' });
+    await mixpanel2.registerSuperProperties({ source: 'app2' });
+
+    // Test the feature
+    mixpanel1.${input:featureName}('parameter1', {});
+    mixpanel2.${input:featureName}('parameter2', {});
+
+    // Verify token isolation
+    expect(MixpanelQueueManager.enqueue).toHaveBeenCalledWith(
+      'token1', MixpanelType.EVENTS,
+      expect.objectContaining({
+        properties: expect.objectContaining({ source: 'app1' })
+      })
+    );
+
+    expect(MixpanelQueueManager.enqueue).toHaveBeenCalledWith(
+      'token2', MixpanelType.EVENTS,
+      expect.objectContaining({
+        properties: expect.objectContaining({ source: 'app2' })
+      })
+    );
+  });
+});
+```
+
+### 8. Performance Tests
+```javascript
+describe('Performance Tests', () => {
+  beforeEach(() => {
+    mixpanel = new Mixpanel('test-token', true, false);
+  });
+
+  it('should handle high-volume operations', async () => {
+    const startTime = Date.now();
+    
+    // Perform 1000 operations
+    for (let i = 0; i < 1000; i++) {
+      mixpanel.${input:featureName}(`parameter_${i}`, { index: i });
+    }
+    
+    const endTime = Date.now();
+    const duration = endTime - startTime;
+    
+    // Should complete within reasonable time
+    expect(duration).toBeLessThan(5000); // 5 seconds
+    
+    // Verify all operations were processed
+    expect(MixpanelQueueManager.enqueue).toHaveBeenCalledTimes(1000);
+  });
+});
+```
+
+## Mock Updates Required
+
+Update `__tests__/jest_setup.js`:
+```javascript
+jest.doMock("react-native", () => ({
+  NativeModules: {
+    MixpanelReactNative: {
+      // ... existing methods
+      ${input:featureName}: jest.fn().mockResolvedValue(undefined), // Add new method
+    },
+  },
+}));
+```
+
+## Test Execution
+
+Run the tests:
+```bash
+# Run specific test file
+npm test -- __tests__/${input:featureName}.test.js
+
+# Run tests in watch mode during development
+npm test -- --watch __tests__/${input:featureName}.test.js
+
+# Run with coverage
+npm test -- --coverage __tests__/${input:featureName}.test.js
+```
+
+## Test Checklist
+
+### Basic Coverage
+- [ ] Input validation for all parameters
+- [ ] Native mode implementation calls
+- [ ] JavaScript mode queue management
+- [ ] Error handling scenarios
+- [ ] Mock verification and reset
+
+### Advanced Coverage
+- [ ] Integration with tracking pipeline
+- [ ] Multi-token isolation
+- [ ] Storage persistence testing
+- [ ] Network request handling
+- [ ] Performance under load
+
+### Mock Maintenance
+- [ ] Native module mocks updated
+- [ ] AsyncStorage mocks configured
+- [ ] Network mocks properly reset
+- [ ] All external dependencies mocked
+
+Reference our testing guide: `claude/workflows/02-testing-changes.md`
+Use our standard patterns: `.github/copilot-instructions.md`

package/.vscode/settings.json

@@ -1,4 +1,5 @@
 {
   "java.compile.nullAnalysis.mode": "automatic",
-  "files.trimTrailingWhitespace": true
+  "files.trimTrailingWhitespace": true,
+  "java.configuration.updateBuildConfiguration": "interactive"
 }

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 #
 
+## [v3.1.0](https://github.com/mixpanel/mixpanel-react-native/tree/v3.1.0) (2025-05-30)
+
+### Enhancements
+
+- Use expo-crypto for UUID on Expo, expose useGzipCompression option and fix JavaScript mode People flushing issue [\#288](https://github.com/mixpanel/mixpanel-react-native/pull/288)
+
+#
+
 ## [v3.0.9](https://github.com/mixpanel/mixpanel-react-native/tree/v3.0.9) (2025-04-11)
 
 ### Enhancements
@@ -493,6 +501,8 @@ This major release removes all remaining calls to Mixpanel's `/decide` API endpo
 
 
 
+
+
 
 
 

package/CLAUDE.md

@@ -0,0 +1,183 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Testing
+- Run all tests: `npm test`
+- Run specific test: `npm test -- path/to/test.js`
+- Tests are located in `__tests__/` directory
+- Run tests with coverage: `npm test -- --coverage`
+
+### Development
+- This is a library package with no build/dev server commands
+- For testing changes, use the sample apps in `Samples/` directory
+- Native changes require: `cd ios && pod install` (iOS) or gradle sync (Android)
+
+### Debugging
+- Enable logging: `mixpanel.setLoggingEnabled(true)`
+- All logs prefixed with `[Mixpanel]` for easy filtering
+- See `claude/workflows/03-debugging-issues.md` for comprehensive debugging guide
+
+## Discovered Conventions
+
+### Code Style & Patterns
+- **File naming**: kebab-case (`mixpanel-core.js`, `mixpanel-queue.js`)
+- **Variables**: camelCase for standard vars, SCREAMING_SNAKE_CASE for constants
+- **Functions**: verb-first naming (`initialize`, `track`, `flush`)
+- **Imports**: External deps first, then internal modules grouped by purpose (with consistent spacing)
+- **Error handling**: Comprehensive input validation with Helper classes
+- **Logging**: Token-scoped conditional logging throughout
+- **UUID Generation** [Updated: 2025-05-30]: Try expo-crypto first, fallback to uuid.v4()
+
+### API Design Philosophy
+- **Graceful degradation**: Native → JavaScript fallback strategy
+- **Defensive programming**: Validate all inputs, handle all errors
+- **Silent failures**: Storage/network errors don't crash the app
+- **Token isolation**: All state scoped by token for multi-project support
+
+### Key Architectural Patterns
+- **Factory functions**: Core modules use dependency injection
+- **Singleton pattern**: Shared resources (config, storage) use singletons
+- **Write-through caching**: Memory cache backed by persistent storage
+- **Queue-based processing**: Async event batching with retry logic
+
+## Critical Workflows
+
+### 1. Adding New Features (`claude/workflows/01-adding-new-features.md`)
+```bash
+# Essential steps for new features:
+1. Design API with input validation (StringHelper/ObjectHelper)
+2. Implement iOS native version with @objc decorator
+3. Implement Android native version with @ReactMethod
+4. Add JavaScript fallback implementation
+5. Write comprehensive tests for both modes
+6. Update TypeScript definitions and documentation
+```
+
+### 2. Testing Changes (`claude/workflows/02-testing-changes.md`)
+```bash
+# Test both implementation modes:
+npm test                           # Run full test suite
+npm test -- __tests__/core.test.js # Test specific module
+# Test in sample apps:
+cd Samples/SimpleMixpanel && npm install && npx react-native run-ios
+```
+
+### 3. Debugging Issues (`claude/workflows/03-debugging-issues.md`)
+```javascript
+// Quick diagnostic script:
+const debugImplementationMode = () => {
+  console.log('Native available:', !!NativeModules.MixpanelReactNative);
+  console.log('Using:', mixpanel.mixpanelImpl === MixpanelReactNative ? 'Native' : 'JS');
+};
+```
+
+## Quick Reference
+
+### Most-Used File Locations
+- **Main API**: `index.js` (public interface with validation)
+- **JS Implementation**: `javascript/mixpanel-main.js`
+- **Core Logic**: `javascript/mixpanel-core.js` 
+- **Queue Management**: `javascript/mixpanel-queue.js`
+- **Network Layer**: `javascript/mixpanel-network.js`
+- **Storage Layer**: `javascript/mixpanel-storage.js`
+- **iOS Native**: `ios/MixpanelReactNative.swift`
+- **Android Native**: `android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java`
+
+### Common Commands
+```bash
+# After native changes:
+cd ios && pod install              # iOS
+cd android && ./gradlew clean      # Android
+
+# Testing specific modes:
+new Mixpanel(token, true, true)    # Force native mode
+new Mixpanel(token, true, false)   # Force JavaScript mode
+
+# Initialize with gzip compression [Updated: 2025-05-30]:
+await mixpanel.init(false, {}, "https://api.mixpanel.com", true)
+
+# Debug storage:
+AsyncStorage.getAllKeys().then(console.log)
+
+# Manual flush for testing:
+mixpanel.flush()
+
+# Check if user is identified [Updated: 2025-05-30]:
+mixpanel.mixpanelImpl.mixpanelPersistent.isIdentified(token)
+```
+
+### Key Constants & Patterns
+```javascript
+// Storage key pattern:
+`MIXPANEL_${token}_${type}_${field}`
+
+// Queue types:
+MixpanelType.EVENTS   // "/track/"
+MixpanelType.USER     // "/engage/" 
+MixpanelType.GROUPS   // "/groups/"
+
+// Error handling pattern:
+if (!StringHelper.isValid(param)) {
+  StringHelper.raiseError(PARAM_NAME);
+}
+
+// Conditional property inclusion [Updated: 2025-05-30]:
+const data = {
+  ...requiredProps,
+  ...(optionalValue != null && { optionalKey: optionalValue })
+};
+```
+
+## Architecture Context
+
+For deeper architecture understanding, consult:
+- `claude/context-map.md` - Guide to knowledge architecture
+- `claude/architecture/system-design.md` - Detailed system design with diagrams
+- `claude/discovered-patterns.md` - Comprehensive coding patterns
+- `claude/codebase-map.md` - File organization and responsibilities
+
+## Generated Context (Original)
+
+### Dual Implementation Strategy
+The library operates in two modes:
+1. **Native Mode** (default): Uses native iOS/Android modules for better performance
+2. **JavaScript Mode**: Pure JS implementation for Expo and React Native Web support
+
+Mode selection happens automatically based on platform capabilities.
+
+### Core Components
+
+**Entry Points:**
+- `index.js` - Main entry exporting Mixpanel, People, and MixpanelGroup classes
+- `index.d.ts` - TypeScript definitions
+
+**Native Modules:**
+- `ios/MixpanelReactNative.swift` - iOS implementation using Mixpanel Swift SDK
+- `android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java` - Android implementation
+
+**JavaScript Implementation (`javascript/` directory):**
+- `mixpanel-main.js` - JS mode entry point, implements full Mixpanel API
+- `mixpanel-core.js` - Core tracking logic shared between modes
+- `mixpanel-queue.js` - Event queue management with automatic flushing
+- `mixpanel-network.js` - HTTP request handling with retry logic
+- `mixpanel-storage.js` - Abstraction over AsyncStorage for persistence
+
+### Data Flow
+1. API calls go through `index.js` which routes to native module or JS implementation
+2. Events are queued (in-memory + persistent storage)
+3. Queues flush automatically every 10s (JS) or 60s (native)
+4. Failed requests retry with exponential backoff
+
+### Key Patterns
+- **Token-based instances**: Multiple Mixpanel projects supported via different tokens
+- **Persistent state**: Super properties, user IDs, and queues survive app restarts
+- **Automatic properties**: Device info, OS version, etc. added automatically
+- **GDPR compliance**: Built-in opt-out and data deletion methods
+
+## Testing Guidelines
+- Mock AsyncStorage and React Native modules are pre-configured
+- Test both native and JS modes when making changes
+- Use sample apps to verify integration works correctly

package/MixpanelReactNative.podspec

@@ -19,5 +19,5 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
 
   s.dependency "React-Core"
-  s.dependency "Mixpanel-swift", '4.4.0'
+  s.dependency "Mixpanel-swift", '5.1.0'
 end