MATRIX Client API

This is a purpose built wrapper for the Matrix API and by no neans a general-purpose SDK! It creates top-level abstractions like project-list and project which are only suitable for ODINv2 replication. It's designed to support both nodejs and browser environments.

WARNING: As of 14mar23 the nodejs runtime must be version 18+ since it requires the (currently experimental) implementation of the fetch API!

http-api

The http-api is a very thin layer for the Matrix http (REST-like) api. The only enhancement is the automated renewal of the access token. This API does not have any ODIN domain specific functionality.

On top of the http-api we have three pillars (structure-api, command-api and timeline-api). These APIs use ODIN domain terms like project and layer but the ids used are still out of the Matrix domain.

structure-api

The structure-api creates ODINv2 structural components like projects (Matrix spaces) and layers (Matrix rooms), allows you to invite users to shared projects and so on. On the other hand one can enumerate existing projects and invitations to join shared projects. You must be in state online to use this API. Top level abstractions must deny access to the methods of this API and/or handle errors accordingly.

command-api

The command-api is a send-only API and is responsible for sending the payload messages to the matrix server. Typically triggered by a state change of a feature or style that is embraced by a layer these messages must get posted in a Matrix room. This API is the only one that can be used while beeing offline. All messages are queued and delivered in-order. If a client is offline there is a retry mechanism that will even work if ODIN gets shut-down and restarted. (TODO :-))

timeline-api

The timeline-api is a receive-only API and is intended to transfer changes from the matrix server to ODINv2. By making use of filters the API can be focused on the project list or a selected project (making use of room ids).

project-list

The project-list targets the ODINv2 view where projects are shared and joined. This API requires the structure-api and the timeline-api. With the exception of user-ids for invitations only ids from the ODIN domain are visible to users of this API. project-list holds a mapping from ODIN ids to Matrix ids.

project