@teardown/react-native 2.0.4 → 2.0.10

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.4",
+	"version": "2.0.10",
 	"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": {
@@ -45,9 +50,9 @@
 		"nuke": "cd ../../ && bun run nuke"
 	},
 	"dependencies": {
-		"@teardown/ingest-api": "0.1.41",
-		"@teardown/schemas": "0.1.41",
-		"@teardown/types": "0.1.41",
+		"@teardown/ingest-api": "0.1.46",
+		"@teardown/schemas": "0.1.46",
+		"@teardown/types": "0.1.46",
 		"eventemitter3": "^5.0.1",
 		"react-native-get-random-values": "^2.0.0",
 		"uuid": "^13.0.0",
@@ -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/api/api.client.ts

@@ -5,7 +5,7 @@ import type { StorageClient } from "../storage";
 
 export type { Eden, IngestApi };
 
-const TEARDOWN_INGEST_URL = "https://ingest.teardown.dev";
+const TEARDOWN_INGEST_URL = "http://localhost:4880";// "https://ingest.teardown.dev";
 const TEARDOWN_API_KEY_HEADER = "td-api-key";
 const TEARDOWN_ORG_ID_HEADER = "td-org-id";
 const TEARDOWN_PROJECT_ID_HEADER = "td-project-id";

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

@@ -4,6 +4,8 @@ import type {
 	HardwareInfo,
 	OSInfo
 } from "@teardown/schemas";
+import type { Platform } from "react-native";
+import { DevicePlatformEnum } from "../device.client";
 
 /**
  * An interface for a device adapter.
@@ -39,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.test.ts

@@ -42,7 +42,7 @@ function createMockIdentityClient(initialState?: IdentifyState) {
 			emitter.emit("IDENTIFY_STATE_CHANGED", currentState);
 			currentState = {
 				type: "identified",
-				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				session: { session_id: "s1", device_id: "d1", user_id: "p1", token: "t1" },
 				version_info: { status: nextIdentifyResult.data?.version_info.status ?? IdentifyVersionStatusEnum.UP_TO_DATE, update: null },
 			};
 			emitter.emit("IDENTIFY_STATE_CHANGED", currentState);
@@ -87,7 +87,7 @@ describe("ForceUpdateClient", () => {
 		test("initializes version status when identity is already identified", () => {
 			const mockIdentity = createMockIdentityClient({
 				type: "identified",
-				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				session: { session_id: "s1", device_id: "d1", user_id: "p1", token: "t1" },
 				version_info: { status: IdentifyVersionStatusEnum.UPDATE_REQUIRED, update: null },
 			});
 			const mockLogging = createMockLoggingClient();
@@ -127,7 +127,7 @@ describe("ForceUpdateClient", () => {
 		test("emits status change during initialization when already identified", () => {
 			const mockIdentity = createMockIdentityClient({
 				type: "identified",
-				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				session: { session_id: "s1", device_id: "d1", user_id: "p1", token: "t1" },
 				version_info: { status: IdentifyVersionStatusEnum.UP_TO_DATE, update: null },
 			});
 			const mockLogging = createMockLoggingClient();
@@ -148,7 +148,7 @@ describe("ForceUpdateClient", () => {
 			// Trigger another identify to verify no duplicate
 			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", {
 				type: "identified",
-				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				session: { session_id: "s1", device_id: "d1", user_id: "p1", token: "t1" },
 				version_info: { status: IdentifyVersionStatusEnum.UP_TO_DATE, update: null },
 			});
 
@@ -181,7 +181,7 @@ describe("ForceUpdateClient", () => {
 			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", { type: "identifying" });
 			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", {
 				type: "identified",
-				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				session: { session_id: "s1", device_id: "d1", user_id: "p1", token: "t1" },
 				version_info: { status: IdentifyVersionStatusEnum.UPDATE_AVAILABLE, update: null },
 			});
 
@@ -253,7 +253,7 @@ describe("ForceUpdateClient", () => {
 			// After shutdown, emitting should not trigger listener
 			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", {
 				type: "identified",
-				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				session: { session_id: "s1", device_id: "d1", user_id: "p1", token: "t1" },
 				version_info: { status: IdentifyVersionStatusEnum.UPDATE_AVAILABLE, update: null },
 			});
 
@@ -515,7 +515,7 @@ describe("ForceUpdateClient", () => {
 
 			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", {
 				type: "identified",
-				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				session: { session_id: "s1", device_id: "d1", user_id: "p1", token: "t1" },
 				version_info: { status: apiStatus, update: null },
 			});
 

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