mixpanel-react-native 3.0.9 → 3.1.1

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(ls:*)"
+    ]
+  },
+  "enableAllProjectMcpServers": false
+}

package/.cursor/rules/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Cursor Rules Changelog
+
+## [2025-05-30] - Context Synchronization Update
+
+### Added
+- Conditional property inclusion pattern in `always/error-handling.mdc` - Prevents sending null values to API
+- Gzip compression support documentation in `components/native-modules.mdc` - Documents new init() parameter
+- Evolution notices for patterns that have been refined based on recent codebase changes
+
+### Changed
+- `always/error-handling.mdc` - Updated UUID generation pattern to prefer expo-crypto with fallback
+- `components/storage-operations.mdc` - Updated AsyncStorageAdapter to handle both ES6 and CommonJS exports
+- `always/core-conventions.mdc` - Added note about consistent import spacing
+- `components/javascript-implementation.mdc` - Updated identity queue management to use core module method
+
+### Deprecated
+- None in this update
+
+### Migration Notes
+Teams should be aware of these evolved patterns:
+1. **UUID Generation**: expo-crypto is now preferred for Expo environments with uuid.v4() as fallback
+2. **Storage Module**: AsyncStorage module resolution now handles different export formats
+3. **API Payloads**: Use conditional spread operator to exclude null values
+4. **Gzip Support**: Optional compression available in init() method
+
+### Impact Summary
+- Improved Expo compatibility through better UUID generation
+- More reliable storage initialization across different bundler configs
+- Cleaner API payloads by excluding null values
+- Better alignment with current codebase patterns

package/.cursor/rules/README.md

@@ -0,0 +1,221 @@
+# Cursor Rules for mixpanel-react-native
+
+This directory contains Cursor MDC rules that actively guide AI assistance when working with the mixpanel-react-native codebase. These rules complement the comprehensive Claude Code context files and transform discovered patterns into actionable behavioral guidance.
+
+## 🎯 Philosophy
+
+The Cursor rules serve a different purpose than the Claude Code context:
+
+- **Claude Code Context**: Comprehensive reference documentation for deep understanding
+- **Cursor Rules**: Active behavioral guidance that shapes every code generation
+
+Think of Claude Code as your library, and Cursor rules as your active coach that guides decisions in real-time.
+
+## 🏗️ Rule Architecture
+
+### Always Rules (`always/`)
+Applied to EVERY file, ensuring fundamental patterns are never violated:
+
+- **`core-conventions.mdc`**: Essential naming, import organization, token-based architecture
+- **`architecture-principles.mdc`**: Dual implementation, graceful degradation, factory patterns
+- **`error-handling.mdc`**: Input validation, silent failures, defensive programming
+
+**Total context impact**: ~300 lines - designed to fit in limited context windows
+
+### Component Rules (`components/`)
+Auto-attached based on file patterns, providing context-specific guidance:
+
+- **`native-modules.mdc`**: iOS Swift and Android Java bridge patterns (`ios/**/*.swift`, `android/**/*.java`)
+- **`javascript-implementation.mdc`**: JS fallback patterns (`javascript/**/*.js`)
+- **`storage-operations.mdc`**: AsyncStorage and persistence patterns (`**/*storage*.js`, `**/*persistent*.js`)
+- **`network-operations.mdc`**: Retry logic and request patterns (`**/*network*.js`)
+
+### Testing Rules (`testing/`)
+Applied to test files for comprehensive testing strategies:
+
+- **`test-patterns.mdc`**: Dual-mode testing, validation patterns (`__tests__/**/*.js`, `**/*.test.js`)
+
+### Workflow Rules (`workflows/`)
+Agent-requested rules for complex procedures:
+
+- **`new-feature.mdc`**: Step-by-step feature addition workflow
+- **`debugging.mdc`**: Systematic diagnostic approach
+- **`testing-workflow.mdc`**: Comprehensive testing methodology
+
+## 🔄 Rule Usage Patterns
+
+### For New Team Members
+1. Always rules provide immediate guardrails for any file they touch
+2. Component rules guide technology-specific patterns automatically
+3. Workflow rules available when tackling complex tasks
+
+### For Feature Development
+1. Always rules ensure architectural consistency
+2. Native module rules guide iOS/Android bridge implementation
+3. JavaScript implementation rules ensure fallback compatibility
+4. New feature workflow provides step-by-step guidance
+
+### For Debugging
+1. Always rules maintain code quality during fixes
+2. Component rules provide context-specific debugging patterns
+3. Debugging workflow offers systematic diagnostic approach
+
+### For Code Review
+1. Always rules catch fundamental violations
+2. Component rules verify technology-specific patterns
+3. Testing rules ensure comprehensive coverage
+
+## 📊 Rule Categorization Logic
+
+### Always Apply (Critical Mass: ~300 lines)
+Patterns that apply to literally every file and represent non-negotiable conventions:
+- Token-based architecture (every operation must include token)
+- Error handling philosophy (Helper classes, graceful degradation)
+- Naming conventions (kebab-case files, camelCase variables)
+- Import organization (external first, then grouped internal)
+
+### Auto-Attached (Context-Sensitive)
+Patterns specific to file types or technologies:
+- Native bridge patterns only apply to iOS/Android files
+- Queue management only applies to JavaScript implementation
+- Storage patterns only apply to persistence-related files
+
+### Agent-Requested (Complex Workflows)
+Multi-step procedures that are too complex for always-apply:
+- Feature addition requires multiple files and platforms
+- Debugging requires systematic investigation
+- Testing requires comprehensive setup and validation
+
+## 🔗 Integration with Claude Code Context
+
+### When to Use Cursor Rules
+- **Real-time coding**: Rules guide every keystroke and suggestion
+- **Code generation**: Rules ensure generated code follows patterns
+- **Quick decisions**: Rules provide immediate answers without research
+
+### When to Consult Claude Code Context
+- **Deep understanding**: Need to understand why patterns exist
+- **Complex architecture decisions**: Need full system context
+- **Learning the codebase**: Need comprehensive overview
+- **Debugging complex issues**: Need detailed diagnostic procedures
+
+### Complementary Relationship
+```
+┌─────────────────┐    ┌─────────────────┐
+│   Cursor Rules  │    │ Claude Context  │
+│   (Behavioral)  │    │ (Knowledge)     │
+├─────────────────┤    ├─────────────────┤
+│ • What to do    │    │ • Why it works  │
+│ • How to code   │    │ • How it fits   │
+│ • Enforce rules │    │ • What options  │
+│ • Guide style   │    │ • Understand    │
+└─────────────────┘    └─────────────────┘
+         │                       │
+         └───────────┬───────────┘
+                     │
+            ┌─────────────────┐
+            │   AI Assistant  │
+            │   Effectiveness │
+            └─────────────────┘
+```
+
+## 🎨 Rule Design Principles
+
+### 1. Actionable Over Descriptive
+Rules tell you what to do, not just what exists:
+```markdown
+❌ "The codebase uses token-based architecture"
+✅ "EVERY operation MUST include token as first parameter"
+```
+
+### 2. Specific Over Generic
+Rules provide concrete patterns, not abstract advice:
+```markdown
+❌ "Handle errors gracefully"
+✅ "ALWAYS wrap storage operations in try-catch with return null fallback"
+```
+
+### 3. Contextual Over Universal
+Rules apply when relevant, not everywhere:
+```markdown
+✅ Native module rules only apply to ios/**/*.swift and android/**/*.java
+✅ Testing rules only apply to __tests__/**/*.js
+```
+
+### 4. Concise Over Comprehensive
+Rules fit in limited context windows:
+```markdown
+✅ Always rules total ~300 lines
+✅ Component rules focus on essential patterns only
+```
+
+## 🚀 Quick Start Guide
+
+### For Immediate Use
+1. Start coding any file - always rules provide immediate guidance
+2. Work on iOS/Android files - native module rules auto-apply
+3. Work on JavaScript files - implementation rules auto-apply
+
+### For Complex Tasks
+1. Request "new feature workflow" for adding functionality
+2. Request "debugging workflow" for systematic issue investigation
+3. Request "testing workflow" for comprehensive validation
+
+### For Learning
+1. Read through always rules to understand fundamental patterns
+2. Explore component rules for technology-specific approaches
+3. Reference workflow rules for complex procedures
+
+## 🔧 Rule Maintenance
+
+### When to Update Rules
+- **New architectural patterns** discovered in the codebase
+- **Technology integrations** change (new React Native versions)
+- **Testing strategies** evolve
+- **Common mistakes** identified in code reviews
+
+### How to Update Rules
+1. **Discover pattern** in actual codebase usage
+2. **Validate pattern** follows established architecture
+3. **Determine rule type** (always vs component vs workflow)
+4. **Update relevant rule file** with specific, actionable guidance
+5. **Test rule effectiveness** in practice
+
+### Rule Quality Metrics
+- **Specificity**: Rules provide concrete, actionable guidance
+- **Coverage**: Rules apply to appropriate file patterns without over-matching
+- **Consistency**: Rules align with discovered codebase patterns
+- **Effectiveness**: Rules prevent common mistakes and guide good practices
+
+## 🎯 Success Indicators
+
+### Effective Rules Enable
+- **Consistent code generation** following established patterns
+- **Faster development** with guided decision-making
+- **Fewer architectural mistakes** through active enforcement
+- **Better code quality** through pattern reinforcement
+
+### Rule Health Indicators
+- **Rules stay current** with codebase evolution
+- **Generated code follows** discovered patterns
+- **New team members** produce consistent code
+- **Common patterns** are automatically applied
+
+## 📋 Rule Reference Quick Guide
+
+### Essential Always Rules
+- `core-conventions.mdc`: Naming, imports, token architecture
+- `architecture-principles.mdc`: Dual implementation, graceful degradation
+- `error-handling.mdc`: Validation, silent failures, defensive programming
+
+### Key Component Rules
+- `native-modules.mdc`: iOS @objc and Android @ReactMethod patterns
+- `javascript-implementation.mdc`: Factory functions, async/await, queuing
+- `storage-operations.mdc`: AsyncStorage wrapper, fallbacks, token-scoped keys
+
+### Critical Workflows
+- `new-feature.mdc`: API → iOS → Android → JS → Tests workflow
+- `debugging.mdc`: Implementation mode → logging → systematic diagnosis
+- `testing-workflow.mdc`: Validation → native mode → JS mode → integration
+
+This rule system transforms the comprehensive Claude Code knowledge into active behavioral guidance, ensuring consistent, high-quality code generation that follows established patterns and prevents common mistakes.

package/.cursor/rules/always/architecture-principles.mdc

@@ -0,0 +1,157 @@
+---
+description: Fundamental architectural principles and patterns for dual-implementation system
+alwaysApply: true
+---
+
+# Architecture Principles
+
+## Dual Implementation Strategy (MANDATORY)
+EVERY feature MUST support both native and JavaScript modes:
+
+### Implementation Router Pattern
+```javascript
+// ALWAYS follow this pattern in public API
+if (useNative && MixpanelReactNative) {
+  this.mixpanelImpl = MixpanelReactNative;
+} else {
+  if (useNative) {
+    console.warn("MixpanelReactNative not available; using JavaScript mode...");
+  }
+  this.mixpanelImpl = new MixpanelMain(token, trackAutomaticEvents, storage);
+}
+```
+
+## Factory Function Pattern (REQUIRED)
+Core modules MUST use dependency injection for testability:
+
+```javascript
+// Correct: Factory with injected dependencies
+export const MixpanelCore = (storage) => {
+  const mixpanelPersistent = MixpanelPersistent.getInstance(storage);
+  return { initialize, track, flush };
+};
+
+// Wrong: Direct dependencies
+import storage from './storage'; // Don't do this
+```
+
+## Singleton Pattern with Lazy Initialization
+Shared resources (config, storage) MUST use singleton pattern:
+
+```javascript
+// Correct pattern for singletons
+export const MixpanelQueueManager = (() => {
+  let _instance;
+  
+  const getInstance = () => {
+    if (!_instance) {
+      _instance = { /* initialize */ };
+    }
+    return _instance;
+  };
+  
+  return { getInstance };
+})();
+```
+
+## Graceful Degradation (CRITICAL)
+ALWAYS provide fallbacks, NEVER let the system fail completely:
+
+### Native → JavaScript Fallback
+```javascript
+// Try native first, fall back to JS
+if (nativeModule && nativeModule.method) {
+  return nativeModule.method(params);
+} else {
+  return jsImplementation(params);
+}
+```
+
+### Storage → In-Memory Fallback
+```javascript
+// Try AsyncStorage, fall back to in-memory
+try {
+  this.storage = require("@react-native-async-storage/async-storage");
+} catch {
+  console.error("[Mixpanel] Falling back to in-memory storage");
+  this.storage = new InMemoryStorage();
+}
+```
+
+## Token-Based Multi-Tenancy (FUNDAMENTAL)
+ALL state MUST be scoped by token for multi-project support:
+
+```javascript
+// Correct: Token-scoped state
+this._superProperties = {};  // Structure: {token1: {props}, token2: {props}}
+this._identity = {};         // Structure: {token1: {id}, token2: {id}}
+
+// Correct: Token-scoped operations
+getSuperProperties(token) {
+  return this._superProperties[token] || {};
+}
+
+// Wrong: Global state
+this.superProperties = {};   // Don't share across tokens
+```
+
+## Write-Through Caching Pattern
+ALWAYS maintain both memory cache AND persistent storage:
+
+```javascript
+// Correct: Update both cache and storage
+updateSuperProperties(token, properties) {
+  // Update in-memory cache
+  this._superProperties[token] = {...properties};
+  
+  // Persist to storage
+  this.persistSuperProperties(token);
+}
+```
+
+## Queue-Based Processing
+ALL data operations MUST use queuing for reliability:
+
+```javascript
+// Correct: Queue then batch process
+const enqueue = async (token, type, data) => {
+  _queues[token][type].push(data);
+  await updateQueueInStorage(token, type);
+  
+  // Trigger processing if needed
+  if (_queues[token][type].length >= batchSize) {
+    processBatch(token, type);
+  }
+};
+```
+
+## Immutable State Updates
+ALWAYS use spread operators and minimize object creation:
+
+```javascript
+// Correct: Immutable updates
+const eventProperties = Object.freeze({
+  token,
+  time: Date.now(),
+  ...this.getMetaData(),
+  ...superProperties,
+  ...properties,
+  ...identityProps,
+});
+
+// Correct: Only create objects when necessary
+if (updateDistinctId || updateDeviceId || updateUserId) {
+  updated = { ...record }; // Shallow copy only if needed
+}
+```
+
+## Layer Separation
+Maintain clear separation between layers:
+
+1. **Public API**: Validation and routing only
+2. **Implementation**: Platform-specific optimization  
+3. **Core Processing**: Shared business logic
+4. **Persistence**: State management
+5. **Infrastructure**: Queue/network/storage
+
+NEVER bypass layers or create circular dependencies.

package/.cursor/rules/always/core-conventions.mdc

@@ -0,0 +1,62 @@
+---
+description: Essential naming conventions and structural patterns that apply to all files
+alwaysApply: true
+---
+
+# Core Conventions
+
+## File Naming
+- Use kebab-case for all JavaScript files: `mixpanel-core.js`, `mixpanel-queue.js`
+- Prefix all internal modules with `mixpanel-` for consistency
+- Use descriptive names reflecting single responsibility
+
+## Variable Naming
+- camelCase for standard variables: `mixpanelImpl`, `trackAutomaticEvents`
+- SCREAMING_SNAKE_CASE for constants: `DEFAULT_OPT_OUT`, `PARAMS.TOKEN`
+- Leading underscore for private variables: `_queues`, `_shouldLog`
+
+## Function Naming
+- Verb-first naming: `initialize`, `track`, `flush`, `addToMixpanelQueue`
+- Boolean predicates: `isValidAndSerializable`, `hasOptedOutTracking`
+- Event handlers: `handleBatchError`
+
+## Import Organization (REQUIRED)
+```javascript
+// 1. External dependencies first (with consistent spacing)
+import { Platform } from "react-native";
+import packageJson from "./package.json";
+
+// 2. Internal modules second, grouped by purpose
+import { MixpanelCore } from "./mixpanel-core";
+import { MixpanelType } from "./mixpanel-constants";
+import { MixpanelConfig } from "./mixpanel-config";
+
+// ⚠️ Style Note [Updated: 2025-05-30]: Use consistent destructuring with spaces
+// ✅ Correct: import { MixpanelCore } from "./mixpanel-core";
+// ❌ Incorrect: import {MixpanelCore} from "./mixpanel-core";
+```
+
+## Export Patterns
+- Named exports for utilities: `export class MixpanelLogger`
+- Default exports for main classes: `export default class MixpanelMain`
+- Factory function exports: `export const MixpanelCore = (storage) => {...}`
+
+## Token-Based Architecture (CRITICAL)
+- EVERY operation MUST include token as first parameter
+- ALL storage keys MUST be token-scoped: `MIXPANEL_${token}_${type}_${field}`
+- ALL configuration MUST be per-token for multi-project support
+
+Example function signatures:
+```javascript
+const flush = async (token) => { /* ... */ };
+const track = async (token, eventName, properties) => { /* ... */ };
+```
+
+## Logging Patterns (REQUIRED)
+- ALL logs MUST include token context
+- ALL logs MUST use [Mixpanel] prefix for filtering
+- ALL logs MUST respect per-token logging settings
+
+```javascript
+MixpanelLogger.log(token, `Track '${eventName}' with properties`, properties);
+```