@teardown/react-native 2.0.2 → 2.0.9

package/docs/02-core-concepts.mdx

@@ -1,188 +0,0 @@
-# Core Concepts
-
-Understanding the architecture and design principles of the Teardown SDK.
-
-## Architecture Overview
-
-The Teardown SDK is built around a central `TeardownCore` instance that manages several specialized clients:
-
-```
-TeardownCore
-├── IdentityClient    - User and device identity
-├── ForceUpdateClient - Version management
-├── DeviceClient      - Device information
-├── StorageClient     - Persistent storage
-├── LoggingClient     - Structured logging
-└── ApiClient         - API communication
-```
-
-## Core Principles
-
-### 1. Single Source of Truth
-
-The `TeardownCore` instance is your single entry point to all SDK functionality. It's initialized once and passed through your app via the `TeardownProvider`.
-
-```typescript
-const teardown = new TeardownCore({...});
-
-// Use throughout your app
-<TeardownProvider core={teardown}>
-  <App />
-</TeardownProvider>
-```
-
-### 2. Automatic Initialization
-
-The SDK automatically initializes when the `TeardownProvider` mounts:
-
-- Loads persisted session data
-- Identifies the device
-- Checks version status
-- Subscribes to app lifecycle events
-
-### 3. Reactive State Management
-
-All clients use event emitters to notify of state changes. React hooks automatically subscribe to these events:
-
-```typescript
-// Hooks automatically subscribe and cleanup
-const session = useSession();
-const { versionStatus } = useForceUpdate();
-```
-
-### 4. Namespaced Storage
-
-Each client gets its own namespaced storage to prevent key collisions:
-
-```typescript
-// Storage is automatically namespaced
-teardown:v1:identity:IDENTIFY_STATE
-teardown:v1:device:deviceId
-teardown:v1:version:VERSION_STATUS
-```
-
-## Client Responsibilities
-
-### IdentityClient
-
-Manages device and user identity:
-
-- Generates unique device IDs
-- Tracks user sessions
-- Persists authentication state
-- Provides persona management (anonymous or identified users)
-
-### ForceUpdateClient
-
-Handles version management:
-
-- Checks app version against backend
-- Monitors app state changes
-- Throttles version checks
-- Emits update status changes
-
-### DeviceClient
-
-Collects device information:
-
-- OS version and platform
-- Device model and manufacturer
-- App version and build number
-- Uses platform adapters for consistency
-
-### StorageClient
-
-Provides persistent storage:
-
-- Namespaced key-value storage
-- Platform-agnostic interface
-- Support for multiple adapters (MMKV, AsyncStorage, etc.)
-- Automatic cleanup on shutdown
-
-### LoggingClient
-
-Structured logging system:
-
-- Configurable log levels
-- Named loggers for each client
-- Console binding preservation
-- Debug mode support
-
-### ApiClient
-
-Handles API communication:
-
-- Type-safe API client
-- Automatic header injection
-- Request/response logging
-- Error handling
-
-## Lifecycle Management
-
-### Initialization
-
-```typescript
-const teardown = new TeardownCore({...});
-// Automatically initializes identity client
-```
-
-### Runtime
-
-The SDK operates automatically:
-- Listens for app state changes
-- Checks version on foreground
-- Persists state changes
-
-### Cleanup
-
-```typescript
-// Automatic cleanup when provider unmounts
-useEffect(() => {
-  return () => {
-    core.shutdown();
-  };
-}, [core]);
-```
-
-## State Persistence
-
-All critical state is automatically persisted:
-
-```typescript
-// Identity state
-{ type: "identified", session: {...}, version_info: {...} }
-
-// Version status
-{ type: "up_to_date" | "update_available" | "update_required" | ... }
-```
-
-State is restored on app restart for seamless user experience.
-
-## Error Handling
-
-The SDK uses `AsyncResult` pattern for predictable error handling:
-
-```typescript
-const result = await core.identity.identify({...});
-
-if (result.success) {
-  // Handle success
-  console.log(result.data);
-} else {
-  // Handle error
-  console.error(result.error);
-}
-```
-
-## Type Safety
-
-Full TypeScript support with:
-- Runtime validation using Zod schemas
-- Discriminated unions for state types
-- Exported types for all public APIs
-
-## Next Steps
-
-- [Identity & Authentication](./03-identity.mdx)
-- [Force Updates](./04-force-updates.mdx)
-- [API Reference](./07-api-reference.mdx)

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)