summaryrefslogtreecommitdiff
path: root/includes/external/matrix/node_modules/matrix-events-sdk/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'includes/external/matrix/node_modules/matrix-events-sdk/README.md')
-rw-r--r--includes/external/matrix/node_modules/matrix-events-sdk/README.md78
1 files changed, 78 insertions, 0 deletions
diff --git a/includes/external/matrix/node_modules/matrix-events-sdk/README.md b/includes/external/matrix/node_modules/matrix-events-sdk/README.md
new file mode 100644
index 0000000..dc93b5a
--- /dev/null
+++ b/includes/external/matrix/node_modules/matrix-events-sdk/README.md
@@ -0,0 +1,78 @@
+# 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);
+```