# `Logistiki.Events.BusinessEvent`
[🔗](https://github.com/thanos/logistiki/blob/v0.1.0/lib/logistiki/events/business_event.ex#L1)

Persisted record of a normalized business event.

Business event persistence enables replay and audit. The `payload` stores the
original event as published by the application; `normalized_payload` stores the
flattened `Logistiki.Event.Normalized` representation used by the pipeline.

## Fields

  * `id` — `integer()` — primary key (e.g. `1`)
  * `event_type` — `String.t()` — e.g. `"deposit_received"`, `"fee_assessed"`
  * `source_system` — `String.t() | nil` — e.g. `"bank_core"`, `"onboarding"`
  * `source_id` — `String.t() | nil` — e.g. `"wire_123"`, `"crm_456"`
  * `actor_id` — `String.t() | nil` — who initiated the event (e.g. `"user_789"`)
  * `occurred_at` — `DateTime.t() | nil` — when the event happened (e.g. `~U[2026-07-07 12:00:00Z]`)
  * `effective_date` — `Date.t() | nil` — accounting effective date (e.g. `~D[2026-07-07]`)
  * `payload` — `map()` — the original event as a string-keyed map (default `%{}`)
  * `normalized_payload` — `map() | nil` — the `Normalized.to_map/1` representation
  * `status` — `String.t()` — one of `statuses/0` (default `"received"`, e.g. `"processed"`)
  * `explanation` — `map() | nil` — pipeline explanation (on completion)
  * `metadata` — `map()` — extensible metadata (default `%{}`)
  * `inserted_at` — `DateTime.t() | nil` — set by Ecto
  * `updated_at` — `DateTime.t() | nil` — set by Ecto

## Status transitions

`received` → `normalized` → `processed` (or `no_accounting_impact`,
`blocked`, `requires_approval`, `failed`).

## Example

    %Logistiki.Events.BusinessEvent{
      id: 1,
      event_type: "deposit_received",
      source_system: "bank_core",
      source_id: "wire_123",
      status: "processed",
      normalized_payload: %{"id" => "evt_001", "type" => "deposit_received", ...},
      inserted_at: ~U[2026-07-07 12:00:00Z]
    }

# `t`

```elixir
@type t() :: %Logistiki.Events.BusinessEvent{
  __meta__: term(),
  actor_id: String.t() | nil,
  effective_date: Date.t() | nil,
  event_type: String.t() | nil,
  explanation: map() | nil,
  id: integer() | nil,
  inserted_at: DateTime.t() | nil,
  metadata: map() | nil,
  normalized_payload: map() | nil,
  occurred_at: DateTime.t() | nil,
  payload: map() | nil,
  source_id: String.t() | nil,
  source_system: String.t() | nil,
  status: String.t() | nil,
  updated_at: DateTime.t() | nil
}
```

The `BusinessEvent` struct type — a persisted record of a normalized business
event.

## Fields

  * `id` — `integer() | nil` — primary key
  * `event_type` — `String.t() | nil` — e.g. `"deposit_received"`
  * `source_system` — `String.t() | nil` — e.g. `"bank_core"`
  * `source_id` — `String.t() | nil` — e.g. `"wire_123"`
  * `actor_id` — `String.t() | nil` — e.g. `"user_789"`
  * `occurred_at` — `DateTime.t() | nil` — e.g. `~U[2026-07-07 12:00:00Z]`
  * `effective_date` — `Date.t() | nil` — e.g. `~D[2026-07-07]`
  * `payload` — `map() | nil` — original event as a string-keyed map
  * `normalized_payload` — `map() | nil` — flattened event representation
  * `status` — `String.t() | nil` — e.g. `"processed"`, `"blocked"`
  * `explanation` — `map() | nil` — pipeline explanation
  * `metadata` — `map() | nil` — extensible metadata
  * `inserted_at` — `DateTime.t() | nil`
  * `updated_at` — `DateTime.t() | nil`

## Example

    %Logistiki.Events.BusinessEvent{
      id: 1, event_type: "deposit_received", status: "processed"
    }

# `statuses`
*since 0.1.0* 

```elixir
@spec statuses() :: [atom(), ...]
```

Returns the list of allowed business-event statuses as atoms.

## Returns

  * `[atom()]` — `[:received, :normalized, :blocked, :requires_approval,
    :processed, :no_accounting_impact, :failed]`

## Examples

    iex> :processed in Logistiki.Events.BusinessEvent.statuses()
    true

---

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