@teardown/react-native 2.0.23 → 2.0.27

package/docs/identity.mdx

@@ -0,0 +1,171 @@
+---
+title: Identity
+description: User and device identification with the Teardown SDK.
+icon: User
+---
+
+The Identity client manages user sessions, device identification, and authentication state.
+
+## Overview
+
+The SDK automatically identifies devices on initialization. You can optionally associate users with devices by calling `identify()` with user information.
+
+## Session Structure
+
+```typescript
+interface Session {
+  session_id: string;  // Unique session identifier
+  device_id: string;   // Stable device identifier
+  user_id: string;     // User or persona identifier
+  token: string;       // Authentication token
+}
+```
+
+## Basic Usage
+
+### Identify a User
+
+```typescript
+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('Identified:', result.data.session_id);
+  } else {
+    console.error('Failed:', result.error);
+  }
+};
+```
+
+### Get Current Session
+
+```typescript
+// Imperative
+const session = core.identity.getSessionState();
+
+// Reactive (hook)
+const session = useSession();
+
+if (session) {
+  console.log('Device:', session.device_id);
+  console.log('User:', session.user_id);
+}
+```
+
+### Reset Identity
+
+Clear the current session and device association:
+
+```typescript
+core.identity.reset();
+```
+
+### Refresh Session
+
+Re-identify to refresh session data (only works if already identified):
+
+```typescript
+const result = await core.identity.refresh();
+```
+
+## Identity State
+
+The identity client maintains a state machine:
+
+```typescript
+type IdentifyState =
+  | { type: 'unidentified' }
+  | { type: 'identifying' }
+  | { type: 'identified'; session: Session; version_info: VersionInfo };
+```
+
+### Subscribe to State Changes
+
+```typescript
+const unsubscribe = core.identity.onIdentifyStateChange((state) => {
+  switch (state.type) {
+    case 'unidentified':
+      // Show login screen
+      break;
+    case 'identifying':
+      // Show loading
+      break;
+    case 'identified':
+      // Navigate to app
+      console.log('Session:', state.session);
+      break;
+  }
+});
+
+// Cleanup
+unsubscribe();
+```
+
+## Persona Object
+
+When identifying, you can provide optional user information:
+
+```typescript
+interface Persona {
+  user_id?: string;   // Your system's user ID
+  email?: string;     // User email
+  name?: string;      // Display name
+}
+```
+
+All fields are optional. If no persona is provided, the device is identified anonymously.
+
+## Device ID
+
+The SDK generates a stable device ID that persists across app sessions:
+
+```typescript
+const deviceId = await core.device.getDeviceId();
+```
+
+The device ID is:
+- Generated once per device
+- Persisted in storage
+- Used for all API calls
+- Stable across app updates
+
+## Version Info
+
+The identify response includes version information used for force updates:
+
+```typescript
+if (state.type === 'identified') {
+  const status = state.version_info.status;
+  // 'UP_TO_DATE' | 'UPDATE_AVAILABLE' | 'UPDATE_RECOMMENDED' | 'UPDATE_REQUIRED' | 'DISABLED'
+}
+```
+
+## Error Handling
+
+```typescript
+const result = await core.identity.identify({ user_id: '123' });
+
+if (!result.success) {
+  switch (result.error) {
+    case 'Network error':
+      // Handle offline
+      break;
+    default:
+      // Handle other errors
+      console.error(result.error);
+  }
+}
+```
+
+## Best Practices
+
+1. **Call identify on login** - Associate users with their devices
+2. **Call reset on logout** - Clear session data
+3. **Handle offline** - The SDK caches session data for offline use
+4. **Use useSession hook** - For reactive UI updates

package/docs/index.mdx

@@ -0,0 +1,61 @@
+---
+title: React Native SDK
+description: Comprehensive SDK for device identity, force updates, logging, and analytics in React Native and Expo applications.
+icon: Smartphone
+---
+
+The Teardown React Native SDK provides everything you need to manage device identity, force app updates, and collect analytics in your mobile applications.
+
+## Features
+
+- **Device & User Identity** - Unique device fingerprinting and user session management
+- **Force Updates** - Automatic version checking with optional, recommended, 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 configurable log levels
+- **Type Safety** - Full TypeScript support with Zod runtime validation
+
+## Quick Start
+
+```bash
+bun add @teardown/react-native
+```
+
+```tsx
+import { TeardownCore, TeardownProvider } from '@teardown/react-native';
+import { ExpoDeviceAdapter } from '@teardown/react-native/adapters/expo';
+import { MMKVStorageAdapter } from '@teardown/react-native/adapters/mmkv';
+
+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(),
+});
+
+export default function App() {
+  return (
+    <TeardownProvider core={teardown}>
+      <YourApp />
+    </TeardownProvider>
+  );
+}
+```
+
+## Platform Support
+
+| Platform | Device Adapter | Storage Adapter |
+|----------|---------------|-----------------|
+| Expo | `ExpoDeviceAdapter` | `MMKVStorageAdapter` or `AsyncStorageAdapter` |
+| React Native CLI | `DeviceInfoAdapter` | `MMKVStorageAdapter` or `AsyncStorageAdapter` |
+
+## Documentation
+
+- [Getting Started](/docs/react-native/getting-started) - Installation and setup
+- [Core Concepts](/docs/react-native/core-concepts) - Architecture overview
+- [Identity](/docs/react-native/identity) - User and device identification
+- [Force Updates](/docs/react-native/force-updates) - Version management
+- [Storage Adapters](/docs/react-native/adapters/storage) - Persistent storage adapters
+- [API Reference](/docs/react-native/api-reference) - Complete API documentation
+- [Hooks Reference](/docs/react-native/hooks-reference) - React hooks

package/docs/logging.mdx

@@ -0,0 +1,144 @@
+---
+title: Logging
+description: Configure structured logging in the Teardown SDK.
+icon: FileText
+---
+
+The SDK includes a structured logging system for debugging and monitoring.
+
+## Log Levels
+
+```typescript
+type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'verbose';
+```
+
+| Level | Priority | Description |
+|-------|----------|-------------|
+| `none` | 0 | No logging |
+| `error` | 1 | Only errors |
+| `warn` | 2 | Errors and warnings |
+| `info` | 3 | General information |
+| `verbose` | 4 | Detailed debug output |
+
+## Setting Log Level
+
+```typescript
+const teardown = new TeardownCore({
+  // ...options
+});
+
+// Set log level (default is 'verbose' during development)
+teardown.setLogLevel('verbose');
+```
+
+## Log Output
+
+Each client logs with a prefix for easy filtering:
+
+```
+[Teardown:TeardownCore] TeardownCore initialized
+[Teardown:IdentityClient] Identifying user with persona: John
+[Teardown:ForceUpdateClient] Version status: up_to_date
+[Teardown:DeviceClient] Device ID: 550e8400-e29b-41d4...
+```
+
+## Log Methods
+
+The internal `Logger` class provides these methods:
+
+| Method | Level Required | Console Method |
+|--------|---------------|----------------|
+| `error()` | error | `console.error` |
+| `warn()` | warn | `console.warn` |
+| `info()` | info | `console.log` |
+| `debug()` | verbose | `console.debug` |
+| `trace()` | verbose | `console.trace` |
+
+### Debug Variants
+
+Additional debug methods for categorized output:
+
+```typescript
+logger.debugError('Something went wrong', { error });   // Error: [prefix] ...
+logger.debugWarn('Warning message');                     // Warning: [prefix] ...
+logger.debugInfo('Info message');                        // Info: [prefix] ...
+logger.debugVerbose('Verbose details');                  // Verbose: [prefix] ...
+```
+
+## Production Logging
+
+For production builds, set log level to `none` or `error`:
+
+```typescript
+const teardown = new TeardownCore({ /* ... */ });
+
+if (__DEV__) {
+  teardown.setLogLevel('verbose');
+} else {
+  teardown.setLogLevel('error');
+}
+```
+
+## Filtering Logs
+
+Use the `[Teardown:` prefix to filter SDK logs in your console:
+
+**React Native Debugger:**
+```
+Filter: [Teardown:
+```
+
+**Xcode Console:**
+```
+[Teardown:
+```
+
+**Android Logcat:**
+```bash
+adb logcat | grep "\[Teardown:"
+```
+
+## Internal Architecture
+
+The logging system consists of two classes:
+
+### LoggingClient
+
+Central log level management:
+
+```typescript
+class LoggingClient {
+  setLogLevel(level: LogLevel): void;
+  getLogLevel(): LogLevel;
+  shouldLog(level: LogLevel): boolean;
+  createLogger(options: { name: string }): Logger;
+}
+```
+
+### Logger
+
+Individual logger instance with bound console methods:
+
+```typescript
+class Logger {
+  get prefix(): string;  // [Teardown:ClientName]
+  info(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+  trace(message: string, ...args: unknown[]): void;
+}
+```
+
+## Best Practices
+
+1. **Use `verbose` in development** - See all SDK activity
+2. **Use `error` in production** - Minimize noise, catch issues
+3. **Filter by prefix** - Isolate SDK logs from app logs
+4. **Check log level first** - Avoid expensive string operations:
+
+```typescript
+if (core.logging.shouldLog('verbose')) {
+  console.log('Complex debug:', JSON.stringify(largeObject));
+}
+```

package/docs/meta.json

@@ -0,0 +1,14 @@
+{
+	"title": "React Native SDK",
+	"pages": [
+		"getting-started",
+		"core-concepts",
+		"identity",
+		"force-updates",
+		"adapters",
+		"logging",
+		"api-reference",
+		"hooks-reference",
+		"advanced"
+	]
+}

package/package.json

@@ -1,6 +1,7 @@
 {
 	"name": "@teardown/react-native",
-	"version": "2.0.23",
+	"version": "2.0.27",
+	"type": "module",
 	"private": false,
 	"publishConfig": {
 		"access": "public"
@@ -13,69 +14,77 @@
 	"module": "./src/exports/index.ts",
 	"types": "./src/exports/index.ts",
 	"exports": {
+		"./package.json": "./package.json",
 		".": {
 			"types": "./src/exports/index.ts",
 			"import": "./src/exports/index.ts",
 			"default": "./src/exports/index.ts"
 		},
-		"./adapters/expo": {
-			"types": "./src/exports/adapters/expo.ts",
-			"import": "./src/exports/adapters/expo.ts",
-			"default": "./src/exports/adapters/expo.ts"
+		"./adapters/*": {
+			"types": "./src/exports/adapters/*.ts",
+			"import": "./src/exports/adapters/*.ts",
+			"default": "./src/exports/adapters/*.ts"
 		},
-		"./adapters/mmkv": {
-			"types": "./src/exports/adapters/mmkv.ts",
-			"import": "./src/exports/adapters/mmkv.ts",
-			"default": "./src/exports/adapters/mmkv.ts"
+		"./expo": {
+			"types": "./src/exports/expo.ts",
+			"import": "./src/exports/expo.ts",
+			"default": "./src/exports/expo.ts"
 		},
-		"./adapters/async-storage": {
-			"types": "./src/exports/adapters/async-storage.ts",
-			"import": "./src/exports/adapters/async-storage.ts",
-			"default": "./src/exports/adapters/async-storage.ts"
+		"./firebase": {
+			"types": "./src/exports/firebase.ts",
+			"import": "./src/exports/firebase.ts",
+			"default": "./src/exports/firebase.ts"
 		},
-		"./adapters/device-info": {
-			"types": "./src/exports/adapters/device-info.ts",
-			"import": "./src/exports/adapters/device-info.ts",
-			"default": "./src/exports/adapters/device-info.ts"
+		"./wix": {
+			"types": "./src/exports/wix.ts",
+			"import": "./src/exports/wix.ts",
+			"default": "./src/exports/wix.ts"
 		}
 	},
 	"scripts": {
 		"build": "tsc --project ./tsconfig.json",
 		"dev": "bun run build && tsc --watch --project ./tsconfig.json",
 		"typecheck": "tsc --noEmit --project ./tsconfig.json",
-		"lint": "biome lint --write",
-		"fmt": "biome format --write",
+		"lint": "bun x biome lint --write ./src",
+		"fmt": "bun x biome format --write ./src",
+		"check": "bun x biome check ./src",
 		"test": "bun test",
-		"prepublishOnly": "bun run build",
-		"nuke": "cd ../../ && bun run nuke"
+		"prepublishOnly": "bun run build"
 	},
 	"dependencies": {
-		"@teardown/ingest-api": "0.1.49",
-		"@teardown/schemas": "0.1.49",
-		"@teardown/types": "0.1.49",
+		"@teardown/ingest-api": "2.0.26",
+		"@teardown/schemas": "2.0.26",
+		"@teardown/types": "2.0.26",
 		"eventemitter3": "^5.0.1",
 		"react-native-get-random-values": "^2.0.0",
 		"uuid": "^13.0.0",
-		"zod": "^4.1.13"
+		"zod": "4.2.1"
 	},
 	"devDependencies": {
-		"@elysiajs/eden": "^1.4.5",
-		"@teardown/tsconfig": "1.0.0",
-		"@types/bun": "latest",
-		"@types/react": "*",
-		"@types/uuid": "^11.0.0"
+		"@biomejs/biome": "2.3.10",
+		"@elysiajs/eden": "1.4.5",
+		"@react-native-firebase/messaging": "*",
+		"@teardown/tsconfig": "2.0.26",
+		"@types/bun": "1.3.5",
+		"@types/react": "~19.1.0",
+		"@types/uuid": "^11.0.0",
+		"react": "19.1.0",
+		"react-native": "0.81.5",
+		"react-native-notifications": "*"
 	},
 	"peerDependencies": {
-		"@react-native-async-storage/async-storage": "~2.0",
+		"@react-native-async-storage/async-storage": "^1.21 || ^2.0",
 		"expo-application": "~7",
 		"expo-device": "~8",
 		"expo-notifications": "~0.32",
 		"expo-secure-store": "~15",
 		"expo-updates": "~29",
+		"@react-native-firebase/messaging": "*",
 		"react": "~19",
 		"react-native": "~0.81",
 		"react-native-device-info": "~15",
 		"react-native-mmkv": "^4",
+		"react-native-notifications": "*",
 		"typescript": "~5"
 	},
 	"peerDependenciesMeta": {
@@ -105,6 +114,15 @@
 		},
 		"expo-secure-store": {
 			"optional": true
+		},
+		"expo-updates": {
+			"optional": true
+		},
+		"@react-native-firebase/messaging": {
+			"optional": true
+		},
+		"react-native-notifications": {
+			"optional": true
 		}
 	}
 }

package/src/clients/api/index.ts

@@ -1 +1 @@
-export * from "./api.client";
+export * from "./api.client";

package/src/clients/device/adapters/basic.adapter.ts

@@ -1,9 +1,4 @@
-import type {
-  ApplicationInfo,
-  HardwareInfo,
-  NotificationsInfo,
-  OSInfo,
-} from "@teardown/schemas";
+import type { ApplicationInfo, HardwareInfo, NotificationsInfo, OSInfo } from "@teardown/schemas";
 import * as Application from "expo-application";
 import * as Device from "expo-device";
 import { Platform } from "react-native";
@@ -15,76 +10,72 @@ import { DeviceInfoAdapter } from "./device.adpater-interface";
  * Maps expo-device DeviceType to a string representation
  */
 function mapDeviceType(deviceType: Device.DeviceType | null): string {
-  switch (deviceType) {
-    case Device.DeviceType.PHONE:
-      return "phone";
-    case Device.DeviceType.TABLET:
-      return "tablet";
-    case Device.DeviceType.DESKTOP:
-      return "desktop";
-    case Device.DeviceType.TV:
-      return "tv";
-    default:
-      return "unknown";
-  }
+	switch (deviceType) {
+		case Device.DeviceType.PHONE:
+			return "phone";
+		case Device.DeviceType.TABLET:
+			return "tablet";
+		case Device.DeviceType.DESKTOP:
+			return "desktop";
+		case Device.DeviceType.TV:
+			return "tv";
+		default:
+			return "unknown";
+	}
 }
 
 /**
  * Maps React Native Platform.OS to DevicePlatformEnum
  */
 function mapPlatform(platform: typeof Platform.OS): DevicePlatformEnum {
-  switch (platform) {
-    case "ios":
-      return DevicePlatformEnum.IOS;
-    case "android":
-      return DevicePlatformEnum.ANDROID;
-    case "web":
-      return DevicePlatformEnum.WEB;
-    case "macos":
-      return DevicePlatformEnum.MACOS;
-    case "windows":
-      return DevicePlatformEnum.WINDOWS;
-    default:
-      return DevicePlatformEnum.UNKNOWN;
-  }
+	switch (platform) {
+		case "ios":
+			return DevicePlatformEnum.IOS;
+		case "android":
+			return DevicePlatformEnum.ANDROID;
+		case "web":
+			return DevicePlatformEnum.WEB;
+		case "macos":
+			return DevicePlatformEnum.MACOS;
+		case "windows":
+			return DevicePlatformEnum.WINDOWS;
+		default:
+			return DevicePlatformEnum.UNKNOWN;
+	}
 }
 
 export class ExpoDeviceAdapter extends DeviceInfoAdapter {
-  get applicationInfo(): ApplicationInfo {
-    return {
-      version: Application.nativeApplicationVersion ?? "0.0.0",
-      build_number: Number.parseInt(
-        Application.nativeBuildVersion ?? "0",
-        10
-      ),
-    };
-  }
+	get applicationInfo(): ApplicationInfo {
+		return {
+			version: Application.nativeApplicationVersion ?? "0.0.0",
+			build_number: Number.parseInt(Application.nativeBuildVersion ?? "0", 10),
+		};
+	}
 
-  get hardwareInfo(): HardwareInfo {
-    return {
-      device_name: Device.deviceName ?? "Unknown Device",
-      device_brand: Device.brand ?? "Unknown Brand",
-      device_type: mapDeviceType(Device.deviceType),
-    };
-  }
+	get hardwareInfo(): HardwareInfo {
+		return {
+			device_name: Device.deviceName ?? "Unknown Device",
+			device_brand: Device.brand ?? "Unknown Brand",
+			device_type: mapDeviceType(Device.deviceType),
+		};
+	}
 
-  get osInfo(): OSInfo {
-    return {
-      platform: mapPlatform(Platform.OS),
-      name: Device.osName ?? Platform.OS,
-      version: Device.osVersion ?? "0.0.0",
-    };
-  }
-
-  get notificationsInfo(): NotificationsInfo {
-    return {
-      push: {
-        enabled: false,
-        granted: false,
-        token: null,
-        platform: NotificationPlatformEnum.EXPO,
-      },
-    };
-  }
+	get osInfo(): OSInfo {
+		return {
+			platform: mapPlatform(Platform.OS),
+			name: Device.osName ?? Platform.OS,
+			version: Device.osVersion ?? "0.0.0",
+		};
+	}
 
+	get notificationsInfo(): NotificationsInfo {
+		return {
+			push: {
+				enabled: false,
+				granted: false,
+				token: null,
+				platform: NotificationPlatformEnum.EXPO,
+			},
+		};
+	}
 }