nativescript-matrix-sdk v0.1.1

NativeScript Matrix SDK

A NativeScript plugin that provides native Matrix client SDK integration for iOS and Android applications. This plugin wraps the official Matrix iOS SDK and Matrix Android SDK to provide a unified TypeScript API.

Features

Core Functionality

• Complete Matrix client implementation for NativeScript
• Cross-platform API with native performance
• End-to-end encryption with cross-signing support
• Transaction management for offline operation
• Advanced performance optimizations

Authentication & Security

• Multiple authentication methods:
  • Username/password login
  • Single Sign-On (SSO)
  • Registration support
• Device verification
• Key backup and recovery
• Secure credential storage

Messaging & Communication

• Real-time messaging with encryption
• File transfer with encryption support
• Typing indicators and read receipts
• User presence management
• Message pagination with optimized loading
• Reaction support
• Message editing and deletion

Room Management

• Room creation and configuration
• Member management
• Permission controls
• Room state tracking
• Room list pagination

Performance Features

• LRU caching with automatic eviction
• Batch operation handling
• Event optimization (buffering/debouncing)
• Memory management
• Pagination optimization
• Transaction retry handling

Installation

npm install nativescript-matrix-sdk --legacy-peer-deps

iOS Setup

Requires iOS 12.0 or later. Add to your Podfile:

pod 'MatrixSDK', '~> 0.28.1'

Android Setup

Requires Android API level 21 or later. Add to your build.gradle:

implementation 'org.matrix.android:matrix-android-sdk2:1.6.2'

Quick Start

Basic Usage

import { MatrixSDK } from 'nativescript-matrix-sdk';

// Get the Matrix client
const client = MatrixSDK.getClient();

// Login to a Matrix server
const loginResult = await client.login(
  'https://matrix.example.org',
  'username',
  'password',
  'My Device'
);

// Start listening for events
await client.startListening();

// Get available rooms
const rooms = await client.getChats();

// Send a message
await client.sendMessage(rooms[0].id, 'Hello from NativeScript!');

Encryption Example

// Enable encryption for a room
await client.enableEncryption(roomId);

// Verify a device
const verificationId = await client.startDeviceVerification(userId, deviceId);
await client.acceptDeviceVerification(verificationId);
await client.completeDeviceVerification(verificationId, confirmationCode);

// Backup keys
const recoveryKey = await client.createKeyBackup();

File Transfer Example

// Send a file
const message = await client.sendFile(
  roomId,
  '/path/to/file.jpg',
  {
    filename: 'image.jpg',
    mimeType: 'image/jpeg',
    generateThumbnail: true
  }
);

// Download a file
await client.downloadFile(
  messageId,
  '/path/to/save.jpg',
  (progress) => {
    console.log(`Downloaded: ${progress.percentage}%`);
  }
);

Transaction Management

// Send with transaction support
const localId = await client.sendMessageWithTransaction(
  roomId,
  'Hello',
  'text',
  {
    retryOptions: {
      maxRetries: 3,
      baseDelay: 1000
    }
  }
);

// Retry failed transaction
await client.retryTransaction(localId);

Performance Optimization

The SDK includes several built-in optimizations:

Caching

// Configure cache sizes
const config = {
  roomMessages: 20,  // Number of rooms to cache messages for
  chats: 100,        // Number of chats to cache
  userData: 200,     // Number of user profiles to cache
  media: 50,         // Number of media items to cache
  thumbnails: 100    // Number of thumbnails to cache
};

// The SDK automatically manages these caches and evicts items as needed

Memory Management

// The SDK automatically monitors memory usage
if (client.isMemoryLow()) {
  // Caches will be cleared automatically based on priority
}

// You can also manually register caches
client.registerCache('custom', myCache, 5); // Priority 1-10

Documentation

For detailed documentation:

• API Reference
• Performance Optimizations
• Contributing Guidelines
• Development Roadmap

Development

This plugin was developed with assistance from AI tools, specifically Claude 3.5 and Claude 3.7 (Reasoning) by Anthropic using Cursor with private mode. We believe in full transparency about AI usage in software development.

Testing

npm run test

Building

npm run build

Support

• Report issues on GitLab
• Join our Matrix room for discussions

Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, COPYRIGHT HOLDERS, OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The Matrix protocol and its implementations are complex and constantly evolving. While we strive to maintain compatibility and security, users should:

• Thoroughly test the SDK in their specific use cases
• Keep the SDK and its dependencies up to date
• Follow Matrix security best practices
• Monitor Matrix security advisories

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.