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

  FeatureFlipper provides a simple, 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 in your application
      defmodule MyApp.FeatureFlippers do
        def feature_flippers do
          [
            {:use_warehouse_cache_tbs_2221?, %{
              deadline: ~D[2025-06-30],
              description: "Use warehouse cache for improved performance"
            }},
            {:enable_warehouse_cache_mirroring_tbs_2395?, %{
              deadline: ~D[2025-06-30],
              force_disable: false,
              description: "Enable cache mirroring for data consistency"
            }}
          ]
        end
      end

      # Initialize in your application
      def start_phase(:init_feature_flippers, _start_type, _phase_args) do
        FeatureFlipper.ConfigLoader.init()
        :ok
      end

      # Use feature flippers
      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)

  ## Examples

      iex> FeatureFlipper.enabled?(:my_feature)
      true
  """
  @spec enabled?(atom()) :: boolean()
  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()
      :ok

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

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

  ## Examples

      iex> FeatureFlipper.all_flags()
      %{
        my_feature: true,
        another_feature: false
      }
  """
  @spec all_flags() :: map()
  def 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