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 for UserService APIs and ol.trixnity.notification, ol.trixnity.verification, and ol.trixnity.key for the other non-room service mappings.

get-outbox

===

source

===

(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

create-room

(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

invite-user

(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

kick-user

(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

ban-user

(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

unban-user

(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

join-room

(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

leave-room

(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

forget-room

(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

send-message

(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 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

send-reaction

(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

send-state-event

(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

  • {::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

set-power-levels

(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

redact-event

(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

cancel-send-message

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

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

source

retry-send-message

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

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

source

get-by-id

(get-by-id client room-id)

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

source

get-all

(get-all client)

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

source

get-all-flat

(get-all-flat client)

Returns a Missionary flow of flattened room snapshots.

source

current-users-typing

(current-users-typing client)

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

source

users-typing

(users-typing client)

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

source

set-typing

(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

get-power-levels

(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.

source

get-account-data

(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

get-state

(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

get-all-state

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

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

source

get-outbox-flat

(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

fill-timeline-gaps

(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

get-timeline-event

(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

get-previous-timeline-event

(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

get-next-timeline-event

(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

get-last-timeline-event

(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

get-timeline-events

(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

get-last-timeline-events

(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

get-timeline-events-list

(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

get-last-timeline-events-list

(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

get-timeline-events-around

(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

get-timeline-events-from-now-on

(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

get-timeline-event-relations

(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