79 lines
2.5 KiB
Markdown
79 lines
2.5 KiB
Markdown
|
# matrix-events-sdk
|
||
|
|
|
||
|
|
JS/TS SDK for handling (extensible) events in Matrix
|
||
|
|
|
||
|
|
## 🚨🚨 Project is a work in progress
|
||
|
|
|
||
|
|
The architecture and approach of this repo is still being considered and is subject to breaking
|
||
|
|
changes. Use at your own risk.
|
||
|
|
|
||
|
|
As a general guide, functionality which is foundational to events (such as text, images, etc)
|
||
|
|
should be incorporated in this repo before the more complex types. This is to ensure that the
|
||
|
|
architecture is up to the task of handling proper extensible events.
|
||
|
|
|
||
|
|
## Usage: Parsing events
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
const parsed = ExtensibleEvents.parse({
|
||
|
|
type: "m.room.message",
|
||
|
|
content: {
|
||
|
|
"msgtype": "m.text",
|
||
|
|
"body": "Hello world!"
|
||
|
|
},
|
||
|
|
// and other fields
|
||
|
|
}) as MessageEvent;
|
||
|
|
|
||
|
|
// Using instanceof can be unsafe in some cases, but casting the
|
||
|
|
// response in TypeScript (as above) should be safe given this
|
||
|
|
// if statement will block non-message types anyhow.
|
||
|
|
if (parsed?.isEquivalentTo(M_MESSAGE)) {
|
||
|
|
console.log(parsed.text);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
*Note*: `instanceof` isn't considered safe for projects which might be running multiple copies
|
||
|
|
of the library, such as in clients which have layers needing access to the events-sdk individually.
|
||
|
|
|
||
|
|
If you would like to register your own handling of events, use the following:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
type MyContent = M_MESSAGE_EVENT_CONTENT & {
|
||
|
|
field: string;
|
||
|
|
};
|
||
|
|
|
||
|
|
class MyEvent extends MessageEvent {
|
||
|
|
public readonly field: string;
|
||
|
|
|
||
|
|
constructor(wireFormat: IPartialEvent<MyContent>) {
|
||
|
|
// Parse the text bit of the event
|
||
|
|
super(wireFormat);
|
||
|
|
|
||
|
|
this.field = wireFormat.content?.field;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
function parseMyEvent(wireEvent: IPartialEvent<MyContent>): Optional<MyEvent> {
|
||
|
|
// If you need to convert a legacy format, this is where you'd do it. Your
|
||
|
|
// event class should be able to be instatiated outside of this parse function.
|
||
|
|
return new MyEvent(wireEvent);
|
||
|
|
}
|
||
|
|
|
||
|
|
ExtensibleEvents.registerInterpreter("org.example.my_event_type", parseMyEvent);
|
||
|
|
ExtensibleEvents.unknownInterpretOrder.push("org.example.my_event_type");
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage: Making events
|
||
|
|
|
||
|
|
Most event objects have a `from` static function which takes common details of an event
|
||
|
|
and returns an instance of that event for later serialization.
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
const userInput = "**hello**";
|
||
|
|
const htmlInput = "<b>hello</b>"; // might be after running through a markdown processor
|
||
|
|
|
||
|
|
const message = MessageEvent.from(userInput, htmlInput).serialize();
|
||
|
|
|
||
|
|
// Finally, assuming your client instance is called `client`:
|
||
|
|
client.sendEvent(message.type, message.content);
|
||
|
|
```
|