@teardown/react-native 1.2.39 → 2.0.1

package/docs/10-advanced.mdx

@@ -0,0 +1,563 @@
+# Advanced Usage
+
+Advanced patterns and techniques for the Teardown SDK.
+
+## Custom Storage Adapters
+
+Create platform-specific or specialized storage adapters.
+
+### In-Memory Storage (Testing)
+
+```typescript
+function createInMemoryStorageFactory(): SupportedStorageFactory {
+  return (storageKey: string) => {
+    const store = new Map<string, string>();
+    
+    return {
+      preload: () => {},
+      getItem: (key: string) => {
+        return store.get(`${storageKey}:${key}`) ?? null;
+      },
+      setItem: (key: string, value: string) => {
+        store.set(`${storageKey}:${key}`, value);
+      },
+      removeItem: (key: string) => {
+        store.delete(`${storageKey}:${key}`);
+      },
+      clear: () => {
+        store.clear();
+      },
+      keys: () => {
+        return Array.from(store.keys());
+      },
+    };
+  };
+}
+
+// Use in tests
+const teardown = new TeardownCore({
+  storageFactory: createInMemoryStorageFactory(),
+  // ...
+});
+```
+
+### AsyncStorage Adapter
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+function createAsyncStorageFactory(): SupportedStorageFactory {
+  return (storageKey: string) => {
+    const cache = new Map<string, string>();
+    
+    return {
+      preload: () => {
+        // Optionally preload keys
+        AsyncStorage.getAllKeys().then((keys) => {
+          const relevantKeys = keys.filter(k => k.startsWith(storageKey));
+          AsyncStorage.multiGet(relevantKeys).then((entries) => {
+            entries.forEach(([key, value]) => {
+              if (value) cache.set(key, value);
+            });
+          });
+        });
+      },
+      getItem: (key: string) => {
+        const fullKey = `${storageKey}:${key}`;
+        return cache.get(fullKey) ?? null;
+      },
+      setItem: (key: string, value: string) => {
+        const fullKey = `${storageKey}:${key}`;
+        cache.set(fullKey, value);
+        AsyncStorage.setItem(fullKey, value).catch(console.error);
+      },
+      removeItem: (key: string) => {
+        const fullKey = `${storageKey}:${key}`;
+        cache.delete(fullKey);
+        AsyncStorage.removeItem(fullKey).catch(console.error);
+      },
+      clear: () => {
+        cache.clear();
+      },
+      keys: () => {
+        return Array.from(cache.keys());
+      },
+    };
+  };
+}
+```
+
+### Encrypted Storage
+
+```typescript
+import EncryptedStorage from 'react-native-encrypted-storage';
+
+function createEncryptedStorageFactory(): SupportedStorageFactory {
+  return (storageKey: string) => {
+    const cache = new Map<string, string>();
+    
+    return {
+      preload: async () => {
+        try {
+          const keys = await EncryptedStorage.getAllKeys();
+          const relevantKeys = keys.filter(k => k.startsWith(storageKey));
+          
+          for (const key of relevantKeys) {
+            const value = await EncryptedStorage.getItem(key);
+            if (value) cache.set(key, value);
+          }
+        } catch (error) {
+          console.error('Preload failed:', error);
+        }
+      },
+      getItem: (key: string) => {
+        return cache.get(`${storageKey}:${key}`) ?? null;
+      },
+      setItem: (key: string, value: string) => {
+        const fullKey = `${storageKey}:${key}`;
+        cache.set(fullKey, value);
+        EncryptedStorage.setItem(fullKey, value).catch(console.error);
+      },
+      removeItem: (key: string) => {
+        const fullKey = `${storageKey}:${key}`;
+        cache.delete(fullKey);
+        EncryptedStorage.removeItem(fullKey).catch(console.error);
+      },
+      clear: () => {
+        cache.clear();
+      },
+      keys: () => {
+        return Array.from(cache.keys());
+      },
+    };
+  };
+}
+```
+
+## Custom Device Adapters
+
+Create adapters for non-standard platforms.
+
+### Web Device Adapter
+
+```typescript
+import type { DeviceInfo } from '@teardown/schemas';
+import type { DeviceInfoAdapter } from '@teardown/react-native';
+
+class WebDeviceAdapter implements DeviceInfoAdapter {
+  async getDeviceInfo(): Promise<DeviceInfo> {
+    return {
+      app_version: this.getAppVersion(),
+      app_build: this.getAppBuild(),
+      app_bundle_id: window.location.hostname,
+      device_platform: this.getPlatform(),
+      device_os_version: navigator.userAgent,
+      device_model: this.getDeviceModel(),
+      device_manufacturer: this.getBrowser(),
+      update: null,
+    };
+  }
+  
+  private getAppVersion(): string {
+    // Read from meta tag or package.json
+    const meta = document.querySelector('meta[name="version"]');
+    return meta?.getAttribute('content') ?? '1.0.0';
+  }
+  
+  private getAppBuild(): string {
+    const meta = document.querySelector('meta[name="build"]');
+    return meta?.getAttribute('content') ?? '1';
+  }
+  
+  private getPlatform(): DevicePlatformEnum {
+    const ua = navigator.userAgent.toLowerCase();
+    if (ua.includes('android')) return DevicePlatformEnum.ANDROID;
+    if (ua.includes('iphone') || ua.includes('ipad')) return DevicePlatformEnum.IOS;
+    return DevicePlatformEnum.WEB;
+  }
+  
+  private getDeviceModel(): string {
+    if (navigator.userAgentData?.mobile) return 'Mobile';
+    return 'Desktop';
+  }
+  
+  private getBrowser(): string {
+    const ua = navigator.userAgent;
+    if (ua.includes('Chrome')) return 'Chrome';
+    if (ua.includes('Firefox')) return 'Firefox';
+    if (ua.includes('Safari')) return 'Safari';
+    return 'Unknown';
+  }
+}
+
+// Use it
+const teardown = new TeardownCore({
+  deviceAdapter: new WebDeviceAdapter(),
+  // ...
+});
+```
+
+## Multiple SDK Instances
+
+Use multiple SDK instances for different projects or environments.
+
+```typescript
+// Production instance
+const productionTeardown = new TeardownCore({
+  org_id: 'prod-org',
+  project_id: 'prod-project',
+  api_key: 'prod-key',
+  storageFactory: createMMKVStorageFactory('production'),
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+
+// Staging instance
+const stagingTeardown = new TeardownCore({
+  org_id: 'staging-org',
+  project_id: 'staging-project',
+  api_key: 'staging-key',
+  storageFactory: createMMKVStorageFactory('staging'),
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+
+// Use based on environment
+const teardown = __DEV__ ? stagingTeardown : productionTeardown;
+
+<TeardownProvider core={teardown}>
+  <App />
+</TeardownProvider>
+```
+
+## Environment-Based Configuration
+
+```typescript
+const config = {
+  development: {
+    org_id: process.env.DEV_ORG_ID!,
+    project_id: process.env.DEV_PROJECT_ID!,
+    api_key: process.env.DEV_API_KEY!,
+  },
+  staging: {
+    org_id: process.env.STAGING_ORG_ID!,
+    project_id: process.env.STAGING_PROJECT_ID!,
+    api_key: process.env.STAGING_API_KEY!,
+  },
+  production: {
+    org_id: process.env.PROD_ORG_ID!,
+    project_id: process.env.PROD_PROJECT_ID!,
+    api_key: process.env.PROD_API_KEY!,
+  },
+};
+
+const env = process.env.NODE_ENV as keyof typeof config;
+const teardown = new TeardownCore({
+  ...config[env],
+  storageFactory: createMMKVStorageFactory(),
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+```
+
+## Advanced Identity Patterns
+
+### Automatic Re-identification
+
+```typescript
+function useAutoReidentify(interval: number = 3600000) {
+  const { core } = useTeardown();
+  
+  useEffect(() => {
+    const timer = setInterval(async () => {
+      await core.identity.refresh();
+    }, interval);
+    
+    return () => clearInterval(timer);
+  }, [core, interval]);
+}
+
+// Use in app
+function App() {
+  useAutoReidentify(3600000); // Re-identify every hour
+  return <YourApp />;
+}
+```
+
+### Session Persistence Across Launches
+
+```typescript
+function useRestoreSession() {
+  const { core } = useTeardown();
+  const [restored, setRestored] = useState(false);
+  
+  useEffect(() => {
+    const state = core.identity.getIdentifyState();
+    
+    if (state.type === 'identified') {
+      // Session already restored from storage
+      setRestored(true);
+    } else {
+      // Wait for auto-identification
+      const unsubscribe = core.identity.onIdentifyStateChange((newState) => {
+        if (newState.type === 'identified') {
+          setRestored(true);
+        }
+      });
+      
+      return unsubscribe;
+    }
+  }, [core]);
+  
+  return restored;
+}
+
+// Use for loading state
+function App() {
+  const restored = useRestoreSession();
+  
+  if (!restored) {
+    return <SplashScreen />;
+  }
+  
+  return <MainApp />;
+}
+```
+
+## Advanced Force Update Patterns
+
+### Custom Update UI with Animation
+
+```typescript
+function AnimatedUpdateBanner() {
+  const { isUpdateAvailable, isUpdateRequired } = useForceUpdate();
+  const slideAnim = useRef(new Animated.Value(-100)).current;
+  
+  useEffect(() => {
+    if (isUpdateAvailable && !isUpdateRequired) {
+      Animated.spring(slideAnim, {
+        toValue: 0,
+        useNativeDriver: true,
+      }).start();
+    } else {
+      Animated.timing(slideAnim, {
+        toValue: -100,
+        duration: 200,
+        useNativeDriver: true,
+      }).start();
+    }
+  }, [isUpdateAvailable, isUpdateRequired]);
+  
+  return (
+    <Animated.View style={[styles.banner, { transform: [{ translateY: slideAnim }] }]}>
+      <Text>Update Available</Text>
+      <Button title="Update" onPress={handleUpdate} />
+    </Animated.View>
+  );
+}
+```
+
+### Deferred Update Prompts
+
+```typescript
+function useDeferredUpdatePrompt(deferCount: number = 3) {
+  const { isUpdateAvailable, isUpdateRequired } = useForceUpdate();
+  const [dismissCount, setDismissCount] = useState(0);
+  
+  const shouldShow = isUpdateAvailable && (
+    isUpdateRequired || dismissCount < deferCount
+  );
+  
+  const dismiss = () => {
+    if (!isUpdateRequired) {
+      setDismissCount(c => c + 1);
+    }
+  };
+  
+  return { shouldShow, dismiss, isForced: isUpdateRequired };
+}
+
+// Use it
+function UpdatePrompt() {
+  const { shouldShow, dismiss, isForced } = useDeferredUpdatePrompt(3);
+  
+  if (!shouldShow) return null;
+  
+  return (
+    <Modal visible={true}>
+      <Text>Update Available</Text>
+      <Button title="Update Now" onPress={handleUpdate} />
+      {!isForced && (
+        <Button title="Remind Me Later" onPress={dismiss} />
+      )}
+    </Modal>
+  );
+}
+```
+
+## Monitoring and Analytics
+
+### Track SDK Events
+
+```typescript
+function useSDKAnalytics() {
+  const { core } = useTeardown();
+  
+  useEffect(() => {
+    // Track identity changes
+    const unsubscribeIdentity = core.identity.onIdentifyStateChange((state) => {
+      analytics.track('identity_state_changed', {
+        state: state.type,
+        timestamp: Date.now(),
+      });
+    });
+    
+    // Track version status changes
+    const unsubscribeVersion = core.forceUpdate.onVersionStatusChange((status) => {
+      analytics.track('version_status_changed', {
+        status: status.type,
+        timestamp: Date.now(),
+      });
+    });
+    
+    return () => {
+      unsubscribeIdentity();
+      unsubscribeVersion();
+    };
+  }, [core]);
+}
+```
+
+### Error Tracking
+
+```typescript
+function useSDKErrorTracking() {
+  const { core } = useTeardown();
+  
+  const trackError = async (operation: string, error: string) => {
+    const deviceId = await core.device.getDeviceId();
+    const session = core.identity.getSessionState();
+    
+    errorTracker.log(error, {
+      operation,
+      deviceId,
+      sessionId: session?.session_id,
+      personaId: session?.persona_id,
+    });
+  };
+  
+  return trackError;
+}
+```
+
+## Testing
+
+### Mock SDK for Tests
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+
+export function createMockTeardown(): TeardownCore {
+  return new TeardownCore({
+    org_id: 'test-org',
+    project_id: 'test-project',
+    api_key: 'test-key',
+    storageFactory: createInMemoryStorageFactory(),
+    deviceAdapter: {
+      getDeviceInfo: async () => ({
+        app_version: '1.0.0',
+        app_build: '1',
+        app_bundle_id: 'com.test.app',
+        device_platform: DevicePlatformEnum.IOS,
+        device_os_version: '17.0',
+        device_model: 'iPhone 14',
+        device_manufacturer: 'Apple',
+        update: null,
+      }),
+    },
+  });
+}
+
+// Use in tests
+import { render } from '@testing-library/react-native';
+
+it('renders with mock SDK', () => {
+  const mockTeardown = createMockTeardown();
+  
+  const { getByText } = render(
+    <TeardownProvider core={mockTeardown}>
+      <MyComponent />
+    </TeardownProvider>
+  );
+  
+  expect(getByText('Welcome')).toBeTruthy();
+});
+```
+
+### Test Hooks
+
+```typescript
+import { renderHook, waitFor } from '@testing-library/react-native';
+
+it('useSession returns session after identify', async () => {
+  const mockTeardown = createMockTeardown();
+  
+  const wrapper = ({ children }) => (
+    <TeardownProvider core={mockTeardown}>
+      {children}
+    </TeardownProvider>
+  );
+  
+  const { result } = renderHook(() => useSession(), { wrapper });
+  
+  // Initially null
+  expect(result.current).toBeNull();
+  
+  // Identify
+  await mockTeardown.identity.identify({ user_id: 'test-user' });
+  
+  // Wait for update
+  await waitFor(() => {
+    expect(result.current).not.toBeNull();
+  });
+  
+  expect(result.current?.persona_id).toBe('test-user');
+});
+```
+
+## Performance Optimization
+
+### Lazy Initialization
+
+```typescript
+function useLazyTeardown() {
+  const [teardown] = useState(() => {
+    // Only initialize once
+    return new TeardownCore({
+      // ... config
+    });
+  });
+  
+  return teardown;
+}
+```
+
+### Memoized Selectors
+
+```typescript
+function usePersonaId() {
+  const session = useSession();
+  return useMemo(() => session?.persona_id ?? null, [session]);
+}
+
+function useIsUpdateRequired() {
+  const { versionStatus } = useForceUpdate();
+  return useMemo(
+    () => versionStatus.type === 'update_required',
+    [versionStatus]
+  );
+}
+```
+
+## Next Steps
+
+- [API Reference](./07-api-reference.mdx)
+- [Hooks Reference](./08-hooks-reference.mdx)
+- [Getting Started](./01-getting-started.mdx)

package/package.json

@@ -1,49 +1,67 @@
 {
-  "name": "@teardown/react-native",
-  "version": "1.2.39",
-  "description": "",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "tsc",
-    "dev": "tsc --watch"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "README.md",
-    "dist/**/*"
-  ],
-  "dependencies": {
-    "@react-native/dev-middleware": "^0.76.1",
-    "@teardown/cli": "^1.2.20",
-    "@teardown/logger": "1.2.39",
-    "@teardown/util": "1.2.39",
-    "@teardown/websocket": "1.2.39",
-    "async-mutex": "^0.5.0",
-    "chalk": "^5.3.0",
-    "compression": "^1.7.5",
-    "connect": "^3.7.0",
-    "debug": "^4.3.7",
-    "pretty-format": "^29.7.0",
-    "ws": "^8.18.0"
-  },
-  "devDependencies": {
-    "@teardown/config": "1.2.39",
-    "@types/compression": "^1.7.5",
-    "@types/connect": "^3.4.38",
-    "@types/react": "^18.3.12",
-    "@types/react-native": "^0.73.0",
-    "metro-config": "^0.81.0",
-    "react": "^18.3.1",
-    "react-native": "^0.75.4",
-    "react-native-device-info": "^14.0.0",
-    "react-native-gesture-handler": "^2.20.2",
-    "typescript": "^5.6.3"
-  },
-  "peerDependencies": {
-    "react": "^18",
-    "react-native": "^0.75",
-    "react-native-device-info": "^14",
-    "react-native-gesture-handler": "^2"
-  }
+	"name": "@teardown/react-native",
+	"version": "2.0.1",
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src/**/*",
+		"docs/**/*"
+	],
+	"main": "./src/exports/index.ts",
+	"module": "./src/exports/index.ts",
+	"types": "./src/exports/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/exports/index.ts",
+			"import": "./src/exports/index.ts",
+			"default": "./src/exports/index.ts"
+		},
+		"./expo": {
+			"types": "./src/exports/expo.ts",
+			"import": "./src/exports/expo.ts",
+			"default": "./src/exports/expo.ts"
+		},
+		"./mmkv": {
+			"types": "./src/exports/mmkv.ts",
+			"import": "./src/exports/mmkv.ts",
+			"default": "./src/exports/mmkv.ts"
+		}
+	},
+	"scripts": {
+		"build": "tsc --project ./tsconfig.json",
+		"dev": "bun run build && tsc --watch --project ./tsconfig.json",
+		"typecheck": "tsc --noEmit --project ./tsconfig.json",
+		"lint": "biome lint --write",
+		"fmt": "biome format --write",
+		"test": "bun test",
+		"prepublishOnly": "bun run build",
+		"nuke": "cd ../../ && bun run nuke"
+	},
+	"dependencies": {
+		"@teardown/ingest-api": "0.1.36",
+		"@teardown/schemas": "0.1.36",
+		"@teardown/types": "0.1.36",
+		"eventemitter3": "^5.0.1",
+		"uuid": "^13.0.0"
+	},
+	"devDependencies": {
+		"@elysiajs/eden": "^1.4.5",
+		"@teardown/tsconfig": "1.0.0",
+		"@types/bun": "latest",
+		"@types/react": "*",
+		"@types/uuid": "^11.0.0",
+		"expo-updates": "^29.0.12"
+	},
+	"peerDependencies": {
+		"react": "*",
+		"react-native": "*",
+		"typescript": "*",
+		"expo-application": "^7.0",
+		"expo-device": "^8.0",
+		"expo-notifications": "^0.29",
+		"react-native-mmkv": "^3.0",
+		"zod": "^4"
+	}
 }