@ion299/sdk-react-native 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+Все заметные изменения в пакете документируются в этом файле.
+Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.0.0/),
+проект следует [семантическому версионированию](https://semver.org/lang/ru/).
+
+## [Unreleased]
+
+## [0.1.0-beta.1]
+
+### Added
+- Первая бета-версия React Native SDK для Chat Platform.
+- `ChatSDK.init()` с авторизацией по токену.
+- Компонент `ChatScreen` и хук `useChat`.
+- Поддержка вложений, кнопок в сообщениях, CSI-опросов.
+- Нативные модули file-picker и downloader (Android/iOS).
+- Сборка пакета через `react-native-builder-bob` (commonjs + module + typescript).

package/ChatPlatformSdk.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ChatPlatformSdk"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://github.com/robotmia/chat-platform"
+  s.license      = "UNLICENSED"
+  s.author       = "Chat Platform"
+  s.platforms    = { :ios => "13.4" }
+  s.source       = { :git => "https://github.com/robotmia/chat-platform.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  s.swift_version = "5.0"
+  s.requires_arc = true
+
+  s.dependency "React-Core"
+end

package/README.md

@@ -0,0 +1,315 @@
+# @chat-platform/sdk-react-native
+
+React Native SDK для встройки чата в мобильное приложение.
+
+**Версия:** 0.1.0-beta.1
+**JS-требования:** React Native ≥ 0.72, React ≥ 18.2
+**Нативные минимумы:** iOS 13.4, Android API 24 (Android 7.0)
+
+Пикер файлов и скачивание вложений работают «из коробки» — никаких дополнительных
+нативных модулей (`expo-*`, `@react-native-documents/*` и т.п.) ставить **не нужно**.
+
+---
+
+## Установка
+
+```bash
+# npm
+npm install @chat-platform/sdk-react-native
+
+# yarn
+yarn add @chat-platform/sdk-react-native
+```
+
+После установки:
+
+**iOS**
+```bash
+cd ios && pod install
+```
+
+**Android** — пересборка через Android Studio или `./gradlew assembleDebug`.
+Никаких правок в `MainApplication.kt` / `AppDelegate.mm` не требуется — модуль
+подключается через autolinking (см. `react-native.config.js` в пакете).
+
+---
+
+## Быстрый старт
+
+### 1. Инициализация (один раз при старте приложения)
+
+```tsx
+// App.tsx
+import { ChatSDK } from '@chat-platform/sdk-react-native'
+
+ChatSDK.init({
+  token:  'ВАШ_ТОКЕН_ИЗ_ЧП',  // универсальный токен (содержит widget token + baseUrl)
+  locale: 'ru',                // 'ru' | 'en' (опционально)
+})
+```
+
+Токен из настроек виджета в ЧП — это base64-JSON вида `{"token":"...","baseUrl":"..."}`.
+SDK сам распакует его и подставит нужный `baseUrl`. Передавать `baseUrl` отдельно
+не нужно.
+
+### 2. Логин после авторизации пользователя
+
+```tsx
+await ChatSDK.login(
+  {
+    userId:  user.id,         // обязательно — id из вашей системы
+    name:    user.firstName,
+    surname: user.lastName,
+    email:   user.email,
+    phone:   user.phone,
+  },
+  {
+    platform:   'ios',        // 'ios' | 'android' | 'other'
+    appVersion: '1.0.0',
+    bundleId:   'com.yourapp',
+  },
+)
+```
+
+### 3. Открыть чат
+
+```tsx
+import { ChatScreen } from '@chat-platform/sdk-react-native'
+
+// В стеке навигации
+<Stack.Screen name="Chat" component={ChatScreen} />
+
+// или как компонент с onClose
+<ChatScreen onClose={() => navigation.goBack()} />
+```
+
+### 4. Логаут
+
+```tsx
+await ChatSDK.logout()
+```
+
+---
+
+## Что включено по умолчанию
+
+| Возможность                              | Android                                  | iOS                                  |
+|------------------------------------------|------------------------------------------|--------------------------------------|
+| Выбор файлов из системного пикера        | SAF `OpenDocument` (множественный выбор) | `UIDocumentPickerViewController`     |
+| Скачивание вложений в системные «Файлы»  | `MediaStore.Downloads` (API 29+)         | `UIActivityViewController` (share-sheet) |
+| Прогресс скачивания                      | Через `NativeEventEmitter`               | Через `NativeEventEmitter`           |
+| Notification «Загрузка завершена»        | Да, тап открывает файл                   | Native share-sheet после загрузки    |
+| Realtime (Laravel Reverb / Pusher)       | Да                                       | Да                                   |
+| Поддержка кнопок ботов в сообщениях      | Да                                       | Да                                   |
+| CSI-опрос после закрытия диалога         | Да                                       | Да                                   |
+| Галерея вложений (изображения + документы) | Да                                     | Да                                   |
+
+Никаких runtime-permissions для скачивания на Android 10+ запрашивать не нужно.
+
+---
+
+## Компонент `<ChatScreen />`
+
+| Prop                    | Тип                                          | Назначение                                              |
+|-------------------------|----------------------------------------------|---------------------------------------------------------|
+| `onClose`               | `() => void`                                 | Колбэк для кнопки «назад» в хедере                      |
+| `theme`                 | `Partial<ChatTheme>`                         | Переопределение цветов поверх темы из ЧП                |
+| `strings`               | `ChatStrings`                                | Кастомные тексты (см. ниже)                             |
+| `onPickFiles`           | `() => Promise<AttachmentInput[] \| null>`   | Escape-hatch: своя реализация пикера                    |
+| `onDownloadAttachment`  | `(a: GalleryAttachment) => Promise<void>`    | Escape-hatch: своя реализация скачивания                |
+
+`onPickFiles` и `onDownloadAttachment` нужны **только** если вы хотите перебить
+встроенное поведение (например, открывать кастомный пикер). Во всех остальных
+случаях оставляйте их `undefined` — SDK использует свои нативные модули.
+
+### Кастомные тексты
+
+```tsx
+<ChatScreen
+  strings={{
+    headerTitle:      'Поддержка',
+    emptyStateText:   'Опишите проблему — мы ответим в течение минуты',
+    inputPlaceholder: 'Ваше сообщение…',
+    errorRetry:       'Повторить',
+    galleryDownload:  'Сохранить',
+    surveyTitle:      'Оцените работу оператора',
+    surveySubmit:     'Отправить',
+    surveySkip:       'Пропустить',
+    surveyClose:      'Закрыть',
+    sendingText:      'Отправка…',
+  }}
+/>
+```
+
+Все поля опциональны — непереданные значения берутся из встроенных дефолтов на
+русском.
+
+### Тема
+
+```tsx
+<ChatScreen
+  theme={{
+    primaryColor:  '#7c3aed',
+    headerBg:      '#7c3aed',
+    outboundBg:    '#7c3aed',
+    background:    '#fafafa',
+  }}
+/>
+```
+
+Полный список полей — в `ChatTheme` (см. `src/theme.ts`).
+
+---
+
+## События
+
+После `ChatSDK.login()` SDK поднимает фоновую сессию (WebSocket + polling fallback)
+и держит её живой до `logout()`. Поэтому события ниже **работают независимо от того,
+открыт ли `<ChatScreen />`** — пока приложение в foreground, подписчик будет получать
+их даже при закрытом чате.
+
+```tsx
+const unsubState = ChatSDK.on('stateChange', (state) => {
+  // 'idle' | 'initializing' | 'ready' | 'authenticated' | 'error'
+})
+
+const unsubOperator = ChatSDK.on('operatorChanged', (p) => {
+  // p: { token, contactId, previousOperator, operator, occurredAt }
+})
+
+const unsubMessage = ChatSDK.on('newMessage', (p) => {
+  // p: { token, contactId, message, operator, occurredAt }
+  // Срабатывает только для сообщений от операторов (type === 'user').
+})
+
+const unsubMessagesUpdated = ChatSDK.on('messagesUpdated', (p) => {
+  // p: { messages, operator } — полный текущий список после любого refresh
+})
+
+const unsubConnected = ChatSDK.on('connectedChange', (online) => {
+  // true когда WS подключён, false при отвале (тогда работает polling)
+})
+
+const unsubError = ChatSDK.on('error', (err) => {
+  // ошибка инициализации/сессии
+})
+
+// Снятие подписки
+unsubState(); unsubOperator(); unsubMessage()
+unsubMessagesUpdated(); unsubConnected(); unsubError()
+```
+
+Подписка на `newMessage` подходит для собственных in-app уведомлений (тосты,
+бейджи в табах) — событие приходит даже если пользователь не открывал чат, пока
+приложение в foreground. Для push-уведомлений в background используйте webhook
+(см. ниже).
+
+### Поведение в фоне
+
+- При уходе в background polling приостанавливается (батарея).
+- WebSocket OS-зависим: некоторые системы дают ему ещё минуту-две, потом гасят.
+- При возврате в foreground SDK делает one-shot `refreshMessages` и при
+  необходимости поднимает сокет.
+
+---
+
+## Push-уведомления
+
+ЧП **не** шлёт FCM/APNs напрямую. Вместо этого ЧП отправляет webhook на ваш
+backend при новом сообщении от оператора. Ваш backend сам решает, кому и как
+доставить push.
+
+### Webhook payload
+
+```json
+{
+  "event":          "message.created",
+  "version":        1,
+  "token":          "widget_token",
+  "contactId":      "user_123",
+  "conversationId": 456,
+  "messageId":      789,
+  "senderType":     "user",
+  "preview":        "Здравствуйте!",
+  "hasAttachments": false,
+  "createdAt":      "2026-06-01T10:00:00Z"
+}
+```
+
+Подпись: заголовок `X-Chat-Platform-Signature: sha256=HMAC_SHA256(body, webhook_secret)`.
+
+### Открытие чата из тапа по push
+
+```tsx
+import { ChatSDK } from '@chat-platform/sdk-react-native'
+
+// В обработчике нотификации
+ChatSDK.handleNotification({
+  token:     data.cp_token,
+  contactId: data.cp_contact_id,
+})
+navigation.navigate('Chat')
+```
+
+Рекомендуемые data-ключи в payload FCM/APNs: `cp_token`, `cp_contact_id`.
+
+---
+
+## API
+
+### `ChatSDK.init(config)`
+
+| Поле     | Тип                | Обязательно |
+|----------|--------------------|-------------|
+| `token`  | `string`           | Да — универсальный токен из ЧП (base64-JSON с `token` + `baseUrl`) |
+| `baseUrl`| `string`           | Нет — указывается только при ручной разработке против локального инстанса ЧП |
+| `locale` | `'ru' \| 'en'`     | Нет         |
+
+### `ChatSDK.login(user, device?)`
+
+| Поле       | Тип       | Обязательно |
+|------------|-----------|-------------|
+| `userId`   | `string`  | Да          |
+| `name`     | `string`  | Нет         |
+| `surname`  | `string`  | Нет         |
+| `email`    | `string`  | Нет         |
+| `phone`    | `string`  | Нет         |
+
+`device` (опционально): `{ platform, appVersion, bundleId }`.
+
+### `ChatSDK.logout()`
+
+Завершает сессию, отключает realtime.
+
+### `ChatSDK.handleNotification(payload)`
+
+Помечает push как относящийся к нашему виджету (по `token`). Навигацию на
+`ChatScreen` запускает host-приложение.
+
+### `ChatSDK.getState() / isAuthenticated() / getUser()`
+
+Геттеры текущего состояния SDK.
+
+### `ChatSDK.on(event, handler)`
+
+Подписка на события — см. раздел «События» выше. Возвращает функцию отписки.
+
+---
+
+## Чеклист интеграции
+
+- [ ] Получить `widget_token` и `baseUrl` от ЧП
+- [ ] `npm install @chat-platform/sdk-react-native` + `pod install` для iOS
+- [ ] Пересобрать нативную часть (Xcode / Android Studio)
+- [ ] `ChatSDK.init(...)` в точке входа приложения
+- [ ] `ChatSDK.login(...)` после авторизации пользователя
+- [ ] `<ChatScreen />` в навигаторе
+- [ ] Webhook URL в настройках виджета в ЧП
+- [ ] FCM/APNs: данные `cp_token`, `cp_contact_id` в data payload
+- [ ] `ChatSDK.handleNotification(...)` в обработчике push на стороне приложения
+
+---
+
+## Лицензия
+
+UNLICENSED. Внутренний пакет — для использования только в рамках проектов ЧП.

package/android/build.gradle

@@ -0,0 +1,54 @@
+buildscript {
+    ext.getExtOrDefault = { name, defaultValue ->
+        rootProject.ext.has(name) ? rootProject.ext.get(name) : defaultValue
+    }
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:8.1.1"
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22"
+    }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+android {
+    namespace "com.chatplatform.sdk"
+    compileSdkVersion getExtOrDefault("compileSdkVersion", 34)
+
+    defaultConfig {
+        minSdkVersion getExtOrDefault("minSdkVersion", 24)
+        targetSdkVersion getExtOrDefault("targetSdkVersion", 34)
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+
+    sourceSets {
+        main {
+            manifest.srcFile "src/main/AndroidManifest.xml"
+            java.srcDirs = ["src/main/java"]
+            res.srcDirs = ["src/main/res"]
+        }
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "com.facebook.react:react-android"
+    implementation "androidx.core:core-ktx:1.13.1"
+    implementation "com.squareup.okhttp3:okhttp:4.12.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.chatsdk.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/chat_sdk_file_paths" />
+        </provider>
+    </application>
+</manifest>

package/android/src/main/java/com/chatplatform/sdk/ChatSdkDownloaderModule.kt

@@ -0,0 +1,240 @@
+package com.chatplatform.sdk
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.ContentValues
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.Build
+import android.os.Environment
+import android.provider.MediaStore
+import androidx.core.app.NotificationCompat
+import androidx.core.content.FileProvider
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import java.io.File
+import java.io.FileOutputStream
+import java.io.InputStream
+import java.util.UUID
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+
+class ChatSdkDownloaderModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String = NAME
+
+    private val executor = Executors.newCachedThreadPool()
+    private val client: OkHttpClient by lazy {
+        OkHttpClient.Builder()
+            .connectTimeout(30, TimeUnit.SECONDS)
+            .readTimeout(120, TimeUnit.SECONDS)
+            .build()
+    }
+
+    @ReactMethod
+    fun addListener(eventName: String) {
+        // RN требует наличия этих методов для NativeEventEmitter
+    }
+
+    @ReactMethod
+    fun removeListeners(count: Int) {
+        // RN требует наличия этих методов для NativeEventEmitter
+    }
+
+    @ReactMethod
+    fun download(request: ReadableMap, promise: Promise) {
+        val url = request.getString("url")
+        val filename = sanitize(request.getString("filename") ?: "file")
+        val mime = request.getString("mime") ?: "application/octet-stream"
+        if (url.isNullOrEmpty()) {
+            promise.reject("INVALID_URL", "URL не задан")
+            return
+        }
+        val headers: ReadableMap? = if (request.hasKey("headers")) request.getMap("headers") else null
+        val id = UUID.randomUUID().toString()
+
+        executor.execute {
+            try {
+                val builder = Request.Builder().url(url).get()
+                headers?.toHashMap()?.forEach { (k, v) ->
+                    if (v is String) builder.header(k, v)
+                }
+                val response = client.newCall(builder.build()).execute()
+                if (!response.isSuccessful) {
+                    response.close()
+                    promise.reject("HTTP_${response.code}", "Ошибка загрузки: HTTP ${response.code}")
+                    return@execute
+                }
+
+                val body = response.body
+                if (body == null) {
+                    response.close()
+                    promise.reject("EMPTY_BODY", "Пустой ответ сервера")
+                    return@execute
+                }
+
+                val total = body.contentLength()
+                val context = reactApplicationContext
+                val savedUri: Uri = body.byteStream().use { stream ->
+                    saveToDownloads(context, stream, filename, mime, total, id)
+                }
+                response.close()
+
+                postCompletionNotification(context, filename, mime, savedUri)
+
+                val result: WritableMap = Arguments.createMap()
+                result.putString("id", id)
+                result.putString("uri", savedUri.toString())
+                promise.resolve(result)
+            } catch (e: Throwable) {
+                promise.reject("DOWNLOAD_FAILED", e.message ?: "Не удалось скачать файл", e)
+            }
+        }
+    }
+
+    private fun saveToDownloads(
+        context: Context,
+        input: InputStream,
+        filename: String,
+        mime: String,
+        total: Long,
+        id: String,
+    ): Uri {
+        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            saveViaMediaStore(context, input, filename, mime, total, id)
+        } else {
+            saveToExternalFiles(context, input, filename, total, id)
+        }
+    }
+
+    private fun saveViaMediaStore(
+        context: Context,
+        input: InputStream,
+        filename: String,
+        mime: String,
+        total: Long,
+        id: String,
+    ): Uri {
+        val resolver = context.contentResolver
+        val collection = MediaStore.Downloads.getContentUri(MediaStore.VOLUME_EXTERNAL_PRIMARY)
+        val values = ContentValues().apply {
+            put(MediaStore.Downloads.DISPLAY_NAME, filename)
+            put(MediaStore.Downloads.MIME_TYPE, mime)
+            put(MediaStore.Downloads.RELATIVE_PATH, Environment.DIRECTORY_DOWNLOADS)
+            put(MediaStore.Downloads.IS_PENDING, 1)
+        }
+        val uri = resolver.insert(collection, values)
+            ?: throw IllegalStateException("Не удалось создать запись в MediaStore")
+
+        resolver.openOutputStream(uri).use { output ->
+            if (output == null) throw IllegalStateException("Не удалось открыть OutputStream")
+            copyWithProgress(input, output, total, id)
+        }
+
+        values.clear()
+        values.put(MediaStore.Downloads.IS_PENDING, 0)
+        resolver.update(uri, values, null, null)
+        return uri
+    }
+
+    private fun saveToExternalFiles(
+        context: Context,
+        input: InputStream,
+        filename: String,
+        total: Long,
+        id: String,
+    ): Uri {
+        val dir = context.getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS)
+            ?: File(context.filesDir, "downloads").apply { mkdirs() }
+        if (!dir.exists()) dir.mkdirs()
+        val target = File(dir, filename)
+        FileOutputStream(target).use { output -> copyWithProgress(input, output, total, id) }
+        val authority = "${context.packageName}.chatsdk.fileprovider"
+        return FileProvider.getUriForFile(context, authority, target)
+    }
+
+    private fun copyWithProgress(input: InputStream, output: java.io.OutputStream, total: Long, id: String) {
+        val buffer = ByteArray(64 * 1024)
+        var written = 0L
+        var lastEmit = 0L
+        while (true) {
+            val read = input.read(buffer)
+            if (read <= 0) break
+            output.write(buffer, 0, read)
+            written += read
+            val now = System.currentTimeMillis()
+            if (now - lastEmit >= 100) {
+                emitProgress(id, written, total)
+                lastEmit = now
+            }
+        }
+        output.flush()
+        emitProgress(id, written, if (total > 0) total else written)
+    }
+
+    private fun emitProgress(id: String, written: Long, total: Long) {
+        val map: WritableMap = Arguments.createMap()
+        map.putString("id", id)
+        map.putDouble("bytesWritten", written.toDouble())
+        map.putDouble("totalBytes", total.toDouble())
+        reactApplicationContext
+            .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+            .emit("ChatSdkDownloadProgress", map)
+    }
+
+    private fun postCompletionNotification(context: Context, filename: String, mime: String, uri: Uri) {
+        ensureChannel(context)
+        val openIntent = Intent(Intent.ACTION_VIEW).apply {
+            setDataAndType(uri, mime)
+            addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+        val pi = PendingIntent.getActivity(
+            context,
+            uri.hashCode(),
+            openIntent,
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+        )
+        val notification = NotificationCompat.Builder(context, CHANNEL_ID)
+            .setSmallIcon(android.R.drawable.stat_sys_download_done)
+            .setContentTitle(filename)
+            .setContentText("Загрузка завершена")
+            .setAutoCancel(true)
+            .setContentIntent(pi)
+            .build()
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        manager.notify(uri.hashCode(), notification)
+    }
+
+    private fun ensureChannel(context: Context) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        if (manager.getNotificationChannel(CHANNEL_ID) != null) return
+        val channel = NotificationChannel(
+            CHANNEL_ID,
+            "Загрузки",
+            NotificationManager.IMPORTANCE_LOW,
+        )
+        manager.createNotificationChannel(channel)
+    }
+
+    private fun sanitize(name: String): String {
+        val cleaned = name.replace(Regex("[/\\\\?%*:|\"<>]"), "_").trim()
+        return if (cleaned.isEmpty()) "file" else cleaned
+    }
+
+    companion object {
+        const val NAME = "ChatSdkDownloader"
+        private const val CHANNEL_ID = "chat_sdk_downloads"
+    }
+}