defmodule Argos.Logger.Behaviour do
  @moduledoc """
  Behaviour para implementaciones de logger en Argos.

  Define el contrato que deben implementar los loggers personalizados.
  """

  @doc """
  Registra un mensaje de log con el nivel y metadata especificados.

  ## Parámetros

    * `level` - Nivel de log (`:debug`, `:info`, `:warning`, `:error`, etc.)
    * `message` - Mensaje a registrar (string)
    * `metadata` - Metadata adicional (keyword list)

  ## Retorna

    `:ok` - Siempre retorna `:ok`

  ## Ejemplos

      def log(:info, "Mensaje informativo", [module: MyModule])
      # => :ok
  """
  @callback log(Logger.level(), String.t(), keyword()) :: :ok

  @doc """
  Registra un mensaje de log en modo raw.

  El modo raw permite calcular el tamaño del TUI y posicionar los logs
  debajo del TUI. Esta función es opcional y solo se llama si está implementada.

  ## Parámetros

    * `level` - Nivel de log (`:debug`, `:info`, `:warning`, `:error`, etc.)
    * `message` - Mensaje a registrar (string)
    * `metadata` - Metadata adicional (keyword list)

  ## Retorna

    `:ok` - Siempre retorna `:ok`

  ## Nota

    Esta función es opcional. Si no se implementa, se usará `log/3` en su lugar.
  """
  @optional_callbacks log_raw: 3
  @callback log_raw(Logger.level(), String.t(), keyword()) :: :ok
end