matrix_sdk 0.25.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 62

Matrix Dart SDK #

A Dart implementation of the federated communications protocol, Matrix.

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

Usage #

   import 'package:matrix_sdk/matrix_sdk.dart';
   import 'package:url/url.dart';

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

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

     await for(SyncState syncState in user.sync()) {
       await for (final room in user.rooms.all()) {
         // Do something
       }
     }
   }

This example uses the SqfliteStore , which is a seperate dependency and only works on Flutter.

Note that using a store is optional.

Also uses the url package for Url.parse(..).

Contributing #

To contribute, a CLA has to be signed. This is the Fiduciary Contributor License Agreement, a very free software friendly license agreement. It actually guarantees you (the Contributor) that your contributions will never be relicensed to anything other than AGPL version 3 or higher.

To sign the CLA, please send a signed copy to wilko@rens.onl.

An image of your signature is also okay, to do this easily you can edit the HTML version, add a photo of your signature as an <img> tag, render it with pandoc using:

   pandoc cla-signed.html -t html -o cla-signed.pdf --css cla.css

Please note that in the future the signing process will be automated using CLAM.

0.25.0 #

  • Relicense to MPL-2.0
  • Remove all individual state fields of Room and use RoomStateEvents to store state
  • Add getters for power levels to Room
  • Implement room aliases

0.24.3 #

  • Make sure that Members.count is and will never return null

0.24.2 #

  • Fix generated code being out of sync

0.24.1 #

  • Add LocalUser.setName method
  • Fix null exception for specific event power levels

0.24.0 #

  • Set profile info of local user on login

  • Use fewer methods for storing LocalUser

    There's just getLocalUser and getSyncToken (and equivalent setters).

  • Fix exception when serializing if duration is null

0.23.9 #

  • Fix audio message duration serialization

0.23.8 #

  • Handle an audio message without duration correctly
  • Handle a power levels event without specific event levels correctly
  • Fix homeserver test

0.23.7 #

  • Don't throw an exception by default

0.23.6 #

  • Make id optional in Device constructor

0.23.5 #

  • Copy the device ID returned from the login response

0.23.4 #

  • Let ImageMessageEvent be created with Event.fromContent

0.23.3 #

  • Use POST for read marker endpoint

0.23.2 #

  • Add Room.markRead method

0.23.1 #

  • Add notification count properties to inherited Room constructors

0.23.0 #

  • Add userId to Device
  • Remove trailing slash from .well-known homeserver url
  • Set setCurrentDevice return type to Future<void>
  • Let Username.toString return its value
  • Save Device on login
  • Set userId of Device on login
  • Add copyWith method to Device
  • Add Homserver.fromWellKnown tests
  • Add httpClient param to Homeserver.fromWellKnown for testing
  • Add libolm build script

0.22.1 #

  • Add notification count properties to Room
  • Parse power levels even if they're strings
  • Make sure duration milliseconds is an int
  • Change AudioInfo.duration type to Durration
  • Fix exceptions when total member count is unknown
  • Add Account for the olm implementation
  • Rename Id to MatrixId and let Id be genereic id
  • Add Device class (now used in Homeserver.login)
  • Handle no specific power level events properly
  • Add unit tests

0.21.1 #

  • Fix example code

0.21.0 #

  • Add deviceId and deviceName parameters to login(..)
  • Make the store parameter @required at login(..)

0.20.3 #

  • Don't check ephemeral events if not supplied

0.20.1 #

  • Fix User hash code implementation

0.20.0 #

  • Redo Members implementation

  • Members can now be retrieved remotely

  • Remove User.isIdenticalTo

    The == operator is now equivalent to the removed method.

0.19.8 #

  • Add Storables.isLastPossibleItem

    Used so that the timeline will not try to get events from store or remote when the RoomCreationEvent has been passed.

  • Add SyncState.dirtyRooms

  • Fix exception when typingUsers contains nulls

0.19.6 #

  • Add isSomeoneTyping and isSomeoneElseTyping properties to Room

0.19.4 #

  • Implement typing notifications
    • Use room.typingUsers to see which users are typing
    • Use room.setIsTyping to notify that the LocalUser is typing
  • Add PowerLevelsChangeEvent

0.19.3 #

  • Export TopicChangeEvent

0.19.2 #

  • Implement m.room.topic

  • Fix exception when room summary is null (thanks Mathieu!)

  • Format code with dartfmt

    For new merge requests, code is checked with dartfmt and dartanalyzer whether it's formatted and correct.

0.19.1 #

  • Downgrade meta package dependency to 1.1.6

0.19.0 #

  • Add from and count to Store.getMembers(..)
  • Use protected methods of Storables correctly
  • Let Storables.getFromMemory(..) be sync instead of async
  • Fix some issues with Members not returning anything

0.18.3 #

  • Add Members.count

    This is the actual amount of users in the room, not how many users are stored in memory or the store.

0.18.2 #

  • Add paginating functionality to Storables

    A new method has been added to Storables: paginate. This can be used to get a 'page' of items (like from the Timeline).

  • Remove use of Streams

    Storables methods that returned Stream<T> before will now return a Future<Iterable<T>>

  • Process state when fetching events remotely

    This means that the user states are now correctly set for remote messages!

  • Don't parse events with invalid user IDs

  • Add MemoryStore

Changes thanks to Mathieu:

  • Remote state_key from StateEventContent
  • Fix parsing of redaction of state events
  • Add upload method to LocalUser
  • Use Stream<List<int>> for upload and download method instead of Uint8List

0.17.3 #

  • Fix missing semicolon

0.17.2 #

  • Don't handle room upgrades without a replacement specified

0.17.1 #

  • Export RoomUpgradeEvent

0.17.0 #

  • Room.timeline(..) can now return message from a previous room if the room was upgraded, for a seamless timeline between upgrades
  • Restructuring of protected methods and other things in Storables
  • Handle mapping of Matrix types differently

0.16.3 #

  • Fix url FormatException not handled

0.16.2 #

  • Mark a room as non-direct if someone new joins

0.16.1 #

  • Fix upTo being null raising an exception

0.16.0 #

  • Rename upTo(..) to get(..) in Storables
  • Merge all(..) in to get(..) in Storables
  • Rename get(..) to getStateOf(..) Members
  • Don't process state events without a state_key

0.15.2 #

  • Use actual nulls when serializing urls

0.15.1 #

  • Don't check whether Url is valid in download methods The given Url already is valid.

0.15.0 #

  • Use url package for all URLs

0.14.0 #

  • Enforce URL validity Use Url.parse(..) to parse a String to an Uri, but which is guaranteed to be an URL, not just an URI (if parsing was successful, otherwise throws a FormatException).

0.13.3 #

  • Add Homeserver.fromWellKnown function Use this to create a Homeserver based on .well-known data.

0.13.2 #

  • Set _directUser based on InviteEvent too
  • Don't serialize width and height if null
  • Add proper toString to MatrixException

0.13.1 #

  • Implement LeftRoom
  • Change Store Room methods to general names (getRooms(..) instead of getJoinedRooms(..), etc.)
  • Set room name to null if set to empty string
  • Remove fromJson(..) factory constructor from Room
  • Remove store param from Room
  • Make all Room parameters named

0.12.3 #

  • Fix remote var being wrong type

0.12.2 #

  • Add original json body to MatrixException
  • Use UnknownException as default MatrixException
  • Handle null room names correctly
  • Fix exception when a Storables has no remote items
  • Handle when width and/or height of ImageInfo are null

0.12.0 #

  • Remove all from parameters

0.11.0 #

Changes from Mathieu Velten:

  • Add allowRemote to option to upTo
  • Add to parameter to upTo
  • Remove from from upTo
  • Add AudioMessageEvent

0.10.1 #

  • Add rooms.create method
  • Remove integration tests These will be replaced with proper unit tests in the future.

0.10.0 #

  • Rename AvatarUrlChangeEvent to AvatarChangeEvent
  • Rename AvatarChangeEvent to RoomAvatarChangeEvent
  • Rename NameChangeEvent to RoomNameChangeEvent
  • Add RoomCreationEvent
  • members.get() returns oldest user state if the given time (at) is lower than any known state.
  • Fix state not being processed properly if room was newly created. Now all processing of events is done in a single function.

0.5.8 #

  • Add DisplayNameChangeEvent and AvatarUrlChangeEvent
  • Check if the user id is valid when processing direct chats

0.5.7 #

  • Sort items from memory in all() call

0.5.6 #

  • Implement redactions

0.5.5 #

  • Leave user name null if unset

0.5.4 #

  • Add avatarUrl field to User
  • Make membershipType protected

0.5.3 #

  • Add directUser to JoinedRoom constructor

0.5.2 #

  • Implement m.direct

0.5.1 #

  • Set room name to null if name is an empty string

0.5.0 #

  • Let room name be null if unset

0.4.12 #

  • Serialize replies

0.4.11 #

  • Add inReplyToId field to MessageEventContent

0.4.10 #

  • Add transaction_id param to send
  • Serialize transaction_id
  • Use RoomEventArgs in Event.fromJson

0.4.9 #

  • Pass sentState to args
  • Await sending

0.4.8 #

  • Add RoomEventArgs and rename SentState.waiting

0.4.7 #

  • Add getUnsentEvents method to Store
  • Retry sending if failed

0.4.6 #

  • Get display name from prev_content as backup

0.4.5 #

  • Fix leave events not having a display name set

0.4.4 #

  • Pass a SyncState object in the sync stream

0.4.3 #

  • Add downloadThumbnail method

0.4.2 #

  • Fix sending test
  • Add formattedBody field to TextMessageEvent
  • Fix store required being non-null

0.4.1 #

  • Serialize display name of member change event

0.4.0 #

  • Implement local message echo

0.3.9 #

  • Serialize url and image info properly

0.3.8 #

  • Fix url not being serialized of image message

0.3.7 #

  • Add image information to image message event

0.3.6 #

  • Return null if image url is null

0.3.5 #

  • Implement m.image message event

0.3.2 #

  • Add delete() method to Store

0.3.1 #

  • Add ability to logout

0.3.0 #

  • Implement message sending
  • Move content fields to seperate classes

0.2.4 #

  • Don't pass dependency injection scope seperately
  • Don't silence dependency injection errors
  • Fix events sometimes being null

0.2.3 #

  • Implement fetching events from history
  • Use dependency injection (using Kiwi)
  • Simplify user assignment when creating events
  • Don't sort items when adding them
  • Implement upTo(count) method in Storables

0.2.2 #

  • Fix exception when handling avatar deletion

0.2.1 #

  • Add option to set user when creating event
  • Let display names also be set on subsequent syncs

0.2.0 #

  • Add Room and User reference to events
  • Save more efficiently
  • Remove print when using historical localpart
  • Add fullState param to sync api
  • Implement members
  • Change some field names
  • Add null checks to LocalUser.fromStore()

0.1.9 #

  • Remove idb_shim dependency
  • Make Rooms and Events implementation generic
  • Deserialize other member events, add displayname
  • Restructure event classes
  • Implement m.room.member
  • Fix events.state() returning MessageEvent stream

0.1.8 #

  • Cast specific event streams
  • Use room id as name if room name is null

0.1.7 #

  • Add avatar url to JoinedRoom constructor

0.1.6 #

  • Fix AvatarChangeEvent not being able to serialize

0.1.5 #

  • Implement m.room.avatar event
  • Add media download method

0.1.4 #

  • Add LocalUser.fromStore
  • Add ability to store homeserver and user id

0.1.3 #

  • Don't check whether Store is open in LocalUser constructor

0.1.2 #

  • Make Store per user
  • Remove IndexedDbStore

0.1.1 #

  • Export event(s)

0.1.0 #

  • Add basic event support
  • Use IndexedDB instead of Sembast store
  • Let store support multiple LocalUsers
  • Fix equality issues
  • Restructure tests, use a test room on matrix.org
  • Use dotenv for username and password in tests

0.0.7 #

  • Fix bug where sync would continously add duplicate rooms

0.0.6 #

  • Fix sync always being initial sync

0.0.5 #

  • Depend on a lower version of the meta package

0.0.4 #

  • Fix syncing without store throwing exception
  • Add missing meta dependency
  • Add example code
  • Remove unused imports

example/main.dart

import 'package:matrix_sdk/matrix_sdk.dart';
import 'package:url/url.dart';

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

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

  await for (SyncState _ in user.sync()) {
    for (Room room in await user.rooms.get()) {
      print(room.name);
    }
  }
}

Use this package as a library

1. Depend on it

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


dependencies:
  matrix_sdk: ^0.25.0

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]
67
Health:
Code health derived from static analysis. [more]
42
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
80
Overall:
Weighted score of the above. [more]
62
Learn more about scoring.

We analyzed this package on Oct 11, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.1
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:matrix_sdk/matrix_sdk.dart.

Health issues and suggestions

Fix lib/src/encryption/ffi/olm.dart. (-57.81 points)

Analysis of lib/src/encryption/ffi/olm.dart failed with 3 errors:

line 45 col 20: The method 'allocate' isn't defined for the class 'OlmFFI'.

line 50 col 26: The method 'allocate' isn't defined for the class 'OlmFFI'.

line 61 col 33: The method 'allocate' isn't defined for the class 'OlmFFI'.

Maintenance issues and suggestions

Support latest dependencies. (-20 points)

The version constraint in pubspec.yaml does not support the latest published versions for 2 dependencies (chopper, url).

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
chopper ^2.4.2 2.5.3 3.0.1
http ^0.12.0+2 0.12.0+2
kiwi ^0.2.0 0.2.0
meta ^1.1.6 1.1.7
url ^1.0.1 1.0.1 2.0.0
Transitive dependencies
async 2.4.0
charcode 1.1.2
collection 1.14.12
http_parser 3.1.3
logging 0.11.3+2
path 1.6.4
source_span 1.5.5
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6
validators 2.0.0+1
Dev dependencies
build_runner ^1.0.0
chopper_generator ^2.4.2
dotenv ^1.0.0
mockito ^4.1.0
pedantic ^1.0.0 1.8.0+1
test ^1.0.0