mixpanel-react-native 3.0.9 → 3.1.0

package/.github/instructions/native-bridge.instructions.md

@@ -0,0 +1,126 @@
+---
+applyTo: "ios/**/*.swift,android/**/*.java,**/*Native*.js"
+---
+
+# Native Bridge Implementation Guidelines
+
+Extends [core instructions](../copilot-instructions.md) with React Native bridge-specific patterns.
+
+## iOS Swift Requirements
+
+### Method Declaration
+```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
+    }
+    
+    // Type conversion using MixpanelTypeHandler
+    let processedValue = MixpanelTypeHandler.processProperty(value: value)
+    
+    // Call native SDK method
+    instance.nativeMethod(parameter: processedValue)
+    resolve(nil)
+}
+```
+
+### Required Patterns
+- **@objc decorator**: Every bridge method must have @objc
+- **Promise pattern**: Use resolver/rejecter for async operations
+- **Instance management**: Always get instance by token
+- **Error handling**: Guard against missing instances
+- **Type conversion**: Use MixpanelTypeHandler for React Native → Swift types
+
+## Android Java Requirements
+
+### Method Declaration
+```java
+@ReactMethod
+public void methodName(final String token, 
+                      String parameter, 
+                      Dynamic value, 
+                      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) {
+        Object processedValue = ReactNativeHelper.dynamicToObject(value);
+        instance.nativeMethod(parameter, processedValue);
+        promise.resolve(null);
+    }
+}
+```
+
+### Required Patterns
+- **@ReactMethod annotation**: Every bridge method must have annotation
+- **Thread safety**: Use synchronized (instance) for all operations
+- **Type conversion**: Use ReactNativeHelper for React Native → Java types
+- **Promise pattern**: Handle async operations with Promise parameter
+- **Error handling**: Check for null instances
+
+## Bridge Integration
+
+### JavaScript Native Module Interface
+```javascript
+// Check availability before calling
+if (MixpanelReactNative && MixpanelReactNative.methodName) {
+  return MixpanelReactNative.methodName(token, parameter);
+} else {
+  console.warn("Native method not available, falling back to JS implementation");
+  return jsImplementation(token, parameter);
+}
+
+// Error handling for native calls
+try {
+  await MixpanelReactNative.methodName(token, parameter);
+} catch (error) {
+  MixpanelLogger.error(token, `Native method failed: ${error.message}`);
+  return jsImplementation(token, parameter);
+}
+```
+
+### Testing Native Modules
+```javascript
+// Mock native module in tests
+jest.doMock("react-native", () => ({
+  NativeModules: {
+    MixpanelReactNative: {
+      methodName: jest.fn().mockResolvedValue(undefined),
+      // Mock ALL native methods
+    },
+  },
+}));
+
+// Test native implementation calls
+expect(MixpanelReactNative.methodName).toHaveBeenCalledWith(
+  'test-token',
+  'parameter',
+  expect.objectContaining({})
+);
+```
+
+## Platform-Specific Considerations
+
+### iOS-Specific Features
+- Background flushing support via `setFlushOnBackground`
+- Use iOS-specific optimizations where available
+- Handle iOS lifecycle events appropriately
+
+### Android Limitations
+- No background flushing support
+- Require thread synchronization for all operations
+- Handle Android-specific memory considerations
+
+### Performance Optimization
+- Minimize bridge calls by batching operations
+- Use native queue management when available
+- Leverage platform-specific features efficiently

package/.github/instructions/storage-patterns.instructions.md

@@ -0,0 +1,337 @@
+---
+applyTo: "**/*storage*.js,**/*persistent*.js,**/*queue*.js"
+---
+
+# Storage Patterns Guidelines
+
+Extends [core instructions](../copilot-instructions.md) with AsyncStorage abstraction and persistence management patterns.
+
+## AsyncStorage Abstraction (MANDATORY)
+
+### Storage Adapter with Fallback
+```javascript
+export class AsyncStorageAdapter {
+  constructor(storage) {
+    if (!storage) {
+      try {
+        const storageModule = require("@react-native-async-storage/async-storage");
+        this.storage = storageModule.default || storageModule;
+      } catch {
+        console.error("[@RNC/AsyncStorage]: NativeModule: AsyncStorage is null");
+        console.error("[Mixpanel] Falling back to in-memory storage");
+        this.storage = new InMemoryStorage();
+      }
+    } else {
+      this.storage = storage;
+    }
+  }
+}
+```
+
+### In-Memory Fallback Implementation
+```javascript
+class InMemoryStorage {
+  constructor() {
+    this.store = {};
+  }
+
+  async getItem(key) {
+    return this.store.hasOwnProperty(key) ? this.store[key] : null;
+  }
+
+  async setItem(key, value) {
+    this.store[key] = value;
+  }
+
+  async removeItem(key) {
+    delete this.store[key];
+  }
+}
+```
+
+## Error Handling Pattern (CRITICAL)
+
+### Silent Failure Implementation
+```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
+  }
+}
+
+async setItem(key, value) {
+  try {
+    await this.storage.setItem(key, value);
+  } catch {
+    MixpanelLogger.error("error setting item in storage");
+    // Silent failure - continue operation
+  }
+}
+
+async removeItem(key) {
+  try {
+    await this.storage.removeItem(key);
+  } catch {
+    MixpanelLogger.error("error removing item from storage");
+    // Silent failure - continue operation
+  }
+}
+```
+
+## Key Management Strategy
+
+### Token-Scoped Key Generation
+```javascript
+// REQUIRED: Use these functions for all storage keys
+export const getQueueKey = (token, type) => `MIXPANEL_${token}_${type}_QUEUE`;
+export const getDeviceIdKey = (token) => `MIXPANEL_${token}_DEVICE_ID`;
+export const getDistinctIdKey = (token) => `MIXPANEL_${token}_DISTINCT_ID`;
+export const getUserIdKey = (token) => `MIXPANEL_${token}_USER_ID`;
+export const getOptedOutKey = (token) => `MIXPANEL_${token}_OPT_OUT`;
+export const getSuperPropertiesKey = (token) => `MIXPANEL_${token}_SUPER_PROPERTIES`;
+export const getTimeEventsKey = (token) => `MIXPANEL_${token}_TIME_EVENTS`;
+
+// Always use consistent key generation
+const key = getSuperPropertiesKey(token);
+await this.storageAdapter.setItem(key, JSON.stringify(properties));
+```
+
+## Serialization Patterns
+
+### JSON Serialization with Error Handling
+```javascript
+// Serialization: Object → JSON string
+async persistSuperProperties(token) {
+  if (this._superProperties[token] === null) {
+    return; // Don't persist null values
+  }
+  
+  try {
+    const serialized = JSON.stringify(this._superProperties[token]);
+    await this.storageAdapter.setItem(getSuperPropertiesKey(token), serialized);
+  } catch (error) {
+    MixpanelLogger.error(`Failed to serialize super properties: ${error.message}`);
+  }
+}
+
+// Deserialization: JSON string → Object with fallback
+async loadSuperProperties(token) {
+  try {
+    const superPropertiesString = await this.storageAdapter.getItem(
+      getSuperPropertiesKey(token)
+    );
+    
+    this._superProperties[token] = superPropertiesString
+      ? JSON.parse(superPropertiesString)
+      : {}; // ALWAYS provide default value
+  } catch (error) {
+    MixpanelLogger.error(`Failed to parse super properties, using defaults: ${error.message}`);
+    this._superProperties[token] = {}; // Fallback to empty object
+  }
+}
+```
+
+### Complex Data Structure Handling
+```javascript
+// Queue persistence (arrays of objects)
+async loadQueue(token, type) {
+  try {
+    const queueString = await this.storageAdapter.getItem(getQueueKey(token, type));
+    return queueString ? JSON.parse(queueString) : []; // Default to empty array
+  } catch (error) {
+    MixpanelLogger.error(`Failed to load ${type} queue, using empty queue: ${error.message}`);
+    return []; // Always return usable array
+  }
+}
+
+async saveQueue(token, type, queue) {
+  try {
+    await this.storageAdapter.setItem(
+      getQueueKey(token, type),
+      JSON.stringify(queue)
+    );
+  } catch (error) {
+    MixpanelLogger.error(`Failed to save ${type} queue: ${error.message}`);
+    // Don't throw - let operation continue
+  }
+}
+
+// Boolean persistence (explicit string conversion)
+async persistOptedOut(token) {
+  if (this._optedOut[token] === null || this._optedOut[token] === undefined) {
+    return; // Don't persist null/undefined
+  }
+  
+  await this.storageAdapter.setItem(
+    getOptedOutKey(token),
+    this._optedOut[token].toString() // Boolean → String
+  );
+}
+
+async loadOptOut(token) {
+  const optOutString = await this.storageAdapter.getItem(getOptedOutKey(token));
+  this._optedOut[token] = optOutString === "true"; // String → Boolean
+}
+```
+
+## Write-Through Caching Pattern
+
+### Memory Cache + Persistent Storage
+```javascript
+export class MixpanelPersistent {
+  constructor(storageAdapter) {
+    this.storageAdapter = storageAdapter;
+    
+    // In-memory caches for fast access
+    this._superProperties = {};
+    this._timeEvents = {};
+    this._identity = {};
+    this._optedOut = {};
+  }
+
+  // Fast reads from memory cache
+  getSuperProperties(token) {
+    return this._superProperties[token] || {};
+  }
+
+  // Write-through: Update cache AND persist
+  async updateSuperProperties(token, superProperties) {
+    // Update in-memory cache immediately
+    this._superProperties[token] = { ...superProperties };
+    
+    // Persist to storage asynchronously
+    await this.persistSuperProperties(token);
+  }
+}
+```
+
+## Lazy Loading Pattern
+
+### Load Data Only When Needed
+```javascript
+async loadDeviceId(token) {
+  if (!token) return; // Early exit for invalid token
+
+  // Check if already loaded
+  if (this._identity[token]?.deviceId) {
+    return;
+  }
+
+  const storageDeviceId = await this.storageAdapter.getItem(getDeviceIdKey(token));
+  
+  // Initialize token state only when needed
+  if (!this._identity[token]) {
+    this._identity[token] = {};
+  }
+
+  this._identity[token].deviceId = storageDeviceId;
+
+  // Generate new ID only if missing
+  if (!this._identity[token].deviceId) {
+    try {
+      this._identity[token].deviceId = randomUUID(); // Expo crypto
+    } catch (e) {
+      this._identity[token].deviceId = uuid.v4();    // uuid package fallback
+    }
+    
+    // Persist the new ID
+    await this.storageAdapter.setItem(
+      getDeviceIdKey(token),
+      this._identity[token].deviceId
+    );
+  }
+}
+```
+
+## Data Migration & Identity Generation
+
+### Identity Generation with Fallbacks
+```javascript
+async loadDistinctId(token) {
+  const distinctId = await this.storageAdapter.getItem(getDistinctIdKey(token));
+  
+  if (!this._identity[token]) {
+    this._identity[token] = {};
+  }
+  
+  this._identity[token].distinctId = distinctId;
+  
+  if (!this._identity[token].distinctId) {
+    // Generate device-based distinct ID
+    await this.loadDeviceId(token); // Ensure device ID exists
+    this._identity[token].distinctId = "$device:" + this._identity[token].deviceId;
+    
+    await this.storageAdapter.setItem(
+      getDistinctIdKey(token),
+      this._identity[token].distinctId
+    );
+  }
+}
+```
+
+## Cleanup Operations
+
+### Comprehensive Token Cleanup
+```javascript
+async reset(token) {
+  // Remove ALL token-related keys
+  await this.storageAdapter.removeItem(getDeviceIdKey(token));
+  await this.storageAdapter.removeItem(getDistinctIdKey(token));
+  await this.storageAdapter.removeItem(getUserIdKey(token));
+  await this.storageAdapter.removeItem(getSuperPropertiesKey(token));
+  await this.storageAdapter.removeItem(getTimeEventsKey(token));
+  await this.storageAdapter.removeItem(getOptedOutKey(token));
+  
+  // Clear memory cache
+  delete this._identity[token];
+  delete this._superProperties[token];
+  delete this._timeEvents[token];
+  delete this._optedOut[token];
+  
+  // Reload fresh state
+  await this.loadIdentity(token);
+  await this.loadSuperProperties(token);
+  await this.loadTimeEvents(token);
+}
+```
+
+## Testing Storage Operations
+
+### Mock Storage for Tests
+```javascript
+describe('Storage Operations', () => {
+  let adapter;
+  let mockStorage;
+
+  beforeEach(() => {
+    mockStorage = {
+      getItem: jest.fn(),
+      setItem: jest.fn(),
+      removeItem: jest.fn(),
+    };
+    adapter = new AsyncStorageAdapter(mockStorage);
+  });
+
+  it('should handle storage errors gracefully', async () => {
+    mockStorage.getItem.mockRejectedValue(new Error('Storage error'));
+    
+    const result = await adapter.getItem('test-key');
+    
+    expect(result).toBeNull();
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('error getting item from storage')
+    );
+  });
+});
+```
+
+## Performance Considerations
+
+- Use write-through caching for frequently accessed data
+- Implement lazy loading to avoid unnecessary storage I/O
+- Batch storage operations when possible
+- Minimize JSON.parse/stringify calls
+- Use efficient queue operations (splice vs recreation)