1 files changed, 99 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b81b553
--- /dev/null
+++ b/README.md
@@ -0,0 +1,99 @@
+# 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).