# `DpExchange.Core.Types.CorporateEvent`
[🔗](https://github.com/DistortionPoint/dp-exchange-core/blob/v0.3.120/lib/dp_exchange/core/types/corporate_event.ex#L1)

A dated event on an issuer — a dividend, an earnings release, a split.

## The dates are several, and they are not interchangeable

A dividend has an **ex-date**, a **record date** and a **pay date**, and they are days or
weeks apart. Which one matters depends entirely on the question: the ex-date determines
who receives it, the pay date when the cash arrives. A single `:date` field would force
every caller to guess which one it held.

So each is carried under its own name, and `:date` is not among them. A venue that
publishes only one populates only that one; the rest stay `nil`, meaning **not published**
rather than "same as the one you have".

## An earnings date is often approximate, and the venue knows it

Issuers announce "week of", and venues relay estimates that move. `:confirmed` carries the
venue's own statement of whether the date is fixed. `nil` means it did not say — which is
not the same as confirmed, and a caller treating an estimate as fixed will be early or
late by days.

# `kind`

```elixir
@type kind() :: :dividend | :earnings | :split | :other
```

# `t`

```elixir
@type t() :: %DpExchange.Core.Types.CorporateEvent{
  amount: Decimal.t() | nil,
  announced_date: Date.t() | nil,
  confirmed: boolean() | nil,
  currency: String.t() | nil,
  details: %{optional(String.t()) => term()} | nil,
  ex_date: Date.t() | nil,
  kind: kind(),
  pay_date: Date.t() | nil,
  provider: atom(),
  ratio: String.t() | nil,
  record_date: Date.t() | nil,
  symbol: String.t()
}
```

# `new`

```elixir
@spec new(keyword() | map()) :: t()
```

Builds a `t:t/0`, failing closed if a required field is absent or `nil`.

`@enforce_keys` guards presence, not `nil` — see `DpExchange.Core.Types.Validate`.

Also raises on a `:kind` outside `:dividend | :earnings | :split | :other`, on a date field that
is not a `Date` (a `DateTime` carries an instant these four do not have), on a `:details` that
is not a plain map, on a `:confirmed` that is not `true`, `false` or `nil` (`nil` is "the venue
did not say", never confirmed) and on an `:amount` that is not a number.

---

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