defmodule FeatureFlipper do
  @moduledoc """
  Main interface for feature flag operations.

  FeatureFlipper provides a comprehensive, easy-to-integrate feature flag system
  for Elixir applications with Consul integration, caching, and deadline management.

  ## Configuration

      # config/config.exs
      config :feature_flipper,
        consul_kv_path: "telephony/services/routing",
        consul_client_http_addr: "http://consul.query.dev.telnyx.io:18500",
        env: System.get_env("ENV", "dev"),
        hostname: System.get_env("SERVER_HOSTNAME", "local"),
        version_suffix: "1.7.9-rc"  # Optional, for production versioning

  ## Usage

      # Define feature flippers
      defmodule MyApp.FeatureFlippers do
        use FeatureFlipper.Definition

        define_flipper :use_warehouse_cache_tbs_2221?, %{
          deadline: ~D[2025-06-30],
          description: "Use warehouse cache for improved performance"
        }
      end

      # Use feature flippers
      if MyApp.FeatureFlippers.use_warehouse_cache_tbs_2221?() do
        # Feature is enabled
      end

      # Or use the main interface
      if FeatureFlipper.enabled?(:use_warehouse_cache_tbs_2221?) do
        # Feature is enabled
      end
  """

  alias FeatureFlipper.{ConfigLoader, DeadlineChecker}

  @doc """
  Check if a feature flipper is enabled.

  ## Parameters

    * `flipper_name` - The name of the feature flipper (atom or string)

  ## Examples

      iex> FeatureFlipper.enabled?(:my_feature)
      true

      iex> FeatureFlipper.enabled?("my_feature")
      false
  """
  @spec enabled?(atom() | String.t()) :: boolean()
  def enabled?(flipper_name) when is_binary(flipper_name) do
    flipper_name
    |> String.to_atom()
    |> enabled?()
  end

  def enabled?(flipper_name) when is_atom(flipper_name) do
    ConfigLoader.get_flipper_value(flipper_name)
  end

  @doc """
  Reload configuration from Consul.

  This function fetches the latest feature flipper configuration from Consul
  and updates the local cache.

  ## Examples

      iex> FeatureFlipper.reload_configuration()
      :ok

      iex> FeatureFlipper.reload_configuration()
      {:error, :consul_unavailable}
  """
  @spec reload_configuration() :: :ok | {:error, term()}
  def reload_configuration do
    ConfigLoader.reload_configuration()
  end

  @doc """
  Get all feature flags and their current values.

  ## Examples

      iex> FeatureFlipper.get_all_flags()
      %{
        my_feature: true,
        another_feature: false
      }
  """
  @spec get_all_flags() :: map()
  def get_all_flags do
    ConfigLoader.get_all_flags()
  end

  @doc """
  Check for feature flippers that are past their deadline.

  Returns a list of warning messages for features that are past their deadline.

  ## Examples

      iex> FeatureFlipper.check_deadlines()
      ["Feature 'old_feature' is past its deadline of 2024-01-01"]

      iex> FeatureFlipper.check_deadlines()
      []
  """
  @spec check_deadlines() :: [String.t()]
  def check_deadlines do
    DeadlineChecker.check_deadlines()
  end
end