@teardown/react-native 2.0.0 → 2.0.2

package/README.md

@@ -28,32 +28,46 @@ bun add react-native-device-info
 
 ## Quick Start
 
+### 1. Initialize the SDK
+
 ```tsx
-import { TeardownCore, TeardownProvider, useTeardown } from '@teardown/react-native';
-
-// Initialize
-const teardown = new TeardownCore({
-  api: {
-    api_key: 'your-api-key',
-    org_id: 'your-org-id',
-    project_id: 'your-project-id',
-    environment_slug: 'production',
+import { TeardownCore } from '@teardown/react-native';
+import { ExpoDeviceAdapter } from '@teardown/react-native/expo';
+import { createMMKVStorageFactory } from '@teardown/react-native/mmkv';
+
+export const teardown = new TeardownCore({
+  org_id: 'your-org-id',
+  project_id: 'your-project-id',
+  api_key: 'your-api-key',
+  storageFactory: createMMKVStorageFactory(),
+  deviceAdapter: new ExpoDeviceAdapter(),
+  forceUpdate: {
+    throttleMs: 30_000, // 30 seconds
+    checkCooldownMs: 10_000, // 10 seconds
   },
-  storage: { /* ... */ },
-  device: { /* ... */ },
-  identity: { identifyOnLoad: true },
 });
+```
+
+### 2. Wrap your app with TeardownProvider
+
+```tsx
+import { TeardownProvider } from '@teardown/react-native';
+import { teardown } from './lib/teardown';
 
-// Wrap your app
-export default function App() {
+export default function RootLayout() {
   return (
     <TeardownProvider core={teardown}>
       <YourApp />
     </TeardownProvider>
   );
 }
+```
+
+### 3. Use in components
+
+```tsx
+import { useTeardown } from '@teardown/react-native';
 
-// Use in components
 function YourComponent() {
   const { core } = useTeardown();
   
@@ -78,10 +92,10 @@ Complete documentation is available in the [docs](./docs) folder:
 - [Force Updates](./docs/04-force-updates.mdx) - Version management
 - [Device Information](./docs/05-device-info.mdx) - Device data collection
 - [Storage](./docs/06-storage.mdx) - Persistent storage
-- [Logging](./docs/06-logging.mdx) - Structured logging
-- [API Reference](./docs/07-api-reference.mdx) - Complete API docs
-- [Hooks Reference](./docs/08-hooks-reference.mdx) - React hooks
-- [Advanced Usage](./docs/09-advanced.mdx) - Advanced patterns
+- [Logging](./docs/07-logging.mdx) - Structured logging
+- [API Reference](./docs/08-api-reference.mdx) - Complete API docs
+- [Hooks Reference](./docs/09-hooks-reference.mdx) - React hooks
+- [Advanced Usage](./docs/10-advanced.mdx) - Advanced patterns
 
 ## License
 

package/docs/01-getting-started.mdx

@@ -0,0 +1,147 @@
+# Getting Started
+
+This guide will walk you through installing and setting up the Teardown SDK in your React Native or Expo application.
+
+## Installation
+
+Install the core package:
+
+```bash
+bun add @teardown/react-native
+```
+
+### Peer Dependencies
+
+Install required peer dependencies:
+
+```bash
+bun add react react-native zod
+```
+
+### Platform Adapters
+
+#### For Expo Projects
+
+```bash
+bun add expo-application expo-device expo-updates
+```
+
+#### For React Native CLI Projects
+
+```bash
+bun add react-native-device-info
+```
+
+### Storage Adapter
+
+Install MMKV for fast, encrypted storage:
+
+```bash
+bun add react-native-mmkv
+```
+
+## Initial Setup
+
+### 1. Create SDK Configuration
+
+Create a file to initialize the Teardown SDK (e.g., `lib/teardown.ts`):
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { ExpoDeviceAdapter } from '@teardown/react-native/expo';
+import { createMMKVStorageFactory } from '@teardown/react-native/mmkv';
+
+export const teardown = new TeardownCore({
+  org_id: 'your-org-id',
+  project_id: 'your-project-id',
+  api_key: 'your-api-key',
+  storageFactory: createMMKVStorageFactory(),
+  deviceAdapter: new ExpoDeviceAdapter(),
+  forceUpdate: {
+    throttleMs: 30_000, // Check every 30 seconds when app returns to foreground
+    checkCooldownMs: 300_000, // Wait 5 minutes between checks
+  },
+});
+```
+
+### 2. Wrap Your App with TeardownProvider
+
+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>
+  );
+}
+```
+
+For traditional React Native:
+
+```typescript
+import { TeardownProvider } from '@teardown/react-native';
+import { teardown } from './lib/teardown';
+
+export default function App() {
+  return (
+    <TeardownProvider core={teardown}>
+      <YourNavigationStack />
+    </TeardownProvider>
+  );
+}
+```
+
+### 3. Use the SDK in Your Components
+
+```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',
+    });
+    
+    if (result.success) {
+      console.log('User identified:', result.data);
+    }
+  };
+  
+  return <Button onPress={handleLogin} title="Login" />;
+}
+```
+
+## Configuration Options
+
+### TeardownCore Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `org_id` | string | Yes | Your organization ID from Teardown dashboard |
+| `project_id` | string | Yes | Your project ID from Teardown dashboard |
+| `api_key` | string | Yes | Your API key from Teardown dashboard |
+| `storageFactory` | function | Yes | Storage adapter factory (e.g., MMKV) |
+| `deviceAdapter` | object | Yes | Device info adapter (Expo or RN) |
+| `forceUpdate` | object | No | Force update configuration |
+
+### Force Update Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `throttleMs` | number | 30000 | Minimum time between foreground checks (ms) |
+| `checkCooldownMs` | number | 300000 | Minimum time since last successful check (ms) |
+
+## Next Steps
+
+- [Core Concepts](./02-core-concepts.mdx) - Understand the architecture
+- [Identity & Authentication](./03-identity.mdx) - Manage user sessions
+- [Force Updates](./04-force-updates.mdx) - Handle version management

package/docs/02-core-concepts.mdx

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

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