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

shade_plugins_ms365/__init__.py

@@ -0,0 +1,934 @@
+"""O plugin ``ms365``: ler e-mails e baixar anexos do Outlook, enviar e-mail, e listar, baixar e
+enviar arquivos do SharePoint, pela Microsoft Graph, sob o contrato de plugin do shade-sdk, com o
+token OAuth da conexão da plataforma.
+
+```toml
+[hosts]
+permitidos = ["graph.microsoft.com", "contoso.sharepoint.com"]
+
+[conexoes]
+nomes = ["microsoft-365"]
+
+[config]
+sharepoint_host = "contoso.sharepoint.com"   # só para baixar arquivo do SharePoint
+
+[plugins]
+ms365 = "0.1.0"
+```
+
+```python
+import shade_plugins_ms365 as ms365
+
+for email in ms365.ler_emails("inbox", nao_lidos=True):
+    ms365.baixar_anexos(item, email["id"])
+
+with item.efetivar("avisar o cliente"):
+    ms365.enviar_email("cliente@exemplo.com", f"Pedido {item['pedido']}", "Recebemos o pedido.")
+
+site = "contoso.sharepoint.com:/sites/Financeiro"
+for arquivo in ms365.listar_arquivos(site, "Notas/2026"):
+    ms365.baixar_arquivo(site, "Notas/2026/" + arquivo["nome"])
+
+with item.efetivar("guardar o comprovante"):
+    ms365.enviar_arquivo("comprovante.pdf", site, "Comprovantes")
+```
+
+- **Conta:** a conexão ``microsoft-365`` 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_MICROSOFT_365``. A caixa de e-mail é a da conta
+  conectada (``/me``); caixa compartilhada fica fora desta versão.
+- **Ler não muda nada:** ``ler_emails``, ``ler_email``, ``baixar_anexos``, ``listar_arquivos`` e
+  ``baixar_arquivo`` rodam inclusive no ensaio, e nenhuma mensagem vira lida.
+- **Escrever só dentro de** ``item.efetivar()`` (no ensaio não roda):
+  - ``enviar_email`` não duplica: a mensagem leva um ``Message-ID`` derivado da chave do item,
+    do nome da efetivação e da ordem do envio, e antes de criar o rascunho o plugin procura esse
+    identificador em Enviados e em Rascunhos. Depois que o envio saiu sem confirmação, o plugin
+    não envia de novo: ele confere Enviados e, sem achar, o erro é ``GraphIncerto`` (o item fica
+    retido para conferência).
+  - ``enviar_arquivo`` grava no caminho dado: repetir sobrescreve o mesmo arquivo, então a
+    retentativa e o "refazer" deixam um arquivo só. ``existente="falhar"`` recusa o caminho
+    ocupado, e ``chave_no_nome=True`` põe a chave da chamada no nome, para um item não sobrescrever
+    o arquivo de outro.
+- **Prazo:** ``timeout=`` (30 s) vale para a chamada inteira, retentativas incluídas.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import mimetypes
+import os
+import re
+import urllib.parse
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from shade_sdk.plugins import Plugin
+
+from shade_plugins_ms365 import _cliente
+from shade_plugins_ms365._cliente import CONEXAO, GRAPH, RAIZ, Cliente, Prazo
+from shade_plugins_ms365.erros import (
+    ArquivoJaExiste,
+    ErroDaGraph,
+    GraphIncerto,
+    GraphNaoSaiu,
+    NaoEncontrado,
+)
+
+__version__ = "0.1.0"
+
+#: A chave de ``[config]`` com o host do tenant no SharePoint, para onde a Graph redireciona o
+#: download (``contoso.sharepoint.com``).
+HOST_DO_SHAREPOINT = "sharepoint_host"
+#: Quantos itens as listagens devolvem, no máximo, e quantos a Graph dá por página.
+LIMITE_EMAILS_MAX = 1_000
+LIMITE_ARQUIVOS_MAX = 10_000
+POR_PAGINA = 100
+#: Quantas páginas ``ler_emails`` percorre atrás do que passa nos filtros do cliente.
+PAGINAS_MAX = 50
+#: O teto de um download (anexo ou arquivo) e de um envio (um ``PUT`` só).
+ARQUIVO_MAX = 150 * 1024 * 1024
+ENVIO_MAX = 100 * 1024 * 1024
+#: O teto do texto de um e-mail e dos destinatários.
+CORPO_MAX = 1_000_000
+DESTINATARIOS_MAX = 100
+#: O domínio do ``Message-ID``: o ``.invalid`` é reservado (RFC 2606) e nunca é de ninguém.
+DOMINIO_DO_ID = "ms365.shadeone.invalid"
+#: Quantos caracteres da ``chamada.idempotencia`` vão no ``Message-ID`` e no nome com chave.
+TAMANHO_DA_CHAVE = 32
+TAMANHO_DA_CHAVE_NO_NOME = 12
+_CONTROLE = re.compile(r"[\x00-\x1f\x7f]")
+#: O id de mensagem, pasta, anexo e item da Graph, e o nome conhecido da pasta (``inbox``).
+_ID = re.compile(r"^[A-Za-z0-9_=+\-]{1,512}$")
+_ENDERECO = re.compile(
+    r"^[^\s<>()\[\]\\,;:@\"]{1,64}@[A-Za-z0-9](?:[A-Za-z0-9.\-]{0,251}[A-Za-z0-9])?$"
+)
+_HOST = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9.\-]{0,251}[A-Za-z0-9])?$")
+_GUID = r"[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}"
+_SITE_POR_ID = re.compile(rf"^({_HOST.pattern[1:-1]}),({_GUID}),({_GUID})$")
+_SITE_POR_CAMINHO = re.compile(rf"^({_HOST.pattern[1:-1]}):((?:/[^/]+)+)$")
+#: O que o SharePoint não aceita num nome (e o ``/`` que separa os segmentos).
+_PROIBIDOS_NO_NOME = set('"*:<>?/\\|')
+_ANEXO_DE_ARQUIVO = "#microsoft.graph.fileAttachment"
+#: O conteúdo de um anexo ou de um arquivo é binário: o ``Accept`` padrão (JSON) não serve.
+_QUALQUER_TIPO = {"Accept": "*/*"}
+
+PLUGIN = Plugin(
+    "ms365",
+    __version__,
+    shade_sdk=">=0.22.3,<0.23",
+    dono="Equipe de integrações da ShadeOne",
+    hosts=[GRAPH],
+    hosts_do_projeto=[HOST_DO_SHAREPOINT],
+    conexoes=[CONEXAO],
+)
+
+__all__ = [
+    "PLUGIN",
+    "ArquivoJaExiste",
+    "ErroDaGraph",
+    "GraphIncerto",
+    "GraphNaoSaiu",
+    "NaoEncontrado",
+    "baixar_anexos",
+    "baixar_arquivo",
+    "enviar_arquivo",
+    "enviar_email",
+    "ler_email",
+    "ler_emails",
+    "listar_arquivos",
+]
+
+
+# ── as réguas ─────────────────────────────────────────────────────────────────────────────
+
+
+def _id(valor: Any, campo: str) -> str:
+    if not isinstance(valor, str) or not _ID.fullmatch(valor):
+        raise ValueError(
+            f"{campo} é o id que a Graph devolveu (letras, dígitos, '-', '_', '=', '+')"
+        )
+    return urllib.parse.quote(valor, safe="")
+
+
+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 _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 literal_odata(valor: str) -> str:
+    """O texto como literal de um ``$filter`` do OData: entre aspas simples, com a aspa do valor
+    dobrada (a regra do OData). Quebra de linha e controle são recusados."""
+    if not isinstance(valor, str) or _CONTROLE.search(valor):
+        raise ValueError("o texto do filtro não pode ter quebra de linha nem caractere de controle")
+    return "'" + valor.replace("'", "''") + "'"
+
+
+def _segmento(valor: Any, campo: str) -> str:
+    """Um nome de pasta ou arquivo do SharePoint, já codificado para o caminho."""
+    if (
+        not isinstance(valor, str)
+        or not valor
+        or len(valor) > 255
+        or valor in (".", "..")
+        or valor != valor.strip()
+        or valor.endswith(".")
+        or _CONTROLE.search(valor)
+        or any(c in _PROIBIDOS_NO_NOME for c in valor)
+    ):
+        raise ValueError(
+            f"{campo}: nome inválido no SharePoint (vazio, '.', '..', espaço nas pontas, ponto "
+            'no fim, controle ou um destes: " * : < > ? / \\ |)'
+        )
+    return urllib.parse.quote(valor, safe="")
+
+
+def _caminho(valor: Any, campo: str, *, vazio: bool) -> list[str]:
+    """Os segmentos já codificados de um caminho relativo (``Notas/2026``)."""
+    if not isinstance(valor, str):
+        raise ValueError(f"{campo} é um caminho relativo, como 'Notas/2026'")
+    texto = valor.strip("/")
+    if not texto:
+        if vazio:
+            return []
+        raise ValueError(f"{campo} é um caminho relativo, como 'Notas/2026/nota.pdf'")
+    return [_segmento(parte, campo) for parte in texto.split("/")]
+
+
+def _site(valor: Any) -> str:
+    """O site como a Graph o endereça, em ``/sites/...``: ``root``, o id
+    (``contoso.sharepoint.com,<guid>,<guid>``) ou ``host:/sites/Nome``. No caminho do site, a
+    forma por caminho leva o ``:`` que fecha o segmento."""
+    if valor == "root":
+        return "/sites/root"
+    if isinstance(valor, str) and _SITE_POR_ID.fullmatch(valor):
+        return "/sites/" + urllib.parse.quote(valor, safe=",")
+    if isinstance(valor, str) and (achado := _SITE_POR_CAMINHO.fullmatch(valor)):
+        partes = [_segmento(p, "site") for p in achado[2].strip("/").split("/")]
+        return f"/sites/{achado[1]}:/{'/'.join(partes)}:"
+    raise ValueError(
+        "site é 'root', o id do site (host,guid,guid) ou 'host:/sites/Nome', "
+        "como 'contoso.sharepoint.com:/sites/Financeiro'"
+    )
+
+
+def _drive(site: str) -> str:
+    """O drive padrão do site (a biblioteca de documentos)."""
+    return f"{RAIZ}{site}/drive"
+
+
+def _no_drive(site: str, partes: list[str], *, depois: str = "") -> str:
+    """O caminho de um item do drive do site: a raiz (sem ``partes``) ou ``root:/a/b:``."""
+    if not partes:
+        return f"{_drive(site)}/root{depois}"
+    return f"{_drive(site)}/root:/{'/'.join(partes)}:{depois}"
+
+
+def _nome_de_arquivo(nome: str, usados: set[str] | None = None) -> str:
+    limpo = _CONTROLE.sub("_", nome.replace("/", "_").replace("\\", "_")).strip(". ")
+    limpo = (limpo or "arquivo")[:200]
+    if usados is None:
+        return limpo
+    final, contador = limpo, 1
+    while final.casefold() in usados:
+        contador += 1
+        raiz, extensao = os.path.splitext(limpo)
+        final = f"{raiz} ({contador}){extensao}"
+    usados.add(final.casefold())
+    return final
+
+
+def _pasta_relativa(pasta: Any) -> Path:
+    if not isinstance(pasta, str) or not pasta or _CONTROLE.search(pasta):
+        raise ValueError("pasta é um caminho relativo do diretório de trabalho")
+    partes = pasta.split("/")
+    if pasta.startswith("/") or any(p in ("", ".", "..") for p in partes):
+        raise ValueError("pasta é um caminho relativo, sem '..' nem segmento vazio")
+    return Path(pasta)
+
+
+def _arquivo_do_workdir(caminho: Any) -> Path:
+    if not isinstance(caminho, str | os.PathLike):
+        raise TypeError("arquivo é 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("arquivo é um caminho dentro do diretório de trabalho")
+    if not completo.is_file():
+        raise FileNotFoundError("arquivo: não existe no diretório de trabalho")
+    return completo
+
+
+def _enderecos(valor: Any, campo: str, *, obrigatorio: bool) -> list[str]:
+    if valor is None:
+        valor = []
+    if isinstance(valor, str):
+        valor = [valor]
+    if not isinstance(valor, list | tuple):
+        raise TypeError(f"{campo} é um endereço ou uma lista de endereços")
+    if obrigatorio and not valor:
+        raise ValueError(f"{campo} precisa de ao menos um destinatário")
+    resultado = []
+    for endereco in valor:
+        if not isinstance(endereco, str) or not _ENDERECO.fullmatch(endereco.strip()):
+            raise ValueError(f"{campo}: endereço de e-mail inválido")
+        resultado.append(endereco.strip())
+    return resultado
+
+
+def _destinatarios(enderecos: list[str]) -> list[dict[str, Any]]:
+    return [{"emailAddress": {"address": e}} for e in enderecos]
+
+
+def _json(dados: Any) -> bytes:
+    return json.dumps(dados, ensure_ascii=False).encode("utf-8")
+
+
+def _lendo(operacao: str, funcao: Callable[[], Any]) -> Any:
+    """A falha de rede no meio da leitura vira ``ErroDaGraph``."""
+    try:
+        return funcao()
+    except ErroDaGraph:
+        raise
+    except OSError as exc:
+        raise _cliente.falha_de_leitura(operacao, exc) from exc
+
+
+def _cliente_da_chamada(chamada: Any, porta: Any) -> Cliente:
+    return Cliente(chamada=chamada, prazo=Prazo(chamada.timeout), porta=_porta(porta))
+
+
+def _paginas(cliente: Cliente, operacao: str, caminho: str, parametros: dict[str, str]) -> Any:
+    """Os itens de ``value`` de cada página, seguindo ``@odata.nextLink`` só dentro do host da
+    Graph (o link é dado do servidor: o token não vai a outro host)."""
+    consulta_crua = ""
+    while True:
+        resposta = cliente.pedir(
+            "GET", GRAPH, caminho, parametros=parametros, consulta_crua=consulta_crua
+        )
+        _cliente.checar_leitura(operacao, resposta)
+        dados = resposta.json()
+        for item in dados.get("value") or []:
+            if isinstance(item, dict):
+                yield item
+        proximo = dados.get("@odata.nextLink")
+        if not isinstance(proximo, str) or not proximo:
+            return
+        partes = urllib.parse.urlsplit(proximo)
+        if (
+            partes.scheme != "https"
+            or (partes.hostname or "").lower() != GRAPH
+            or partes.username
+            or not partes.path.startswith(RAIZ + "/")
+        ):
+            raise ErroDaGraph(f"Graph {operacao}: a próxima página aponta para fora da Graph")
+        caminho, parametros, consulta_crua = partes.path, {}, partes.query
+
+
+# ── Outlook: ler ──────────────────────────────────────────────────────────────────────────
+
+_CAMPOS_DA_MENSAGEM = "id,internetMessageId,subject,from,receivedDateTime,isRead,hasAttachments"
+
+
+def _endereco_do_remetente(mensagem: dict[str, Any]) -> tuple[str, str]:
+    de = (mensagem.get("from") or {}).get("emailAddress") or {}
+    return str(de.get("address") or ""), str(de.get("name") or "")
+
+
+def _resumo(mensagem: dict[str, Any]) -> dict[str, Any]:
+    endereco, nome = _endereco_do_remetente(mensagem)
+    return {
+        "id": mensagem.get("id", ""),
+        "internet_id": mensagem.get("internetMessageId", ""),
+        "assunto": mensagem.get("subject") or "",
+        "de": endereco,
+        "de_nome": nome,
+        "recebido": mensagem.get("receivedDateTime", ""),
+        "lido": bool(mensagem.get("isRead")),
+        "tem_anexos": bool(mensagem.get("hasAttachments")),
+    }
+
+
+def _instante(valor: Any) -> str:
+    """``desde`` como o instante UTC que o OData lê (``2026-10-25T00:00:00Z``)."""
+    if isinstance(valor, datetime):
+        instante = valor
+    elif isinstance(valor, str):
+        try:
+            instante = datetime.fromisoformat(valor.strip().replace("Z", "+00:00"))
+        except ValueError:
+            raise ValueError(
+                "desde é uma data ISO, como '2026-10-25' ou '2026-10-25T08:00:00Z'"
+            ) from None
+    else:
+        raise ValueError("desde é uma data ISO, como '2026-10-25' ou '2026-10-25T08:00:00Z'")
+    if instante.tzinfo is None:
+        instante = instante.replace(tzinfo=UTC)
+    return instante.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@PLUGIN.operacao
+def ler_emails(
+    chamada: Any,
+    pasta: str = "inbox",
+    *,
+    nao_lidos: bool = False,
+    desde: str | datetime | None = None,
+    remetente: str | None = None,
+    assunto: str | None = None,
+    limite: int = 50,
+    porta: int | None = None,
+) -> list[dict[str, Any]]:
+    """As mensagens de ``pasta`` (``inbox``, ``sentitems``, ``archive``... ou o id de uma pasta),
+    as mais recentes primeiro, até ``limite``. ``nao_lidos`` e ``desde`` (uma data ISO) filtram na
+    Graph; ``remetente`` e ``assunto`` (um pedaço do endereço e do assunto, sem diferenciar
+    maiúsculas) filtram aqui, depois da leitura. Cada uma: ``id``, ``internet_id``, ``assunto``,
+    ``de``, ``de_nome``, ``recebido``, ``lido`` e ``tem_anexos``. Nada vira lido."""
+    destino = _id(pasta, "pasta")
+    limite = _limite(limite, LIMITE_EMAILS_MAX)
+    parametros = {"$select": _CAMPOS_DA_MENSAGEM, "$top": str(POR_PAGINA)}
+    filtros = []
+    if nao_lidos:
+        filtros.append("isRead eq false")
+    if desde is not None:
+        filtros.append(f"receivedDateTime ge {_instante(desde)}")
+    if filtros:
+        parametros["$filter"] = " and ".join(filtros)
+    for campo, valor in (("remetente", remetente), ("assunto", assunto)):
+        if valor is not None and (not isinstance(valor, str) or not valor):
+            raise ValueError(f"{campo} é um texto não vazio")
+    cliente = _cliente_da_chamada(chamada, porta)
+    caminho = f"{RAIZ}/me/mailFolders/{destino}/messages"
+
+    def ler() -> list[dict[str, Any]]:
+        achadas: list[dict[str, Any]] = []
+        for percorridas, mensagem in enumerate(
+            _paginas(cliente, "ler_emails", caminho, parametros)
+        ):
+            if percorridas >= PAGINAS_MAX * POR_PAGINA:
+                break
+            resumo = _resumo(mensagem)
+            if remetente and remetente.casefold() not in resumo["de"].casefold():
+                continue
+            if assunto and assunto.casefold() not in resumo["assunto"].casefold():
+                continue
+            achadas.append(resumo)
+            if len(achadas) >= limite:
+                break
+        return achadas
+
+    return _lendo("ler_emails", ler)
+
+
+@PLUGIN.operacao
+def ler_email(chamada: Any, mensagem: str, *, porta: int | None = None) -> dict[str, Any]:
+    """Uma mensagem inteira, pelo ``id`` de ``ler_emails``: o resumo mais ``para`` e ``cc`` (listas
+    de endereços) e ``corpo`` (em texto). Não marca como lida."""
+    identificador = _id(mensagem, "mensagem")
+    cliente = _cliente_da_chamada(chamada, porta)
+
+    def ler() -> dict[str, Any]:
+        resposta = cliente.pedir(
+            "GET",
+            GRAPH,
+            f"{RAIZ}/me/messages/{identificador}",
+            parametros={"$select": f"{_CAMPOS_DA_MENSAGEM},body,toRecipients,ccRecipients"},
+            cabecalhos={"Prefer": 'outlook.body-content-type="text"'},
+        )
+        _cliente.checar_leitura("ler_email", resposta)
+        dados = resposta.json()
+
+        def enderecos(campo: str) -> list[str]:
+            return [
+                str((r.get("emailAddress") or {}).get("address") or "")
+                for r in dados.get(campo) or []
+                if isinstance(r, dict)
+            ]
+
+        return {
+            **_resumo(dados),
+            "para": enderecos("toRecipients"),
+            "cc": enderecos("ccRecipients"),
+            "corpo": str((dados.get("body") or {}).get("content") or ""),
+        }
+
+    return _lendo("ler_email", ler)
+
+
+@PLUGIN.operacao
+def baixar_anexos(
+    chamada: Any,
+    item: Any,
+    mensagem: str,
+    *,
+    nomes: list[str] | tuple[str, ...] | str | None = None,
+    incluir_inline: bool = False,
+    pasta: str = "anexos",
+    porta: int | None = None,
+) -> list[dict[str, Any]]:
+    """Os anexos de arquivo da mensagem ``mensagem`` (o ``id`` de ``ler_emails``) gravados em
+    ``<pasta>/<12 caracteres do id>/`` no diretório de trabalho e anexados ao item por
+    ``item.anexar`` (a saída do run). ``nomes`` escolhe quais; as imagens embutidas no corpo só
+    entram com ``incluir_inline``. Cada um: ``nome`` (o da mensagem), ``arquivo`` (o caminho
+    gravado, com o nome limpo de separador e controle), ``tipo``, ``tamanho`` e ``anexado``
+    (``False`` acima do teto da saída do run; o arquivo fica no disco). O anexo que é outra
+    mensagem ou um link vem com ``ignorado`` e sem arquivo. A mensagem não é marcada como lida."""
+    anexar = getattr(item, "anexar", None)
+    if not callable(anexar):
+        raise TypeError("baixar_anexos(item, mensagem): passe o item do processar()")
+    identificador = _id(mensagem, "mensagem")
+    escolhidos = None if nomes is None else ({nomes} if isinstance(nomes, str) else set(nomes))
+    destino = _pasta_relativa(pasta) / hashlib.sha256(mensagem.encode()).hexdigest()[:12]
+    cliente = _cliente_da_chamada(chamada, porta)
+    base = f"{RAIZ}/me/messages/{identificador}/attachments"
+    raiz = Path.cwd().resolve()
+
+    def ler() -> list[dict[str, Any]]:
+        resultado: list[dict[str, Any]] = []
+        usados: set[str] = set()
+        parametros = {"$select": "id,name,contentType,size,isInline", "$top": str(POR_PAGINA)}
+        for anexo in _paginas(cliente, "baixar_anexos", base, parametros):
+            nome = str(anexo.get("name") or "")
+            tipo = str(anexo.get("contentType") or "")
+            if escolhidos is not None and nome not in escolhidos:
+                continue
+            if anexo.get("@odata.type") != _ANEXO_DE_ARQUIVO:
+                resultado.append(
+                    {
+                        "nome": nome,
+                        "arquivo": None,
+                        "tipo": tipo,
+                        "tamanho": None,
+                        "anexado": False,
+                        "ignorado": "anexo que não é arquivo (mensagem ou link)",
+                    }
+                )
+                continue
+            if anexo.get("isInline") and not incluir_inline:
+                continue
+            identificador_do_anexo = anexo.get("id")
+            if not isinstance(identificador_do_anexo, str) or not _ID.fullmatch(
+                identificador_do_anexo
+            ):
+                raise ErroDaGraph("Graph baixar_anexos: anexo sem um id que a Graph reconheça")
+            pasta_completa = raiz / destino
+            pasta_completa.mkdir(parents=True, exist_ok=True)
+            gravado = pasta_completa / _nome_de_arquivo(nome, usados)
+            parcial = pasta_completa / (gravado.name + ".parcial")
+            try:
+                conteudo = cliente.pedir(
+                    "GET",
+                    GRAPH,
+                    f"{base}/{urllib.parse.quote(identificador_do_anexo, safe='')}/$value",
+                    cabecalhos=_QUALQUER_TIPO,
+                    para_arquivo=parcial,
+                    tamanho_max=ARQUIVO_MAX,
+                )
+                _cliente.checar_leitura("baixar_anexos", conteudo)
+                parcial.replace(gravado)
+            finally:
+                parcial.unlink(missing_ok=True)
+            resultado.append(
+                {
+                    "nome": nome,
+                    "arquivo": str(gravado.relative_to(raiz)),
+                    "tipo": tipo,
+                    "tamanho": conteudo.tamanho,
+                    "anexado": bool(anexar(gravado)),
+                }
+            )
+        return resultado
+
+    return _lendo("baixar_anexos", ler)
+
+
+# ── Outlook: enviar ───────────────────────────────────────────────────────────────────────
+
+
+class _AindaNaoSaiu(Exception):
+    """Uma volta do envio falhou antes de despachar o ``send`` (o rascunho não ficou criado, ou
+    a resposta dele se perdeu): a volta seguinte procura o rascunho antes de criar outro."""
+
+
+def _procurar(cliente: Cliente, pasta: str, mid: str, marca: str) -> dict[str, Any] | None:
+    """A mensagem de ``pasta`` (``sentitems`` ou ``drafts``) com este ``internetMessageId``."""
+    try:
+        resposta = cliente.pedir(
+            "GET",
+            GRAPH,
+            f"{RAIZ}/me/mailFolders/{pasta}/messages",
+            parametros={
+                "$filter": f"internetMessageId eq {literal_odata(mid)}",
+                "$select": "id,internetMessageId",
+                "$top": "1",
+            },
+            idempotencia=marca,
+        )
+        _cliente.checar_leitura("enviar_email", resposta)
+        achadas = resposta.json().get("value") or []
+    except (ErroDaGraph, OSError) as exc:
+        # Sem a busca, não se envia (o token que não veio já é um ``http.NadaSaiu``).
+        raise GraphNaoSaiu(f"Graph enviar_email: a busca do identificador falhou: {exc}") from exc
+    return achadas[0] if achadas and isinstance(achadas[0], dict) else None
+
+
+def _criar_rascunho(cliente: Cliente, rascunho: bytes, marca: str) -> str:
+    try:
+        resposta = cliente.pedir(
+            "POST",
+            GRAPH,
+            f"{RAIZ}/me/messages",
+            corpo=rascunho,
+            tipo="application/json",
+            idempotencia=marca,
+            repetir_depois_do_envio=False,
+        )
+    except OSError as exc:
+        raise _AindaNaoSaiu() from exc
+    if resposta.status >= 500:
+        raise _AindaNaoSaiu()
+    _cliente.checar_escrita("enviar_email", resposta)
+    try:
+        criado = resposta.json().get("id")
+    except ErroDaGraph:
+        criado = None
+    if not isinstance(criado, str) or not _ID.fullmatch(criado):
+        # Criou, mas não dá para enviar o que não se identifica: a volta seguinte o acha.
+        raise _AindaNaoSaiu()
+    return criado
+
+
+def _despachar_o_envio(cliente: Cliente, mid: str, marca: str, id_do_rascunho: str) -> None:
+    """O ``send`` do rascunho. Depois de despachado, nenhuma volta repete: a dúvida confere
+    Enviados e, sem achar, é ``GraphIncerto``."""
+    try:
+        resposta = cliente.pedir(
+            "POST",
+            GRAPH,
+            f"{RAIZ}/me/messages/{urllib.parse.quote(id_do_rascunho, safe='')}/send",
+            idempotencia=marca,
+            repetir_depois_do_envio=False,
+        )
+        _cliente.checar_escrita("enviar_email", resposta)
+        return
+    except GraphIncerto as incerto:
+        duvida: Exception = incerto
+    except OSError as exc:
+        duvida = _cliente.falha_de_escrita("enviar_email", exc)
+        if isinstance(duvida, GraphNaoSaiu):
+            raise duvida from exc
+    # O envio pode ter saído: o que o confirma é a mensagem em Enviados.
+    try:
+        confirmada = _procurar(cliente, "sentitems", mid, marca)
+    except GraphNaoSaiu:
+        confirmada = None
+    if confirmada is None:
+        raise duvida
+    return
+
+
+@PLUGIN.efeito
+def enviar_email(
+    chamada: Any,
+    para: str | list[str],
+    assunto: str,
+    corpo: str,
+    *,
+    cc: str | list[str] | None = None,
+    cco: str | list[str] | None = None,
+    html: bool = False,
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Envia um e-mail da conta conectada, só dentro de ``item.efetivar()``. ``corpo`` é texto (ou
+    HTML, com ``html=True``: o HTML é do robô). Devolve ``internet_id`` (o ``Message-ID``) e
+    ``reaproveitado`` (``True`` quando a mensagem desta mesma chamada já estava em Enviados).
+
+    Não duplica: a mensagem leva o ``Message-ID`` derivado da chave do item, do nome da
+    efetivação e da ordem do envio, e antes de criar o rascunho o plugin procura esse
+    identificador em Enviados e em Rascunhos. ``GraphNaoSaiu``: nada foi enviado (a Graph
+    recusou, a rede não abriu, a busca não respondeu). ``GraphIncerto``: o envio saiu sem
+    confirmação e a mensagem não está em Enviados; o plugin não envia de novo."""
+    destinatarios = _enderecos(para, "para", obrigatorio=True)
+    copia = _enderecos(cc, "cc", obrigatorio=False)
+    oculta = _enderecos(cco, "cco", obrigatorio=False)
+    if len(destinatarios) + len(copia) + len(oculta) > DESTINATARIOS_MAX:
+        raise ValueError(f"no máximo {DESTINATARIOS_MAX} destinatários")
+    if not isinstance(assunto, str) or not assunto.strip() or len(assunto) > 255:
+        raise ValueError("assunto é um texto de 1 a 255 caracteres")
+    if _CONTROLE.search(assunto):
+        raise ValueError("assunto não pode ter quebra de linha nem caractere de controle")
+    if not isinstance(corpo, str) or len(corpo) > CORPO_MAX:
+        raise ValueError(f"corpo é um texto de até {CORPO_MAX} caracteres")
+    if not isinstance(html, bool):
+        raise ValueError("html é verdadeiro ou falso")
+    marca = chamada.idempotencia
+    mid = f"<{marca[:TAMANHO_DA_CHAVE]}@{DOMINIO_DO_ID}>"
+    rascunho = _json(
+        {
+            "subject": assunto,
+            "body": {"contentType": "HTML" if html else "Text", "content": corpo},
+            "toRecipients": _destinatarios(destinatarios),
+            "ccRecipients": _destinatarios(copia),
+            "bccRecipients": _destinatarios(oculta),
+            "internetMessageId": mid,
+        }
+    )
+    cliente = _cliente_da_chamada(chamada, porta)
+    for _ in range(_cliente.TENTATIVAS):
+        try:
+            return _enviar_uma_vez(cliente, mid, marca, rascunho)
+        except _AindaNaoSaiu:
+            if not cliente.prazo.cabe(0):
+                break
+    raise GraphNaoSaiu("Graph enviar_email: o rascunho não ficou criado; nada foi enviado")
+
+
+def _enviar_uma_vez(cliente: Cliente, mid: str, marca: str, rascunho: bytes) -> dict[str, Any]:
+    if _procurar(cliente, "sentitems", mid, marca) is not None:
+        return {"internet_id": mid, "reaproveitado": True}
+    achado = _procurar(cliente, "drafts", mid, marca)
+    id_do_rascunho = achado["id"] if achado and isinstance(achado.get("id"), str) else None
+    if id_do_rascunho is None:
+        id_do_rascunho = _criar_rascunho(cliente, rascunho, marca)
+    _despachar_o_envio(cliente, mid, marca, id_do_rascunho)
+    return {"internet_id": mid, "reaproveitado": False}
+
+
+# ── SharePoint ────────────────────────────────────────────────────────────────────────────
+
+_CAMPOS_DO_ARQUIVO = "id,name,size,file,folder,lastModifiedDateTime,webUrl"
+
+
+def _item(dados: dict[str, Any]) -> dict[str, Any]:
+    tamanho = dados.get("size")
+    pasta = isinstance(dados.get("folder"), dict)
+    return {
+        "id": dados.get("id", ""),
+        "nome": dados.get("name", ""),
+        "tipo": "pasta" if pasta else str((dados.get("file") or {}).get("mimeType") or ""),
+        "tamanho": None if pasta or not isinstance(tamanho, int) else tamanho,
+        "modificado": dados.get("lastModifiedDateTime", ""),
+        "url": dados.get("webUrl", ""),
+    }
+
+
+@PLUGIN.operacao
+def listar_arquivos(
+    chamada: Any,
+    site: str,
+    pasta: str = "",
+    *,
+    limite: int = POR_PAGINA,
+    porta: int | None = None,
+) -> list[dict[str, Any]]:
+    """Os itens da ``pasta`` (um caminho como ``Notas/2026``; vazio é a raiz) da biblioteca de
+    documentos padrão do ``site`` (``root``, o id ``host,guid,guid`` ou
+    ``contoso.sharepoint.com:/sites/Financeiro``), até ``limite``. Cada um: ``id``, ``nome``,
+    ``tipo`` (``pasta`` ou o MIME), ``tamanho`` (``None`` na pasta), ``modificado`` e ``url``."""
+    limite = _limite(limite, LIMITE_ARQUIVOS_MAX)
+    caminho = _no_drive(_site(site), _caminho(pasta, "pasta", vazio=True), depois="/children")
+    cliente = _cliente_da_chamada(chamada, porta)
+
+    def ler() -> list[dict[str, Any]]:
+        itens: list[dict[str, Any]] = []
+        parametros = {"$select": _CAMPOS_DO_ARQUIVO, "$top": str(min(POR_PAGINA, limite))}
+        for dados in _paginas(cliente, "listar_arquivos", caminho, parametros):
+            itens.append(_item(dados))
+            if len(itens) >= limite:
+                break
+        return itens
+
+    return _lendo("listar_arquivos", ler)
+
+
+def _local_do_download(cliente: Cliente, resposta: _cliente.Resposta, host: str) -> tuple[str, str]:
+    """O caminho e a consulta do ``Location`` da Graph, que só vale se for HTTPS no host do
+    tenant que o projeto declarou (o link é dado do servidor: nenhum outro host recebe o
+    pedido)."""
+    destino = resposta.cabecalho("Location")
+    partes = urllib.parse.urlsplit(destino)
+    porta_aceita = {None, 443, cliente.porta}
+    if (
+        partes.scheme != "https"
+        or partes.username
+        or (partes.hostname or "").lower() != host
+        or partes.port not in porta_aceita
+    ):
+        raise ErroDaGraph(
+            f"Graph baixar_arquivo: a Graph mandou baixar de {partes.hostname or 'outro lugar'}, "
+            f"que não é o {HOST_DO_SHAREPOINT} do projeto ({host})",
+            status=resposta.status,
+        )
+    return partes.path, partes.query
+
+
+@PLUGIN.operacao
+def baixar_arquivo(
+    chamada: Any,
+    site: str,
+    caminho: str,
+    *,
+    pasta: str = "sharepoint",
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Grava o arquivo ``caminho`` (``Notas/2026/nota.pdf``) da biblioteca padrão do ``site`` em
+    ``<pasta>/<nome>`` no diretório de trabalho (o nome do SharePoint, limpo de separador e
+    controle) e devolve ``id``, ``arquivo`` (o caminho gravado), ``tamanho`` e ``tipo``. O
+    arquivo só aparece inteiro: o download que cai no meio não deixa arquivo.
+
+    A Graph responde o conteúdo com um redirecionamento para o host do tenant no SharePoint, que
+    vem de ``[config] sharepoint_host`` (e de ``[hosts] permitidos``); o token da conexão não vai
+    a esse host, a URL já é autenticada."""
+    host = chamada.host_do_projeto(HOST_DO_SHAREPOINT)
+    partes = _caminho(caminho, "caminho", vazio=False)
+    endereco_do_site = _site(site)
+    base = _no_drive(endereco_do_site, partes)
+    destino = _pasta_relativa(pasta)
+    cliente = _cliente_da_chamada(chamada, porta)
+    raiz = Path.cwd().resolve()
+
+    def ler() -> dict[str, Any]:
+        resposta = cliente.pedir("GET", GRAPH, base, parametros={"$select": _CAMPOS_DO_ARQUIVO})
+        _cliente.checar_leitura("baixar_arquivo", resposta)
+        dados = _item(resposta.json())
+        if dados["tipo"] == "pasta":
+            raise ErroDaGraph("Graph baixar_arquivo: o caminho é uma pasta, não um arquivo")
+        identificador = dados["id"]
+        if not isinstance(identificador, str) or not _ID.fullmatch(identificador):
+            raise ErroDaGraph("Graph baixar_arquivo: o item veio sem um id que a Graph reconheça")
+        pasta_completa = raiz / destino
+        pasta_completa.mkdir(parents=True, exist_ok=True)
+        gravado = pasta_completa / _nome_de_arquivo(str(dados["nome"]))
+        parcial = pasta_completa / (gravado.name + ".parcial")
+        conteudo_em = f"{_drive(endereco_do_site)}/items/{identificador}/content"
+        try:
+            conteudo = cliente.pedir(
+                "GET",
+                GRAPH,
+                conteudo_em,
+                cabecalhos=_QUALQUER_TIPO,
+                para_arquivo=parcial,
+                tamanho_max=ARQUIVO_MAX,
+            )
+            if conteudo.status in (301, 302, 303, 307, 308):
+                caminho_final, consulta = _local_do_download(cliente, conteudo, host)
+                conteudo = cliente.pedir(
+                    "GET",
+                    host,
+                    caminho_final,
+                    consulta_crua=consulta,
+                    cabecalhos=_QUALQUER_TIPO,
+                    para_arquivo=parcial,
+                    tamanho_max=ARQUIVO_MAX,
+                    com_token=False,
+                )
+            if not 200 <= conteudo.status < 300:
+                _cliente.checar_leitura("baixar_arquivo", conteudo)
+            parcial.replace(gravado)
+        finally:
+            parcial.unlink(missing_ok=True)
+        return {
+            "id": identificador,
+            "arquivo": str(gravado.relative_to(raiz)),
+            "tamanho": conteudo.tamanho,
+            "tipo": dados["tipo"],
+        }
+
+    return _lendo("baixar_arquivo", ler)
+
+
+@PLUGIN.efeito
+def enviar_arquivo(
+    chamada: Any,
+    arquivo: str | os.PathLike[str],
+    site: str,
+    pasta: str = "",
+    *,
+    nome: str | None = None,
+    existente: str = "substituir",
+    chave_no_nome: bool = False,
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Envia um arquivo do diretório de trabalho (até 100 MB) para a ``pasta`` (um caminho como
+    ``Comprovantes/2026``; vazio é a raiz) da biblioteca padrão do ``site``, só dentro de
+    ``item.efetivar()``, com ``nome`` (o do arquivo, se omitido). Devolve ``id``, ``nome``,
+    ``caminho``, ``tamanho`` e ``criado`` (``False`` quando substituiu um arquivo).
+
+    O caminho é a chave: repetir (retentativa, retomada, refazer) grava o mesmo arquivo, com o
+    mesmo conteúdo, e deixa um arquivo só. ``existente="substituir"`` (o padrão) sobrescreve o
+    que estiver no caminho; ``existente="falhar"`` recusa o caminho ocupado
+    (``ArquivoJaExiste``). ``chave_no_nome=True`` acrescenta ao nome 12 caracteres da chave da
+    chamada (``nota.3fa9c1d2b4e6.pdf``), para o arquivo de um item não sobrescrever o de outro.
+
+    ``GraphNaoSaiu``: nada foi gravado (a Graph recusou, a rede não abriu). ``GraphIncerto``: o
+    envio saiu sem confirmação; conferir o arquivo antes de refazer."""
+    local = _arquivo_do_workdir(arquivo)
+    nome_final = nome if nome is not None else local.name
+    if existente not in ("substituir", "falhar"):
+        raise ValueError("existente é 'substituir' ou 'falhar'")
+    if not isinstance(chave_no_nome, bool):
+        raise ValueError("chave_no_nome é verdadeiro ou falso")
+    if chave_no_nome:
+        raiz_do_nome, extensao = os.path.splitext(str(nome_final))
+        nome_final = f"{raiz_do_nome}.{chamada.idempotencia[:TAMANHO_DA_CHAVE_NO_NOME]}{extensao}"
+    _segmento(nome_final, "nome")
+    partes = [*_caminho(pasta, "pasta", vazio=True), _segmento(nome_final, "nome")]
+    dados = local.read_bytes()
+    if len(dados) > ENVIO_MAX:
+        raise ValueError("arquivo passa de 100 MB: o envio desta versão é de um pedido só")
+    caminho = _no_drive(_site(site), partes, depois="/content")
+    tipo = mimetypes.guess_type(nome_final)[0] or "application/octet-stream"
+    cliente = _cliente_da_chamada(chamada, porta)
+    try:
+        resposta = cliente.pedir(
+            "PUT",
+            GRAPH,
+            caminho,
+            parametros={
+                "@microsoft.graph.conflictBehavior": "replace"
+                if existente == "substituir"
+                else "fail"
+            },
+            corpo=dados,
+            tipo=tipo,
+            idempotencia=chamada.idempotencia,
+            # Substituir é idempotente (o mesmo caminho, o mesmo conteúdo): repetir depois de uma
+            # resposta perdida não muda nada. Falhar não é: a 2ª volta bateria no próprio arquivo.
+            repetir_depois_do_envio=existente == "substituir",
+        )
+    except OSError as exc:
+        raise _cliente.falha_de_escrita("enviar_arquivo", exc) from exc
+    if resposta.status == 409 and existente == "falhar":
+        raise ArquivoJaExiste(
+            f"Graph enviar_arquivo: já existe um arquivo nesse caminho ({resposta.status} "
+            f"{resposta.codigo})".strip(),
+            status=409,
+        )
+    _cliente.checar_escrita("enviar_arquivo", resposta)
+    try:
+        criado = resposta.json()
+    except ErroDaGraph as exc:
+        raise GraphIncerto(
+            "Graph enviar_arquivo: a Graph confirmou com um corpo ilegível; o arquivo pode estar "
+            "lá",
+            status=resposta.status,
+        ) from exc
+    return {
+        "id": criado.get("id", ""),
+        "nome": criado.get("name", nome_final),
+        "caminho": "/".join(urllib.parse.unquote(p) for p in partes),
+        "tamanho": criado.get("size", len(dados)),
+        "criado": resposta.status == 201,
+    }