@teardown/react-native 2.0.4 → 2.0.10

package/docs/05-device-info.mdx

@@ -1,324 +0,0 @@
-# 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

@@ -1,345 +0,0 @@
-# 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)