@teardown/react-native 2.0.24 → 2.0.28

package/docs/advanced.mdx

@@ -0,0 +1,280 @@
+---
+title: Advanced Usage
+description: Advanced patterns and configurations for the Teardown SDK.
+icon: Wrench
+---
+
+## Multiple Environments
+
+Configure different credentials per environment:
+
+```typescript
+const getConfig = () => {
+  if (__DEV__) {
+    return {
+      org_id: 'dev-org-id',
+      project_id: 'dev-project-id',
+      api_key: 'dev-api-key',
+    };
+  }
+  return {
+    org_id: 'prod-org-id',
+    project_id: 'prod-project-id',
+    api_key: 'prod-api-key',
+  };
+};
+
+export const teardown = new TeardownCore({
+  ...getConfig(),
+  storageAdapter: new MMKVStorageAdapter(),
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+```
+
+## Disable Force Update Checking
+
+For debugging or testing:
+
+```typescript
+const teardown = new TeardownCore({
+  // ...
+  forceUpdate: {
+    checkIntervalMs: -1, // Disable automatic checking
+  },
+});
+```
+
+## Custom Version Check Interval
+
+Check more or less frequently:
+
+```typescript
+const teardown = new TeardownCore({
+  // ...
+  forceUpdate: {
+    checkIntervalMs: 60_000,     // Check every minute
+    checkOnForeground: true,
+  },
+});
+```
+
+## Manual Version Checking
+
+Trigger version check programmatically:
+
+```typescript
+const { core } = useTeardown();
+
+const checkForUpdates = async () => {
+  const result = await core.identity.refresh();
+  if (result.success) {
+    // Version status will update via subscription
+    console.log('Version checked');
+  }
+};
+```
+
+## Offline Support
+
+The SDK handles offline scenarios gracefully:
+
+1. **Cached session** - Identity state persists across restarts
+2. **Cached version status** - Last known status is preserved
+3. **Retry on foreground** - Re-checks when connectivity restored
+
+```typescript
+const session = useSession();
+
+// Works offline - returns cached session
+if (session) {
+  console.log('User:', session.user_id);
+}
+```
+
+## Pre-warming
+
+Initialize SDK before app is fully loaded:
+
+```typescript
+// In app entry point (before React renders)
+import { teardown } from './lib/teardown';
+
+// SDK starts initializing immediately
+// By the time UI renders, it may already be ready
+```
+
+## Error Boundaries
+
+Handle SDK errors gracefully:
+
+```tsx
+import { ErrorBoundary } from 'react-error-boundary';
+
+function App() {
+  return (
+    <ErrorBoundary fallback={<ErrorScreen />}>
+      <TeardownProvider core={teardown}>
+        <MainApp />
+      </TeardownProvider>
+    </ErrorBoundary>
+  );
+}
+```
+
+## Testing
+
+### Mock the SDK
+
+```typescript
+// __mocks__/@teardown/react-native.ts
+export const TeardownProvider = ({ children }) => children;
+
+export const useTeardown = () => ({
+  core: {
+    identity: {
+      identify: jest.fn().mockResolvedValue({ success: true, data: mockSession }),
+      reset: jest.fn(),
+      getSessionState: () => mockSession,
+    },
+    forceUpdate: {
+      getVersionStatus: () => ({ type: 'up_to_date' }),
+    },
+  },
+});
+
+export const useSession = () => mockSession;
+export const useForceUpdate = () => ({
+  versionStatus: { type: 'up_to_date' },
+  isUpdateRequired: false,
+  isUpdateRecommended: false,
+  isUpdateAvailable: false,
+});
+```
+
+### Test Components
+
+```typescript
+import { render } from '@testing-library/react-native';
+
+test('shows login when not identified', () => {
+  jest.spyOn(hooks, 'useSession').mockReturnValue(null);
+
+  const { getByText } = render(<App />);
+  expect(getByText('Login')).toBeTruthy();
+});
+```
+
+## Debugging
+
+### Enable Verbose Logging
+
+```typescript
+teardown.setLogLevel('verbose');
+```
+
+### Inspect State
+
+```typescript
+const { core } = useTeardown();
+
+console.log('Identity state:', core.identity.getIdentifyState());
+console.log('Version status:', core.forceUpdate.getVersionStatus());
+console.log('Device ID:', await core.device.getDeviceId());
+```
+
+### Clear All Data
+
+For debugging or logout:
+
+```typescript
+core.identity.reset();
+// This clears session data and device association
+```
+
+## Performance
+
+### Minimize Re-renders
+
+Use specific hooks instead of broad subscriptions:
+
+```tsx
+// Good - only re-renders on session change
+const session = useSession();
+
+// Avoid - accessing core gives no reactivity
+const { core } = useTeardown();
+const session = core.identity.getSessionState(); // Not reactive!
+```
+
+### Lazy Initialization
+
+Defer SDK init until needed:
+
+```typescript
+let teardownInstance: TeardownCore | null = null;
+
+export const getTeardown = () => {
+  if (!teardownInstance) {
+    teardownInstance = new TeardownCore({ /* ... */ });
+  }
+  return teardownInstance;
+};
+```
+
+## Cleanup
+
+Properly cleanup on app shutdown:
+
+```typescript
+import { AppState } from 'react-native';
+
+useEffect(() => {
+  const subscription = AppState.addEventListener('change', (state) => {
+    if (state === 'background') {
+      // SDK persists state automatically, no action needed
+    }
+  });
+
+  return () => {
+    subscription.remove();
+    teardown.shutdown();
+  };
+}, []);
+```
+
+## TypeScript
+
+### Strict Types
+
+All SDK types are exported:
+
+```typescript
+import type {
+  TeardownCore,
+  TeardownCoreOptions,
+  Session,
+  IdentifyState,
+  VersionStatus,
+  Persona,
+  AsyncResult,
+} from '@teardown/react-native';
+```
+
+### Type Guards
+
+```typescript
+function handleIdentifyState(state: IdentifyState) {
+  switch (state.type) {
+    case 'unidentified':
+      // state is UnidentifiedSessionState
+      break;
+    case 'identifying':
+      // state is IdentifyingSessionState
+      break;
+    case 'identified':
+      // state is IdentifiedSessionState
+      console.log(state.session.user_id);
+      break;
+  }
+}
+```

package/docs/api-reference.mdx

@@ -0,0 +1,241 @@
+---
+title: API Reference
+description: Complete API reference for the Teardown React Native SDK.
+icon: Code
+---
+
+## TeardownCore
+
+The main SDK class that orchestrates all clients.
+
+### Constructor
+
+```typescript
+new TeardownCore(options: TeardownCoreOptions)
+```
+
+### TeardownCoreOptions
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `org_id` | `string` | Yes | Organization ID from dashboard |
+| `project_id` | `string` | Yes | Project ID from dashboard |
+| `api_key` | `string` | Yes | API key from dashboard |
+| `storageAdapter` | `StorageAdapter` | Yes | Storage adapter instance |
+| `deviceAdapter` | `DeviceInfoAdapter` | Yes | Device info adapter instance |
+| `forceUpdate` | `ForceUpdateClientOptions` | No | Force update configuration |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `setLogLevel(level)` | `void` | Set logging verbosity |
+| `shutdown()` | `void` | Cleanup SDK resources |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `api` | `ApiClient` | Backend API client |
+| `device` | `DeviceClient` | Device information client |
+| `identity` | `IdentityClient` | Identity management client |
+| `forceUpdate` | `ForceUpdateClient` | Version checking client |
+
+---
+
+## IdentityClient
+
+Manages user and device identification.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `identify(persona?)` | `AsyncResult<IdentityUser>` | Identify user/device |
+| `refresh()` | `AsyncResult<IdentityUser>` | Re-identify current user |
+| `reset()` | `void` | Clear session data |
+| `getIdentifyState()` | `IdentifyState` | Get current state |
+| `getSessionState()` | `Session \| null` | Get current session |
+| `onIdentifyStateChange(listener)` | `() => void` | Subscribe to state changes |
+| `shutdown()` | `void` | Cleanup listeners |
+
+### Persona
+
+```typescript
+interface Persona {
+  user_id?: string;
+  email?: string;
+  name?: string;
+}
+```
+
+### Session
+
+```typescript
+interface Session {
+  session_id: string;
+  device_id: string;
+  user_id: string;
+  token: string;
+}
+```
+
+### IdentifyState
+
+```typescript
+type IdentifyState =
+  | { type: 'unidentified' }
+  | { type: 'identifying' }
+  | { type: 'identified'; session: Session; version_info: VersionInfo };
+```
+
+---
+
+## ForceUpdateClient
+
+Manages version checking and force updates.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getVersionStatus()` | `VersionStatus` | Get current version status |
+| `onVersionStatusChange(listener)` | `() => void` | Subscribe to status changes |
+| `shutdown()` | `void` | Cleanup listeners |
+
+### ForceUpdateClientOptions
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `checkIntervalMs` | `number` | `300000` | Min time between checks. `0` = every foreground, `-1` = disabled |
+| `checkOnForeground` | `boolean` | `true` | Check when app foregrounds |
+| `identifyAnonymousDevice` | `boolean` | `false` | Check when not identified |
+
+### VersionStatus
+
+```typescript
+type VersionStatus =
+  | { type: 'initializing' }
+  | { type: 'checking' }
+  | { type: 'up_to_date' }
+  | { type: 'update_available' }
+  | { type: 'update_recommended' }
+  | { type: 'update_required' }
+  | { type: 'disabled' };
+```
+
+---
+
+## DeviceClient
+
+Collects device information.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getDeviceId()` | `Promise<string>` | Get stable device UUID |
+| `getDeviceInfo()` | `Promise<DeviceInfo>` | Get full device info |
+
+### DeviceInfo
+
+```typescript
+interface DeviceInfo {
+  timestamp: string;
+  os: OSInfo;
+  hardware: HardwareInfo;
+  application: ApplicationInfo;
+}
+```
+
+---
+
+## StorageAdapter
+
+Abstract class for storage implementations.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `createStorage(key)` | `SupportedStorage` | Create namespaced storage |
+
+### SupportedStorage
+
+```typescript
+interface SupportedStorage {
+  preload(): void;
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  clear(): void;
+  keys(): string[];
+}
+```
+
+---
+
+## DeviceInfoAdapter
+
+Interface for device information adapters.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `applicationInfo` | `ApplicationInfo` | App version info |
+| `hardwareInfo` | `HardwareInfo` | Device hardware info |
+| `osInfo` | `OSInfo` | Operating system info |
+
+### ApplicationInfo
+
+```typescript
+interface ApplicationInfo {
+  version: string;
+  buildNumber: string;
+  bundleId: string;
+}
+```
+
+### HardwareInfo
+
+```typescript
+interface HardwareInfo {
+  deviceName: string;
+  brand: string;
+  deviceType: string;
+}
+```
+
+### OSInfo
+
+```typescript
+interface OSInfo {
+  osName: string;
+  osVersion: string;
+}
+```
+
+---
+
+## AsyncResult
+
+Type-safe result type for async operations.
+
+```typescript
+type AsyncResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+```
+
+### Usage
+
+```typescript
+const result = await core.identity.identify({ user_id: '123' });
+
+if (result.success) {
+  console.log(result.data.session_id);
+} else {
+  console.error(result.error);
+}
+```

package/docs/core-concepts.mdx

@@ -0,0 +1,158 @@
+---
+title: Core Concepts
+description: Understand the architecture and design principles of the Teardown React Native SDK.
+icon: Lightbulb
+---
+
+## Architecture Overview
+
+The Teardown SDK is built around a central `TeardownCore` class that orchestrates multiple specialized clients:
+
+```
+TeardownCore
+├── IdentityClient      # User/device identification
+├── ForceUpdateClient   # Version checking
+├── DeviceClient        # Device information
+├── StorageClient       # Persistent storage
+├── ApiClient           # Backend communication
+└── LoggingClient       # Structured logging
+```
+
+## Initialization Flow
+
+When you create a `TeardownCore` instance, the following happens:
+
+1. **Storage Hydration** - Storage adapters load persisted state
+2. **Identity Initialization** - Loads cached session, then identifies with backend
+3. **Force Update Setup** - Subscribes to identity events for version checking
+4. **Ready State** - SDK is fully operational
+
+```typescript
+const teardown = new TeardownCore({
+  org_id: 'your-org-id',
+  project_id: 'your-project-id',
+  api_key: 'your-api-key',
+  storageAdapter: new MMKVStorageAdapter(),
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+// Initialization happens automatically in the background
+```
+
+## State Management
+
+The SDK uses an event-driven architecture with discriminated unions for type-safe state:
+
+### Identity State
+
+```typescript
+type IdentifyState =
+  | { type: 'unidentified' }
+  | { type: 'identifying' }
+  | { type: 'identified'; session: Session; version_info: VersionInfo };
+```
+
+### Version Status
+
+```typescript
+type VersionStatus =
+  | { type: 'initializing' }
+  | { type: 'checking' }
+  | { type: 'up_to_date' }
+  | { type: 'update_available' }
+  | { type: 'update_recommended' }
+  | { type: 'update_required' }
+  | { type: 'disabled' };
+```
+
+## Adapter Pattern
+
+The SDK uses adapters to abstract platform-specific functionality:
+
+### Storage Adapters
+
+Handle persistent data storage with a consistent interface:
+
+```typescript
+interface SupportedStorage {
+  preload(): void;
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  clear(): void;
+  keys(): string[];
+}
+```
+
+### Device Adapters
+
+Provide device and app information:
+
+```typescript
+interface DeviceInfoAdapter {
+  applicationInfo: ApplicationInfo;  // version, buildNumber, bundleId
+  hardwareInfo: HardwareInfo;        // deviceName, brand, deviceType
+  osInfo: OSInfo;                    // osName, osVersion
+}
+```
+
+## React Integration
+
+The SDK provides React primitives for seamless integration:
+
+### TeardownProvider
+
+Context provider that makes the SDK available throughout your app:
+
+```tsx
+<TeardownProvider core={teardown}>
+  <App />
+</TeardownProvider>
+```
+
+### Hooks
+
+Reactive hooks that subscribe to SDK state changes:
+
+- `useTeardown()` - Access the core instance
+- `useSession()` - Get current session (reactive)
+- `useForceUpdate()` - Get version status (reactive)
+
+## Persistence
+
+The SDK automatically persists:
+
+- **Session data** - Device ID, user ID, token
+- **Version status** - Last known update state
+- **Device ID** - Stable device identifier
+
+State is restored on app restart, providing offline-first functionality.
+
+## Error Handling
+
+All async operations return `AsyncResult` for type-safe error handling:
+
+```typescript
+type AsyncResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+const result = await core.identity.identify({ user_id: '123' });
+if (result.success) {
+  console.log(result.data.session_id);
+} else {
+  console.error(result.error);
+}
+```
+
+## Logging
+
+The SDK includes a structured logging system with configurable levels:
+
+```typescript
+teardown.setLogLevel('verbose'); // none | error | warn | info | verbose
+```
+
+Each client logs with a prefix for easy filtering:
+- `[Teardown:IdentityClient]`
+- `[Teardown:ForceUpdateClient]`
+- `[Teardown:DeviceClient]`