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

shade_plugins_slack/__init__.py

@@ -0,0 +1,307 @@
+"""O plugin ``slack``: listar os canais e enviar mensagem no Slack, pela Web API, sob o contrato de
+plugin do shade-sdk, com o token OAuth da conexão da plataforma.
+
+```toml
+[hosts]
+permitidos = ["slack.com"]
+
+[conexoes]
+nomes = ["slack"]
+
+[plugins]
+slack = "0.1.0"
+```
+
+```python
+import shade_plugins_slack as slack
+
+canal = next(c["id"] for c in slack.listar_canais() if c["nome"] == "financeiro")
+
+with item.efetivar("avisar o time"):
+    slack.enviar_mensagem(canal, f"Pedido {item['pedido']} conferido.")
+```
+
+- **Conta:** a conexão ``slack`` da plataforma (Conectores). O robô nunca vê a senha nem o
+  refresh token: o token de acesso chega sob demanda e é renovado pela plataforma. No laptop, ponha
+  um token de acesso em ``SHADE_TOKEN_SLACK``. Os escopos são ``channels:read``, ``chat:write`` e
+  ``channels:history``; o app precisa estar no canal para ler o histórico e postar.
+- **Ler não muda nada:** ``listar_canais`` roda inclusive no ensaio.
+- **Escrever só dentro de** ``item.efetivar()`` (no ensaio não roda). ``enviar_mensagem`` não
+  duplica: a mensagem leva no ``metadata`` a chave do item, e antes de postar o plugin lê o
+  histórico recente do canal e devolve a mensagem que já tiver a chave. Depois que o envio saiu
+  sem confirmação, o plugin não posta de novo: ele confere o histórico e, sem achar, o erro é
+  ``SlackIncerto`` (o item fica retido para conferência).
+- **Prazo:** ``timeout=`` (30 s) vale para a chamada inteira, retentativas incluídas.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any
+
+from shade_sdk.plugins import Plugin
+
+from shade_plugins_slack import _cliente
+from shade_plugins_slack._cliente import CONEXAO, SLACK, Cliente, Prazo
+from shade_plugins_slack.erros import ErroDoSlack, NaoEncontrado, SlackIncerto, SlackNaoSaiu
+
+__version__ = "0.1.0"
+
+#: O ``event_type`` do ``metadata`` das mensagens do plugin: o histórico se lê por ele.
+EVENTO_DA_MENSAGEM = "shade_item"
+#: Quantos canais ``listar_canais`` devolve, no máximo, e quantos o Slack dá por página.
+LIMITE_CANAIS_MAX = 10_000
+POR_PAGINA = 200
+#: Quantas páginas de canais e de histórico o plugin percorre.
+PAGINAS_DE_CANAIS_MAX = 50
+#: O histórico recente que se lê atrás da chave antes de postar: 5 páginas de 100 mensagens.
+PAGINAS_DE_HISTORICO = 5
+POR_PAGINA_DE_HISTORICO = 100
+#: O teto do texto (o Slack corta em 40 000 caracteres).
+TEXTO_MAX = 40_000
+_CONTROLE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+#: O id de um canal público (``C...``), privado ou grupo antigo (``G...``) ou conversa (``D...``).
+_CANAL = re.compile(r"^[CGD][A-Z0-9]{6,30}$")
+_CURSOR = re.compile(r"^[A-Za-z0-9+/=_\-%.]{1,512}$")
+
+PLUGIN = Plugin(
+    "slack",
+    __version__,
+    shade_sdk=">=0.22.3,<0.23",
+    dono="Equipe de integrações da ShadeOne",
+    hosts=[SLACK],
+    conexoes=[CONEXAO],
+)
+
+__all__ = [
+    "PLUGIN",
+    "ErroDoSlack",
+    "NaoEncontrado",
+    "SlackIncerto",
+    "SlackNaoSaiu",
+    "enviar_mensagem",
+    "listar_canais",
+]
+
+
+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 _canal(valor: Any) -> str:
+    if not isinstance(valor, str) or not _CANAL.fullmatch(valor):
+        raise ValueError(
+            "canal é o id do canal (como C0123ABCD, o que listar_canais devolve), não o nome"
+        )
+    return valor
+
+
+def _limite(valor: Any, maximo: int) -> int:
+    if not isinstance(valor, int) or isinstance(valor, bool) or not 0 < valor <= maximo:
+        raise ValueError(f"limite é um número de 1 a {maximo}")
+    return valor
+
+
+def _texto_do_slack(texto: Any) -> str:
+    """O texto do item como o Slack o quer: ``&``, ``<`` e ``>`` viram as entidades que a Web API
+    documenta, para que ``<!channel>``, ``<@U123>`` e ``<http://...|texto>`` que vierem de um dado
+    não virem menção nem link."""
+    if not isinstance(texto, str) or not texto.strip() or len(texto) > TEXTO_MAX:
+        raise ValueError(f"texto é uma mensagem de 1 a {TEXTO_MAX} caracteres")
+    if _CONTROLE.search(texto):
+        raise ValueError("texto não pode ter caractere de controle (a não ser quebra de linha)")
+    return texto.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _cliente_da_chamada(chamada: Any, porta: Any) -> Cliente:
+    return Cliente(chamada=chamada, prazo=Prazo(chamada.timeout), porta=_porta(porta))
+
+
+def _lendo(operacao: str, funcao: Callable[[], Any]) -> Any:
+    """A falha de rede no meio da leitura vira ``ErroDoSlack``."""
+    try:
+        return funcao()
+    except ErroDoSlack:
+        raise
+    except OSError as exc:
+        raise _cliente.falha_de_leitura(operacao, exc) from exc
+
+
+def _proximo_cursor(dados: dict[str, Any]) -> str:
+    meta = dados.get("response_metadata")
+    cursor = meta.get("next_cursor") if isinstance(meta, dict) else ""
+    return cursor if isinstance(cursor, str) and _CURSOR.fullmatch(cursor) else ""
+
+
+# ── Canais ───────────────────────────────────────────────────────────────────────────────
+
+
+def _resumo_do_canal(canal: dict[str, Any]) -> dict[str, Any]:
+    membros = canal.get("num_members")
+    return {
+        "id": canal.get("id", ""),
+        "nome": canal.get("name", ""),
+        "arquivado": bool(canal.get("is_archived")),
+        "membro": bool(canal.get("is_member")),
+        "membros": membros if isinstance(membros, int) and not isinstance(membros, bool) else None,
+    }
+
+
+@PLUGIN.operacao
+def listar_canais(
+    chamada: Any,
+    *,
+    limite: int = 1_000,
+    arquivados: bool = False,
+    porta: int | None = None,
+) -> list[dict[str, Any]]:
+    """Os canais públicos do workspace, até ``limite``, seguindo o cursor do Slack. Cada um: ``id``
+    (o que ``enviar_mensagem`` pede), ``nome``, ``arquivado``, ``membro`` (o app está no canal) e
+    ``membros``. ``arquivados=True`` inclui os arquivados. Nada muda no Slack."""
+    limite = _limite(limite, LIMITE_CANAIS_MAX)
+    if not isinstance(arquivados, bool):
+        raise ValueError("arquivados é verdadeiro ou falso")
+    cliente = _cliente_da_chamada(chamada, porta)
+
+    def ler() -> list[dict[str, Any]]:
+        achados: list[dict[str, Any]] = []
+        cursor = ""
+        for _ in range(PAGINAS_DE_CANAIS_MAX):
+            parametros = {
+                "types": "public_channel",
+                "exclude_archived": "false" if arquivados else "true",
+                "limit": str(min(POR_PAGINA, limite)),
+            }
+            if cursor:
+                parametros["cursor"] = cursor
+            resposta = cliente.pedir("conversations.list", parametros=parametros)
+            dados = _cliente.checar_leitura("listar_canais", resposta)
+            for canal in dados.get("channels") or []:
+                if isinstance(canal, dict):
+                    achados.append(_resumo_do_canal(canal))
+                    if len(achados) >= limite:
+                        return achados
+            proximo = _proximo_cursor(dados)
+            if not proximo or proximo == cursor:
+                break
+            cursor = proximo
+        return achados
+
+    return _lendo("listar_canais", ler)
+
+
+# ── Mensagem ─────────────────────────────────────────────────────────────────────────────
+
+
+def _mensagem_com_a_chave(cliente: Cliente, canal: str, chave: str) -> dict[str, Any] | None:
+    """A mensagem recente do canal cujo ``metadata`` leva esta chave. Sem ler o histórico não se
+    posta: a falha daqui é ``SlackNaoSaiu`` (o token que não veio já é um ``http.NadaSaiu``)."""
+    cursor = ""
+    for _ in range(PAGINAS_DE_HISTORICO):
+        parametros = {
+            "channel": canal,
+            "limit": str(POR_PAGINA_DE_HISTORICO),
+            "include_all_metadata": "true",
+        }
+        if cursor:
+            parametros["cursor"] = cursor
+        try:
+            resposta = cliente.pedir(
+                "conversations.history", parametros=parametros, idempotencia=chave
+            )
+            if not resposta.ok:
+                raise _cliente.recusa_antes_de_postar("enviar_mensagem", resposta)
+            dados = resposta.dados()
+        except (ErroDoSlack, OSError) as exc:
+            if isinstance(exc, SlackNaoSaiu):
+                raise
+            raise SlackNaoSaiu(
+                f"Slack enviar_mensagem: o histórico do canal não foi lido ({type(exc).__name__}); "
+                "nada foi postado"
+            ) from exc
+        for mensagem in dados.get("messages") or []:
+            if _leva_a_chave(mensagem, chave):
+                return mensagem
+        proximo = _proximo_cursor(dados)
+        if not dados.get("has_more") or not proximo or proximo == cursor:
+            break
+        cursor = proximo
+    return None
+
+
+def _leva_a_chave(mensagem: Any, chave: str) -> bool:
+    if not isinstance(mensagem, dict):
+        return False
+    metadata = mensagem.get("metadata")
+    if not isinstance(metadata, dict) or metadata.get("event_type") != EVENTO_DA_MENSAGEM:
+        return False
+    payload = metadata.get("event_payload")
+    return isinstance(payload, dict) and payload.get("chave") == chave
+
+
+def _resultado(canal: str, ts: Any, *, reaproveitada: bool) -> dict[str, Any]:
+    return {"canal": canal, "ts": ts if isinstance(ts, str) else "", "reaproveitada": reaproveitada}
+
+
+def _postar(cliente: Cliente, canal: str, texto: str, chave: str) -> dict[str, Any]:
+    """O ``chat.postMessage``. Depois de despachado, nada o repete: a dúvida confere o histórico
+    e, sem achar, é ``SlackIncerto``."""
+    corpo = {
+        "channel": canal,
+        "text": texto,
+        "mrkdwn": False,
+        "metadata": {"event_type": EVENTO_DA_MENSAGEM, "event_payload": {"chave": chave}},
+    }
+    try:
+        resposta = cliente.pedir(
+            "chat.postMessage", corpo=corpo, idempotencia=chave, repetir_depois_do_envio=False
+        )
+        dados = _cliente.checar_escrita("enviar_mensagem", resposta)
+        return _resultado(canal, dados.get("ts"), reaproveitada=False)
+    except SlackIncerto as incerto:
+        duvida: Exception = incerto
+    except OSError as exc:
+        duvida = _cliente.falha_de_escrita("enviar_mensagem", exc)
+        if isinstance(duvida, SlackNaoSaiu):
+            raise duvida from exc
+    # A mensagem pode ter saído: o que a confirma é o histórico.
+    try:
+        achada = _mensagem_com_a_chave(cliente, canal, chave)
+    except SlackNaoSaiu:
+        achada = None
+    if achada is None:
+        raise duvida
+    return _resultado(canal, achada.get("ts"), reaproveitada=True)
+
+
+@PLUGIN.efeito
+def enviar_mensagem(
+    chamada: Any,
+    canal: str,
+    texto: str,
+    *,
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Posta ``texto`` no canal (o id que ``listar_canais`` devolve), só dentro de
+    ``item.efetivar()``. O texto é literal: ``&``, ``<`` e ``>`` vão como entidade, e menção ou
+    link vindos de um dado não disparam. Devolve ``canal``, ``ts`` (o id da mensagem no canal) e
+    ``reaproveitada`` (``True`` quando a mensagem desta mesma chamada já estava no histórico).
+
+    Não duplica: a mensagem leva a chave do item no ``metadata`` e, antes de postar, o plugin lê as
+    últimas mensagens do canal e devolve a que tiver a chave. ``SlackNaoSaiu``: nada foi postado
+    (o Slack recusou, a rede não abriu, o histórico não foi lido, inclusive a conexão sem
+    ``channels:history``). ``SlackIncerto``: o envio saiu sem confirmação e a mensagem não está
+    no histórico; o plugin não posta de novo."""
+    canal = _canal(canal)
+    texto = _texto_do_slack(texto)
+    chave = chamada.idempotencia
+    cliente = _cliente_da_chamada(chamada, porta)
+    existente = _mensagem_com_a_chave(cliente, canal, chave)
+    if existente is not None:
+        return _resultado(canal, existente.get("ts"), reaproveitada=True)
+    return _postar(cliente, canal, texto, chave)

shade_plugins_slack/_cliente.py

@@ -0,0 +1,321 @@
+"""O cliente HTTP da Web API do Slack: o token da conexão, o prazo da chamada e a retentativa.
+
+Fala só com ``slack.com`` (o host que o plugin declara), sempre com ``chamada.destino(host)`` 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 Slack responde ``200`` com ``{"ok": false, "error": "..."}`` até no erro de autenticação. O token
+vem de ``chamada.token(CONEXAO)``; o ``401`` e o ``token_expired``/``invalid_auth`` (o token
+expirou ou foi revogado antes da hora) trocam o token uma vez (``renovar=True``) e repetem: o pedido
+recusado não teve efeito.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from shade_sdk import http
+
+from shade_plugins_slack.erros import ErroDoSlack, NaoEncontrado, SlackIncerto, SlackNaoSaiu
+
+#: A conexão OAuth da plataforma de que o plugin pede o token (o provedor do catálogo).
+CONEXAO = "slack"
+SLACK = "slack.com"
+RAIZ = "/api"
+#: Quantas vezes o pedido é tentado quando a rede ou o Slack falham de forma transitória.
+TENTATIVAS = 3
+#: A espera antes da 2ª e da 3ª tentativa (a régua do ``shade_sdk.http``).
+ESPERAS = (0.5, 1.0)
+#: O maior ``Retry-After`` que o plugin honra; acima disso, devolve o que recebeu.
+ESPERA_MAX = 10.0
+#: O teto do corpo de uma resposta lida na memória.
+RESPOSTA_MAX = 8 * 1024 * 1024
+#: O que o Slack põe em ``error``: um nome curto, nunca o texto do pedido.
+_CODIGO = re.compile(r"^[a-z0-9_]{1,64}$")
+#: Os erros de autenticação em que um token novo pode resolver; o pedido não teve efeito.
+RENOVAVEIS = frozenset({"token_expired", "invalid_auth", "not_authed"})
+#: Os erros do servidor do Slack em que não se sabe se a mensagem foi postada.
+DO_SERVIDOR = frozenset(
+    {"internal_error", "fatal_error", "service_unavailable", "request_timeout", "internal"}
+)
+
+
+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
+
+
+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
+    cabecalhos: Mapping[str, str]
+    corpo: bytes = b""
+
+    def cabecalho(self, nome: str) -> str:
+        for chave, valor in self.cabecalhos.items():
+            if chave.lower() == nome.lower():
+                return valor
+        return ""
+
+    def dados(self) -> dict[str, Any]:
+        try:
+            dados = json.loads(self.corpo)
+        except ValueError as exc:
+            raise ErroDoSlack("Slack: a resposta não é JSON", status=self.status) from exc
+        if not isinstance(dados, dict):
+            raise ErroDoSlack("Slack: a resposta não é um objeto JSON", status=self.status)
+        return dados
+
+    @property
+    def erro(self) -> str:
+        """O código de ``error`` quando o Slack recusou (``ok: false``), só se for um nome curto;
+        vazio quando deu certo ou o corpo não é o do Slack."""
+        try:
+            dados = json.loads(self.corpo[:65536])
+        except ValueError:
+            return ""
+        if not isinstance(dados, dict) or dados.get("ok") is not False:
+            return ""
+        codigo = dados.get("error")
+        return codigo if isinstance(codigo, str) and _CODIGO.fullmatch(codigo) else "desconhecido"
+
+    @property
+    def ok(self) -> bool:
+        if self.status != 200:
+            return False
+        try:
+            dados = json.loads(self.corpo)
+        except ValueError:
+            return False
+        return isinstance(dados, dict) and dados.get("ok") is True
+
+
+def transitorio(exc: BaseException) -> bool:
+    """Falha de rede em que repetir pode dar certo. O certificado inválido e o prazo esgotado,
+    não."""
+    if isinstance(exc, TimeoutError):
+        return False
+    return isinstance(exc, urllib.error.URLError | ConnectionError | ssl.SSLError) and not (
+        isinstance(exc, urllib.error.URLError)
+        and isinstance(exc.reason, ssl.SSLCertVerificationError)
+    )
+
+
+def _retry_after(resposta: Resposta) -> float:
+    """O ``Retry-After`` em segundos (o Slack manda o número), limitado a ``ESPERA_MAX``."""
+    texto = resposta.cabecalho("Retry-After").strip()
+    if not texto.isdigit():
+        return 0.0
+    return min(float(texto), ESPERA_MAX)
+
+
+@dataclass
+class Cliente:
+    chamada: Any
+    prazo: Prazo
+    porta: int | None = None
+    _token: str | None = None
+    _renovou: bool = False
+
+    def url(self, metodo: str, parametros: Mapping[str, str] | None = None) -> str:
+        endereco = SLACK if self.porta in (None, 443) else f"{SLACK}:{self.porta}"
+        consulta = urllib.parse.urlencode(dict(parametros or {}))
+        return f"https://{endereco}{RAIZ}/{metodo}" + (f"?{consulta}" if consulta else "")
+
+    def _bearer(self, *, renovar: bool = False) -> str:
+        if self._token is None or renovar:
+            self._token = self.chamada.token(CONEXAO, renovar=renovar)
+        return self._token
+
+    def pedir(
+        self,
+        metodo: str,
+        *,
+        parametros: Mapping[str, str] | None = None,
+        corpo: Mapping[str, Any] | None = None,
+        idempotencia: str | None = None,
+        repetir_depois_do_envio: bool = True,
+    ) -> Resposta:
+        """Um método da Web API com o token da conexão, dentro do prazo: ``GET`` com os
+        ``parametros`` ou ``POST`` do ``corpo`` em JSON (o ``json.dumps`` escapa o valor). Repete a
+        falha transitória de rede, o ``429`` e o ``5xx`` quando ``repetir_depois_do_envio`` (a
+        leitura); senão, só o que certamente não saiu (a rede que recusou antes do envio, o
+        ``429``). A autenticação vencida troca o token uma vez e repete. ``idempotencia`` vai no
+        ``Idempotency-Key``: o Slack o ignora, e quem observa o tráfego (o proxy, o servidor
+        falso) distingue a execução."""
+        self.chamada.destino(SLACK)
+        url = self.url(metodo, parametros)
+        dados = None if corpo is None else json.dumps(corpo, ensure_ascii=False).encode("utf-8")
+        abrir = _abridor()
+        ultima_falha: BaseException | None = None
+        ultima_resposta: Resposta | None = None
+        tentativa = 0
+        while tentativa < TENTATIVAS:
+            if tentativa:
+                espera = ESPERAS[min(tentativa - 1, len(ESPERAS) - 1)]
+                if ultima_resposta is not None:
+                    espera = max(espera, _retry_after(ultima_resposta))
+                if not self.prazo.cabe(espera):
+                    break
+                time.sleep(espera)
+            tentativa += 1
+            enviados = {
+                "Accept": "application/json",
+                "Authorization": f"Bearer {self._bearer()}",
+            }
+            if dados is not None:
+                enviados["Content-Type"] = "application/json; charset=utf-8"
+            if idempotencia:
+                enviados["Idempotency-Key"] = idempotencia
+            pedido = urllib.request.Request(
+                url, data=dados, headers=enviados, method="GET" if dados is None else "POST"
+            )
+            try:
+                resposta = self._despachar(abrir, pedido)
+            except Exception as exc:
+                if not transitorio(exc) or not (repetir_depois_do_envio or http.nada_saiu(exc)):
+                    raise
+                ultima_falha, ultima_resposta = exc, None
+                continue
+            if not self._renovou and (resposta.status == 401 or resposta.erro in RENOVAVEIS):
+                # O token venceu antes da hora ou foi revogado: o pedido não teve efeito.
+                self._renovou = True
+                self._bearer(renovar=True)
+                tentativa -= 1
+                continue
+            if resposta.status == 429 or (resposta.status >= 500 and repetir_depois_do_envio):
+                ultima_falha, ultima_resposta = None, resposta
+                continue
+            return resposta
+        if ultima_resposta is not None:
+            return ultima_resposta
+        if ultima_falha is None:
+            raise TimeoutError("o prazo da chamada acabou")
+        raise ultima_falha
+
+    def _despachar(self, abrir: Callable[..., Any], pedido: Any) -> Resposta:
+        try:
+            with abrir(pedido, timeout=self.prazo.restante()) as resposta:
+                corpo = resposta.read(RESPOSTA_MAX + 1)
+                if len(corpo) > RESPOSTA_MAX:
+                    raise ErroDoSlack("Slack: a resposta passa do teto de leitura")
+                return Resposta(resposta.status, dict(resposta.headers.items()), corpo)
+        except urllib.error.HTTPError as exc:
+            corpo = exc.read(65536) if exc.fp else b""
+            return Resposta(exc.code, dict(exc.headers.items()), corpo)
+
+
+def _descricao(resposta: Resposta) -> str:
+    return f"{resposta.status} {resposta.erro}".strip()
+
+
+def checar_leitura(operacao: str, resposta: Resposta) -> dict[str, Any]:
+    """Os dados da resposta de uma leitura; o erro vira ``ErroDoSlack`` com o código do Slack."""
+    if resposta.ok:
+        return resposta.dados()
+    erro = resposta.erro
+    if erro in ("channel_not_found", "not_in_channel") or resposta.status == 404:
+        raise NaoEncontrado(
+            f"Slack {operacao}: o canal não existe, ou a conta conectada não o vê "
+            f"({_descricao(resposta)})",
+            status=resposta.status,
+            codigo=erro,
+        )
+    if erro in ("missing_scope", "no_permission", "access_denied"):
+        raise ErroDoSlack(
+            f"Slack {operacao}: a conexão não tem permissão ({_descricao(resposta)}); "
+            "reconecte o Slack para conceder os escopos que faltam",
+            status=resposta.status,
+            codigo=erro,
+        )
+    raise ErroDoSlack(
+        f"Slack {operacao}: o Slack devolveu {_descricao(resposta)}",
+        status=resposta.status,
+        codigo=erro,
+    )
+
+
+def recusa_antes_de_postar(operacao: str, resposta: Resposta) -> SlackNaoSaiu:
+    """A leitura do histórico (antes de postar) que o Slack recusou: nada foi postado."""
+    erro = resposta.erro
+    dica = (
+        "; reconecte o Slack para conceder o escopo channels:history"
+        if erro == "missing_scope"
+        else ""
+    )
+    return SlackNaoSaiu(
+        f"Slack {operacao}: o histórico do canal não foi lido ({_descricao(resposta)}){dica}; "
+        "nada foi postado",
+        status=resposta.status,
+        codigo=erro,
+    )
+
+
+def checar_escrita(operacao: str, resposta: Resposta) -> dict[str, Any]:
+    """``ok: true`` passa; o ``ok: false`` e o 4xx são ``SlackNaoSaiu`` (o Slack recusou antes de
+    postar; o 429 também: o cliente já tentou de novo); o erro do servidor e o corpo que não se
+    lê são dúvida."""
+    if resposta.status >= 500 or resposta.erro in DO_SERVIDOR:
+        raise SlackIncerto(
+            f"Slack {operacao}: o Slack devolveu {_descricao(resposta)}",
+            status=resposta.status,
+            codigo=resposta.erro,
+        )
+    if resposta.ok:
+        return resposta.dados()
+    if resposta.status != 200 or resposta.erro:
+        raise SlackNaoSaiu(
+            f"Slack {operacao}: o Slack recusou o pedido ({_descricao(resposta)})",
+            status=resposta.status,
+            codigo=resposta.erro,
+        )
+    # 200 sem ``ok``: o corpo não é o do Slack, e a mensagem pode ter saído.
+    raise SlackIncerto(f"Slack {operacao}: a resposta não confirma o envio", status=resposta.status)
+
+
+def falha_de_leitura(operacao: str, exc: BaseException) -> ErroDoSlack:
+    return ErroDoSlack(f"Slack {operacao}: a conexão falhou ({type(exc).__name__})")
+
+
+def falha_de_escrita(operacao: str, exc: BaseException) -> Exception:
+    if http.nada_saiu(exc):
+        return SlackNaoSaiu(f"Slack {operacao}: a conexão não abriu ({type(exc).__name__})")
+    return SlackIncerto(
+        f"Slack {operacao}: a conexão falhou depois do envio ({type(exc).__name__}); "
+        "a mensagem pode ter chegado"
+    )

shade_plugins_slack/erros.py

@@ -0,0 +1,48 @@
+"""Os erros do plugin ``slack``.
+
+Separam o que **certamente não chegou** ao canal (``SlackNaoSaiu``, um ``http.NadaSaiu``) do que
+**pode ter chegado** (``SlackIncerto``, um ``http.ResultadoIncerto``). O token que não veio é o
+``TokenIndisponivel`` do ``shade_sdk.plugins`` (também um ``http.NadaSaiu``).
+
+As mensagens dizem a operação, o status HTTP e o código que o Slack dá (``channel_not_found``,
+``missing_scope``), nunca o corpo, o texto da mensagem, o id do canal nem o token.
+"""
+
+from __future__ import annotations
+
+from shade_sdk import http
+
+
+class ErroDoSlack(Exception):
+    """A leitura não deu certo: conexão, TLS, permissão ou o Slack recusou o pedido."""
+
+    def __init__(self, mensagem: str, *, status: int | None = None, codigo: str = "") -> None:
+        super().__init__(mensagem)
+        self.status = status
+        self.codigo = codigo
+
+
+class NaoEncontrado(ErroDoSlack):
+    """O canal não existe, ou a conta conectada não o vê (``channel_not_found``)."""
+
+
+class SlackNaoSaiu(http.NadaSaiu):
+    """Certamente sem efeito: o Slack recusou o pedido (``ok: false``, 4xx, inclusive o 429 que
+    sobrou das retentativas), a leitura do histórico antes de postar falhou, ou a rede falhou
+    antes do envio."""
+
+    def __init__(self, mensagem: str, *, status: int | None = None, codigo: str = "") -> None:
+        super().__init__(mensagem)
+        self.status = status
+        self.codigo = codigo
+
+
+class SlackIncerto(http.ResultadoIncerto):
+    """Pode ter tido efeito: o pedido foi enviado e a resposta não veio, veio com erro do servidor
+    ou não se leu, e a mensagem não está no histórico. Conferir no canal antes de refazer: a
+    mensagem pode ter sido postada."""
+
+    def __init__(self, mensagem: str, *, status: int | None = None, codigo: str = "") -> None:
+        super().__init__(mensagem)
+        self.status = status
+        self.codigo = codigo

shade_plugins_slack-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: shade-plugins-slack
+Version: 0.1.0
+Summary: Listar canais e enviar mensagem no Slack sem duplicar, pela Web API, com o token OAuth da conexão da plataforma.
+Author: ShadeOne
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: shade-sdk<0.23,>=0.22.3
+Description-Content-Type: text/markdown
+
+# shade-plugins-slack
+
+Lista os canais e envia mensagem no [Slack](https://api.slack.com/web), de dentro de um robô do
+[`shade-sdk`](https://pypi.org/project/shade-sdk/), com o token OAuth da conexão do Slack na
+plataforma. 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 a conexão em `[conexoes]`:
+
+```toml
+[hosts]
+permitidos = ["slack.com"]
+
+[conexoes]
+nomes = ["slack"]
+
+[plugins]
+slack = "0.1.0"
+```
+
+```python
+import shade_plugins_slack as slack
+
+# Leitura: roda inclusive no ensaio.
+canal = next(c["id"] for c in slack.listar_canais() if c["nome"] == "financeiro")
+
+# Escrita: só dentro de item.efetivar() (no ensaio não roda).
+with item.efetivar("avisar o time"):
+    slack.enviar_mensagem(canal, f"Pedido {item['pedido']} conferido.")
+```
+
+## A conta
+
+- **Conexão:** o robô nunca vê a senha nem o refresh token. O token de acesso chega sob demanda da
+  conexão `slack` da plataforma e é renovado por ela. Fora da plataforma (no laptop), ponha um
+  token de acesso em `SHADE_TOKEN_SLACK`.
+- **Escopos:** `channels:read` (listar os canais), `chat:write` (postar) e `channels:history` (ler o
+  histórico recente, que é o que evita a mensagem duplicada). A conexão sem `channels:history` não
+  posta nada e o erro manda reconectar o Slack.
+- **Canais:** os públicos. O app precisa ter sido adicionado ao canal para ler o histórico e postar.
+  O `canal` das operações é o **id** (como `C0123ABCD`, o que `listar_canais` devolve), não o nome.
+
+## O que o plugin garante
+
+- **Não duplica a mensagem.** O Slack não reconhece repetição. O plugin grava a chave do item no
+  `metadata` da mensagem e, antes de postar, lê as últimas mensagens do canal (até 500) e devolve a
+  que já tiver a chave. Depois que o envio saiu sem confirmação (a conexão caiu, o `5xx`, a
+  resposta que não se lê), o plugin não posta de novo: ele confere o histórico e, sem achar, o
+  erro é `SlackIncerto` (o item fica retido para uma pessoa conferir no canal e, só se a mensagem
+  não chegou, mandar refazer).
+- **O texto é literal.** `&`, `<` e `>` vão como as entidades que a API documenta, então
+  `<!channel>`, `<@U123>` e `<https://...|texto>` vindos de um dado não viram menção nem link. A
+  mensagem sai sem formatação (`mrkdwn` desligado), e o corpo é montado como objeto e serializado
+  pelo `shade_sdk.http`, nunca por concatenação de texto.
+- **Retentativa só onde é segura:** a leitura e o `429` (nada foi postado) repetem dentro do
+  `timeout=`; depois do despacho do `chat.postMessage`, nada repete.
+- **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ó `slack.com`, com o certificado verificado, sem seguir redirecionamento; toda
+  chamada aceita `timeout=` (30 s por padrão), que vale para a chamada inteira.
+- **Sem conteúdo 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 id do canal, o token nem o corpo da resposta; o erro da API
+  chega só pelo código que o Slack dá (`channel_not_found`, `missing_scope`).
+
+## Operações
+
+| Operação | Efeito | O que faz |
+|---|---|---|
+| `listar_canais(*, limite=1000, arquivados=False)` | não | Os canais públicos: `id`, `nome`, `arquivado`, `membro`, `membros`. |
+| `enviar_mensagem(canal, texto)` | sim | Posta `texto` (até 40 000 caracteres) no canal. Devolve `canal`, `ts` e `reaproveitada`. |
+
+## Limites
+
+O histórico do Slack é de leitura limitada para alguns apps (os não listados no Marketplace têm
+cota baixa em `conversations.history`). Se a leitura for recusada com `ratelimited`, a mensagem não
+é postada (`SlackNaoSaiu`), em vez de arriscar o duplicado.
+
+## Testes
+
+A suíte de contrato do `shade_sdk.testing.plugins` e um servidor falso da Web API (TLS de uma CA de
+teste, que responde `ok: false` com `200` e não reconhece repetição, como a de verdade) acompanham o
+código-fonte em `tests/`.

shade_plugins_slack-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+shade_plugins_slack/__init__.py,sha256=SGIsBlgPrSIDTlzpYa_7Av5WUiiEn5Z5kL8orj0EJo4,12337
+shade_plugins_slack/_cliente.py,sha256=qtCZe6HbZaCS1sZRsJI-7R8n50nde9iEVND-n0phOjc,12880
+shade_plugins_slack/erros.py,sha256=c8nml5EIsVxOEID7t09BjMNPWT7JI3r_rpUI__iWpZo,1906
+shade_plugins_slack-0.1.0.dist-info/METADATA,sha256=5e776ljdhcOuJ_Wd-5mpjIKHtD0gzHRi9BdLEmmBmak,4479
+shade_plugins_slack-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+shade_plugins_slack-0.1.0.dist-info/entry_points.txt,sha256=0ETm3PTvHIMm4BJ5c0UN2Ndk0cVCidvwTl5_shCrrO0,55
+shade_plugins_slack-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+shade_plugins_slack-0.1.0.dist-info/RECORD,,

shade_plugins_slack-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_slack-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[shade_sdk.plugins]
+slack = shade_plugins_slack:PLUGIN

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