@spec channel_join(pid(), binary(), map()) ::
  {:ok, pid()}
  | {:error, :channel_manager_not_found | {:already_started, pid()}}

Joins a channel through the socket.

@spec channel_leave(pid(), pid()) :: :ok | :error

Leaves a channel.

@spec child_spec(keyword()) :: Supervisor.child_spec()

Returns a child specification for the socket client supervisor.

Delegates to Phoenix.SocketClient.Supervisor.child_spec/1.

@spec connect(pid() | atom()) :: :ok | {:error, :no_socket_found}

Connects the socket.

@spec connected?(pid() | atom()) :: boolean()

Checks if the socket is connected.

@spec connection_info(pid() | atom()) ::
  %{
    attempt_ref: reference() | nil,
    status: :disconnected | :connecting | :connected,
    last_error: atom() | {atom(), integer()} | nil
  }
  | {:error, :no_socket_found}

Returns the current connection attempt independently of telemetry configuration.

The snapshot contains :attempt_ref, :status, and :last_error. The reference is nil before the first attempt and changes whenever a new transport is opened, including automatic retries. Failures retain the reference and reason until another attempt starts. Successful connections clear the error.

HTTP upgrade rejections retain {:unexpected_status, status} (including 401 and 403); transient failures retain their error atom, such as :econnrefused or :timeout. Other structured errors expose their category without private details. Explicit disconnect records :cancelled and cancels pending retries.

Read the snapshot again before acting on a previously observed failure; an older attempt must not override a newer connection. Automatic retries replace the snapshot, so use reconnect?: false and let the caller initiate retries when each rejection must be classified. This function reports connection state and leaves authentication policy to the caller.

@spec discard_child_spec(Supervisor.child_spec()) :: :ok | {:error, :in_use}

Releases private configuration for an unused client child specification.

See Phoenix.SocketClient.Supervisor.discard_child_spec/1 for its lifetime.

@spec disconnect(pid() | atom()) :: :ok

Disconnects the socket.

@spec get_state(pid() | atom()) :: map() | nil

Gets the entire socket state.

@spec get_state(pid() | atom(), atom()) :: any() | nil

Gets a value from the socket state.

@spec push(pid() | atom(), Phoenix.SocketClient.Message.t()) ::
  Phoenix.SocketClient.Message.t() | no_return()

Pushes a message through the socket.

@spec put_state(pid() | atom(), atom(), any()) :: :ok | nil

Puts a value into the socket state.

@spec remove_channel(pid(), String.t()) :: :ok | nil

Removes a channel from the list of joined channels. For internal use.

@spec start_link(keyword()) :: Supervisor.on_start()

Starts the socket client supervisor.

Delegates to Phoenix.SocketClient.Supervisor.start_link/1.

@spec update_channel_status(pid(), pid(), String.t(), atom(), map() | nil) ::
  :ok | nil

Updates the status of a channel. For internal use.