@teardown/react-native 2.0.4 → 2.0.10

package/docs/03-identity.mdx

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

@@ -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)