mixpanel-react-native 3.1.2 → 3.1.3

package/.claude/settings.local.json

@@ -2,7 +2,18 @@
   "permissions": {
     "allow": [
       "Bash(find:*)",
-      "Bash(ls:*)"
+      "Bash(ls:*)",
+      "mcp__github__list_dependabot_alerts",
+      "Bash(npm ls:*)",
+      "Bash(npm test)",
+      "Bash(npm test:*)",
+      "mcp__github__get_pull_request",
+      "mcp__github__get_issue",
+      "mcp__vscode__get_diagnostics_code",
+      "mcp__vscode__search_symbols_code",
+      "mcp__vscode__get_document_symbols_code",
+      "mcp__vscode__get_symbol_definition_code",
+      "WebFetch(domain:docs.anthropic.com)"
     ]
   },
   "enableAllProjectMcpServers": false

package/.github/copilot-instructions.md

@@ -1,198 +1,134 @@
-# Essential Coding Standards for Mixpanel React Native
+# Mixpanel React Native SDK - Copilot Instructions
 
-> Critical patterns preventing errors. Every instruction has proven impact.
+## Repository Overview
+This is the official Mixpanel React Native SDK, a wrapper around native iOS and Android SDKs for analytics tracking. It supports React Native apps, Expo, and React Native for Web (via JavaScript mode).
 
-## 🔒 Security & Validation
+**Type:** React Native library (npm package)  
+**Languages:** JavaScript (main), Swift (iOS native), Java (Android native)  
+**Version:** 3.1.2  
+**Minimum React Native:** 0.6+
 
-**ALWAYS validate inputs with Helper classes**:
-```javascript
-if (!StringHelper.isValid(eventName)) {
-  StringHelper.raiseError(PARAMS.EVENT_NAME);
-}
-if (!ObjectHelper.isValidOrUndefined(properties)) {
-  ObjectHelper.raiseError(PARAMS.PROPERTIES);
-}
-```
-
-**ALWAYS check opt-out before operations**:
-```javascript
-if (this.mixpanelPersistent.getOptedOut(token)) {
-  MixpanelLogger.log(token, `User opted out, skipping ${operation}`);
-  return;
-}
-```
+## Quick Reference - Build & Test Commands
 
-## ⚡ Error Handling Patterns
-
-**Storage operations - Silent failure with defaults**:
-```javascript
-async getItem(key) {
-  try {
-    return await this.storage.getItem(key);
-  } catch {
-    MixpanelLogger.error("error getting item from storage");
-    return null; // ALWAYS return usable default
-  }
-}
-```
+### Primary Commands (Always Run in This Order)
+```bash
+# 1. Install dependencies (ALWAYS run first after checkout)
+npm install
 
-**Network operations - Retry with exponential backoff**:
-```javascript
-const sendRequest = async ({...params, retryCount = 0}) => {
-  try {
-    return await fetch(url, options);
-  } 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});
-    }
-    throw error;
-  }
-};
+# 2. Run tests
+npm test
 ```
 
-**UUID generation - Expo fallback**:
-```javascript
-try {
-  deviceId = randomUUID(); // expo-crypto
-} catch (e) {
-  deviceId = uuid.v4();    // uuid package
-}
+### Validation Results
+- All 106 tests should pass across 6 test suites
+- Jest is the test framework with react-native preset
+
+## Project Architecture
+
+### Key Entry Points
+| File | Purpose |
+|------|---------|
+| `index.js` | Main SDK entry - exports `Mixpanel`, `People`, `MixpanelGroup` classes |
+| `index.d.ts` | TypeScript type definitions |
+| `package.json` | NPM package config, dependencies, Jest configuration |
+
+### Native Platform Code
+| Directory | Purpose |
+|-----------|---------|
+| `ios/` | Swift native bridge (`MixpanelReactNative.swift`) |
+| `android/` | Java native bridge (`android/src/main/java/com/mixpanel/reactnative/`) |
+
+### JavaScript Mode (Expo/Web Support)
+| File | Purpose |
+|------|---------|
+| `javascript/mixpanel-main.js` | Main JavaScript implementation |
+| `javascript/mixpanel-core.js` | Queue processing and event handling |
+| `javascript/mixpanel-persistent.js` | Storage and identity persistence |
+| `javascript/mixpanel-network.js` | API request handling |
+| `javascript/mixpanel-config.js` | Configuration management |
+| `javascript/mixpanel-queue.js` | Event queue management |
+| `javascript/mixpanel-storage.js` | AsyncStorage adapter |
+| `javascript/mixpanel-logger.js` | Logging utilities |
+| `javascript/mixpanel-utils.js` | Helper utilities |
+| `javascript/mixpanel-constants.js` | Constants (MixpanelType enum) |
+
+### Test Files
+| File | Tests |
+|------|-------|
+| `__tests__/index.test.js` | Native bridge integration tests |
+| `__tests__/main.test.js` | JavaScript mode MixpanelMain tests |
+| `__tests__/core.test.js` | Queue and core processing tests |
+| `__tests__/persistent.test.js` | Persistence layer tests |
+| `__tests__/queue.test.js` | Queue management tests |
+| `__tests__/network.test.js` | Network request tests |
+| `__tests__/jest_setup.js` | Mock setup for react-native and dependencies |
+
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `MixpanelReactNative.podspec` | iOS CocoaPods spec (Swift 5.0, iOS 11.0+) |
+| `android/build.gradle` | Android config (compileSdk 34, minSdk 21, Gradle 8.1.0) |
+| `react-native.config.js` | React Native auto-linking configuration |
+
+## CI/CD Workflows
+
+### `.github/workflows/node.js.yml` (Primary CI)
+- Runs on: push/PR to master
+- Jobs: `test_main_code`, `test_android`, `test_ios`
+- Node version: 18.x
+- Steps: `npm install` → `npm test`
+
+### Test Requirements
+- Tests use mocked react-native modules (`__tests__/jest_setup.js`)
+- AsyncStorage, uuid, and react-native-get-random-values are mocked
+
+## Development Guidelines
+
+### Making Code Changes
+1. JavaScript/TypeScript changes: Modify files in root or `javascript/` directory
+2. iOS changes: Modify `.swift` files in `ios/` directory
+3. Android changes: Modify `.java` files in `android/src/main/java/`
+4. After changes: Always run `npm test` to verify
+
+### Adding Tests
+- Place tests in `__tests__/` directory with `.test.js` suffix
+- Use existing mock setup from `jest_setup.js`
+- Follow patterns in existing test files
+
+### Type Definitions
+- Update `index.d.ts` when adding/modifying public API methods
+- Ensure TypeScript types match runtime behavior
+
+## Dependencies
+
+### Runtime Dependencies
+- `@react-native-async-storage/async-storage` - Persistence (JavaScript mode)
+- `react-native-get-random-values` - UUID polyfill
+- `uuid@3.3.2` - UUID generation
+
+### Native SDK Dependencies
+- iOS: `Mixpanel-swift@5.1.0`
+- Android: `mixpanel-android@8.2.0`
+
+## Sample Apps
+Located in `Samples/` directory:
+- `SimpleMixpanel` - Minimal integration example (used in CI)
+- `MixpanelDemo` - Full API demonstration
+- `ContextAPIMixpanel` - React Context integration
+- `MixpanelExpo` - Expo project example
+- `MixpanelExample`, `MixpanelStarter` - Additional examples
+
+## Generating Documentation
+```bash
+./generate_docs.sh  # Uses jsdoc, outputs to docs/
 ```
 
-## 🏗️ Architecture Rules
-
-**Token-based multi-tenancy (MANDATORY)**:
-```javascript
-// EVERY operation includes token as first parameter
-const track = async (token, eventName, properties) => { /* ... */ };
-const flush = async (token) => { /* ... */ };
-
-// ALL storage keys are token-scoped
-const key = `MIXPANEL_${token}_${type}_${field}`;
-```
-
-**Dual implementation routing**:
-```javascript
-if (useNative && MixpanelReactNative) {
-  this.mixpanelImpl = MixpanelReactNative;
-} else {
-  if (useNative) {
-    console.warn("MixpanelReactNative not available; using JavaScript mode...");
-  }
-  this.mixpanelImpl = new MixpanelMain(token, trackAutomaticEvents, storage);
-}
-```
-
-**Queue-based processing**:
-```javascript
-const enqueue = async (token, type, data) => {
-  _queues[token][type].push(data);
-  await updateQueueInStorage(token, type);
-  
-  if (_queues[token][type].length >= batchSize) {
-    processBatch(token, type);
-  }
-};
-```
-
-## 📱 Native Module Patterns
-
-**iOS Swift**:
-```swift
-@objc
-func methodName(_ token: String,
-                parameter: String,
-                resolver resolve: RCTPromiseResolveBlock,
-                rejecter reject: RCTPromiseRejectBlock) -> Void {
-    guard let instance = MixpanelReactNative.getMixpanelInstance(token) else {
-        reject("Instance Error", "Failed to get Mixpanel instance", nil)
-        return
-    }
-    instance.nativeMethod(parameter: parameter)
-    resolve(nil)
-}
-```
-
-**Android Java**:
-```java
-@ReactMethod
-public void methodName(String token, String parameter, Promise promise) {
-    MixpanelAPI instance = MixpanelAPI.getInstance(mReactContext, token, true);
-    if (instance == null) {
-        promise.reject("Instance Error", "Failed to get Mixpanel instance");
-        return;
-    }
-    synchronized (instance) {
-        instance.nativeMethod(parameter);
-        promise.resolve(null);
-    }
-}
-```
-
-## 🧹 Data Handling
-
-**Conditional property inclusion - prevent null values**:
-```javascript
-const profileData = {
-  $token: token,
-  $time: Date.now(),
-  ...action,
-  ...(distinctId != null && { $distinct_id: distinctId }),
-  ...(deviceId != null && { $device_id: deviceId }),
-  ...(userId != null && { $user_id: userId }),
-};
-```
-
-**Storage module resolution**:
-```javascript
-const storageModule = require("@react-native-async-storage/async-storage");
-if (storageModule.default) {
-  this.storage = storageModule.default;
-} else {
-  this.storage = storageModule;
-}
-```
-
-## 🧪 Testing Requirements
-
-**Test both modes for every feature**:
-```javascript
-describe('Feature', () => {
-  it('Native mode', () => {
-    mixpanel = new Mixpanel('token', true, true); // Force native
-    mixpanel.track('Event', {prop: 'value'});
-    expect(MixpanelReactNative.track).toHaveBeenCalled();
-  });
-
-  it('JavaScript mode', () => {
-    mixpanel = new Mixpanel('token', true, false); // Force JS
-    mixpanel.track('Event', {prop: 'value'});
-    expect(MixpanelQueueManager.enqueue).toHaveBeenCalled();
-  });
-});
-```
+## Important Notes
 
-## 📋 Quick Reference
-
-### Naming
-- Files: `mixpanel-{feature}.js` (kebab-case)
-- Variables: `camelCase`
-- Constants: `SCREAMING_SNAKE_CASE`
-- Functions: verb-first (`initialize`, `track`, `flush`)
-
-### Key Files
-- `index.js` - Public API with validation
-- `javascript/mixpanel-main.js` - JS implementation
-- `javascript/mixpanel-core.js` - Shared logic
-- `ios/MixpanelReactNative.swift` - iOS native
-- `android/.../MixpanelReactNativeModule.java` - Android native
-
-### Critical Patterns
-- Token as first parameter everywhere
-- Validate all inputs with Helper classes
-- Silent failure for infrastructure errors
-- Check opt-out before any operation
-- Test both native and JS modes
-- Log with token context and [Mixpanel] prefix
+1. **Trust these instructions first** - Only perform additional searches if information here is incomplete or incorrect
+2. **npm install is required** before running tests
+3. **All 106 tests must pass** before submitting changes
+4. **Mocks are essential** - Tests rely on mocked react-native modules; do not remove mocks from `jest_setup.js`
+5. **Two modes of operation**: Native mode (iOS/Android) and JavaScript mode (Expo/Web)
+6. **API surface**: Changes to `index.js` require corresponding updates to `index.d.ts`

package/.github/dependabot.yml

@@ -0,0 +1,7 @@
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: "npm" # Or "yarn"
+    directory: "/" # Tells Dependabot to scan root directory only
+    schedule:
+      interval: "daily"

package/.github/workflows/node.js.yml

@@ -15,69 +15,113 @@ jobs:
     strategy:
       matrix:
         node-version: [18.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm install
       - run: npm test
 
   test_android:
-    runs-on: macos-13
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         node-version: [18.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+        api-level: [34]
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
+
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-      - uses: actions/setup-java@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
         with:
-          distribution: "temurin" # See 'Supported distributions' for available options
+          distribution: "temurin"
           java-version: "17"
-      - run: npm install
-      - run: npm install -g react-native-cli
-      - run: npm i react-native-gradle-plugin
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Install dependencies
+        run: |
+          npm install
+          npm install -g react-native-cli
+          npm i react-native-gradle-plugin
+
       - name: Test Integration - Install dependencies
         working-directory: ./Samples/SimpleMixpanel
         run: yarn install
-      - name: Setup Android
-        uses: reactivecircus/android-emulator-runner@v2.32.0
+
+      - name: Enable KVM
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - name: AVD cache
+        uses: actions/cache@v4
+        id: avd-cache
         with:
-          api-level: 34
-          profile: Nexus 5X
-          arch: x86_64
-          working-directory: ./Samples/SimpleMixpanel/android
-          script: ./gradlew
-      - name: Test Android
-        uses: reactivecircus/android-emulator-runner@v2.32.0
+          path: |
+            ~/.android/avd/*
+            ~/.android/adb*
+          key: avd-${{ matrix.api-level }}-google-apis-x86_64-nexus5x
+
+      - name: Create AVD and generate snapshot for caching
+        if: steps.avd-cache.outputs.cache-hit != 'true'
+        uses: reactivecircus/android-emulator-runner@v2
+        env:
+          GRADLE_OPTS: -Xmx4096m -Dorg.gradle.daemon=false
+          JAVA_OPTS: -Xmx4096m
         with:
-          api-level: 34
+          api-level: ${{ matrix.api-level }}
+          target: google_apis
+          arch: x86_64
           profile: Nexus 5X
+          force-avd-creation: false
+          emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
+          disable-animations: false
+          working-directory: ./Samples/SimpleMixpanel
+          script: echo "Generated AVD snapshot for caching."
+
+      - name: Run Android Tests
+        uses: reactivecircus/android-emulator-runner@v2
+        env:
+          GRADLE_OPTS: -Xmx4096m -Dorg.gradle.daemon=false
+          JAVA_OPTS: -Xmx4096m
+        with:
+          api-level: ${{ matrix.api-level }}
+          target: google_apis
           arch: x86_64
+          profile: Nexus 5X
+          force-avd-creation: false
+          emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
+          disable-animations: true
+          emulator-boot-timeout: 900
           working-directory: ./Samples/SimpleMixpanel
-          script: react-native run-android
+          script: |
+            echo "org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -XX:+HeapDumpOnOutOfMemoryError" >> android/gradle.properties
+            echo "org.gradle.daemon=false" >> android/gradle.properties
+            npx react-native run-android --no-packager
 
   test_ios:
     runs-on: macos-latest
     strategy:
       matrix:
         node-version: [18.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm install

package/.idea/dataSources/data_sources_history.xml

@@ -0,0 +1 @@
+<DataSourcesHistory />

package/.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-    "java.configuration.updateBuildConfiguration": "interactive"
+    "java.configuration.updateBuildConfiguration": "interactive",
+    "java.compile.nullAnalysis.mode": "automatic"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 #
 
+## [v3.1.3](https://github.com/mixpanel/mixpanel-react-native/tree/v3.1.3) (2025-12-15)
+
+### Fixes
+
+- Fix getUseIpAddressForGeolocation always returning true [\#316](https://github.com/mixpanel/mixpanel-react-native/pull/316)
+
+## [v3.2.0-beta.2](https://github.com/mixpanel/mixpanel-react-native/tree/v3.2.0-beta.2) (2025-11-07)
+
+## [v3.2.0-beta.1](https://github.com/mixpanel/mixpanel-react-native/tree/v3.2.0-beta.1) (2025-11-07)
+
+## [v3.2.0-beta.0](https://github.com/mixpanel/mixpanel-react-native/tree/v3.2.0-beta.0) (2025-11-07)
+
+#
+
 ## [v3.1.2](https://github.com/mixpanel/mixpanel-react-native/tree/v3.1.2) (2025-06-05)
 
 ### Fixes
@@ -529,6 +543,8 @@ This major release removes all remaining calls to Mixpanel's `/decide` API endpo
 
 
 
+
+
 
 
 

package/MixpanelReactNative.podspec

@@ -10,7 +10,7 @@ Pod::Spec.new do |s|
   s.license = package['license']
   s.author = { 'Mixpanel, Inc' => 'support@mixpanel.com' }
   s.homepage = package['homepage']
-  s.platform = :ios, "11.0"
+  s.platform = :ios, "12.0"
   s.swift_version = '5.0'
   s.source = { :git => "https://github.com/mixpanel/mixpanel-react-native.git", :tag => s.version }
   s.source_files = "ios/*.{swift,h,m}"
@@ -19,5 +19,5 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
 
   s.dependency "React-Core"
-  s.dependency "Mixpanel-swift", '5.1.0'
+  s.dependency "Mixpanel-swift", '5.1.3'
 end

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/.github/dependabot.yml

@@ -0,0 +1,7 @@
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: "npm" # Or "yarn"
+    directory: "/" # Tells Dependabot to scan root directory only
+    schedule:
+      interval: "daily"

package/Samples/MixpanelExpo/.yalc/mixpanel-react-native/CHANGELOG.md

@@ -1,5 +1,35 @@
 #
 
+## [v3.1.2](https://github.com/mixpanel/mixpanel-react-native/tree/v3.1.2) (2025-06-05)
+
+### Fixes
+
+- Expo dependencies are required for non-Expo apps [\#291](https://github.com/mixpanel/mixpanel-react-native/issues/291)
+- Use a react-native-get-random-values polyfill instead of expo-crypto [\#294](https://github.com/mixpanel/mixpanel-react-native/pull/294)
+
+#
+
+## [v3.1.1](https://github.com/mixpanel/mixpanel-react-native/tree/v3.1.1) (2025-06-02)
+
+### Enhancements
+
+- Add support for using Gzip compression [\#286](https://github.com/mixpanel/mixpanel-react-native/issues/286)
+
+### Fixes
+
+- Make expo-crypto an optional dependency [\#292](https://github.com/mixpanel/mixpanel-react-native/pull/292)
+- Add useGzipCompression parameter to types declaration file [\#290](https://github.com/mixpanel/mixpanel-react-native/pull/290)
+
+#
+
+## [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
@@ -489,6 +519,12 @@ This major release removes all remaining calls to Mixpanel's `/decide` API endpo
 
 
 
+
+
+
+
+
+