# `Raxol.Core.Events.CloudEvent`
[🔗](https://github.com/DROOdotFOO/raxol/blob/v2.8.0/lib/raxol/core/events/cloud_event.ex#L1)

CloudEvents v1.0 envelope ([cloudevents.io](https://cloudevents.io/)).

Standardized event metadata so raxol events can interoperate with
webhook receivers, pub/sub fabrics, and message brokers without
bespoke serialization. Conversion to and from `Raxol.Core.Events.Event`
is provided by that module.

## Required fields

  * `:specversion` - "1.0"
  * `:id` - unique within the source
  * `:source` - URI-reference identifying the producer (e.g. `"raxol://node-1"`)
  * `:type` - reverse-DNS style event type (e.g. `"raxol.key"`)

## Optional fields

  * `:time` - `DateTime.t()` when the event occurred
  * `:data` - event payload (any term)
  * `:datacontenttype` - MIME type of `:data` (e.g. `"application/json"`)
  * `:subject` - subject of the event in the context of the source

## Examples

    ce = CloudEvent.new("raxol.key", "raxol://node-1",
      data: %{key: :enter, state: :pressed}
    )

    map = CloudEvent.to_map(ce)
    # => %{specversion: "1.0", id: "...", source: "raxol://node-1",
    #      type: "raxol.key", time: ~U[...], data: %{...}}

    {:ok, ce2} = CloudEvent.from_map(map)

# `t`

```elixir
@type t() :: %Raxol.Core.Events.CloudEvent{
  data: term() | nil,
  datacontenttype: String.t() | nil,
  id: String.t(),
  source: String.t(),
  specversion: String.t(),
  subject: String.t() | nil,
  time: DateTime.t() | nil,
  type: String.t()
}
```

# `from_map`

```elixir
@spec from_map(map()) :: {:ok, t()} | {:error, :missing_required_field}
```

Build a CloudEvent from a map (atom or string keys).

Returns `{:error, :missing_required_field}` if `:id`, `:source`, or
`:type` is absent. Unknown fields are dropped silently.

# `new`

```elixir
@spec new(String.t(), String.t(), keyword()) :: t()
```

Construct a CloudEvent. `type` and `source` are required.

## Options

  * `:id` - explicit id (default: random 16 hex chars)
  * `:time` - `DateTime.t()` (default: `DateTime.utc_now/0`)
  * `:data` - event payload
  * `:datacontenttype` - MIME type of `:data`
  * `:subject` - subject of the event

# `to_map`

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

Returns the CloudEvent as a map suitable for JSON encoding.
Nil-valued optional fields are dropped. Atom keys; convert to
string keys at the serialization boundary if needed.

---

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