unleash_fresha

defmodule Unleash do
  @moduledoc """
  Unofficial Elixir SDK for the [Unleash Feature Flag System](https://www.getunleash.io/).

  Use it to check feature flags and variants via the main usage macros:

      require Unleash.Macros, as: Unleash
      Unleash.enabled?(:some_feature, fallback: false)
      Unleash.get_variant(:some_feature_with_variants)

  The SDK additionally provides a bunch of utilities to automatically set some context fields
  in Plug applications (see `Unleash.Plug`) and some utilities for propagation of context,
  feature flags overrides and impressions across services (see `Unleash.Propagation`).
  Note that Propagation is not a standard Unleash mechanism, but a custom extension
  defined and developed by [Fresha](https://www.fresha.com/careers).

  This module just contains the "interface "of the SDK, meaning the `Unleash` behaviour
  and types. For the actual runtime implementation, check `Unleash.Runtime` and related modules.
  """

  alias Unleash.Variant

  @typedoc """
  Type that can be used to reference a feature.

  Note that `:feature_a` and `"feature_a"` reference the same feature.
  """
  @type feature_name() :: String.t() | atom()

  @typedoc """
  Option that can be passed to `enabled?/2`.

  * `:allow_overrides` - Whether propagated overrides should be considered for the feature flag check.
    See `t:Unleash.overrides/0`. The default is `false`.
  * `:context` - Context that might be used to evaluate activation strategies. The default is an empty map.
  * `:fallback` - Fallback value that will be returned if the feature is not found in the local cache or overrides.
    The default is `false`. You can use `nil` if you'd like to handle missing features explicitly.
  """
  @type enabled_opt ::
          {:allow_overrides, boolean()}
          | {:context, Unleash.Context.t()}
          | {:fallback, boolean() | nil}

  @typedoc """
  Option that can be passed to `get_variant/2`.

  * `:allow_overrides` - Whether propagated overrides should be considered for the feature flag check.
    See `t:Unleash.overrides/0`. The default is `false`.
  * `:context` - Context that might be used to evaluate activation strategies. The default is an empty map.
  * `:fallback` - Fallback value that will be returned if the feature is not found in the local cache or overrides.
    The default is the special "disabled" variant.
    You can use `nil` if you'd like to handle missing features explicitly.
  """
  @type get_variant_opt ::
          {:allow_overrides, boolean()}
          | {:context, Unleash.Context.t()}
          | {:fallback, Variant.result() | nil}

  @typedoc """
  The Unleash Context for activation strategies evaluation. See `Unleash.Context`.
  """
  @type context :: Unleash.Context.t()

  @typedoc """
  Represents local feature overrides that can be used to force a feature evaluation value,
  bypassing its activation strategies.

  These can be inherited from the clients,
  see `Unleash.Propagation` for a high-level introduction to the topic.
  """
  @type overrides :: %{
          String.t() => :on | :off | String.t()
        }

  @typedoc """
  Record of a feature flag activation check.

  In other words, whenever a feature flag is queried for status via `enabled?/3`,
  an impression represents the feature that was checked and the result of that check.
  See https://docs.getunleash.io/reference/impression-data
  """
  @type impression :: %{
          feature_name: String.t(),
          enabled: boolean()
        }

  # The behaviour that Unleash Runtimes must implement.
  @doc """
  Checks if the given feature is enabled.
  """
  @callback enabled?(Unleash.feature_name(), opts :: [Unleash.enabled_opt()]) :: boolean() | nil

  @doc """
  Returns the variant for the given feature flag.
  """
  @callback get_variant(Unleash.feature_name(), opts :: [Unleash.get_variant_opt()]) :: Variant.result() | nil
end