@teardown/react-native 1.2.39 → 2.0.1

package/docs/03-identity.mdx

@@ -0,0 +1,301 @@
+# Identity & Authentication
+
+Manage user sessions and device identity with the IdentityClient.
+
+## Overview
+
+The IdentityClient handles:
+- Device fingerprinting
+- User identification and session management
+- Anonymous and identified user states
+- Automatic session persistence
+
+## Identity States
+
+The SDK uses a discriminated union to represent identity states:
+
+```typescript
+type IdentifyState = 
+  | { type: "unidentified" }
+  | { type: "identifying" }
+  | { type: "identified", session: Session, version_info: {...} }
+```
+
+### State Transitions
+
+```
+unidentified → identifying → identified
+     ↑                           ↓
+     └───────── reset() ─────────┘
+```
+
+## Using the Identity Client
+
+### Access via Hook
+
+```typescript
+import { useSession } from '@teardown/react-native';
+
+function MyComponent() {
+  const session = useSession();
+  
+  if (!session) {
+    return <LoginScreen />;
+  }
+  
+  return <div>Welcome, {session.persona_id}</div>;
+}
+```
+
+### Access via Core
+
+```typescript
+import { useTeardown } from '@teardown/react-native';
+
+function MyComponent() {
+  const { core } = useTeardown();
+  
+  const handleLogin = async () => {
+    const result = await core.identity.identify({
+      user_id: 'user-123',
+      email: 'user@example.com',
+      name: 'John Doe',
+    });
+  };
+}
+```
+
+## Identifying Users
+
+### Anonymous Identification
+
+Automatically happens on SDK initialization:
+
+```typescript
+// Happens automatically when TeardownProvider mounts
+await core.identity.identify();
+```
+
+This creates an anonymous session with:
+- Unique device ID
+- Session ID
+- Device information
+- Version status
+
+### Identified Users
+
+Identify users with their information:
+
+```typescript
+const result = await core.identity.identify({
+  user_id: 'user-123',
+  email: 'user@example.com',
+  name: 'John Doe',
+});
+
+if (result.success) {
+  console.log('Session:', result.data.session_id);
+  console.log('Device:', result.data.device_id);
+  console.log('Persona:', result.data.persona_id);
+  console.log('Token:', result.data.token);
+}
+```
+
+### Persona Object
+
+```typescript
+type Persona = {
+  user_id?: string;
+  email?: string;
+  name?: string;
+}
+```
+
+All fields are optional. You can identify with just an email, just a user_id, or any combination.
+
+## Session Management
+
+### Getting Current Session
+
+```typescript
+// Via hook (reactive)
+const session = useSession();
+
+// Via client (direct)
+const session = core.identity.getSessionState();
+```
+
+### Session Object
+
+```typescript
+type Session = {
+  session_id: string;   // Unique session identifier
+  device_id: string;    // Unique device identifier
+  persona_id: string;   // User/persona identifier
+  token: string;        // Authentication token
+}
+```
+
+### Refreshing Session
+
+Re-identify the current persona to refresh session data:
+
+```typescript
+const result = await core.identity.refresh();
+
+if (result.success) {
+  console.log('Session refreshed');
+}
+```
+
+Note: `refresh()` only works if already identified.
+
+## Logging Out
+
+Reset the identity state to anonymous:
+
+```typescript
+core.identity.reset();
+```
+
+This will:
+- Clear persisted session data
+- Set state to "unidentified"
+- Emit state change event
+- Trigger re-identification on next app open
+
+## Listening to State Changes
+
+### Via Hook
+
+```typescript
+const session = useSession();
+
+// Automatically re-renders on state changes
+useEffect(() => {
+  console.log('Session changed:', session);
+}, [session]);
+```
+
+### Via Event Listener
+
+```typescript
+useEffect(() => {
+  const unsubscribe = core.identity.onIdentifyStateChange((state) => {
+    console.log('State changed:', state.type);
+    
+    if (state.type === 'identified') {
+      console.log('User session:', state.session);
+    }
+  });
+  
+  return unsubscribe;
+}, []);
+```
+
+## Identity State
+
+Get the full identity state (not just session):
+
+```typescript
+const state = core.identity.getIdentifyState();
+
+switch (state.type) {
+  case 'unidentified':
+    // No session yet
+    break;
+  case 'identifying':
+    // Identifying in progress
+    break;
+  case 'identified':
+    // Has session and version info
+    console.log(state.session);
+    console.log(state.version_info);
+    break;
+}
+```
+
+## Error Handling
+
+All identity operations return `AsyncResult`:
+
+```typescript
+const result = await core.identity.identify({
+  email: 'invalid-email',
+});
+
+if (!result.success) {
+  console.error('Identification failed:', result.error);
+  // Handle error (show message, retry, etc.)
+}
+```
+
+Common errors:
+- Network errors
+- Invalid API credentials
+- Validation errors (422)
+- Server errors
+
+## Best Practices
+
+### 1. Let Auto-Initialization Happen
+
+```typescript
+// ✅ Good - automatic anonymous identification
+<TeardownProvider core={teardown}>
+  <App />
+</TeardownProvider>
+
+// ❌ Bad - don't manually call identify on mount
+useEffect(() => {
+  core.identity.identify();
+}, []);
+```
+
+### 2. Identify on Login/Signup
+
+```typescript
+const handleLogin = async (email: string, password: string) => {
+  // Your auth logic
+  const user = await login(email, password);
+  
+  // Identify with Teardown
+  await core.identity.identify({
+    user_id: user.id,
+    email: user.email,
+    name: user.name,
+  });
+};
+```
+
+### 3. Reset on Logout
+
+```typescript
+const handleLogout = async () => {
+  // Your logout logic
+  await logout();
+  
+  // Reset Teardown identity
+  core.identity.reset();
+};
+```
+
+### 4. Use the Hook for Reactive UI
+
+```typescript
+function UserProfile() {
+  const session = useSession();
+  
+  if (!session) {
+    return <LoginPrompt />;
+  }
+  
+  return <Profile personaId={session.persona_id} />;
+}
+```
+
+## Next Steps
+
+- [Force Updates](./04-force-updates.mdx)
+- [Device Information](./05-device-info.mdx)
+- [API Reference](./07-api-reference.mdx)

package/docs/04-force-updates.mdx

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