@spec channel_count() :: non_neg_integer()

Returns the number of cached channels.

@spec channels() :: [map()]

Gets all cached channels.

@spec channels_for_guild(String.t() | integer()) :: [map()]

Gets all channels for a guild.

@spec fetch_channel(String.t() | integer()) :: {:ok, map()} | {:error, term()}

Fetches a channel from cache, falling back to REST on miss.

@spec fetch_guild(String.t() | integer()) :: {:ok, map()} | {:error, term()}

Fetches a guild from cache, falling back to REST on miss.

@spec fetch_member(String.t() | integer(), String.t() | integer()) ::
  {:ok, map()} | {:error, term()}

Fetches a member from cache, falling back to REST on miss.

@spec fetch_role(String.t() | integer(), String.t() | integer()) ::
  {:ok, map()} | {:error, term()}

Fetches a role from cache, falling back to REST on miss.

Note: the REST API returns all roles for the guild, so guild_id is required.

@spec fetch_user(String.t() | integer()) :: {:ok, map()} | {:error, term()}

Fetches a user from cache, falling back to REST on miss.

@spec get_channel(String.t() | integer()) :: map() | nil

Gets a channel by ID.

@spec get_guild(String.t() | integer()) :: map() | nil

Gets a guild by ID.

@spec get_member(String.t() | integer(), String.t() | integer()) :: map() | nil

Gets a member in a guild.

@spec get_presence(String.t() | integer(), String.t() | integer()) :: map() | nil

Gets a user's presence in a guild.

@spec get_role(String.t() | integer()) :: map() | nil

Gets a role by ID.

@spec get_user(String.t() | integer()) :: map() | nil

Gets a user by ID.

@spec get_voice_state(String.t() | integer(), String.t() | integer()) :: map() | nil

Gets a user's voice state in a guild.

@spec guild_count() :: non_neg_integer()

Returns the number of cached guilds.

@spec guilds() :: [map()]

Gets all cached guilds.

@spec me() :: EDA.User.t() | map() | nil

Gets the current bot user as an %EDA.User{} struct.

Returns nil if the bot hasn't connected yet. The raw map is also stored for internal callers that need string-key access.

@spec me_raw() :: map() | nil

Returns the raw map of the current bot user (string keys).

Used internally by code that expects me["id"] string-key access (e.g., app_id/0, voice event routing).

@spec member_count() :: non_neg_integer()

Returns the total number of cached members.

@spec members(String.t() | integer()) :: [map()]

Gets all members for a guild.

@spec presences(String.t() | integer()) :: [map()]

Gets all presences for a guild.

@spec put_me(map()) :: :ok

Stores the current bot user. Saves both the parsed %EDA.User{} struct and the raw map for backward compatibility.

@spec role_count() :: non_neg_integer()

Returns the total number of cached roles.

@spec roles(String.t() | integer()) :: [map()]

Gets all roles for a guild.

@spec user_count() :: non_neg_integer()

Returns the number of cached users.

@spec users() :: [map()]

Gets all cached users.

@spec voice_channel_members(String.t() | integer(), String.t() | integer()) :: [map()]

Gets all voice states for a specific channel in a guild.

@spec voice_states(String.t() | integer()) :: [map()]

Gets all voice states for a guild.