# `Issho.Event`
[🔗](https://github.com/hattoriai/issho/blob/v0.4.0/lib/issho/event.ex#L1)

Something that happened in a room, for whoever acts on it: the app's
code, the room's components, agents (`Issho.Events`).

  * `:name`: what happened, a dotted name (`"document.changed"`).
  * `:room`: the room it happened in.
  * `:document`: the document it is about, or `nil`.
  * `:by`: who made it happen (`Issho.Identity`: a person, an agent and
    whom it acts for, a service), or `nil`.
  * `:data`: what else there is to know, a map of the event's.
  * `:at`: when, a `DateTime` in UTC.

## Names

Issho's own names, and those its components emit, are reserved, so that
every app and component means the same by them:

  * `"document.changed"`: a document accepted a change (`data`:
    `%{revision: n}`). Every document emits it, and so does a component
    whose content is its own, not an Issho document's (Masu's rows:
    `data: %{op: :update, count: n}`).
  * `"person.joined"` and `"person.left"`: someone entered the room
    (their first tab, or an agent) or left it (their last), `data`:
    `%{can: "write"}`.
  * `"selection.changed"`: a session's place changed (`data`: `%{place:
    place, session: id}`, the place `nil` when it has none): what
    someone selected, in the document's own terms.
  * `"agent.started"` (`%{title, steps}`) and `"agent.finished"`
    (`%{title, summary}`): an agent began or ended a task
    (`Issho.Work`); `"agent.interrupted"` (`%{agent: key, action:
    "pause" | "stop"}`) and `"agent.resumed"` (`%{agent: key}`), by the
    person who paused, stopped or resumed it; `"agent.failed"`
    (`%{agent: key, title, reason}`): its work crashed
    (`Issho.Work.failed/2`).
  * `"stream.started"`, `"stream.finished"`, `"stream.failed"`,
    `"stream.closed"`: a stream of the room (`Issho.Streams`), `data`
    `%{stream: id, kind: kind, for: for}` and the reason or outcome.
  * `"thread.created"`, `"comment.created"`, `"comment.edited"`,
    `"comment.deleted"`, `"thread.resolved"`, `"thread.reopened"`:
    comments (`Issho.Comments`).

An app's own events take a name of its own, outside these
(`"retro.voted"`, `"myapp.toast"`).

# `t`

```elixir
@type t() :: %Issho.Event{
  at: DateTime.t(),
  by: Issho.Identity.t() | nil,
  data: map(),
  document: String.t() | nil,
  name: String.t(),
  room: String.t()
}
```

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

The event as JSON (string keys, the time in ISO 8601), for a model or a
browser: who made it happen is their public identity, and the data's
values that JSON has no way to say (a struct, a tuple) are inspected.

---

*Consult [api-reference.md](api-reference.md) for complete listing*