@spec all() :: bitset()

Returns the bitset with all permissions set.

@spec all_flags() :: [flag()]

Returns all known permission flag atoms.

@spec applies_to?(flag(), channel_kind() | integer() | map()) :: boolean()

Returns true if the permission applies to the given channel.

The second argument is a channel kind (:text, :voice, :stage), a raw Discord channel type integer, or a channel struct or map. Categories accept every kind, since their overwrites cascade to children of any type.

Examples

iex> EDA.Permission.applies_to?(:request_to_speak, :stage)
true

iex> EDA.Permission.applies_to?(:request_to_speak, :text)
false

iex> EDA.Permission.applies_to?(:kick_members, :text)
false

@spec channel?(flag()) :: boolean()

Returns true for a permission that can meaningfully appear in a channel overwrite.

Examples

iex> EDA.Permission.channel?(:send_messages)
true

iex> EDA.Permission.channel?(:administrator)
false

@spec channel_types(flag()) :: [channel_kind()]

The channel kinds a permission applies to.

An empty list means the permission is guild-level only — setting it in a channel overwrite has no effect.

Examples

iex> EDA.Permission.channel_types(:send_messages)
[:text, :voice, :stage]

iex> EDA.Permission.channel_types(:kick_members)
[]

iex> EDA.Permission.channel_types(:request_to_speak)
[:stage]

@spec explain(String.t(), String.t(), String.t()) ::
  {:ok, explanation()} | {:error, term()}

Explains how a member's channel permissions were derived.

in_channel/3 answers what a member may do; this answers why. Neither JDA nor Nostrum exposes the derivation, and "why can't my bot post here" is usually answered by guesswork against an opaque integer.

Returns the same :effective bitset as in_channel/3, plus:

• :base — guild-level permissions from the member's roles, before overwrites;
• :steps — the derivation in order, each with the running :result. Overwrite steps carry the :allow/:deny bitsets that were applied;
• :gates — which access gates fired (:timed_out, :no_view_channel, :no_connect);
• :denied_by — the gate that reduced the result to zero, or nil.

Owner and administrator short-circuit to every permission, and say so in a single step.

Examples

{:ok, why} = EDA.Permission.explain(guild_id, user_id, channel_id)

why.denied_by
#=> :no_view_channel

Enum.map(why.steps, & &1.stage)
#=> [:role_base, :everyone_overwrite, :role_overwrites, :member_overwrite, :gate]

# what the @everyone overwrite took away
why.steps
|> Enum.find(&(&1.stage == :everyone_overwrite))
|> Map.fetch!(:deny)
|> EDA.Permission.to_list()
#=> [:send_messages]

@spec for_member(EDA.Member.t() | map(), String.t() | integer()) ::
  {:ok, bitset()} | {:error, term()}

Computes effective guild-level permissions for a member already in hand: an EDA.Member, or a raw member map such as the one an interaction carries.

Unlike in_guild/2, the member need not be cached — without the GUILD_MEMBERS intent, most are not. Only the guild and its roles are read from the cache.

For the channel an interaction was used in, Discord already sends the member's permissions there, overwrites included, as member.permissions.

Returns {:ok, bitset} or {:error, reason}.

{:ok, perms} = EDA.Permission.for_member(interaction.member, interaction.guild_id)
EDA.Permission.has?(perms, :ban_members)

@spec from_bit(bitset()) :: {:ok, flag()} | :error

Returns the flag atom for a bit value, or :error.

@spec guild_only?(flag()) :: boolean()

Returns true for a permission that only has meaning at guild level.

Examples

iex> EDA.Permission.guild_only?(:kick_members)
true

iex> EDA.Permission.guild_only?(:send_messages)
false

@spec has?(bitset(), flag()) :: boolean()

Checks if a specific flag is set in a bitset.

@spec has_guild_permission?(String.t(), String.t(), flag()) :: boolean()

Checks if a member has a specific permission at guild level.

@spec has_permission?(String.t(), String.t(), String.t(), flag()) :: boolean()

Checks if a member has a specific permission in a channel.

Convenience function — most common use case for bots.

@spec in_channel(String.t(), String.t(), String.t()) ::
  {:ok, bitset()} | {:error, term()}

Computes effective channel-level permissions for a member.

Returns {:ok, bitset} or {:error, reason}.

Algorithm (matches Discord's official spec + JDA)

1. Owner → ALL_PERMISSIONS
2. Compute guild base permissions
3. ADMINISTRATOR → ALL_PERMISSIONS (skips all overwrites)
4. Apply 3-tier overwrite cascade: a. @everyone role overwrite b. All role overwrites (merged via OR, then applied) c. Member-specific overwrite (highest priority)
5. Access gate: no VIEW_CHANNEL → 0
6. Access gate: voice/stage channel + no CONNECT → 0

Obfuscated channels

Returns {:error, :channel_obfuscated} for a channel Discord has redacted because the bot cannot view it (see EDA.Channel.obfuscated?/1). Such a channel carries a single synthetic overwrite denying VIEW_CHANNEL to @everyone, which is indistinguishable from a real one — computing from it would return a confident but meaningless answer, so the ambiguity is surfaced to the caller instead.

has_permission?/4 maps this to false, like any other error.

@spec in_guild(String.t(), String.t()) :: {:ok, bitset()} | {:error, term()}

Computes effective guild-level permissions for a member.

Returns {:ok, bitset} or {:error, reason}.

Algorithm

1. Guild owner → ALL_PERMISSIONS
2. OR all role permission bits together
3. If ADMINISTRATOR is set → ALL_PERMISSIONS

@spec inapplicable(bitset(), channel_kind() | integer() | map()) :: [flag()]

Lists the permissions in a bitset that have no effect in the given channel.

Use it to catch a meaningless overwrite before sending it — Discord accepts KICK_MEMBERS in a channel overwrite and silently ignores it. Neither JDA nor Nostrum offers this check.

Examples

iex> bitset = EDA.Permission.to_bitset([:send_messages, :kick_members])
iex> EDA.Permission.inapplicable(bitset, :text)
[:kick_members]

iex> EDA.Permission.inapplicable(EDA.Permission.to_bitset([:send_messages]), :text)
[]

@spec to_bit(flag()) :: bitset()

Returns the bit value for a permission flag.

@spec to_bitset([flag()]) :: bitset()

Converts a list of flag atoms to a combined bitset.

@spec to_list(bitset()) :: [flag()]

Converts a bitset to a list of flag atoms. Unknown bits are skipped.