aronline-sdk 0.3.0__py3-none-any.whl

aronline/__init__.py

@@ -0,0 +1,119 @@
+"""Official SDK for the AR Online API.
+
+The SDK speaks two surfaces. The /v3 resources at the top of ``Client`` are the
+clean contract. ``client.legacy`` speaks the old gateway exactly as its public
+documentation describes it -- idiosyncrasies included -- because an integration
+written against the old API needs typed calls today, and normalizing the old
+contract would break the callers the area exists to keep working.
+
+The /v1 and /v2 mirrors are not covered: they answer the old contracts byte for
+byte, and a typed client that "improved" them would break the same callers.
+"""
+
+from aronline.client import Client
+from aronline.errors import ApiError, ErrorDetail
+from aronline.http.transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from aronline.legacy.area import LegacyArea
+from aronline.legacy.errors import LegacyApiError
+from aronline.legacy.models import (
+    GW_TEMPLATE_TYPES,
+    SMS_TYPE_SENDS,
+    Anexo,
+    CanalCarta,
+    CanalSms,
+    CanalVoz,
+    CanalWhatsapp,
+    EnvioRequest,
+    EnvioResponse,
+    EnvioValidation,
+    FinalizarReguaResult,
+    FullChannelDetail,
+    GwTemplate,
+    GwTemplateType,
+    GwTemplateWriteResult,
+    SendingProof,
+    SmsAnswer,
+    SmsTypeSend,
+    StatusCarta,
+    StatusEmail,
+    StatusEvent,
+    StatusFull,
+    StatusHistory,
+    StatusLast,
+    StatusSms,
+    StatusVoz,
+    StatusWhatsapp,
+    UpdateGwTemplate,
+    WebhookChannel,
+    WebhookMetadata,
+    WebhookPayloadV1,
+    WebhookPayloadV2,
+    WebhookStatusPayload,
+)
+from aronline.legacy.transport import DEFAULT_LEGACY_BASE_URL
+from aronline.models import (
+    CHANNELS,
+    AllowlistEntry,
+    Channel,
+    Freshness,
+    Tag,
+    Template,
+    TemplateVariable,
+    Version,
+)
+
+#: This package's version -- the same string ``pyproject.toml`` carries.
+VERSION = "0.3.0"
+
+__all__ = [
+    "CHANNELS",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_LEGACY_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "GW_TEMPLATE_TYPES",
+    "SMS_TYPE_SENDS",
+    "VERSION",
+    "AllowlistEntry",
+    "Anexo",
+    "ApiError",
+    "CanalCarta",
+    "CanalSms",
+    "CanalVoz",
+    "CanalWhatsapp",
+    "Channel",
+    "Client",
+    "EnvioRequest",
+    "EnvioResponse",
+    "EnvioValidation",
+    "ErrorDetail",
+    "FinalizarReguaResult",
+    "Freshness",
+    "FullChannelDetail",
+    "GwTemplate",
+    "GwTemplateType",
+    "GwTemplateWriteResult",
+    "LegacyApiError",
+    "LegacyArea",
+    "SendingProof",
+    "SmsAnswer",
+    "SmsTypeSend",
+    "StatusCarta",
+    "StatusEmail",
+    "StatusEvent",
+    "StatusFull",
+    "StatusHistory",
+    "StatusLast",
+    "StatusSms",
+    "StatusVoz",
+    "StatusWhatsapp",
+    "Tag",
+    "Template",
+    "TemplateVariable",
+    "UpdateGwTemplate",
+    "Version",
+    "WebhookChannel",
+    "WebhookMetadata",
+    "WebhookPayloadV1",
+    "WebhookPayloadV2",
+    "WebhookStatusPayload",
+]

aronline/client.py

@@ -0,0 +1,75 @@
+"""The client -- the one thing you construct."""
+
+from __future__ import annotations
+
+import urllib.request
+
+from aronline.http.transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, Transport
+from aronline.legacy.area import LegacyArea
+from aronline.legacy.transport import DEFAULT_LEGACY_BASE_URL, LegacyTransport
+from aronline.resources.allowlist import AllowlistResource
+from aronline.resources.freshness import FreshnessResource
+from aronline.resources.tags import TagsResource
+from aronline.resources.templates import TemplatesResource
+from aronline.resources.version import VersionResource
+
+__all__ = ["Client"]
+
+
+class Client:
+    """The AR Online API client.
+
+    ::
+
+        from aronline import Client
+
+        client = Client(token=os.environ["AR_TOKEN"])
+        templates = client.templates.list(channel="whatsapp")
+
+    It owns the transport and hands it to each resource; the resources are the
+    public surface. Nothing above this line knows that HTTP is involved.
+
+    ``client.legacy`` is the second surface: the old gateway's contract, spoken
+    exactly as documented, with its own address and its own credential
+    (``legacy_token``). It exists so an integration on the old API gets typed
+    calls today and migrates to /v3 by SDK update, not by rewrite.
+
+    Each credential is optional: pass only the one for the surface you use.
+    Neither leaks into the other's calls.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        legacy_token: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        legacy_base_url: str = DEFAULT_LEGACY_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        opener: urllib.request.OpenerDirector | None = None,
+    ) -> None:
+        transport = Transport(
+            token=token,
+            base_url=base_url,
+            timeout=timeout,
+            opener=opener,
+        )
+        legacy_transport = LegacyTransport(
+            token=legacy_token,
+            base_url=legacy_base_url,
+            timeout=timeout,
+            opener=opener,
+        )
+
+        #: Message templates.
+        self.templates = TemplatesResource(transport)
+        #: Your labels.
+        self.tags = TagsResource(transport)
+        #: Your allowed recipients.
+        self.allowlist = AllowlistResource(transport)
+        #: How fresh the copy of the data is.
+        self.freshness = FreshnessResource(transport)
+        #: Which version is running. The one route that needs no token.
+        self.version = VersionResource(transport)
+        #: The legacy gateway surface -- today's contract, idiosyncrasies included.
+        self.legacy = LegacyArea(legacy_transport)

aronline/errors.py

@@ -0,0 +1,60 @@
+"""What a refusal from the API looks like on this side."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+__all__ = ["ApiError", "ErrorDetail"]
+
+
+class ErrorDetail(TypedDict):
+    """One field-level complaint inside a validation error."""
+
+    field: str
+    code: str
+    message: str
+
+
+class ApiError(Exception):
+    """A refusal from the API, raised so a failed call cannot pass for a good one.
+
+    ``request_id`` is a first-class attribute on purpose: it is the first thing
+    support asks for, and an SDK that swallowed it would force whoever hit the
+    failure to reproduce it with curl just to find the number.
+    """
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str | None,
+        field: str | None = None,
+        details: list[ErrorDetail] | None = None,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(message)
+
+        #: The HTTP status. Zero when the API was never reached.
+        self.status = status
+        #: The catalog code -- ``not_found``, ``forbidden``, ``rate_limited``, ...
+        self.code = code
+        #: The message the API sent, in pt-BR.
+        self.message = message
+        #: From the error body, or from the ``X-Request-Id`` header when absent.
+        self.request_id = request_id
+        #: The field at fault, when the refusal is about one.
+        self.field = field
+        #: One entry per rejected field, on validation errors.
+        self.details = details
+        #: From the ``Retry-After`` header, on 429 and 503.
+        self.retry_after_seconds = retry_after_seconds
+
+    @property
+    def retryable(self) -> bool:
+        """True for the statuses the API says are worth trying again."""
+        return self.status in (429, 503)
+
+    def __repr__(self) -> str:
+        return f"ApiError(status={self.status}, code={self.code!r}, request_id={self.request_id!r})"

aronline/http/__init__.py

@@ -0,0 +1,5 @@
+"""The only part of the SDK that knows HTTP exists."""
+
+from aronline.http.transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, Transport
+
+__all__ = ["DEFAULT_BASE_URL", "DEFAULT_TIMEOUT", "Transport"]

aronline/http/error_envelope.py

@@ -0,0 +1,61 @@
+"""Turning a refused response into an ``ApiError``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aronline.errors import ApiError
+
+__all__ = ["to_api_error"]
+
+
+def to_api_error(
+    status: int,
+    body: Any,
+    request_id: str | None,
+    retry_after: str | None,
+) -> ApiError:
+    """Build the error a refusal becomes.
+
+    A refusal that does not carry the envelope is still a refusal: a proxy
+    answering 502 in HTML has to fail the same way, or whoever hit it goes
+    looking for a bug in their own parsing code.
+    """
+    envelope = _read_envelope(body)
+
+    return ApiError(
+        status=status,
+        code=envelope.get("code") or "invalid_response",
+        message=envelope.get("message") or f"a API respondeu {status} sem o corpo de erro esperado",
+        request_id=envelope.get("request_id") or request_id,
+        field=envelope.get("field"),
+        details=envelope.get("details"),
+        retry_after_seconds=_read_retry_after(retry_after),
+    )
+
+
+def _read_envelope(body: Any) -> dict[str, Any]:
+    if not isinstance(body, dict):
+        return {}
+
+    error = body.get("error")
+
+    return error if isinstance(error, dict) else {}
+
+
+def _read_retry_after(header: str | None) -> float | None:
+    """Seconds, or nothing.
+
+    ``Retry-After`` also has an HTTP-date form. The API only ever sends
+    seconds, so anything else is dropped rather than guessed at -- a wrong
+    delay is worse than no delay.
+    """
+    if header is None:
+        return None
+
+    try:
+        seconds = float(header)
+    except ValueError:
+        return None
+
+    return seconds if seconds >= 0 else None

aronline/http/json_body.py

@@ -0,0 +1,30 @@
+"""Reading a response body that claims to be JSON.
+
+Both transports need the same distinction: "the body was not JSON" is not the
+same thing as "the body was ``null``". A proxy answering HTML has to fail like
+any other refusal, while a route that legitimately answers ``null`` has to keep
+answering it.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+__all__ = ["UNPARSED", "parse_json"]
+
+
+class _Unparsed:
+    """Tells "the body was not JSON" apart from "the body was ``null``"."""
+
+
+#: What :func:`parse_json` returns when the text is not JSON at all.
+UNPARSED = _Unparsed()
+
+
+def parse_json(text: str) -> Any:
+    """The parsed body, or :data:`UNPARSED` when the text is not JSON."""
+    try:
+        return json.loads(text)
+    except ValueError:
+        return UNPARSED

aronline/http/transport.py

@@ -0,0 +1,158 @@
+"""The HTTP layer, and the only place in the SDK that knows it exists."""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from aronline.errors import ApiError
+from aronline.http.error_envelope import to_api_error
+from aronline.http.json_body import UNPARSED, parse_json
+
+__all__ = ["DEFAULT_BASE_URL", "DEFAULT_TIMEOUT", "Transport"]
+
+#: Where /v3 lives. Override it for staging or for a local process.
+DEFAULT_BASE_URL = "https://v3.ar-online.com.br"
+
+#: How long a call waits before giving up, in seconds.
+DEFAULT_TIMEOUT = 30.0
+
+
+class Transport:
+    """Builds the request, reads the answer, and raises what went wrong.
+
+    Everything above it -- the resources, the client -- deals in functions and
+    dictionaries. That is the whole point of the package: whoever installs it
+    should never build a URL, set a header, read a status or unwrap an
+    envelope.
+
+    It uses ``urllib`` from the standard library on purpose: an SDK with no
+    dependencies is one that never conflicts with what the application already
+    pinned.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        opener: urllib.request.OpenerDirector | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._timeout = timeout
+        self._opener = opener or urllib.request.build_opener()
+
+    def envelope(
+        self,
+        path: str,
+        *,
+        query: dict[str, str | None] | None = None,
+        authenticated: bool = True,
+    ) -> Any:
+        """For the routes that answer ``{"data": ...}`` -- templates, tags, allowlist.
+
+        Not every route wraps its answer, which is the one trap of this API:
+        freshness and version answer the object itself. Unwrapping all of them,
+        or none, breaks half the calls, so the choice is made per route by
+        whichever method the resource calls.
+        """
+        body = self.bare(path, query=query, authenticated=authenticated)
+
+        if not isinstance(body, dict) or "data" not in body:
+            raise ApiError(
+                status=200,
+                code="invalid_response",
+                message=f"{path} respondeu sem o envelope 'data' que a rota promete",
+                request_id=None,
+            )
+
+        return body["data"]
+
+    def bare(
+        self,
+        path: str,
+        *,
+        query: dict[str, str | None] | None = None,
+        authenticated: bool = True,
+    ) -> Any:
+        """For the routes that answer the object directly -- freshness, version."""
+        # Refused here, before the socket: a 401 round trip teaches nothing
+        # that the missing token does not already say.
+        if authenticated and self._token is None:
+            raise ApiError(
+                status=401,
+                code="unauthenticated",
+                message=f"{path} exige um token; construa o cliente com token=...",
+                request_id=None,
+            )
+
+        request = urllib.request.Request(
+            self.url(path, query),
+            method="GET",
+            headers=self._headers(authenticated),
+        )
+
+        status, text, headers = self._send(request)
+        body = parse_json(text)
+        request_id = headers.get("X-Request-Id")
+
+        if status >= 400:
+            raise to_api_error(status, body, request_id, headers.get("Retry-After"))
+
+        # A 200 that is not JSON is something other than the API answering. It
+        # fails like any other refusal -- a raw JSONDecodeError leaking out
+        # here would send whoever hit it looking for a bug in their own code.
+        if body is UNPARSED:
+            raise ApiError(
+                status=status,
+                code="invalid_response",
+                message="a resposta não é JSON — algo respondeu no lugar da API",
+                request_id=request_id,
+            )
+
+        return body
+
+    def url(self, path: str, query: dict[str, str | None] | None = None) -> str:
+        """The absolute URL of a path. Exposed because the tests assert on it."""
+        filled = {key: value for key, value in (query or {}).items() if value is not None}
+        suffix = f"?{urllib.parse.urlencode(filled)}" if filled else ""
+
+        return f"{self._base_url}{path}{suffix}"
+
+    def _headers(self, authenticated: bool) -> dict[str, str]:
+        headers = {"Accept": "application/json"}
+
+        if authenticated and self._token is not None:
+            headers["Authorization"] = f"Bearer {self._token}"
+
+        return headers
+
+    def _send(self, request: urllib.request.Request) -> tuple[int, str, Any]:
+        try:
+            with self._opener.open(request, timeout=self._timeout) as response:
+                return response.status, _read(response), response.headers
+        except urllib.error.HTTPError as error:
+            # urllib raises on 4xx and 5xx. They are answers, not failures:
+            # the body carries the catalog, and the caller needs it.
+            with error:
+                return error.code, _read(error), error.headers
+        except (urllib.error.URLError, OSError) as error:
+            # Timeout and connection refused arrive as opaque platform errors.
+            # They become the SDK's own error so a caller has one type to catch
+            # instead of three.
+            raise ApiError(
+                status=0,
+                code="unreachable",
+                message=f"não foi possível falar com {self._base_url}: {error}",
+                request_id=None,
+            ) from error
+
+
+def _read(response: Any) -> str:
+    payload: bytes = response.read()
+
+    return payload.decode("utf-8", errors="replace")

aronline/legacy/__init__.py

@@ -0,0 +1,32 @@
+"""The legacy gateway surface -- today's contract, idiosyncrasies included.
+
+The /v3 resources at the top of the package are the clean contract. This area
+speaks the old gateway exactly as its public documentation describes it, so an
+integration written against the old API gets typed calls today; when a /v3
+equivalent lands, the legacy function swaps transport without changing its
+signature.
+
+The names here follow the **legacy vocabulary** -- ``laudo``, ``regua``,
+``voz``, ``carta``, ``EnvioRequest``. It is a deliberate exception to the
+project's English rule: translating them would create a vocabulary that exists
+in no documentation anywhere. Only the case convention is adapted to Python.
+"""
+
+from aronline.legacy.area import LegacyArea
+from aronline.legacy.errors import LegacyApiError
+from aronline.legacy.resources import (
+    LegacyResource,
+    LegacyStatusResource,
+    LegacyTemplatesResource,
+)
+from aronline.legacy.transport import DEFAULT_LEGACY_BASE_URL, LegacyTransport
+
+__all__ = [
+    "DEFAULT_LEGACY_BASE_URL",
+    "LegacyApiError",
+    "LegacyArea",
+    "LegacyResource",
+    "LegacyStatusResource",
+    "LegacyTemplatesResource",
+    "LegacyTransport",
+]

aronline/legacy/area.py

@@ -0,0 +1,127 @@
+"""The legacy gateway, as functions."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import urllib.parse
+from typing import Any, cast
+
+from aronline.legacy.errors import LegacyApiError
+from aronline.legacy.models.envio import EnvioRequest, EnvioResponse
+from aronline.legacy.models.regua import FinalizarReguaResult
+from aronline.legacy.models.sending_proof import SendingProof
+from aronline.legacy.resources.status import LegacyStatusResource
+from aronline.legacy.resources.templates import LegacyTemplatesResource
+from aronline.legacy.transport import LegacyTransport
+
+__all__ = ["LegacyArea"]
+
+
+class LegacyArea:
+    """Everything docs.ar-online.com.br documents of the gateway, spoken exactly
+    as the old API speaks it.
+
+    ::
+
+        from aronline import Client
+
+        client = Client(legacy_token=os.environ["AR_GW_TOKEN"])
+        sent = client.legacy.send({"nameTo": "João", "subject": "…", "content": "…"})
+        status = client.legacy.status.email(sent["idEmail"])
+
+    This area exists so an integration written against the old contract gets
+    typed calls today. As /v3 grows an equivalent for a route, the function here
+    swaps its transport without changing shape -- the migration happens under
+    your feet, not in your code. Each function's documentation names its /v3
+    equivalent when one exists.
+    """
+
+    def __init__(self, transport: LegacyTransport) -> None:
+        self._transport = transport
+
+        #: Per-channel status and the consolidated forensic view.
+        self.status = LegacyStatusResource(transport)
+        #: The gateway's template routes. The /v3 equivalent for reads is
+        #: ``client.templates``.
+        self.templates = LegacyTemplatesResource(transport)
+
+    def send(self, envio: EnvioRequest) -> EnvioResponse:
+        """Sends a notification -- ``POST /gw/email``, the multichannel route
+        despite the name.
+
+        Processing is asynchronous: keep the returned ``idEmail``, it is the
+        handle for every status and proof question later.
+
+        No /v3 equivalent yet.
+        """
+        return cast("EnvioResponse", self._transport.json("POST", "/gw/email", body=envio))
+
+    def sending_proof(self, id_email: str) -> SendingProof:
+        """The sending proof as a PDF.
+
+        The wire carries it in base64 inside JSON; this decodes it for you and
+        keeps the raw string reachable. While the e-mail has no delivery status
+        the gateway answers a message instead, and ``pdf`` comes back ``None``
+        -- ask again later. That is an answer, not a refusal.
+
+        No /v3 equivalent yet.
+        """
+        body: Any = self._transport.json("GET", f"/gw/sending-proof/{_quote(id_email)}")
+        content = body.get("content") if isinstance(body, dict) else None
+
+        if not isinstance(content, str):
+            message = body.get("message") if isinstance(body, dict) else None
+
+            return {
+                "pdf": None,
+                "content_base64": None,
+                "message": message if isinstance(message, str) else None,
+            }
+
+        return {"pdf": _decode_base64(content), "content_base64": content, "message": None}
+
+    def laudo(self, id_email: str) -> bytes:
+        """The expert-evidence report -- the one route that answers the PDF
+        binary directly, no base64, no JSON.
+
+        No /v3 equivalent yet.
+        """
+        return self._transport.binary(f"/gw/email/laudo/{_quote(id_email)}")
+
+    def finalizar_regua(self, id_email: str) -> FinalizarReguaResult:
+        """Stops the notification ladder for this send.
+
+        A GET with a side effect -- that is the old contract, and the SDK does
+        not "fix" it to POST. A caller who saw ``GET`` and assumed it was safe
+        to repeat would be repeating a write.
+
+        No /v3 equivalent yet.
+        """
+        return cast(
+            "FinalizarReguaResult",
+            self._transport.json("GET", f"/regua-notificacao/finalizar/{_quote(id_email)}"),
+        )
+
+
+def _quote(id_email: str) -> str:
+    """Escaped, so a crooked id cannot become another path."""
+    return urllib.parse.quote(id_email, safe="")
+
+
+def _decode_base64(content: str) -> bytes:
+    """The proof, decoded, or the SDK's own error.
+
+    ``validate=True`` on purpose: without it, base64 that is not base64 decodes
+    to garbage bytes, and the caller writes a corrupt PDF to disk instead of
+    finding out that the gateway answered something unexpected.
+    """
+    try:
+        return base64.b64decode(content, validate=True)
+    except (binascii.Error, ValueError) as error:
+        raise LegacyApiError(
+            status=200,
+            http_status=200,
+            message="o comprovante veio com base64 ilegível",
+            body={"content": content},
+        ) from error