### Complete Client Setup (JavaScript)

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

A complete example of the client setup in JavaScript, including imports, configuration, and starting the client.

```javascript
import {
    MatrixClient,
    SimpleFsStorageProvider,
    AutojoinRoomsMixin
} from "matrix-bot-sdk";

const homeserverUrl = "https://matrix.org"; // make sure to update this with your url
const accessToken = "YourSecretAccessToken";
const storage = new SimpleFsStorageProvider("bot.json");

const client = new MatrixClient(homeserverUrl, accessToken, storage);
AutojoinRoomsMixin.setupOnClient(client);

client.start().then(() => console.log("Client started!"));

```

--------------------------------

### Start the Matrix Client

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Start the Matrix client to connect to the homeserver and begin processing events. Logs 'Client started!' upon successful connection.

```javascript
client.start().then(() => console.log("Client started!"));

```

--------------------------------

### Install matrix-bot-sdk

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Install the matrix-bot-sdk npm package. This is the only dependency required.

```bash
mkdir matrix-js-echo-bot
cd matrix-js-echo-bot
npm install matrix-bot-sdk

```

--------------------------------

### Install TypeScript Compiler

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Install the TypeScript compiler using npm. This is the first step to using TypeScript with the matrix-bot-sdk.

```bash
npm install typescript

```

--------------------------------

### Membership Event Content Example

Source: https://matrix.org/docs/spec/server_server/latest.html

This is an example of the content for a membership event, specifically for a user leaving a room.

```json
{
  "content": {
    "membership": "leave"
  },
  "depth": 0,
  "origin": "example.org",
  "origin_server_ts": 1549041175876,
  "sender": "@someone:example.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}
```

--------------------------------

### Matrix.to URI Examples

Source: https://matrix.org/docs/spec/appendices.html

Examples of matrix.to URIs used to reference Matrix objects like rooms, users, and groups. These URIs are percent-encoded.

```plaintext
https://matrix.to/#/%23somewhere%3Aexample.org
```

```plaintext
https://matrix.to/#/!somewhere%3Aexample.org
```

```plaintext
https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org
```

```plaintext
https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org
```

```plaintext
https://matrix.to/#/%40alice%3Aexample.org
```

```plaintext
https://matrix.to/#/%2Bexample%3Aexample.org
```

--------------------------------

### Device Keys Response Example

Source: https://matrix.org/docs/spec/server_server/latest.html

An example of a successful response when querying device keys. It includes encryption algorithms, device and user IDs, public keys, and signatures.

```json
{
  "device_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": {
        "algorithms": [
          "m.olm.v1.curve25519-aes-sha2",
          "m.megolm.v1.aes-sha2"
        ],
        "device_id": "JLAFKJWSCS",
        "keys": {
          "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
          "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
        },
        "signatures": {
          "@alice:example.com": {
            "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
          }
        },
        "unsigned": {
          "device_display_name": "Alice's mobile phone"
        },
        "user_id": "@alice:example.com"
      }
    }
  }
}
```

--------------------------------

### Query Server Keys Request Example

Source: https://matrix.org/docs/spec/server_server/latest.html

This JSON object is an example request body for the POST /_matrix/key/v2/query endpoint. It specifies which server keys to query.

```json
{
  "server_keys": {
    "example.org": {
      "ed25519:abc123": {
        "minimum_valid_until_ts": 1234567890
      }
    }
  }
}
```

--------------------------------

### Example Persistent Data Unit (PDU)

Source: https://matrix.org/docs/spec/rooms/v1

A standard example of a Persistent Data Unit (PDU) for Matrix room versions 1 and 2, illustrating the structure and typical fields.

```json
{
  "auth_events": [
    [
      "$af232176:example.org",
      {
        "sha256": "abase64encodedsha256hashshouldbe43byteslong"
      }
    ]
  ],
  "content": {
    "key": "value"
  },
  "depth": 12,
  "event_id": "$a4ecee13e2accdadf56c1025:example.com",
  "hashes": {
    "sha256": "thishashcoversallfieldsincasethisisredacted"
  },
  "origin_server_ts": 1404838188000,
  "prev_events": [
    [
      "$af232176:example.org",
      {
        "sha256": "abase64encodedsha256hashshouldbe43byteslong"
      }
    ]
  ],
  "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
  "sender": "@alice:example.com",
  "signatures": {
    "example.com": {
      "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
    }
  },
  "type": "m.room.message",
  "unsigned": {
    "age": 4612
  }
}
```

--------------------------------

### Canonical JSON Transformation Examples

Source: https://matrix.org/docs/spec/appendices.html

These examples demonstrate the transformation of various JSON objects into their canonical form, illustrating key sorting and formatting rules.

```json
{}

```

```json
{}

```

```json
{
    "one": 1,
    "two": "Two"
}

```

```json
{"one":1,"two":"Two"}

```

```json
{
    "b": "2",
    "a": "1"
}

```

```json
{"a":"1","b":"2"}

```

```json
{"b":"2","a":"1"}

```

```json
{"a":"1","b":"2"}

```

```json
{
    "auth": {
        "success": true,
        "mxid": "@john.doe:example.com",
        "profile": {
            "display_name": "John Doe",
            "three_pids": [
                {
                    "medium": "email",
                    "address": "john.doe@example.org"
                },
                {
                    "medium": "msisdn",
                    "address": "123456789"
                }
            ]
        }
    }
}

```

```json
{"auth":{"mxid":"@john.doe:example.com","profile":{"display_name":"John Doe","three_pids":[{"address":"john.doe@example.org","medium":"email"},{"address":"123456789","medium":"msisdn"}]},"success":true}}

```

```json
{
    "a": "日本語"
}

```

```json
{"a":"日本語"}

```

```json
{
    "本": 2,
    "日": 1
}

```

```json
{"日":1,"本":2}

```

```json
{
    "a": "\u65E5"
}

```

```json
{"a":"日"}

```

```json
{
    "a": null
}

```

```json
{"a":null}

```

--------------------------------

### Run the bot script

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Execute the bot script using Node.js. This command starts the bot and connects it to the Matrix homeserver.

```bash
node index.js

```

--------------------------------

### 200 OK Response Example

Source: https://matrix.org/docs/spec/server_server/latest.html

A successful response indicating the event was accepted by the receiving homeserver. This response is empty.

```json
{}
```

--------------------------------

### GET /_matrix/federation/v1/make_join/{roomId}/{userId}

Source: https://matrix.org/docs/spec/server_server/latest.html

Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room. Before signing the returned template and calling `/send_join`, the sending server MUST verify specific conditions.

```APIDOC
## GET /_matrix/federation/v1/make_join/{roomId}/{userId}

### Description
Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room. Before signing the returned template and calling `/send_join`, the sending server MUST verify that:
  * the `room_id` is equal to the `roomId` path parameter.
  * both the `sender` and `state_key` are equal to the `userId` path parameter.
  * the `type` of the event is `m.room.member`.
  * the `membership` field inside `content` is `join`.

In case any of the above checks fail, the response MUST be treated as malformed and discarded. The caller MAY try to join through another server.

### Method
GET

### Endpoint
`/_matrix/federation/v1/make_join/{roomId}/{userId}`

### Parameters
#### Path Parameters
- **roomId** (string) - Required - The room ID that is about to be joined.
- **userId** (string) - Required - The user ID the join event will be for. This MUST be a user ID on the origin server.

#### Query Parameters
- **ver** (string) - Optional - The room versions the sending server has support for. Defaults to `[1]`.

### Responses
#### Success Response (200)
- **event** (Event Template) - An unsigned template event. Note that events have a different format depending on the room version - check the room version specification for precise event formats.
- **room_version** (string) - The version of the room where the server is trying to join. If not provided, the room version is assumed to be either “1” or “2”.

### Request Example
```json
{
  "event": {
    "content": {
      "join_authorised_via_users_server": "@anyone:resident.example.org",
      "membership": "join"
    },
    "origin": "example.org",
    "origin_server_ts": 1549041175876,
    "room_id": "!somewhere:example.org",
    "sender": "@someone:example.org",
    "state_key": "@someone:example.org",
    "type": "m.room.member"
  },
  "room_version": "2"
}
```

### Error Responses
- **400** - The request is invalid, the room the server is attempting to join has a version that is not listed in the `ver` parameters, or the server was unable to validate restricted room conditions.
- **403** - The room that the joining server is attempting to join does not permit the user to join.
- **404** - The room that the joining server is attempting to join is unknown to the receiving server.
```

--------------------------------

### m.device_list_update EDU Example

Source: https://matrix.org/docs/spec/server_server/latest.html

An example of the m.device_list_update EDU payload sent between servers to notify about device list changes. This is crucial for E2E encryption to target the correct devices.

```json
{
  "content": {
    "device_display_name": "Mobile",
    "device_id": "QBUAZIFURK",
    "keys": {
      "algorithms": [
        "m.olm.v1.curve25519-aes-sha2",
        "m.megolm.v1.aes-sha2"
      ],
      "device_id": "JLAFKJWSCS",
      "keys": {
        "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
        "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
      },
      "signatures": {
        "@alice:example.com": {
          "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
        }
      },
      "user_id": "@alice:example.com"
    },
    "prev_id": [
      5
    ],
    "stream_id": 6,
    "user_id": "@john:example.com"
  },
  "edu_type": "m.device_list_update"
}
```

--------------------------------

### Get Homeserver Implementation Version

Source: https://matrix.org/docs/spec/server_server/latest.html

Retrieves the implementation name and version of the homeserver.

```APIDOC
## GET /_matrix/federation/v1/version

### Description
Get the implementation name and version of this homeserver.

### Method
GET

### Endpoint
`/_matrix/federation/v1/version`

### Parameters
No request parameters or request body.

### Responses
#### Success Response (200)
- **server** (Server) - An object containing the server's name and version.
  - **name** (string) - Arbitrary name that identify this implementation.
  - **version** (string) - Version of this implementation. The version format depends on the implementation.

### Request Example
```json
{
  "server": {
    "name": "My_Homeserver_Implementation",
    "version": "ArbitraryVersionNumber"
  }
}
```
```

--------------------------------

### Matrix Federation API: 200 Response Example

Source: https://matrix.org/docs/spec/server_server/latest.html

Example of a successful authentication chain response from the Matrix Federation API. The structure of PDUs in the auth chain can vary based on the room version.

```json
{
  "auth_chain": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}
```

--------------------------------

### Matrix Signing Key Update EDU

Source: https://matrix.org/docs/spec/server_server/latest.html

Example of an m.signing_key_update EDU used for server-to-server communication.

```json
{
  "content": {
    "master_key": {
      "keys": {
        "ed25519:base64+master+public+key": "base64+master+public+key"
      },
      "usage": [
        "master"
      ],
      "user_id": "@alice:example.com"
    },
    "self_signing_key": {
      "keys": {
        "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
      },
      "signatures": {
        "@alice:example.com": {
          "ed25519:base64+master+public+key": "signature+of+self+signing+key"
        }
      },
      "usage": [
        "self_signing"
      ],
      "user_id": "@alice:example.com"
    },
    "user_id": "@alice:example.com"
  },
  "edu_type": "m.signing_key_update"
}
```

--------------------------------

### Request Body Example for Signing Event

Source: https://matrix.org/docs/spec/server_server/latest.html

This is an example of the JSON body to be sent to the Policy Server to request a signature for an event. Ensure the event format adheres to the specified room version.

```json
{
  "content": {
    "see_room_version_spec": "The event format changes depending on the room version."
  },
  "room_id": "!somewhere:example.org",
  "type": "m.room.minimal_pdu"
}
```

--------------------------------

### 400 Incompatible Room Version Error

Source: https://matrix.org/docs/spec/server_server/latest.html

Example of a 400 response when the homeserver does not support the room version.

```json
{
  "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
  "error": "Your homeserver does not support the features required to join this room",
  "room_version": "3"
}
```

--------------------------------

### Example Signed JSON Object

Source: https://matrix.org/docs/spec/appendices.html

This JSON object demonstrates the structure after signing, including signing keys, unsigned data, and the signature itself.

```json
{
   "name": "example.org",
   "signing_keys": {
     "ed25519:1": "XSl0kuyvrXNj6A+7/tkrB9sxSbRi08Of5uRhxOqZtEQ"
   },
   "unsigned": {
      "age_ts": 922834800000
   },
   "signatures": {
      "example.org": {
         "ed25519:1": "s76RUgajp8w172am0zQb/iPTHsRnb4SkrzGoeCOSFfcBY2V/1c8QfrmdXHpvnc2jK5BD1WiJIxiMW95fMjK7Bw"
      }
   }
}

```

--------------------------------

### Request Body for Get Missing Events

Source: https://matrix.org/docs/spec/server_server/latest.html

Example JSON body for the POST /_matrix/federation/v1/get_missing_events/{roomId} request. Specifies the latest and earliest events to guide the search.

```json
{
  "earliest_events": [
    "$missing_event:example.org"
  ],
  "latest_events": [
    "$event_that_has_the_missing_event_as_a_previous_event:example.org"
  ],
  "limit": 10
}
```

--------------------------------

### 200 Response for Get Missing Events

Source: https://matrix.org/docs/spec/server_server/latest.html

Example JSON response for a successful retrieval of missing events. Contains a list of PDUs that were missing.

```json
{
  "events": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}
```

--------------------------------

### PDU DAG Example

Source: https://matrix.org/docs/spec/server_server/latest.html

Illustrates the Directed Acyclic Graph (DAG) structure of events within a room, showing how `prev_events` links events. A new event should include all known 'parent' events.

```text
E1
^
|
E2 <--- E5
^
|
E3      E6
^
|
E4

```

--------------------------------

### Get User Devices

Source: https://matrix.org/docs/spec/server_server/latest.html

Retrieves a list of devices associated with a given user ID, along with their encryption keys and cross-signing key information. This endpoint is crucial for understanding a user's security setup and for cryptographic operations.

```APIDOC
## GET /_matrix/client/v3/devices/{userId}

### Description
Retrieves a list of devices associated with a given user ID, along with their encryption keys and cross-signing key information.

### Method
GET

### Endpoint
/_matrix/client/v3/devices/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The user ID to retrieve devices for. Must be a user local to the receiving homeserver.

### Responses
#### Success Response (200)
- **devices** ([User Device]) - Required - The user’s devices. May be empty.
- **master_key** (CrossSigningKey) - The user's master signing key.
- **self_signing_key** (CrossSigningKey) - The user's self-signing key.
- **stream_id** (integer) - Required - A unique ID for a given user_id which describes the version of the returned device list. This is matched with the `stream_id` field in `m.device_list_update` EDUs in order to incrementally update the returned device_list.
- **user_id** (string) - Required - The user ID devices were requested for.

User Device Name | Type | Description
---|---|---
`device_display_name` | `string` | Optional display name for the device.
`device_id` | `string` | Required: The device ID.
`keys` | `DeviceKeys` | Required: Identity keys for the device.

DeviceKeys Name | Type | Description
---|---|---
`algorithms` | `[string]` | Required: The encryption algorithms supported by this device.
`device_id` | `string` | Required: The ID of the device these keys belong to. Must match the device ID used when logging in.
`keys` | `{string: string}` | Required: Public identity keys. The names of the properties should be in the format `<algorithm>:<device_id>`. The keys themselves should be encoded as specified by the key algorithm.
`signatures` | `{User ID: {string: string}}` | Required: Signatures for the device key object. A map from user ID, to a map from `<algorithm>:<device_id>` to the signature. The signature is calculated using the process described at Signing JSON.
`user_id` | `string` | Required: The ID of the user the device belongs to. Must match the user ID used when logging in.

CrossSigningKey Name | Type | Description
---|---|---
`keys` | `{string: string}` | Required: The public key. The object must have exactly one property, whose name is in the form `<algorithm>:<unpadded_base64_public_key>`, and whose value is the unpadded base64 public key.
`signatures` | `Signatures` | Signatures of the key, calculated using the process described at Signing JSON. Optional for the master signing key. Other keys must be signed by the user's master signing key.
`usage` | `[string]` | Required: What the key is for.
`user_id` | `string` | Required: The ID of the user the key belongs to.

### Request Example
```json
{
  "devices": [
    {
      "device_display_name": "Alice's Mobile Phone",
      "device_id": "JLAFKJWSCS",
      "keys": {
        "algorithms": [
          "m.olm.v1.curve25519-aes-sha2",
          "m.megolm.v1.aes-sha2"
        ],
        "device_id": "JLAFKJWSCS",
        "keys": {
          "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
          "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
        },
        "signatures": {
          "@alice:example.com": {
            "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
          }
        },
        "user_id": "@alice:example.com"
      }
    }
  ],
  "master_key": {
    "keys": {
      "ed25519:base64+master+public+key": "base64+master+public+key"
    },
    "usage": [
      "master"
    ],
    "user_id": "@alice:example.com"
  },
  "self_signing_key": {
    "keys": {
      "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
    },
    "signatures": {
      "@alice:example.com": {
        "ed25519:base64+master+public+key": "signature+of+self+signing+key"
      }
    },
    "usage": [
      "self_signing"
    ],
    "user_id": "@alice:example.com"
  },
  "stream_id": 5,
  "user_id": "@alice:example.org"
}
```
```

--------------------------------

### Instantiate Matrix Client

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Create a new MatrixClient instance using the configured homeserver URL, access token, and storage provider.

```javascript
const client = new MatrixClient(homeserverUrl, accessToken, storage);

```

--------------------------------

### Get User Devices

Source: https://matrix.org/docs/spec/server_server/latest.html

Gets information on all of the user’s devices. This is critical for reliable end-to-end encryption and to-device messaging.

```APIDOC
## GET /_matrix/federation/v1/user/devices/{userId}

### Description
Gets information on all of the user’s devices. This is critical for reliable end-to-end encryption and to-device messaging.

### Method
GET

### Endpoint
/_matrix/federation/v1/user/devices/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user whose devices to retrieve.

### Responses
#### Success Response (200)
Details of the user's devices.

#### Error Response (401)
Indicates that authentication is required and has failed or is missing.
```

--------------------------------

### Configure storage provider

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Initialize the SimpleFsStorageProvider for storing bot data. The SDK will create a 'bot.json' file to manage this data.

```javascript
const storage = new SimpleFsStorageProvider("bot.json");

```

--------------------------------

### 403 Forbidden Response Example

Source: https://matrix.org/docs/spec/server_server/latest.html

Example of a 403 error response indicating that the calling server is not authorized to request a signature from the Policy Server.

```json
{
  "errcode": "M_FORBIDDEN",
  "error": "Your server is not allowed to request a signature."
}
```

--------------------------------

### 400 Bad Request Response Example

Source: https://matrix.org/docs/spec/server_server/latest.html

An example of a bad request response, indicating the event is invalid. This includes an error code and a human-readable message.

```json
{
  "errcode": "M_INVALID_PARAM",
  "error": "Not a leave event."
}
```

--------------------------------

### 200 Response for Server Keys Query

Source: https://matrix.org/docs/spec/server_server/latest.html

Example of a successful response when querying for server keys. Includes old and current verification keys, server name, and signatures.

```json
{
  "server_keys": [
    {
      "old_verify_keys": {
        "ed25519:0ldk3y": {
          "expired_ts": 1532645052628,
          "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
        }
      },
      "server_name": "example.org",
      "signatures": {
        "example.org": {
          "ed25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
        },
        "notary.server.com": {
          "ed25519:010203": "VGhpcyBpcyBhbm90aGVyIHNpZ25hdHVyZQ"
        }
      },
      "valid_until_ts": 1652262000000,
      "verify_keys": {
        "ed25519:abc123": {
          "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
        }
      }
    }
  ]
}
```

--------------------------------

### Example Matrix Room Alias

Source: https://matrix.org/docs/matrix-concepts/rooms_and_events

Demonstrates the format of a human-readable alias for a Matrix room. Aliases are composed of a room name and a server part.

```text
#goodfriends:example.com

```

--------------------------------

### 200 OK Response Example

Source: https://matrix.org/docs/spec/server_server/latest.html

A successful response from the Policy Server, containing the server's signature for the event. The signature is prefixed with the algorithm used, e.g., `ed25519:policy_server`.

```json
{
  "policy.example.org": {
    "ed25519:policy_server": "zLFxllD0pbBuBpfHh8NuHNaICpReF/PAOpUQTsw+bFGKiGfDNAsnhcP7pbrmhhpfbOAxIdLraQLeeiXBryLmBw"
  }
}
```

--------------------------------

### Request Body Example for Send Knock

Source: https://matrix.org/docs/spec/server_server/latest.html

This is an example of the JSON request body for the send_knock endpoint. It includes the knock event details and origin server information.

```json
{
  "content": {
    "membership": "knock"
  },
  "origin": "example.org",
  "origin_server_ts": 1549041175876,
  "sender": "@someone:example.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}
```

--------------------------------

### Room Alias to Room ID Mapping Example

Source: https://matrix.org/docs/spec

Illustrates how a server maps room aliases to their corresponding room IDs and provides a list of servers that can be used for joining.

```plaintext
HTTP GET
#matrix:example.org      !aaabaa:matrix.org
       |
       |
_______V____________________|
|          example.org           |
| Mappings:
| #matrix >> !aaabaa:matrix.org  |
| #golf   >> !wfeiofh:sport.com  |
| #bike   >> !4rguxf:matrix.org  |
|________________________________|
```

--------------------------------

### GET /_matrix/federation/v1/hierarchy/{roomId}

Source: https://matrix.org/docs/spec/server_server/latest.html

Retrieves the hierarchy of a space room and its children from a federated server. This endpoint is the federation equivalent of the Client-Server API’s GET /hierarchy endpoint but does not paginate.

```APIDOC
## GET /_matrix/federation/v1/hierarchy/{roomId}

### Description
Federation version of the Client-Server `GET /hierarchy` endpoint. Unlike the Client-Server API version, this endpoint does not paginate. Instead, all the space-room’s children the requesting server could feasibly peek/join are returned. The requesting server is responsible for filtering the results further down for the user’s request. Only `m.space.child` state events of the room are considered. Invalid child rooms and parent events are not covered by this endpoint. Responses to this endpoint should be cached for a period of time.

### Method
GET

### Endpoint
`/_matrix/federation/v1/hierarchy/{roomId}`

### Parameters
#### Path Parameters
- **roomId** (string) - Required - The room ID of the space to get a hierarchy for.

#### Query Parameters
- **suggested_only** (boolean) - Optional - A flag to indicate whether or not the server should only consider suggested rooms. Suggested rooms are annotated in their `m.space.child` event contents. Defaults to `false`.

### Responses
#### Success Response (200)
- **chunk** ([PublishedRoomsChunk]) - A paginated chunk of published rooms.
- **next_batch** (string) - A pagination token for the response. The absence of this token means there are no more results to fetch and the client should stop paginating.
- **prev_batch** (string) - A pagination token that allows fetching previous results. The absence of this token means there are no results before this batch, i.e. this is the first batch.
- **total_room_count_estimate** (integer) - An estimate on the total number of published rooms, if the server has an estimate.

#### Error Response (404)
The room is not known to the server or the requesting server is unable to peek/join it (if it were to attempt this).

### Request Example
```json
{
  "chunk": [
    {
      "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
      "guest_can_join": false,
      "join_rule": "public",
      "name": "CHEESE",
      "num_joined_members": 37,
      "room_id": "!ol19s:bleecker.street",
      "room_type": "m.space",
      "topic": "Tasty tasty cheese",
      "world_readable": true
    }
  ],
  "next_batch": "p190q",
  "prev_batch": "p1902",
  "total_room_count_estimate": 115
}
```

### Response Example
```json
{
  "chunk": [
    {
      "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
      "guest_can_join": false,
      "join_rule": "public",
      "name": "CHEESE",
      "num_joined_members": 37,
      "room_id": "!ol19s:bleecker.street",
      "room_type": "m.space",
      "topic": "Tasty tasty cheese",
      "world_readable": true
    }
  ],
  "next_batch": "p190q",
  "prev_batch": "p1902",
  "total_room_count_estimate": 115
}
```
```

--------------------------------

### Import SDK components

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Import the necessary components from the matrix-bot-sdk for client instantiation and storage.

```javascript
const sdk = require("matrix-bot-sdk");
const MatrixClient = sdk.MatrixClient;
const SimpleFsStorageProvider = sdk.SimpleFsStorageProvider;
const AutojoinRoomsMixin = sdk.AutojoinRoomsMixin;

```

--------------------------------

### 400 Bad Request Response Example

Source: https://matrix.org/docs/spec/server_server/latest.html

Example of a 400 error response when the Policy Server refuses to sign the event due to invalid formatting or content. The `errcode` field indicates the specific reason.

```json
{
  "errcode": "M_FORBIDDEN",
  "error": "The message appears to contain possible spam"
}
```

--------------------------------

### Start TypeScript Watch Mode

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Start the TypeScript compiler in watch mode to automatically recompile TypeScript files to JavaScript whenever changes are detected. Use this command in your project's root directory.

```bash
npx tsc --watch *.ts

```

--------------------------------

### Matrix Federation API: Ephemeral Data Unit (EDU) Example

Source: https://matrix.org/docs/spec/server_server/latest.html

Example of an Ephemeral Data Unit (EDU) used for non-persistent data like presence or typing notifications. EDUs do not have an ID or room ID.

```json
{
  "content": {
    "key": "value"
  },
  "edu_type": "m.presence"
}
```

--------------------------------

### Inviting to a Room

Source: https://matrix.org/docs/spec/server_server/latest.html

Explains the process of inviting users to a room, including considerations for same-homeserver and different-homeserver invitations, and the handling of invite events.

```APIDOC
## Inviting to a room

### Description
This section outlines the process for inviting users to a Matrix room. It covers scenarios where users are on the same or different homeservers and details the requirements for membership events, particularly regarding room versions and validation.

### Notes
- When inviting a user on the same homeserver, the homeserver may sign the membership event itself.
- For invites to users on different homeservers, a request to the target homeserver is required to sign and verify the event.
- Invites are used to indicate that knocks were accepted. Receiving servers should link previous knocks to invites if the invite event does not directly reference the knock.
- `invite_room_state` entries must be formatted according to the room's version.
- Servers should warn about invites failing validation for room versions 1-11 rather than erroring, to aid migration.
- Invites to other room versions failing validation should result in an error.
- Server migration to support new room version specifications is suggested to be completed by January 2026, but can be extended.
```

--------------------------------

### Event Graph Example

Source: https://matrix.org/docs/spec/server_server/latest.html

Illustrates a scenario where an event C is soft-failed due to a preceding ban event B, and how a subsequent event D referencing both B and C is handled.

```text
  A
 / 
B

```

```text
  A
 / \
B   C

```

```text
  A
 / \
B   C
 \ /
  D

```

```text
  A
 / \
B   C
| 
D' 

```

--------------------------------

### Example Matrix Event JSON

Source: https://matrix.org/docs/matrix-concepts/rooms_and_events

Illustrates the structure of a typical Matrix event, including content, sender, room ID, and type. This format is used for all actions within a room.

```json
{
  "content": {
    "body": "This is an example text message",
    "format": "org.matrix.custom.html",
    "formatted_body": "<b>This is an example text message</b>",
    "msgtype": "m.text"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "type": "m.room.message",
  "unsigned": {
    "age": 1234
  }
}

```

--------------------------------

### GET /_matrix/federation/v1/event/{eventId}

Source: https://matrix.org/docs/spec/server_server/latest.html

Retrieves a single event by its ID.

```APIDOC
## GET /_matrix/federation/v1/event/{eventId}

### Description
Retrieves a single event by its ID.

### Method
GET

### Endpoint
/_matrix/federation/v1/event/{eventId}

### Parameters
#### Path Parameters
- **eventId** (string) - Required - The event ID to get.

### Response
#### Success Response (200)
- **origin** (string) - Required - The `server_name` of the homeserver sending this transaction.
- **origin_server_ts** (integer) - Required - POSIX timestamp in milliseconds on originating homeserver when this transaction started.
- **pdus** (array of PDUs) - Required - A single PDU. Note that events have a different format depending on the room version - check the room version specification for precise event formats.

#### Response Example
```json
{
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "pdus": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}
```
```