@teardown/react-native 2.0.29 → 2.0.30

package/docs/api-reference.mdx

@@ -21,8 +21,11 @@ new TeardownCore(options: TeardownCoreOptions)
 | `org_id` | `string` | Yes | Organization ID from dashboard |
 | `project_id` | `string` | Yes | Project ID from dashboard |
 | `api_key` | `string` | Yes | API key from dashboard |
+| `environment_slug` | `string` | No | Environment slug (default: "production") |
+| `ingestUrl` | `string` | No | Custom ingest API URL for local/staging |
 | `storageAdapter` | `StorageAdapter` | Yes | Storage adapter instance |
 | `deviceAdapter` | `DeviceInfoAdapter` | Yes | Device info adapter instance |
+| `notificationAdapter` | `NotificationAdapter` | No | Push notification adapter instance |
 | `forceUpdate` | `ForceUpdateClientOptions` | No | Force update configuration |
 
 ### Methods
@@ -38,8 +41,10 @@ new TeardownCore(options: TeardownCoreOptions)
 |----------|------|-------------|
 | `api` | `ApiClient` | Backend API client |
 | `device` | `DeviceClient` | Device information client |
+| `events` | `EventsClient` | Event tracking client |
 | `identity` | `IdentityClient` | Identity management client |
 | `forceUpdate` | `ForceUpdateClient` | Version checking client |
+| `notifications` | `NotificationsClient \| undefined` | Push notifications client (if adapter provided) |
 
 ---
 
@@ -53,7 +58,8 @@ Manages user and device identification.
 |--------|---------|-------------|
 | `identify(persona?)` | `AsyncResult<IdentityUser>` | Identify user/device |
 | `refresh()` | `AsyncResult<IdentityUser>` | Re-identify current user |
-| `reset()` | `void` | Clear session data |
+| `signOut(options?)` | `AsyncResult<void>` | Sign out user, preserve device |
+| `signOutAll(options?)` | `AsyncResult<void>` | Sign out and reset device |
 | `getIdentifyState()` | `IdentifyState` | Get current state |
 | `getSessionState()` | `Session \| null` | Get current session |
 | `onIdentifyStateChange(listener)` | `() => void` | Subscribe to state changes |
@@ -89,6 +95,17 @@ type IdentifyState =
   | { type: 'identified'; session: Session; version_info: VersionInfo };
 ```
 
+### SignOutOptions
+
+```typescript
+interface SignOutOptions {
+  // Additional properties to include in the sign out event
+  properties?: Record<string, unknown>;
+  // Wait for event to be sent before clearing state (default: true)
+  waitForEvent?: boolean;
+}
+```
+
 ---
 
 ## ForceUpdateClient
@@ -118,14 +135,144 @@ type VersionStatus =
   | { type: 'initializing' }
   | { type: 'checking' }
   | { type: 'up_to_date' }
-  | { type: 'update_available' }
-  | { type: 'update_recommended' }
-  | { type: 'update_required' }
+  | { type: 'update_available'; releaseNotes?: string | null }
+  | { type: 'update_recommended'; releaseNotes?: string | null }
+  | { type: 'update_required'; releaseNotes?: string | null }
   | { type: 'disabled' };
 ```
 
 ---
 
+## EventsClient
+
+Tracks events to the backend.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `track(event, sessionId?)` | `AsyncResult<void>` | Track a single event |
+| `trackBatch(events, sessionId?)` | `AsyncResult<void>` | Track multiple events |
+
+### EventPayload
+
+```typescript
+interface EventPayload {
+  /** Name of the event (e.g., "button_clicked", "page_viewed") */
+  event_name: string;
+  /** Type of event */
+  event_type?: "action" | "screen_view" | "custom";
+  /** Additional properties to attach to the event */
+  properties?: Record<string, unknown>;
+  /** ISO timestamp. Defaults to current time if not provided */
+  timestamp?: string;
+}
+```
+
+### Usage
+
+```typescript
+const { core } = useTeardown();
+
+// Track a single event
+await core.events.track({
+  event_name: 'button_clicked',
+  event_type: 'action',
+  properties: { button_id: 'submit-form' }
+});
+
+// Track multiple events
+await core.events.trackBatch([
+  { event_name: 'page_viewed', event_type: 'screen_view', properties: { page: 'home' } },
+  { event_name: 'cta_shown', event_type: 'action' }
+]);
+```
+
+---
+
+## NotificationsClient
+
+Manages push notifications across different providers. Only available if `notificationAdapter` is provided in TeardownCore options.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `requestPermissions()` | `Promise<PermissionStatus>` | Request notification permissions |
+| `getToken()` | `Promise<string \| null>` | Get push notification token |
+| `onTokenChange(listener)` | `Unsubscribe` | Subscribe to token changes |
+| `onNotificationReceived(listener)` | `Unsubscribe` | Subscribe to foreground notifications |
+| `onNotificationOpened(listener)` | `Unsubscribe` | Subscribe to notification taps |
+| `onDataMessage(listener)` | `Unsubscribe` | Subscribe to silent/data messages |
+| `destroy()` | `void` | Cleanup resources |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `platform` | `NotificationPlatformEnum` | Notification platform (APNS, FCM, EXPO) |
+
+### PermissionStatus
+
+```typescript
+interface PermissionStatus {
+  granted: boolean;
+  canAskAgain: boolean;
+}
+```
+
+### PushNotification
+
+```typescript
+interface PushNotification {
+  title?: string;
+  body?: string;
+  data?: Record<string, unknown>;
+}
+```
+
+### DataMessage
+
+```typescript
+interface DataMessage {
+  data: Record<string, unknown>;
+}
+```
+
+### NotificationPlatformEnum
+
+```typescript
+enum NotificationPlatformEnum {
+  APNS = "APNS",  // Apple Push Notification Service
+  FCM = "FCM",    // Firebase Cloud Messaging
+  EXPO = "EXPO",  // Expo Push Notifications
+}
+```
+
+### Usage
+
+```typescript
+const { core } = useTeardown();
+
+if (core.notifications) {
+  // Request permissions
+  const status = await core.notifications.requestPermissions();
+
+  // Get token for backend
+  const token = await core.notifications.getToken();
+
+  // Listen for foreground notifications
+  const unsub = core.notifications.onNotificationReceived((notification) => {
+    console.log('Notification:', notification.title);
+  });
+
+  // Cleanup
+  unsub();
+}
+```
+
+---
+
 ## DeviceClient
 
 Collects device information.
@@ -136,15 +283,18 @@ Collects device information.
 |--------|---------|-------------|
 | `getDeviceId()` | `Promise<string>` | Get stable device UUID |
 | `getDeviceInfo()` | `Promise<DeviceInfo>` | Get full device info |
+| `reset()` | `void` | Clear stored deviceId (new ID on next call) |
 
 ### DeviceInfo
 
 ```typescript
 interface DeviceInfo {
-  timestamp: string;
+  timestamp?: Date;
   os: OSInfo;
   hardware: HardwareInfo;
   application: ApplicationInfo;
+  update: DeviceUpdateInfo | null;
+  notifications?: NotificationsInfo;
 }
 ```
 
@@ -192,8 +342,7 @@ Interface for device information adapters.
 ```typescript
 interface ApplicationInfo {
   version: string;
-  buildNumber: string;
-  bundleId: string;
+  build_number: number;
 }
 ```
 
@@ -201,9 +350,9 @@ interface ApplicationInfo {
 
 ```typescript
 interface HardwareInfo {
-  deviceName: string;
-  brand: string;
-  deviceType: string;
+  device_name: string;
+  device_brand: string;
+  device_type: string;
 }
 ```
 
@@ -211,8 +360,24 @@ interface HardwareInfo {
 
 ```typescript
 interface OSInfo {
-  osName: string;
-  osVersion: string;
+  platform: DevicePlatformEnum;
+  name: string;
+  version: string;
+}
+```
+
+### DevicePlatformEnum
+
+```typescript
+enum DevicePlatformEnum {
+  IOS = "IOS",
+  ANDROID = "ANDROID",
+  WEB = "WEB",
+  WINDOWS = "WINDOWS",
+  MACOS = "MACOS",
+  LINUX = "LINUX",
+  UNKNOWN = "UNKNOWN",
+  // ... and more
 }
 ```
 

package/docs/core-concepts.mdx

@@ -10,12 +10,14 @@ The Teardown SDK is built around a central `TeardownCore` class that orchestrate
 
 ```
 TeardownCore
-├── IdentityClient      # User/device identification
-├── ForceUpdateClient   # Version checking
-├── DeviceClient        # Device information
-├── StorageClient       # Persistent storage
-├── ApiClient           # Backend communication
-└── LoggingClient       # Structured logging
+├── IdentityClient       # User/device identification
+├── ForceUpdateClient    # Version checking
+├── DeviceClient         # Device information
+├── EventsClient         # Event tracking
+├── NotificationsClient  # Push notifications (optional)
+├── StorageClient        # Persistent storage
+├── ApiClient            # Backend communication
+└── LoggingClient        # Structured logging
 ```
 
 ## Initialization Flow
@@ -58,9 +60,9 @@ type VersionStatus =
   | { type: 'initializing' }
   | { type: 'checking' }
   | { type: 'up_to_date' }
-  | { type: 'update_available' }
-  | { type: 'update_recommended' }
-  | { type: 'update_required' }
+  | { type: 'update_available'; releaseNotes?: string | null }
+  | { type: 'update_recommended'; releaseNotes?: string | null }
+  | { type: 'update_required'; releaseNotes?: string | null }
   | { type: 'disabled' };
 ```
 
@@ -88,10 +90,26 @@ interface SupportedStorage {
 Provide device and app information:
 
 ```typescript
-interface DeviceInfoAdapter {
-  applicationInfo: ApplicationInfo;  // version, buildNumber, bundleId
-  hardwareInfo: HardwareInfo;        // deviceName, brand, deviceType
-  osInfo: OSInfo;                    // osName, osVersion
+abstract class DeviceInfoAdapter {
+  applicationInfo: ApplicationInfo;  // version, build_number
+  hardwareInfo: HardwareInfo;        // device_name, device_brand, device_type
+  osInfo: OSInfo;                    // platform, name, version
+}
+```
+
+### Notification Adapters
+
+Handle push notification registration and events (optional):
+
+```typescript
+abstract class NotificationAdapter {
+  platform: NotificationPlatformEnum;
+  getToken(): Promise<string | null>;
+  requestPermissions(): Promise<PermissionStatus>;
+  onTokenRefresh(listener): Unsubscribe;
+  onNotificationReceived(listener): Unsubscribe;
+  onNotificationOpened(listener): Unsubscribe;
+  onDataMessage(listener): Unsubscribe;
 }
 ```
 

package/docs/force-updates.mdx

@@ -21,12 +21,14 @@ type VersionStatus =
   | { type: 'initializing' }   // SDK starting up
   | { type: 'checking' }       // Version check in progress
   | { type: 'up_to_date' }     // Current version is valid
-  | { type: 'update_available' }   // Optional update exists
-  | { type: 'update_recommended' } // Recommended update exists
-  | { type: 'update_required' }    // Must update to continue
+  | { type: 'update_available'; releaseNotes?: string | null }   // Optional update exists
+  | { type: 'update_recommended'; releaseNotes?: string | null } // Recommended update exists
+  | { type: 'update_required'; releaseNotes?: string | null }    // Must update to continue
   | { type: 'disabled' }       // Version/build has been disabled
 ```
 
+Update status types include an optional `releaseNotes` field containing notes set in the dashboard when changing version/build status.
+
 ## Basic Usage
 
 ### Using the Hook
@@ -35,16 +37,16 @@ type VersionStatus =
 import { useForceUpdate } from '@teardown/react-native';
 
 function App() {
-  const { versionStatus, isUpdateRequired, isUpdateAvailable, isUpdateRecommended } = useForceUpdate();
+  const { versionStatus, isUpdateRequired, isUpdateAvailable, isUpdateRecommended, releaseNotes } = useForceUpdate();
 
   if (isUpdateRequired) {
-    return <ForceUpdateModal />;
+    return <ForceUpdateModal releaseNotes={releaseNotes} />;
   }
 
   if (isUpdateRecommended) {
     return (
       <>
-        <UpdateBanner onDismiss={() => {}} />
+        <UpdateBanner releaseNotes={releaseNotes} onDismiss={() => {}} />
         <MainApp />
       </>
     );
@@ -62,6 +64,7 @@ interface UseForceUpdateResult {
   isUpdateAvailable: boolean;        // Any update exists (available, recommended, or required)
   isUpdateRecommended: boolean;      // Update is recommended but not required
   isUpdateRequired: boolean;         // Update is mandatory
+  releaseNotes: string | null;       // Release notes for the update, if available
 }
 ```
 
@@ -114,7 +117,7 @@ unsubscribe();
 ### Force Update Modal
 
 ```tsx
-function ForceUpdateModal() {
+function ForceUpdateModal({ releaseNotes }: { releaseNotes: string | null }) {
   const handleUpdate = () => {
     // Open app store
     Linking.openURL('https://apps.apple.com/app/your-app');
@@ -125,6 +128,12 @@ function ForceUpdateModal() {
       <View style={styles.container}>
         <Text>Update Required</Text>
         <Text>Please update to continue using the app.</Text>
+        {releaseNotes && (
+          <View style={styles.releaseNotes}>
+            <Text style={styles.releaseNotesTitle}>What's New:</Text>
+            <Text>{releaseNotes}</Text>
+          </View>
+        )}
         <Button onPress={handleUpdate} title="Update Now" />
       </View>
     </Modal>
@@ -135,7 +144,7 @@ function ForceUpdateModal() {
 ### Soft Update Banner
 
 ```tsx
-function UpdateBanner({ onDismiss }: { onDismiss: () => void }) {
+function UpdateBanner({ releaseNotes, onDismiss }: { releaseNotes: string | null; onDismiss: () => void }) {
   const { isUpdateRecommended } = useForceUpdate();
 
   if (!isUpdateRecommended) return null;
@@ -143,6 +152,7 @@ function UpdateBanner({ onDismiss }: { onDismiss: () => void }) {
   return (
     <View style={styles.banner}>
       <Text>A new version is available</Text>
+      {releaseNotes && <Text style={styles.notes}>{releaseNotes}</Text>}
       <Button onPress={onDismiss} title="Later" />
       <Button onPress={() => Linking.openURL('...')} title="Update" />
     </View>

package/docs/hooks-reference.mdx

@@ -105,7 +105,7 @@ Returns `null` if not identified.
 
 The hook subscribes to `identity.onIdentifyStateChange()` and re-renders when:
 - User identifies (session available)
-- User resets (session becomes null)
+- User signs out (session becomes null)
 - Session refreshes (new session data)
 
 ---
@@ -122,17 +122,18 @@ function App() {
     versionStatus,
     isUpdateAvailable,
     isUpdateRecommended,
-    isUpdateRequired
+    isUpdateRequired,
+    releaseNotes
   } = useForceUpdate();
 
   if (isUpdateRequired) {
-    return <ForceUpdateModal />;
+    return <ForceUpdateModal releaseNotes={releaseNotes} />;
   }
 
   if (isUpdateRecommended) {
     return (
       <>
-        <UpdateBanner />
+        <UpdateBanner releaseNotes={releaseNotes} />
         <MainApp />
       </>
     );
@@ -154,6 +155,8 @@ interface UseForceUpdateResult {
   isUpdateRecommended: boolean;
   /** Update is mandatory */
   isUpdateRequired: boolean;
+  /** Release notes for the update, if available (set in dashboard when changing status) */
+  releaseNotes: string | null;
 }
 ```
 
@@ -222,8 +225,8 @@ function App() {
 function LogoutButton() {
   const { core } = useTeardown();
 
-  const handleLogout = () => {
-    core.identity.reset();
+  const handleLogout = async () => {
+    await core.identity.signOut();
     // Session will become null, useSession will re-render
   };
 

package/docs/identity.mdx

@@ -58,12 +58,51 @@ if (session) {
 }
 ```
 
-### Reset Identity
+### Sign Out
 
-Clear the current session and device association:
+Sign out the current user while preserving the device identity:
 
 ```typescript
-core.identity.reset();
+const result = await core.identity.signOut();
+
+if (result.success) {
+  console.log('Signed out successfully');
+} else {
+  console.error('Sign out failed:', result.error);
+}
+```
+
+This clears the session and user association but keeps the device ID. The same device will be recognized on the next `identify()` call.
+
+### Sign Out All (Full Reset)
+
+Sign out and reset all SDK state including the device ID:
+
+```typescript
+const result = await core.identity.signOutAll();
+```
+
+This clears everything - the device will appear as a fresh install on the next `identify()` call.
+
+### Sign Out Options
+
+Both `signOut()` and `signOutAll()` accept optional configuration:
+
+```typescript
+interface SignOutOptions {
+  // Additional properties to include in the sign out event
+  properties?: Record<string, unknown>;
+  // Wait for event to be sent before clearing state (default: true)
+  waitForEvent?: boolean;
+}
+
+// Example: Fire-and-forget sign out
+await core.identity.signOut({ waitForEvent: false });
+
+// Example: Include custom properties
+await core.identity.signOut({
+  properties: { reason: 'user_requested' }
+});
 ```
 
 ### Refresh Session
@@ -166,6 +205,7 @@ if (!result.success) {
 ## 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
+2. **Call signOut on logout** - Clear session data and notify the backend
+3. **Use signOutAll for account switching** - When users switch accounts, use `signOutAll()` for a clean slate
+4. **Handle offline** - The SDK caches session data for offline use
+5. **Use useSession hook** - For reactive UI updates

package/docs/logging.mdx

@@ -135,10 +135,11 @@ class Logger {
 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:
+4. **Set log level based on environment**:
 
 ```typescript
-if (core.logging.shouldLog('verbose')) {
-  console.log('Complex debug:', JSON.stringify(largeObject));
-}
+const teardown = new TeardownCore({ /* ... */ });
+
+// Set based on environment
+teardown.setLogLevel(__DEV__ ? 'verbose' : 'error');
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@teardown/react-native",
-	"version": "2.0.29",
+	"version": "2.0.30",
 	"type": "module",
 	"private": false,
 	"publishConfig": {
@@ -52,9 +52,9 @@
 		"prepublishOnly": "bun run build"
 	},
 	"dependencies": {
-		"@teardown/ingest-api": "2.0.29",
-		"@teardown/schemas": "2.0.29",
-		"@teardown/types": "2.0.29",
+		"@teardown/ingest-api": "2.0.30",
+		"@teardown/schemas": "2.0.30",
+		"@teardown/types": "2.0.30",
 		"eventemitter3": "^5.0.1",
 		"react-native-get-random-values": "^2.0.0",
 		"uuid": "^13.0.0",
@@ -64,7 +64,7 @@
 		"@biomejs/biome": "2.3.10",
 		"@elysiajs/eden": "1.4.5",
 		"@react-native-firebase/messaging": "*",
-		"@teardown/tsconfig": "2.0.29",
+		"@teardown/tsconfig": "2.0.30",
 		"@types/bun": "1.3.5",
 		"@types/react": "~19.1.0",
 		"@types/uuid": "^11.0.0",

package/src/clients/api/api.client.ts

@@ -77,4 +77,8 @@ export class ApiClient {
 	get environmentSlug(): string {
 		return this.options.environment_slug ?? "production";
 	}
+
+	get ingestUrl(): string {
+		return this.options.ingestUrl ?? TEARDOWN_INGEST_URL;
+	}
 }

package/src/clients/device/device.client.ts

@@ -67,4 +67,13 @@ export class DeviceClient {
 	async getDeviceInfo(): Promise<DeviceInfo> {
 		return this.options.adapter.getDeviceInfo();
 	}
+
+	/**
+	 * Reset the device client by clearing the stored deviceId.
+	 * This will generate a new deviceId on next getDeviceId() call.
+	 */
+	reset(): void {
+		this.logger.debug("Resetting device - clearing deviceId");
+		this.storage.removeItem("deviceId");
+	}
 }