@teardown/react-native 2.0.2 → 2.0.9

package/docs/04-force-updates.mdx

@@ -1,339 +0,0 @@
-# Force Updates
-
-Manage app version requirements and force updates with the ForceUpdateClient.
-
-## Overview
-
-The ForceUpdateClient automatically:
-- Checks app version against your backend
-- Monitors app state changes (background/foreground)
-- Throttles version checks to prevent excessive API calls
-- Emits version status changes for UI updates
-
-## Version Status Types
-
-```typescript
-type VersionStatus = 
-  | { type: "initializing" }      // Initial state
-  | { type: "checking" }           // Currently checking version
-  | { type: "up_to_date" }        // Version is current
-  | { type: "update_available" }  // New version available (optional)
-  | { type: "update_recommended" } // Update is recommended
-  | { type: "update_required" }   // Update is required
-  | { type: "disabled" }          // Version/build is disabled
-```
-
-## Using Force Updates
-
-### Access via Hook
-
-```typescript
-import { useForceUpdate } from '@teardown/react-native';
-
-function MyComponent() {
-  const { versionStatus, isUpdateRequired, isUpdateAvailable } = useForceUpdate();
-  
-  if (isUpdateRequired) {
-    return <UpdateRequiredScreen />;
-  }
-  
-  if (isUpdateAvailable) {
-    return <UpdateAvailableBanner />;
-  }
-  
-  return <App />;
-}
-```
-
-### Hook Return Value
-
-```typescript
-type UseForceUpdateResult = {
-  versionStatus: VersionStatus;
-  isUpdateAvailable: boolean;    // true if any update exists
-  isUpdateRequired: boolean;     // true if update is required
-}
-```
-
-## Configuration
-
-Configure force update behavior when initializing TeardownCore:
-
-```typescript
-const teardown = new TeardownCore({
-  // ... other options
-  forceUpdate: {
-    // Minimum time between foreground checks (default: 30000ms = 30s)
-    throttleMs: 30_000,
-    
-    // Minimum time since last successful check (default: 300000ms = 5min)
-    checkCooldownMs: 300_000,
-  },
-});
-```
-
-### Configuration Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `throttleMs` | 30000 | Min milliseconds between foreground transitions before checking |
-| `checkCooldownMs` | 300000 | Min milliseconds since last successful check before re-checking |
-
-## How It Works
-
-### Automatic Checks
-
-The SDK automatically checks version in these scenarios:
-
-1. **Initial Identification**
-   - When the SDK initializes
-   - When `identify()` is called
-   
-2. **App Foreground**
-   - When app returns from background
-   - Subject to throttle and cooldown timers
-
-### Check Flow
-
-```
-App goes to foreground
-  ↓
-Check throttle timer (last foreground < throttleMs ago?)
-  ↓ No
-Check cooldown timer (last check < checkCooldownMs ago?)
-  ↓ No
-Call identify() to refresh version status
-  ↓
-Update version status
-  ↓
-Emit VERSION_STATUS_CHANGED event
-```
-
-### Throttle vs Cooldown
-
-- **Throttle**: Prevents checks when rapidly switching apps
-- **Cooldown**: Prevents excessive API calls even with long background periods
-
-Example:
-```typescript
-// User switches between apps rapidly:
-// 10:00:00 - Foreground (check)
-// 10:00:05 - Foreground (throttled - too soon)
-// 10:00:45 - Foreground (check - passed throttle)
-// 10:00:50 - Foreground (cooldown - last check < 5min ago)
-```
-
-## Building Update UI
-
-### Required Update Screen
-
-```typescript
-function UpdateRequiredScreen() {
-  const { isUpdateRequired, versionStatus } = useForceUpdate();
-  
-  if (!isUpdateRequired) return null;
-  
-  return (
-    <View style={styles.container}>
-      <Text>Update Required</Text>
-      <Text>Please update to continue using the app</Text>
-      <Button 
-        title="Update Now" 
-        onPress={() => Linking.openURL('market://details?id=com.yourapp')}
-      />
-    </View>
-  );
-}
-```
-
-### Optional Update Banner
-
-```typescript
-function UpdateBanner() {
-  const { isUpdateAvailable, isUpdateRequired } = useForceUpdate();
-  const [dismissed, setDismissed] = useState(false);
-  
-  // Don't show if required (use dedicated screen)
-  if (isUpdateRequired || !isUpdateAvailable || dismissed) {
-    return null;
-  }
-  
-  return (
-    <View style={styles.banner}>
-      <Text>A new version is available</Text>
-      <Button title="Update" onPress={handleUpdate} />
-      <Button title="Later" onPress={() => setDismissed(true)} />
-    </View>
-  );
-}
-```
-
-### Full-Screen Takeover
-
-Example from the SDK:
-
-```typescript
-function FullscreenTakeover() {
-  const { isUpdateRequired } = useForceUpdate();
-  
-  if (!isUpdateRequired) return null;
-  
-  return (
-    <Modal visible={true} animationType="fade">
-      <UpdateRequiredScreen />
-    </Modal>
-  );
-}
-
-// In your layout
-<TeardownProvider core={teardown}>
-  <App />
-  <FullscreenTakeover />
-</TeardownProvider>
-```
-
-## Listening to Status Changes
-
-### Via Hook (Recommended)
-
-```typescript
-const { versionStatus } = useForceUpdate();
-
-useEffect(() => {
-  console.log('Version status:', versionStatus.type);
-}, [versionStatus]);
-```
-
-### Via Event Listener
-
-```typescript
-import { useTeardown } from '@teardown/react-native';
-
-function MyComponent() {
-  const { core } = useTeardown();
-  
-  useEffect(() => {
-    const unsubscribe = core.forceUpdate.onVersionStatusChange((status) => {
-      console.log('Status changed:', status.type);
-      
-      if (status.type === 'update_required') {
-        // Show update UI
-      }
-    });
-    
-    return unsubscribe;
-  }, []);
-}
-```
-
-## Getting Current Status
-
-```typescript
-// Via hook (reactive)
-const { versionStatus } = useForceUpdate();
-
-// Via client (direct)
-const status = core.forceUpdate.getVersionStatus();
-```
-
-## Platform-Specific Store Links
-
-### iOS
-
-```typescript
-const APP_STORE_ID = 'your-app-id';
-const APP_STORE_URL = `https://apps.apple.com/app/id${APP_STORE_ID}`;
-
-<Button 
-  title="Update" 
-  onPress={() => Linking.openURL(APP_STORE_URL)} 
-/>
-```
-
-### Android
-
-```typescript
-const PACKAGE_NAME = 'com.yourcompany.yourapp';
-const PLAY_STORE_URL = `market://details?id=${PACKAGE_NAME}`;
-const PLAY_STORE_WEB = `https://play.google.com/store/apps/details?id=${PACKAGE_NAME}`;
-
-const handleUpdate = async () => {
-  const supported = await Linking.canOpenURL(PLAY_STORE_URL);
-  const url = supported ? PLAY_STORE_URL : PLAY_STORE_WEB;
-  Linking.openURL(url);
-};
-```
-
-### Cross-Platform
-
-```typescript
-import { Platform, Linking } from 'react-native';
-
-const STORE_URL = Platform.select({
-  ios: 'https://apps.apple.com/app/id123456789',
-  android: 'market://details?id=com.yourapp',
-  default: 'https://yourapp.com/download',
-});
-
-<Button 
-  title="Update Now" 
-  onPress={() => Linking.openURL(STORE_URL)} 
-/>
-```
-
-## Version Status in Backend
-
-Version status is determined by your backend configuration:
-
-- `UP_TO_DATE`: Current version matches or is newer than minimum
-- `UPDATE_AVAILABLE`: New version exists, but not required
-- `UPDATE_RECOMMENDED`: New version exists, recommended to update
-- `UPDATE_REQUIRED`: Current version is below minimum required
-- `DISABLED`: This specific version/build is disabled
-
-Configure these in your Teardown dashboard under project settings.
-
-## Best Practices
-
-### 1. Use Full-Screen Takeover for Required Updates
-
-```typescript
-// ✅ Good - blocks app usage
-{isUpdateRequired && <UpdateRequiredModal />}
-
-// ❌ Bad - user can dismiss and continue with outdated version
-{isUpdateRequired && <UpdateBanner dismissible />}
-```
-
-### 2. Make Optional Updates Dismissible
-
-```typescript
-// ✅ Good - user can choose when to update
-{isUpdateAvailable && !isUpdateRequired && <DismissibleBanner />}
-```
-
-### 3. Respect User Decisions
-
-```typescript
-// ✅ Good - remember dismissal for session
-const [dismissed, setDismissed] = useState(false);
-
-// ❌ Bad - annoying the user every render
-{isUpdateAvailable && <Banner />}
-```
-
-### 4. Provide Clear CTAs
-
-```typescript
-// ✅ Good - clear action
-<Button title="Update Now" onPress={openStore} />
-
-// ❌ Bad - vague
-<Button title="OK" onPress={openStore} />
-```
-
-## Next Steps
-
-- [Device Information](./05-device-info.mdx)
-- [Hooks Reference](./08-hooks-reference.mdx)
-- [Advanced Usage](./09-advanced.mdx)

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)