IXO MATRIX CLIENT SDK

This SDK provides a set of tools to interact with a Matrix server and associated bot services. It allows developers to query user profiles, room details, ACLs, and state information using pre-configured or custom home server and bot URLs.

• IXO MATRIX CLIENT SDK
  • Installation
  • Getting Started
    • Matrix API Client
      • Profile
      • Room
    • State Bot Client
      • ACL
      • State
    • Utilities
      • MXC Utilities
      • Validators

Installation

To install the SDK, add it to your project using npm or yarn:

npm install @ixo/matrixclient-sdk

or

yarn add @ixo/matrixclient-sdk

Getting Started

You can import the SDK and its components into your project as follows:

import { createMatrixApiClient, createMatrixStateBotClient, utils } from 'matrix-sdk';

This SDK allows you to create separate clients for interacting with the Matrix API and Matrix Bot services.

When making requests with the SDK, errors may occur. These are typically thrown as exceptions, so you should handle them using try...catch blocks.

Matrix API Client

To create a client for the Matrix API, use the createMatrixApiClient function. This client can be configured with a default homeServerUrl and an optional default accessToken, both of which can be overridden in individual method calls if needed.

const matrixApiClient = createMatrixApiClient({
    botUrl: 'https://your-homeserver-url',
    accessToken: 'your-access-token' // optional
});

Profile

The profile API methods allow you to retrieve information about a user's profile, including their display name, avatar URL, and full profile details. Note that the parameters are validated using the validators utility functions.

• queryProfile: Fetches the full profile of a user.

  const profile = await matrixApiClient.profile.v1beta1.queryProfile('@user:homeserver.url');
  console.log(profile.displayName, profile.avatar_url);

• queryDisplayname: Fetches the display name of a user.

  const displayName = await matrixApiClient.profile.v1beta1.queryDisplayname('@user:homeserver.url');
  console.log(displayName);

• queryAvatarUrl: Fetches the avatar URL of a user.

  const avatarUrl = await matrixApiClient.profile.v1beta1.queryAvatarUrl('@user:homeserver.url');
  console.log(avatarUrl);

The avatarUrl is returned as a mxc url which can be converted to a http url using the mxcUrlToHttp utility function. This will return an http url if the avatarUrl is a valid mxc url, otherwise it will return the original mxc url.

Room

The room api methods provide functionality to retrieve details about Matrix rooms, such as their ID and visibility. Note that the parameters are validated using the validators utility functions.

• queryId: Retrieves the room ID based on the room alias.

  const roomDirectory = await matrixApiClient.room.v1beta1.queryId('#roomAlias:homeserver.url');
  console.log(roomDirectory.room_id, roomDirectory.servers);

• queryVisibility: Retrieves the visibility status of a room.

  const roomVisibility = await matrixApiClient.room.v1beta1.queryVisibility('!roomId:homeserver.url');
  console.log(roomVisibility.visibility);

State Bot Client

To create a client for interacting with the state bot services, use the createMatrixStateBotClient function. This client can be configured with a default botUrl and an optional default accessToken, both of which can be overridden in individual method calls if needed.

const matrixStateBotClient = createMatrixStateBotClient('https://your-bot-url');

ACL

The state bot ACL methods allow you to retrieve access control lists (ACLs) for rooms, which specify what users or groups can access or edit certain parts of the room. The parameters are strictly validated using the validators utility functions. The state bot fetches the acl for a given key and optional path. If no path is provided (path = ''), the acl for the overall state object under the key is returned.

• queryAcl: Fetches the ACL data for a room. Note that '*' means all users.

  const aclData = await matrixStateBotClient.acl.v1beta1.queryAcl(
    '!roomId:homeserver.url',
    'impactsX',
    'profile'
  );
  console.log(aclData.data);

State

The state methods provide functionality to query the state of a room, including custom data stored within the room. The state bot fetches the state for a given key and optional path. If no path is provided (path = ''), the entire state object under the key is returned. The parameters are strictly validated using the validators utility functions.

• queryState: Fetches the state data for a room.

  const stateData = await matrixStateBotClient.state.v1beta1.queryState(
    '!roomId:homeserver.url',
    'impactsX',
    'profile'
  );
  console.log(stateData.data);

Utilities

The SDK also includes utility functions for various tasks.

MXC Utilities

The mxc utilities allow you to convert Matrix Content (MXC) URLs to standard HTTP URLs.

• getHttpUriForMxc: Converts an MXC URL to an HTTP URL.

  const httpUrl = utils.mxc.getHttpUriForMxc(
    'https://your-homeserver-url', // homeServerUrl
    'mxc://matrix.org/abc123', // the mxc url
    300, // width
    300, // height
    'crop' // resizeMethod
  );
  console.log(httpUrl); // Outputs the HTTP URL

Validators

The validators namespace provides a set of utility functions for validating user IDs and room IDs.

• isValidUserId: Validates whether a string is a properly formatted user ID. Note that all user IDs are prefixed with an '@'.

  const isValid = utils.validators.isValidUserId('@user:homeserver.url');
  console.log(isValid); // true or false

• isValidRoomId: Validates whether a string is a properly formatted room ID. Note that all room IDs are prefixed with an '!'.

  const isValid = utils.validators.isValidRoomId('!roomId:homeserver.url');
  console.log(isValid); // true or false

• isValidRoomAlias: Validates whether a string is a properly formatted room alias. Note that all room aliases are prefixed with an '#'.

  const isValid = utils.validators.isValidRoomAlias('#roomAlias:homeserver.url');
  console.log(isValid); // true or false

• isValidMxcLink: Validates whether a string is a properly formatted mxc link. Note that all mxc links are prefixed with an 'mxc://'.

  const isValid = utils.validators.isValidMxcLink('mxc://matrix.org/abc123');
  console.log(isValid); // true or false