Matrix Elixir SDK

A Matrix SDK for Elixir. It is currently in active (and early) development. The first (unstable) version has been released to hex. The docs can be found at https://hexdocs.pm/matrix_sdk.

The first release provides a simple wrapper around the main endpoints of the Matrix client-server API. There are still many endpoints to be implemented; if you feel like contributing, please don't hesitate to open an issue or a PR (all skill levels welcome)!

Likewise, if you want to start a project using the SDK, let me know!

Roadmap

In future, the SDK plans to include:

  • an encryption library (currently in development): olm-ex.
  • further abstractions around the Client library to handle state.
  • a wrapper for the Server-Server API
  • & more tbd.

Installation

The package can be installed by adding matrix_sdk to your list of dependencies in mix.exs:

def deps do
  [
    {:matrix_sdk, "~> 0.1.0"}
  ]
end

Basic Usage

Guest account registration. When initially joining the room it will ask you to fill out a consent form in the browser. Once this is done try joining the room again.

# Set the URL for the homeserver, this is the first argument of every function in the Client. 
iex(1)> url = "https://matrix.org"
# Set the room, this is used for the join_room/3 call.
iex(2)> room = "#elixirsdktest:matrix.org"
# ...
iex(3)> {:ok, %{body: %{"access_token" => token}}} = MatrixSDK.Client.register_guest(url)
# ...
iex(4)> {:ok, %{body: %{"consent_uri" => consent_uri}}} = MatrixSDK.Client.join_room(url, token, room)
# Open the link in the browser and accept the terms. 
iex(5)> MatrixSDK.Client.join_room(url, token, room_address)
# ...

Username and password login with an existing account:

iex(1)> url = "https://matrix.org"
# ...
iex(2)> auth = MatrixSDK.Client.Auth.login_user("username", "supersecretpassword")
%{
  identifier: %{type: "m.id.user", user: "username"},
  password: "supersecretpassword",
  type: "m.login.password"
}
iex(3)> {:ok, %{body: %{"access_token" => token}}} = MatrixSDK.Client.login(url, auth)
# ...
iex(4)> MatrixSDK.Client.joined_rooms(url, token)
# Returns a list of the rooms joined with that account.
iex(5)> MatrixSDK.Client.logout(url, token)
# Invalidates the token and logs the user out.