turbodesk-livechat-react-native 0.1.0-alpha.0

package/docs/backend-contract.md

@@ -0,0 +1,392 @@
+# Backend Contract
+
+This document describes every backend endpoint and WebSocket event consumed by the
+`@turbodev/livechat-react-native` SDK. It is extracted from the web widget
+(`turbodev-livchat-widget`) and applies 1-to-1 to the mobile SDK because both share
+the same backend.
+
+---
+
+## Base URL
+
+All REST calls are made to `apiBaseUrl` (supplied by the client at provider setup).
+Example: `https://api.example.com`
+
+WebSocket: the SDK converts the scheme automatically — `http` → `ws`, `https` → `wss`.
+
+---
+
+## Authentication
+
+### Guest mode (no token)
+- A stable random `userId` is generated and persisted in `AsyncStorage` under the key
+  `lcw_uid_{widgetId}`.
+- Every request includes `?widgetId=…&userId=…` as query params.
+
+### Authenticated mode (token)
+- Pass `userToken` to the provider or call `setToken(token)` at runtime.
+- Every request adds `Authorization: Bearer {userToken}` header.
+- Query params: `?widgetId=…&userToken=…` (and optionally `userId=…` if both are set).
+
+### Visitor profile params (optional extra query params)
+- `name`, `email`, `phone` — sent alongside `widgetId`/`userId`/`userToken` when supplied.
+
+### 401 handling
+1. SDK calls the `authCallback` prop to get a fresh token.
+2. The original request is retried once with the new token.
+3. If `authCallback` is not set, the error propagates to the hook caller.
+
+### 403 handling
+- Request fails immediately; no redirect (unlike the web widget which redirects to `/login`).
+
+---
+
+## REST Endpoints
+
+### 1. Widget Config
+```
+GET {apiBaseUrl}/api/v1/public/livechat/:widgetId/config
+```
+No auth header required. Public endpoint.
+
+**Response** (`response.data`):
+```json
+{
+  "widgetId": "abc123",
+  "widgetName": "Turbodesk Support",
+  "workspaceId": "ws_xyz",
+  "channelId": "ch_xyz",
+  "widgetSettings": {
+    "title": "Chat with us",
+    "description": "We reply in minutes.",
+    "greetings": "Hi! How can we help?",
+    "theme": "light",
+    "brandColor": "#6366f1",
+    "brandLogoUrl": "https://...",
+    "afterHoursNote": "We are offline now.",
+    "replyTime": "a few minutes",
+    "pushNotificationsEnabled": false,
+    "requireIdentitySignIn": false,
+    "useBrandThemingForChat": false
+  }
+}
+```
+
+---
+
+### 2. Total Unread Count
+```
+GET {apiBaseUrl}/api/v1/livechat/unread
+Query: widgetId, userId | userToken, [name, email, phone]
+Auth: Bearer token (if token mode)
+```
+
+**Response**:
+```json
+{ "data": { "totalUnread": 3 } }
+```
+
+---
+
+### 3. List Conversations
+```
+GET {apiBaseUrl}/api/v1/livechat/conversations
+Query: widgetId, userId | userToken, page (1-based), limit (default 20)
+Auth: Bearer token (if token mode)
+```
+
+**Response**:
+```json
+{
+  "data": {
+    "conversations": [
+      {
+        "_id": "conv_001",
+        "status": "open",
+        "latestMessageAt": "2025-01-15T10:30:00Z",
+        "latestMessageId": "msg_999",
+        "assigneeType": "agent",
+        "assigneeId": "agent_42",
+        "livechat": { "visitorUnreadCount": 2 },
+        "hasUnreadMessages": true,
+        "userUnreadCount": 2
+      }
+    ],
+    "pagination": { "hasNextPage": true, "nextPage": 2 }
+  }
+}
+```
+
+---
+
+### 4. Get Conversation
+```
+GET {apiBaseUrl}/api/v1/livechat/conversations/:conversationId
+Query: widgetId, userId | userToken
+Auth: Bearer token (if token mode)
+```
+
+**Response**:
+```json
+{
+  "data": {
+    "conversation": {
+      "_id": "conv_001",
+      "status": "open",
+      "assigneeType": "agent",
+      "assigneeId": "agent_42",
+      "userId": "user_abc",
+      "messageCount": 12
+    }
+  }
+}
+```
+
+---
+
+### 5. Get Messages
+```
+GET {apiBaseUrl}/api/v1/livechat/conversations/:conversationId/messages
+Query: widgetId, userId | userToken, limit (default 30), nextCursor (for pagination)
+Auth: Bearer token (if token mode)
+```
+
+**Response**:
+```json
+{
+  "data": {
+    "messages": [
+      {
+        "_id": "msg_100",
+        "senderType": "contact",
+        "channelType": "livechat",
+        "localMessageId": "lc-1700000000000",
+        "createdAt": "2025-01-15T10:28:00Z",
+        "livechat": {
+          "type": "text",
+          "text": { "body": "Hello!" },
+          "status": "delivered",
+          "timestamp": "2025-01-15T10:28:00Z"
+        }
+      },
+      {
+        "_id": "msg_101",
+        "senderType": "agent",
+        "channelType": "livechat",
+        "createdAt": "2025-01-15T10:29:00Z",
+        "livechat": {
+          "type": "text",
+          "text": { "body": "Hi! How can I help?" },
+          "status": "delivered"
+        }
+      }
+    ],
+    "pagination": { "hasNextPage": true, "nextCursor": "cursor_xyz" }
+  }
+}
+```
+
+---
+
+### 6. Send Message
+```
+POST {apiBaseUrl}/api/v1/livechat/messages
+Query: widgetId, userId | userToken
+Auth: Bearer token (if token mode)
+Content-Type: application/json
+```
+
+**Request body — text message**:
+```json
+{
+  "localMessageId": "lc-1700000001234",
+  "conversationId": "conv_001",
+  "message": {
+    "type": "text",
+    "text": { "body": "Hello from mobile!" }
+  }
+}
+```
+If `conversationId` is omitted, the server creates a new conversation and returns its id.
+
+**Request body — file/image**:
+```json
+{
+  "localMessageId": "lc-1700000001235",
+  "conversationId": "conv_001",
+  "fileId": "file_abc",
+  "fileUrl": "https://cdn.example.com/file.jpg",
+  "fileName": "photo.jpg",
+  "fileExtension": "jpg",
+  "message": {
+    "type": "image",
+    "image": { "link": "https://cdn.example.com/file.jpg" }
+  }
+}
+```
+
+**Response**:
+```json
+{ "data": { "conversationId": "conv_001" } }
+```
+
+---
+
+### 7. Mark Conversation Read
+```
+PUT {apiBaseUrl}/api/v1/livechat/conversations/:conversationId/read
+Query: widgetId, userId | userToken
+Auth: Bearer token (if token mode)
+Body: {}
+```
+
+**Response**: `200 OK` (body ignored)
+
+---
+
+### 8. Conversation Count
+```
+GET {apiBaseUrl}/api/v1/livechat/conversations/count
+Query: widgetId, userId | userToken, [extra filters]
+Auth: Bearer token (if token mode)
+```
+
+**Response**:
+```json
+{ "data": { "count": 5 } }
+```
+
+---
+
+### 9. File Presign (upload)
+```
+POST {apiBaseUrl}/api/v1/livechat/files/presign
+Query/Auth: same as other endpoints
+Content-Type: application/json
+Body: { "fileName": "photo.jpg", "fileType": "image/jpeg", "widgetId": "abc" }
+```
+
+**Response**:
+```json
+{
+  "data": {
+    "uploadUrl": "https://s3.example.com/presigned-put-url",
+    "fileId": "file_abc",
+    "fileUrl": "https://cdn.example.com/file.jpg",
+    "fields": {}
+  }
+}
+```
+
+---
+
+## WebSocket
+
+### Connection URL
+```
+{wsBase}/api/v1/ws/livechat?widgetId=…&userToken=…
+                             widgetId=…&userId=…    (guest mode)
+```
+`wsBase` = `apiBaseUrl` with scheme replaced (`http→ws`, `https→wss`).
+
+### Connection lifecycle
+- SDK connects as soon as `widgetId` is available.
+- Exponential backoff on disconnect: 1 s → 2 s → 4 s … max 30 s.
+- Reconnects on: app foreground (`AppState` active), network restore (`NetInfo`).
+- Connecting timeout: 20 s (then force-reconnect).
+- Idle safety reconnect: 30 min without any message.
+
+### Message envelope
+All WS messages are JSON with a top-level `type` field:
+```json
+{ "type": "new_livechat_message", "data": { ... } }
+```
+
+### Events
+
+#### `new_livechat_message`
+New message in any conversation the visitor is part of.
+```json
+{
+  "type": "new_livechat_message",
+  "data": {
+    "conversation": { "_id": "conv_001", "status": "open", "livechat": { "visitorUnreadCount": 1 } },
+    "message": {
+      "_id": "msg_102",
+      "senderType": "agent",
+      "channelType": "livechat",
+      "localMessageId": null,
+      "createdAt": "2025-01-15T10:35:00Z",
+      "livechat": { "type": "text", "text": { "body": "Reply from agent" }, "status": "delivered" }
+    }
+  }
+}
+```
+SDK action: append message to active conversation list; increment `totalUnread` (if sender is not `"contact"`).
+
+#### `new_log_message`
+System/log message (e.g. "Conversation assigned to Agent X").
+```json
+{
+  "type": "new_log_message",
+  "data": {
+    "conversation": { "_id": "conv_001" },
+    "message": { "_id": "log_01", "channelType": "log", "livechat": { "type": "log", "text": { "body": "Assigned to Agent" } } }
+  }
+}
+```
+SDK action: append to messages list.
+
+#### `visitor_conversation_messages_marked_as_read`
+Visitor opened the conversation; server confirms read.
+```json
+{
+  "type": "visitor_conversation_messages_marked_as_read",
+  "data": { "conversationId": "conv_001", "visitorUnreadCount": 0, "messageCount": 3 }
+}
+```
+SDK action: update `totalUnread` using `visitorUnreadCount` or decrement by `messageCount`.
+
+#### `conversation_intervened`
+A bot/agent started handling the conversation.
+```json
+{
+  "type": "conversation_intervened",
+  "data": {
+    "conversation": { "_id": "conv_001", "assigneeType": "agent", "assigneeId": "agent_42", "status": "open" }
+  }
+}
+```
+SDK action: patch conversation in list and detail view.
+
+#### `conversation_unassigned`
+Conversation unassigned (returned to queue).
+```json
+{ "type": "conversation_unassigned", "data": { "conversation": { "_id": "conv_001", "assigneeType": null, "assigneeId": null } } }
+```
+SDK action: patch conversation.
+
+#### `conversation_transferred`
+Conversation transferred to another agent/team.
+```json
+{ "type": "conversation_transferred", "data": { "conversation": { "_id": "conv_001", "assigneeType": "agent", "assigneeId": "agent_99" } } }
+```
+SDK action: patch conversation.
+
+#### `conversation_resolved`
+Conversation closed by agent.
+```json
+{ "type": "conversation_resolved", "data": { "conversation": { "_id": "conv_001", "status": "resolved" } } }
+```
+SDK action: patch conversation; disable composer in ConversationScreen.
+
+---
+
+## Response unwrapping
+
+Responses may come in multiple shapes depending on backend version:
+- `response.data.data.X` — double-wrapped
+- `response.data.X` — single-wrapped
+- `response.data` (array) — bare array
+
+The SDK defensively unwraps all of these.

package/docs/migration-notes.md

@@ -0,0 +1,32 @@
+# Migration Notes
+
+This file tracks API changes that require action when upgrading.
+
+---
+
+## v0.1.0-alpha → future versions
+
+### Planned API changes (not yet breaking)
+- `useSendMessage` may gain optimistic update support
+- `useMessages` may expose a `refetch` method
+- `LiveChatProvider.theme` will likely accept a full or partial `ThemeConfig`
+
+### Things that will NOT change (stable API surface)
+- `LiveChatProvider` prop names (widgetId, apiBaseUrl, userToken, authCallback)
+- All 4 hook names and their primary return values
+- WS event names (new_livechat_message, conversation_resolved, etc.)
+- REST endpoint paths (backend contract is shared with the web widget)
+
+---
+
+## Upgrading from web widget (`turbodev-livchat-widget`) to mobile SDK
+
+This package is a fresh React Native build. There is no direct upgrade path.
+
+| Web widget pattern | Mobile SDK equivalent |
+|---|---|
+| `window.LCWidget.init({ widgetId })` | `<LiveChatProvider widgetId="..." />` |
+| `useLivechatWs("event", cb)` | `wsClient.subscribe("event", cb)` (via `useLiveChat()` → `.wsClient`) |
+| `localStorage` fingerprint | `AsyncStorage` fingerprint (`src/core/identity.ts`) |
+| Tailwind classes | `StyleSheet` + `ThemeConfig` |
+| Panel router / hash history | Use your app navigator (React Navigation recommended) |

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "turbodesk-livechat-react-native",
+  "version": "0.1.0-alpha.0",
+  "description": "Headless Live Chat SDK for React Native - REST, WebSocket, hooks, and optional UI kit",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepack": "npm run clean && npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    },
+    "@react-native-community/netinfo": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    },
+    "react-native-image-picker": {
+      "optional": true
+    },
+    "react-native-document-picker": {
+      "optional": true
+    },
+    "react-native-linear-gradient": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.20",
+    "@types/react-native": "^0.73.0",
+    "react": "^18.3.1",
+    "react-native": "~0.76.9",
+    "typescript": "^5.6.3"
+  }
+}

package/src/api/conversation-api.ts

@@ -0,0 +1,71 @@
+import getApiClient, { type RequestOptions } from "../axios/axios";
+
+const apiClient = getApiClient();
+
+export const conversationApi = {
+  getConversationCount: async (params?: RequestOptions["params"]) => {
+    const response = await apiClient.get<any>(
+      `api/v1/livechat/conversations/count`,
+      params ? { params } : undefined
+    );
+    return response.data;
+  },
+
+  getTotalUnread: async (options?: RequestOptions) => {
+    const response = await apiClient.get<any>(
+      `api/v1/livechat/unread`,
+      options
+    );
+    return response.data;
+  },
+
+  getConversations: async (options?: RequestOptions) => {
+    const response = await apiClient.get<any>(
+      `api/v1/livechat/conversations`,
+      options
+    );
+    return response.data;
+  },
+
+  getConversation: async (conversationId: string, options?: RequestOptions) => {
+    const response = await apiClient.get<any>(
+      `api/v1/livechat/conversations/${conversationId}`,
+      options
+    );
+    return response.data;
+  },
+
+  /**
+   * Visitor message entrypoint (`POST /api/v1/livechat/messages`).
+   * If `conversationId` is absent in the body, the server creates a new conversation
+   * for the resolved contact.
+   */
+  sendVisitorMessage: async (data: any, options?: RequestOptions) => {
+    const response = await apiClient.post<any>(
+      `api/v1/livechat/messages`,
+      data,
+      options
+    );
+    return response.data;
+  },
+
+  getMessages: async (conversationId: string, options?: RequestOptions) => {
+    const response = await apiClient.get<any>(
+      `api/v1/livechat/conversations/${conversationId}/messages`,
+      options
+    );
+    return response.data;
+  },
+
+  markMessageAsRead: async (
+    conversationId: string,
+    options?: RequestOptions
+  ) => {
+    const response = await apiClient.put<any>(
+      `api/v1/livechat/conversations/${conversationId}/read`,
+      {},
+      options
+    );
+    return response.data;
+  },
+};

package/src/api/file-api.ts

@@ -0,0 +1,14 @@
+import getApiClient, { type RequestOptions } from "../axios/axios";
+
+const apiClient = getApiClient();
+
+export const fileApi = {
+  getFileUrl: async (params: any, options?: RequestOptions) => {
+    const response = await apiClient.post(
+      `/api/v1/livechat/files/presign`,
+      params,
+      options
+    );
+    return response.data;
+  },
+};

package/src/api/widget-api.ts

@@ -0,0 +1,12 @@
+import getApiClient from "../axios/axios";
+
+const apiClient = getApiClient();
+
+export const widgetApi = {
+  getWidget: async (widgetId: string) => {
+    const response = await apiClient.get<any>(
+      `api/v1/public/livechat/${widgetId}/config`
+    );
+    return response.data;
+  },
+};