mixpanel-react-native 3.0.9 → 3.1.0

package/.github/instructions/test-generation.instructions.md

@@ -0,0 +1,289 @@
+---
+applyTo: "**/*.test.*, **/*.spec.*, __tests__/**"
+---
+
+# Test Generation Guidelines
+
+Extends [core instructions](../copilot-instructions.md) with comprehensive testing patterns for dual-implementation architecture.
+
+## Test Structure Requirements
+
+### Dual Mode Testing (MANDATORY)
+Every feature test MUST cover both implementation modes:
+
+```javascript
+describe('Feature Name', () => {
+  let mixpanel;
+  
+  beforeEach(() => {
+    jest.clearAllMocks();
+    MixpanelQueueManager._queues = {};
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+  });
+
+  describe('Input Validation', () => {
+    beforeEach(() => {
+      mixpanel = new Mixpanel('test-token', true);
+    });
+
+    it('should validate required parameters', () => {
+      expect(() => {
+        mixpanel.track('', {});
+      }).toThrow('eventName is not a valid string');
+    });
+  });
+
+  describe('Native Mode', () => {
+    beforeEach(() => {
+      mixpanel = new Mixpanel('test-token', true, true); // Force native
+    });
+
+    it('should call native implementation', () => {
+      mixpanel.track('Event', {prop: 'value'});
+      expect(MixpanelReactNative.track).toHaveBeenCalledWith(
+        'test-token', 'Event', expect.objectContaining({prop: 'value'})
+      );
+    });
+  });
+
+  describe('JavaScript Mode', () => {
+    beforeEach(() => {
+      mixpanel = new Mixpanel('test-token', true, false); // Force JS
+    });
+
+    it('should queue events for processing', () => {
+      mixpanel.track('Event', {prop: 'value'});
+      expect(MixpanelQueueManager.enqueue).toHaveBeenCalledWith(
+        'test-token', MixpanelType.EVENTS, expect.objectContaining({})
+      );
+    });
+  });
+});
+```
+
+## Input Validation Testing (REQUIRED)
+
+### Test All Invalid Inputs
+```javascript
+describe('Input Validation', () => {
+  const invalidStrings = ['', null, undefined, '   ', 123, {}, [], Symbol('test')];
+  const invalidObjects = ['string', 123, true, () => {}, Symbol('test')];
+
+  invalidStrings.forEach((invalid) => {
+    it(`should reject invalid string: ${JSON.stringify(invalid)}`, () => {
+      expect(() => {
+        mixpanel.track(invalid, {});
+      }).toThrow('eventName is not a valid string');
+    });
+  });
+
+  invalidObjects.forEach((invalid) => {
+    it(`should reject invalid object: ${typeof invalid}`, () => {
+      expect(() => {
+        mixpanel.track('event', invalid);
+      }).toThrow('properties is not a valid json object');
+    });
+  });
+
+  it('should allow null and undefined properties', () => {
+    expect(() => {
+      mixpanel.track('event', null);
+      mixpanel.track('event', undefined);
+    }).not.toThrow();
+  });
+});
+```
+
+## Error Handling Testing
+
+### Storage Failure Testing
+```javascript
+describe('Error Handling', () => {
+  it('should handle storage failures gracefully', async () => {
+    const storageError = new Error('Storage unavailable');
+    AsyncStorage.setItem.mockRejectedValue(storageError);
+
+    await expect(
+      mixpanel.registerSuperProperties({ prop: 'value' })
+    ).resolves.toBeUndefined();
+
+    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);
+  });
+});
+```
+
+## Integration Testing Patterns
+
+### End-to-End Flow Testing
+```javascript
+describe('Complete Tracking Flow', () => {
+  beforeEach(async () => {
+    mixpanel = new Mixpanel('test-token', true, false);
+    await mixpanel.init();
+  });
+
+  it('should track event through complete pipeline', async () => {
+    await mixpanel.identify('user123');
+    await mixpanel.registerSuperProperties({ user_segment: 'premium' });
+
+    mixpanel.track('Purchase', { amount: 99.99, currency: 'USD' });
+
+    expect(MixpanelQueueManager.enqueue).toHaveBeenCalledWith(
+      'test-token',
+      MixpanelType.EVENTS,
+      expect.objectContaining({
+        event: 'Purchase',
+        properties: expect.objectContaining({
+          amount: 99.99,
+          currency: 'USD',
+          user_segment: 'premium',
+          distinct_id: 'user123',
+          mp_lib: 'react-native',
+          $lib_version: expect.any(String)
+        })
+      })
+    );
+  });
+});
+```
+
+### Multi-Token Testing
+```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();
+
+    await mixpanel1.registerSuperProperties({ source: 'app1' });
+    await mixpanel2.registerSuperProperties({ source: 'app2' });
+
+    mixpanel1.track('Event1', {});
+    mixpanel2.track('Event2', {});
+
+    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' })
+      })
+    );
+  });
+});
+```
+
+## Performance Testing
+
+### Load Testing Pattern
+```javascript
+describe('Performance Tests', () => {
+  it('should handle high-volume event tracking', async () => {
+    const startTime = Date.now();
+    
+    for (let i = 0; i < 1000; i++) {
+      mixpanel.track(`Event ${i}`, { index: i });
+    }
+    
+    const endTime = Date.now();
+    const duration = endTime - startTime;
+    
+    expect(duration).toBeLessThan(5000); // 5 seconds
+    expect(MixpanelQueueManager.enqueue).toHaveBeenCalledTimes(1000);
+  });
+});
+```
+
+## Mock Configuration
+
+### Required Mocks Setup
+```javascript
+// In jest_setup.js or beforeEach blocks
+jest.mock("@react-native-async-storage/async-storage", () => ({
+  getItem: jest.fn().mockResolvedValue(null),
+  setItem: jest.fn().mockResolvedValue(undefined),
+  removeItem: jest.fn().mockResolvedValue(undefined),
+}));
+
+jest.mock("react-native", () => ({
+  NativeModules: {
+    MixpanelReactNative: {
+      initialize: jest.fn().mockResolvedValue(undefined),
+      track: jest.fn().mockResolvedValue(undefined),
+      identify: jest.fn().mockResolvedValue(undefined),
+      // Mock ALL native methods
+    },
+  },
+  Platform: { OS: 'ios' }
+}));
+
+global.fetch = jest.fn();
+```
+
+### Mock Verification
+```javascript
+beforeEach(() => {
+  expect(jest.isMockFunction(MixpanelReactNative.track)).toBe(true);
+  expect(jest.isMockFunction(AsyncStorage.getItem)).toBe(true);
+  expect(jest.isMockFunction(global.fetch)).toBe(true);
+});
+```
+
+## Test Organization
+
+### File Structure
+- Mirror source structure with `.test.js` suffix
+- Group related tests in describe blocks
+- Use descriptive test names that explain the behavior being tested
+
+### Test Naming
+- Use "should [behavior] when [condition]" format
+- Include test mode in description when relevant
+- Be specific about expected outcomes
+
+Example:
+```javascript
+it('should call native implementation when in native mode', () => {
+  // Test implementation
+});
+
+it('should queue events when in JavaScript mode', () => {
+  // Test implementation
+});
+
+it('should respect opt-out status and skip tracking', async () => {
+  // Test implementation  
+});
+```

package/.github/prompts/add-feature.prompt.md

@@ -0,0 +1,186 @@
+---
+mode: 'agent'
+tools: ['codebase', 'terminal']
+description: 'Implement a new feature following dual-implementation patterns'
+---
+
+Implement a new feature named "${input:featureName}" in the Mixpanel React Native library.
+
+## Feature Implementation Workflow
+
+Follow this EXACT sequence for all new features:
+
+### 1. Design Public API
+- Update `index.d.ts` with TypeScript definitions
+- Add method to main Mixpanel class in `index.js` with comprehensive input validation using StringHelper/ObjectHelper
+- Use token as first parameter for all operations
+- Follow camelCase naming convention
+
+### 2. Implement iOS Native Version
+- Add method to `ios/MixpanelReactNative.swift`
+- Use `@objc` decorator with Promise pattern (resolver/rejecter)
+- Include error handling for missing instances
+- Use MixpanelTypeHandler for type conversion
+- Call through to official Mixpanel iOS SDK
+
+### 3. Implement Android Native Version  
+- Add method to `android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java`
+- Use `@ReactMethod` annotation with synchronized access
+- Use ReactNativeHelper for type conversion
+- Include comprehensive error handling
+
+### 4. Implement JavaScript Fallback
+- Add method to `javascript/mixpanel-main.js`
+- Check opt-out status before ANY operation
+- Add comprehensive logging with token context
+- Use existing infrastructure (super properties, persistent storage)
+- Follow async/await pattern consistently
+
+### 5. Add Comprehensive Tests
+- Test input validation for all parameter combinations
+- Test native mode implementation calls
+- Test JavaScript mode queue management
+- Test opt-out behavior
+- Test error handling scenarios
+- Update native module mocks in `__tests__/jest_setup.js`
+
+### 6. Update Documentation
+- Add JSDoc comments with examples
+- Update sample applications in `Samples/` directory
+- Test integration in sample apps
+
+## Requirements Checklist
+
+### API Design
+- [ ] TypeScript definitions added to `index.d.ts`
+- [ ] Method added to main Mixpanel class with validation
+- [ ] Token-based architecture followed
+- [ ] Input validation using Helper classes
+
+### Native Implementations
+- [ ] iOS method with @objc decorator and Promise pattern
+- [ ] Android method with @ReactMethod and synchronization
+- [ ] Error handling for missing instances
+- [ ] Type conversion using helper utilities
+
+### JavaScript Implementation
+- [ ] Method added to `javascript/mixpanel-main.js`
+- [ ] Opt-out status checked before operations
+- [ ] Comprehensive token-scoped logging
+- [ ] Async/await pattern followed
+
+### Testing
+- [ ] Input validation tests for all parameters
+- [ ] Native mode tests with mock verification
+- [ ] JavaScript mode tests with queue validation
+- [ ] Opt-out behavior testing
+- [ ] Error handling scenario coverage
+- [ ] Native module mocks updated
+
+### Integration
+- [ ] Sample applications updated and tested
+- [ ] iOS pod install tested
+- [ ] Android gradle build tested
+- [ ] Documentation with examples added
+
+## Key Patterns to Follow
+
+### Input Validation Pattern
+```javascript
+if (!StringHelper.isValid(parameter)) {
+  StringHelper.raiseError("parameter");
+}
+if (!ObjectHelper.isValidOrUndefined(properties)) {
+  ObjectHelper.raiseError("properties");
+}
+```
+
+### Implementation Routing Pattern
+```javascript
+// Route to appropriate implementation
+this.mixpanelImpl.methodName(this.token, parameter, properties);
+```
+
+### iOS Native Pattern
+```swift
+@objc
+func methodName(_ token: String,
+                parameter: String,
+                resolver resolve: RCTPromiseResolveBlock,
+                rejecter reject: RCTPromiseRejectBlock) -> Void {
+    let instance = MixpanelReactNative.getMixpanelInstance(token)
+    guard let instance = instance else {
+        reject("Instance Error", "Failed to get Mixpanel instance", nil)
+        return
+    }
+    
+    instance.nativeMethod(parameter: parameter)
+    resolve(nil)
+}
+```
+
+### Android Native Pattern
+```java
+@ReactMethod
+public void methodName(final String token, 
+                      String parameter, 
+                      Promise promise) throws JSONException {
+    MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+    if (instance == null) {
+        promise.reject("Instance Error", "Failed to get Mixpanel instance");
+        return;
+    }
+    
+    synchronized (instance) {
+        instance.nativeMethod(parameter);
+        promise.resolve(null);
+    }
+}
+```
+
+### JavaScript Implementation Pattern
+```javascript
+async methodName(token, parameter) {
+  if (this.mixpanelPersistent.getOptedOut(token)) {
+    MixpanelLogger.log(token, `User has opted out, skipping methodName`);
+    return;
+  }
+
+  MixpanelLogger.log(token, `Calling methodName with parameter: ${parameter}`);
+  // Implementation logic here
+}
+```
+
+### Test Pattern
+```javascript
+describe('Feature Name', () => {
+  describe('Native Mode', () => {
+    it('should call native implementation', () => {
+      mixpanel.methodName('parameter');
+      expect(MixpanelReactNative.methodName).toHaveBeenCalledWith(
+        'test-token', 'parameter'
+      );
+    });
+  });
+
+  describe('JavaScript Mode', () => {
+    it('should implement JavaScript fallback', async () => {
+      await mixpanel.methodName('parameter');
+      // Verify JavaScript implementation behavior
+    });
+  });
+});
+```
+
+## Testing Instructions
+
+After implementation:
+1. Run full test suite: `npm test`
+2. Test in iOS sample app: `cd Samples/SimpleMixpanel && npx react-native run-ios`
+3. Test in Android sample app: `cd Samples/SimpleMixpanel && npx react-native run-android`
+4. Verify both native and JavaScript modes work correctly
+
+Reference our architecture guide: `claude/architecture/system-design.md`
+Use our standard patterns: `.github/copilot-instructions.md`
+
+Ensure the feature maintains the library's reliability, performance, and compatibility standards while following all established architectural patterns.