@teardown/react-native 2.0.24 → 2.0.28

package/docs/force-updates.mdx

@@ -0,0 +1,185 @@
+---
+title: Force Updates
+description: Manage app version checking and force update flows.
+icon: RefreshCw
+---
+
+The Force Update client automatically checks your app version against your configured release policy and can require users to update.
+
+## Overview
+
+Force updates work by:
+
+1. Checking app version on identify
+2. Checking again when app returns to foreground
+3. Emitting status changes your app can respond to
+
+## Version Status
+
+```typescript
+type VersionStatus =
+  | { type: 'initializing' }   // SDK starting up
+  | { type: 'checking' }       // Version check in progress
+  | { type: 'up_to_date' }     // Current version is valid
+  | { type: 'update_available' }   // Optional update exists
+  | { type: 'update_recommended' } // Recommended update exists
+  | { type: 'update_required' }    // Must update to continue
+  | { type: 'disabled' }       // Version/build has been disabled
+```
+
+## Basic Usage
+
+### Using the Hook
+
+```typescript
+import { useForceUpdate } from '@teardown/react-native';
+
+function App() {
+  const { versionStatus, isUpdateRequired, isUpdateAvailable, isUpdateRecommended } = useForceUpdate();
+
+  if (isUpdateRequired) {
+    return <ForceUpdateModal />;
+  }
+
+  if (isUpdateRecommended) {
+    return (
+      <>
+        <UpdateBanner onDismiss={() => {}} />
+        <MainApp />
+      </>
+    );
+  }
+
+  return <MainApp />;
+}
+```
+
+### Hook Return Values
+
+```typescript
+interface UseForceUpdateResult {
+  versionStatus: VersionStatus;      // Full status object
+  isUpdateAvailable: boolean;        // Any update exists (available, recommended, or required)
+  isUpdateRecommended: boolean;      // Update is recommended but not required
+  isUpdateRequired: boolean;         // Update is mandatory
+}
+```
+
+## Configuration
+
+Configure force update behavior in `TeardownCore`:
+
+```typescript
+const teardown = new TeardownCore({
+  // ...other options
+  forceUpdate: {
+    checkIntervalMs: 300_000,        // 5 minutes (default)
+    checkOnForeground: true,         // Check when app foregrounds (default: true)
+    identifyAnonymousDevice: false,  // Check even when not identified (default: false)
+  },
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `checkIntervalMs` | number | 300000 | Minimum time between version checks. Use `0` for every foreground, `-1` to disable. Values below 30s are clamped to 30s. |
+| `checkOnForeground` | boolean | true | Check version when app returns to foreground |
+| `identifyAnonymousDevice` | boolean | false | Check version even when user is not identified |
+
+## Direct API Access
+
+### Get Current Status
+
+```typescript
+const status = core.forceUpdate.getVersionStatus();
+```
+
+### Subscribe to Changes
+
+```typescript
+const unsubscribe = core.forceUpdate.onVersionStatusChange((status) => {
+  if (status.type === 'update_required') {
+    // Show force update modal
+  }
+});
+
+// Cleanup
+unsubscribe();
+```
+
+## Implementation Patterns
+
+### Force Update Modal
+
+```tsx
+function ForceUpdateModal() {
+  const handleUpdate = () => {
+    // Open app store
+    Linking.openURL('https://apps.apple.com/app/your-app');
+  };
+
+  return (
+    <Modal visible>
+      <View style={styles.container}>
+        <Text>Update Required</Text>
+        <Text>Please update to continue using the app.</Text>
+        <Button onPress={handleUpdate} title="Update Now" />
+      </View>
+    </Modal>
+  );
+}
+```
+
+### Soft Update Banner
+
+```tsx
+function UpdateBanner({ onDismiss }: { onDismiss: () => void }) {
+  const { isUpdateRecommended } = useForceUpdate();
+
+  if (!isUpdateRecommended) return null;
+
+  return (
+    <View style={styles.banner}>
+      <Text>A new version is available</Text>
+      <Button onPress={onDismiss} title="Later" />
+      <Button onPress={() => Linking.openURL('...')} title="Update" />
+    </View>
+  );
+}
+```
+
+### Root Level Guard
+
+```tsx
+function RootLayout() {
+  const { isUpdateRequired } = useForceUpdate();
+
+  if (isUpdateRequired) {
+    return <ForceUpdateScreen />;
+  }
+
+  return <Stack />;
+}
+```
+
+## How It Works
+
+1. **On Identify** - Version status is returned from the identify API
+2. **On Foreground** - If `checkOnForeground` is true and interval has passed, re-identifies to check version
+3. **State Persistence** - Last known status is cached for offline access
+4. **Event Emission** - Status changes trigger subscribers and hook re-renders
+
+## Dashboard Configuration
+
+Configure version policies in the [Teardown Dashboard](https://dash.teardown.dev):
+
+1. Go to your project settings
+2. Navigate to "Releases" or "Version Management"
+3. Set policies for each version/build:
+   - **Active** - Version is valid
+   - **Update Available** - Optional update exists
+   - **Update Recommended** - Soft nudge to update
+   - **Update Required** - Force update
+   - **Disabled** - Version blocked entirely

package/docs/getting-started.mdx

@@ -0,0 +1,156 @@
+---
+title: Getting Started
+description: Install and configure the Teardown SDK for React Native.
+icon: Rocket
+---
+
+## Installation
+
+Install the core package:
+
+```bash
+bun add @teardown/react-native
+# or
+npm install @teardown/react-native
+# or
+yarn add @teardown/react-native
+```
+
+### Peer Dependencies
+
+Choose adapters based on your project setup:
+
+**Expo projects:**
+```bash
+npx expo install expo-device expo-application
+```
+
+**Bare React Native projects:**
+```bash
+npm install react-native-device-info
+```
+
+**Storage (choose one):**
+```bash
+# MMKV (recommended - faster, synchronous)
+npm install react-native-mmkv
+
+# or AsyncStorage (broader compatibility)
+npm install @react-native-async-storage/async-storage
+```
+
+## Getting Your Credentials
+
+1. Sign up or log in at [dash.teardown.dev](https://dash.teardown.dev)
+2. Create or select a project
+3. Copy your `org_id`, `project_id`, and `api_key` from project settings
+
+## Setup
+
+### 1. Create SDK Configuration
+
+Create a file to initialize the Teardown SDK (e.g., `lib/teardown.ts`):
+
+**Expo Setup:**
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { ExpoDeviceAdapter } from '@teardown/react-native/adapters/expo';
+import { MMKVStorageAdapter } from '@teardown/react-native/adapters/mmkv';
+
+export const teardown = new TeardownCore({
+  org_id: 'your-org-id',
+  project_id: 'your-project-id',
+  api_key: 'your-api-key',
+  storageAdapter: new MMKVStorageAdapter(),
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+```
+
+**Bare React Native Setup:**
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { DeviceInfoAdapter } from '@teardown/react-native/adapters/device-info';
+import { AsyncStorageAdapter } from '@teardown/react-native/adapters/async-storage';
+
+export const teardown = new TeardownCore({
+  org_id: 'your-org-id',
+  project_id: 'your-project-id',
+  api_key: 'your-api-key',
+  storageAdapter: new AsyncStorageAdapter(),
+  deviceAdapter: new DeviceInfoAdapter(),
+});
+```
+
+### 2. Wrap Your App
+
+In your root layout file (e.g., `app/_layout.tsx` for Expo Router):
+
+```typescript
+import { TeardownProvider } from '@teardown/react-native';
+import { teardown } from '../lib/teardown';
+
+export default function RootLayout() {
+  return (
+    <TeardownProvider core={teardown}>
+      <YourApp />
+    </TeardownProvider>
+  );
+}
+```
+
+### 3. Use in Components
+
+```typescript
+import { useTeardown, useSession, useForceUpdate } from '@teardown/react-native';
+
+function MyComponent() {
+  const { core } = useTeardown();
+  const session = useSession();
+  const { isUpdateRequired } = useForceUpdate();
+
+  const handleLogin = async () => {
+    const result = await core.identity.identify({
+      user_id: 'user-123',
+      email: 'user@example.com',
+    });
+
+    if (result.success) {
+      console.log('Session:', result.data.session_id);
+    }
+  };
+
+  if (isUpdateRequired) {
+    return <UpdateRequiredScreen />;
+  }
+
+  return <Button onPress={handleLogin} title="Login" />;
+}
+```
+
+## Configuration Options
+
+### TeardownCore Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `org_id` | string | Yes | Organization ID from dashboard |
+| `project_id` | string | Yes | Project ID from dashboard |
+| `api_key` | string | Yes | API key from dashboard |
+| `storageAdapter` | StorageAdapter | Yes | Storage adapter instance ([see storage](/docs/react-native/adapters/storage)) |
+| `deviceAdapter` | DeviceInfoAdapter | Yes | Device info adapter ([see device](/docs/react-native/adapters/device)) |
+| `forceUpdate` | object | No | Force update configuration ([see force-updates](/docs/react-native/force-updates)) |
+
+## Available Adapters
+
+| Adapter | Import Path | Use Case |
+|---------|-------------|----------|
+| `ExpoDeviceAdapter` | `@teardown/react-native/adapters/expo` | Expo projects |
+| `DeviceInfoAdapter` | `@teardown/react-native/adapters/device-info` | Bare RN projects |
+| `MMKVStorageAdapter` | `@teardown/react-native/adapters/mmkv` | Fast sync storage |
+| `AsyncStorageAdapter` | `@teardown/react-native/adapters/async-storage` | Standard async storage |
+
+## Next Steps
+
+- [Core Concepts](/docs/react-native/core-concepts) - Understand the SDK architecture
+- [Identity](/docs/react-native/identity) - Learn about user identification
+- [Force Updates](/docs/react-native/force-updates) - Configure version management

package/docs/hooks-reference.mdx

@@ -0,0 +1,232 @@
+---
+title: Hooks Reference
+description: React hooks for the Teardown SDK.
+icon: Anchor
+---
+
+The SDK provides React hooks for reactive access to SDK state.
+
+## TeardownProvider
+
+Context provider that makes the SDK available to all child components.
+
+```tsx
+import { TeardownProvider } from '@teardown/react-native';
+import { teardown } from './lib/teardown';
+
+function App() {
+  return (
+    <TeardownProvider core={teardown}>
+      <YourApp />
+    </TeardownProvider>
+  );
+}
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `core` | `TeardownCore` | Yes | Initialized TeardownCore instance |
+| `children` | `ReactNode` | Yes | Child components |
+
+---
+
+## useTeardown
+
+Access the TeardownCore instance from any component.
+
+```typescript
+import { useTeardown } from '@teardown/react-native';
+
+function MyComponent() {
+  const { core } = useTeardown();
+
+  // Access clients
+  await core.identity.identify({ user_id: '123' });
+  core.setLogLevel('verbose');
+}
+```
+
+### Returns
+
+```typescript
+interface UseTeardownResult {
+  core: TeardownCore;
+}
+```
+
+### Throws
+
+Throws an error if used outside of `TeardownProvider`.
+
+---
+
+## useSession
+
+Get the current session with reactive updates.
+
+```typescript
+import { useSession } from '@teardown/react-native';
+
+function ProfileScreen() {
+  const session = useSession();
+
+  if (!session) {
+    return <LoginScreen />;
+  }
+
+  return (
+    <View>
+      <Text>User ID: {session.user_id}</Text>
+      <Text>Device ID: {session.device_id}</Text>
+      <Text>Session ID: {session.session_id}</Text>
+    </View>
+  );
+}
+```
+
+### Returns
+
+```typescript
+type UseSessionResult = Session | null;
+
+interface Session {
+  session_id: string;
+  device_id: string;
+  user_id: string;
+  token: string;
+}
+```
+
+Returns `null` if not identified.
+
+### Reactivity
+
+The hook subscribes to `identity.onIdentifyStateChange()` and re-renders when:
+- User identifies (session available)
+- User resets (session becomes null)
+- Session refreshes (new session data)
+
+---
+
+## useForceUpdate
+
+Get version status with reactive updates.
+
+```typescript
+import { useForceUpdate } from '@teardown/react-native';
+
+function App() {
+  const {
+    versionStatus,
+    isUpdateAvailable,
+    isUpdateRecommended,
+    isUpdateRequired
+  } = useForceUpdate();
+
+  if (isUpdateRequired) {
+    return <ForceUpdateModal />;
+  }
+
+  if (isUpdateRecommended) {
+    return (
+      <>
+        <UpdateBanner />
+        <MainApp />
+      </>
+    );
+  }
+
+  return <MainApp />;
+}
+```
+
+### Returns
+
+```typescript
+interface UseForceUpdateResult {
+  /** Full version status object */
+  versionStatus: VersionStatus;
+  /** Any update exists (available, recommended, or required) */
+  isUpdateAvailable: boolean;
+  /** Update is recommended but not required */
+  isUpdateRecommended: boolean;
+  /** Update is mandatory */
+  isUpdateRequired: boolean;
+}
+```
+
+### Convenience Booleans
+
+| Property | True When |
+|----------|-----------|
+| `isUpdateRequired` | `versionStatus.type === 'update_required'` |
+| `isUpdateRecommended` | `versionStatus.type === 'update_recommended'` |
+| `isUpdateAvailable` | Any of: `update_available`, `update_recommended`, `update_required` |
+
+### Reactivity
+
+The hook subscribes to `forceUpdate.onVersionStatusChange()` and re-renders when:
+- Version check completes
+- Status changes (e.g., from up_to_date to update_required)
+- App foregrounds (triggers new check)
+
+---
+
+## Usage Patterns
+
+### Conditional Rendering
+
+```tsx
+function RootLayout() {
+  const session = useSession();
+  const { isUpdateRequired } = useForceUpdate();
+
+  if (isUpdateRequired) {
+    return <ForceUpdateScreen />;
+  }
+
+  if (!session) {
+    return <AuthStack />;
+  }
+
+  return <MainStack />;
+}
+```
+
+### Loading States
+
+```tsx
+function App() {
+  const session = useSession();
+  const { versionStatus } = useForceUpdate();
+
+  // SDK is initializing
+  if (versionStatus.type === 'initializing') {
+    return <SplashScreen />;
+  }
+
+  // Checking version
+  if (versionStatus.type === 'checking') {
+    return <LoadingScreen message="Checking for updates..." />;
+  }
+
+  return <MainApp />;
+}
+```
+
+### Accessing Core Methods
+
+```tsx
+function LogoutButton() {
+  const { core } = useTeardown();
+
+  const handleLogout = () => {
+    core.identity.reset();
+    // Session will become null, useSession will re-render
+  };
+
+  return <Button onPress={handleLogout} title="Logout" />;
+}
+```