zapcore-sdk 0.1.1__py3-none-any.whl

zapcore/__init__.py

@@ -0,0 +1,17 @@
+"""SDK oficial da API REST v2 do zapCore (WhatsApp).
+
+    from zapcore import Client
+    zap = Client("https://api.seudominio.com", token="TOKEN_DA_INSTANCIA")
+    zap.send_text("5527999999999", "Olá!")
+"""
+from ._client import ApiResponse, Client, Page, SDK_VERSION, Transport, destino, parse_retry_after, urllib_transport
+from ._errors import WebhookVerificationError, ZapcoreError
+from ._generated import API_VERSION, SPEC_SHA256
+from .webhook import parse_webhook, verify_webhook
+
+__all__ = [
+    "Client", "ApiResponse", "Page", "Transport", "ZapcoreError", "WebhookVerificationError",
+    "verify_webhook", "parse_webhook", "destino", "parse_retry_after", "urllib_transport",
+    "SDK_VERSION", "API_VERSION", "SPEC_SHA256",
+]
+__version__ = SDK_VERSION

zapcore/_client.py

@@ -0,0 +1,423 @@
+from __future__ import annotations
+
+import base64
+import email.utils
+import json
+import random
+import re
+import time
+import urllib.error
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Sequence, Tuple, Union
+from urllib.parse import urlencode, urlparse
+
+from ._errors import ZapcoreError
+from ._generated import _Operations
+
+SDK_VERSION = "0.1.1"  # x-release-please-version
+
+#: (status, headers com chave minúscula, corpo)
+TransportResponse = Tuple[int, Dict[str, str], bytes]
+#: transport(method, url, headers, body, timeout) -> TransportResponse. Falha de rede: levante OSError.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], TransportResponse]
+
+_RETENTAVEIS_5XX = {502, 503, 504}
+_POR_STATUS = {400: "bad_request", 401: "unauthorized", 403: "forbidden", 404: "not_found",
+               409: "conflict", 423: "session_locked", 429: "rate_limited"}
+
+
+@dataclass
+class ApiResponse:
+    """Resposta completa, para quem precisa de ``meta``, status ou headers."""
+
+    data: Any
+    meta: Dict[str, Any]
+    status: int
+    headers: Dict[str, str]
+    #: ``True`` quando o servidor repetiu a resposta guardada de uma Idempotency-Key.
+    idempotent_replay: bool = False
+
+
+@dataclass
+class Page:
+    items: List[Any]
+    #: Repasse sem interpretar. ``None`` = acabou.
+    next_cursor: Optional[str]
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+
+class _SemRedirect(urllib.request.HTTPRedirectHandler):
+    """Nunca segue redirect: o urllib reenviaria o header ``token`` para o destino do Location.
+
+    Devolver ``None`` faz o 3xx subir como HTTPError, que o transporte entrega ao cliente.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[override]
+        return None
+
+
+_OPENER = urllib.request.build_opener(_SemRedirect())
+
+
+#: Teto do download de imagem por URL (o motor também limita o que aceita).
+MAX_DOWNLOAD_BYTES = 16 * 1024 * 1024
+#: Tipos aceitos no download por URL (sem svg: pode carregar script).
+_IMAGENS_OK = {"image/jpeg", "image/png", "image/webp", "image/gif"}
+#: ``http://`` só é aceito sem opt-in nestes hosts: o tráfego não sai da máquina.
+_HOSTS_LOCAIS = {"localhost", "127.0.0.1", "::1"}
+
+
+def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float, max_bytes: Optional[int] = None) -> TransportResponse:
+    """Transporte padrão: só biblioteca padrão, sem seguir redirect.
+
+    ``max_bytes`` (opcional) corta a leitura do corpo: estourou, levanta :class:`ZapcoreError` 413.
+    """
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with _OPENER.open(req, timeout=timeout) as r:  # noqa: S310 (URL vem do dono do cliente)
+            return r.status, {k.lower(): v for k, v in r.headers.items()}, _ler(r, max_bytes)
+    except urllib.error.HTTPError as e:
+        return e.code, {k.lower(): v for k, v in (e.headers or {}).items()}, _ler(e, max_bytes) or b""
+
+
+def _ler(r: Any, max_bytes: Optional[int]) -> bytes:
+    if max_bytes is None:
+        return r.read()
+    declarado = r.headers.get("content-length")
+    if declarado and declarado.isdigit() and int(declarado) > max_bytes:
+        raise _estouro(max_bytes)
+    dados = r.read(max_bytes + 1)
+    if len(dados) > max_bytes:
+        raise _estouro(max_bytes)
+    return dados
+
+
+def _estouro(max_bytes: int) -> "ZapcoreError":
+    return ZapcoreError(f"zapcore: a imagem passa de {max_bytes} bytes; baixe você e passe os bytes", status=413, code="bad_request")
+
+
+def _exige_canal_cifrado(base_url: str, permitir_http: bool) -> None:
+    """``http://`` para host remoto mandaria o token da instância em claro."""
+    u = urlparse(base_url)
+    if u.scheme.lower() == "https" or permitir_http or (u.hostname or "").lower() in _HOSTS_LOCAIS:
+        return
+    raise ValueError(
+        "zapcore: base_url em http:// para um host remoto mandaria o token em claro. Use https://, "
+        "ou allow_insecure_http=True para uma rede interna sem TLS (http:// é aceito sem opt-in "
+        "só em localhost, 127.0.0.1 e [::1])."
+    )
+
+
+def parse_retry_after(valor: Optional[str], agora: Optional[float] = None) -> Optional[float]:
+    """``Retry-After`` em segundos (número ou data HTTP)."""
+    if not valor:
+        return None
+    v = valor.strip()
+    if re.fullmatch(r"\d+(\.\d+)?", v):
+        return float(v)
+    try:
+        quando = email.utils.parsedate_to_datetime(v).timestamp()
+    except (TypeError, ValueError):
+        return None
+    return max(0.0, float(int(quando - (time.time() if agora is None else agora) + 0.999)))
+
+
+def destino(phone: str) -> str:
+    """Número com pontuação vira só dígitos; JID (``...@g.us``) passa intacto."""
+    return phone.strip() if "@" in phone else re.sub(r"\D+", "", phone)
+
+
+def _limpar_data_url(u: str) -> str:
+    """O motor recusa (400) parâmetro no mime do data URL."""
+    m = re.match(r"^data:([^;,]+)[^,]*?(;base64)?,", u, re.I)
+    if not m:
+        return u
+    return f"data:{m.group(1)}{m.group(2) or ''},{u[m.end():]}"
+
+
+def _backoff(tentativa: int) -> float:
+    base = min(8.0, 0.5 * (2 ** tentativa))
+    return base / 2 + random.random() * (base / 2)
+
+
+class Client(_Operations):
+    """Cliente da API v2 do zapCore.
+
+    Todo método gerado (um por ``operationId``, ex. ``post_chat_send_text``) e todo atalho
+    (``send_text``, ``send_image``…) devolve o ``data`` do envelope. Para ``meta``, status e
+    headers use :meth:`request`.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: Optional[str] = None,
+        *,
+        admin_token: Optional[str] = None,
+        max_retries: int = 2,
+        max_retry_wait: float = 60.0,
+        timeout: float = 30.0,
+        auto_idempotency: bool = True,
+        headers: Optional[Mapping[str, str]] = None,
+        transport: Optional[Transport] = None,
+        sleep: Callable[[float], None] = time.sleep,
+        idempotency_key_factory: Callable[[], str] = lambda: str(uuid.uuid4()),
+        allow_insecure_http: bool = False,
+    ) -> None:
+        if not re.match(r"^https?://", base_url or "", re.I):
+            raise ValueError("zapcore: base_url precisa ser uma URL http(s), ex. https://api.seudominio.com")
+        _exige_canal_cifrado(base_url, allow_insecure_http)
+        self.base_url = re.sub(r"/api/v2$", "", base_url.rstrip("/"))
+        self._token = token
+        self._admin_token = admin_token
+        self._max_retries = max(0, max_retries)
+        self._max_retry_wait = max_retry_wait
+        self._timeout = timeout
+        self._auto_idem = auto_idempotency
+        self._headers = dict(headers or {})
+        self._transport: Transport = transport or urllib_transport
+        self._sleep = sleep
+        self._nova_chave = idempotency_key_factory
+
+    # ------------------------------------------------------------ baixo nível
+
+    def _call(self, method: str, path: str, **kw: Any) -> Any:
+        return self.request(method, path, **kw).data
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        send: bool = False,
+        admin: bool = False,
+        idempotency_key: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> ApiResponse:
+        """Chamada de baixo nível. Levanta :class:`ZapcoreError` em HTTP >= 400."""
+        url = self.base_url + path + _montar_query(query)
+        h: Dict[str, str] = {"Accept": "application/json", "User-Agent": f"zapcore-sdk-python/{SDK_VERSION}", **self._headers}
+        if admin:
+            if not self._admin_token:
+                raise ValueError("zapcore: rota /admin exige admin_token no cliente")
+            h["Authorization"] = self._admin_token
+        else:
+            if not self._token:
+                raise ValueError("zapcore: esta rota exige token (token da instância) no cliente")
+            h["token"] = self._token
+        dados: Optional[bytes] = None
+        if body is not None:
+            dados = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+            h["Content-Type"] = "application/json"
+        # Uma chave por chamada LÓGICA, reaproveitada em todo retry: retry nunca duplica mensagem.
+        chave = (idempotency_key or (self._nova_chave() if self._auto_idem else None)) if send else None
+        if chave:
+            h["Idempotency-Key"] = chave
+        h.update(headers or {})
+
+        seguro = method == "GET" or chave is not None
+        limite = self._max_retries if max_retries is None else max(0, max_retries)
+        prazo = self._timeout if timeout is None else timeout
+
+        tentativa = 0
+        while True:
+            try:
+                status, rh, cru = self._transport(method, url, h, dados, prazo)
+            except OSError as e:
+                if seguro and tentativa < limite:
+                    self._sleep(_backoff(tentativa))
+                    tentativa += 1
+                    continue
+                raise ZapcoreError(f"zapcore: falha de rede em {method} {path}: {e}", status=0, code="network_error") from e
+
+            texto = cru.decode("utf-8", errors="replace") if cru else ""
+            try:
+                corpo = json.loads(texto) if texto else None
+            except ValueError:
+                corpo = None
+
+            if 200 <= status < 300:
+                env = corpo if isinstance(corpo, dict) else {}
+                return ApiResponse(
+                    data=env["data"] if "data" in env else corpo,
+                    meta=env.get("meta") or {},
+                    status=status,
+                    headers=rh,
+                    idempotent_replay=rh.get("idempotent-replay") == "true",
+                )
+
+            if 300 <= status < 400:
+                raise ZapcoreError(
+                    f"zapcore: {method} {path} respondeu redirect ({status}). O SDK não segue redirect "
+                    "para não vazar o token; confira o base_url (http→https? barra final?)",
+                    status=status, code="redirect_refused", request_id=rh.get("request-id"),
+                )
+            erro = _montar_erro(status, rh, corpo, texto, method, path)
+            # 409 idempotency_in_progress: a MESMA requisição ainda está em voo no motor; repetir a
+            # MESMA chave (``h`` é reaproveitado) após o Retry-After. Teto = ``max_retries``.
+            em_voo = status == 409 and chave is not None and erro.code == "idempotency_in_progress"
+            if tentativa < limite and (status == 429 or em_voo or (status in _RETENTAVEIS_5XX and seguro)):
+                espera = erro.retry_after if erro.retry_after is not None else _backoff(tentativa)
+                # Janela de hora/dia estourada: esperar 40 min dentro de um request é travar o processo.
+                if espera > self._max_retry_wait:
+                    raise erro
+                self._sleep(espera)
+                tentativa += 1
+                continue
+            raise erro
+
+    def paginate(self, path: str, query: Optional[Mapping[str, Any]] = None, **kw: Any) -> Iterator[Any]:
+        """Itera uma listagem por cursor; para quando ``next_cursor`` some ou a página volta vazia."""
+        cursor: Optional[str] = None
+        while True:
+            q = dict(query or {})
+            if cursor:
+                q["cursor"] = cursor
+            r = self.request("GET", path, query=q, **kw)
+            itens = r.data if isinstance(r.data, list) else []
+            yield from itens
+            cursor = r.meta.get("next_cursor") if itens else None
+            if not cursor:
+                return
+
+    # ------------------------------------------------------------ atalhos
+
+    def send_text(self, phone: str, text: str, **extra: Any) -> Dict[str, Any]:
+        """Envia texto. ``extra``: campos do corpo (``LinkPreview``…) e opções (``idempotency_key``…)."""
+        corpo, opts = _separar(extra)
+        return self.post_chat_send_text({**corpo, "Phone": destino(phone), "Body": text}, **opts)
+
+    def send_image(self, phone: str, image: Union[str, bytes], caption: Optional[str] = None, *, mime_type: str = "image/jpeg", **extra: Any) -> Dict[str, Any]:
+        """Envia imagem: data URL, base64 puro, URL http(s) (o SDK baixa) ou bytes."""
+        corpo, opts = _separar(extra)
+        corpo.update({"Phone": destino(phone), "Image": self._data_url(image, mime_type)})
+        if caption is not None:
+            corpo["Caption"] = caption
+        return self.post_chat_send_image(corpo, **opts)
+
+    def send_buttons(self, phone: str, text: str, buttons: Sequence[Union[str, Mapping[str, Any]]], **extra: Any) -> Dict[str, Any]:
+        """Botões (``reply``, ``cta_url``, ``cta_call``, ``copy``). Strings viram ``reply``."""
+        corpo, opts = _separar(extra)
+        lista = [{"id": f"b{i + 1}", "title": b, "type": "reply"} if isinstance(b, str) else dict(b) for i, b in enumerate(buttons)]
+        return self.post_chat_send_buttons({**corpo, "Phone": destino(phone), "Body": text, "Buttons": lista}, **opts)
+
+    def send_list(self, phone: str, text: str, button_text: str, sections: Sequence[Mapping[str, Any]], *, title: Optional[str] = None, footer: Optional[str] = None, **extra: Any) -> Dict[str, Any]:
+        corpo, opts = _separar(extra)
+        corpo.update({"Phone": destino(phone), "Desc": text, "ButtonText": button_text, "Sections": list(sections)})
+        if title is not None:
+            corpo["TopText"] = title
+        if footer is not None:
+            corpo["FooterText"] = footer
+        return self.post_chat_send_list(corpo, **opts)
+
+    def send_poll(self, to: str, question: str, choices: Sequence[str], **extra: Any) -> Dict[str, Any]:
+        corpo, opts = _separar(extra)
+        return self.post_chat_send_poll({**corpo, "group": destino(to), "header": question, "options": list(choices)}, **opts)
+
+    def get_qr(self, **opts: Any) -> Dict[str, Any]:
+        """QR de pareamento (data URL em ``QRCode``). Conecte antes com ``post_session_connect``."""
+        return self.get_session_qr(**opts)
+
+    def pair_phone(self, phone: str, **opts: Any) -> Dict[str, Any]:
+        """Pareia por código: devolve ``LinkingCode`` para digitar no celular."""
+        return self.post_session_pairphone({"Phone": destino(phone)}, **opts)
+
+    def status(self, **opts: Any) -> Dict[str, Any]:
+        return self.get_session_status(**opts)
+
+    def create_group(self, name: str, participants: Sequence[str], **extra: Any) -> Dict[str, Any]:
+        corpo, opts = _separar(extra)
+        return self.post_group_create({**corpo, "name": name, "participants": [destino(p) for p in participants]}, **opts)
+
+    def check_numbers(self, phones: Union[str, Sequence[str]], **opts: Any) -> List[Dict[str, Any]]:
+        """Quais números têm WhatsApp. Um item por número, na ordem enviada."""
+        lista = [phones] if isinstance(phones, str) else list(phones)
+        r = self.post_user_check({"Phone": [destino(p) for p in lista]}, **opts)
+        return list((r or {}).get("Users") or [])
+
+    def history(self, chat_jid: str, *, limit: Optional[int] = None, cursor: Optional[str] = None, **opts: Any) -> Page:
+        """Uma página do histórico (mais recente primeiro)."""
+        r = self.request("GET", "/api/v2/chat/history", query={"chat_jid": chat_jid, "limit": limit, "cursor": cursor}, **opts)
+        itens = r.data if isinstance(r.data, list) else []
+        return Page(items=itens, next_cursor=(r.meta.get("next_cursor") or None) if itens else None, meta=r.meta)
+
+    def iter_history(self, chat_jid: str, page_size: int = 100, **opts: Any) -> Iterator[Dict[str, Any]]:
+        """Itera o histórico inteiro, buscando páginas sob demanda."""
+        return self.paginate("/api/v2/chat/history", {"chat_jid": chat_jid, "limit": page_size}, **opts)
+
+    # ------------------------------------------------------------ internos
+
+    def _data_url(self, img: Union[str, bytes], mime: str) -> str:
+        if isinstance(img, (bytes, bytearray, memoryview)):
+            return f"data:{mime};base64,{base64.b64encode(bytes(img)).decode('ascii')}"
+        if img.startswith("data:"):
+            return _limpar_data_url(img)
+        if re.match(r"^https?://", img, re.I):
+            try:
+                if self._transport is urllib_transport:
+                    status, rh, cru = urllib_transport("GET", img, {}, None, self._timeout, MAX_DOWNLOAD_BYTES)
+                else:
+                    status, rh, cru = self._transport("GET", img, {}, None, self._timeout)
+            except OSError as e:
+                raise ZapcoreError(f"zapcore: falha de rede ao baixar a imagem: {e}", status=0, code="network_error") from e
+            if not 200 <= status < 300:
+                dica = ". A URL redirecionou: passe a URL final ou os bytes" if 300 <= status < 400 else ""
+                raise ZapcoreError(f"zapcore: não consegui baixar a imagem ({status}){dica}", status=status, code="bad_request")
+            if len(cru) > MAX_DOWNLOAD_BYTES:
+                raise _estouro(MAX_DOWNLOAD_BYTES)
+            tipo = (rh.get("content-type") or "").split(";")[0].strip().lower()
+            if tipo not in _IMAGENS_OK:
+                raise ZapcoreError(
+                    f"zapcore: a URL não devolveu uma imagem (Content-Type: {tipo or 'ausente'}); passe a URL final ou os bytes",
+                    status=status, code="bad_request",
+                )
+            return f"data:{tipo};base64,{base64.b64encode(cru).decode('ascii')}"
+        limpo = re.sub(r"\s+", "", img)
+        return f"data:{mime};base64,{limpo}"
+
+
+_OPCOES = {"idempotency_key", "headers", "timeout", "query"}
+
+
+def _separar(extra: Mapping[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    corpo = {k: v for k, v in extra.items() if k not in _OPCOES}
+    opts = {k: v for k, v in extra.items() if k in _OPCOES}
+    return corpo, opts
+
+
+def _montar_query(q: Optional[Mapping[str, Any]]) -> str:
+    if not q:
+        return ""
+    pares: List[Tuple[str, str]] = []
+    for k, v in q.items():
+        if v is None or v == "":
+            continue
+        if isinstance(v, bool):
+            pares.append((k, "true" if v else "false"))
+        elif isinstance(v, (list, tuple)):
+            pares.extend((k, str(x)) for x in v)
+        else:
+            pares.append((k, str(v)))
+    return "?" + urlencode(pares) if pares else ""
+
+
+def _montar_erro(status: int, rh: Mapping[str, str], corpo: Any, texto: str, method: str, path: str) -> ZapcoreError:
+    e = corpo.get("error") if isinstance(corpo, dict) else None
+    meta = corpo.get("meta") if isinstance(corpo, dict) else None
+    obj = e if isinstance(e, dict) else {}
+    msg = obj.get("message") or (e if isinstance(e, str) else f"zapcore: {method} {path} respondeu {status}" + (f": {texto[:200]}" if texto and corpo is None else ""))
+    return ZapcoreError(
+        msg,
+        status=status,
+        code=obj.get("code") or _POR_STATUS.get(status, "internal_error"),
+        field=obj.get("field"),
+        request_id=(meta or {}).get("request_id") or rh.get("request-id"),
+        retry_after=parse_retry_after(rh.get("retry-after")),
+        body=corpo if corpo is not None else texto,
+    )

zapcore/_errors.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class ZapcoreError(Exception):
+    """Erro da API v2. Case por ``code`` (contrato estável), nunca pela mensagem.
+
+    ``status`` é 0 em falha de rede (``code == "network_error"``).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str,
+        field: Optional[str] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.field = field
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body
+
+    def __repr__(self) -> str:
+        return f"ZapcoreError(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+class WebhookVerificationError(Exception):
+    """A assinatura HMAC do webhook não fechou."""