# ol.trixnity.room

Room operations, state queries, and timeline traversal.

## Upstream Mapping

This namespace maps primarily to Trixnity’s `RoomService` on
`de.connect2x.trixnity.client.MatrixClient`.

The public wrappers here cover three upstream groupings:

* room mutations such as room creation, invites, messages, reactions, and
  supported room state events and redactions
* room observation and state operations such as `getById`, `getAll`,
  `getAccountData`, `getState`, and `getOutbox`
* room-scoped timeline lookup and traversal helpers exposed through the
  room service and its timeline helpers

Use [`ol.trixnity.user`](api/ol-trixnity-user.adoc) for `UserService` APIs and
[`ol.trixnity.notification`](api/ol-trixnity-notification.adoc), [`ol.trixnity.verification`](api/ol-trixnity-verification.adoc), and
[`ol.trixnity.key`](api/ol-trixnity-key.adoc) for the other non-room service mappings.

## get-outbox

=== 

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L30-L30)

=== 

```clojure
(get-outbox client)
(get-outbox client room-id)
(get-outbox client room-id transaction-id)
```

Returns Missionary flows over room outbox state.

Arities:

* `(get-outbox client)` returns all outbox entries as a list of inner flows
* `(get-outbox client room-id)` scopes that list to one room
* `(get-outbox client room-id transaction-id)` returns the single outbox
  entry flow for that transaction id, including attachment upload progress
  under `::mx/media-upload-progress` when available

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L487-L505)

---

## create-room

```clojure
(create-room client opts)
```

Creates a room and returns a Missionary task that resolves to the new room id.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/room-name` | Optional room display name. |
| `::mx/topic` | Optional room topic. |
| `::mx/invite` | Optional vector of Matrix user ids to invite during creation. |
| `::mx/preset` | Optional preset keyword, one of `:private-chat`, `:public-chat`, or `:trusted-private-chat`. |
| `::mx/is-direct` | Optional direct-message flag for invite membership events. |
| `::mx/visibility` | Optional room-directory visibility, either `:private` or `:public`. |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L64-L81)

---

## invite-user

```clojure
(invite-user client room-id user-id)
(invite-user client room-id user-id opts)
```

Invites `user-id` to `room-id` and returns a Missionary task.

Supported opts:

| key | description
|-----|-------------
| `::mx/timeout` | Maximum time to wait for the invite request |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L83-L101)

---

## kick-user

```clojure
(kick-user client room-id user-id)
(kick-user client room-id user-id opts)
```

Kicks `user-id` from `room-id` and returns a Missionary task.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/reason` | Optional Matrix kick reason passed through to Trixnity |
| `::mx/timeout` | Maximum time to wait for the kick request |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L103-L123)

---

## ban-user

```clojure
(ban-user client room-id user-id)
(ban-user client room-id user-id opts)
```

Bans `user-id` from `room-id` and returns a Missionary task.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/reason` | Optional Matrix ban reason passed through to Trixnity |
| `::mx/timeout` | Maximum time to wait for the ban request |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L125-L145)

---

## unban-user

```clojure
(unban-user client room-id user-id)
(unban-user client room-id user-id opts)
```

Unbans `user-id` from `room-id` and returns a Missionary task.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/reason` | Optional Matrix unban reason passed through to Trixnity |
| `::mx/timeout` | Maximum time to wait for the unban request |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L147-L167)

---

## join-room

```clojure
(join-room client room-id-or-alias)
(join-room client room-id-or-alias opts)
```

Joins `room-id-or-alias` and returns a Missionary task.

Supported opts:

| key | description
|-----|-------------
| `::mx/timeout` | Maximum time to wait for the join request |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L169-L185)

---

## leave-room

```clojure
(leave-room client room-id)
(leave-room client room-id opts)
```

Leaves `room-id` and returns a Missionary task.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/reason` | Optional Matrix leave reason passed through to Trixnity |
| `::mx/timeout` | Maximum time to wait for the leave request |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L187-L205)

---

## forget-room

```clojure
(forget-room client room-id)
(forget-room client room-id opts)
```

Forgets `room-id` locally and returns a Missionary task.

Upstream notes that this is intended for rooms in `LEAVE` membership.

Supported opts:

| key | description
|-----|-------------
| `::mx/force` | Force forgetting even when the usual upstream preconditions are not met |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L207-L225)

---

## send-message

```clojure
(send-message client room-id message)
(send-message client room-id message opts)
```

Queues `message` for `room-id` and returns a Missionary task of a send handle.

The task resolves to:

* `::mx/transaction-id` for the queued outbox entry
* `::mx/status`, a Missionary flow backed by [`get-outbox`](#get-outbox) for that
  transaction id

The status flow may emit `nil` after the message leaves the outbox, which
usually means it was echoed back by sync, cancelled, or otherwise removed.

Supported opts:

| key | description
|-----|-------------
| `::mx/timeout` | Maximum time to wait for the send operation |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L227-L257)

---

## send-reaction

```clojure
(send-reaction client room-id ev key)
(send-reaction client room-id ev key opts)
```

Sends a reaction to event `ev` in `room-id` and returns a Missionary task.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L259-L273)

---

## send-state-event

```clojure
(send-state-event client room-id state-event)
(send-state-event client room-id state-event opts)
```

Sends a supported room state event map to `room-id`.

Supported state-event payloads:

* `{::mx/type "m.room.name", ::mx/name ...}`
* `{::mx/type "m.room.topic", ::mx/topic ...}`
* `{::mx/type "m.room.avatar", ::mx/url ...}`
* `{::mx/type "m.room.power_levels", ...}` using the same content keys as
  [`set-power-levels`](#set-power-levels)
* `{::mx/type "m.space.child", ::mx/state-key child-room-id, ::mx/via ...}`
* `{::mx/type "m.space.parent", ::mx/state-key parent-space-id, ::mx/via ...}`

`::mx/state-key` is optional for room state events that use the empty string
state key. Space relation events require a room id state key.

Supported opts:

| key | description
|-----|-------------
| `::mx/timeout` | Maximum time to wait for the send operation |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L275-L306)

---

## set-power-levels

```clojure
(set-power-levels client room-id power-levels)
(set-power-levels client room-id power-levels opts)
```

Sets the `m.room.power_levels` content for `room-id`.

`power-levels` is a map with Matrix power-level fields using namespaced
Clojure keys:

|     |     |
| --- | --- |
| key | description |
| `::mx/ban-level` | Level required to ban users |
| `::mx/event-levels` | Map of event type string to required level |
| `::mx/events-default-level` | Default level for message events |
| `::mx/invite-level` | Level required to invite users |
| `::mx/kick-level` | Level required to kick users |
| `::mx/redact-level` | Level required to redact others' events |
| `::mx/state-default-level` | Default level for state events |
| `::mx/user-levels` | Map of user id string to user level |
| `::mx/users-default-level` | Default level for users not in `::mx/user-levels` |
| `::mx/notification-levels` | Map of notification key to required level |
| `::mx/external-url` | Optional external URL attached to the state event content |

Supported opts:

| key | description
|-----|-------------
| `::mx/timeout` | Maximum time to wait for the send operation |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L308-L343)

---

## redact-event

```clojure
(redact-event client room-id event-id)
(redact-event client room-id event-id opts)
```

Redacts `event-id` in `room-id` and returns a Missionary task of the redaction event id.

Supported opts:

| key | description
|-----|-------------
| `::mx/reason` | Optional redaction reason sent to the homeserver |
| `::mx/timeout` | Maximum time to wait for the redact operation |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L345-L365)

---

## cancel-send-message

```clojure
(cancel-send-message client room-id transaction-id)
```

Cancels an outbox message identified by `transaction-id` and returns a Missionary task.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L367-L375)

---

## retry-send-message

```clojure
(retry-send-message client room-id transaction-id)
```

Retries an outbox message identified by `transaction-id` and returns a Missionary task.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L377-L385)

---

## get-by-id

```clojure
(get-by-id client room-id)
```

Returns a Missionary flow of the room for `room-id`, or nil when unavailable.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L387-L391)

---

## get-all

```clojure
(get-all client)
```

Returns a Missionary flow of room flows keyed by room id.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L393-L396)

---

## get-all-flat

```clojure
(get-all-flat client)
```

Returns a Missionary flow of flattened room snapshots.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L398-L401)

---

## current-users-typing

```clojure
(current-users-typing client)
```

Returns the current typing-state snapshot keyed by room id.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L403-L406)

---

## users-typing

```clojure
(users-typing client)
```

Returns a relieved Missionary flow of typing-state snapshots keyed by room id.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L408-L412)

---

## set-typing

```clojure
(set-typing client room-id typing?)
(set-typing client room-id typing? opts)
```

Sets the typing status for `room-id` and returns a Missionary task.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/timeout` | How long the typing notification should remain active |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L414-L432)

---

## get-power-levels

```clojure
(get-power-levels client room-id)
```

Returns a Missionary flow of normalized `m.room.power_levels` content.

The flow emits `nil` when no local power-level state is available for
`room-id`. Emitted maps use the same content keys accepted by
[`set-power-levels`](#set-power-levels).

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L434-L442)

---

## get-account-data

```clojure
(get-account-data client room-id event-content-class)
(get-account-data client room-id event-content-class key)
```

Returns a Missionary flow of room account-data content.

When `key` is omitted, the empty-string key is used.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L444-L458)

---

## get-state

```clojure
(get-state client room-id event-content-class)
(get-state client room-id event-content-class state-key)
```

Returns a Missionary flow of room state for `event-content-class`.

When `state-key` is omitted, the empty-string state key is used.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L460-L474)

---

## get-all-state

```clojure
(get-all-state client room-id event-content-class)
```

Returns a Missionary flow of state-event flows keyed by state key.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L476-L485)

---

## get-outbox-flat

```clojure
(get-outbox-flat client)
(get-outbox-flat client room-id)
```

Returns flattened Missionary flows over room outbox state.

With `room-id`, scopes the flattened outbox view to a single room.

Flattened outbox snapshots also include `::mx/media-upload-progress` when an
attachment-backed send is still uploading.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L507-L518)

---

## fill-timeline-gaps

```clojure
(fill-timeline-gaps client room-id event-id)
(fill-timeline-gaps client room-id event-id opts)
```

Fills timeline gaps around `event-id` in `room-id` and returns a Missionary task.

Supported opts:

| key | description
|-----|-------------
| `::mx/limit` | Maximum number of events to request while filling gaps (default `20`) |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L520-L538)

---

## get-timeline-event

```clojure
(get-timeline-event client room-id event-id)
(get-timeline-event client room-id event-id opts)
```

Returns a Missionary flow of the timeline event for `event-id`.

Upstream notes that this lookup may traverse locally stored events and fill
remote gaps when the event is not available locally.

Supported opts:

| key | description
|-----|-------------
| `::mx/decryption-timeout` | Timeout used while decrypting timeline events
| `::mx/fetch-timeout` | Timeout for remote fetches when the event is missing locally
| `::mx/fetch-size` | Maximum number of events fetched from the server at once
| `::mx/allow-replace-content` | Replace event content when an `m.replace` relation is present |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L540-L570)

---

## get-previous-timeline-event

```clojure
(get-previous-timeline-event client timeline-event)
(get-previous-timeline-event client timeline-event opts)
```

Returns a Missionary flow of the previous timeline event relative to `timeline-event`.

Returns nil when upstream cannot traverse backward from the supplied event.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L572-L588)

---

## get-next-timeline-event

```clojure
(get-next-timeline-event client timeline-event)
(get-next-timeline-event client timeline-event opts)
```

Returns a Missionary flow of the next timeline event relative to `timeline-event`.

Returns nil when upstream cannot traverse forward from the supplied event.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L590-L606)

---

## get-last-timeline-event

```clojure
(get-last-timeline-event client room-id)
(get-last-timeline-event client room-id opts)
```

Returns a Missionary outer flow whose values are flows of the latest timeline event.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L608-L624)

---

## get-timeline-events

```clojure
(get-timeline-events client response)
(get-timeline-events client response opts)
(get-timeline-events client room-id start-from direction)
(get-timeline-events client room-id start-from direction opts)
```

Returns Missionary flows over timeline events.

Arities:

* `(get-timeline-events client response opts)` extracts timeline events from
  a sync `response`
* `(get-timeline-events client room-id start-from direction opts)` traverses
  a room timeline from `start-from` in `:backwards` or `:forwards`

The room traversal arity follows upstream behavior: it emits flows of events,
may fetch missing events from the server, and can be bounded with
`::mx/min-size` and `::mx/max-size`.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L626-L669)

---

## get-last-timeline-events

```clojure
(get-last-timeline-events client room-id)
(get-last-timeline-events client room-id opts)
```

Returns a Missionary flow whose values are flows of flows for the latest timeline events.

This mirrors upstream’s nested-flow shape for continuously updated room-end
traversal.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L671-L692)

---

## get-timeline-events-list

```clojure
(get-timeline-events-list client room-id start-from direction max-size min-size)
(get-timeline-events-list client room-id start-from direction max-size min-size opts)
```

Returns a Missionary flow of timeline-event lists starting from `start-from`.

`max-size` and `min-size` bound the list-shaped traversal directly.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L694-L720)

---

## get-last-timeline-events-list

```clojure
(get-last-timeline-events-list client room-id max-size min-size)
(get-last-timeline-events-list client room-id max-size min-size opts)
```

Returns a Missionary flow of the latest timeline events as lists.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L722-L742)

---

## get-timeline-events-around

```clojure
(get-timeline-events-around client room-id start-from max-size-before max-size-after)
(get-timeline-events-around client room-id start-from max-size-before max-size-after opts)
```

Returns a Missionary flow of timeline-event lists centered around `start-from`.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L744-L766)

---

## get-timeline-events-from-now-on

```clojure
(get-timeline-events-from-now-on client)
(get-timeline-events-from-now-on client opts)
```

Returns a Missionary flow of timeline events received after subscription starts.

Upstream notes that timeline gaps are not filled automatically for this live
stream.

Supported opts:

| key | description
|-----|-------------
| `::mx/decryption-timeout` | Timeout used while decrypting live events
| `::mx/sync-response-buffer-size` | Number of sync responses buffered while events are consumed |

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L768-L789)

---

## get-timeline-event-relations

```clojure
(get-timeline-event-relations client room-id event-id relation-type)
```

Returns a Missionary flow of related timeline-event flows keyed by related event id.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/room.clj#L791-L799)