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

A room's events (`Issho.Event`), on every node: subscribe to act on what
happens in it (an admin page, a job, an agent waiting for someone), and
emit an app's or a component's own.

    Issho.Events.subscribe(MyApp.Issho, "board:42")

    def handle_info({Issho, :event, %Issho.Event{name: "document.changed"} = event}, socket) do
      ...
    end

    Issho.Events.emit(MyApp.Issho, "board:42", "retro.voted", by: current_user, data: %{card: id})

Each event is also a `:telemetry` event, once in the cluster, for an
app's own handlers (a notification, a log, a metric):

  * `[:issho, :event]`, with the measurement `:system_time`, and the
    metadata `:event` (the `Issho.Event`) and `:pubsub`.

A LiveView's components receive the events they ask for
(`Issho.Live.subscribe/3`), and so do participants that join with
`events: true` (`Issho.join_as/4`), such as the agents of
`Issho.Agents`, which wait for them (the `wait_for_events` tool).

# `emit`

```elixir
@spec emit(atom(), String.t(), String.t(), keyword()) :: :ok | {:error, term()}
```

Emits an event in a room. Options: `:document`, `:by` (an actor, as
`Issho.Actor` says them, or an `Issho.Identity`) and `:data` (a map).
An event whose data has `mentions` (keys) lands in the inbox of each
(`Issho.Inbox`), as a comment's does.

# `match?`

```elixir
@spec match?(:all | [String.t()], String.t()) :: boolean()
```

Whether an event's name is one of `names`: a name, a name ending in
`".*"` for all of a kind (`"comment.*"`), or `:all`.

    iex> Issho.Events.match?(["comment.*"], "comment.created")
    true
    iex> Issho.Events.match?(["document.changed"], "person.joined")
    false

# `subscribe`

```elixir
@spec subscribe(atom(), String.t()) :: :ok | {:error, term()}
```

Subscribes the calling process to a room's events: `{Issho, :event, %Issho.Event{}}`.

# `unsubscribe`

```elixir
@spec unsubscribe(atom(), String.t()) :: :ok
```

Stops the calling process's subscription to a room's events.

---

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