otensor-sdk 0.1.0__tar.gz

otensor_sdk-0.1.0/.env.example

@@ -0,0 +1,3 @@
+API_BASE_URL=http://localhost:8000
+API_KEY=sk-...
+DEVICE_ID=...

otensor_sdk-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# ── Secrets ──────────────────────────────────────────────────────────────────
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+*.p12
+
+# ── Python ────────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# ── Node / Web ────────────────────────────────────────────────────────────────
+node_modules/
+web/dist/
+web/.vite/
+web/coverage/
+
+# ── Android ───────────────────────────────────────────────────────────────────
+app/.gradle/
+app/build/
+app/local.properties
+*.apk
+*.aab
+
+# ── ESP-IDF / Firmware ────────────────────────────────────────────────────────
+firmware/build/
+firmware/managed_components/
+firmware/sdkconfig
+firmware/sdkconfig.old
+firmware/.cache/
+
+# ── AWS SAM ───────────────────────────────────────────────────────────────────
+.aws-sam/
+samconfig.toml
+
+# ── DynamoDB Local ────────────────────────────────────────────────────────────
+*.db
+shared-local-instance.db
+
+# ── IDEs ──────────────────────────────────────────────────────────────────────
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ── Logs ──────────────────────────────────────────────────────────────────────
+*.log
+logs/
+
+# ── Docs Site (Docusaurus) ────────────────────────────────────────────────────
+docs-site/node_modules/
+docs-site/build/
+docs-site/.docusaurus/
+
+# Pasta temporária para upload no Claude Design
+temp-claude-design/

otensor_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: otensor-sdk
+Version: 0.1.0
+Summary: Otensor Python SDK — para makers com hardware Linux/Raspberry Pi
+Project-URL: Homepage, https://github.com/Oseiasdfarias/otensor-platform
+Project-URL: Repository, https://github.com/Oseiasdfarias/otensor-platform
+Project-URL: Issues, https://github.com/Oseiasdfarias/otensor-platform/issues
+License: MIT
+Keywords: iot,mqtt,otensor,raspberry-pi,sdk,sense-hat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: paho-mqtt>=2.1
+Requires-Dist: pydantic>=2.9
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# otensor-sdk
+
+> **PT-BR** · SDK Python para makers com hardware Linux/Raspberry Pi — roda
+> **no dispositivo**, publica telemetria e recebe comandos da plataforma
+> [Otensor](https://github.com/Oseiasdfarias/otensor-platform).
+>
+> **EN** · Python SDK for makers running Linux/Raspberry Pi hardware — runs
+> **on the device**, publishes telemetry and receives commands from the
+> [Otensor](https://github.com/Oseiasdfarias/otensor-platform) platform.
+
+Diferença em relação à lib de automação (`pip install otensor`):
+
+| | `otensor-sdk` (este pacote) | `otensor` |
+|---|---|---|
+| Onde roda | **No hardware** (Raspberry Pi) | Em qualquer lugar |
+| O que faz | Publica telemetria, recebe comandos | Reage a eventos, cria automações |
+
+## Instalação
+
+```bash
+pip install otensor-sdk
+```
+
+Requer Python ≥ 3.11.
+
+## Configuração
+
+Gere uma **API key** no dashboard Otensor (as chaves começam com `sk-`) e
+cadastre um device do tipo `sense_hat_unit` (ou outro tipo do catálogo WoT).
+
+```dotenv
+API_BASE_URL=http://localhost:8000   # ou a URL real da sua instância
+API_KEY=sk-...
+DEVICE_ID=...
+```
+
+## Início rápido
+
+```python
+import os
+from otensor_sdk import OtensorSDK
+
+sdk = OtensorSDK(
+    api_base_url=os.environ["API_BASE_URL"],
+    api_key=os.environ["API_KEY"],
+    device_id=os.environ["DEVICE_ID"],
+)
+
+device = sdk.connect(device_type="sense_hat_unit")  # já conecta ao MQTT
+
+# publica uma leitura
+device.publish_property("temperature", 24.5)
+
+# recebe comandos da plataforma (registrar antes de qualquer publish, para
+# não perder um comando que chegue entre o connect() e o registro)
+@device.on_action("set_pixels")
+def handle_set_pixels(payload: dict) -> None:
+    print("acender LEDs:", payload)
+```
+
+### Publicando telemetria em loop (`TelemetryPublisher`)
+
+```python
+from otensor_sdk import TelemetryPublisher
+
+publisher = TelemetryPublisher(device, interval=5.0)
+publisher.set_source("temperature", lambda: sense_hat.get_temperature())
+publisher.set_source("humidity", lambda: sense_hat.get_humidity())
+publisher.run_forever()  # publica todas as sources a cada 5s, até Ctrl-C
+```
+
+Um exemplo completo, simulando um Raspberry Pi + Sense HAT sem hardware real,
+está em [`examples/mock_raspberry_pi.py`](examples/mock_raspberry_pi.py).
+
+## Desenvolvimento
+
+```bash
+cd sdk-python
+uv sync
+uv run pytest tests/ -q                      # testes unitários (sem infra real)
+RUN_E2E=1 uv run pytest tests/test_integration.py -v  # integração real (ver docstring do arquivo)
+```
+
+Processo de release (publicação no PyPI): ver [RELEASING.md](RELEASING.md).

otensor_sdk-0.1.0/README.md

@@ -0,0 +1,84 @@
+# otensor-sdk
+
+> **PT-BR** · SDK Python para makers com hardware Linux/Raspberry Pi — roda
+> **no dispositivo**, publica telemetria e recebe comandos da plataforma
+> [Otensor](https://github.com/Oseiasdfarias/otensor-platform).
+>
+> **EN** · Python SDK for makers running Linux/Raspberry Pi hardware — runs
+> **on the device**, publishes telemetry and receives commands from the
+> [Otensor](https://github.com/Oseiasdfarias/otensor-platform) platform.
+
+Diferença em relação à lib de automação (`pip install otensor`):
+
+| | `otensor-sdk` (este pacote) | `otensor` |
+|---|---|---|
+| Onde roda | **No hardware** (Raspberry Pi) | Em qualquer lugar |
+| O que faz | Publica telemetria, recebe comandos | Reage a eventos, cria automações |
+
+## Instalação
+
+```bash
+pip install otensor-sdk
+```
+
+Requer Python ≥ 3.11.
+
+## Configuração
+
+Gere uma **API key** no dashboard Otensor (as chaves começam com `sk-`) e
+cadastre um device do tipo `sense_hat_unit` (ou outro tipo do catálogo WoT).
+
+```dotenv
+API_BASE_URL=http://localhost:8000   # ou a URL real da sua instância
+API_KEY=sk-...
+DEVICE_ID=...
+```
+
+## Início rápido
+
+```python
+import os
+from otensor_sdk import OtensorSDK
+
+sdk = OtensorSDK(
+    api_base_url=os.environ["API_BASE_URL"],
+    api_key=os.environ["API_KEY"],
+    device_id=os.environ["DEVICE_ID"],
+)
+
+device = sdk.connect(device_type="sense_hat_unit")  # já conecta ao MQTT
+
+# publica uma leitura
+device.publish_property("temperature", 24.5)
+
+# recebe comandos da plataforma (registrar antes de qualquer publish, para
+# não perder um comando que chegue entre o connect() e o registro)
+@device.on_action("set_pixels")
+def handle_set_pixels(payload: dict) -> None:
+    print("acender LEDs:", payload)
+```
+
+### Publicando telemetria em loop (`TelemetryPublisher`)
+
+```python
+from otensor_sdk import TelemetryPublisher
+
+publisher = TelemetryPublisher(device, interval=5.0)
+publisher.set_source("temperature", lambda: sense_hat.get_temperature())
+publisher.set_source("humidity", lambda: sense_hat.get_humidity())
+publisher.run_forever()  # publica todas as sources a cada 5s, até Ctrl-C
+```
+
+Um exemplo completo, simulando um Raspberry Pi + Sense HAT sem hardware real,
+está em [`examples/mock_raspberry_pi.py`](examples/mock_raspberry_pi.py).
+
+## Desenvolvimento
+
+```bash
+cd sdk-python
+uv sync
+uv run pytest tests/ -q                      # testes unitários (sem infra real)
+RUN_E2E=1 uv run pytest tests/test_integration.py -v  # integração real (ver docstring do arquivo)
+```
+
+Processo de release (publicação no PyPI): ver [RELEASING.md](RELEASING.md).

otensor_sdk-0.1.0/RELEASING.md

@@ -0,0 +1,64 @@
+# Como publicar o `otensor-sdk` no PyPI
+
+Publicação automatizada via GitHub Actions
+([.github/workflows/publish-sdk-python.yml](../.github/workflows/publish-sdk-python.yml)),
+disparada por tag. Usa **PyPI Trusted Publishing (OIDC)** — não existe token
+de API guardado como secret em lugar nenhum.
+
+## Setup único (já feito uma vez, não repetir)
+
+Antes da primeira publicação, é preciso registrar o "pending publisher" no
+PyPI (só o dono da conta PyPI consegue fazer isso, via navegador):
+
+1. Acesse <https://pypi.org/manage/account/publishing/>
+2. "Add a new pending publisher" com exatamente estes valores:
+   - **PyPI Project Name:** `otensor-sdk`
+   - **Owner:** `Oseiasdfarias`
+   - **Repository name:** `otensor-platform`
+   - **Workflow name:** `publish-sdk-python.yml`
+   - **Environment name:** `pypi`
+
+Isso autoriza o workflow a publicar **antes mesmo de o pacote existir** no
+PyPI — não precisa fazer nenhum upload manual primeiro.
+
+(Opcional, recomendado) Em Settings → Environments → `pypi` deste repo no
+GitHub, adicionar um required reviewer — assim toda publicação real pausa
+para uma confirmação manual antes de rodar.
+
+## Processo de release (toda vez)
+
+```bash
+cd sdk-python
+
+# 1. bump de versão em pyproject.toml (campo `version`)
+#    seguir semver: PATCH para fix, MINOR para feature compatível, MAJOR para breaking change
+
+# 2. commit do bump
+git add pyproject.toml
+git commit -m "chore(sdk-python): bump versão para 0.2.0"
+
+# 3. tag no formato sdk-python-vX.Y.Z — precisa bater com pyproject.toml
+#    (o workflow falha em check-version se não bater)
+git tag sdk-python-v0.2.0
+
+# 4. push do commit e da tag
+git push origin local
+git push origin sdk-python-v0.2.0
+```
+
+O push da tag dispara o workflow: lint + testes unitários primeiro (não
+roda o `test_integration.py`, que exige infra local real), depois confere
+se a tag bate com `pyproject.toml`, depois builda (`uv build`) e publica.
+
+Acompanhar em: `https://github.com/Oseiasdfarias/otensor-platform/actions`
+
+## Se algo falhar
+
+- **`check-version` falhou:** tag e `pyproject.toml` estão diferentes.
+  Corrija um dos dois, apague a tag remota (`git push origin :refs/tags/sdk-python-vX.Y.Z`),
+  crie a tag certa e faça push de novo.
+- **`publish` falhou por permissão/trusted publisher:** confira se o
+  pending publisher no PyPI tem exatamente os valores acima — um typo no
+  nome do workflow ou do repo quebra o OIDC.
+- **Versão já existe no PyPI:** o PyPI não deixa sobrescrever uma versão já
+  publicada — sempre bump antes de tentar de novo.

otensor_sdk-0.1.0/examples/mock_raspberry_pi.py

@@ -0,0 +1,93 @@
+"""
+Mock de Raspberry Pi + Sense HAT — simula um device sense_hat_unit completo
+usando só a API pública do otensor_sdk, sem hardware real.
+
+Uso:
+  cd sdk-python
+  cp .env.example .env   # preencher API_BASE_URL, API_KEY, DEVICE_ID
+  uv run python examples/mock_raspberry_pi.py
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import random
+
+from dotenv import load_dotenv
+
+from otensor_sdk import OtensorSDK, TelemetryPublisher
+
+load_dotenv()
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [mock-rpi] %(levelname)s %(message)s")
+log = logging.getLogger("mock_raspberry_pi")
+
+_state = {"temperature": 25.0, "humidity": 55.0, "pressure": 1013.0}
+
+
+def _next_temperature() -> float:
+    _state["temperature"] = max(
+        -50.0, min(150.0, _state["temperature"] + random.uniform(-0.8, 0.8))
+    )
+    return round(_state["temperature"], 1)
+
+
+def _next_humidity() -> float:
+    _state["humidity"] = max(0.0, min(100.0, _state["humidity"] + random.uniform(-2.0, 2.0)))
+    return round(_state["humidity"], 1)
+
+
+def _next_pressure() -> float:
+    _state["pressure"] = max(800.0, min(1200.0, _state["pressure"] + random.uniform(-0.5, 0.5)))
+    return round(_state["pressure"], 1)
+
+
+def _next_vector() -> dict:
+    return {axis: round(random.uniform(-0.05, 0.05), 4) for axis in ("x", "y", "z")}
+
+
+def _next_lux() -> float:
+    return round(random.uniform(0, 1000), 1)
+
+
+def main() -> None:
+    sdk = OtensorSDK(
+        api_base_url=os.environ["API_BASE_URL"],
+        api_key=os.environ["API_KEY"],
+        device_id=os.environ["DEVICE_ID"],
+    )
+    device = sdk.connect(device_type="sense_hat_unit")
+    log.info("Conectado como device %s (tenant %s)", device.device_id, device.tenant_id)
+
+    @device.on_action("set_pixels")
+    def _set_pixels(payload: dict) -> None:
+        log.info("LED matrix: set_pixels(%s)", payload)
+
+    @device.on_action("clear_display")
+    def _clear_display(payload: dict) -> None:
+        log.info("LED matrix: clear_display()")
+
+    def _logged(name: str, source):
+        def _wrapped():
+            value = source()
+            log.info("%s = %s", name, value)
+            return value
+
+        return _wrapped
+
+    publisher = TelemetryPublisher(device, interval=5.0)
+    publisher.set_source("temperature", _logged("temperature", _next_temperature))
+    publisher.set_source("humidity", _logged("humidity", _next_humidity))
+    publisher.set_source("pressure", _logged("pressure", _next_pressure))
+    publisher.set_source("gyroscope", _logged("gyroscope", _next_vector))
+    publisher.set_source("magnetometer", _logged("magnetometer", _next_vector))
+    publisher.set_source("accelerometer", _logged("accelerometer", _next_vector))
+    publisher.set_source("lux", _logged("lux", _next_lux))
+
+    log.info("Publicando telemetria a cada 5s (Ctrl-C para sair)")
+    publisher.run_forever()
+
+
+if __name__ == "__main__":
+    main()

otensor_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "otensor-sdk"
+version = "0.1.0"
+description = "Otensor Python SDK — para makers com hardware Linux/Raspberry Pi"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["iot", "sdk", "mqtt", "raspberry-pi", "sense-hat", "otensor"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Home Automation",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "paho-mqtt>=2.1",
+    "pydantic>=2.9",
+    "httpx>=0.27",
+    "python-dotenv>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Oseiasdfarias/otensor-platform"
+Repository = "https://github.com/Oseiasdfarias/otensor-platform"
+Issues = "https://github.com/Oseiasdfarias/otensor-platform/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-cov>=5.0",
+    "ruff>=0.7",
+    "twine>=5.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/otensor_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "e2e: integração real contra API FastAPI + Mosquitto (pulado sem RUN_E2E=1)",
+]

otensor_sdk-0.1.0/src/otensor_sdk/__init__.py

@@ -0,0 +1,29 @@
+"""
+Otensor Python SDK — para makers com hardware Linux/Raspberry Pi.
+
+Import: from otensor_sdk import OtensorSDK
+
+Diferença em relação à lib de automação (pip install otensor):
+  otensor_sdk  →  roda NO hardware (RPi), publica telemetria, recebe comandos
+  otensor      →  roda EM QUALQUER LUGAR, reage a eventos, cria automações em Python
+"""
+
+from .client import OtensorSDK
+from .device import Device
+from .exceptions import OtensorAuthError, OtensorError, OtensorSessionError
+from .telemetry import TelemetryPublisher
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OtensorSDK",
+    "Device",
+    "TelemetryPublisher",
+    "OtensorError",
+    "OtensorAuthError",
+    "OtensorSessionError",
+]
+
+# gpio.py / sensehat.py — wrappers de RPi.GPIO e sense-hat: fora de escopo até
+# haver hardware real para validar contra (ver docs/superpowers/specs/
+# 2026-07-03-sdk-python-mock-raspberry-pi-design.md).

otensor_sdk-0.1.0/src/otensor_sdk/client.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import httpx
+
+from .device import Device, MQTTClientProtocol
+from .exceptions import OtensorAuthError, OtensorSessionError
+
+
+def _default_mqtt_client() -> MQTTClientProtocol:
+    import paho.mqtt.client as mqtt
+
+    return mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
+
+
+class OtensorSDK:
+    def __init__(
+        self,
+        api_base_url: str,
+        api_key: str,
+        device_id: str,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._device_id = device_id
+        self._http = http_client or httpx.Client(base_url=api_base_url.rstrip("/"), timeout=10.0)
+
+    def connect(self, device_type: str, mqtt_client: MQTTClientProtocol | None = None) -> Device:
+        response = self._http.post(
+            "/v1/sessions/mqtt",
+            headers={"Authorization": f"ApiKey {self._api_key}"},
+        )
+        if response.status_code == 401:
+            raise OtensorAuthError("API key inválida ou revogada.")
+        if response.status_code != 200:
+            raise OtensorSessionError(
+                f"Falha ao obter sessão MQTT: {response.status_code} {response.text}"
+            )
+        try:
+            data = response.json()["data"]
+            tenant_id = data["tenant_id"]
+            broker_host = data["broker_host"]
+            broker_port = data["broker_port"]
+            username = data["username"]
+            password = data["password"]
+        except (KeyError, ValueError) as exc:
+            raise OtensorSessionError(f"Resposta malformada de /v1/sessions/mqtt: {exc}") from exc
+
+        device = Device(
+            mqtt_client=mqtt_client or _default_mqtt_client(),
+            tenant_id=tenant_id,
+            device_id=self._device_id,
+            device_type=device_type,
+            broker_host=broker_host,
+            broker_port=broker_port,
+            username=username,
+            password=password,
+        )
+        device.connect()
+        return device

otensor_sdk-0.1.0/src/otensor_sdk/device.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Callable, Protocol
+
+log = logging.getLogger("otensor_sdk.device")
+
+
+class MQTTClientProtocol(Protocol):
+    on_message: Callable[[Any, Any, Any], None] | None
+
+    def username_pw_set(self, username: str, password: str | None = None) -> None: ...
+    def connect(self, host: str, port: int, keepalive: int = 60) -> None: ...
+    def disconnect(self) -> None: ...
+    def loop_start(self) -> None: ...
+    def loop_stop(self) -> None: ...
+    def subscribe(self, topic: str, qos: int = 0) -> Any: ...
+    def publish(self, topic: str, payload: str, qos: int = 0) -> Any: ...
+
+
+class Device:
+    def __init__(
+        self,
+        mqtt_client: MQTTClientProtocol,
+        tenant_id: str,
+        device_id: str,
+        device_type: str,
+        broker_host: str,
+        broker_port: int,
+        username: str,
+        password: str,
+    ) -> None:
+        self._client = mqtt_client
+        self.tenant_id = tenant_id
+        self.device_id = device_id
+        self.device_type = device_type
+        self._broker_host = broker_host
+        self._broker_port = broker_port
+        self._username = username
+        self._password = password
+        self._action_handlers: dict[str, Callable[[dict], None]] = {}
+        self._base_topic = f"ot/{tenant_id}/d/{device_id}"
+        self._client.on_message = self._dispatch_message
+
+    def connect(self) -> None:
+        """Conecta ao broker MQTT e assina o tópico de comandos (`cmd`).
+
+        Atenção — janela de corrida: a assinatura do tópico `cmd` acontece
+        aqui, antes de o chamador ter chance de registrar handlers via
+        `on_action(...)`. Um comando publicado exatamente entre o retorno
+        deste método e o registro do handler correspondente é descartado
+        silenciosamente, pois `_action_handlers` ainda estará vazio no
+        momento em que a mensagem chegar. Registre todos os `on_action`
+        antes de considerar o dispositivo pronto para receber comandos
+        (ou, idealmente, antes de chamar `connect()`).
+        """
+        self._client.username_pw_set(self._username, self._password)
+        self._client.connect(self._broker_host, self._broker_port, keepalive=60)
+        self._client.loop_start()
+        self._client.subscribe(f"{self._base_topic}/cmd", qos=1)
+
+    def disconnect(self) -> None:
+        self._client.loop_stop()
+        self._client.disconnect()
+
+    def publish_property(self, name: str, value: object) -> None:
+        payload = json.dumps({name: value})
+        self._client.publish(f"{self._base_topic}/telemetry", payload, qos=1)
+
+    def on_action(self, name: str) -> Callable[[Callable[[dict], None]], Callable[[dict], None]]:
+        def decorator(fn: Callable[[dict], None]) -> Callable[[dict], None]:
+            self._action_handlers[name] = fn
+            return fn
+
+        return decorator
+
+    def _dispatch_message(self, client: object, userdata: object, msg: object) -> None:
+        try:
+            payload = json.loads(msg.payload.decode())  # type: ignore[attr-defined]
+        except (json.JSONDecodeError, UnicodeDecodeError, AttributeError):
+            log.warning("comando MQTT inválido em %s", getattr(msg, "topic", "?"))
+            return
+        if not isinstance(payload, dict):
+            log.warning("comando MQTT inválido em %s", getattr(msg, "topic", "?"))
+            return
+        action = payload.get("action", "")
+        params = payload.get("payload") or {}
+        handler = self._action_handlers.get(action)
+        if handler is not None:
+            handler(params)
+
+    def __enter__(self) -> "Device":
+        self.connect()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.disconnect()

otensor_sdk-0.1.0/src/otensor_sdk/exceptions.py

@@ -0,0 +1,10 @@
+class OtensorError(Exception):
+    """Erro base do SDK Otensor."""
+
+
+class OtensorAuthError(OtensorError):
+    """API key inválida ou revogada (HTTP 401 em /v1/sessions/mqtt)."""
+
+
+class OtensorSessionError(OtensorError):
+    """Falha ao obter uma sessão MQTT (qualquer status ≠ 200/401)."""