matrix-client-0.1.4.3: A matrix client library
Safe HaskellSafe-Inferred
LanguageHaskell2010

Network.Matrix.Tutorial

Description

The matrix-client library provides a simple interface for interacting with Matrix servers.

This tutorial introduces how to use the matrix-client library.

You will need a token to create a session, if you already have an account, you can get it with the element client by visiting the account Settings page, Help & About panel, then click Access Token.

Alternatively, you can setup a test service by running these commands in a terminal:

git clone https://github.com/matrix-org/dendrite
cd dendrite; ./build.sh; ./bin/generate-keys --private-key matrix_key.pem; cp dendrite-config.yaml dendrite.yaml
./bin/dendrite-monolith-server --config dendrite.yaml
curl -XPOST http://localhost:8008/_matrix/client/r0/register -d'{"username": "tristanC", "password": "supersecret", "auth": {"type": "m.login.dummy"}}'

To avoid manipulating the token directly, put it in your environment:

export MATRIX_TOKEN="THE_ACCESS_TOKEN"
Synopsis

    Introduction

    To start using this library you need a haskell toolchain, on fedora run:

    $ sudo dnf install -y ghc cabal-install && cabal update

    Then get a copy of the library by running:

    $ git clone https://github.com/softwarefactory-project/matrix-client-haskell
    $ cd matrix-client-haskell

    Start a REPL:

    $ cabal repl
    Prelude> import Network.Matrix.Client
    Prelude Netowrk.Matrix.Client> :set prompt "> "
    > :set -XOverloadedStrings
    > :type getTokenOwner
    getTokenOwner :: ClientSession -> MatrixIO WhoAmI

    Create a session

    Most functions require ClientSession which carries the endpoint url and the http client manager.

    The only way to get the client is through the createSession function:

    > token <- getTokenFromEnv "MATRIX_TOKEN"
    > sess <- createSession "https://matrix.org" token
    > getTokenOwner sess
    Right (WhoAmI "@tristanc_:matrix.org")

    Get messages

    Create a filter to limit the sync result using the createFilter function. To keep room message only, use the messageFilter default filter:

    > Right userId <- getTokenOwner sess
    > Right filterId <- createFilter sess userId messageFilter
    > getFilter sess (UserID "@gerritbot:matrix.org") filterId
    Right (Filter {filterEventFields = ...})

    Call the sync function to synchronize your client state:

    > Right syncResult <- sync sess (Just filterId) Nothing (Just Online) Nothing
    > putStrLn $ take 512 $ show (getTimelines syncResult)
    SyncResult {srNextBatch = ...}

    Get next batch with a 300 second timeout using the since argument:

    > Right syncResult' <- sync sess (Just filterId) (Just (srNextBatch syncResult)) (Just Online) (Just 300000)

    Here are some helpers function to format the messages from sync results, copy them in your REPL:

    > import qualified Data.Text.IO as Text
    > :{
      let printEvent re = Text.putStrLn $ case reContent re of
            EventRoomMessage (RoomMessageText mt) -> unAuthor (reSender re) <> ": " <> mtBody mt
            _ -> ""
      :}
    > let printRoomEvent room event = Text.putStr room >> putStr "| " >> printEvent event
    > let printRoomEvents (RoomID room, events) = traverse (printRoomEvent room) events
    > let printTimelines sr = mapM_ printRoomEvents (getTimelines sr)
    > printTimelines syncResult
    ...

    Use the syncPoll utility function to continuously get events, here is an example to print new messages, similar to a tail -f process:

    > syncPoll sess (Just filterId) (Just (srNextBatch syncResult)) (Just Online) printTimelines
    room1| test-user: Hello world!
    ...

    Lookup identity

    To use the Identity api you need another token. Get it by running these commands:

    $ MATRIX_OPENID=$(curl -XPOST https://matrix.org/_matrix/client/r0/user/${USER}/openid/request_token -H "Authorization: Bearer ${MATRIX_TOKEN}" -d '{}')
    $ export MATRIX_IDENTITY_TOKEN=$(curl -XPOST https://matrix.org/_matrix/identity/v2/account/register -d "${MATRIX_OPENID}" | jq -r '.access_token')

    Then here is how to lookup a matrix identity:

    > import Network.Matrix.Identity
    > tokenId <- getTokenFromEnv "MATRIX_IDENTITY_TOKEN"
    > sessId <- createIdentitySession "https://matrix.org" tokenId
    > Right hd <- hashDetails sessId
    > identityLookup sessId hd (Email "tdecacqu@redhat.com")
    Right (Just (UserID "@tristanc_:matrix.org"))