nativescript-matrix-sdk/README.md

Native Matrix SDK integration for NativeScript

# 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](https://github.com/matrix-org/matrix-ios-sdk) and [Matrix Android SDK](https://github.com/matrix-org/matrix-android-sdk2) to provide a unified TypeScript API.

[![npm](https://img.shields.io/npm/v/nativescript-matrix-sdk.svg)](https://www.npmjs.com/package/nativescript-matrix-sdk)
[![npm downloads](https://img.shields.io/npm/dt/nativescript-matrix-sdk.svg)](https://www.npmjs.com/package/nativescript-matrix-sdk)

## 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

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

### iOS Setup
Requires iOS 12.0 or later. Add to your Podfile:
```ruby
pod 'MatrixSDK', '~> 0.28.1'
```

### Android Setup
Requires Android API level 21 or later. Add to your build.gradle:
```gradle
implementation 'org.matrix.android:matrix-android-sdk2:1.6.2'
```

## Quick Start

### Basic Usage
```typescript
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
```typescript
// 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
```typescript
// 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
```typescript
// 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
```typescript
// 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
```typescript
// 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](DOCUMENTATION.md)
- [Performance Optimizations](OPTIMIZATIONS.md)
- [Contributing Guidelines](CONTRIBUTING.md)
- [Development Roadmap](TODO.md)

## 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
```bash
npm run test
```

### Building
```bash
npm run build
```

## Support

- Report issues on [GitLab](https://gitlab.com/ascade/nativescript-matrix-sdk/-/issues)
- Join our [Matrix room](https://matrix.to/#/#nativescript-matrix-sdk:matrix.org) 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](LICENSE) file for details.