@teardown/react-native 2.0.2 → 2.0.9

package/README.md

@@ -2,49 +2,90 @@
 
 Comprehensive SDK for managing device identity, force updates, logging, and analytics in React Native and Expo applications.
 
+**[Documentation](https://teardown.dev/docs)** | **[Dashboard](https://dash.teardown.dev)**
+
 ## 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
+- **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
 
 ## Installation
 
 ```bash
+npm install @teardown/react-native
+# or
+yarn add @teardown/react-native
+# or
 bun add @teardown/react-native
 ```
 
 ### Peer Dependencies
 
+Choose adapters based on your project setup:
+
+**Expo projects:**
+```bash
+npx expo install expo-device expo-application
+```
+
+**Bare React Native projects:**
 ```bash
-bun add react react-native zod
-bun add expo-application expo-device expo-updates
-bun add react-native-device-info
+npm install react-native-device-info
 ```
 
+**Storage (choose one):**
+```bash
+# MMKV (recommended - faster)
+npm install react-native-mmkv
+
+# or AsyncStorage
+npm install @react-native-async-storage/async-storage
+```
+
+## Getting Your Credentials
+
+1. Sign up or log in at [dash.teardown.dev](https://dash.teardown.dev)
+2. Create or select a project
+3. Copy your `org_id`, `project_id`, and `api_key` from project settings
+
 ## Quick Start
 
 ### 1. Initialize the SDK
 
+Create a file (e.g., `lib/teardown.ts`):
+
+**Expo Setup:**
 ```tsx
 import { TeardownCore } from '@teardown/react-native';
-import { ExpoDeviceAdapter } from '@teardown/react-native/expo';
-import { createMMKVStorageFactory } from '@teardown/react-native/mmkv';
+import { ExpoDeviceAdapter } from '@teardown/react-native/adapters/expo';
+import { MMKVStorageAdapter } from '@teardown/react-native/adapters/mmkv';
 
 export const teardown = new TeardownCore({
   org_id: 'your-org-id',
   project_id: 'your-project-id',
   api_key: 'your-api-key',
-  storageFactory: createMMKVStorageFactory(),
+  storageAdapter: new MMKVStorageAdapter(),
   deviceAdapter: new ExpoDeviceAdapter(),
-  forceUpdate: {
-    throttleMs: 30_000, // 30 seconds
-    checkCooldownMs: 10_000, // 10 seconds
-  },
+});
+```
+
+**Bare React Native Setup:**
+```tsx
+import { TeardownCore } from '@teardown/react-native';
+import { DeviceInfoAdapter } from '@teardown/react-native/adapters/device-info';
+import { AsyncStorageAdapter } from '@teardown/react-native/adapters/async-storage';
+
+export const teardown = new TeardownCore({
+  org_id: 'your-org-id',
+  project_id: 'your-project-id',
+  api_key: 'your-api-key',
+  storageAdapter: new AsyncStorageAdapter(),
+  deviceAdapter: new DeviceInfoAdapter(),
 });
 ```
 
@@ -54,7 +95,7 @@ export const teardown = new TeardownCore({
 import { TeardownProvider } from '@teardown/react-native';
 import { teardown } from './lib/teardown';
 
-export default function RootLayout() {
+export default function App() {
   return (
     <TeardownProvider core={teardown}>
       <YourApp />
@@ -66,36 +107,65 @@ export default function RootLayout() {
 ### 3. Use in components
 
 ```tsx
-import { useTeardown } from '@teardown/react-native';
+import { useTeardown, useForceUpdate, useSession } from '@teardown/react-native';
 
 function YourComponent() {
   const { core } = useTeardown();
-  
+  const session = useSession();
+  const { status, isUpdateRequired } = useForceUpdate();
+
   const handleLogin = async () => {
     await core.identity.identify({
       user_id: 'user-123',
       email: 'user@example.com',
     });
   };
-  
-  return <Button onPress={handleLogin} />;
+
+  return <Button onPress={handleLogin} title="Login" />;
 }
 ```
 
+## Configuration Options
+
+```tsx
+new TeardownCore({
+  org_id: string,           // Your organization ID
+  project_id: string,       // Your project ID
+  api_key: string,          // Your API key
+  storageAdapter: adapter,  // Storage implementation
+  deviceAdapter: adapter,   // Device info source
+  forceUpdate: {
+    throttleMs: 30_000,     // Min time between checks (default: 30s)
+    checkCooldownMs: 10_000 // Cooldown after check (default: 10s)
+  },
+});
+```
+
+## Available Adapters
+
+| Adapter | Import Path | Use Case |
+|---------|-------------|----------|
+| `ExpoDeviceAdapter` | `@teardown/react-native/adapters/expo` | Expo projects |
+| `DeviceInfoAdapter` | `@teardown/react-native/adapters/device-info` | Bare RN projects |
+| `MMKVStorageAdapter` | `@teardown/react-native/adapters/mmkv` | Fast sync storage |
+| `AsyncStorageAdapter` | `@teardown/react-native/adapters/async-storage` | Standard async storage |
+
 ## 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
+For detailed guides, visit **[teardown.dev/docs](https://teardown.dev/docs)**
+
+Local documentation is also available in the [docs](./docs) folder:
+
+- [Getting Started](./docs/01-getting-started.mdx)
+- [Core Concepts](./docs/02-core-concepts.mdx)
+- [Identity & Authentication](./docs/03-identity.mdx)
+- [Force Updates](./docs/04-force-updates.mdx)
+- [Device Information](./docs/05-device-info.mdx)
+- [Storage](./docs/06-storage.mdx)
+- [Logging](./docs/07-logging.mdx)
+- [API Reference](./docs/08-api-reference.mdx)
+- [Hooks Reference](./docs/09-hooks-reference.mdx)
+- [Advanced Usage](./docs/10-advanced.mdx)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@teardown/react-native",
-	"version": "2.0.2",
+	"version": "2.0.9",
 	"private": false,
 	"publishConfig": {
 		"access": "public"
@@ -32,6 +32,11 @@
 			"types": "./src/exports/adapters/async-storage.ts",
 			"import": "./src/exports/adapters/async-storage.ts",
 			"default": "./src/exports/adapters/async-storage.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"
 		}
 	},
 	"scripts": {
@@ -62,20 +67,24 @@
 		"expo-updates": "^29.0.12"
 	},
 	"peerDependencies": {
-		"@react-native-async-storage/async-storage": "^1.21.0 || ^2.0.0",
-		"react": "*",
-		"react-native": "*",
-		"typescript": "*",
+		"@react-native-async-storage/async-storage": "^1.21 || ^2.0",
 		"expo-application": "*",
 		"expo-device": "*",
 		"expo-notifications": "*",
 		"expo-secure-store": "*",
-		"react-native-mmkv": "*"
+		"react": "*",
+		"react-native": "*",
+		"react-native-device-info": "^15",
+		"react-native-mmkv": "^4.0.0",
+		"typescript": "*"
 	},
 	"peerDependenciesMeta": {
 		"@react-native-async-storage/async-storage": {
 			"optional": true
 		},
+		"react-native-device-info": {
+			"optional": true
+		},
 		"react-native-mmkv": {
 			"optional": true
 		},

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

@@ -8,8 +8,8 @@ import * as Application from "expo-application";
 import * as Device from "expo-device";
 import { Platform } from "react-native";
 
-import { DeviceInfoAdapter } from "./device.adpater-interface";
 import { DevicePlatformEnum, NotificationPlatformEnum } from "../device.client";
+import { DeviceInfoAdapter } from "./device.adpater-interface";
 
 /**
  * Maps expo-device DeviceType to a string representation

package/src/clients/device/adapters/device-info.adapter.ts

@@ -0,0 +1,36 @@
+import type {
+  ApplicationInfo,
+  HardwareInfo,
+  OSInfo
+} from "@teardown/schemas";
+import { Platform } from "react-native";
+import DeviceInfo from "react-native-device-info";
+import { DeviceInfoAdapter as BaseInfoAdapterInterface } from "./device.adpater-interface";
+
+export class DeviceInfoAdapter extends BaseInfoAdapterInterface {
+  get applicationInfo(): ApplicationInfo {
+    return {
+      version: DeviceInfo.getVersion() ?? "0.0.0",
+      build_number: Number.parseInt(
+        DeviceInfo.getBuildNumber() ?? "0",
+        10
+      ),
+    };
+  }
+
+  get hardwareInfo(): HardwareInfo {
+    return {
+      device_name: DeviceInfo.getDeviceNameSync() ?? "Unknown Device",
+      device_brand: DeviceInfo.getBrand() ?? "Unknown Brand",
+      device_type: DeviceInfo.getDeviceType?.() ?? "unknown",
+    };
+  }
+
+  get osInfo(): OSInfo {
+    return {
+      platform: this.mapPlatform(Platform.OS),
+      name: DeviceInfo.getSystemName() ?? Platform.OS,
+      version: DeviceInfo.getSystemVersion() ?? "0.0.0",
+    };
+  }
+}

package/src/clients/device/adapters/device.adpater-interface.ts

@@ -2,9 +2,10 @@ import type {
 	ApplicationInfo,
 	DeviceInfo,
 	HardwareInfo,
-	NotificationsInfo,
 	OSInfo
 } from "@teardown/schemas";
+import type { Platform } from "react-native";
+import { DevicePlatformEnum } from "../device.client";
 
 /**
  * An interface for a device adapter.
@@ -16,32 +17,18 @@ import type {
  *
  */
 export abstract class DeviceInfoAdapter {
-	// -- Application Information --
 	/**
 	 * The information about the application running.
 	 */
 	abstract get applicationInfo(): ApplicationInfo;
-	// -- Updates Information --
-	/**
-	 * The information about the update running.
-	 */
-	// abstract get updateInfo(): UpdateInfo | null;
-	// -- Hardware Information --
 	/**
 	 * The information about the hardware of the device.
 	 */
 	abstract get hardwareInfo(): HardwareInfo;
-	// -- OS Information --
 	/**
 	 * The information about the operating system of the device.
 	 */
 	abstract get osInfo(): OSInfo;
-
-	/**
-	 * The information about the notifications of the device.
-	 */
-	abstract get notificationsInfo(): NotificationsInfo;
-
 	/**
 	 * The information about the device.
 	 */
@@ -54,4 +41,25 @@ export abstract class DeviceInfoAdapter {
 			update: null,
 		});
 	}
+
+	/**
+	 * Maps React Native Platform.OS to DevicePlatformEnum
+	 */
+	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;
+		}
+	}
+
 }

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

@@ -1,15 +1,13 @@
 import type {
   ApplicationInfo,
   HardwareInfo,
-  NotificationsInfo,
-  OSInfo,
+  OSInfo
 } from "@teardown/schemas";
 import * as Application from "expo-application";
 import * as Device from "expo-device";
 import { Platform } from "react-native";
 
 import { DeviceInfoAdapter } from "./device.adpater-interface";
-import { DevicePlatformEnum, NotificationPlatformEnum } from "../device.client";
 
 /**
  * Maps expo-device DeviceType to a string representation
@@ -29,26 +27,6 @@ function mapDeviceType(deviceType: Device.DeviceType | null): string {
   }
 }
 
-/**
- * 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;
-  }
-}
-
 export class ExpoDeviceAdapter extends DeviceInfoAdapter {
   get applicationInfo(): ApplicationInfo {
     return {
@@ -70,21 +48,9 @@ export class ExpoDeviceAdapter extends DeviceInfoAdapter {
 
   get osInfo(): OSInfo {
     return {
-      platform: mapPlatform(Platform.OS),
+      platform: this.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,
-      },
-    };
-  }
-
 }

package/src/clients/force-update/force-update.client.ts

@@ -69,12 +69,31 @@ export type VersionStatusChangeEvents = {
 };
 
 export type ForceUpdateClientOptions = {
-	/** Min ms between foreground checks (default: 30000) */
+	/** 
+	 * Minimum time (ms) between foreground transitions to prevent rapid-fire checks.
+	 * Measured from the last time the app came to foreground.
+	 * Prevents checking when user quickly switches apps back and forth.
+	 * Default: 30000 (30 seconds)
+	 * 
+	 * Special values:
+	 * - -1: Disable throttling, check on every foreground (respects checkCooldownMs)
+	 * 
+	 * Example: If throttleMs is 30s and user backgrounds then foregrounds the app
+	 * twice within 20s, only the first transition triggers a check.
+	 */
 	throttleMs?: number;
 	/** 
-	 * Min ms since last successful check before re-checking (default: 300000 = 5min)
-	 * Set this to 0 to disable cooldown and check immediately on every foreground transition.
-	 * Set to -1 disable checking entirely.
+	 * Minimum time (ms) since the last successful version check before checking again.
+	 * Measured from when the last check completed successfully (not when it started).
+	 * Prevents unnecessary API calls after we already have fresh version data.
+	 * Default: 300000 (5 minutes)
+	 * 
+	 * Special values:
+	 * - 0: Disable cooldown, check on every foreground (respects throttleMs)
+	 * - -1: Disable all automatic version checking
+	 * 
+	 * Example: If checkCooldownMs is 5min and a check completes at 12:00pm,
+	 * no new checks occur until 12:05pm, even if user foregrounds the app multiple times.
 	 */
 	checkCooldownMs?: number;
 };
@@ -84,7 +103,7 @@ const DEFAULT_OPTIONS: Required<ForceUpdateClientOptions> = {
 	checkCooldownMs: 300_000, // 5 minutes
 };
 
-export const VERSION_STATUS_STORAGE_KEY = "VERSION_STATUS";
+export const VERSION_STATUS_STORAGE_KEY = "version_status";
 
 export class ForceUpdateClient {
 	private emitter = new EventEmitter<VersionStatusChangeEvents>();
@@ -220,7 +239,12 @@ export class ForceUpdateClient {
 			}
 
 			const now = Date.now();
-			const throttleOk = !this.lastForegroundTime || now - this.lastForegroundTime >= this.options.throttleMs;
+
+			// If throttleMs is -1, disable throttling (always pass)
+			// Otherwise, check if enough time has passed since last foreground
+			const throttleOk = this.options.throttleMs === -1
+				|| !this.lastForegroundTime
+				|| now - this.lastForegroundTime >= this.options.throttleMs;
 
 			// If checkCooldownMs is 0, always allow check (no cooldown)
 			// Otherwise, check if enough time has passed since last successful check

package/src/clients/identity/identity.client.test.ts

@@ -27,7 +27,7 @@ function createMockLoggingClient() {
 			debug: (message: string, ...args: unknown[]) => logs.push({ level: "debug", message, args }),
 		}),
 		getLogs: () => logs,
-		clearLogs: () => logs.length = 0,
+		clearLogs: () => { logs.length = 0; },
 	};
 }
 
@@ -605,7 +605,7 @@ describe("IdentityClient", () => {
 
 			// Should have debug log about state already being 'identifying' (first setIdentifyState call)
 			// Then transitions to identified
-			const debugLogs = mockLogging.getLogs().filter(l => l.level === "debug");
+			const debugLogs = mockLogging.getLogs().filter((l) => l.level === "debug");
 			// The "identifying" to "identifying" won't happen since we start from "identified"
 			// But we can check that state changes are logged properly
 			expect(mockLogging.getLogs().some(l => l.level === "info")).toBe(true);

package/src/exports/adapters/device-info.ts

@@ -0,0 +1 @@
+export * from "../../clients/device/adapters/device-info.adapter";

package/docs/01-getting-started.mdx

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