@spec active_quests() :: [GameServer.Quests.Quest.t()]

All active quest definitions (cached — this backs event dispatch).

@spec admin_claim(user_id(), String.t()) ::
  {:ok, %{progress: GameServer.Quests.QuestProgress.t(), rewards: [map()]}}
  | {:error, term()}

Claim on a user's behalf, skipping the before_quest_claim veto (admin).

@spec admin_complete(user_id(), String.t()) ::
  {:ok, GameServer.Quests.QuestProgress.t()} | {:error, term()}

Force-complete a quest for a user (admin grant): every objective jumps to its target and the normal completion side effects fire (hooks, auto-claim).

@spec admin_reset(user_id(), String.t()) ::
  {:ok, GameServer.Quests.QuestProgress.t() | :not_found} | {:error, term()}

Delete a user's current-period progress row for a quest (admin reset).

@spec change_quest(GameServer.Quests.Quest.t(), map()) :: Ecto.Changeset.t()

Returns a changeset for tracking quest changes (used by forms).

@spec claim(user_id(), String.t(), keyword()) ::
  {:ok, %{progress: GameServer.Quests.QuestProgress.t(), rewards: [map()]}}
  | {:error, term()}

Claim a completed quest's rewards for the current period.

Runs the before_quest_claim pipeline hook (veto), then transitions completed → claimed atomically — only the winner grants rewards.

Returns {:ok, %{progress: progress, rewards: rewards}} or {:error, :quest_not_found | :not_completed | :already_claimed | term()}.

@spec claimable_count(user_id()) :: non_neg_integer()

Number of completed-but-unclaimed quests for a user (badge count).

@spec count_progress(keyword()) :: non_neg_integer()

Count progress rows (same filters as list_progress/1).

@spec count_quests(keyword()) :: non_neg_integer()

Count quest definitions (same filters as list_quests/1).

@spec count_user_completions(
  user_id(),
  keyword()
) :: non_neg_integer()

Count of a user's completed quests (same filters as list_user_completions/2).

@spec count_user_quests(
  user_id(),
  keyword()
) :: non_neg_integer()

Count of quests visible to the user (same filters as list_user_quests/2).

@spec create_quest(map()) :: {:ok, GameServer.Quests.Quest.t()} | {:error, term()}

Creates a quest definition. Capped by the max_quests limit.

@spec dashboard_stats() :: map()

Quest statistics for the admin dashboard.

@spec delete_quest(GameServer.Quests.Quest.t()) ::
  {:ok, GameServer.Quests.Quest.t()} | {:error, Ecto.Changeset.t()}

Deletes a quest definition and all related progress.

@spec funnel(String.t()) :: %{required(String.t()) => non_neg_integer()}

Per-status progress counts for one quest (admin completion funnel).

@spec get_progress(user_id(), String.t()) :: GameServer.Quests.QuestProgress.t() | nil

Get a user's progress row for a quest's current period.

@spec get_quest(Ecto.UUID.t()) :: GameServer.Quests.Quest.t() | nil

Get a quest by ID.

@spec get_quest_by_key(String.t()) :: GameServer.Quests.Quest.t() | nil

Get a quest by key.

@spec list_progress(keyword()) :: [GameServer.Quests.QuestProgress.t()]

Lists progress rows (admin viewer).

## Options

• :user_id — exact UUID or username/display-name substring
• :quest_key, :status
• :page / :page_size

@spec list_quests(keyword()) :: [GameServer.Quests.Quest.t()]

Lists quest definitions (admin view — no per-user state).

## Options

• :category — filter by category
• :active — filter by active flag
• :search — substring match on key/title
• :page / :page_size

@spec list_user_completions(
  user_id(),
  keyword()
) :: [
  %{
    quest: GameServer.Quests.Quest.t(),
    progress: GameServer.Quests.QuestProgress.t()
  }
]

A user's completed quests, newest first — the public-profile view ("their achievements"). Hidden quests appear once earned.

## Options

• :category — filter by category (a profile typically wants "achievement")
• :page / :page_size

@spec list_user_quests(
  user_id(),
  keyword()
) :: [
  %{
    quest: GameServer.Quests.Quest.t(),
    progress: GameServer.Quests.QuestProgress.t() | nil,
    claimable: boolean()
  }
]

Lists quests as seen by one user: active definitions in-window with the user's current-period progress and a claimable flag.

Hidden quests are listed but carry no details until earned (callers obscure them). Chain quests only appear once their prerequisite is met.

## Options

• :category — filter by category
• :status — "in_progress" (not yet completed), "claimable" (completed, waiting to be claimed) or "done" (completed or claimed)
• :page / :page_size

@spec period_key(GameServer.Quests.Quest.t() | String.t(), DateTime.t()) :: String.t()

The reset bucket a quest is in at now (UTC).

"static" when it never resets, else the current day ("2026-07-22"), ISO week ("2026-W30"), month ("2026-07"), or interval bucket ("I14-1436" — the 1436th 14-day window since the epoch). Derived purely from the clock, so a reset needs nothing to fire at midnight.

@spec prerequisite_met?(user_id(), GameServer.Quests.Quest.t()) :: boolean()

True when the quest's prerequisite (if any) is completed by the user.

@spec prune_old_periods() :: non_neg_integer()

Deletes daily/weekly progress rows whose period ended more than max_quest_period_history days ago (called from GameServer.Retention).

@spec recover_pending_rewards(keyword()) :: non_neg_integer()

Re-runs reward grants for rows that claimed but never finished granting (e.g. the process died mid-grant). Safe to run anywhere, any time — the per-entry idempotency keys dedupe. Pass :user_id to heal one user (done lazily when they list their quests). Returns the number of rows retried.

@spec report_event(user_id(), String.t(), pos_integer(), map()) ::
  {:ok, [GameServer.Quests.QuestProgress.t()]}

Report a gameplay event for a user, advancing every matching active quest.

meta narrows objective matching: an objective with params only advances when every param key/value is present in meta.

Returns {:ok, progress_rows} for the quests that advanced.

@spec subscribe_quests() :: :ok | {:error, term()}

Subscribe to global quest events (definition changes, completions).

@spec update_quest(GameServer.Quests.Quest.t(), map()) ::
  {:ok, GameServer.Quests.Quest.t()} | {:error, Ecto.Changeset.t()}

Updates a quest definition.