@teardown/react-native 1.2.39 → 2.0.1

package/docs/05-device-info.mdx

@@ -0,0 +1,324 @@
+# Device Information
+
+Collect comprehensive device, OS, and app information with the DeviceClient.
+
+## Overview
+
+The DeviceClient provides:
+- Unique device identification
+- Comprehensive device information
+- Platform-specific adapters
+- Automatic device fingerprinting
+
+## Device Adapters
+
+The SDK uses adapters to collect device information across different platforms.
+
+### Expo Adapter
+
+For Expo applications:
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { ExpoDeviceAdapter } from '@teardown/react-native/expo';
+
+const teardown = new TeardownCore({
+  // ... other options
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+```
+
+Required dependencies:
+```bash
+bun add expo-application expo-device expo-updates
+```
+
+### React Native Adapter
+
+For React Native CLI applications:
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { ReactNativeDeviceAdapter } from '@teardown/react-native/device-info';
+
+const teardown = new TeardownCore({
+  // ... other options
+  deviceAdapter: new ReactNativeDeviceAdapter(),
+});
+```
+
+Required dependencies:
+```bash
+bun add react-native-device-info
+```
+
+## Device ID
+
+Every device gets a unique, persistent identifier.
+
+### Getting Device ID
+
+```typescript
+import { useTeardown } from '@teardown/react-native';
+
+function MyComponent() {
+  const { core } = useTeardown();
+  
+  const getDeviceId = async () => {
+    const deviceId = await core.device.getDeviceId();
+    console.log('Device ID:', deviceId);
+  };
+}
+```
+
+### How It Works
+
+1. On first launch, a random UUID is generated
+2. ID is persisted in namespaced storage
+3. Same ID is used for all subsequent sessions
+4. Survives app updates and reinstalls (depending on storage)
+
+## Device Information
+
+### Getting Device Info
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+```
+
+### DeviceInfo Object
+
+```typescript
+type DeviceInfo = {
+  // App Information
+  app_version: string;          // e.g., "1.0.0"
+  app_build: string;           // e.g., "100"
+  app_bundle_id: string;       // e.g., "com.company.app"
+  
+  // Device Information
+  device_platform: DevicePlatformEnum;  // IOS, ANDROID, WEB, etc.
+  device_os_version: string;            // e.g., "17.0"
+  device_model: string;                 // e.g., "iPhone 14 Pro"
+  device_manufacturer: string;          // e.g., "Apple"
+  
+  // Update Information (Expo only)
+  update?: {
+    update_id: string;
+    channel: string;
+    created_at: string;
+    runtime_version: string;
+  } | null;
+}
+```
+
+## Platform Enums
+
+### DevicePlatformEnum
+
+```typescript
+enum DevicePlatformEnum {
+  IOS = "IOS",
+  ANDROID = "ANDROID",
+  WEB = "WEB",
+  WINDOWS = "WINDOWS",
+  MACOS = "MACOS",
+  LINUX = "LINUX",
+  PHONE = "PHONE",
+  TABLET = "TABLET",
+  DESKTOP = "DESKTOP",
+  CONSOLE = "CONSOLE",
+  TV = "TV",
+  WEARABLE = "WEARABLE",
+  GAME_CONSOLE = "GAME_CONSOLE",
+  VR = "VR",
+  UNKNOWN = "UNKNOWN",
+  OTHER = "OTHER",
+}
+```
+
+## Creating Custom Adapters
+
+You can create custom device adapters for specific platforms or needs.
+
+### Adapter Interface
+
+```typescript
+interface DeviceInfoAdapter {
+  getDeviceInfo(): Promise<DeviceInfo>;
+}
+```
+
+### Example: Custom Web Adapter
+
+```typescript
+class WebDeviceAdapter implements DeviceInfoAdapter {
+  async getDeviceInfo(): Promise<DeviceInfo> {
+    return {
+      app_version: '1.0.0',
+      app_build: '1',
+      app_bundle_id: 'com.yourapp.web',
+      device_platform: DevicePlatformEnum.WEB,
+      device_os_version: navigator.userAgent,
+      device_model: 'Web Browser',
+      device_manufacturer: this.getBrowserName(),
+      update: null,
+    };
+  }
+  
+  private getBrowserName(): 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(),
+  // ...
+});
+```
+
+## Expo Update Information
+
+When using Expo with OTA updates, the SDK automatically includes update information:
+
+```typescript
+{
+  update: {
+    update_id: "abc123",
+    channel: "production",
+    created_at: "2024-01-01T00:00:00Z",
+    runtime_version: "1.0.0",
+  }
+}
+```
+
+This helps track which OTA update version users are running.
+
+## Usage in Identification
+
+Device information is automatically sent during identification:
+
+```typescript
+await core.identity.identify({
+  user_id: 'user-123',
+});
+
+// Automatically includes:
+// - Device ID
+// - Device platform
+// - OS version
+// - App version
+// - Device model
+// - Manufacturer
+// - Update info (if Expo)
+```
+
+This data is visible in your Teardown dashboard for analytics and debugging.
+
+## Platform Detection Examples
+
+### Check if iOS
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+const isIOS = deviceInfo.device_platform === DevicePlatformEnum.IOS;
+
+if (isIOS) {
+  // iOS-specific logic
+}
+```
+
+### Check Version
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+const version = deviceInfo.app_version;
+
+if (compareVersions(version, '2.0.0') < 0) {
+  // Running version older than 2.0.0
+}
+```
+
+### Check if Tablet
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+const isTablet = deviceInfo.device_platform === DevicePlatformEnum.TABLET;
+
+if (isTablet) {
+  // Show tablet-optimized UI
+}
+```
+
+## Storage
+
+Device ID is stored in namespaced storage:
+
+```
+Key: teardown:v1:device:deviceId
+Value: "uuid-generated-on-first-launch"
+```
+
+## Best Practices
+
+### 1. Cache Device Info If Needed Frequently
+
+```typescript
+// ❌ Bad - fetches every render
+function MyComponent() {
+  const deviceInfo = await core.device.getDeviceInfo();
+}
+
+// ✅ Good - fetch once and cache
+function MyComponent() {
+  const [deviceInfo, setDeviceInfo] = useState(null);
+  
+  useEffect(() => {
+    core.device.getDeviceInfo().then(setDeviceInfo);
+  }, []);
+}
+```
+
+### 2. Use Platform-Specific Code When Needed
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+
+if (deviceInfo.device_platform === DevicePlatformEnum.IOS) {
+  // iOS-specific behavior
+} else if (deviceInfo.device_platform === DevicePlatformEnum.ANDROID) {
+  // Android-specific behavior
+}
+```
+
+### 3. Don't Manually Generate Device IDs
+
+```typescript
+// ❌ Bad - inconsistent with SDK
+const myDeviceId = uuid.v4();
+
+// ✅ Good - use SDK's device ID
+const deviceId = await core.device.getDeviceId();
+```
+
+## Privacy Considerations
+
+The SDK collects:
+- ✅ Device model and OS (for compatibility)
+- ✅ App version (for update management)
+- ✅ Generated device ID (for analytics)
+- ❌ No personal information
+- ❌ No advertising IDs
+- ❌ No contacts or photos
+
+Device ID is randomly generated and not tied to hardware identifiers.
+
+## Next Steps
+
+- [Storage](./06-storage.mdx)
+- [Logging](./06-logging.mdx)
+- [API Reference](./07-api-reference.mdx)

package/docs/06-logging.mdx

@@ -0,0 +1,345 @@
+# Logging
+
+Structured logging system with configurable log levels.
+
+## Overview
+
+The LoggingClient provides:
+- Configurable log levels
+- Named loggers for each client
+- Console binding preservation
+- Debug mode support
+
+## Log Levels
+
+```typescript
+type LogLevel = 
+  | "none"      // No logging
+  | "error"     // Only errors
+  | "warn"      // Errors and warnings
+  | "info"      // Errors, warnings, and info
+  | "verbose"   // Everything including debug
+```
+
+### Level Priority
+
+```
+none < error < warn < info < verbose
+```
+
+When you set a level, all lower-priority levels are also shown:
+- `error`: Shows only errors
+- `warn`: Shows errors + warnings
+- `info`: Shows errors + warnings + info
+- `verbose`: Shows everything (errors + warnings + info + debug)
+
+## Setting Log Level
+
+### On Initialization
+
+```typescript
+const teardown = new TeardownCore({
+  // ... other options
+});
+
+// Set log level after initialization
+teardown.setLogLevel('verbose');
+```
+
+### During Runtime
+
+```typescript
+import { useTeardown } from '@teardown/react-native';
+
+function DebugPanel() {
+  const { core } = useTeardown();
+  
+  const enableDebugMode = () => {
+    core.setLogLevel('verbose');
+  };
+  
+  const disableLogging = () => {
+    core.setLogLevel('none');
+  };
+  
+  return (
+    <View>
+      <Button title="Enable Debug" onPress={enableDebugMode} />
+      <Button title="Disable Logs" onPress={disableLogging} />
+    </View>
+  );
+}
+```
+
+## Log Output Format
+
+All logs are prefixed with the client name:
+
+```
+[Teardown:TeardownCore] Shutting down TeardownCore
+[Teardown:IdentityClient] Identify state: unidentified -> identifying
+[Teardown:IdentityClient] Identify state: identifying -> identified
+[Teardown:ForceUpdateClient] Version status changing: initializing -> checking
+[Teardown:ForceUpdateClient] Checking version status on foreground
+[Teardown:DeviceClient] Getting device ID
+[Teardown:StorageClient] Creating storage for teardown:v1:identity
+```
+
+## Logger Methods
+
+Each client has a logger with these methods:
+
+```typescript
+logger.info(message, ...args)    // Info level
+logger.warn(message, ...args)    // Warning level
+logger.error(message, ...args)   // Error level
+logger.debug(message, ...args)   // Debug level (verbose)
+logger.trace(message, ...args)   // Stack trace (verbose)
+```
+
+## Internal Logging
+
+The SDK logs these events:
+
+### TeardownCore
+
+```typescript
+[Teardown:TeardownCore] Error initializing TeardownCore { error }
+[Teardown:TeardownCore] Shutting down TeardownCore
+```
+
+### IdentityClient
+
+```typescript
+[Teardown:IdentityClient] Identify state: unidentified -> identifying
+[Teardown:IdentityClient] Identify state: identifying -> identified
+[Teardown:IdentityClient] 422 Error identifying user { ... }
+```
+
+### ForceUpdateClient
+
+```typescript
+[Teardown:ForceUpdateClient] Version status changing: initializing -> up_to_date
+[Teardown:ForceUpdateClient] Checking version status on foreground
+[Teardown:ForceUpdateClient] Skipping version check - not identified
+```
+
+### DeviceClient
+
+```typescript
+[Teardown:DeviceClient] Getting device ID
+```
+
+### StorageClient
+
+```typescript
+[Teardown:StorageClient] Creating storage for teardown:v1:identity
+[Teardown:StorageClient] Storage already exists for teardown:v1:identity
+[Teardown:StorageClient] Returning existing storage for teardown:v1:identity
+[Teardown:StorageClient] Clearing storage for teardown:v1:identity
+```
+
+## Console Binding
+
+The logger preserves console call sites for better debugging:
+
+```typescript
+// Bound console methods preserve original call site
+private boundConsole = {
+  log: console.log.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console),
+  warn: console.warn.bind(console),
+  trace: console.trace.bind(console),
+};
+```
+
+This means clicking log messages in DevTools takes you to the original SDK code, not the logger wrapper.
+
+## Creating Custom Loggers
+
+While not typically needed, you can create custom loggers:
+
+```typescript
+import { LoggingClient } from '@teardown/react-native';
+
+const logging = new LoggingClient({ logLevel: 'info' });
+const logger = logging.createLogger({ name: 'MyFeature' });
+
+logger.info('Feature initialized');
+logger.error('Something went wrong');
+```
+
+## Conditional Logging
+
+The SDK checks log level before logging:
+
+```typescript
+// Only logs if current level >= info
+if (this.loggingClient.shouldLog('info')) {
+  logger.info('Message');
+}
+```
+
+This prevents unnecessary string concatenation and formatting in production.
+
+## Best Practices
+
+### 1. Use 'none' in Production
+
+```typescript
+// ✅ Good - no logs in production
+const logLevel = __DEV__ ? 'verbose' : 'none';
+teardown.setLogLevel(logLevel);
+```
+
+### 2. Use 'verbose' for Debugging
+
+```typescript
+// ✅ Good - detailed logs during development
+if (__DEV__) {
+  teardown.setLogLevel('verbose');
+}
+```
+
+### 3. Enable Logging for Support
+
+```typescript
+// ✅ Good - user can enable logs for support
+function Settings() {
+  const { core } = useTeardown();
+  const [debugMode, setDebugMode] = useState(false);
+  
+  const toggleDebug = () => {
+    const newMode = !debugMode;
+    setDebugMode(newMode);
+    core.setLogLevel(newMode ? 'verbose' : 'none');
+  };
+  
+  return <Switch value={debugMode} onValueChange={toggleDebug} />;
+}
+```
+
+### 4. Don't Rely on Logs for Logic
+
+```typescript
+// ❌ Bad - logs may be disabled
+logger.info('User identified');
+// ... rely on this log
+
+// ✅ Good - use state/events
+const result = await identify();
+if (result.success) {
+  // ... use result, not logs
+}
+```
+
+## Log Level Examples
+
+### Development
+
+```typescript
+// See everything
+teardown.setLogLevel('verbose');
+
+// Output:
+// [Teardown:IdentityClient] Getting device ID
+// [Teardown:IdentityClient] Identify state: unidentified -> identifying
+// [Teardown:StorageClient] Creating storage for teardown:v1:identity
+// etc.
+```
+
+### Debugging Issues
+
+```typescript
+// See important events
+teardown.setLogLevel('info');
+
+// Output:
+// [Teardown:IdentityClient] Identify state: unidentified -> identifying
+// [Teardown:ForceUpdateClient] Version status changing: initializing -> up_to_date
+```
+
+### Production
+
+```typescript
+// See only errors
+teardown.setLogLevel('error');
+
+// Output:
+// [Teardown:TeardownCore] Error initializing TeardownCore { error }
+// [Teardown:IdentityClient] 422 Error identifying user { ... }
+```
+
+### Disabled
+
+```typescript
+// No logs
+teardown.setLogLevel('none');
+
+// Output:
+// (nothing)
+```
+
+## Environment-Based Configuration
+
+```typescript
+const LOG_LEVEL: LogLevel = 
+  process.env.NODE_ENV === 'development' ? 'verbose' :
+  process.env.NODE_ENV === 'staging' ? 'info' :
+  'error';
+
+teardown.setLogLevel(LOG_LEVEL);
+```
+
+## Debugging Tips
+
+### 1. Enable Verbose Logging
+
+```typescript
+teardown.setLogLevel('verbose');
+```
+
+### 2. Filter by Client
+
+Search DevTools console for specific client:
+```
+[Teardown:IdentityClient]
+```
+
+### 3. Track State Transitions
+
+Look for state change logs:
+```
+Identify state: unidentified -> identifying
+Version status changing: checking -> up_to_date
+```
+
+### 4. Check Error Details
+
+Errors include full context:
+```typescript
+logger.error('Error initializing', { error, context });
+```
+
+## Performance
+
+Logging is optimized for production:
+
+```typescript
+// ✅ Good - check happens before string operations
+if (this.shouldLog('verbose')) {
+  logger.debug(`Expensive operation: ${JSON.stringify(bigObject)}`);
+}
+
+// ❌ Bad - string created even if logging disabled
+logger.debug(`Expensive operation: ${JSON.stringify(bigObject)}`);
+```
+
+The SDK uses the first pattern internally.
+
+## Next Steps
+
+- [API Reference](./07-api-reference.mdx)
+- [Hooks Reference](./08-hooks-reference.mdx)
+- [Advanced Usage](./09-advanced.mdx)