matrix_sdk 0.33.0+1

  • Readme
  • Changelog
  • Example
  • Installing
  • 80

Matrix Dart SDK #

An SDK written in Dart to connect to Matrix, the federated communication protocol.

This SDK is for general use, but mainly being developed for Pattle, an easy to use Matrix app.

Please note that this SDK is still pre-1.0 and in development. Things may still change a lot!

Usage #

Set the initial MyUser, either by logging in to a homeserver:

   final homeserver = Homeserver(Uri.parse('https://pattle.im'));

   var user = await homeserver.login(
     Username('pat'),
     'pattle',
     store: MemoryStore(),
   );

Or, from a Store, for example, the included MoorStore, which uses moor:

   var user = await MyUser.fromStore(
     MoorStore(
       LazyDatabase(
         () => VmDatabase(File('/somewhere')),
       ),
     ),
   );

Once a MyUser has been set up, you can start syncing with:

   user.startSync();

All data objects such as MyUser, Room, etc. are immutable.

The user has a stream of Updates, user.updates. An Update contains the latest 'snapshot' of data associated with the user. It also contains a delta MyUser, where all properties are null, except those that are changed. For example, if a user started typing in a certain room, and we're syncing, there will be an Update in user.updates, where delta has 1 Room in delta.rooms, with only the room where the user started typing, reflected in room.typingUserIds. All other properties of the Room will be null. This is all assuming that this is the only change in the sync. If more happened, it will be reflected in delta.

Use update.user to get the complete up-to date copy of all data. Note that rooms, timelines and memberTimelines may not be a complete set of the data, more might need to be retrieved from the Store or remotely. You can use load on rooms, timeline and memberTimeline, to load more items.

   user.startSync();

   // Do something after the first received sync specifically.
   var update = await user.updates.firstSync;

   // ALWAYS use the MyUser from the latest update.
   // It will have the latest data.
   user = update.user;

   print(user.rooms.length);

   // Get more events from the timeline. This also returns an update.
   // Note that because we're doing things before we listen to updates, we
   // might miss some syncs. Even though we've missed some syncs, the update
   // received from the load is the most up to date one, and will contain a
   // user with data from processed syncs in the background.
   update = await user.rooms.first.timeline.load(count: 50);
   user = update.user;

   // Because we called load, the update is a RequestUpdate<Timeline>,
   // which means data is the updated Timeline, now with more items.
   print(update.data.timeline.length);

   // Do something every sync. If you don't use onlySync, you will also
   // receive updates that are caused by a request (such as above, load).
   // If you do a request (such as timeline.load) inside a Stream with all
   // updates, and await for it also in the stream, you will use it twice.
   await for (update in user.updates.onlySync) {
     user = update.user;
   }

Custom events #

The SDK also supports any custom types, using RawRoomEvent. To get RawRoomEvents from the timeline easily, use

   timeline.withCustomType('my.type');

Custom events have a RawEventContent, which is comparable to a Map<String, dynamic> in API. For example, to get the name of a im.vector.modular.widgets event:

   final widgetsEvent = timeline.firstWithCustomType('im.vector.modular.widgets');
   final name = widgetsEvent.content['name'];

State events

For custom state events, you can retrieve them as such:

   final widgetsEvent = someRoom.stateEvents['im.vector.modular.widgets']['some_key'];

Contributing #

Contributions are encouraged!

We use the DCO, which asserts that the contribution is yours, and you allow the Matrix Dart SDK to use it.

If you agree to what's stated in the DCO (also shown under), you can sign-off your commits:

   Signed-off-by: Joe Smith <joe.smith@email.org>

If your user.name and user.email are set for git, you can sign-off your commits using:

   git commit -s

Contributions can only be accepted if you agree to the DCO, indicated by the sign-off.

DCO #

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

0.33.0+1 #

  • Support custom events using RawRoomEvent and RawStateEvent Check the README for details.
  • Add ability to register using Homeserver.register
  • Add VideoMessageEvent
  • Add Room.canonicalAlias and Room.alternativeAliases
  • Add format field to TextMessage (thank you Cyril Dutrieux!)
  • Remove equatable dependency

See previous versions here

example/main.dart

// Copyright (C) 2020  Wilko Manger
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

import 'dart:io';

import 'package:matrix_sdk/matrix_sdk.dart';

void main() async {
  final homeserver = Homeserver(Uri.parse('https://pattle.im'));

  var user = await homeserver.login(
    Username('pat'),
    'pattle',
    // Use a valid Moor backend here
    store: MoorStoreLocation.file(File('/somewhere')),
  );

  user.startSync();

  // Do something after the first sync specifically.
  var update = await user.updates.firstSync;
  // ALWAYS use the MyUser from the latest update. It will have the latest data.
  user = update.user;

  print(user.rooms.length);

  // Get more events from the timeline. This also returns an update.
  // Note that because we're doing things before we listen to updates, we
  // might miss some syncs. Even though we've missed some syncs, the update
  // received from the load is the most up to date one, and will contain a
  // user with data from processed syncs in the background.
  update = await user.rooms.first.timeline.load(count: 50);
  user = update.user;

  print(user.rooms.first.timeline.length);

  // Do something every sync. If you don't use onlySync, you will also receive
  // updates that are caused by a request (such as above). If you do a request
  // (such as timeline.load) inside a Stream with all updates, and await
  // for it also in the stream, you will use it twice.
  await for (update in user.updates.onlySync) {
    user = update.user;
  }
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  matrix_sdk: ^0.33.0+1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:matrix_sdk/matrix_sdk.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
63
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
80
Learn more about scoring.

We analyzed this package on Jul 5, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13

Analysis suggestions

Package does not support Flutter platform android

Because of import path [package:matrix_sdk/matrix_sdk.dart, package:matrix_sdk/src/store/moor/moor_store.dart, package:moor_ffi/moor_ffi.dart] that declares support for platforms:

Package does not support Flutter platform ios

Because of import path [package:matrix_sdk/matrix_sdk.dart, package:matrix_sdk/src/store/moor/moor_store.dart, package:moor_ffi/moor_ffi.dart] that declares support for platforms:

Package does not support Flutter platform linux

Because of import path [package:matrix_sdk/matrix_sdk.dart, package:matrix_sdk/src/store/moor/moor_store.dart, package:moor_ffi/moor_ffi.dart] that declares support for platforms:

Package does not support Flutter platform macos

Because of import path [package:matrix_sdk/matrix_sdk.dart, package:matrix_sdk/src/store/moor/moor_store.dart, package:moor_ffi/moor_ffi.dart] that declares support for platforms:

Package does not support Flutter platform web

Because of import path [package:matrix_sdk/matrix_sdk.dart, package:matrix_sdk/src/store/moor/moor_store.dart, package:moor_ffi/moor_ffi.dart] that declares support for platforms:

Package does not support Flutter platform windows

Because of import path [package:matrix_sdk/matrix_sdk.dart, package:matrix_sdk/src/store/moor/moor_store.dart, package:moor_ffi/moor_ffi.dart] that declares support for platforms:

Package not compatible with runtime web

Because of the import of dart:isolate via the import chain package:matrix_sdk/matrix_sdk.dartpackage:matrix_sdk/src/util/mxc_url.dartpackage:matrix_sdk/src/homeserver.dartpackage:matrix_sdk/src/updater/updater.dartpackage:matrix_sdk/src/updater/isolated/isolated_updater.dartpackage:matrix_sdk/src/updater/isolated/isolate_runner.dartdart:isolate

Maintenance issues and suggestions

Support latest dependencies. (-10 points)

The version constraint in pubspec.yaml does not support the latest published versions for 1 dependency (moor_ffi).

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
async ^2.4.0 2.4.1
chopper ^3.0.1 3.0.3
collection ^1.14.12 1.14.13
ffi ^0.1.3 0.1.3
http ^0.12.0+4 0.12.1
image ^2.1.12 2.1.13
meta ^1.1.6 1.1.8
mime ^0.9.6+3 0.9.6+3
moor ^3.1.0 3.2.0
moor_ffi ^0.6.0 0.6.0 0.7.0
pedantic ^1.0.0 1.9.0 1.9.1
quiver ^2.1.3 2.1.3
synchronized ^2.2.0 2.2.0+1
Transitive dependencies
archive 2.0.13
args 1.6.0
charcode 1.1.3
convert 2.1.1
crypto 2.1.5
http_parser 3.1.4
logging 0.11.4
matcher 0.12.8
path 1.7.0
petitparser 3.0.4
source_span 1.7.0
stack_trace 1.9.5
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.2.0
xml 3.7.0 4.2.0
Dev dependencies
build_runner ^1.0.0
chopper_generator ^3.0.1
dotenv ^1.0.0
effective_dart ^1.2.1
mockito ^4.1.0
moor_generator ^3.0.0
precise_pattle ^1.0.5
test ^1.0.0