diff --git a/README.md b/README.md index cf3e557c..f74ed8e2 100644 --- a/README.md +++ b/README.md @@ -10,65 +10,14 @@ Additionally, OpenSSL (libcrypto) must be provided on native platforms for E2EE. For flutter apps you can easily import it with the [flutter_olm](https://pub.dev/packages/flutter_olm) and the [flutter_openssl_crypto](https://pub.dev/packages/flutter_openssl_crypto) packages. -## How to use this - -1. Import the sdk - -```yaml - matrix: - # Optional: - flutter_olm: - flutter_openssl_crypto: +```sh +flutter pub add matrix +flutter pub add flutter_olm +flutter pub add flutter_openssl_crypto ``` -```dart -import 'package:matrix/matrix.dart'; -``` +## Get started -2. Create a new client: +See the API documentation for details: -```dart -final client = Client("HappyChat"); -``` - -The SDK works better with a database. Otherwise it has no persistence. For this you need to provide a databaseBuilder like this: - -```dart -final client = Client( - "HappyChat", - databaseBuilder: (_) async { - final dir = await getApplicationSupportDirectory(); // Recommend path_provider package - final db = HiveCollectionsDatabase('matrix_example_chat', dir.path); - await db.open(); - return db; - }, -); -``` - -3. Connect to a Matrix Homeserver and listen to the streams: - -```dart -client.onLoginStateChanged.stream.listen((bool loginState){ - print("LoginState: ${loginState.toString()}"); -}); - -client.onEvent.stream.listen((EventUpdate eventUpdate){ - print("New event update!"); -}); - -client.onRoomUpdate.stream.listen((RoomUpdate eventUpdate){ - print("New room update!"); -}); - -await client.checkHomeserver("https://yourhomeserver.abc"); -await client.login( - identifier: AuthenticationUserIdentifier(user: 'alice'), - password: '123456', -); -``` - -4. Send a message to a Room: - -```dart -await client.getRoomById('your_room_id').sendTextEvent('Hello world'); -``` +[API documentation](https://pub.dev/documentation/matrix/latest/) \ No newline at end of file diff --git a/doc/get-started.md b/doc/get-started.md new file mode 100644 index 00000000..5b2d5f69 --- /dev/null +++ b/doc/get-started.md @@ -0,0 +1,75 @@ +Follow these steps to get started with your first Matrix Client. + +## Step 1: Add dependencies + +In your `pubspec.yaml` file add the following dependencies: + +```yaml + matrix: + # If you plan to use the SDK in a Flutter application on IO: + sqflite: + # For end to end encryption: + flutter_olm: + flutter_openssl_crypto: +``` + +## Step 2: Create the client + +```dart +final client = Client( + '', + databaseBuilder: (client) => MatrixSdkDatabase( + '', + database: await openDatabase(''), + ), +); +``` + +## Step 3: Login + +```dart +// Connect to a homeserver before login: +final homeserver = Uri.parse('https://matrix.org'); +await client.checkHomeserver(homeserver); + +await client.login( + LoginType.password, + user: AuthenticationUserIdentifier(user: ''), + password: '', +); +``` + +## Step 4: Create a new room + +```dart +// Start a new DM room or return an existing room with a user +final roomId = await client.startDirectChat(''); + +// Start a new group chat +final roomId = await client.createGroupChat(name: ''); +``` + +## Step 5: Send messages + +```dart +// Get a specific room by room ID or iterate over `client.rooms`: +final room = client.getRoomById(''); +// Or get the DM room for a user: +final dmRoom = client.getDirectChatFromUserId(''); + +// Send a normal text message into the room: +await room.sendTextEvent(''); +``` + +## Step 6: Receive messages + +```dart +// Load the timeline of a room: +final timeline = await room.getTimeline( + onUpdate: reloadYourGui(), + onInsert: (i) => print('New message!'), +); + +// Print all messages in the timeline to the console +for(final event in timeline.events) print(event.calcLocalizedBodyFallback()); +``` \ No newline at end of file diff --git a/doc/web.md b/doc/web.md new file mode 100644 index 00000000..fd9f6f20 --- /dev/null +++ b/doc/web.md @@ -0,0 +1,25 @@ +To use end to end encryption in web you have to download the olm javascript/wasm library: + +```sh +#!/bin/sh -ve +rm -r assets/js/package + +OLM_VERSION=$(cat pubspec.yaml | yq .dependencies.flutter_olm) +DOWNLOAD_PATH="https://github.com/famedly/olm/releases/download/v$OLM_VERSION/olm.zip" + +curl -L $DOWNLOAD_PATH > olm.zip +unzip olm.zip +rm olm.zip +``` + +...and import it in your `index.html`: + +```html + + + ... + + + ... + +``` \ No newline at end of file diff --git a/lib/src/database/matrix_sdk_database.dart b/lib/src/database/matrix_sdk_database.dart index 89a89575..4a230769 100644 --- a/lib/src/database/matrix_sdk_database.dart +++ b/lib/src/database/matrix_sdk_database.dart @@ -36,6 +36,20 @@ import 'package:matrix/src/utils/run_benchmarked.dart'; import 'package:matrix/src/database/indexeddb_box.dart' if (dart.library.io) 'package:matrix/src/database/sqflite_box.dart'; +/// Database based on SQlite3 on native and IndexedDB on web. For native you +/// have to pass a `Database` object, which can be created with the sqflite +/// package like this: +/// ```dart +/// final database = await openDatabase('path/to/your/database'); +/// ``` +/// +/// **WARNING**: For android it seems like that the CursorWindow is too small for +/// large amounts of data if you are using SQFlite. Consider using a different +/// package to open the database like +/// [sqflite_sqlcipher](https://pub.dev/packages/sqflite_sqlcipher) or +/// [sqflite_common_ffi](https://pub.dev/packages/sqflite_common_ffi). +/// Learn more at: +/// https://github.com/famedly/matrix-dart-sdk/issues/1642#issuecomment-1865827227 class MatrixSdkDatabase extends DatabaseApi { static const int version = 7; final String name;