@teardown/react-native 1.2.39 → 2.0.1

package/README.md

@@ -1,20 +1,102 @@
+# @teardown/react-native
 
+Comprehensive SDK for managing device identity, force updates, logging, and analytics in React Native and Expo applications.
 
+## Features
 
+- 🔐 **Device & User Identity** - Unique device fingerprinting and user session management
+- 🔄 **Force Updates** - Automatic version checking with optional or required update flows
+- 📱 **Device Information** - Comprehensive device, OS, and app information collection
+- 💾 **Storage** - Namespaced persistent storage with platform adapters
+- 📝 **Logging** - Structured logging system with debug modes
+- ⚡ **Performance** - Optimized with caching, throttling, and efficient state management
+- 🎯 **Type Safety** - Full TypeScript support with runtime validation
 
-
-To get started:
+## Installation
 
 ```bash
-yarn add react-native-gesture-handler @teardown/react-native
+bun add @teardown/react-native
 ```
 
-If you're using CocoaPods you need to install pods:
+### Peer Dependencies
 
 ```bash
-cd ios && pod install
+bun add react react-native zod
+bun add expo-application expo-device expo-updates
+bun add react-native-device-info
+```
+
+## Quick Start
 
-or
+### 1. Initialize the SDK
 
-npx pod-install
+```tsx
+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
+  },
+});
 ```
+
+### 2. Wrap your app with TeardownProvider
+
+```tsx
+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
+
+```tsx
+import { useTeardown } from '@teardown/react-native';
+
+function YourComponent() {
+  const { core } = useTeardown();
+  
+  const handleLogin = async () => {
+    await core.identity.identify({
+      user_id: 'user-123',
+      email: 'user@example.com',
+    });
+  };
+  
+  return <Button onPress={handleLogin} />;
+}
+```
+
+## Documentation
+
+Complete documentation is available in the [docs](./docs) folder:
+
+- [Getting Started](./docs/01-getting-started.mdx) - Installation and setup
+- [Core Concepts](./docs/02-core-concepts.mdx) - Architecture overview
+- [Identity & Authentication](./docs/03-identity.mdx) - User session management
+- [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/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
+
+Proprietary - See LICENSE file for details

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)