ex_gram

# Commands

`ExGram` provides a `command` macro to declare bot commands with descriptions, visibility scopes, and language translations. When `setup_commands: true` is set on the bot, these declarations are automatically registered with the Telegram API on startup, making your commands appear in the autocomplete menu for users.

## Basic usage

The simplest way to declare a command is with just a name and a description:

```elixir
defmodule MyBot do
  use ExGram.Bot, name: :my_bot, setup_commands: true

  command(:start, description: "Start the bot")

  def handle({:command, :start, _msg}, context) do
    answer(context, "Welcome!")
  end
end
```

Commands without a `description` are still valid - they will be handled by your bot but won't be registered in the Telegram command menu. This is useful for "hidden" commands or not useful commands in day-to-day:

```elixir
command(:start)  # no description - works but won't show in menu
command(:debug)  # no description - works but won't show in menu

def handle({:command, :start, _msg}, context) do
  answer(context, "Hey!")
end

def handle({:command, :debug, _msg}, context) do
  answer(context, "Debug mode")
end
```

## Options reference

- `:description` (string) - text shown in Telegram's command menu. Required if any other of this options are set.
- `:scopes` (list) - scopes where the command is visible. See [Scopes](#scopes).
- `:lang` (keyword list) - language-specific overrides, IETF language code atom. See [Language translations](#language-translations).
- `:name` (atom) - atom used for dispatch pattern matching. Defaults to the command name as an atom. Useful when you want a different name in the handler.

```elixir
# Override the handler atom - dispatches as {:command, :begin, msg}
command(:start, name: :begin, description: "Start the bot")

def handle({:command, :begin, _msg}, context) do
  answer(context, "Welcome!")
end
```

## Scopes

Telegram's [BotCommandScope](https://core.telegram.org/bots/api#botcommandscope) controls where commands appear in the autocomplete menu. By declaring scopes you can show different command sets to different audiences - for example, showing admin commands only to group administrators.

### Simple scopes

These are plain atoms:

| Scope                      | Who sees it                                   |
|----------------------------|-----------------------------------------------|
| `:default`                 | All users when no more specific scope applies |
| `:all_private_chats`       | Users in any private (1-on-1) chat            |
| `:all_group_chats`         | Users in any group or supergroup chat         |
| `:all_chat_administrators` | Administrators in any group chat              |

```elixir
command(:help,
  description: "Get help",
  scopes: [:all_private_chats, :all_group_chats]
)

command(:ban,
  description: "Ban a user",
  scopes: [:all_chat_administrators]
)
```

### Parametric scopes

These are tuples that target specific chats or users:

- `{:chat, chat_ids: [100, 200]}` - visible in the listed chats. Expands to one API registration per chat.
- `{:chat_administrators, chat_ids: [100]}` - visible to administrators of the listed chats.
- `{:chat_member, chat_id: 1, user_ids: [10, 20]}` - visible to specific users in a specific chat.

```elixir
command(:notify,
  description: "Send a notification",
  scopes: [{:chat, chat_ids: [123_456, 789_012]}]
)

command(:secret,
  description: "Secret command",
  scopes: [{:chat_member, chat_id: 123_456, user_ids: [111, 222]}]
)
```

### Scope inheritance

The `scopes` option controls not just where a command appears, but how it interacts with the rest of your command list.

**Commands without `scopes`** (or with `scopes: nil`). All the other scopes will inherit this command, meaning they will appear everywhere other commands appear.

**Commands with `scopes: []`** (empty list) fall back to `:default`. It will only appear to users with the default scope.

**If no command defines any scope**, everything falls back to `:default`.

**Commands with explicit scopes** appear **only** in those scopes.

```elixir
# "help" has no scopes
command(:help, description: "Get help")

# "stats" is only in :all_private_chats
command(:stats,
  description: "Your stats",
  scopes: [:all_private_chats]
)
```

In this example, both `:stats` and `:help` appear in `:all_private_chats`. And on the `:default` scope (group chats for example) only the `:help` command would appear.

## Language translations

The `:lang` option lets you provide per-language overrides for the command name and description. Each key is an IETF language code atom (`:es`, `:pt`, `:it`, etc.) and the value is a keyword list with `:command` and/or `:description`.

### Translating descriptions

```elixir
command(:start,
  description: "Start the bot",
  scopes: [:default],
  lang: [
    es: [description: "Iniciar el bot"],
    pt: [description: "Iniciar o bot"]
  ]
)
```

Spanish users see "Iniciar el bot", Portuguese users see "Iniciar o bot", everyone else sees "Start the bot".

### Translating command names

You can also change the command name itself for a language:

```elixir
command(:help,
  description: "Get help",
  scopes: [:default],
  lang: [es: [command: "ayuda", description: "Obtener ayuda"]]
)
```

Spanish users see `/ayuda` in their menu. ExGram automatically registers `/ayuda` as a dispatch alias, so it routes to the same `:help` handler - no extra `handle` clause needed:

```elixir
def handle({:command, :help, _msg}, context) do
  # Here the user will have `language_code` if you want to send translated messages
  answer(context, "Here is some help!")
end
```

### Inheriting values

A lang entry does not need to override both fields:

- Omitting `:description` inherits the base description.
- Omitting `:command` keeps the base command name.

```elixir
command(:help,
  description: "Get help",
  lang: [es: [command: "ayuda"]]  # description inherited from base
)
```

### Merge behavior

Untranslated commands are automatically merged into every language group. This ensures users of any language always see the full command list - translated commands appear in their translated form, untranslated commands fall back to their base form.

```elixir
command(:start,
  description: "Start the bot",
  lang: [es: [description: "Iniciar el bot"]]
)
command(:help, description: "Get help")
```

Spanish users see both `start` ("Iniciar el bot") and `help` ("Get help"). The untranslated `:help` is merged in automatically.

If a command renames itself in a translation (e.g. `help` -> `ayuda`), the original name (`help`) is excluded from that language group to avoid showing duplicate entries.

## Scopes and languages combined

Translations apply independently to each scope. If a command appears in multiple scopes, each (scope + language) combination gets its own Telegram API registration.

```elixir
command(:greet,
  description: "Greet users",
  scopes: [:all_private_chats, :all_group_chats],
  lang: [es: [description: "Saludar usuarios"]]
)
```

This produces four registrations:

- `:all_private_chats` (no lang) - "Greet users"
- `:all_group_chats` (no lang) - "Greet users"
- `:all_private_chats` + `"es"` - "Saludar usuarios"
- `:all_group_chats` + `"es"` - "Saludar usuarios"

## Full example

```elixir
defmodule MyBot do
  use ExGram.Bot, name: :my_bot, setup_commands: true

  middleware(ExGram.Middleware.IgnoreUsername)

  # Visible to all users in all contexts
  command(:start,
    description: "Start the bot",
    lang: [
      es: [description: "Iniciar el bot"],
      pt: [description: "Iniciar o bot"]
    ]
  )

  # Only visible in private chats, with a translated name for Spanish
  command(:help,
    description: "Get help",
    scopes: [:all_private_chats],
    lang: [es: [command: "ayuda", description: "Obtener ayuda"]]
  )

  # Only visible to group administrators
  command(:ban,
    description: "Ban a user",
    scopes: [:all_chat_administrators],
    lang: [es: [description: "Prohibir usuario"]]
  )

  # Hidden command - no description, won't appear in the menu
  command(:debug)

  def handle({:command, :start, _msg}, context) do
    answer(context, "Welcome! Use /help for a list of commands.")
  end

  # Handles both /help and /ayuda (Spanish alias)
  def handle({:command, :help, _msg}, context) do
    answer(context, "Here is some help!")
  end

  def handle({:command, :ban, %{text: target}}, context) do
    answer(context, "Banned #{target}")
  end

  def handle({:command, :debug, _msg}, context) do
    answer(context, "Debug info: ...")
  end

  def handle(_, _context), do: :ok
end
```