# ol.trixnity.space

Matrix space creation, hierarchy, and relation helpers.

Spaces are Matrix rooms with room type `m.space`. This namespace keeps the
wrapper thin: optional values are passed only when callers provide them, and
parent/child relation state is managed explicitly. Use [`ol.trixnity.room`](api/ol-trixnity-room.adoc)
and [`ol.trixnity.user`](api/ol-trixnity-user.adoc) for generic room membership and power-level APIs.

## create-space

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

Creates a Matrix space and returns a Missionary task resolving to its room id.

The request uses upstream create-room defaults and only forces the Matrix room
type to `m.space`. It does not add encryption or relation state.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/room-name` | Optional space name |
| `::mx/topic` | Optional space topic |
| `::mx/invite` | Optional users to invite during creation |
| `::mx/preset` | Optional upstream create-room preset |
| `::mx/is-direct` | Optional direct-room flag passed through upstream |
| `::mx/visibility` | Optional directory visibility |
| `::mx/power-levels` | Optional upstream power-level content override |
| `::mx/timeout` | Maximum time to wait for the create request |

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

---

## create-subspace

```clojure
(create-subspace client parent-space-id opts)
```

Creates a Matrix space and adds it as a child of `parent-space-id`.

This composes [`create-space`](#create-space) with [`set-child`](#set-child). It writes only the
`m.space.child` event in `parent-space-id`; use [`set-parent`](#set-parent) separately if
the child should also contain an `m.space.parent` event.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/room-name` | Optional subspace name |
| `::mx/topic` | Optional subspace topic |
| `::mx/invite` | Optional users to invite during creation |
| `::mx/preset` | Optional upstream create-room preset |
| `::mx/is-direct` | Optional direct-room flag passed through upstream |
| `::mx/visibility` | Optional directory visibility |
| `::mx/power-levels` | Optional upstream power-level content override |
| `::mx/via` | Required non-empty set of server names for the child relation |
| `::mx/order` | Optional Matrix space child ordering string |
| `::mx/suggested` | Optional suggested-child flag |
| `::mx/external-url` | Optional external URL for the child relation |
| `::mx/timeout` | Maximum time to wait for each request |

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

---

## hierarchy

```clojure
(hierarchy client space-id)
(hierarchy client space-id opts)
```

Returns one paginated hierarchy page for `space-id` as a Missionary task.

Supported opts:

|     |     |
| --- | --- |
| key | description |
| `::mx/from` | Optional pagination token |
| `::mx/limit` | Optional maximum rooms per page |
| `::mx/max-depth` | Optional maximum traversal depth |
| `::mx/suggested-only` | When true, include only suggested children |
| `::mx/timeout` | Maximum time to wait for the hierarchy request |

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

---

## get-all

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

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

This observes spaces already known to the client. It does not perform public
room discovery.

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

---

## get-all-flat

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

Returns a Missionary flow of local flattened space snapshots.

This observes spaces already known to the client. It does not perform public
room discovery.

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

---

## get-children

```clojure
(get-children client space-id)
```

Returns a Missionary flow of `m.space.child` state flows keyed by child room id.

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

---

## get-child

```clojure
(get-child client space-id child-room-id)
```

Returns a Missionary flow of the child relation for `child-room-id`.

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

---

## get-parents

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

Returns a Missionary flow of `m.space.parent` state flows keyed by parent space id.

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

---

## set-child

```clojure
(set-child client space-id child-room-id content)
(set-child client space-id child-room-id content opts)
```

Writes an `m.space.child` event in `space-id` for `child-room-id`.

The `content` map must include `::mx/via`. It may also include `::mx/order`,
`::mx/suggested`, and `::mx/external-url`.

Supported opts:

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

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

---

## remove-child

```clojure
(remove-child client space-id child-room-id)
(remove-child client space-id child-room-id opts)
```

Removes the child relation from `space-id` to `child-room-id`.

This sends empty `m.space.child` content for the child state key, which makes
the relation invalid under Matrix space rules.

Supported opts:

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

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

---

## set-parent

```clojure
(set-parent client room-id parent-space-id content)
(set-parent client room-id parent-space-id content opts)
```

Writes an `m.space.parent` event in `room-id` for `parent-space-id`.

The `content` map must include `::mx/via`. It may also include
`::mx/canonical` and `::mx/external-url`.

Supported opts:

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

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

---

## remove-parent

```clojure
(remove-parent client room-id parent-space-id)
(remove-parent client room-id parent-space-id opts)
```

Removes the parent relation from `room-id` to `parent-space-id`.

This sends empty `m.space.parent` content for the parent state key, which
makes the relation invalid under Matrix space rules.

Supported opts:

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

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