mixpanel-react-native 3.0.9 → 3.1.0

package/claude/context-map.md

@@ -0,0 +1,245 @@
+# Context Map: Knowledge Architecture Guide
+
+## Overview
+
+This document serves as your navigation guide to the comprehensive knowledge architecture built for the mixpanel-react-native codebase. Each resource is designed for specific use cases and depths of understanding.
+
+## 🎯 Quick Decision Tree
+
+**I need to...**
+
+- **🚀 Start immediately** → Read `CLAUDE.md` Quick Reference section
+- **🔍 Find a specific file** → Use `codebase-map.md` 
+- **🐛 Debug an issue** → Go to `workflows/03-debugging-issues.md`
+- **⚙️ Add a new feature** → Follow `workflows/01-adding-new-features.md`
+- **🧪 Write tests** → Use `workflows/02-testing-changes.md`
+- **🏗️ Understand architecture** → Read `architecture/system-design.md`
+- **📝 Learn coding patterns** → Study `discovered-patterns.md`
+- **🔧 Configure technologies** → Check `technologies/` directory
+
+## 📚 Knowledge Resources
+
+### 🎯 CLAUDE.md (Enhanced)
+**Purpose**: Your daily driver - immediate reference with discovered insights
+**When to use**: 
+- Starting any task
+- Quick commands and patterns
+- Implementation mode debugging
+- File location lookup
+
+**Key sections**:
+- Discovered Conventions (most important patterns)
+- Critical Workflows (3 most common tasks)
+- Quick Reference (commands, file locations, constants)
+
+### 🗺️ codebase-map.md
+**Purpose**: High-level structural understanding and file organization
+**When to use**:
+- New to the codebase
+- Looking for specific functionality
+- Understanding overall architecture
+- Planning changes across modules
+
+**Key insights**:
+- Executive summary of architectural strategy
+- File organization by purpose
+- Entry points and configuration
+- Sample application structure
+
+### 🧬 discovered-patterns.md  
+**Purpose**: Deep dive into coding conventions and design philosophies
+**When to use**:
+- Writing new code
+- Refactoring existing code
+- Understanding team conventions
+- Code review preparation
+
+**Key patterns**:
+- Naming conventions across all types
+- Error handling philosophy
+- Async patterns and performance optimization
+- Testing strategies
+
+## 🏗️ Architecture Resources
+
+### 📐 architecture/system-design.md
+**Purpose**: Complete system architecture with data flows and design decisions
+**When to use**:
+- Planning major changes
+- Understanding data flow
+- Performance optimization
+- Architectural decisions
+
+**Contains**:
+- High-level architecture diagrams (ASCII)
+- Detailed data flow documentation
+- Layer-by-layer system breakdown
+- Design trade-offs and reasoning
+
+## 🔧 Technology Resources
+
+### ⚛️ technologies/react-native.md
+**Purpose**: React Native integration patterns and native module bridging
+**When to use**:
+- Native module development
+- Bridge debugging
+- Platform-specific issues
+- Autolinking problems
+
+### 🧪 technologies/jest.md
+**Purpose**: Testing patterns and mocking strategies
+**When to use**:
+- Writing comprehensive tests
+- Setting up new test scenarios
+- Debugging test failures
+- Understanding mocking patterns
+
+### 💾 technologies/async-storage.md
+**Purpose**: Storage abstraction and persistence patterns
+**When to use**:
+- Storage-related issues
+- Performance optimization
+- Data migration scenarios
+- Cross-platform storage concerns
+
+## 🔄 Workflow Resources
+
+### 1️⃣ workflows/01-adding-new-features.md
+**Purpose**: Step-by-step guide for feature development
+**When to use**:
+- Adding any new functionality
+- Following dual-implementation pattern
+- Ensuring comprehensive testing
+- Maintaining compatibility
+
+**Covers**: API design → Native implementation → JS fallback → Testing → Documentation
+
+### 2️⃣ workflows/02-testing-changes.md
+**Purpose**: Complete testing methodology and patterns
+**When to use**:
+- Testing new features
+- Regression testing
+- CI/CD setup
+- Debugging test failures
+
+**Covers**: Unit tests → Integration tests → Manual testing → Performance testing
+
+### 3️⃣ workflows/03-debugging-issues.md
+**Purpose**: Systematic debugging approach for common problems
+**When to use**:
+- Any issue investigation
+- Silent failures
+- Performance problems
+- Platform-specific bugs
+
+**Covers**: Diagnostics → Native debugging → JS debugging → Network issues → Common scenarios
+
+## 🎨 Usage Patterns by Role
+
+### New Team Member
+1. Start with `codebase-map.md` for overview
+2. Read `discovered-patterns.md` to understand conventions  
+3. Use `CLAUDE.md` for daily reference
+4. Practice with `workflows/01-adding-new-features.md`
+
+### Debugging Developer
+1. Check `CLAUDE.md` Quick Reference first
+2. Use `workflows/03-debugging-issues.md` systematically
+3. Consult relevant `technologies/` docs for specific issues
+4. Reference `architecture/system-design.md` for complex problems
+
+### Feature Developer
+1. Plan with `workflows/01-adding-new-features.md`
+2. Reference `discovered-patterns.md` for coding style
+3. Test with `workflows/02-testing-changes.md`
+4. Use technology-specific docs as needed
+
+### Architecture Reviewer
+1. Review `architecture/system-design.md` for current state
+2. Check `discovered-patterns.md` for established conventions
+3. Use `codebase-map.md` to understand impact scope
+
+## 🔍 Depth Levels
+
+### Surface Level (5 minutes)
+- `CLAUDE.md` Quick Reference section
+- File location lookups
+- Common commands
+
+### Working Level (30 minutes)  
+- Complete `CLAUDE.md` read
+- Relevant workflow document
+- Technology-specific patterns
+
+### Deep Level (2 hours)
+- `architecture/system-design.md` complete study
+- `discovered-patterns.md` full analysis
+- Multiple workflow documents
+
+### Mastery Level (Full day)
+- All documents studied
+- Workflows practiced
+- Technology docs internalized
+
+## 📈 Knowledge Maintenance
+
+### When to Update
+
+**After major changes**:
+- New architectural patterns discovered
+- Technology integrations changed
+- Testing strategies evolved
+- Common workflows identified
+
+### What to Watch For
+
+**Pattern Evolution**:
+- New error handling approaches
+- Performance optimization techniques
+- Testing methodology improvements
+- Technology upgrade impacts
+
+**Workflow Changes**:
+- New development practices
+- Build process modifications
+- Debugging technique improvements
+
+### Update Process
+
+1. **Identify changed patterns** in code review
+2. **Update relevant documents** with new discoveries
+3. **Revise CLAUDE.md** if critical workflows change
+4. **Test workflow accuracy** with sample implementations
+
+## 🎯 Success Metrics
+
+### Effective Usage Indicators
+- **Reduced onboarding time** for new team members
+- **Consistent code patterns** across contributions
+- **Faster debugging** with systematic approaches
+- **Fewer architectural questions** during development
+
+### Knowledge Architecture Health
+- **Documents stay current** with codebase evolution
+- **Workflows remain accurate** for actual development
+- **Examples still work** with current codebase state
+- **Patterns reflect reality** of current development practices
+
+## 🚀 Getting Started Recommendations
+
+### First-Time Users
+1. Skim `CLAUDE.md` for immediate context (5 min)
+2. Read `codebase-map.md` for structural understanding (15 min)
+3. Try a workflow document for hands-on learning (30 min)
+
+### Returning Users  
+1. Check `CLAUDE.md` Quick Reference for immediate needs
+2. Jump directly to relevant workflow or technology document
+3. Use architecture docs for complex decisions
+
+### Emergency Debugging
+1. `CLAUDE.md` debugging section for quick diagnostics
+2. `workflows/03-debugging-issues.md` for systematic approach
+3. Technology-specific docs for deep issues
+
+This knowledge architecture is designed to grow with the codebase and provide value at every level of engagement, from quick references to deep architectural understanding.

package/claude/discovered-patterns.md

@@ -0,0 +1,380 @@
+# Discovered Patterns: mixpanel-react-native
+
+## Code Architecture Philosophy
+
+This codebase demonstrates **graceful degradation** and **defensive programming** principles. The team prioritizes reliability over performance, with comprehensive fallback mechanisms and robust error handling throughout.
+
+## 🏗️ Architectural Patterns
+
+### 1. Singleton Pattern with Lazy Initialization
+
+**Pattern**: Factory functions returning singleton instances for shared resources.
+
+```javascript
+// javascript/mixpanel-queue.js
+export const MixpanelQueueManager = (() => {
+  let _queues = {};
+  let mixpanelPersistent;
+
+  const getPersistent = () => {
+    if (!mixpanelPersistent) {
+      mixpanelPersistent = MixpanelPersistent.getInstance();
+    }
+    return mixpanelPersistent;
+  };
+  // ...
+})();
+```
+
+**Motivation**: Ensures single source of truth for queue state and persistent storage while avoiding initialization costs until needed.
+
+### 2. Factory Function Pattern for Dependency Injection
+
+**Pattern**: Core modules accept dependencies via factory functions rather than direct imports.
+
+```javascript
+// javascript/mixpanel-core.js
+export const MixpanelCore = (storage) => {
+  const mixpanelPersistent = MixpanelPersistent.getInstance(storage);
+  // ...
+  return {
+    initialize,
+    startProcessingQueue,
+    addToMixpanelQueue,
+    flush,
+    identifyUserQueue,
+  };
+};
+```
+
+**Motivation**: Enables testing with mock storage and supports different storage implementations (AsyncStorage vs. custom).
+
+### 3. Token-Based Multi-Tenancy
+
+**Pattern**: All operations include token parameter for instance isolation.
+
+```javascript
+// Every function signature includes token as first parameter
+const flush = async (token) => { /* ... */ };
+const track = async (token, eventName, properties) => { /* ... */ };
+
+// Storage keys are token-scoped
+export const getQueueKey = (token, type) => `MIXPANEL_${token}_${type}_QUEUE`;
+```
+
+**Motivation**: Supports multiple Mixpanel projects within single app without data leakage.
+
+## 🎯 Naming Conventions
+
+### File Naming
+- **Kebab-case**: `mixpanel-core.js`, `mixpanel-queue.js`
+- **Descriptive modules**: Each file represents a single responsibility
+- **Prefix consistency**: All JavaScript modules start with `mixpanel-`
+
+### Variable Naming
+- **camelCase**: Standard JavaScript convention (`mixpanelImpl`, `trackAutomaticEvents`)
+- **Constants**: SCREAMING_SNAKE_CASE (`DEFAULT_OPT_OUT`, `PARAMS.TOKEN`)
+- **Private variables**: Leading underscore (`_queues`, `_shouldLog`)
+
+### Function Naming
+- **Verb-first**: `initialize`, `track`, `flush`, `addToMixpanelQueue`
+- **Boolean predicates**: `isValidAndSerializable`, `hasOptedOutTracking`
+- **Event handlers**: `handleBatchError`
+
+## 📦 Import/Export Patterns
+
+### Import Organization
+
+```javascript
+// External dependencies first
+import { Platform } from "react-native";
+import packageJson from "./package.json";
+
+// Internal modules second, grouped by purpose
+import { MixpanelCore } from "./mixpanel-core";
+import { MixpanelType } from "./mixpanel-constants";
+import { MixpanelConfig } from "./mixpanel-config";
+```
+
+### Export Strategies
+- **Named exports for utilities**: `export class MixpanelLogger`
+- **Default exports for main classes**: `export default class MixpanelMain`
+- **Factory function exports**: `export const MixpanelCore = (storage) => {...}`
+
+## 🛡️ Error Handling Philosophy
+
+### 1. Comprehensive Input Validation
+
+**Pattern**: Helper classes for parameter validation with descriptive errors.
+
+```javascript
+// index.js
+class StringHelper {
+  static isValid(str) {
+    return typeof str === "string" && !/^\s*$/.test(str);
+  }
+  
+  static raiseError(paramName) {
+    throw new Error(`${paramName}${ERROR_MESSAGE.INVALID_STRING}`);
+  }
+}
+
+// Usage
+if (!StringHelper.isValid(distinctId)) {
+  StringHelper.raiseError(PARAMS.DISTINCT_ID);
+}
+```
+
+### 2. Graceful Degradation
+
+**Pattern**: Try native implementation, fall back to JavaScript mode.
+
+```javascript
+// index.js
+if (useNative && MixpanelReactNative) {
+  this.mixpanelImpl = MixpanelReactNative;
+  return;
+} else if (useNative) {
+  console.warn("MixpanelReactNative is not available; using JavaScript mode...");
+}
+
+this.mixpanelImpl = new MixpanelMain(token, trackAutomaticEvents, storage);
+```
+
+### 3. Safe Storage Operations
+
+**Pattern**: Wrap all storage operations in try-catch with fallbacks.
+
+```javascript
+// javascript/mixpanel-storage.js
+async getItem(key) {
+  try {
+    return await this.storage.getItem(key);
+  } catch {
+    MixpanelLogger.error("error getting item from storage");
+    return null;
+  }
+}
+```
+
+#### Evolution [Updated: 2025-05-30]
+Storage module resolution now handles both ES6 and CommonJS exports:
+
+```javascript
+const storageModule = require("@react-native-async-storage/async-storage");
+if (storageModule.default) {
+  this.storage = storageModule.default
+} else {
+  this.storage = storageModule
+}
+```
+
+### 4. UUID Generation with Expo Compatibility [Updated: 2025-05-30]
+
+**Pattern**: Try platform-specific method first, fallback to universal.
+
+```javascript
+// javascript/mixpanel-persistent.js
+try {
+  this._identity[token].deviceId = randomUUID(); // expo-crypto
+} catch (e) {
+  this._identity[token].deviceId = uuid.v4();    // uuid package
+}
+```
+
+**Motivation**: Better Expo support while maintaining backward compatibility.
+
+## 🔄 Async Patterns
+
+### 1. Promise-Based API with Error Propagation
+
+**Pattern**: Native methods return Promises, JavaScript methods async/await.
+
+```javascript
+// Native (iOS Swift)
+@objc
+func initialize(_ token: String, /* ... */) -> Void {
+    // ...
+    resolve(true)
+}
+
+// JavaScript wrapper
+identify(distinctId) {
+  return new Promise((resolve, reject) => {
+    if (!StringHelper.isValid(distinctId)) {
+      reject(new Error("Invalid distinctId"));
+    }
+    this.mixpanelImpl.identify(this.token, distinctId)
+      .then(() => resolve())
+      .catch((err) => reject(err));
+  });
+}
+```
+
+### 2. Retry Logic with Exponential Backoff
+
+**Pattern**: Network requests implement sophisticated retry strategy.
+
+```javascript
+// javascript/mixpanel-network.js
+const maxRetries = 5;
+const backoff = Math.min(2 ** retryCount * 2000, 60000); // Exponential backoff
+if (retryCount < maxRetries) {
+  MixpanelLogger.log(token, `Retrying in ${backoff / 1000} seconds...`);
+  await new Promise((resolve) => setTimeout(resolve, backoff));
+  return sendRequest({ /* ... */, retryCount: retryCount + 1 });
+}
+```
+
+## 🧪 Testing Patterns
+
+### 1. Comprehensive Mocking Strategy
+
+**Pattern**: Mock all external dependencies at the module level.
+
+```javascript
+// __tests__/jest_setup.js
+jest.mock("expo-crypto", () => ({
+  randomUUID: jest.fn(() => "mocked-uuid-string-" + Math.random().toString(36).substring(2, 15))
+}));
+
+jest.mock("@react-native-async-storage/async-storage", () => ({
+  getItem: jest.fn().mockResolvedValue(null),
+  setItem: jest.fn().mockResolvedValue(undefined),
+  removeItem: jest.fn().mockResolvedValue(undefined),
+}));
+```
+
+### 2. Test File Organization
+
+**Pattern**: Mirror source structure with `.test.js` suffix.
+
+```
+__tests__/
+├── core.test.js           # Tests javascript/mixpanel-core.js
+├── network.test.js        # Tests javascript/mixpanel-network.js
+├── queue.test.js          # Tests javascript/mixpanel-queue.js
+└── jest_setup.js          # Global test configuration
+```
+
+## 📝 Documentation Patterns
+
+### 1. JSDoc with Rich Examples
+
+**Pattern**: Comprehensive JSDoc comments with usage examples.
+
+```javascript
+/**
+ * Associate all future calls to track() with the user identified by
+ * the given distinct id.
+ *
+ * @param {string} distinctId a string uniquely identifying this user
+ * @returns {Promise} A promise that resolves when the identify is successful
+ */
+identify(distinctId) { /* ... */ }
+```
+
+### 2. Inline Comments for Complex Logic
+
+**Pattern**: Explain "why" not "what" in comments.
+
+```javascript
+// Only update if there is a difference; minimize object copies
+if (updateDistinctId || updateDeviceId || updateUserId) {
+  updated = { ...record }; // shallow copy only if needed
+  // ...
+}
+```
+
+## 🔍 Logging Philosophy
+
+### 1. Token-Scoped Conditional Logging
+
+**Pattern**: All logs include token context and respect per-instance settings.
+
+```javascript
+// javascript/mixpanel-logger.js
+static log(token, ...args) {
+  if (MixpanelLogger._shouldLog(token)) {
+    console.log(...MixpanelLogger._prependPrefix(args));
+  }
+}
+
+// Usage with context
+MixpanelLogger.log(token, `Track '${eventName}' with properties`, properties);
+```
+
+### 2. Structured Logging with Prefixes
+
+**Pattern**: Consistent log format for easy filtering.
+
+```javascript
+static _prependPrefix(args) {
+  return ["[Mixpanel]", ...args];
+}
+// Output: [Mixpanel] Track 'Plan Selected' with properties {...}
+```
+
+## 🚀 Performance Patterns
+
+### 1. Batched Processing with Queues
+
+**Pattern**: Collect events in memory, flush in configurable batches.
+
+```javascript
+// Process in batches to reduce network overhead
+const batchSize = config.getFlushBatchSize(token);
+const batch = queue.slice(0, batchSize);
+
+// Recursive processing for large queues
+if (queue.length > 0) {
+  setTimeout(processBatch, 0); // Non-blocking recursion
+}
+```
+
+### 2. Immutable State Updates
+
+**Pattern**: Use spread operator for shallow copies, minimize object creation.
+
+```javascript
+// Only create new objects when necessary
+const eventProperties = Object.freeze({
+  token,
+  time: Date.now(),
+  ...this.getMetaData(),
+  ...superProperties,
+  ...properties,
+  ...identityProps,
+});
+```
+
+### 3. Conditional Property Inclusion [Updated: 2025-05-30]
+
+**Pattern**: Use conditional spread to exclude null/undefined values.
+
+```javascript
+// Prevents sending null values to API
+const profileData = {
+  $token: token,
+  $time: Date.now(),
+  ...action,
+  ...(distinctId != null && { $distinct_id: distinctId }),
+  ...(deviceId != null && { $device_id: deviceId }),
+  ...(userId != null && { $user_id: userId }),
+};
+```
+
+**Motivation**: Cleaner API payloads and prevents backend issues with null values.
+
+## 🎨 Code Style Insights
+
+### Philosophy
+- **Defensive coding**: Assume everything can fail
+- **Explicit over implicit**: Clear parameter names and validation
+- **Fail fast**: Validate inputs immediately
+- **Progressive enhancement**: Native performance with JS fallback
+
+### Trade-offs Made
+- **Reliability over performance**: Multiple validation layers
+- **Developer experience over bundle size**: Helpful error messages
+- **Compatibility over simplicity**: Support both native and JS modes

package/claude/optimization/copilot-impact-analysis-2025-05-30.md

@@ -0,0 +1,56 @@
+# Copilot Instructions Impact Analysis - 2025-05-30
+
+## Current State
+- Total instructions: 40+ distinct guidance items
+- Total line count: 342 of ~500 recommended
+- Sections: 11 major sections
+- Available buffer: 158 lines
+
+## Impact Scores
+
+### High Impact (Score >75) - Must Keep
+| Instruction | Prevention | Frequency | Clarity | Total | Current Lines |
+|-------------|------------|-----------|---------|-------|---------------|
+| Token-based operations | 5 | 5 | 5 | 125 | 10 |
+| Input validation pattern | 5 | 5 | 5 | 125 | 12 |
+| Error handling (storage) | 4 | 5 | 5 | 100 | 15 |
+| Dual implementation routing | 5 | 4 | 5 | 100 | 14 |
+| Native module patterns | 4 | 4 | 5 | 80 | 40 |
+| Opt-out checking | 5 | 4 | 5 | 100 | 8 |
+| Silent failure pattern | 4 | 5 | 4 | 80 | 20 |
+
+### Medium Impact (Score 27-75) - Keep If Space
+| Instruction | Prevention | Frequency | Clarity | Total | Current Lines |
+|-------------|------------|-----------|---------|-------|---------------|
+| Naming conventions | 2 | 5 | 5 | 50 | 25 |
+| Queue-based processing | 3 | 4 | 4 | 48 | 14 |
+| Factory functions | 3 | 3 | 5 | 45 | 10 |
+| Testing both modes | 3 | 3 | 5 | 45 | 30 |
+| Logging with context | 2 | 5 | 5 | 50 | 19 |
+| Import organization | 1 | 5 | 5 | 25 | 11 |
+| Immutable updates | 2 | 3 | 4 | 24 | 14 |
+
+### Low Impact (Score <27) - Consider Removing
+| Instruction | Prevention | Frequency | Clarity | Total | Current Lines |
+|-------------|------------|-----------|---------|-------|---------------|
+| File structure context | 1 | 2 | 5 | 10 | 11 |
+| Key principles summary | 1 | 1 | 5 | 5 | 8 |
+| Singleton pattern details | 2 | 2 | 4 | 16 | 12 |
+| Private variable naming | 1 | 3 | 5 | 15 | 2 |
+
+## Redundancy Analysis
+- **Duplicate concepts**: Error handling appears in 3 sections
+- **Redundant with Cursor rules**: Detailed naming conventions, import organization
+- **Better in documentation**: File structure, key principles
+- **Consolidation opportunities**: Platform-specific code examples
+
+## Coverage Gaps
+- **Conditional property inclusion**: Not covered (new pattern)
+- **UUID generation fallback**: Not mentioned
+- **Gzip compression**: New feature not documented
+
+## Key Findings
+1. **Over-explained patterns**: Many patterns have both explanation and example
+2. **Platform code duplication**: iOS/Android/JS examples could be consolidated
+3. **Low-impact verbosity**: File structure and principles add little behavioral value
+4. **Missing critical patterns**: New patterns from recent updates not included