@teardown/react-native 2.0.4 → 2.0.10

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; },
 	};
 }
 
@@ -48,7 +48,7 @@ function createMockUtilsClient() {
 	let uuidCounter = 0;
 	return {
 		generateRandomUUID: async () => `mock-uuid-${++uuidCounter}`,
-		resetCounter: () => uuidCounter = 0,
+		resetCounter: () => { uuidCounter = 0; },
 	};
 }
 
@@ -90,12 +90,12 @@ type ApiCallRecord = {
 
 function createMockApiClient(options: {
 	success?: boolean;
-	versionStatus?: IdentifyVersionStatusEnum;
+	versionStatus?: (typeof IdentifyVersionStatusEnum)[keyof typeof IdentifyVersionStatusEnum];
 	errorStatus?: number;
 	errorMessage?: string;
 	sessionId?: string;
 	deviceId?: string;
-	personaId?: string;
+	user_id?: string;
 	token?: string;
 	throwError?: Error;
 } = {}) {
@@ -106,7 +106,7 @@ function createMockApiClient(options: {
 		errorMessage,
 		sessionId = "session-123",
 		deviceId = "device-123",
-		personaId = "persona-123",
+		user_id = "user-123",
 		token = "token-123",
 		throwError,
 	} = options;
@@ -143,7 +143,7 @@ function createMockApiClient(options: {
 					data: {
 						session_id: sessionId,
 						device_id: deviceId,
-						persona_id: personaId,
+						user_id: user_id,
 						token: token,
 						version_info: { status: versionStatus },
 					},
@@ -152,7 +152,7 @@ function createMockApiClient(options: {
 		},
 		getCalls: () => calls,
 		getLastCall: () => calls[calls.length - 1],
-		clearCalls: () => calls.length = 0,
+		clearCalls: () => { calls.length = 0; },
 	};
 }
 
@@ -214,7 +214,7 @@ describe("IdentityClient", () => {
 			const mockStorage = createMockStorageClient();
 			const storedState = {
 				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 },
 			};
 			mockStorage.getStorage().set(IDENTIFY_STORAGE_KEY, JSON.stringify(storedState));
@@ -227,7 +227,7 @@ describe("IdentityClient", () => {
 			if (state.type === "identified") {
 				expect(state.session.session_id).toBe("s1");
 				expect(state.session.device_id).toBe("d1");
-				expect(state.session.persona_id).toBe("p1");
+				expect(state.session.user_id).toBe("p1");
 				expect(state.session.token).toBe("t1");
 			}
 		});
@@ -296,7 +296,7 @@ describe("IdentityClient", () => {
 				versionStatus: IdentifyVersionStatusEnum.UPDATE_AVAILABLE,
 				sessionId: "custom-session",
 				deviceId: "custom-device",
-				personaId: "custom-persona",
+				user_id: "custom-user_id",
 				token: "custom-token",
 			});
 			const { client } = createTestClient({ api: mockApi });
@@ -307,7 +307,7 @@ describe("IdentityClient", () => {
 			if (result.success) {
 				expect(result.data.session_id).toBe("custom-session");
 				expect(result.data.device_id).toBe("custom-device");
-				expect(result.data.persona_id).toBe("custom-persona");
+				expect(result.data.user_id).toBe("custom-user_id");
 				expect(result.data.token).toBe("custom-token");
 				expect(result.data.version_info.status).toBe(IdentifyVersionStatusEnum.UPDATE_AVAILABLE);
 				expect(result.data.version_info.update).toBeNull();
@@ -360,7 +360,7 @@ describe("IdentityClient", () => {
 			const mockStorage = createMockStorageClient();
 			const storedState = {
 				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 },
 			};
 			mockStorage.getStorage().set(IDENTIFY_STORAGE_KEY, JSON.stringify(storedState));
@@ -484,7 +484,7 @@ describe("IdentityClient", () => {
 
 			const persona: Persona = {
 				name: "John Doe",
-				user_id: "user-456",
+				user_id: "user-123",
 				email: "john@example.com",
 			};
 
@@ -566,7 +566,7 @@ describe("IdentityClient", () => {
 			const mockStorage = createMockStorageClient();
 			const storedState = {
 				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 },
 			};
 			mockStorage.getStorage().set(IDENTIFY_STORAGE_KEY, JSON.stringify(storedState));
@@ -605,10 +605,10 @@ 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);
+			expect(mockLogging.getLogs().some(l => l.level === "debug")).toBe(true);
 		});
 	});
 
@@ -731,7 +731,7 @@ describe("IdentityClient", () => {
 					data: {
 						session_id: "refreshed-session",
 						device_id: "device-123",
-						persona_id: "persona-123",
+						user_id: "user-123",
 						token: "token-123",
 						version_info: { status: IdentifyVersionStatusEnum.UP_TO_DATE },
 					},
@@ -873,7 +873,7 @@ describe("IdentityClient", () => {
 			expect(session).not.toBeNull();
 			expect(session?.session_id).toBe("session-123");
 			expect(session?.device_id).toBe("device-123");
-			expect(session?.persona_id).toBe("persona-123");
+			expect(session?.user_id).toBe("user-123");
 			expect(session?.token).toBe("token-123");
 		});
 
@@ -891,7 +891,7 @@ describe("IdentityClient", () => {
 					data: {
 						session_id: "second-session",
 						device_id: "device-123",
-						persona_id: "persona-123",
+						user_id: "user-123",
 						token: "token-123",
 						version_info: { status: IdentifyVersionStatusEnum.UP_TO_DATE },
 					},
@@ -1002,7 +1002,7 @@ describe("IdentityClient", () => {
 						data: {
 							session_id: "session-123",
 							device_id: "device-123",
-							persona_id: "persona-123",
+							user_id: "user-123",
 							token: "token-123",
 							version_info: { status: IdentifyVersionStatusEnum.UP_TO_DATE },
 						},

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

@@ -17,7 +17,7 @@ export type Persona = {
 export type IdentityUser = {
 	session_id: string;
 	device_id: string;
-	persona_id: string;
+	user_id: string;
 	token: string;
 	version_info: {
 		status: IdentifyVersionStatusEnum;
@@ -40,7 +40,7 @@ export const UpdateVersionStatusBodySchema = z.object({
 export const SessionSchema = z.object({
 	session_id: z.string(),
 	device_id: z.string(),
-	persona_id: z.string(),
+	user_id: z.string(),
 	token: z.string(),
 });
 export type Session = z.infer<typeof SessionSchema>;
@@ -211,8 +211,8 @@ export class IdentityClient {
 		}
 	}
 
-	async identify(persona?: Persona): AsyncResult<IdentityUser> {
-		this.logger.debug(`Identifying user with persona: ${persona?.name ?? "none"}`);
+	async identify(user?: Persona): AsyncResult<IdentityUser> {
+		this.logger.debug(`Identifying user with persona: ${user?.name ?? "none"}`);
 		const previousState = this.identifyState;
 		this.setIdentifyState({ type: "identifying" });
 
@@ -231,8 +231,7 @@ export class IdentityClient {
 					"td-device-id": deviceId,
 				},
 				body: {
-					persona,
-					// @ts-expect-error - notifications is not yet implemented
+					user,
 					device: {
 						timestamp: deviceInfo.timestamp,
 						os: deviceInfo.os,

package/src/clients/storage/adapters/async-storage.adapter.ts

@@ -21,29 +21,27 @@ export class AsyncStorageAdapter extends StorageAdapter {
 		const prefixedKey = (key: string): string => `${storageKey}:${key}`;
 
 		return {
-			preload: () => {
+			preload: async (): Promise<void> => {
 				if (hydrated) return;
 
-				// Fire async hydration - cache will be populated when complete
-				AsyncStorage.getAllKeys()
-					.then((allKeys) => {
-						const relevantKeys = allKeys.filter((k) =>
-							k.startsWith(`${storageKey}:`)
-						);
-						return AsyncStorage.multiGet(relevantKeys);
-					})
-					.then((pairs) => {
-						for (const [fullKey, value] of pairs) {
-							if (value != null) {
-								const key = fullKey.replace(`${storageKey}:`, "");
-								cache[key] = value;
-							}
+				try {
+					const allKeys = await AsyncStorage.getAllKeys();
+					const relevantKeys = allKeys.filter((k) =>
+						k.startsWith(`${storageKey}:`)
+					);
+					const pairs = await AsyncStorage.multiGet(relevantKeys);
+
+					for (const [fullKey, value] of pairs) {
+						if (value != null) {
+							const key = fullKey.replace(`${storageKey}:`, "");
+							cache[key] = value;
 						}
-						hydrated = true;
-					})
-					.catch(() => {
-						// Silently fail - cache remains empty
-					});
+					}
+				} catch {
+					// Silently fail - cache remains empty
+				} finally {
+					hydrated = true;
+				}
 			},
 
 			getItem: (key: string): string | null => {

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

@@ -3,7 +3,7 @@
  * A storage interface that is used to store data.
  */
 export type SupportedStorage = {
-	preload: () => void;
+	preload: () => void | Promise<void>;
 	getItem: (key: string) => string | null;
 	setItem: (key: string, value: string) => void;
 	removeItem: (key: string) => void;

package/src/clients/storage/storage.client.ts

@@ -8,6 +8,14 @@ export class StorageClient {
 
   private readonly storage: Map<string, SupportedStorage> = new Map();
 
+  private readonly preloadPromises: Promise<void>[] = [];
+
+  private _isReady = false;
+
+  get isReady(): boolean {
+    return this._isReady;
+  }
+
   constructor(
     logging: LoggingClient,
     private readonly orgId: string,
@@ -40,7 +48,10 @@ export class StorageClient {
 
     this.logger.debug(`Creating new storage for ${fullStorageKey}`);
     const newStorage = this.storageAdapter.createStorage(fullStorageKey);
-    newStorage.preload();
+    const preloadResult = newStorage.preload();
+    if (preloadResult instanceof Promise) {
+      this.preloadPromises.push(preloadResult);
+    }
 
     const remappedStorage = {
       ...newStorage,
@@ -55,6 +66,11 @@ export class StorageClient {
     return remappedStorage;
   }
 
+  async whenReady(): Promise<void> {
+    await Promise.all(this.preloadPromises);
+    this._isReady = true;
+  }
+
   shutdown(): void {
     this.storage.forEach((storage) => {
       storage.clear();

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

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

package/src/teardown.core.ts

@@ -69,7 +69,9 @@ export class TeardownCore {
 	}
 
 	async initialize(): Promise<void> {
-		// Initialize identity first (loads from storage, then identifies if needed)
+		// Wait for all storage hydration to complete
+		await this.storage.whenReady();
+		// Initialize identity (loads from storage, then identifies if needed)
 		await this.identity.initialize();
 		// Then initialize force update (subscribes to identity events)
 		this.forceUpdate.initialize();

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

package/docs/02-core-concepts.mdx

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