defmodule Polymarket.Activity.Event do
  @moduledoc """
  Typed struct for a single normalized Polymarket activity event.

  Produced by `Polymarket.Activity.normalize/1`. Each event corresponds to
  one row from Polymarket's public Data API `/activity` endpoint and
  represents either a trade fill (`type: :trade` with `side: :buy | :sell`)
  or a market redemption (`type: :redeem`).

  The original raw map is preserved under the `:raw` field so callers can
  recover any field this struct does not normalize without re-parsing.

  ## Fields

    * `:type` — `:trade`, `:redeem`, or `:unknown`.
    * `:side` — `:buy`, `:sell`, or `nil` (always `nil` for `:redeem`).
    * `:tx_hash` — on-chain transaction hash (used to join activity ↔ fills).
    * `:condition_id` — the market condition id this event belongs to.
    * `:token_id` — outcome token id (asset id).
    * `:usdc_size` — fee-inclusive USDC amount. For BUYs this is the wallet
      debit including taker fee; for SELLs it is the credit. For REDEEMs
      it is the payout.
    * `:shares` — number of outcome tokens involved (Polymarket sends this
      as `size` on the wire).
    * `:price` — execution price per share (TRADE only).
    * `:timestamp` — Unix-seconds timestamp.
    * `:raw` — the raw map this struct was normalized from.
  """

  @type type :: :trade | :redeem | :unknown
  @type side :: :buy | :sell | nil

  @type t :: %__MODULE__{
          type: type(),
          side: side(),
          tx_hash: String.t() | nil,
          condition_id: String.t() | nil,
          token_id: String.t() | nil,
          usdc_size: float() | nil,
          shares: float() | nil,
          price: float() | nil,
          timestamp: integer() | nil,
          raw: map()
        }

  defstruct [
    :type,
    :side,
    :tx_hash,
    :condition_id,
    :token_id,
    :usdc_size,
    :shares,
    :price,
    :timestamp,
    raw: %{}
  ]
end