@roeehrl/tinode-sdk 0.25.1-sqlite.1 → 0.25.1-sqlite.11

package/README.md

@@ -1,47 +1,364 @@
-# Javascript bindings for Tinode
+# @roeehrl/tinode-sdk
 
-This SDK implements [Tinode](https://github.com/tinode/chat) client-side protocol for the browser based applications. See it in action
-at https://web.tinode.co/ and https://sandbox.tinode.co/ ([full source](https://github.com/tinode/webapp)).
+> Fork of [tinode-js](https://github.com/tinode/tinode-js) with React Native support and SQLite persistence
 
-This is **not** a standalone project. It can only be used in conjunction with the [Tinode server](https://github.com/tinode/chat).
+This is a **modified fork** of the official Tinode JavaScript SDK, specifically adapted for **React Native** applications. It adds persistent storage using SQLite and platform-specific file handling.
 
-Regularly released NPM packages are at https://www.npmjs.com/package/tinode-sdk
+## What is Tinode?
 
-You may include the latest standalone minified SDK into your html file as
-```html
-<script crossorigin="anonymous"
-  src="https://cdn.jsdelivr.net/npm/tinode-sdk/umd/tinode.prod.js">
-</script>
+[Tinode](https://github.com/tinode/chat) is an open-source instant messaging backend server. This SDK implements the client-side protocol for connecting to Tinode servers from JavaScript/TypeScript applications.
+
+## Fork Overview
+
+| Aspect | Original (tinode-js) | This Fork (@roeehrl/tinode-sdk) |
+|--------|----------------------|----------------------------------|
+| Storage | IndexedDB (browser only) | **SQLite via expo-sqlite** (React Native) |
+| File Uploads | Blob API (browser only) | **File URI support** (React Native) |
+| Platform | Web browsers | **React Native (iOS/Android)** |
+| Persistence | Session-based (IndexedDB) | **Permanent** (SQLite database) |
+
+## Key Changes
+
+### 1. SQLite Storage (`storage-sqlite.js`)
+
+**Problem:** Original SDK used IndexedDB, which doesn't exist in React Native.
+
+**Solution:** Created `SQLiteStorage` class using `expo-sqlite` with the same API as the original `DB` class:
+
+```typescript
+import { Tinode, SQLiteStorage } from '@roeehrl/tinode-sdk';
+
+// Create storage instance
+const sqliteStorage = new SQLiteStorage('activon-chat.db');
+
+// Set as storage provider BEFORE creating Tinode instance
+Tinode.setStorageProvider(sqliteStorage);
+
+// Now Tinode will persist all data to SQLite
+const tinode = new Tinode({ host: '...', apiKey: '...' });
+```
+
+**Database Schema:**
+- `topics` - Chat topics metadata
+- `users` - User profiles
+- `subscriptions` - Topic subscriptions
+- `messages` - Chat messages
+- `dellog` - Deletion log (for sync)
+
+### 2. React Native Entry Point (`index.native.js`)
+
+Metro bundler automatically selects this file for native platforms:
+
+```javascript
+// package.json exports field
+"exports": {
+  ".": {
+    "react-native": "./src/index.native.js",  // ← Selected by Metro
+    "browser": "./umd/tinode.prod.js"
+  }
+}
+```
+
+### 3. File Upload Support (`large-file.native.js`)
+
+React Native doesn't have the Blob API. This fork provides `LargeFileHelperNative` that accepts **file URIs**:
+
+```typescript
+const { uri } = await DocumentPicker.getDocumentAsync({});
+tinode.getLargeFileHelper().uploadUri(
+  uri,
+  'photo.jpg',
+  'image/jpeg',
+  size,
+  null,
+  (progress) => console.log(progress),
+  (success) => console.log('Uploaded!'),
+  (error) => console.error(error)
+);
+```
+
+---
+
+## Polyfill Requirements
+
+The SDK requires several JavaScript polyfills because **Hermes** (React Native's JavaScript engine) doesn't provide all standard Web APIs.
+
+### Required Polyfills
+
+| Polyfill | Purpose | Why Needed |
+|----------|---------|------------|
+| `text-encoding-polyfill` | `TextEncoder` / `TextDecoder` | Hermes doesn't have these APIs |
+| `core-js/stable/structured-clone` | `structuredClone()` | Hermes doesn't have this |
+| `unicode-segmenter` | `Intl.Segmenter` | For text segmentation in Drafty parser |
+
+### Installation
+
+```bash
+yarn add text-encoding-polyfill core-js unicode-segmenter
+```
+
+---
+
+## Metro Configuration
+
+**Critical:** Metro must have `package exports` enabled to properly resolve `.native.ts` files:
+
+```javascript
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config');
+
+const config = getDefaultConfig(__dirname);
+
+// REQUIRED: Enable package exports for platform-specific module resolution
+config.resolver.unstable_enablePackageExports = true;
+
+module.exports = config;
+```
+
+**Without this**, Metro will ignore the `exports` field in `package.json` and use the wrong entry point.
+
+---
+
+## Setup Guide
+
+### Step 1: Install Dependencies
+
+```bash
+# Tinode SDK fork
+yarn add @roeehrl/tinode-sdk@^0.25.1-sqlite.8
+
+# Required peer dependency
+yarn add expo-sqlite
+
+# Polyfills
+yarn add text-encoding-polyfill core-js unicode-segmenter
 ```
-or while developing as
-```html
-<script crossorigin="anonymous"
-  src="https://cdn.jsdelivr.net/npm/tinode-sdk/umd/tinode.dev.js">
-</script>
+
+### Step 2: Import Polyfills First
+
+**Before** any Tinode imports, import polyfills in your app's entry point:
+
+```typescript
+// App.tsx or index.tsx - TOP OF FILE
+import 'text-encoding-polyfill';
+import 'core-js/stable/structured-clone';
+import 'unicode-segmenter/intl-polyfill';
+
+// Now you can import Tinode
+import { Tinode, SQLiteStorage } from '@roeehrl/tinode-sdk';
+```
+
+### Step 3: Configure SQLite Storage
+
+```typescript
+import { Tinode, SQLiteStorage } from '@roeehrl/tinode-sdk';
+
+// Create SQLite storage instance
+const sqliteStorage = new SQLiteStorage('activon-chat.db');
+
+// Initialize database
+await sqliteStorage.initDatabase();
+
+// Set as storage provider
+Tinode.setStorageProvider(sqliteStorage);
 ```
 
-## Getting support
+### Step 4: Create Tinode Instance
 
-* Read [client-side](http://tinode.github.io/js-api/) and [server-side](https://github.com/tinode/chat/blob/master/docs/API.md) API documentation.
-* For support, general questions, discussions post to [https://groups.google.com/d/forum/tinode](https://groups.google.com/d/forum/tinode).
-* For bugs and feature requests [open an issue](https://github.com/tinode/tinode-js/issues/new).
-* Use https://tinode.co/contact for commercial inquiries.
+```typescript
+const tinode = new Tinode({
+  host: 'your-tinode-server.com',
+  apiKey: 'your-api-key',
+  secure: true // use wss:// for secure WebSocket
+});
+```
 
-## Helping out
+---
 
-* If you appreciate our work, please help spread the word! Sharing on Reddit, HN, and other communities helps more than you think.
-* Consider buying paid support: https://tinode.co/support.html
-* If you are a software developer, send us your pull requests with bug fixes and new features.
-* If you use the SDK and discover bugs or missing features, let us know by filing bug reports and feature requests. Vote for existing [feature requests](https://github.com/tinode/chat/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A%22feature+request%22) you find most valuable.
+## EAS Build Configuration
 
-## Node JS compatibility
+For EAS (Expo Application Services) builds, ensure `expo-sqlite` is properly configured:
 
-This SDK is intended to be used in a browser. To use `tinode-sdk` in Node JS environment (such as on a server), you have to polyfill network providers, for example with [ws](https://www.npmjs.com/package/ws) and [xmlhttprequest](https://www.npmjs.com/package/xmlhttprequest) or [xhr](https://www.npmjs.com/package/xhr), as well as `indexedDB` with something like [fake-indexeddb](https://www.npmjs.com/package/fake-indexeddb):
+### app.config.js
 
-```js
-  Tinode.setNetworkProviders(require('ws'), require('xmlhttprequest'));
-  Tinode.setDatabaseProvider(require('fake-indexeddb'));
-  this.tinode = new Tinode(...);
+```javascript
+export default {
+  expo: {
+    plugins: [
+      ['expo-sqlite', {
+        // Optional: Enable database restoration on app launch
+        enableRestore: true,
+      }],
+    ],
+  },
+};
 ```
 
-`URL.createObjectURL()` and related methods were added in Node v16.7.0. The SDK is unlikely to work correctly with earlier versions of Node.
+### eas.json Configuration
+
+```json
+{
+  "build": {
+    "ios": {
+      "bundleIdentifier": "com.yourapp"
+    },
+    "android": {
+      "bundleIdentifier": "com.yourapp"
+    }
+  }
+}
+```
+
+---
+
+## Limitations & Known Issues
+
+### 1. Database File Location
+
+- **iOS:** `NSDocumentDirectory` (app's Documents folder)
+- **Android:** App's internal storage
+- Database file name: `activon-chat.db` (configurable)
+
+### 2. Database Recovery
+
+The SQLite storage includes automatic recovery for stale database handles after app lifecycle events. This handles cases where:
+- App goes to background and comes back
+- Device is locked/unlocked
+- App is suspended and resumed
+
+### 3. Hermes Limitations
+
+These JavaScript APIs are **not available** in Hermes:
+- `Blob` → Use file URIs instead
+- `URL.createObjectURL()` → Not supported
+- IndexedDB → Replaced by SQLite
+
+### 4. Thread Safety
+
+expo-sqlite is **not thread-safe**. All database operations must run on the JavaScript thread.
+
+---
+
+## Migration from Original SDK
+
+If migrating from the original `tinode-js`:
+
+### Before (Original)
+```typescript
+import { Tinode } from 'tinode-sdk';
+
+// Uses IndexedDB (doesn't work in React Native)
+const tinode = new Tinode({ host: '...', apiKey: '...' });
+```
+
+### After (This Fork)
+```typescript
+import 'text-encoding-polyfill';
+import 'core-js/stable/structured-clone';
+import 'unicode-segmenter/intl-polyfill';
+import { Tinode, SQLiteStorage } from '@roeehrl/tinode-sdk';
+
+// Setup SQLite storage
+const storage = new SQLiteStorage('chat.db');
+await storage.initDatabase();
+Tinode.setStorageProvider(storage);
+
+// Create Tinode instance
+const tinode = new Tinode({ host: '...', apiKey: '...' });
+```
+
+---
+
+## Platform-Specific Behavior
+
+| Feature | iOS | Android | Web |
+|---------|-----|---------|-----|
+| SQLite Storage | ✅ expo-sqlite | ✅ expo-sqlite | ❌ Use IndexedDB |
+| File Uploads | ✅ File URIs | ✅ File URIs | ✅ Blob API |
+| WebSocket | ✅ WSS supported | ✅ WSS supported | ✅ WS supported |
+| Polyfills Required | ✅ Yes | ✅ Yes | ❌ No |
+
+---
+
+## API Reference
+
+### SQLiteStorage
+
+```typescript
+class SQLiteStorage {
+  constructor(dbName: string, onError?: Function, logger?: Function)
+
+  async initDatabase(): Promise<void>
+  async deleteDatabase(): Promise<boolean>
+  isReady(): boolean
+
+  // Topics
+  async updTopic(topic: Object): Promise<void>
+  async remTopic(name: string): Promise<void>
+  async mapTopics(callback: Function, context: Object): Promise<Array>
+
+  // Users
+  async updUser(uid: string, pub: Object): Promise<void>
+  async remUser(uid: string): Promise<void>
+  async mapUsers(callback: Function, context: Object): Promise<Array>
+
+  // Messages
+  async addMessage(msg: Object): Promise<void>
+  async remMessages(topic: string, from?: number, to?: number): Promise<void>
+  async readMessages(topic: string, query: Object, callback: Function, context: Object): Promise<Array>
+}
+```
+
+### Tinode.setStorageProvider()
+
+```typescript
+static setStorageProvider(storage: SQLiteStorage): void
+```
+
+Sets the storage provider for all Tinode instances. Must be called **before** creating any Tinode instances.
+
+---
+
+## Troubleshooting
+
+### "Cannot find module 'expo-sqlite'"
+
+```bash
+yarn add expo-sqlite
+npx expo prebuild --clean
+```
+
+### "TextEncoder is not defined"
+
+Make sure polyfills are imported **before** any Tinode imports:
+
+```typescript
+// WRONG
+import { Tinode } from '@roeehrl/tinode-sdk';
+import 'text-encoding-polyfill';
+
+// RIGHT
+import 'text-encoding-polyfill';
+import { Tinode } from '@roeehrl/tinode-sdk';
+```
+
+### "setStorageProvider is not a function"
+
+Make sure you're using the React Native entry point. Check that Metro is using `index.native.js`:
+
+```javascript
+// In metro.config.js
+config.resolver.unstable_enablePackageExports = true; // ← MUST be true
+```
+
+---
+
+## License
+
+Apache-2.0 (Same as original Tinode SDK)
+
+## Original Project
+
+- [Tinode Server](https://github.com/tinode/chat)
+- [Original SDK](https://github.com/tinode/tinode-js)
+- [Documentation](http://tinode.github.io/js-api/)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@roeehrl/tinode-sdk",
   "description": "Tinode SDK fork with Storage interface for SQLite persistence in React Native",
-  "version": "0.25.1-sqlite.1",
+  "version": "0.25.1-sqlite.11",
   "types": "./types/index.d.ts",
   "scripts": {
     "format": "js-beautify -r src/*.js",
@@ -13,7 +13,9 @@
     "vers": "echo \"export const PACKAGE_VERSION = \\\"`node -p -e \"require('./package.json').version\"`\\\";\" > version.js",
     "test": "jest"
   },
-  "browserslist": ["defaults"],
+  "browserslist": [
+    "defaults"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/roeehrl/tinode-js.git"
@@ -24,7 +26,8 @@
     "umd/tinode.prod.js",
     "umd/tinode.prod.js.map",
     "types/index.d.ts",
-    "src/"
+    "src/",
+    "version.js"
   ],
   "keywords": [
     "instant messenger",
@@ -44,6 +47,7 @@
   "react-native": "./src/index.native.js",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "react-native": "./src/index.native.js",
       "browser": "./umd/tinode.prod.js",
       "import": "./src/index.js",

package/src/connection.js

@@ -354,7 +354,11 @@ export default class Connection {
 
     this.reconnect = force => {
       this.#boffStop();
-      this.connect(null, force);
+      // Catch the promise to prevent unhandled rejection
+      // Errors are handled via onDisconnect callback instead
+      this.connect(null, force).catch(_ => {
+        Connection.#log('LP reconnect promise rejected, error handled via onDisconnect callback');
+      });
     };
 
     this.disconnect = _ => {
@@ -463,7 +467,11 @@ export default class Connection {
 
     this.reconnect = force => {
       this.#boffStop();
-      this.connect(null, force);
+      // Catch the promise to prevent unhandled rejection
+      // Errors are handled via onDisconnect callback instead
+      this.connect(null, force).catch(_ => {
+        Connection.#log('WS reconnect promise rejected, error handled via onDisconnect callback');
+      });
     };
 
     this.disconnect = _ => {
@@ -481,6 +489,20 @@ export default class Connection {
       if (this.#socket && (this.#socket.readyState == this.#socket.OPEN)) {
         this.#socket.send(msg);
       } else {
+        // Socket is not connected - trigger disconnect callback if not already done
+        // This handles the case where the server dies but onclose hasn't fired yet
+        if (this.onDisconnect) {
+          // Use setTimeout to avoid blocking the throw
+          setTimeout(() => {
+            if (this.onDisconnect) {
+              this.onDisconnect(new CommError(NETWORK_ERROR_TEXT, NETWORK_ERROR), NETWORK_ERROR);
+            }
+          }, 0);
+        }
+        // Clean up the socket reference if it exists but isn't connected
+        if (this.#socket) {
+          this.#socket = null;
+        }
         throw new Error("Websocket is not connected");
       }
     };

package/src/db.js

@@ -73,16 +73,10 @@ export default class DB {
    * @returns {Promise} promise to be resolved/rejected when the DB is initialized.
    */
   initDatabase() {
-    console.log('[DB] initDatabase CALLED, shouldDelegate:', this.#shouldDelegate(), 'delegateStorage:', !!this.#delegateStorage);
     // Delegate to custom storage if set
     if (this.#shouldDelegate()) {
-      console.log('[DB] initDatabase DELEGATING to SQLiteStorage');
-      return this.#delegateStorage.initDatabase().then(result => {
-        console.log('[DB] initDatabase: SQLiteStorage initialized successfully');
-        return result;
-      });
+      return this.#delegateStorage.initDatabase();
     }
-    console.log('[DB] initDatabase using IndexedDB');
 
     return new Promise((resolve, reject) => {
       // Open the database and initialize callbacks.
@@ -220,7 +214,13 @@ export default class DB {
    * @returns {Promise} promise resolved/rejected on operation completion.
    */
   updTopic(topic) {
-    console.log('[DB] updTopic CALLED:', topic?.name, 'shouldDelegate:', this.#shouldDelegate());
+    // Skip topics that haven't been confirmed by the server yet.
+    // The _new flag is true for topics created locally but not yet subscribed.
+    // Only persist after subscribe succeeds and server assigns the real topic name.
+    if (topic?._new) {
+      return Promise.resolve();
+    }
+
     // Delegate to custom storage if set
     if (this.#shouldDelegate()) {
       return this.#delegateStorage.updTopic(topic);
@@ -325,16 +325,10 @@ export default class DB {
    * @return {Promise} promise resolved/rejected on operation completion.
    */
   mapTopics(callback, context) {
-    console.log('[DB] mapTopics CALLED, shouldDelegate:', this.#shouldDelegate());
     // Delegate to custom storage if set
     if (this.#shouldDelegate()) {
-      console.log('[DB] mapTopics DELEGATING to SQLiteStorage');
-      return this.#delegateStorage.mapTopics(callback, context).then(result => {
-        console.log('[DB] mapTopics: SQLiteStorage returned', result ? result.length : 0, 'topics');
-        return result;
-      });
+      return this.#delegateStorage.mapTopics(callback, context);
     }
-    console.log('[DB] mapTopics using IndexedDB');
     return this.#mapObjects('topic', callback, context);
   }
 
@@ -663,13 +657,10 @@ export default class DB {
    * @return {Promise} promise resolved/rejected on operation completion.
    */
   readMessages(topicName, query, callback, context) {
-    console.log('[DB] readMessages CALLED:', topicName, 'shouldDelegate:', this.#shouldDelegate(), 'delegateStorage:', !!this.#delegateStorage);
     // Delegate to custom storage if set
     if (this.#shouldDelegate()) {
-      console.log('[DB] readMessages DELEGATING to SQLiteStorage');
       return this.#delegateStorage.readMessages(topicName, query, callback, context);
     }
-    console.log('[DB] readMessages NOT delegating, using IndexedDB');
 
     query = query || {};
 

package/src/index.native.js

@@ -4,7 +4,9 @@
  * This is the entry point for React Native (iOS/Android) environments.
  * Metro bundler automatically picks this file for native platforms.
  *
- * Exports SQLiteStorage for persistent storage using expo-sqlite.
+ * Exports:
+ * - SQLiteStorage for persistent storage using expo-sqlite
+ * - LargeFileHelperNative for file uploads using file URIs
  *
  * @module tinode-sdk
  * @copyright 2015-2025 Tinode LLC, Activon
@@ -33,3 +35,9 @@ export {
   default as SQLiteStorage
 }
 from './storage-sqlite.js';
+
+// Export LargeFileHelperNative for React Native file uploads
+export {
+  default as LargeFileHelperNative
+}
+from './large-file.native.js';