@spec clear_flow(ExGram.Cnt.t()) :: ExGram.Cnt.t()

Resets the FSM to a clean state: no active flow, no state, no data.

Calls storage.clear/1 to remove the user's FSM record entirely.

Example

def handle({:command, :cancel, _}, context) do
  context
  |> clear_flow()
  |> answer("Cancelled. Send /start to begin again.")
end

@spec get_data(ExGram.Cnt.t()) :: map()

Returns the current FSM data map from context.

Never returns nil — returns %{} if no FSM state exists.

Example

def handle({:command, :status, _}, context) do
  data = get_data(context)
  answer(context, "Your data: #{inspect(data)}")
end

@spec get_flow(ExGram.Cnt.t()) :: atom() | nil

Returns the current active flow name atom from context.

Returns nil if no flow is active or if the FSM middleware didn't run.

Example

def handle({:command, :status, _}, context) do
  flow = get_flow(context)
  answer(context, "Current flow: #{inspect(flow)}")
end

@spec get_state(ExGram.Cnt.t()) :: atom() | nil

Returns the current FSM state atom (step within the active flow) from context.

Returns nil if no state is set or if the FSM middleware didn't run.

Example

def handle({:command, :status, _}, context) do
  state = get_state(context)
  answer(context, "Current step: #{inspect(state)}")
end

@spec set_state(ExGram.Cnt.t(), atom()) :: ExGram.Cnt.t()

Unconditionally sets the FSM state within the currently active flow.

Requires an active flow. If no flow is active, the on_invalid_transition policy is applied (with from: nil, to: new_state).

This bypasses transition validation — use transition/2 for the normal path.

Use cases:

• Resetting to the flow's first step
• Admin override within a flow
• Recovery from an error state within a flow

Example

def handle({:command, :restart_flow, _}, context) do
  context
  |> set_state(:get_name)
  |> answer("Let's start over. What's your name?")
end

@spec set_state(ExGram.Cnt.t(), atom(), atom()) :: ExGram.Cnt.t()

Force sets a flow and state, bypassing all conflict and validation checks.

This is the escape hatch — it always succeeds regardless of the current flow. The data map is preserved as-is. Use this only for admin resets, recovery, or testing.

Example

def handle({:command, :admin_reset, _}, context) do
  context
  |> set_state(:registration, :get_name)
  |> answer("Admin reset. Starting registration flow.")
end

@spec start_flow(ExGram.Cnt.t(), atom()) :: ExGram.Cnt.t()

Starts a named flow for the current user/chat.

Sets the flow name, applies the flow's default_state/0 as the initial state (if defined), and clears any previous data.

Behavior:

• If no flow is currently active → starts the new flow
• If the same flow is already active → re-starts it (resets state + data)
• If a different flow is active → applies the on_invalid_transition policy. The "from" is the current flow name (treated as a pseudo-state), "to" is the requested flow name.

Example

def handle({:command, :register, _}, context) do
  context
  |> start_flow(:registration)
  |> answer("What's your name?")
end

@spec transition(ExGram.Cnt.t(), atom()) :: ExGram.Cnt.t()

Sets the FSM state with transition validation against the active flow.

This is the normal path for moving through steps. Use set_state/2 only as an escape hatch when you want to force a state skip validation.

Behavior:

1. Reads the current state from context.extra.fsm.state
2. Reads the active flow from context.extra.fsm.flow
3. Looks up the flow module and checks whether from -> to is a valid transition
4. If valid (or no flows configured): updates state and persists to storage
5. If NOT valid: delegates to the on_invalid_transition policy

Return value depends on policy:

• :raise — raises ExGram.FSM.TransitionError (never returns normally)
• :log — logs a warning, returns context unchanged
• :ignore — returns context unchanged silently
• {Module, :function} — calls Module.function(context, from, to), returns its result

Example

def handle({:text, name, _}, %{extra: %{fsm: %ExGram.FSM.State{flow: :registration, state: :get_name}}} = context) do
  context
  |> update_data(%{name: name})
  |> transition(:get_email)
  |> answer("Got it! What's your email?")
end

@spec update_data(ExGram.Cnt.t(), map()) :: ExGram.Cnt.t()

Merges a map into the current FSM data, persisting the result.

Uses Map.merge/2 semantics: new keys are added, existing keys are overwritten. The active flow and state are preserved.

Example

def handle({:text, name, _}, context) do
  context
  |> update_data(%{name: name})
  |> transition(:get_email)
  |> answer("What's your email?")
end