@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 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.