defmodule HawkEx do
  @moduledoc """
  Public convenience API for HawkEx entitlement checks.

  HawkEx provides billing infrastructure for Phoenix and Ecto applications:
  plans, subscriptions, entitlement checks, audit logs, and CSV exports. The
  top-level module intentionally exposes only the most common entitlement
  operations so application code can stay small at the call site.

  Use the context modules for the full API:

    * `HawkEx.Billing` - plan and subscription management.
    * `HawkEx.Entitlements` - feature access, limits, and entitlement matrices.
    * `HawkEx.Audit` - audit logging and audit queries.
    * `HawkEx.CSV` - synchronous and asynchronous CSV exports.

  ## Quick start

      # Gate a feature
      if HawkEx.allowed?(account, :export_csv) do
        export(data)
      end

      # Diagnostic check with reason
      case HawkEx.check_entitlement(account, :export_csv) do
        :ok                             -> export(data)
        {:error, :no_subscription}      -> redirect_to_pricing()
        {:error, :feature_not_included} -> redirect_to_upgrade()
      end

      # Check a plan limit
      case HawkEx.remaining(account, :api_calls) do
        :unlimited -> proceed()
        n when n > 0 -> proceed()
        _ -> deny()
      end
  """

  alias HawkEx.Entitlements

  @doc """
  Returns `true` when the account's active plan grants the feature.

  This delegates to `HawkEx.Entitlements.allowed?/2`.
  """
  defdelegate allowed?(account, feature), to: Entitlements

  @doc """
  Returns `:ok` or a tagged denial reason for a feature check.

  This delegates to `HawkEx.Entitlements.check_entitlement/2`.
  """
  defdelegate check_entitlement(account, feature), to: Entitlements

  @doc """
  Returns the plan-defined limit for a feature.

  This delegates to `HawkEx.Entitlements.remaining/2`.
  """
  defdelegate remaining(account, feature), to: Entitlements
end