defmodule CodeNameRaven.Runtime do
  @moduledoc """
  Provides a runtime façade for integrations to interact with the host system.
  """

  @doc """
  Returns the most recent samples for `monitor_id` across the cluster.

  Each sample is returned as a plain map with the following keys:
    * `:monitor_id` - the monitor's string ID
    * `:instance_id` - the instance ID (string/binary)
    * `:status` - string representation of the health status (e.g., "up", "down", "degraded", "unknown")
    * `:latency_ms` - nullable integer representing latency
    * `:status_code` - nullable integer representing status code
    * `:metrics` - map of numeric metrics
    * `:collected_at` - UTC DateTime of the sample collection
    * `:synthetic` - boolean indicating if this is a synthetic sample
  """
  @spec recent_samples(String.t(), keyword()) :: [map()]
  def recent_samples(monitor_id, opts \\ []) do
    adapter().recent_samples(monitor_id, opts)
  end

  @doc """
  Returns the stable instance ID of this running node.
  """
  @spec instance_id() :: String.t()
  def instance_id do
    adapter().instance_id()
  end

  defp adapter do
    Application.get_env(:raven_observer_sdk, :runtime_adapter, CodeNameRaven.Runtime.NullAdapter)
  end
end