@parlr/react-native 0.1.0

package/README.md

@@ -0,0 +1,918 @@
+<p align="center">
+  <img src="https://parlr.chat/logo.svg" alt="Parlr" width="64" height="64" />
+</p>
+
+<h1 align="center">@parlr/react-native</h1>
+
+<p align="center">
+  <strong>The official Parlr live chat SDK for React Native.</strong><br />
+  Add real-time customer messaging to your mobile app in under 5 minutes.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@parlr/react-native"><img src="https://img.shields.io/npm/v/@parlr/react-native.svg?style=flat-square&color=6366f1" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@parlr/react-native"><img src="https://img.shields.io/npm/dm/@parlr/react-native.svg?style=flat-square&color=6366f1" alt="npm downloads" /></a>
+  <a href="https://github.com/parlr/parlr/blob/main/parlr-react-native/LICENSE"><img src="https://img.shields.io/npm/l/@parlr/react-native.svg?style=flat-square" alt="license" /></a>
+  <a href="https://parlr.chat/docs/sdk/react-native"><img src="https://img.shields.io/badge/docs-parlr.chat-6366f1?style=flat-square" alt="docs" /></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#components">Components</a> &bull;
+  <a href="#hooks">Hooks</a> &bull;
+  <a href="#theming">Theming</a> &bull;
+  <a href="#api-reference">API Reference</a> &bull;
+  <a href="https://parlr.chat/docs/sdk/react-native">Full Docs</a>
+</p>
+
+---
+
+## Why Parlr?
+
+Parlr is a modern B2B live chat platform. This SDK gives your React Native app:
+
+- **Real-time messaging** via WebSocket with automatic reconnection
+- **Optimistic UI** &mdash; messages appear instantly, sync in the background
+- **Typing indicators**, read receipts, and delivery status
+- **Pre-built UI components** that match your app's theme
+- **Pre-chat forms** to collect visitor info before the first message
+- **CSAT surveys** after conversation resolution
+- **File attachments** (images, documents)
+- **Rich messages** (cards, carousels, quick replies)
+- **Offline queue** with automatic retry when connectivity returns
+- **Push notifications** (FCM / APNs)
+- **HMAC identity verification** for secure user identification
+- **Dark mode** with automatic system detection
+- **TypeScript-first** with complete type definitions
+- **Tiny footprint** &mdash; ~160 KB published, 1 runtime dependency
+
+---
+
+## Installation
+
+```bash
+npm install @parlr/react-native
+```
+
+```bash
+yarn add @parlr/react-native
+```
+
+### Peer dependencies
+
+```bash
+npm install react-native-reanimated
+```
+
+### Optional dependencies
+
+```bash
+# Recommended: secure session persistence
+npm install expo-secure-store
+
+# For file/image attachments
+npm install expo-image-picker expo-document-picker
+```
+
+> Without `expo-secure-store`, sessions are stored in memory only and won't survive app restarts.
+
+### Compatibility
+
+| Dependency | Minimum version |
+|---|---|
+| `react` | 18.0.0 |
+| `react-native` | 0.72.0 |
+| `react-native-reanimated` | 3.0.0 |
+| `expo-secure-store` | 13.0.0 *(optional)* |
+| `expo-image-picker` | 15.0.0 *(optional)* |
+| `expo-document-picker` | 12.0.0 *(optional)* |
+
+Works with **Expo** and **bare React Native** projects.
+
+---
+
+## Quick Start
+
+### 1. Wrap your app with the provider
+
+```tsx
+import { ParlrProvider } from '@parlr/react-native';
+
+export default function App() {
+  return (
+    <ParlrProvider workspaceId="your-workspace-id">
+      <Navigation />
+    </ParlrProvider>
+  );
+}
+```
+
+### 2. Drop in the chat screen
+
+```tsx
+import { ParlrChat } from '@parlr/react-native';
+
+function SupportScreen({ navigation }) {
+  return (
+    <ParlrChat
+      user={{ email: 'alice@acme.com', name: 'Alice' }}
+      onBack={() => navigation.goBack()}
+    />
+  );
+}
+```
+
+### 3. Show unread count anywhere
+
+```tsx
+import { useParlr } from '@parlr/react-native';
+
+function SupportButton() {
+  const { unreadCount } = useParlr();
+
+  return (
+    <TouchableOpacity onPress={() => navigation.navigate('Support')}>
+      <Text>Support</Text>
+      {unreadCount > 0 && <Badge count={unreadCount} />}
+    </TouchableOpacity>
+  );
+}
+```
+
+**That's it.** The SDK handles session management, WebSocket connections, message delivery, and UI rendering automatically.
+
+---
+
+## Components
+
+### `<ParlrProvider>`
+
+Root wrapper that initializes the SDK. Place it near the top of your component tree.
+
+```tsx
+<ParlrProvider
+  workspaceId="your-workspace-id"
+  locale="en"
+  debug={__DEV__}
+  theme={{ colors: { primary: '#E91E63' } }}
+  onError={(err) => Sentry.captureException(err)}
+>
+  <App />
+</ParlrProvider>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `workspaceId` | `string` | *required* | Your Parlr workspace ID |
+| `apiBaseUrl` | `string` | `https://api.parlr.chat/api/v1/widget` | REST API base URL |
+| `wsUrl` | `string` | `wss://ws.parlr.chat/ws` | WebSocket endpoint |
+| `locale` | `string` | `"fr"` | BCP-47 locale (`"fr"` or `"en"`) |
+| `debug` | `boolean` | `false` | Enable verbose console logging |
+| `theme` | `Partial<ParlrTheme>` | auto | Theme overrides (see [Theming](#theming)) |
+| `identityToken` | `string` | &mdash; | HMAC token for identity verification |
+| `onError` | `(error: ParlrError) => void` | &mdash; | Global error callback |
+
+---
+
+### `<ParlrChat>`
+
+Full-featured chat screen. Handles everything: session, WebSocket, messages, input, typing indicators, attachments, CSAT.
+
+```tsx
+<ParlrChat
+  user={{ email: 'alice@acme.com', name: 'Alice' }}
+  conversationId="conv_123"          // optional: resume existing conversation
+  onBack={() => navigation.goBack()}
+  headerTitle="Support"
+  showPreChatForm={true}
+  preChatFields={['name', 'email']}
+  showSatisfactionSurvey={true}
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `user` | `ParlrUser` | &mdash; | Identify the user on mount |
+| `conversationId` | `string` | &mdash; | Resume an existing conversation |
+| `onBack` | `() => void` | &mdash; | Back button handler (shows arrow if provided) |
+| `headerTitle` | `string` | `"Support"` | Header bar title |
+| `placeholder` | `string` | `"Write a message..."` | Input placeholder |
+| `accentColor` | `string` | `theme.colors.primary` | Accent color override |
+| `showHeader` | `boolean` | `true` | Show/hide header bar |
+| `showPreChatForm` | `boolean` | `false` | Collect user info before first message |
+| `preChatFields` | `Array<'name' \| 'email' \| 'phone'>` | `['name', 'email']` | Pre-chat form fields |
+| `showSatisfactionSurvey` | `boolean` | `true` | Show CSAT after conversation closes |
+| `onConversationClosed` | `() => void` | &mdash; | Callback when conversation is closed |
+
+**Built-in features:** online/offline status, three-dot menu (close/reopen), optimistic send, agent typing indicator, attachment picker with preview, pagination (load older messages), auto-scroll, closed conversation banner, CSAT survey.
+
+---
+
+### `<ParlrConversationList>`
+
+Displays a list of conversations with last message preview, unread badges, and status.
+
+```tsx
+<ParlrConversationList
+  onSelectConversation={(id) => navigation.navigate('Chat', { id })}
+  onNewConversation={() => navigation.navigate('Chat')}
+  statusFilter="open"
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onSelectConversation` | `(id: string) => void` | *required* | Tap on a conversation |
+| `onNewConversation` | `() => void` | &mdash; | "New conversation" button handler |
+| `headerTitle` | `string` | `"Conversations"` | Header title |
+| `statusFilter` | `'open' \| 'closed' \| 'pending'` | &mdash; | Filter by status |
+| `showHeader` | `boolean` | `true` | Show/hide header |
+| `accentColor` | `string` | `"#6366f1"` | Accent color |
+
+---
+
+### Lower-level components
+
+These are used internally by `ParlrChat` but are exported for custom UIs:
+
+| Component | Description |
+|---|---|
+| `<ChatBubble message={msg} />` | Single message bubble (agent left, contact right) |
+| `<TypingIndicator />` | Animated three-dot typing indicator |
+| `<EmptyState />` | Welcome screen when no messages exist |
+| `<PreChatForm onSubmit={fn} />` | Pre-chat information form |
+| `<SatisfactionSurvey onSubmit={fn} />` | CSAT 1-5 star survey |
+| `<AttachmentPicker onFilePicked={fn} />` | Photo/camera/file picker |
+| `<AttachmentPreview file={f} onSend={fn} />` | Preview before sending |
+| `<RichMessage content={rich} />` | Cards, carousels, quick replies |
+
+See the [API Reference](#api-reference) for full prop tables.
+
+---
+
+## Hooks
+
+### `useParlr()`
+
+Access SDK state from any component inside `<ParlrProvider>`.
+
+```tsx
+const {
+  isReady,              // SDK initialized
+  isConnected,          // WebSocket connected
+  session,              // Current JWT session
+  conversations,        // All conversations
+  unreadCount,          // Total unread messages
+  identify,             // Identify or update user
+  refreshConversations, // Force refresh
+  theme,                // Resolved theme
+} = useParlr();
+
+// Identify a user
+await identify({
+  email: 'alice@acme.com',
+  name: 'Alice Martin',
+  company: 'Acme Inc',
+  customAttributes: { plan: 'pro', mrr: 299 },
+});
+```
+
+---
+
+### `useChat(conversationId?)`
+
+Manage a single conversation with real-time updates.
+
+```tsx
+const {
+  messages,            // Messages (oldest first)
+  isLoading,           // Initial load in progress
+  hasError,            // Error occurred
+  conversation,        // Active conversation
+  agentTyping,         // Agent is typing (auto-clears after 5s)
+  sendMessage,         // Send a text message (optimistic)
+  retryMessage,        // Retry a failed message
+  notifyTyping,        // Send typing indicator (debounced 3s)
+  loadMore,            // Load older messages
+  hasMore,             // More pages available
+  closeConversation,   // Close the conversation
+  reopenConversation,  // Reopen a closed conversation
+} = useChat(conversationId);
+
+// Send a message (appears instantly, syncs in background)
+await sendMessage('Hello, I need help with my order');
+
+// Retry a failed message
+const failed = messages.find(m => m.status === 'failed');
+if (failed?.clientId) await retryMessage(failed.clientId);
+```
+
+**Automatic behaviors:**
+- Messages appear instantly with `sending` status, then update to `sent` on server confirmation
+- Duplicate messages from WebSocket are merged with optimistic messages via `clientId`
+- Failed messages can be retried up to 3 times with exponential backoff (1s, 2s, 4s)
+- If no `conversationId` is provided, a new conversation is created on first `sendMessage()`
+
+---
+
+## Theming
+
+The SDK automatically detects your system's dark/light mode. You can override any value:
+
+### Just your brand color (most common)
+
+```tsx
+<ParlrProvider
+  workspaceId="your-workspace-id"
+  theme={{
+    colors: {
+      primary: '#E91E63',
+      contactBubble: '#E91E63',
+    },
+  }}
+>
+```
+
+### Full custom theme
+
+```tsx
+<ParlrProvider
+  workspaceId="your-workspace-id"
+  theme={{
+    colors: {
+      primary: '#FF6B00',
+      primaryText: '#FFFFFF',
+      background: '#1A1A2E',
+      surface: '#16213E',
+      text: '#EAEAEA',
+      textSecondary: '#A0A0B0',
+      border: '#2A2A4A',
+      agentBubble: '#16213E',
+      agentText: '#EAEAEA',
+      contactBubble: '#FF6B00',
+      contactText: '#FFFFFF',
+    },
+    borderRadius: { bubble: 20, input: 16, button: 12, avatar: 24 },
+    spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
+    typography: { headerSize: 20, bodySize: 16, captionSize: 12 },
+  }}
+>
+```
+
+### Programmatic access
+
+```tsx
+import { useParlr, defaultLightTheme, defaultDarkTheme, mergeTheme } from '@parlr/react-native';
+
+// Access resolved theme in components
+const { theme } = useParlr();
+<View style={{ backgroundColor: theme.colors.background }} />
+
+// Build a theme from scratch
+const custom = mergeTheme(defaultDarkTheme, { colors: { primary: '#FF6B00' } });
+```
+
+<details>
+<summary><strong>Full ParlrTheme interface</strong></summary>
+
+```typescript
+interface ParlrTheme {
+  colors: {
+    primary: string;         // Accent color
+    primaryText: string;     // Text on primary
+    background: string;      // Screen background
+    surface: string;         // Card/input background
+    surfaceDark: string;     // Darker surface (avatars)
+    text: string;            // Primary text
+    textSecondary: string;   // Secondary text, timestamps
+    border: string;          // Borders, dividers
+    success: string;         // Online indicator
+    error: string;           // Error states
+    agentBubble: string;     // Agent bubble background
+    agentBubbleDark: string; // Reserved
+    agentText: string;       // Agent bubble text
+    agentTextDark: string;   // Reserved
+    contactBubble: string;   // Contact bubble background
+    contactText: string;     // Contact bubble text
+  };
+  borderRadius: {
+    bubble: number;   // Message bubbles (default: 16)
+    input: number;    // Text input (default: 12)
+    button: number;   // Buttons (default: 8)
+    avatar: number;   // Avatars (default: 20)
+  };
+  spacing: {
+    xs: number;  // 4
+    sm: number;  // 8
+    md: number;  // 16
+    lg: number;  // 24
+    xl: number;  // 32
+  };
+  typography: {
+    headerSize: number;   // 18
+    bodySize: number;     // 15
+    captionSize: number;  // 12
+  };
+}
+```
+
+</details>
+
+---
+
+## Error Handling
+
+The SDK exports a typed error hierarchy for precise error handling:
+
+```tsx
+import {
+  ParlrError,            // Base class
+  ParlrNetworkError,     // HTTP errors (has statusCode)
+  ParlrAuthError,        // Expired or invalid session
+  ParlrValidationError,  // Invalid data (has field)
+  ParlrConnectionError,  // WebSocket errors (has code, reason)
+} from '@parlr/react-native';
+
+<ParlrProvider
+  workspaceId="your-workspace-id"
+  onError={(error) => {
+    if (error instanceof ParlrAuthError) {
+      // Session expired — SDK auto-refreshes it
+    } else if (error instanceof ParlrNetworkError) {
+      console.warn(`HTTP ${error.statusCode}`);
+    } else if (error instanceof ParlrConnectionError) {
+      console.warn(`WebSocket closed: ${error.reason}`);
+    }
+    Sentry.captureException(error);
+  }}
+>
+```
+
+---
+
+## Offline Support
+
+Queue messages when the device is offline. They are automatically sent when connectivity returns.
+
+```tsx
+import {
+  queueMessage,
+  getQueuedMessages,
+  removeFromQueue,
+  flushQueue,
+} from '@parlr/react-native';
+
+// Queue a message
+queueMessage({ conversationId: 'conv_123', content: 'Hello', clientId: 'uuid', timestamp: Date.now() });
+
+// Retrieve and flush the queue
+const queued = await getQueuedMessages();
+await flushQueue(api);
+```
+
+Uses AsyncStorage when available, falls back to in-memory storage.
+
+---
+
+## Push Notifications
+
+Register device tokens for FCM (Android) or APNs (iOS) push notifications:
+
+```tsx
+import { registerPushToken, unregisterPushToken } from '@parlr/react-native';
+
+// After obtaining the device token from expo-notifications or react-native-push-notification
+await registerPushToken(api, deviceToken, 'ios');
+
+// On logout
+await unregisterPushToken(api, deviceToken);
+```
+
+---
+
+## Identity Verification (HMAC)
+
+For production apps, use HMAC verification to prevent contact impersonation. Generate the token server-side:
+
+```tsx
+<ParlrProvider
+  workspaceId="your-workspace-id"
+  identityToken={hmacTokenFromYourBackend}
+>
+```
+
+The token is sent as `X-Identity-Token` on every identification request.
+
+---
+
+## API Reference
+
+### Types
+
+<details>
+<summary><strong>ParlrUser</strong></summary>
+
+```typescript
+interface ParlrUser {
+  email?: string;
+  name?: string;
+  firstName?: string;
+  lastName?: string;
+  externalId?: string;
+  phone?: string;
+  company?: string;
+  customAttributes?: Record<string, unknown>;
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Session</strong></summary>
+
+```typescript
+interface Session {
+  token: string;        // JWT token
+  contactId: string;    // Contact ID
+  workspaceId: string;  // Workspace ID
+  expiresAt: string;    // ISO 8601 expiration
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Conversation</strong></summary>
+
+```typescript
+interface Conversation {
+  id: string;
+  status: 'open' | 'resolved' | 'pending' | 'closed';
+  subject: string | null;
+  lastMessageAt: string | null;
+  unreadCount: number;
+  assignee?: { id: string; name: string; avatarUrl?: string } | null;
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Message</strong></summary>
+
+```typescript
+interface Message {
+  id: string;
+  conversationId: string;
+  senderType: 'contact' | 'agent';
+  senderName?: string;
+  senderAvatarUrl?: string;
+  content: string;
+  createdAt: string;
+  clientId?: string;                    // For optimistic deduplication
+  status?: 'sending' | 'sent' | 'failed' | 'read';
+  attachments?: Attachment[];
+  contentType?: 'text' | 'image' | 'file' | 'rich';
+  metadata?: Record<string, unknown>;
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Attachment</strong></summary>
+
+```typescript
+interface Attachment {
+  id: string;
+  name: string;
+  url: string;
+  contentType: string;
+  size: number;
+}
+```
+
+</details>
+
+<details>
+<summary><strong>RichContent</strong></summary>
+
+```typescript
+interface RichContent {
+  type: 'card' | 'carousel' | 'quick_replies' | 'buttons';
+  card?: RichCard;
+  carousel?: { cards: RichCard[] };
+  quickReplies?: { text?: string; replies: Array<{ label: string; value: string }> };
+  buttons?: RichAction[];
+}
+
+interface RichCard {
+  title?: string;
+  description?: string;
+  imageUrl?: string;
+  actions?: RichAction[];
+}
+
+interface RichAction {
+  type: 'link' | 'postback' | 'reply';
+  label: string;
+  value: string;
+}
+```
+
+</details>
+
+<details>
+<summary><strong>WebSocket Events</strong></summary>
+
+```typescript
+interface WsEventMap {
+  auth_ok: { contactId: string };
+  auth_error: { code?: number; reason?: string; message?: string };
+  new_message: WsNewMessagePayload;
+  typing_start: { conversationId: string; senderType?: 'agent' | 'contact'; senderName?: string };
+  typing_stop: { conversationId: string; senderType?: 'agent' | 'contact'; senderName?: string };
+  message_seen: { conversationId: string; messageId: string; seenBy: string };
+  conversation_updated: { conversationId: string; status?: string; assignee?: object | null };
+  pong: {};
+  disconnected: { code?: number; reason?: string };
+  error: { code?: string; message?: string };
+}
+```
+
+**WebSocket behavior:**
+- Auto-reconnect with exponential backoff (1s &rarr; 30s max)
+- Keep-alive ping every 25s, timeout at 50s
+- Clean listener teardown on unmount
+
+</details>
+
+### All Exports
+
+```typescript
+// Components
+import {
+  ParlrProvider,
+  ParlrChat,
+  ParlrConversationList,
+  ChatBubble,
+  TypingIndicator,
+  EmptyState,
+  PreChatForm,
+  SatisfactionSurvey,
+  AttachmentPicker,
+  AttachmentPreview,
+  RichMessage,
+} from '@parlr/react-native';
+
+// Hooks
+import { useParlr, useChat } from '@parlr/react-native';
+
+// Errors
+import {
+  ParlrError,
+  ParlrNetworkError,
+  ParlrAuthError,
+  ParlrValidationError,
+  ParlrConnectionError,
+} from '@parlr/react-native';
+
+// Theme utilities
+import { defaultLightTheme, defaultDarkTheme, mergeTheme } from '@parlr/react-native';
+
+// Offline queue
+import { queueMessage, getQueuedMessages, removeFromQueue, flushQueue } from '@parlr/react-native';
+
+// Push notifications
+import { registerPushToken, unregisterPushToken } from '@parlr/react-native';
+```
+
+---
+
+## Examples
+
+### Minimal integration
+
+```tsx
+import { ParlrProvider, ParlrChat } from '@parlr/react-native';
+
+export default function App() {
+  return (
+    <ParlrProvider workspaceId="your-workspace-id">
+      <ParlrChat />
+    </ParlrProvider>
+  );
+}
+```
+
+### With React Navigation
+
+```tsx
+// App.tsx
+import { ParlrProvider } from '@parlr/react-native';
+import { NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+
+const Stack = createNativeStackNavigator();
+
+export default function App() {
+  return (
+    <ParlrProvider workspaceId="your-workspace-id" locale="en">
+      <NavigationContainer>
+        <Stack.Navigator>
+          <Stack.Screen name="Home" component={HomeScreen} />
+          <Stack.Screen
+            name="Support"
+            component={SupportScreen}
+            options={{ headerShown: false }}
+          />
+        </Stack.Navigator>
+      </NavigationContainer>
+    </ParlrProvider>
+  );
+}
+
+// HomeScreen.tsx
+import { useParlr } from '@parlr/react-native';
+
+function HomeScreen({ navigation }) {
+  const { unreadCount } = useParlr();
+
+  return (
+    <View>
+      <TouchableOpacity onPress={() => navigation.navigate('Support')}>
+        <Text>Contact Support {unreadCount > 0 ? `(${unreadCount})` : ''}</Text>
+      </TouchableOpacity>
+    </View>
+  );
+}
+
+// SupportScreen.tsx
+import { ParlrChat } from '@parlr/react-native';
+
+function SupportScreen({ navigation }) {
+  return (
+    <ParlrChat
+      user={{ email: 'alice@acme.com', name: 'Alice' }}
+      onBack={() => navigation.goBack()}
+      headerTitle="Help & Support"
+      showPreChatForm={true}
+    />
+  );
+}
+```
+
+### Conversation list + chat
+
+```tsx
+import { ParlrConversationList, ParlrChat } from '@parlr/react-native';
+
+// List screen
+function ConversationsScreen({ navigation }) {
+  return (
+    <ParlrConversationList
+      onSelectConversation={(id) => navigation.navigate('Chat', { conversationId: id })}
+      onNewConversation={() => navigation.navigate('Chat')}
+    />
+  );
+}
+
+// Chat screen
+function ChatScreen({ route, navigation }) {
+  return (
+    <ParlrChat
+      conversationId={route.params?.conversationId}
+      onBack={() => navigation.goBack()}
+    />
+  );
+}
+```
+
+### Custom chat UI with hooks
+
+```tsx
+import { useChat, ChatBubble, TypingIndicator } from '@parlr/react-native';
+import { FlatList, TextInput, TouchableOpacity, View, Text } from 'react-native';
+
+function CustomChat({ conversationId }) {
+  const [text, setText] = useState('');
+  const {
+    messages, agentTyping, sendMessage, notifyTyping, loadMore, hasMore,
+  } = useChat(conversationId);
+
+  const handleSend = async () => {
+    if (!text.trim()) return;
+    await sendMessage(text.trim());
+    setText('');
+  };
+
+  return (
+    <View style={{ flex: 1 }}>
+      <FlatList
+        data={messages}
+        inverted
+        keyExtractor={(m) => m.id}
+        renderItem={({ item }) => <ChatBubble message={item} />}
+        onEndReached={() => hasMore && loadMore()}
+      />
+      {agentTyping && <TypingIndicator />}
+      <View style={{ flexDirection: 'row', padding: 8 }}>
+        <TextInput
+          value={text}
+          onChangeText={(t) => { setText(t); notifyTyping(true); }}
+          style={{ flex: 1 }}
+          placeholder="Type a message..."
+        />
+        <TouchableOpacity onPress={handleSend}>
+          <Text>Send</Text>
+        </TouchableOpacity>
+      </View>
+    </View>
+  );
+}
+```
+
+---
+
+## Advanced Configuration
+
+### Self-hosted Parlr
+
+Point the SDK to your own Parlr instance:
+
+```tsx
+<ParlrProvider
+  workspaceId="your-workspace-id"
+  apiBaseUrl="https://your-api.example.com/api/v1/widget"
+  wsUrl="wss://your-ws.example.com/ws"
+>
+```
+
+### Debug mode
+
+```tsx
+<ParlrProvider workspaceId="your-workspace-id" debug={true}>
+```
+
+Logs WebSocket events, session lifecycle, API calls, and errors to the console.
+
+---
+
+## FAQ
+
+<details>
+<summary><strong>How do I get my workspace ID?</strong></summary>
+
+Sign up at [app.parlr.chat](https://app.parlr.chat), create a workspace, and find your workspace ID in **Settings > Channels > Mobile SDK**.
+
+</details>
+
+<details>
+<summary><strong>Does the SDK work with Expo?</strong></summary>
+
+Yes. The SDK works with both Expo managed and bare workflows. All optional dependencies (`expo-secure-store`, `expo-image-picker`, `expo-document-picker`) are Expo packages.
+
+</details>
+
+<details>
+<summary><strong>What happens when the device goes offline?</strong></summary>
+
+Messages are queued locally and automatically retried when connectivity returns. The WebSocket reconnects with exponential backoff.
+
+</details>
+
+<details>
+<summary><strong>Can I use the SDK without any UI components?</strong></summary>
+
+Yes. Use `useParlr()` and `useChat()` hooks to build a completely custom UI. The SDK handles all networking, state management, and real-time updates.
+
+</details>
+
+<details>
+<summary><strong>How does identity verification work?</strong></summary>
+
+Generate an HMAC token server-side using your workspace secret and the user's email. Pass it as `identityToken` to `ParlrProvider`. This prevents contact impersonation.
+
+</details>
+
+---
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](https://github.com/parlr/parlr/blob/main/CONTRIBUTING.md) for details.
+
+```bash
+git clone https://github.com/parlr/parlr.git
+cd parlr/parlr-react-native
+npm install
+npm run typecheck   # Type checking
+npm run test        # Run tests
+npm run build       # Build (CJS + ESM + d.ts)
+npm run lint        # Lint
+```
+
+---
+
+## License
+
+MIT &copy; [Parlr](https://parlr.chat)