@teardown/react-native 2.0.24 → 2.0.27

package/docs/adapters/device/basic.mdx

@@ -0,0 +1,59 @@
+---
+title: BasicAdapter
+description: Fallback device adapter with minimal or static device information.
+---
+
+The `BasicAdapter` provides minimal device information without external dependencies. Useful for testing or fallback scenarios.
+
+## Usage
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { BasicAdapter } from '@teardown/react-native/adapters/basic';
+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',
+  storageAdapter: new MMKVStorageAdapter(),
+  deviceAdapter: new BasicAdapter(),
+});
+```
+
+## Import Path
+
+```typescript
+import { BasicAdapter } from '@teardown/react-native/adapters/basic';
+```
+
+## Collected Data
+
+The BasicAdapter returns static or minimal information:
+
+### Application Info
+- `version` - Static value or from app.json
+- `buildNumber` - Static value
+- `bundleId` - Static value or from app.json
+
+### Hardware Info
+- `deviceName` - "Unknown Device"
+- `brand` - "Unknown"
+- `deviceType` - "unknown"
+
+### OS Info
+- `osName` - From React Native Platform API
+- `osVersion` - From React Native Platform API
+
+## When to Use
+
+- Unit testing without native modules
+- Development/prototyping
+- Fallback when other adapters fail
+- Environments where native modules aren't available
+
+## Limitations
+
+- Limited device information accuracy
+- No hardware-specific details
+- Not recommended for production analytics

package/docs/adapters/device/device-info.mdx

@@ -0,0 +1,76 @@
+---
+title: DeviceInfoAdapter
+description: Device adapter for bare React Native projects using react-native-device-info.
+---
+
+The `DeviceInfoAdapter` uses `react-native-device-info` to collect device information in bare React Native projects.
+
+## Installation
+
+```bash
+npm install react-native-device-info
+# or
+bun add react-native-device-info
+```
+
+For iOS, run pod install:
+```bash
+cd ios && pod install
+```
+
+## Usage
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { DeviceInfoAdapter } from '@teardown/react-native/adapters/device-info';
+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',
+  storageAdapter: new MMKVStorageAdapter(),
+  deviceAdapter: new DeviceInfoAdapter(),
+});
+```
+
+## Import Path
+
+```typescript
+import { DeviceInfoAdapter } from '@teardown/react-native/adapters/device-info';
+```
+
+## Collected Data
+
+### Application Info
+- `version` - From `getVersion()`
+- `buildNumber` - From `getBuildNumber()`
+- `bundleId` - From `getBundleId()`
+
+### Hardware Info
+- `deviceName` - From `getDeviceName()`
+- `brand` - From `getBrand()`
+- `deviceType` - From `getDeviceType()` (phone, tablet, desktop, tv, unknown)
+
+### OS Info
+- `osName` - From `getSystemName()`
+- `osVersion` - From `getSystemVersion()`
+
+## When to Use
+
+- Bare React Native CLI projects
+- Projects not using Expo modules
+- Projects requiring additional device info beyond what Expo provides
+
+## Requirements
+
+- `react-native-device-info` >= 10.0.0
+- React Native >= 0.60 (autolinking)
+
+## Platform Notes
+
+### iOS
+Requires `pod install` after installation.
+
+### Android
+Works out of the box with autolinking.

package/docs/adapters/device/expo.mdx

@@ -0,0 +1,61 @@
+---
+title: ExpoDeviceAdapter
+description: Device adapter for Expo projects using expo-device and expo-application.
+---
+
+The `ExpoDeviceAdapter` uses Expo's native modules to collect device information.
+
+## Installation
+
+```bash
+npx expo install expo-device expo-application
+```
+
+## Usage
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+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',
+  storageAdapter: new MMKVStorageAdapter(),
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+```
+
+## Import Path
+
+```typescript
+import { ExpoDeviceAdapter } from '@teardown/react-native/adapters/expo';
+```
+
+## Collected Data
+
+### Application Info
+- `version` - From `expo-application` `nativeApplicationVersion`
+- `buildNumber` - From `expo-application` `nativeBuildVersion`
+- `bundleId` - From `expo-application` `applicationId`
+
+### Hardware Info
+- `deviceName` - From `expo-device` `deviceName`
+- `brand` - From `expo-device` `brand`
+- `deviceType` - From `expo-device` `deviceType` (phone, tablet, desktop, tv, unknown)
+
+### OS Info
+- `osName` - From `expo-device` `osName`
+- `osVersion` - From `expo-device` `osVersion`
+
+## When to Use
+
+- Expo managed workflow projects
+- Expo bare workflow projects using Expo modules
+- Projects using Expo SDK 44+
+
+## Requirements
+
+- `expo-device` >= 4.0.0
+- `expo-application` >= 4.0.0

package/docs/adapters/device/index.mdx

@@ -0,0 +1,102 @@
+---
+title: Device Adapters
+description: Collect device, OS, and app information with platform adapters.
+icon: Monitor
+---
+
+Device adapters collect device and application information for identification and analytics. You must provide a device adapter when initializing `TeardownCore`.
+
+## Available Adapters
+
+| Adapter | Package | Best For |
+|---------|---------|----------|
+| [`ExpoDeviceAdapter`](/docs/react-native/adapters/device/expo) | `expo-device`, `expo-application` | Expo projects |
+| [`DeviceInfoAdapter`](/docs/react-native/adapters/device/device-info) | `react-native-device-info` | Bare RN projects |
+| [`BasicAdapter`](/docs/react-native/adapters/device/basic) | None | Fallback/testing |
+
+## Collected Information
+
+All device adapters provide:
+
+### Application Info
+
+```typescript
+interface ApplicationInfo {
+  version: string;      // App version (e.g., "1.2.3")
+  buildNumber: string;  // Build number (e.g., "45")
+  bundleId: string;     // Bundle identifier (e.g., "com.example.app")
+}
+```
+
+### Hardware Info
+
+```typescript
+interface HardwareInfo {
+  deviceName: string;   // Device name (e.g., "iPhone 14 Pro")
+  brand: string;        // Manufacturer (e.g., "Apple")
+  deviceType: string;   // Device type (e.g., "phone", "tablet")
+}
+```
+
+### OS Info
+
+```typescript
+interface OSInfo {
+  osName: string;       // OS name (e.g., "iOS", "Android")
+  osVersion: string;    // OS version (e.g., "17.0")
+}
+```
+
+## Usage
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { ExpoDeviceAdapter } from '@teardown/react-native/adapters/expo';
+
+const teardown = new TeardownCore({
+  deviceAdapter: new ExpoDeviceAdapter(),
+  // ... other options
+});
+```
+
+## Device ID
+
+The SDK generates a stable device ID that persists across app sessions:
+
+```typescript
+const deviceId = await core.device.getDeviceId();
+// Returns a UUID that persists in storage
+```
+
+## Custom Adapter
+
+Implement the `DeviceInfoAdapter` interface:
+
+```typescript
+import type { DeviceInfoAdapter, ApplicationInfo, HardwareInfo, OSInfo } from '@teardown/react-native';
+
+class CustomDeviceAdapter implements DeviceInfoAdapter {
+  get applicationInfo(): ApplicationInfo {
+    return {
+      version: '1.0.0',
+      buildNumber: '1',
+      bundleId: 'com.example.app',
+    };
+  }
+
+  get hardwareInfo(): HardwareInfo {
+    return {
+      deviceName: 'Custom Device',
+      brand: 'Custom',
+      deviceType: 'phone',
+    };
+  }
+
+  get osInfo(): OSInfo {
+    return {
+      osName: 'iOS',
+      osVersion: '17.0',
+    };
+  }
+}
+```

package/docs/adapters/device/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Device",
+	"pages": ["expo", "device-info", "basic"]
+}

package/docs/adapters/index.mdx

@@ -0,0 +1,96 @@
+---
+title: Adapters
+description: Platform adapters for storage, device info, and notifications.
+icon: Plug
+---
+
+The Teardown SDK uses adapters to abstract platform-specific functionality. This allows the SDK to work across different React Native environments (Expo, bare RN) and with different underlying libraries.
+
+## Adapter Types
+
+### Device Adapters
+
+Collect device and application information for identification and analytics.
+
+| Adapter | Package | Use Case |
+|---------|---------|----------|
+| [`ExpoDeviceAdapter`](/docs/react-native/adapters/device/expo) | `expo-device`, `expo-application` | Expo projects |
+| [`DeviceInfoAdapter`](/docs/react-native/adapters/device/device-info) | `react-native-device-info` | Bare RN projects |
+| [`BasicAdapter`](/docs/react-native/adapters/device/basic) | None | Fallback/testing |
+
+[View Device Adapters →](/docs/react-native/adapters/device)
+
+### Storage Adapters
+
+Handle persistent data storage for sessions, device IDs, and version status.
+
+| Adapter | Package | Use Case |
+|---------|---------|----------|
+| [`MMKVStorageAdapter`](/docs/react-native/adapters/storage/mmkv) | `react-native-mmkv` | Fast sync storage (recommended) |
+| [`AsyncStorageAdapter`](/docs/react-native/adapters/storage/async-storage) | `@react-native-async-storage/async-storage` | Broader compatibility |
+
+[View Storage Adapters →](/docs/react-native/adapters/storage)
+
+### Notification Adapters
+
+Handle push notification registration and token management.
+
+| Adapter | Package | Use Case |
+|---------|---------|----------|
+| [`ExpoNotificationsAdapter`](/docs/react-native/adapters/notifications/expo) | `expo-notifications` | Expo projects |
+| [`FirebaseMessagingAdapter`](/docs/react-native/adapters/notifications/firebase) | `@react-native-firebase/messaging` | Firebase Cloud Messaging |
+| [`WixNotificationsAdapter`](/docs/react-native/adapters/notifications/wix) | `react-native-notifications` | Wix notifications library |
+
+[View Notification Adapters →](/docs/react-native/adapters/notifications)
+
+## Required Adapters
+
+When initializing `TeardownCore`, you must provide:
+
+```typescript
+const teardown = new TeardownCore({
+  org_id: 'your-org-id',
+  project_id: 'your-project-id',
+  api_key: 'your-api-key',
+  storageAdapter: new MMKVStorageAdapter(),    // Required
+  deviceAdapter: new ExpoDeviceAdapter(),       // Required
+});
+```
+
+## Common Configurations
+
+### Expo Project
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+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',
+  storageAdapter: new MMKVStorageAdapter(),
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+```
+
+### Bare React Native Project
+
+```typescript
+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(),
+});
+```
+
+## Custom Adapters
+
+All adapter types can be extended for custom implementations. See individual adapter sections for interface definitions.

package/docs/adapters/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Adapters",
+	"pages": ["device", "storage", "notifications"]
+}

package/docs/adapters/notifications/expo.mdx

@@ -0,0 +1,127 @@
+---
+title: ExpoNotificationsAdapter
+description: Notification adapter for Expo projects using expo-notifications.
+---
+
+The `ExpoNotificationsAdapter` integrates with Expo's notifications library for push notification handling.
+
+## Installation
+
+```bash
+npx expo install expo-notifications expo-device expo-constants
+```
+
+## Usage
+
+```typescript
+import { ExpoNotificationsAdapter } from '@teardown/react-native/expo-notifications';
+
+const notifications = new ExpoNotificationsAdapter();
+
+// Request permissions
+const granted = await notifications.requestPermissions();
+
+if (granted) {
+  // Get push token
+  const token = await notifications.getToken();
+  console.log('Push token:', token);
+}
+```
+
+## Import Path
+
+```typescript
+import { ExpoNotificationsAdapter } from '@teardown/react-native/expo-notifications';
+```
+
+## API
+
+### getToken()
+
+Get the Expo push token:
+
+```typescript
+const token = await notifications.getToken();
+// Returns: "ExponentPushToken[xxxxxx]" or null
+```
+
+### requestPermissions()
+
+Request notification permissions:
+
+```typescript
+const granted = await notifications.requestPermissions();
+// Returns: true if granted, false otherwise
+```
+
+### isEnabled()
+
+Check if notifications are enabled:
+
+```typescript
+const enabled = await notifications.isEnabled();
+```
+
+### onNotification()
+
+Subscribe to incoming notifications while app is foregrounded:
+
+```typescript
+const unsubscribe = notifications.onNotification((notification) => {
+  console.log('Received:', notification.title);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+### onNotificationResponse()
+
+Subscribe to notification responses (user taps):
+
+```typescript
+const unsubscribe = notifications.onNotificationResponse((response) => {
+  console.log('User tapped notification:', response.notification.title);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+## Configuration
+
+### app.json / app.config.js
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-notifications",
+        {
+          "icon": "./assets/notification-icon.png",
+          "color": "#ffffff"
+        }
+      ]
+    ]
+  }
+}
+```
+
+### Android
+
+For FCM integration, add your `google-services.json` to the project root.
+
+### iOS
+
+Push notifications require:
+- Apple Developer account
+- Push notification capability
+- APNs certificate or key
+
+## Requirements
+
+- `expo-notifications` >= 0.17.0
+- `expo-device` >= 4.0.0
+- `expo-constants` >= 13.0.0
+- EAS Build or dev client (not Expo Go)

package/docs/adapters/notifications/firebase.mdx

@@ -0,0 +1,142 @@
+---
+title: FirebaseMessagingAdapter
+description: Notification adapter for Firebase Cloud Messaging.
+---
+
+The `FirebaseMessagingAdapter` integrates with Firebase Cloud Messaging for push notifications.
+
+## Installation
+
+```bash
+npm install @react-native-firebase/app @react-native-firebase/messaging
+# or
+bun add @react-native-firebase/app @react-native-firebase/messaging
+```
+
+For iOS:
+```bash
+cd ios && pod install
+```
+
+## Usage
+
+```typescript
+import { FirebaseMessagingAdapter } from '@teardown/react-native/firebase-messaging';
+
+const notifications = new FirebaseMessagingAdapter();
+
+// Request permissions (iOS)
+const granted = await notifications.requestPermissions();
+
+if (granted) {
+  // Get FCM token
+  const token = await notifications.getToken();
+  console.log('FCM token:', token);
+}
+```
+
+## Import Path
+
+```typescript
+import { FirebaseMessagingAdapter } from '@teardown/react-native/firebase-messaging';
+```
+
+## API
+
+### getToken()
+
+Get the FCM registration token:
+
+```typescript
+const token = await notifications.getToken();
+// Returns: FCM token string or null
+```
+
+### requestPermissions()
+
+Request notification permissions (required on iOS):
+
+```typescript
+const granted = await notifications.requestPermissions();
+// Returns: true if granted, false otherwise
+```
+
+### isEnabled()
+
+Check if notifications are enabled:
+
+```typescript
+const enabled = await notifications.isEnabled();
+```
+
+### onNotification()
+
+Subscribe to incoming notifications:
+
+```typescript
+const unsubscribe = notifications.onNotification((notification) => {
+  console.log('Received:', notification.title);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+### onNotificationResponse()
+
+Subscribe to notification opens:
+
+```typescript
+const unsubscribe = notifications.onNotificationResponse((response) => {
+  console.log('User tapped:', response.notification.title);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+## Configuration
+
+### Android
+
+1. Add `google-services.json` to `android/app/`
+2. Add to `android/build.gradle`:
+
+```groovy
+buildscript {
+  dependencies {
+    classpath 'com.google.gms:google-services:4.3.15'
+  }
+}
+```
+
+3. Add to `android/app/build.gradle`:
+
+```groovy
+apply plugin: 'com.google.gms.google-services'
+```
+
+### iOS
+
+1. Add `GoogleService-Info.plist` to iOS project
+2. Enable Push Notifications capability in Xcode
+3. Upload APNs key to Firebase Console
+
+## Background Messages
+
+Handle messages when app is in background:
+
+```typescript
+import messaging from '@react-native-firebase/messaging';
+
+// Register background handler (must be outside component)
+messaging().setBackgroundMessageHandler(async (remoteMessage) => {
+  console.log('Background message:', remoteMessage);
+});
+```
+
+## Requirements
+
+- `@react-native-firebase/app` >= 18.0.0
+- `@react-native-firebase/messaging` >= 18.0.0
+- React Native >= 0.71