HawkEx.Entitlements (hawk_ex v0.1.0)

Entitlement checks and entitlement reporting.

Entitlements answer whether an account's current plan grants a feature and, for limit features, what value that plan grants. The module reads the account's active plan through HawkEx.Billing and then evaluates the plan's HawkEx.Billing.PlanFeature records.

Feature values are interpreted as follows:

"true" grants a boolean feature.
"false" denies a boolean feature.
"0" denies a limit feature.
Positive integer strings grant that numeric limit.
"unlimited" grants unlimited access.

The three functions

allowed?/2 is the fast boolean check for gates and UI rendering. No subscription returns false.

if HawkEx.allowed?(account, :export_csv), do: export()

check_entitlement/2 is the diagnostic check. Use this when the caller needs to distinguish between no subscription and a missing feature.

case HawkEx.check_entitlement(account, :export_csv) do
  :ok                            -> proceed()
  {:error, :no_subscription}     -> show_subscribe_prompt()
  {:error, :feature_not_included} -> show_upgrade_prompt()
end

remaining/2 returns the plan-defined limit. It does not subtract usage. Host applications should track usage separately.

NOTE: v0.1 returns the plan limit, not actual remaining quota.
Usage tracking will be added in a future version.

case HawkEx.remaining(account, :api_calls) do
  :unlimited -> proceed()
  n when n > 0 -> proceed()
  0 -> deny()
end

Summary

Functions

allowed?(account, feature_key)

Returns true when the account is allowed to use a feature.

check_entitlement(account, feature_key)

Returns :ok when the account can use a feature.

for_account(account)

Returns all entitlement values for an account's current plan.

matrix()

Returns the full entitlement matrix for display.

remaining(account, feature_key)

Returns the limit value for a limit-type feature.

Functions

allowed?(account, feature_key)

Returns true when the account is allowed to use a feature.

Returns false when the account has no active subscription or when the current plan does not include the feature.

check_entitlement(account, feature_key)

Returns :ok when the account can use a feature.

Returns a tagged error when access is denied:

{:error, :no_subscription} - the account has no active plan.
{:error, :feature_not_included} - the plan does not include the requested feature or explicitly denies it.

for_account(account)

Returns all entitlement values for an account's current plan.

Returns {:ok, %{plan: plan, features: features}}, where each feature entry includes :key, :description, :feature_type, and :value.

Returns {:error, :no_subscription} if the account has no active plan.

matrix()

Returns the full entitlement matrix for display.

Returns a map with:

:plans - active plans ordered by trial_days ascending.
:features - all feature definitions.
:matrix - map of {plan_id, feature_key} to the configured value.

This is intended for admin dashboards and plan-comparison screens.

remaining(account, feature_key)

Returns the limit value for a limit-type feature.

Returns:

:unlimited when the plan grants unlimited use.
an integer when the plan grants a numeric limit.
{:error, :no_subscription} when the account has no active plan.
{:error, :feature_not_included} when the plan does not include the feature.
{:error, :invalid_limit_value} when the stored value is not parseable.

This function returns the configured plan limit, not actual remaining quota. Usage tracking and subtraction belong to the host application.