Skip to content

Commit

Permalink
- Fix Room Pagination node event data being unaccessible #28
Browse files Browse the repository at this point in the history 
- Add new node `Get Event` that will give you room data for a corresponding roomId and eventId #117
- Add new node `Fetch Event Relations` that can paginate through events related to another event #119
- README updates
  • Loading branch information
@skylord123
skylord123 committed Sep 17, 2024
1 parent 6bbd1d5 commit 02826e2
Show file tree
Hide file tree
Showing 9 changed files with 623 additions and 243 deletions.
87 changes: 42 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,75 +1,72 @@
# node-red-contrib-matrix-chat
[Matrix](https://matrix.org/) chat server client for [Node-RED](https://nodered.org/)

***Currently we are in beta. We ask that you open any issues you have on our repository to help us reach a stable well tested version. Things may change & break before our first release so check changelog before updating.***
***Currently in beta. Please report any issues in our repository to help us reach a stable, well-tested release. Breaking changes may occur before our first stable release, so be sure to check the changelog before updating.***

If you need help with this feel free to join our public matrix room at [#node-red-contrib-matrix-chat:skylar.tech](https://app.element.io/#/room/#node-red-contrib-matrix-chat:skylar.tech)
Join our public Matrix room for help: [#node-red-contrib-matrix-chat:skylar.tech](https://app.element.io/#/room/#node-red-contrib-matrix-chat:skylar.tech)

### Features

The following is supported from this package:

- End-to-end encryption
- [Currently a WIP](#end-to-end-encryption-notes)
- Can also use [pantalaimon](https://github.com/matrix-org/pantalaimon) as an alternative solution to E2EE (if you need multiple sessions synced up with keys)
- Receive events from a room (messages, reactions, images, audio, locations, and files) whether encrypted or not
- Fetch and modify room state events (for changing room settings)
- Paginate room history
- Send Images/Files (sending files to e2ee room doesn't currently encrypt them yet)
- Edit messages
- Send typing events (Bot is typing ...)
- Delete events (messages, reactions, etc)
- Decrypt files in e2ee rooms
- Send HTML/Plain Text Message/Notice
- React to messages
- Register user's on closed registration Synapse servers using `registration_shared_secret` (Admin Only)
- List out users on a Synapse server (Admin Only)
- Get WhoIs info for a Synapse user (Admin Only)
- Add/Edit Synapse users using the v2 API (requires a pre-existing admin account)
- Deactivate users on Synapse servers (Admin Only)
- Get a user list from a room
- Kick user from room
- Ban user from room
- Join, Create, Invite, and Leave rooms
- Synapse admin API to force add user to room (requires bot to be in same room already)


Therefore, you can easily build a bot, chat relay, or administrate your Matrix server from within [Node-RED](https://nodered.org/).
Supported functionality in this package includes:

- **End-to-end encryption (E2EE)**
- [Work in progress](#end-to-end-encryption-notes)
- Alternative: Use [Pantalaimon](https://github.com/matrix-org/pantalaimon) for E2EE key synchronization across sessions
- **Receive events** from rooms: Messages, reactions, images, audio, locations, files, encrypted or unencrypted
- **Fetch/modify room state**: Update room settings
- **Paginate room history**
- **Send files** (encryption support for files coming soon)
- **Send/edit messages** (supports plain text and HTML formats)
- **Send typing notifications**
- **Delete events** (messages, reactions, etc.)
- **Decrypt files** in E2EE rooms
- **React to messages**
- **Admin tools**:
- Register users on closed Synapse servers (`registration_shared_secret`)
- Manage users, including listing, adding, editing, deactivating (Synapse API)
- Force-add users to rooms
- **Room management**: Invite, kick, ban, join, create, and leave rooms

These features allow you to easily build bots, set up chat relays, or even administrate your Matrix server directly from [Node-RED](https://nodered.org/).

### Installing

You can either install from within Node-RED by searching for `node-red-contrib-matrix-chat` or run this from within your Node-RED directory:
Install through Node-RED's UI by searching for `node-red-contrib-matrix-chat`, or use the following command inside your Node-RED directory:

```bash
npm install node-red-contrib-matrix-chat
```

### Usage
We have examples! [Check them out](https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/tree/master/examples#readme)

#### Extra functionality
You are not limited by just the nodes we have created. If you turn on global access when setting up your Matrix Client you can access the client directly from any function node to write your own logic.
Explore our [examples](https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/tree/master/examples#readme) to see the module in action.

View an example [here](https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/tree/master/examples#use-function-node-to-run-any-command)
#### Extending functionality

### End-to-End Encryption Notes
Currently, this module has no way of getting encryption keys from other devices on the same account. Therefore it is recommended you use the bot exclusively with Node-RED after it's creation. Failure to do so will lead to your bot being unable to receive messages from e2ee rooms it joined from another client. Shared secret registration makes this super easy since it returns a token and device ID.
You're not limited to just the nodes we've created. Enable global access in your Matrix Client to directly interact with the client from function nodes and create custom logic.

This module stores a folder in your Node-RED directory called `matrix-client-storage` and is it vital that you periodically back this up if you are using e2ee. This is where the client stores all the keys necessary to decrypt messages and if lost you will lose access to e2e rooms. If you move your client to another NR install make sure to migrate this folder as well (and do not let both the old and new client run at same time).
[View an example here](https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/tree/master/examples#use-function-node-to-run-any-command).

Want to contribute? Any help on getting the last pieces of e2ee figured out would be greatly appreciated :)
### End-to-End Encryption Notes

### Generate user
You will need a user to use this module. Luckily this module comes with a node that allows you to register users to a homeserver using the secret registration endpoint. This is perfect because it returns an `access_token` as well as a `device_id` which is exactly what we need.
- This module doesn't handle encryption key synchronization between devices. It’s recommended to use the bot exclusively in Node-RED to prevent issues with E2EE messages.
- **Storage:** Keys for E2EE are saved in a folder called `matrix-client-storage` within your Node-RED directory. Back up this folder regularly! If lost, you won’t be able to decrypt messages from E2EE rooms.
- To move your bot to a different installation, migrate this folder and ensure the old and new clients don't run simultaneously.

[Click here](https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/tree/master/examples#readme) to see how to generate a user using secret registration
Interested in helping? Contributions to finalize E2EE support are welcome!

### Registering a User

This module includes a node to register users using the Synapse secret registration endpoint. It returns both an `access_token` and a `device_id`, perfect for setting up the bot.

[See how to register a user here](https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/tree/master/examples#readme).

### Other Packages

- [node-red-contrib-gamedig](https://www.npmjs.com/package/node-red-contrib-gamedig) - Query game servers from Node-RED!
- [node-red-contrib-gamedig](https://www.npmjs.com/package/node-red-contrib-gamedig) - Query game servers from Node-RED.

### Contributing
All contributions are welcome! If you do add a feature please do a pull request so that everyone benefits :)

Sharing is caring!
We welcome all contributions! Please submit a pull request if you add a feature so the whole community can benefit.

**Sharing is caring!**
5 changes: 4 additions & 1 deletion examples/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -264,4 +264,7 @@ If you say "force_join @test:example.com !320j90mf0394f:example.com" the bot wil

Note: This requires the bot to be a server admin. This also only works for rooms on the same server.

![room-kick-ban.png](force-join-room.png)
![room-kick-ban.png](force-join-room.png)

### Paginate room history

4 changes: 3 additions & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,9 @@
"matrix-synapse-deactivate-user": "src/matrix-synapse-deactivate-user.js",
"matrix-synapse-join-room": "src/matrix-synapse-join-room.js",
"matrix-whois-user": "src/matrix-whois-user.js",
"matrix-paginate-room": "src/matrix-paginate-room.js"
"matrix-paginate-room": "src/matrix-paginate-room.js",
"matrix-get-event": "src/matrix-get-event.js",
"matrix-event-relations": "src/matrix-event-relations.js"
}
},
"engines": {
Expand Down
230 changes: 230 additions & 0 deletions src/matrix-event-relations.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,230 @@
<script type="text/javascript">
RED.nodes.registerType('matrix-fetch-relations', {
category: 'matrix',
color: '#00b7ca',
icon: "matrix.png",
outputLabels: ["Related Events", "Error"],
inputs: 1,
outputs: 2,
defaults: {
name: { value: null },
server: { type: "matrix-server-config" },
roomType: { value: "msg" },
roomValue: { value: "topic" },
eventIdType: { value: "msg" },
eventIdValue: { value: "eventId" },
relationTypeType: { value: "json" },
relationTypeValue: { value: "null" },
eventTypeType: { value: "json" },
eventTypeValue: { value: "null" },
directionType: { value: "str" },
directionValue: { value: "b" },
limitType: { value: "json" },
limitValue: { value: "null" },
recurseType: { value: "bool" },
recurseValue: { value: "false" },
fromType: { value: "msg" },
fromValue: { value: "payload.next_batch" },
toType: { value: "json" },
toValue: { value: "null" },
},
label: function () {
return this.name || "Fetch Event Relations";
},
paletteLabel: 'Fetch Event Relations',
oneditprepare: function () {
$("#node-input-room").typedInput({
type: this.roomType,
types: ['msg', 'flow', 'global', 'str'],
})
.typedInput('value', this.roomValue)
.typedInput('type', this.roomType);

$("#node-input-eventId").typedInput({
types: ['msg', 'flow', 'global', 'str'],
})
.typedInput('value', this.eventIdValue)
.typedInput('type', this.eventIdType);

$("#node-input-relationType").typedInput({
types: ['msg', 'flow', 'global', 'str', 'json'],
})
.typedInput('value', this.relationTypeValue)
.typedInput('type', this.relationTypeType);

$("#node-input-eventType").typedInput({
types: ['msg', 'flow', 'global', 'str', 'json'],
})
.typedInput('value', this.eventTypeValue)
.typedInput('type', this.eventTypeType);

$("#node-input-direction").typedInput({
types: ['msg', 'flow', 'global', 'str'],
})
.typedInput('value', this.directionValue)
.typedInput('type', this.directionType);

$("#node-input-limit").typedInput({
types: ['msg', 'flow', 'global', 'num', 'json'],
})
.typedInput('value', this.limitValue)
.typedInput('type', this.limitType);

$("#node-input-recurse").typedInput({
types: ['msg', 'flow', 'global', 'bool', 'json'],
})
.typedInput('value', this.recurseValue)
.typedInput('type', this.recurseType);

$("#node-input-from").typedInput({
types: ['msg', 'flow', 'global', 'str', 'json'],
})
.typedInput('value', this.fromValue)
.typedInput('type', this.fromType);

$("#node-input-to").typedInput({
types: ['msg', 'flow', 'global', 'str', 'json'],
})
.typedInput('value', this.toValue)
.typedInput('type', this.toType);
},
oneditsave: function () {
this.roomType = $("#node-input-room").typedInput('type');
this.roomValue = $("#node-input-room").typedInput('value');
this.eventIdType = $("#node-input-eventId").typedInput('type');
this.eventIdValue = $("#node-input-eventId").typedInput('value');
this.relationTypeType = $("#node-input-relationType").typedInput('type');
this.relationTypeValue = $("#node-input-relationType").typedInput('value');
this.eventTypeType = $("#node-input-eventType").typedInput('type');
this.eventTypeValue = $("#node-input-eventType").typedInput('value');
this.directionType = $("#node-input-direction").typedInput('type');
this.directionValue = $("#node-input-direction").typedInput('value');
this.limitType = $("#node-input-limit").typedInput('type');
this.limitValue = $("#node-input-limit").typedInput('value');
this.recurseType = $("#node-input-recurse").typedInput('type');
this.recurseValue = $("#node-input-recurse").typedInput('value');
this.fromType = $("#node-input-from").typedInput('type');
this.fromValue = $("#node-input-from").typedInput('value');
this.toType = $("#node-input-to").typedInput('type');
this.toValue = $("#node-input-to").typedInput('value');
}
});
</script>

<script type="text/html" data-template-name="matrix-fetch-relations">
<div class="form-row">
<label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
<input type="text" id="node-input-name" placeholder="Name">
</div>

<div class="form-row">
<label for="node-input-server"><i class="fa fa-server"></i> Matrix Server</label>
<input type="text" id="node-input-server">
</div>

<div class="form-row">
<label for="node-input-room"><i class="fa fa-comments"></i> Room</label>
<input type="text" id="node-input-room">
</div>

<div class="form-row">
<label for="node-input-eventId"><i class="fa fa-key"></i> Event ID</label>
<input type="text" id="node-input-eventId">
<div class="form-tips" style="margin-top: 10px;">The event ID for which relations are being fetched.</div>
</div>

<div class="form-row">
<label for="node-input-relationType"><i class="fa fa-link"></i> Relation Type</label>
<input type="text" id="node-input-relationType">
<div class="form-tips" style="margin-top: 10px;">The type of relations (e.g., m.in_reply_to, m.replace, m.annotation, m.thread, m.reference) to be fetched for the event. You can read more in the <a href="https://spec.matrix.org/v1.11/client-server-api/#relationship-types" target="_blank">Matrix specification</a>.</div>
</div>

<div class="form-row">
<label for="node-input-eventType"><i class="fa fa-file"></i> Event Type</label>
<input type="text" id="node-input-eventType">
<div class="form-tips" style="margin-top: 10px;">The type of event (e.g., m.reaction, m.annotation) to be retrieved.</div>
</div>

<div class="form-row">
<label for="node-input-direction"><i class="fa fa-arrow-left"></i> Direction</label>
<input type="text" id="node-input-direction">
<div class="form-tips" style="margin-top: 10px;">Set the direction of pagination. Can be "b" for backwards or "f" for forwards. Defaults to "b".</div>
</div>

<div class="form-row">
<label for="node-input-limit"><i class="fa fa-arrow-left"></i> Limit</label>
<input type="text" id="node-input-limit">
<div class="form-tips" style="margin-top: 10px;">The maximum number of results to return in a single chunk. Recommended to leave as null to use the server default.</div>
</div>

<div class="form-row">
<label for="node-input-recurse"><i class="fa fa-arrow-left"></i> Recurse</label>
<input type="text" id="node-input-recurse">
<div class="form-tips" style="margin-top: 10px;">
Whether to additionally include events which only relate indirectly to the given event, i.e. events related to the given event via two or more direct relationships.
<br><br>
If set to false, only events which have a direct relation with the given event will be included.
<br><br>
If set to true, events which have an indirect relation with the given event will be included additionally up to a certain depth level. Homeservers SHOULD traverse at least 3 levels of relationships. Implementations MAY perform more but MUST be careful to not infinitely recurse.
<br><br>
The default value is false.
<br><br>
Added in v1.10
</div>
</div>

<div class="form-row">
<label for="node-input-from"><i class="fa fa-arrow-left"></i> From</label>
<input type="text" id="node-input-from">
<div class="form-tips" style="margin-top: 10px;">
The pagination token to start returning results from. If not supplied, results start at the most recent topological event known to the server.
<br><br>
Can be a next_batch or prev_batch token from a previous call, or a returned start token from /messages, or a next_batch token from /sync.
<br><br>
Defaults to msg.payload.next_batch to easily fetch the next batch in a recursive loop.
</div>
</div>

<div class="form-row">
<label for="node-input-to"><i class="fa fa-arrow-left"></i> To</label>
<input type="text" id="node-input-to">
<div class="form-tips" style="margin-top: 10px;">
The pagination token to stop returning results at. If not supplied, results continue up to limit or until there are no more events.
<br><br>
Like from, this can be a previous token from a prior call to this endpoint or from /messages or /sync.
</div>
</div>
</script>

<script type="text/html" data-help-name="matrix-fetch-relations">
<p>
The Matrix Fetch Relations node allows you to retrieve event relations for a specific event within a Matrix room.
</p>

<h3>Inputs</h3>
<ul>
<li><strong>msg</strong> (<em>default</em>): Triggers the fetching of relations based on the provided parameters.</li>
</ul>

<h3>Outputs</h3>
<ul>
<li>
<strong>Output 1 (Related Events)</strong>: Returns an array of events with their relations.
Each event contains details such as:
<ul>
<li><code>msg.payload.chunk</code> - Array of related events.</li>
<li><code>msg.payload.prev_batch</code> - The previous batch token for pagination.</li>
<li><code>msg.payload.next_batch</code> - The next batch token for pagination.</li>
</ul>
</li>
<li>
<strong>Output 2 (Error)</strong>: If an error occurs during the fetch process, the error message is sent to this output.
</li>
</ul>

<h3>Dynamic Properties</h3>
<p>Properties such as <strong>Room ID</strong>, <strong>Event ID</strong>, <strong>Relation Type</strong>, and <strong>Event Type</strong> can be dynamically set using message, flow, or global context variables.</p>

<h3>Usage</h3>
<p>To fetch event relations, trigger this node with a <code>msg</code> input. The node will fetch the relations for the given event ID and return the related events.</p>
</script>
Loading

0 comments on commit 02826e2

Please sign in to comment.