# cepis-telegram

Bot de Telegram para consulta de CEP, sobre a API pública da
[cep.is](https://cep.is) — base oficial dos Correios (DNE), atualizada a cada
quinzena.

Escrito em Go, usa o cliente oficial [`cep.is/go`](https://cep.is/go) e recebe
as mensagens por *long polling*: não precisa de porta aberta, de hostname
público nem de segredo de webhook.

## O que ele faz

| onde | como se usa |
| --- | --- |
| conversa privada | manda o CEP direto: `01001000` ou `01001-000` |
| grupos e canais | `/cep 01001000` — e também `/cep@seubot 01001000` |
| qualquer conversa | `@seubot 01001000` (modo inline, sem precisar adicionar o bot) |

Também responde `/start` e `/help`.

A resposta traz o endereço formatado e, quando o CEP tem coordenada, distingue
os dois casos: com precisão de logradouro sai um link de mapa; quando o CEP é
geral do município, sai um aviso com o raio da área em vez de um pino, porque o
ponto é o centroide da cidade e pode errar dezenas de quilómetros.

## Criando o bot

O username e o token são criados por você no
[@BotFather](https://t.me/BotFather) e pertencem a você — este repositório não
contém nem nunca deve conter um token.

1. `/newbot` no @BotFather, escolha nome e username. Guarde o token.
2. `/setinline` no @BotFather, para o mesmo bot, com um texto de placeholder
   (por exemplo `01001000`). Sem isso o modo inline fica desligado.
3. Opcional, `/setcommands`:

   ```
   cep - consulta um CEP
   help - como usar
   ```

O *privacy mode* pode continuar ligado (é o padrão). Em grupos o bot só recebe
os comandos endereçados a ele, que é exatamente o que ele precisa.

## Rodando

```sh
export TELEGRAM_BOT_TOKEN=... # o token do @BotFather
make build
./bin/cepis-telegram
```

Em container:

```sh
docker build -t cepis-telegram .
docker run --rm -e TELEGRAM_BOT_TOKEN=... cepis-telegram
```

Só uma instância por token: o Telegram entrega cada update uma única vez, e dois
processos com o mesmo token disputam os mesmos updates.

## Configuração

Tudo vem do ambiente.

| variável | padrão | o que faz |
| --- | --- | --- |
| `TELEGRAM_BOT_TOKEN` | — | obrigatória; o processo aborta na partida sem ela |
| `CEPIS_BASE_URL` | `https://cep.is` | aponta as consultas para outra instância da API |
| `TELEGRAM_API_BASE_URL` | `https://api.telegram.org` | aponta o bot para outro host da Bot API |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn` ou `error` |

Os logs saem em JSON no stdout. O token nunca aparece neles, e o conteúdo das
mensagens dos usuários não é registrado.

Há um limite por usuário de 5 consultas em rajada e uma a cada 3 segundos
depois disso.

## Desenvolvimento

```sh
make            # lista os alvos
make test       # sobe um Telegram falso e uma cep.is falsa, em processo
make lint       # gofmt -l + go vet, não escreve nada
make format     # aplica o gofmt
make check      # lint + test + build
```

Para testar contra uma cep.is local (o repositório da API sobe uma com
`just up`):

```sh
CEPIS_BASE_URL=http://localhost:8080 TELEGRAM_BOT_TOKEN=... ./bin/cepis-telegram
```

## Licença

ISC. Veja [LICENSE](LICENSE).