@teardown/react-native 2.0.24 → 2.0.27

package/docs/adapters/notifications/index.mdx

@@ -0,0 +1,100 @@
+---
+title: Notification Adapters
+description: Push notification adapters for token registration and management.
+icon: Bell
+---
+
+Notification adapters handle push notification token registration and management with your push notification provider.
+
+## Available Adapters
+
+| Adapter | Package | Best For |
+|---------|---------|----------|
+| [`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 |
+
+## Usage
+
+Notification adapters are optional and used separately from the core SDK:
+
+```typescript
+import { ExpoNotificationsAdapter } from '@teardown/react-native/expo-notifications';
+
+const notificationsAdapter = new ExpoNotificationsAdapter();
+
+// Get push token
+const token = await notificationsAdapter.getToken();
+
+// Register token with your backend
+await registerPushToken(token);
+```
+
+## Adapter Interface
+
+All notification adapters implement:
+
+```typescript
+interface NotificationsAdapter {
+  /** Get the push notification token */
+  getToken(): Promise<string | null>;
+
+  /** Request notification permissions */
+  requestPermissions(): Promise<boolean>;
+
+  /** Check if notifications are enabled */
+  isEnabled(): Promise<boolean>;
+
+  /** Subscribe to incoming notifications */
+  onNotification(handler: (notification: Notification) => void): () => void;
+
+  /** Subscribe to notification responses (user taps) */
+  onNotificationResponse(handler: (response: NotificationResponse) => void): () => void;
+}
+```
+
+## Choosing an Adapter
+
+| If you're using... | Use this adapter |
+|-------------------|------------------|
+| Expo with expo-notifications | `ExpoNotificationsAdapter` |
+| Firebase Cloud Messaging | `FirebaseMessagingAdapter` |
+| Wix react-native-notifications | `WixNotificationsAdapter` |
+| Other push library | Implement custom adapter |
+
+## Custom Adapter
+
+Implement the `NotificationsAdapter` interface:
+
+```typescript
+import type { NotificationsAdapter, Notification, NotificationResponse } from '@teardown/react-native';
+
+class CustomNotificationsAdapter implements NotificationsAdapter {
+  async getToken(): Promise<string | null> {
+    // Return push token from your notification library
+    return await myNotificationLib.getToken();
+  }
+
+  async requestPermissions(): Promise<boolean> {
+    // Request notification permissions
+    return await myNotificationLib.requestPermission();
+  }
+
+  async isEnabled(): Promise<boolean> {
+    // Check if notifications are enabled
+    return await myNotificationLib.areNotificationsEnabled();
+  }
+
+  onNotification(handler: (notification: Notification) => void): () => void {
+    // Subscribe to incoming notifications
+    const subscription = myNotificationLib.onNotification(handler);
+    return () => subscription.remove();
+  }
+
+  onNotificationResponse(handler: (response: NotificationResponse) => void): () => void {
+    // Subscribe to notification taps
+    const subscription = myNotificationLib.onNotificationOpened(handler);
+    return () => subscription.remove();
+  }
+}
+```

package/docs/adapters/notifications/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Notifications",
+	"pages": ["expo", "firebase", "wix"]
+}

package/docs/adapters/notifications/wix.mdx

@@ -0,0 +1,140 @@
+---
+title: WixNotificationsAdapter
+description: Notification adapter for Wix react-native-notifications library.
+---
+
+The `WixNotificationsAdapter` integrates with Wix's react-native-notifications library.
+
+## Installation
+
+```bash
+npm install react-native-notifications
+# or
+bun add react-native-notifications
+```
+
+For iOS:
+```bash
+cd ios && pod install
+```
+
+## Usage
+
+```typescript
+import { WixNotificationsAdapter } from '@teardown/react-native/wix-notifications';
+
+const notifications = new WixNotificationsAdapter();
+
+// 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 { WixNotificationsAdapter } from '@teardown/react-native/wix-notifications';
+```
+
+## API
+
+### getToken()
+
+Get the device push token:
+
+```typescript
+const token = await notifications.getToken();
+// Returns: device token string 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:
+
+```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
+
+### iOS
+
+1. Enable Push Notifications capability in Xcode
+2. Add to `AppDelegate.m`:
+
+```objc
+#import <RNNotifications.h>
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+  [RNNotifications startMonitorNotifications];
+  return YES;
+}
+
+- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
+  [RNNotifications didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
+}
+
+- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
+  [RNNotifications didFailToRegisterForRemoteNotificationsWithError:error];
+}
+```
+
+### Android
+
+1. Add Firebase configuration (google-services.json)
+2. Initialize in `MainApplication.java`:
+
+```java
+import com.wix.reactnativenotifications.RNNotificationsPackage;
+```
+
+## When to Use
+
+- Existing projects using react-native-notifications
+- Projects requiring fine-grained notification control
+- Cross-platform notification handling
+
+## Requirements
+
+- `react-native-notifications` >= 4.0.0
+- React Native >= 0.60

package/docs/adapters/storage/async-storage.mdx

@@ -0,0 +1,95 @@
+---
+title: AsyncStorageAdapter
+description: Storage adapter using @react-native-async-storage/async-storage.
+---
+
+The `AsyncStorageAdapter` uses the community AsyncStorage library for persistent storage with broad platform compatibility.
+
+## Installation
+
+```bash
+npm install @react-native-async-storage/async-storage
+# or
+bun add @react-native-async-storage/async-storage
+```
+
+For Expo:
+```bash
+npx expo install @react-native-async-storage/async-storage
+```
+
+## Usage
+
+```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(),
+});
+```
+
+## Import Path
+
+```typescript
+import { AsyncStorageAdapter } from '@teardown/react-native/adapters/async-storage';
+```
+
+## When to Use
+
+- Web support needed
+- Existing AsyncStorage setup in your app
+- Simpler debugging (plain text storage)
+- Expo Go compatibility (no dev build needed)
+
+## Trade-offs
+
+### Pros
+- Broader platform support (iOS, Android, Web)
+- Works in Expo Go without dev build
+- Plain text storage (easier debugging)
+- Well-established, stable API
+
+### Cons
+- Asynchronous API (slightly slower)
+- No built-in encryption
+- Larger bundle size than MMKV
+
+## How It Works
+
+AsyncStorage provides a key-value storage API:
+
+1. The adapter wraps AsyncStorage with a synchronous-like interface
+2. Uses `preload()` to hydrate data into memory at startup
+3. Writes are persisted asynchronously
+
+## Requirements
+
+- `@react-native-async-storage/async-storage` >= 1.17.0
+- React Native >= 0.60
+
+## Platform Notes
+
+### iOS
+- Data stored in NSUserDefaults (small data) or files (large data)
+- Not encrypted by default
+
+### Android
+- Data stored in SQLite database
+- Not encrypted by default
+
+### Web
+- Uses localStorage
+- Size limited (~5MB)
+
+## Encryption Note
+
+AsyncStorage does not encrypt data by default. For sensitive data, consider:
+- Using MMKV instead (encrypted by default)
+- Encrypting values before storage
+- Using a separate encrypted storage for secrets

package/docs/adapters/storage/index.mdx

@@ -0,0 +1,93 @@
+---
+title: Storage Adapters
+description: Persistent storage adapters for sessions, device IDs, and version status.
+icon: Database
+---
+
+Storage adapters handle persistent data storage for the SDK. You must provide a storage adapter when initializing `TeardownCore`.
+
+## Available Adapters
+
+| Adapter | Package | Sync/Async | Best For |
+|---------|---------|-----------|----------|
+| [`MMKVStorageAdapter`](/docs/react-native/adapters/storage/mmkv) | `react-native-mmkv` | Sync | Performance (recommended) |
+| [`AsyncStorageAdapter`](/docs/react-native/adapters/storage/async-storage) | `@react-native-async-storage/async-storage` | Async | Compatibility |
+
+## Storage Interface
+
+All storage adapters implement:
+
+```typescript
+interface SupportedStorage {
+  preload(): void;
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  clear(): void;
+  keys(): string[];
+}
+```
+
+## What Gets Stored
+
+The SDK stores:
+
+| Data | Storage Key | Description |
+|------|-------------|-------------|
+| Identity State | `identity:IDENTIFY_STATE` | Session, user ID, token |
+| Version Status | `version:version_status` | Last known update status |
+| Device ID | `device:device_id` | Stable device UUID |
+
+## Namespacing
+
+Keys are prefixed with org/project IDs to prevent conflicts:
+
+```
+teardown:{org_id}:{project_id}:identity:IDENTIFY_STATE
+teardown:{org_id}:{project_id}:version:version_status
+teardown:{org_id}:{project_id}:device:device_id
+```
+
+## Custom Adapter
+
+Extend `StorageAdapter` for custom implementations:
+
+```typescript
+import { StorageAdapter, type SupportedStorage } from '@teardown/react-native';
+
+class CustomStorageAdapter extends StorageAdapter {
+  createStorage(storageKey: string): SupportedStorage {
+    return {
+      preload: () => {
+        // Load data into memory (called on init)
+      },
+      getItem: (key: string) => {
+        return myStorage.get(`${storageKey}:${key}`);
+      },
+      setItem: (key: string, value: string) => {
+        myStorage.set(`${storageKey}:${key}`, value);
+      },
+      removeItem: (key: string) => {
+        myStorage.delete(`${storageKey}:${key}`);
+      },
+      clear: () => {
+        // Clear all keys for this namespace
+      },
+      keys: () => {
+        // Return all keys for this namespace
+        return [];
+      },
+    };
+  }
+}
+```
+
+## Comparison
+
+| Feature | MMKV | AsyncStorage |
+|---------|------|--------------|
+| Speed | Faster (sync) | Slower (async) |
+| Encryption | Built-in | No |
+| Bundle Size | Smaller | Larger |
+| Debugging | Binary data | Plain text |
+| Platform Support | iOS, Android | iOS, Android, Web |

package/docs/adapters/storage/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Storage",
+	"pages": ["mmkv", "async-storage"]
+}

package/docs/adapters/storage/mmkv.mdx

@@ -0,0 +1,86 @@
+---
+title: MMKVStorageAdapter
+description: Fast, encrypted storage adapter using react-native-mmkv.
+---
+
+The `MMKVStorageAdapter` uses MMKV for high-performance, encrypted storage. **Recommended for most apps.**
+
+## Installation
+
+```bash
+npm install react-native-mmkv
+# or
+bun add react-native-mmkv
+```
+
+For iOS, run pod install:
+```bash
+cd ios && pod install
+```
+
+## 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 { MMKVStorageAdapter } from '@teardown/react-native/adapters/mmkv';
+```
+
+## Benefits
+
+- **Synchronous** - No async/await needed for reads/writes
+- **Encrypted** - Data encrypted by default
+- **Fast** - Memory-mapped for optimal performance
+- **Small** - Minimal bundle size impact
+- **Reliable** - Used by WeChat with 1B+ users
+
+## How It Works
+
+MMKV uses memory-mapped files for storage:
+
+1. Data is written to memory
+2. OS flushes to disk asynchronously
+3. Reads are instant (from memory)
+4. Crash-safe with journaling
+
+## Requirements
+
+- `react-native-mmkv` >= 2.0.0
+- React Native >= 0.71
+
+## Platform Notes
+
+### iOS
+- Requires `pod install`
+- Data stored in app's sandboxed Documents directory
+- Encrypted with iOS Keychain
+
+### Android
+- Works out of the box
+- Data stored in app's private directory
+- Encrypted with Android KeyStore
+
+## Expo Compatibility
+
+For Expo managed workflow, you need a development build:
+
+```bash
+npx expo install react-native-mmkv
+npx expo prebuild
+```
+
+Or use EAS Build for production.