shade-plugins-telegram 0.1.0__py3-none-any.whl

shade_plugins_telegram/__init__.py

@@ -0,0 +1,276 @@
+"""O plugin ``telegram``: enviar mensagem e documento pela Bot API do Telegram, sob o contrato de
+plugin do shade-sdk.
+
+```toml
+[hosts]
+permitidos = ["api.telegram.org"]
+
+[credenciais]
+nomes = ["TELEGRAM_BOT_TOKEN"]
+
+[plugins]
+telegram = "0.1.0"
+```
+
+```python
+import shade_plugins_telegram as telegram
+
+with item.efetivar("avisar o time"):
+    telegram.enviar_mensagem(config["telegram_chat"], f"Pedido {item['pedido']} conferido.")
+
+with item.efetivar("mandar o comprovante"):
+    telegram.enviar_documento(config["telegram_chat"], "saida/comprovante.pdf", legenda="Pronto.")
+```
+
+- **A API não reconhece repetição.** Não há chave de idempotência: um segundo ``POST`` é uma
+  segunda mensagem no chat. Por isso o plugin **nunca repete depois do despacho**, em nenhum
+  erro. Só a falha que prova que nada saiu (conexão recusada, nome que não resolve, rede
+  inalcançável) é tentada de novo, dentro do ``timeout=``. O ``timeout``, a conexão que cai, o
+  ``5xx`` e a resposta sem o identificador da mensagem são ``TelegramIncerto``: o item fica retido
+  para uma pessoa conferir no chat, e o "refazer" só depois de ela ver que a mensagem não chegou.
+  O 4xx é ``TelegramNaoSaiu``: a API recusou, nenhuma mensagem saiu.
+- **Token só por** ``segredo()``: ``TELEGRAM_BOT_TOKEN`` (o do @BotFather). A Bot API o põe no
+  **caminho da URL**, então a URL é um segredo: ela só existe dentro do envio, e toda mensagem de
+  erro mostra o endpoint como ``/bot<token>/sendMessage``. Nunca vai a evento, log nem erro.
+- **Enviar só dentro de** ``item.efetivar()`` (no ensaio não roda).
+- **O que sai do evento e do erro:** a operação, o host, a duração e o status. Nunca o texto, o
+  ``chat_id`` (dado pessoal), o nome do arquivo nem o corpo da resposta; o erro da API chega só
+  pelo código numérico e por uma explicação escrita aqui.
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from shade_sdk.plugins import Plugin
+
+from shade_plugins_telegram import _cliente
+from shade_plugins_telegram._cliente import HOST, Prazo
+from shade_plugins_telegram.erros import TelegramIncerto, TelegramNaoSaiu
+
+__version__ = "0.1.0"
+
+#: A credencial que o plugin lê (``[credenciais] nomes``).
+TOKEN = "TELEGRAM_BOT_TOKEN"
+#: O teto do texto de uma mensagem (a API recusa acima disto).
+TEXTO_MAX = 4096
+#: O teto da legenda de um documento.
+LEGENDA_MAX = 1024
+#: O teto de um documento enviado por bot.
+DOCUMENTO_MAX = 50 * 1024 * 1024
+_CONTROLE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+_CONTROLE_E_BARRAS = re.compile(r"[\x00-\x1f\x7f\"\\/]")
+# O token vai no caminho da URL: só o que o BotFather emite (dígitos, ``:``, letras, ``_``, ``-``).
+_TOKEN = re.compile(r"[A-Za-z0-9:_-]{8,200}")
+_CHAT_NUMERICO = re.compile(r"-?[0-9]{1,20}")
+_CHAT_PUBLICO = re.compile(r"@[A-Za-z][A-Za-z0-9_]{4,31}")
+
+PLUGIN = Plugin(
+    "telegram",
+    __version__,
+    shade_sdk=">=0.22.1,<0.23",
+    dono="Equipe de integrações da ShadeOne",
+    hosts=[HOST],
+    credenciais=[TOKEN],
+)
+
+__all__ = [
+    "PLUGIN",
+    "TelegramIncerto",
+    "TelegramNaoSaiu",
+    "enviar_documento",
+    "enviar_mensagem",
+]
+
+
+def _chat(chat_id: Any) -> int | str:
+    """O destino: o número do chat (``-100...`` nos grupos e canais) ou ``@canal_publico``."""
+    if isinstance(chat_id, bool):
+        raise ValueError("chat_id é o número do chat ou @canal")
+    if isinstance(chat_id, int):
+        return chat_id
+    if isinstance(chat_id, str):
+        if _CHAT_NUMERICO.fullmatch(chat_id):
+            return int(chat_id)
+        if _CHAT_PUBLICO.fullmatch(chat_id):
+            return chat_id
+    raise ValueError("chat_id é o número do chat (ex.: 123456789 ou -1001234567890) ou @canal")
+
+
+def _utf8(valor: str, campo: str) -> str:
+    """Recusa o surrogate solitário: o erro de codificação do Python guardaria o texto inteiro."""
+    try:
+        valor.encode("utf-8")
+        valido = True
+    except UnicodeEncodeError:
+        valido = False
+    if not valido:  # fora do ``except``: o erro de codificação não vira ``__context__``
+        raise ValueError(f"{campo} tem um caractere que não existe em UTF-8")
+    return valor
+
+
+def _porta(porta: Any) -> int | None:
+    if porta is not None and (
+        not isinstance(porta, int) or isinstance(porta, bool) or not 0 < porta < 65536
+    ):
+        raise ValueError(f"porta é um número de 1 a 65535, não {porta!r}")
+    return porta
+
+
+def _token(chamada: Any) -> str:
+    token = chamada.segredo(TOKEN)
+    if not isinstance(token, str) or not _TOKEN.fullmatch(token):
+        # Sem o valor na mensagem: ele vai no caminho da URL.
+        raise ValueError(f"{TOKEN} é o token do BotFather (letras, dígitos, ':', '_' e '-')")
+    return token
+
+
+def _legenda(legenda: Any) -> str | None:
+    if legenda is None:
+        return None
+    if not isinstance(legenda, str) or not legenda.strip():
+        raise ValueError("legenda é um texto não vazio")
+    if len(legenda) > LEGENDA_MAX:
+        raise ValueError(f"legenda passa de {LEGENDA_MAX} caracteres")
+    if _CONTROLE.search(legenda):
+        raise ValueError("legenda não pode ter caractere de controle (fora quebra de linha e tab)")
+    return _utf8(legenda, "legenda")
+
+
+def _arquivo_do_workdir(caminho: Any) -> Path:
+    if not isinstance(caminho, str | os.PathLike):
+        raise TypeError("documento é o caminho de um arquivo do diretório de trabalho")
+    relativo = Path(caminho)
+    raiz = Path.cwd().resolve()
+    completo = (raiz / relativo).resolve()
+    if relativo.is_absolute() or completo != raiz and raiz not in completo.parents:
+        raise ValueError("documento é um caminho dentro do diretório de trabalho")
+    if not completo.is_file():
+        raise FileNotFoundError("documento: não existe no diretório de trabalho")
+    return completo
+
+
+def _nome_do_documento(nome: Any, padrao: str) -> str:
+    """O ``filename`` do multipart. Aspas, barra, barra invertida e controle são recusados, não
+    escapados à mão: o nome vai dentro de um cabeçalho entre aspas."""
+    escolhido = padrao if nome is None else nome
+    if not isinstance(escolhido, str) or not escolhido.strip():
+        raise ValueError("nome é o nome do arquivo no chat, não vazio")
+    if len(_utf8(escolhido, "nome").encode("utf-8")) > 200:
+        raise ValueError("nome passa de 200 bytes")
+    if _CONTROLE_E_BARRAS.search(escolhido):
+        raise ValueError("nome não pode ter aspas, barra, barra invertida nem controle")
+    return escolhido
+
+
+@PLUGIN.efeito
+def enviar_mensagem(
+    chamada: Any,
+    chat_id: int | str,
+    texto: str,
+    *,
+    previa_de_link: bool = False,
+    porta: int | None = None,
+) -> dict[str, int]:
+    """Envia uma mensagem de texto (até 4096 caracteres) ao chat ``chat_id`` (só dentro de
+    ``item.efetivar()``). O texto vai como texto puro, sem ``parse_mode``: ``*``, ``_`` e ``<``
+    não viram formatação. ``previa_de_link`` mostra a prévia do primeiro link. ``porta`` só serve
+    para apontar a um servidor de teste. Devolve ``mensagem_id``.
+
+    Nunca repete depois do despacho. ``TelegramNaoSaiu`` (um ``http.NadaSaiu``): a conexão não
+    abriu ou a API recusou. ``TelegramIncerto``: a mensagem pode ter saído; o item fica retido."""
+    destino = _chat(chat_id)
+    if not isinstance(texto, str) or not texto.strip():
+        raise ValueError("texto é o texto da mensagem, não vazio")
+    if len(texto) > TEXTO_MAX:
+        raise ValueError(f"texto passa de {TEXTO_MAX} caracteres")
+    if _CONTROLE.search(texto):
+        raise ValueError("texto não pode ter caractere de controle (fora quebra de linha e tab)")
+    _utf8(texto, "texto")
+    if not isinstance(previa_de_link, bool):
+        raise ValueError("previa_de_link é verdadeiro ou falso")
+    _porta(porta)
+    corpo = {
+        "chat_id": destino,
+        "text": texto,
+        "link_preview_options": {"is_disabled": not previa_de_link},
+    }
+    token = _token(chamada)
+    dados = json.dumps(corpo, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    identificador = _cliente.enviar(
+        "enviar_mensagem",
+        chamada,
+        "sendMessage",
+        token,
+        dados,
+        "application/json",
+        Prazo(chamada.timeout),
+        porta,
+    )
+    return {"mensagem_id": identificador}
+
+
+@PLUGIN.efeito
+def enviar_documento(
+    chamada: Any,
+    chat_id: int | str,
+    documento: str | os.PathLike[str],
+    *,
+    nome: str | None = None,
+    legenda: str | None = None,
+    tipo: str | None = None,
+    porta: int | None = None,
+) -> dict[str, int]:
+    """Envia um arquivo do diretório de trabalho (até 50 MB) como documento ao chat ``chat_id``
+    (só dentro de ``item.efetivar()``). ``nome`` é o nome que aparece no chat (o do arquivo, se
+    omitido), ``legenda`` o texto de até 1024 caracteres sob ele, ``tipo`` o ``Content-Type``
+    (adivinhado pelo nome). A legenda também vai como texto puro. Devolve ``mensagem_id``.
+
+    Nunca repete depois do despacho. ``TelegramNaoSaiu``: a conexão não abriu ou a API recusou.
+    ``TelegramIncerto``: o documento pode ter saído; o item fica retido."""
+    destino = _chat(chat_id)
+    caminho = _arquivo_do_workdir(documento)
+    nome_no_chat = _nome_do_documento(nome, caminho.name)
+    texto_da_legenda = _legenda(legenda)
+    if tipo is not None and (
+        not isinstance(tipo, str) or not re.fullmatch(r"[a-z0-9.+-]+/[a-z0-9.+-]+", tipo)
+    ):
+        raise ValueError("tipo é o Content-Type, como 'application/pdf'")
+    tipo = tipo or mimetypes.guess_type(nome_no_chat)[0] or "application/octet-stream"
+    _porta(porta)
+    try:
+        tamanho = caminho.stat().st_size
+        conteudo = caminho.read_bytes() if tamanho <= DOCUMENTO_MAX else b""
+        lido = True
+    except OSError:
+        lido = False
+    if not lido:
+        # Fora do ``except``: o erro do SO traria o caminho absoluto e o nome do arquivo.
+        raise FileNotFoundError("documento: não pôde ser lido")
+    if tamanho > DOCUMENTO_MAX:
+        raise ValueError("documento passa de 50 MB, o limite dos bots")
+    if tamanho == 0:
+        raise ValueError("documento está vazio")
+    token = _token(chamada)
+    campos = {"chat_id": str(destino)}
+    if texto_da_legenda is not None:
+        campos["caption"] = texto_da_legenda
+    corpo, tipo_do_corpo = _cliente.corpo_multipart(
+        campos, ("document", nome_no_chat, conteudo, tipo)
+    )
+    identificador = _cliente.enviar(
+        "enviar_documento",
+        chamada,
+        "sendDocument",
+        token,
+        corpo,
+        tipo_do_corpo,
+        Prazo(chamada.timeout),
+        porta,
+    )
+    return {"mensagem_id": identificador}

shade_plugins_telegram/_cliente.py

@@ -0,0 +1,277 @@
+"""O cliente HTTP da Bot API do Telegram: um despacho, no máximo.
+
+Fala com ``https://api.telegram.org/bot<token>/<método>`` (o host que o plugin declara), com
+``chamada.destino()`` antes de conectar. O certificado é verificado; o ``HTTPS_PROXY`` do ambiente
+é respeitado (no sandbox, o proxy da allowlist). Não segue redirecionamento: o token não vai a
+outro host.
+
+**O token está no caminho da URL.** A Bot API não tem cabeçalho de autenticação, então a URL é um
+segredo. Ela só existe dentro de ``enviar``: nenhuma mensagem de erro, evento ou ``__cause__`` a
+leva. Toda menção ao endpoint passa por ``redigir``, e o erro do ``urllib`` (cujo
+``filename``/``url`` carrega a URL inteira) nunca vira a causa de um erro nosso: a decisão é
+tomada fora do ``except``.
+
+**Só se repete o que certamente não saiu.** A API não reconhece repetição, então a regra é uma só:
+a falha que prova que nenhum byte do pedido chegou ao servidor (conexão recusada, nome que não
+resolve, rede inalcançável) é tentada de novo dentro do prazo; qualquer outra coisa, depois de o
+pedido ter podido sair (timeout, conexão que cai, ``5xx``, resposta que não se lê), encerra a
+chamada. Resposta HTTP nunca é repetida: o 4xx diz que a API recusou, e quem quiser enviar de novo
+é o robô, com uma nova decisão.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import secrets
+import ssl
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from shade_sdk import http
+
+from shade_plugins_telegram.erros import TelegramIncerto, TelegramNaoSaiu
+
+HOST = "api.telegram.org"
+#: Quantas vezes o pedido é tentado quando a conexão **não chegou a abrir**.
+TENTATIVAS = 3
+#: A espera antes da 2ª e da 3ª tentativa (a régua do ``shade_sdk.http``).
+ESPERAS = (0.5, 1.0)
+#: O teto do corpo da resposta que o plugin lê (a resposta de sucesso é uma mensagem em JSON).
+RESPOSTA_MAX = 1024 * 1024
+#: O que a ``description`` da Bot API quer dizer, escrito aqui para a mensagem de erro, nunca copiado
+#: do corpo da resposta (que pode repetir o pedido). A chave é um trecho fixo da descrição.
+DICAS: dict[str, str] = {
+    "chat not found": "chat_id desconhecido, ou o bot nunca entrou nesse chat",
+    "bot was blocked by the user": "a pessoa bloqueou o bot",
+    "user is deactivated": "a conta da pessoa foi desativada",
+    "can't initiate conversation": "o bot não pode abrir conversa: a pessoa precisa escrever "
+    "para ele antes (/start)",
+    "not enough rights": "o bot não tem permissão para escrever nesse chat",
+    "have no rights to send": "o bot não tem permissão para escrever nesse chat",
+    "message is too long": "a mensagem passa do limite de 4096 caracteres",
+    "message text is empty": "o texto da mensagem está vazio",
+    "file is too big": "o arquivo passa do limite de 50 MB dos bots",
+    "too many requests": "limite de mensagens do bot: espere o retry_apos",
+    "unauthorized": "token do bot inválido ou revogado",
+}
+
+
+class Prazo:
+    """O ``timeout`` da chamada como um prazo só: cada etapa usa o que sobrou."""
+
+    def __init__(self, segundos: float) -> None:
+        self.fim = time.monotonic() + segundos
+
+    def restante(self) -> float:
+        sobra = self.fim - time.monotonic()
+        if sobra <= 0:
+            raise TimeoutError("o prazo da chamada acabou")
+        return sobra
+
+    def cabe(self, espera: float) -> bool:
+        return self.fim - time.monotonic() > espera
+
+
+def redigir(texto: str, token: str) -> str:
+    """``texto`` sem o token do caminho ``/bot<token>/``: é o que entra em mensagem de erro e em
+    qualquer registro. Só o caminho é trocado, para um token curto não casar com o host."""
+    return texto.replace(f"/bot{token}/", "/bot<token>/")
+
+
+def corpo_multipart(
+    campos: dict[str, str], arquivo: tuple[str, str, bytes, str]
+) -> tuple[bytes, str]:
+    """O ``multipart/form-data`` de um envio de documento: (corpo, ``Content-Type``).
+
+    ``arquivo`` é (campo, nome, conteúdo, tipo). Nome e campos já chegam validados (sem aspas,
+    barra invertida nem controle); a fronteira é sorteada até não aparecer no conteúdo."""
+    while True:
+        fronteira = "shade" + secrets.token_hex(16)
+        marca = fronteira.encode()
+        campo, nome, conteudo, tipo = arquivo
+        partes: list[bytes] = []
+        for chave, valor in campos.items():
+            partes.append(
+                f'--{fronteira}\r\nContent-Disposition: form-data; name="{chave}"\r\n\r\n'.encode()
+                + valor.encode("utf-8")
+                + b"\r\n"
+            )
+        partes.append(
+            f'--{fronteira}\r\nContent-Disposition: form-data; name="{campo}"; '
+            f'filename="{nome}"\r\nContent-Type: {tipo}\r\n\r\n'.encode()
+            + conteudo
+            + b"\r\n"
+        )
+        partes.append(f"--{fronteira}--\r\n".encode())
+        corpo = b"".join(partes)
+        if corpo.count(marca) == len(campos) + 2:  # só as fronteiras que nós pusemos
+            return corpo, f"multipart/form-data; boundary={fronteira}"
+
+
+class _SemRedirecionamento(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+def _abridor() -> Callable[..., Any]:
+    contexto = ssl.create_default_context()
+    contexto.minimum_version = ssl.TLSVersion.TLSv1_2
+    return urllib.request.build_opener(
+        urllib.request.ProxyHandler(),
+        urllib.request.HTTPSHandler(context=contexto),
+        _SemRedirecionamento(),
+    ).open
+
+
+@dataclass
+class Resposta:
+    status: int
+    corpo: bytes
+
+
+def _json_do_corpo(corpo: bytes) -> dict[str, Any]:
+    try:
+        dados = json.loads(corpo[:65536])
+    except (ValueError, RecursionError):  # o corpo de um intermediário pode ser um `[[[[...`
+        return {}
+    return dados if isinstance(dados, dict) else {}
+
+
+def _inteiro(valor: Any) -> int | None:
+    return valor if isinstance(valor, int) and not isinstance(valor, bool) else None
+
+
+def _pode_repetir(motivo: Any) -> bool:
+    """A falha que **prova** que nada chegou ao servidor e em que repetir pode dar certo. O
+    certificado inválido e o túnel recusado pelo proxy não melhoram com o tempo."""
+    if isinstance(motivo, ssl.SSLCertVerificationError):
+        return False
+    return not str(motivo).startswith("Tunnel connection failed")
+
+
+def _despachar(abrir: Callable[..., Any], pedido: Any, tempo: float) -> Resposta:
+    try:
+        with abrir(pedido, timeout=tempo) as resposta:
+            return Resposta(resposta.status, resposta.read(RESPOSTA_MAX))
+    except urllib.error.HTTPError as exc:
+        try:
+            corpo = exc.read(65536) if exc.fp else b""
+        except (OSError, http.client.HTTPException):
+            corpo = b""  # o status já diz que a API recusou; o corpo só traria o código
+        return Resposta(exc.code, corpo)
+
+
+def enviar(
+    operacao: str,
+    chamada: Any,
+    metodo: str,
+    token: str,
+    conteudo: bytes,
+    tipo: str,
+    prazo: Prazo,
+    porta: int | None,
+) -> int:
+    """Despacha ``conteudo`` em ``/bot<token>/<metodo>`` e devolve o ``message_id``.
+
+    ``TelegramNaoSaiu`` se nada saiu; ``TelegramIncerto`` se pode ter saído. Nenhum dos dois
+    carrega o token, a URL com ele nem o erro do ``urllib`` como causa."""
+    chamada.destino(HOST)
+    autoridade = HOST if porta in (None, 443) else f"{HOST}:{porta}"
+    url = f"https://{autoridade}/bot{token}/{metodo}"
+    endpoint = redigir(url, token)
+    cabecalhos = {
+        "Content-Type": tipo,
+        "Accept": "application/json",
+        # A Bot API ignora a chave (não há idempotência nela); quem observa o tráfego, o proxy e o
+        # servidor falso dos testes, distingue a execução.
+        "Idempotency-Key": chamada.idempotencia,
+    }
+    abrir = _abridor()
+    for tentativa in range(1, TENTATIVAS + 1):
+        try:
+            tempo = prazo.restante()
+        except TimeoutError:
+            tempo = None
+        if tempo is None:
+            raise TelegramNaoSaiu(
+                f"Telegram {operacao}: o prazo acabou antes de a conexão abrir ({endpoint})"
+            )
+        pedido = urllib.request.Request(url, data=conteudo, headers=cabecalhos, method="POST")
+        resposta: Resposta | None = None
+        falha: BaseException | None = None
+        try:
+            resposta = _despachar(abrir, pedido, tempo)
+        except Exception as exc:
+            falha = exc
+        if falha is None and resposta is not None:
+            return _identificador(operacao, endpoint, resposta)
+        # A decisão fica fora do ``except``: nenhum erro nosso nasce com o do ``urllib`` (e a URL
+        # com o token que ele guarda) como ``__context__``.
+        assert falha is not None
+        if not http.nada_saiu(falha):
+            tipo_da_falha = type(falha).__name__
+            falha = None
+            raise TelegramIncerto(
+                f"Telegram {operacao}: a conexão falhou depois do envio ({tipo_da_falha}); "
+                f"a mensagem pode ter saído ({endpoint})"
+            )
+        motivo = getattr(falha, "reason", falha)
+        espera = ESPERAS[min(tentativa - 1, len(ESPERAS) - 1)]
+        repetir = tentativa < TENTATIVAS and _pode_repetir(motivo) and prazo.cabe(espera)
+        nome_do_motivo = type(motivo).__name__
+        falha = None
+        if repetir:
+            time.sleep(espera)
+            continue
+        raise TelegramNaoSaiu(
+            f"Telegram {operacao}: a conexão não abriu ({nome_do_motivo}; {endpoint})"
+        )
+    raise AssertionError("o laço de tentativas sempre retorna ou levanta")  # pragma: no cover
+
+
+def _dica(descricao: Any) -> str:
+    if not isinstance(descricao, str):
+        return ""
+    minuscula = descricao.lower()
+    for trecho, dica in DICAS.items():
+        if trecho in minuscula:
+            return f": {dica}"
+    return ""
+
+
+def _identificador(operacao: str, endpoint: str, resposta: Resposta) -> int:
+    """O ``result.message_id`` de uma resposta 2xx; o resto é recusa (4xx) ou dúvida."""
+    dados = _json_do_corpo(resposta.corpo)
+    if 200 <= resposta.status < 300:
+        resultado = dados.get("result")
+        achado = _inteiro(resultado.get("message_id")) if isinstance(resultado, dict) else None
+        if dados.get("ok") is True and achado is not None:
+            return achado
+        raise TelegramIncerto(
+            f"Telegram {operacao}: a API respondeu {resposta.status} sem o identificador da "
+            f"mensagem; ela pode ter saído ({endpoint})"
+        )
+    codigo = _inteiro(dados.get("error_code"))
+    parametros = dados.get("parameters")
+    retry_apos = _inteiro(parametros.get("retry_after")) if isinstance(parametros, dict) else None
+    sufixo = f", código {codigo}" if codigo is not None else ""
+    sufixo += _dica(dados.get("description"))
+    if retry_apos is not None:
+        sufixo += f", retry_apos {retry_apos} s"
+    if 400 <= resposta.status < 500:
+        raise TelegramNaoSaiu(
+            f"Telegram {operacao}: a API recusou o pedido ({resposta.status}{sufixo}; {endpoint})",
+            status=resposta.status,
+            codigo=codigo,
+            retry_apos=retry_apos,
+        )
+    raise TelegramIncerto(
+        f"Telegram {operacao}: a API devolveu {resposta.status}{sufixo}; a mensagem pode ter "
+        f"saído ({endpoint})",
+        status=resposta.status,
+    )

shade_plugins_telegram/erros.py

@@ -0,0 +1,44 @@
+"""Os erros do plugin ``telegram``.
+
+A Bot API do Telegram **não reconhece repetição**: não há chave de idempotência, e um segundo
+``POST`` com o mesmo conteúdo é uma segunda mensagem no chat. Por isso os erros separam só duas
+coisas, e o plugin nunca repete o que passou da primeira:
+
+- ``TelegramNaoSaiu`` (um ``http.NadaSaiu``): **certamente** nenhuma mensagem saiu. A conexão não
+  chegou a abrir, ou a API recusou o pedido (4xx) antes de aceitá-lo.
+- ``TelegramIncerto`` (um ``http.ResultadoIncerto``): o pedido pode ter chegado e a confirmação
+  não veio (timeout, conexão que caiu, ``5xx``, resposta sem o identificador da mensagem). A
+  mensagem pode estar no chat. O item fica retido para uma pessoa conferir; reenviar sozinho é a
+  duplicata que este plugin existe para não fazer.
+
+As mensagens dizem a operação, o endpoint **sem o token** (a Bot API o põe no caminho da URL), o
+status HTTP e o código da API, nunca o corpo, o texto, o ``chat_id`` nem o token.
+"""
+
+from __future__ import annotations
+
+from shade_sdk import http
+
+
+class TelegramNaoSaiu(http.NadaSaiu):
+    """Certamente sem mensagem: a conexão não abriu ou a API recusou o pedido (4xx).
+
+    ``codigo`` é o ``error_code`` da Bot API e ``retry_apos`` os segundos que ela pede de espera
+    (429), quando vieram."""
+
+    def __init__(
+        self,
+        mensagem: str,
+        *,
+        status: int | None = None,
+        codigo: int | None = None,
+        retry_apos: int | None = None,
+    ):
+        super().__init__(mensagem, status=status)
+        self.codigo = codigo
+        self.retry_apos = retry_apos
+
+
+class TelegramIncerto(http.ResultadoIncerto):
+    """Pode ter saído: o pedido foi despachado e a confirmação não veio. Conferir no chat antes de
+    reenviar."""

shade_plugins_telegram-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: shade-plugins-telegram
+Version: 0.1.0
+Summary: Enviar mensagem e documento pela Bot API do Telegram, sem nunca repetir um envio depois de despachado.
+Author: ShadeOne
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: shade-sdk<0.23,>=0.22.1
+Description-Content-Type: text/markdown
+
+# shade-plugins-telegram
+
+Envia mensagem e documento pela [Bot API do Telegram](https://core.telegram.org/bots/api), de
+dentro de um robô do [`shade-sdk`](https://pypi.org/project/shade-sdk/). Só a biblioteca padrão do
+Python: nenhuma dependência além do `shade-sdk`.
+
+No `shade.toml` do robô, o host da API vai em `[hosts] permitidos` e o token do bot em
+`[credenciais]`:
+
+```toml
+[hosts]
+permitidos = ["api.telegram.org"]
+
+[credenciais]
+nomes = ["TELEGRAM_BOT_TOKEN"]
+
+[plugins]
+telegram = "0.1.0"
+```
+
+```python
+import shade_plugins_telegram as telegram
+
+# Escrita: só dentro de item.efetivar() (no ensaio não roda).
+with item.efetivar("avisar o time"):
+    telegram.enviar_mensagem(config["telegram_chat"], f"Pedido {item['pedido']} conferido.")
+
+with item.efetivar("mandar o comprovante"):
+    telegram.enviar_documento(
+        config["telegram_chat"],  # o número do chat, ou @canal
+        "saida/comprovante.pdf",  # um arquivo do diretório de trabalho do robô
+        legenda="Segue o comprovante.",
+    )
+```
+
+## A conta
+
+- **Token:** o token que o [@BotFather](https://t.me/BotFather) entrega ao criar o bot. Guarde-o
+  como a credencial `TELEGRAM_BOT_TOKEN`; o plugin o lê só por `segredo()`.
+- **`chat_id`:** o número do chat (positivo para conversa com uma pessoa, `-100...` para grupo e
+  canal) ou `@canal_publico`. Não é segredo, mas identifica uma pessoa: guarde-o no `[config]` do
+  robô e não o ponha em log. O bot só escreve a quem já falou com ele (`/start`) e nos grupos e
+  canais em que foi adicionado.
+- **Texto puro:** a mensagem e a legenda vão sem `parse_mode`, então `*`, `_` e `<` aparecem como
+  são. Formatação (Markdown, HTML) não é suportada nesta versão, nem botão, foto, áudio ou
+  resposta a outra mensagem.
+- **Documento:** até 50 MB, do diretório de trabalho do robô (caminho relativo). `nome` troca o
+  nome que aparece no chat (sem aspas, barras nem controle: o que não serve é recusado, não
+  escapado), `legenda` leva até 1024 caracteres.
+
+## O que o plugin garante
+
+- **Nunca envia duas vezes.** A Bot API não reconhece repetição: não há chave de idempotência, e
+  um segundo pedido é uma segunda mensagem no chat. Por isso o plugin **não repete depois do
+  despacho, em nenhum erro**:
+  - A conexão que não chegou a abrir (recusada, nome que não resolve, rede inalcançável) é tentada
+    de novo, dentro do `timeout=`, porque nada saiu.
+  - A API que recusou (4xx) é `TelegramNaoSaiu`: nenhuma mensagem saiu. O `codigo` vem em
+    `erro.codigo` e, no limite de envio (429), o `retry_apos` em segundos. O plugin não espera
+    nem repete sozinho: a espera é decisão do robô.
+  - O que sobra é `TelegramIncerto`: o `timeout`, a conexão que cai depois do envio, o `5xx` e a
+    resposta de sucesso sem o `message_id`. A mensagem **pode** estar no chat. O item fica
+    retido para uma pessoa conferir no chat e, só se a mensagem não chegou, mandar refazer. O
+    plugin não reenvia sozinho, e uma nova execução do robô também não.
+- **O token não aparece em lugar nenhum.** A Bot API o põe no **caminho da URL**
+  (`/bot<token>/sendMessage`), então a URL é um segredo: ela só existe dentro do envio. Mensagem
+  de erro, evento e relatório mostram o endpoint como `/bot<token>/sendMessage`, e o erro do
+  `urllib` (que guarda a URL inteira) nunca é a causa de um erro do plugin.
+- **Só dentro de `item.efetivar()`.** Fora dele, a operação é um erro de contrato antes de qualquer
+  byte; no ensaio, o bloco é pulado e nada é enviado.
+- **Host e prazo:** só `api.telegram.org`, com o certificado verificado, sem seguir
+  redirecionamento; toda chamada aceita `timeout=` (30 s por padrão), que vale para a chamada
+  inteira.
+- **Sem dado pessoal em evento nem em erro:** cada chamada emite um evento com a operação, o host,
+  a duração e o status. Nunca o texto, o `chat_id`, o nome do arquivo nem o corpo da resposta; o
+  erro da API chega só pelo código numérico e por uma explicação escrita no plugin.
+
+## Operações
+
+| Operação | Efeito | O que faz |
+|---|---|---|
+| `enviar_mensagem(chat_id, texto, *, previa_de_link=False)` | sim | Mensagem de texto de até 4096 caracteres. |
+| `enviar_documento(chat_id, documento, *, nome=None, legenda=None, tipo=None)` | sim | Arquivo do diretório de trabalho como documento. |
+
+As duas devolvem `{"mensagem_id": 1234}`.
+
+## Testes
+
+A suíte de contrato do `shade_sdk.testing.plugins` e um servidor falso da Bot API (TLS de uma CA de
+teste, com o token no caminho como na de verdade) acompanham o código-fonte em `tests/`. O servidor
+falso não reconhece repetição, como a API de verdade.

shade_plugins_telegram-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+shade_plugins_telegram/__init__.py,sha256=neNpQIEfQY6N8YpfUrfw9K4pbG5bzamKHJsU5TdP7vs,10723
+shade_plugins_telegram/_cliente.py,sha256=P7rLFZdCacPk6iJXKeMmYoTN9aj2iTaHcJTX8zuYEfk,11468
+shade_plugins_telegram/erros.py,sha256=FhQCvxRc91GBwTbhO5ObSNZA0oOnSYd7XIhIz2ZEJqM,1783
+shade_plugins_telegram-0.1.0.dist-info/METADATA,sha256=BfA2f3UHxDmWoJax5we0XOzgNV0J1uXMRe_0BalieVA,5022
+shade_plugins_telegram-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+shade_plugins_telegram-0.1.0.dist-info/entry_points.txt,sha256=yLNbMh82iCTb3QWOQrpsbpzWuS6yCyrvYZcTRP3bUiQ,61
+shade_plugins_telegram-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+shade_plugins_telegram-0.1.0.dist-info/RECORD,,

shade_plugins_telegram-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

shade_plugins_telegram-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[shade_sdk.plugins]
+telegram = shade_plugins_telegram:PLUGIN

shade_plugins_telegram-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.