@matrix-widget-toolkit/api 1.0.1

package/README.md

@@ -0,0 +1,148 @@
+# `@matrix-widget-toolkit/api`
+
+This is package that wraps `matrix-widget-api` to provide a more convenient API.
+For now, the API includes:
+
+- A `WidgetApi` interface with more advanced features.
+- Helper functions for registering the Widget in rooms.
+- Types and helper functions for common events, like power levels, room members, redactions, and relations.
+
+## Usage
+
+Install it with:
+
+```bash
+yarn add @matrix-widget-toolkit/api
+```
+
+### Creating a `WidgetApi` instance
+
+Creating the `WidgetApi` instance should be done as early as possible in your code because otherwise the widget misses the connection estabilshment by the widget host (especially on Safari).
+
+```typescript
+import { WidgetApiImpl } from '@matrix-widget-toolkit/api';
+
+const widgetApi = await WidgetApiImpl.create();
+```
+
+### Request capabilities
+
+You can request additional capabilities at any time using `requestCapabilities()`.
+A call returns a promise that resolves once the user approved the capabilities.
+
+```typescript
+import { WidgetEventCapability } from 'matrix-widget-api';
+
+await widgetApi.requestCapabilities([
+  WidgetEventCapability.forStateEvent(
+    EventDirection.Send,
+    STATE_EVENT_POWER_LEVELS
+  ),
+]);
+```
+
+### Receiving state events
+
+You can read state events once from the current room using `receiveStateEvents()`:
+
+```typescript
+const events = await widgetApi.receiveStateEvents(STATE_EVENT_ROOM_NAME);
+
+// events is an array of state events
+```
+
+> **Warning** Don't assume the type of the returned events, always validate that they have the expected schema.
+
+### Observing state event changes
+
+You can listen to state event changes using `observeStateEvents()`.
+Note that the initial state is also returned.
+
+```typescript
+const subscription = widgetApi
+  .observeStateEvents(STATE_EVENT_POWER_LEVELS)
+  .subscribe(async (event) => {
+    // The callback is always called if a state event changes
+  });
+
+// Don't forget to unsubscribe later
+subscription.unsubscribe();
+```
+
+### Sending state events
+
+You can send state events using `sendStateEvent()`.
+It returns a promise that resolves once the event has been sent.
+
+```typescript
+await widgetApi.sendStateEvent('m.room.topic', {
+  topic: 'A brief description',
+});
+```
+
+> **Warning** Avoid sending event content that has no changes, as the returned promise doesn't resolve in this case.
+
+### Receiving room events
+
+You can read the current room events using `receiveRoomEvents()`.
+Note that this API only returns the events that are currently in the view of the client.
+There is no guarantees to read all events from the room.
+Therefore this function is of limited use.
+For more details and solutions, see [MSC3869](https://github.com/nordeck/matrix-spec-proposals/blob/nic/feat/widgetapi-read-relations/proposals/3869-widgetapi-read-event-relations.md).
+
+```typescript
+const events = await widgetApi.receiveRoomEvents('com.example.test');
+
+// events is an array of room events
+```
+
+### Observing room events
+
+You can listen to room events using `observeRoomEvents()`.
+
+```typescript
+const subscription = widgetApi
+  .observeRoomEvents(ROOM_EVENT_REACTION)
+  .subscribe(async (event) => {
+    // Callback is called every time a room event is received
+  });
+
+// Don't forget to unsubscribe later
+subscription.unsubscribe();
+```
+
+### Sending room events
+
+You can send room events using `sendRoomEvent()`.
+It returns a promise that resolves once the event has been sent.
+
+```typescript
+await widgetApi.sendRoomEvent('m.room.redaction', {
+  redacts: '$event-id',
+});
+```
+
+### Read related events
+
+You can use `readEventRelations()` to read events releated to an event via `m.relates_to`.
+It provides an API with cursors that you can use to page through the results.
+
+```typescript
+const result = await widgetApi.readEventRelations(eventId, {
+  limit: 50,
+  from,
+  relationType: 'm.annotation',
+  eventType: 'm.reaction',
+});
+
+// result contains the events and cursor for paging further though the events
+```
+
+### Opening Modal Widgets
+
+You can open modal widgets using `openModal()`.
+It returns a promise that resolves with the result of the modal.
+
+Inside the modal widget, you can use `observeModalButtons()` to listen to clicks on the bottom buttons of the modal.
+You can use `setModalButtonEnabled()` to disable buttons from within the widget.
+Once you are done, you can call `closeModal()` to close the modal and pass the results back to the main widget.