# `KapsoEx.Platform.Events`
[🔗](https://github.com/rocket4ce/kapso_ex/blob/v0.1.0/lib/kapso_ex/platform/events.ex#L1)

[Project events](https://docs.kapso.ai/docs/platform/events): timestamped
data points you record (for example `order.created`) that can trigger
workflows, plus the definitions that describe them.

Event names are lowercase, optionally with dot-separated segments; each
segment starts with a letter and may contain letters, numbers and
underscores.

# `result`

```elixir
@type result() :: {:ok, map() | nil} | {:error, KapsoEx.Error.t()}
```

# `create_definition`

```elixir
@spec create_definition(KapsoEx.Client.t(), map() | keyword()) :: result()
```

Creates an event definition, or updates (and unarchives) the one with the
same name. Attributes: `name` (required), `description`,
`property_schema`.

# `delete_definition`

```elixir
@spec delete_definition(KapsoEx.Client.t(), String.t()) :: result()
```

Permanently deletes an event definition **and all its recorded events**.
Deletion runs in the background (`202 Accepted`). To keep history,
archive it with `update_definition/3` instead.

# `emit`

```elixir
@spec emit(KapsoEx.Client.t(), String.t(), keyword()) :: result()
```

Emits an event.

## Options

  * `:properties` - map of event properties.
  * `:conversation_id` - link the event to a WhatsApp conversation.
  * `:occurred_at` - `DateTime` or ISO 8601 string; defaults to now.

## Examples

    Events.emit(client, "order.created", properties: %{order_id: "1234", total: 59.9})

# `get_definition`

```elixir
@spec get_definition(KapsoEx.Client.t(), String.t()) :: result()
```

Gets an event definition.

# `list`

```elixir
@spec list(KapsoEx.Client.t(), map() | keyword()) :: result()
```

Lists events, newest first.

Params: `name`, `conversation_id`, `occurred_after`, `occurred_before`,
`limit`, `before`, `after`.

# `list_definitions`

```elixir
@spec list_definitions(KapsoEx.Client.t(), map() | keyword()) :: result()
```

Lists event definitions. Params: `include_archived`.

# `update_definition`

```elixir
@spec update_definition(KapsoEx.Client.t(), String.t(), map() | keyword()) :: result()
```

Updates an event definition: `name`, `description`, `property_schema`,
or `archived` (to hide it while keeping its events).

---

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