ngits-drf-iot-client 0.1.0__tar.gz

ngits_drf_iot_client-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: ngits-drf-iot-client
+Version: 0.1.0
+Summary: Identity-agnostic Django/DRF client for the NGITS IoT ESB automation & command APIs
+Author-email: "NG IT Services Sp. z o.o." <biuro@ngits.pl>
+License: BSD-3-Clause
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Django>=4.2
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: requests>=2.31
+Provides-Extra: schemas
+Requires-Dist: drf-spectacular>=0.27; extra == "schemas"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: isort>=5.13.0; extra == "dev"
+Requires-Dist: drf-spectacular>=0.27; extra == "dev"
+
+# ngits-drf-iot-client
+
+Identity-agnostic Django/DRF client for the **IoT ESB** automation and command
+APIs. It lets any application (a single-tenant app, a multi-tenant panel, ...)
+act as a thin BFF over the shared IoT platform **without duplicating domain
+logic** — the same way `ngits-drf-cube-proxy` sits in front of analytics.
+
+The automation domain (models, evaluation, command dispatch) lives in the IoT
+platform services. This package is only the transport + tenant-scoping glue
+used by the presentation layer.
+
+## Install
+
+```bash
+pip install ngits-drf-iot-client
+# during local development, before it is published:
+pip install -e ../ngits-drf-iot-client
+```
+
+## Configure (host `settings.py`)
+
+```python
+IOT_ESB_BASE_URL = "https://iot-esb.example.com"  # client appends /api/v1
+IOT_ESB_TOKEN = env("IOT_ESB_TOKEN")              # sent as X-Token
+IOT_CLIENT_IDENTITY_RESOLVER = "myapp.iot.resolve_scope"
+# optional:
+IOT_CLIENT_TIMEOUT = 10
+```
+
+The resolver maps an authenticated user to the tenant(s) they may access:
+
+```python
+# myapp/iot.py  (single-tenant app)
+def resolve_scope(user):
+    tenant = get_tenant_for(user)                    # your own lookup
+    return None if tenant is None else tenant.uuid   # None -> 403
+
+# multi-tenant panel
+def resolve_scope(user):
+    return list(get_tenants_for(user))               # iterable of tenant UUIDs
+```
+
+## Use in a DRF view
+
+```python
+from rest_framework import viewsets
+from rest_framework.response import Response
+from iot_client import IotClientMixin
+
+class AutomationViewSet(IotClientMixin, viewsets.ViewSet):
+    def list(self, request):
+        client = self.get_iot_client()
+        return Response(client.list_automations(tenants=self.get_tenant_scope()))
+
+    def create(self, request):
+        client = self.get_iot_client()
+        return Response(client.create_automation(request.data), status=201)
+```
+
+## Client surface
+
+`IotEsbClient`: `list_automations`, `get_automation`, `create_automation`,
+`update_automation`, `delete_automation`, `activate_automation`,
+`deactivate_automation`, `list_rule_types`, `list_actions`, `create_command`,
+`get_command`. All read methods accept a `tenants` scope; errors raise
+`IotClientError(status_code=...)`.

ngits_drf_iot_client-0.1.0/README.md

@@ -0,0 +1,66 @@
+# ngits-drf-iot-client
+
+Identity-agnostic Django/DRF client for the **IoT ESB** automation and command
+APIs. It lets any application (a single-tenant app, a multi-tenant panel, ...)
+act as a thin BFF over the shared IoT platform **without duplicating domain
+logic** — the same way `ngits-drf-cube-proxy` sits in front of analytics.
+
+The automation domain (models, evaluation, command dispatch) lives in the IoT
+platform services. This package is only the transport + tenant-scoping glue
+used by the presentation layer.
+
+## Install
+
+```bash
+pip install ngits-drf-iot-client
+# during local development, before it is published:
+pip install -e ../ngits-drf-iot-client
+```
+
+## Configure (host `settings.py`)
+
+```python
+IOT_ESB_BASE_URL = "https://iot-esb.example.com"  # client appends /api/v1
+IOT_ESB_TOKEN = env("IOT_ESB_TOKEN")              # sent as X-Token
+IOT_CLIENT_IDENTITY_RESOLVER = "myapp.iot.resolve_scope"
+# optional:
+IOT_CLIENT_TIMEOUT = 10
+```
+
+The resolver maps an authenticated user to the tenant(s) they may access:
+
+```python
+# myapp/iot.py  (single-tenant app)
+def resolve_scope(user):
+    tenant = get_tenant_for(user)                    # your own lookup
+    return None if tenant is None else tenant.uuid   # None -> 403
+
+# multi-tenant panel
+def resolve_scope(user):
+    return list(get_tenants_for(user))               # iterable of tenant UUIDs
+```
+
+## Use in a DRF view
+
+```python
+from rest_framework import viewsets
+from rest_framework.response import Response
+from iot_client import IotClientMixin
+
+class AutomationViewSet(IotClientMixin, viewsets.ViewSet):
+    def list(self, request):
+        client = self.get_iot_client()
+        return Response(client.list_automations(tenants=self.get_tenant_scope()))
+
+    def create(self, request):
+        client = self.get_iot_client()
+        return Response(client.create_automation(request.data), status=201)
+```
+
+## Client surface
+
+`IotEsbClient`: `list_automations`, `get_automation`, `create_automation`,
+`update_automation`, `delete_automation`, `activate_automation`,
+`deactivate_automation`, `list_rule_types`, `list_actions`, `create_command`,
+`get_command`. All read methods accept a `tenants` scope; errors raise
+`IotClientError(status_code=...)`.

ngits_drf_iot_client-0.1.0/iot_client/__init__.py

@@ -0,0 +1,28 @@
+"""NGITS DRF IoT client.
+
+A thin, identity-agnostic client + DRF helpers for the IoT ESB automation,
+command and alert APIs. The client exposes one sub-client per resource
+(``client.automations`` / ``client.commands`` / ``client.alerts``), and
+``IotResourceProxyViewSet`` turns a host module into a thin BFF. Mirrors
+``ngits-drf-cube-proxy``: applications (a single-tenant app, a multi-tenant
+panel, ...) install this package and wire their tenant-scope resolver via
+``IOT_CLIENT_IDENTITY_RESOLVER`` — the package itself knows nothing about a
+particular application's identity model.
+"""
+
+from iot_client.client import IotEsbClient
+from iot_client.exceptions import IotClientError, IotClientImproperlyConfigured
+from iot_client.identity import resolve_scope
+from iot_client.mixins import IotClientMixin
+from iot_client.proxy import IotResourceProxyViewSet
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "IotEsbClient",
+    "IotClientError",
+    "IotClientImproperlyConfigured",
+    "resolve_scope",
+    "IotClientMixin",
+    "IotResourceProxyViewSet",
+]

ngits_drf_iot_client-0.1.0/iot_client/apps.py

@@ -0,0 +1,12 @@
+"""Optional Django AppConfig.
+
+The client works as a plain library (just reads settings), but it can be added
+to ``INSTALLED_APPS`` for discoverability and future checks/management commands.
+"""
+
+from django.apps import AppConfig
+
+
+class IotClientConfig(AppConfig):
+    name = "iot_client"
+    verbose_name = "NGITS IoT ESB client"

ngits_drf_iot_client-0.1.0/iot_client/client.py

@@ -0,0 +1,87 @@
+"""HTTP transport for the IoT ESB, exposing one sub-client per resource.
+
+Pure transport: no Django request/user awareness (that lives in
+``iot_client.identity`` / ``iot_client.mixins`` / ``iot_client.proxy``), so it is
+trivially unit-testable. Resources are reached as namespaced sub-clients::
+
+    client = IotEsbClient()
+    client.automations.list(tenants=...)
+    client.commands.create(payload)
+    client.alerts.list(tenants=...)
+"""
+
+from functools import cached_property
+from typing import Any, Dict, Optional
+
+import requests
+
+from iot_client.conf import get_setting
+from iot_client.exceptions import IotClientError
+from iot_client.resources import (
+    AlertsResource,
+    AutomationsResource,
+    CommandsResource,
+)
+
+
+class IotEsbClient:
+    """Client for ``{IOT_ESB_BASE_URL}/api/v1`` with per-resource sub-clients."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        token: Optional[str] = None,
+        timeout: Optional[int] = None,
+    ):
+        self.base_url = (base_url or get_setting("IOT_ESB_BASE_URL")).rstrip("/")
+        self.token = token or get_setting("IOT_ESB_TOKEN")
+        self.timeout = timeout or get_setting("IOT_CLIENT_TIMEOUT", 10)
+
+    # -- resource sub-clients ---------------------------------------------
+
+    @cached_property
+    def automations(self) -> AutomationsResource:
+        return AutomationsResource(self)
+
+    @cached_property
+    def commands(self) -> CommandsResource:
+        return CommandsResource(self)
+
+    @cached_property
+    def alerts(self) -> AlertsResource:
+        return AlertsResource(self)
+
+    # -- transport ---------------------------------------------------------
+
+    @property
+    def _headers(self) -> Dict[str, str]:
+        return {"Content-Type": "application/json", "X-Token": str(self.token)}
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/api/v1{path}"
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        try:
+            response = requests.request(
+                method,
+                self._url(path),
+                params=params,
+                json=json,
+                headers=self._headers,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise IotClientError(f"IoT ESB request failed: {exc}") from exc
+
+        if response.status_code >= 400:
+            raise IotClientError(response.text, response.status_code)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()

ngits_drf_iot_client-0.1.0/iot_client/conf.py

@@ -0,0 +1,26 @@
+"""Settings access for the IoT client.
+
+Recognized Django settings:
+- ``IOT_ESB_BASE_URL``  (required) base URL of the IoT ESB, e.g.
+  ``https://iot-esb.example.com``. The client appends ``/api/v1``.
+- ``IOT_ESB_TOKEN``     (required) token sent in the ``X-Token`` header.
+- ``IOT_CLIENT_IDENTITY_RESOLVER`` (optional) dotted path to a callable
+  ``resolver(user) -> tenant scope`` (see ``iot_client.identity``).
+- ``IOT_CLIENT_TIMEOUT`` (optional, default 10) request timeout in seconds.
+"""
+
+from django.conf import settings
+
+from iot_client.exceptions import IotClientImproperlyConfigured
+
+_SENTINEL = object()
+
+
+def get_setting(name: str, default=_SENTINEL):
+    """Return a Django setting, or raise if required and missing."""
+    value = getattr(settings, name, _SENTINEL)
+    if value is _SENTINEL:
+        if default is _SENTINEL:
+            raise IotClientImproperlyConfigured(f"Missing required setting: {name}")
+        return default
+    return value

ngits_drf_iot_client-0.1.0/iot_client/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions raised by the IoT client."""
+
+
+class IotClientError(Exception):
+    """An error returned by (or while reaching) the IoT ESB API."""
+
+    def __init__(self, message: str, status_code: int = 0):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class IotClientImproperlyConfigured(Exception):
+    """A required Django setting for the IoT client is missing."""

ngits_drf_iot_client-0.1.0/iot_client/identity.py

@@ -0,0 +1,25 @@
+"""Tenant-scope resolution.
+
+The package is identity-agnostic: the host application supplies a callable via
+``IOT_CLIENT_IDENTITY_RESOLVER`` (a dotted path) that maps an authenticated user
+to the tenant(s) they may access. The resolver returns:
+
+- ``None``               -> no access (callers should treat as 403),
+- a single ``UUID``/str  -> one tenant (e.g. a single-tenant app),
+- an iterable of ids     -> several tenants (e.g. a multi-tenant panel).
+
+This mirrors ``ngits-drf-cube-proxy``'s ``CUBE_PROXY_IDENTITY_RESOLVER``.
+"""
+
+from django.utils.module_loading import import_string
+
+from iot_client.conf import get_setting
+
+
+def resolve_scope(user):
+    """Resolve the tenant scope for ``user`` using the configured resolver."""
+    dotted_path = get_setting("IOT_CLIENT_IDENTITY_RESOLVER", None)
+    if not dotted_path:
+        return None
+    resolver = import_string(dotted_path)
+    return resolver(user)

ngits_drf_iot_client-0.1.0/iot_client/mixins.py

@@ -0,0 +1,42 @@
+"""DRF helpers for building a thin BFF over the IoT ESB.
+
+Usage in a host application::
+
+    class AutomationViewSet(IotClientMixin, viewsets.ViewSet):
+        def list(self, request):
+            client = self.get_iot_client()
+            return Response(client.list_automations(tenants=self.get_tenant_scope()))
+"""
+
+from typing import List
+
+from rest_framework.exceptions import PermissionDenied
+
+from iot_client.client import IotEsbClient
+from iot_client.identity import resolve_scope
+
+
+class IotClientMixin:
+    """Provides an ESB client and the request user's tenant scope."""
+
+    iot_client_class = IotEsbClient
+
+    def get_iot_client(self) -> IotEsbClient:
+        return self.iot_client_class()
+
+    def get_tenant_scope(self) -> List:
+        """Return the user's tenant scope as a list, or raise 403.
+
+        The host application's resolver (``IOT_CLIENT_IDENTITY_RESOLVER``)
+        decides what each user may see; a single-tenant app returns one id, a
+        multi-tenant panel returns several.
+        """
+        scope = resolve_scope(self.request.user)
+        if scope is None:
+            raise PermissionDenied("No IoT tenant scope for this user.")
+        if isinstance(scope, (list, tuple, set)):
+            scope_list = list(scope)
+            if not scope_list:
+                raise PermissionDenied("Empty IoT tenant scope for this user.")
+            return scope_list
+        return [scope]

ngits_drf_iot_client-0.1.0/iot_client/proxy.py

@@ -0,0 +1,110 @@
+"""Generic DRF proxy viewset over an IoT ESB resource sub-client.
+
+Turns a host-application module into a thin BFF: subclass, set ``resource_name``
+to a sub-client attribute on :class:`~iot_client.client.IotEsbClient` (e.g.
+``"automations"``), and the standard list / retrieve / create / partial_update /
+destroy actions are wired — tenant-scoped, with ESB errors mapped to HTTP. Add
+``@action`` methods for resource-specific extras (e.g. activate, catalog).
+
+Example::
+
+    from rest_framework.decorators import action
+    from rest_framework.response import Response
+    from iot_client import IotResourceProxyViewSet
+
+    class AutomationViewSet(IotResourceProxyViewSet):
+        resource_name = "automations"
+        lookup_value_regex = "[0-9a-f-]{36}"
+
+        @action(detail=True, methods=["post"])
+        def activate(self, request, pk=None):
+            return self.proxy(lambda r: r.activate(pk, tenants=self.get_tenant_scope()))
+"""
+
+from rest_framework import status, viewsets
+from rest_framework.response import Response
+
+from iot_client.exceptions import IotClientError
+from iot_client.mixins import IotClientMixin
+
+
+class IotResourceProxyViewSet(IotClientMixin, viewsets.ViewSet):
+    """Standard CRUD proxy to ``IotEsbClient.<resource_name>``."""
+
+    #: attribute name of the sub-client on IotEsbClient, e.g. "automations".
+    resource_name: str = None
+    #: optional DRF serializers used to validate create / update bodies.
+    create_serializer_class = None
+    update_serializer_class = None
+
+    def get_resource(self):
+        if not self.resource_name:
+            raise NotImplementedError("Set `resource_name` on the viewset.")
+        return getattr(self.get_iot_client(), self.resource_name)
+
+    # -- hooks -------------------------------------------------------------
+
+    def get_list_filters(self) -> dict:
+        """Extra query filters for ``list`` (override per module)."""
+        return {}
+
+    def prepare_create_payload(self, data: dict) -> dict:
+        """Adapt the validated/raw create body before sending (override)."""
+        return dict(data)
+
+    # -- standard actions --------------------------------------------------
+
+    def list(self, request):
+        return self.proxy(
+            lambda r: r.list(tenants=self.get_tenant_scope(), **self.get_list_filters())
+        )
+
+    def retrieve(self, request, pk=None):
+        return self.proxy(lambda r: r.get(pk, tenants=self.get_tenant_scope()))
+
+    def create(self, request):
+        payload = self.prepare_create_payload(
+            self._validate(self.create_serializer_class, request.data)
+        )
+        return self.proxy(lambda r: r.create(payload), success=status.HTTP_201_CREATED)
+
+    def partial_update(self, request, pk=None):
+        payload = self._validate(self.update_serializer_class, request.data)
+        return self.proxy(
+            lambda r: r.update(pk, payload, tenants=self.get_tenant_scope())
+        )
+
+    def destroy(self, request, pk=None):
+        return self.proxy(
+            lambda r: r.delete(pk, tenants=self.get_tenant_scope()),
+            success=status.HTTP_204_NO_CONTENT,
+        )
+
+    # -- helpers -----------------------------------------------------------
+
+    def proxy(self, call, success=status.HTTP_200_OK) -> Response:
+        """Run a sub-client call, mapping ``IotClientError`` to an HTTP error."""
+        try:
+            result = call(self.get_resource())
+        except IotClientError as exc:
+            return self._esb_error(exc)
+        if success == status.HTTP_204_NO_CONTENT:
+            return Response(status=success)
+        return Response(result, status=success)
+
+    @staticmethod
+    def _validate(serializer_class, data) -> dict:
+        if serializer_class is None:
+            return dict(data)
+        serializer = serializer_class(data=data)
+        serializer.is_valid(raise_exception=True)
+        return serializer.validated_data
+
+    @staticmethod
+    def _esb_error(exc: IotClientError) -> Response:
+        code = (
+            status.HTTP_404_NOT_FOUND
+            if exc.status_code == 404
+            else status.HTTP_502_BAD_GATEWAY
+        )
+        return Response({"detail": str(exc)}, status=code)

ngits_drf_iot_client-0.1.0/iot_client/resources/__init__.py

@@ -0,0 +1,13 @@
+"""ESB resource sub-clients."""
+
+from iot_client.resources.alerts import AlertsResource
+from iot_client.resources.automations import AutomationsResource
+from iot_client.resources.base import BaseResource
+from iot_client.resources.commands import CommandsResource
+
+__all__ = [
+    "BaseResource",
+    "AlertsResource",
+    "AutomationsResource",
+    "CommandsResource",
+]

ngits_drf_iot_client-0.1.0/iot_client/resources/alerts.py

@@ -0,0 +1,41 @@
+"""Alert-definition resource sub-client (``/api/v1/alerts/definitions``).
+
+The ESB alert-definitions endpoint scopes list by a single ``tenant`` query
+param, so this resource uses the first tenant of the scope. Cross-tenant
+enumeration (admin "list all") is the host application's responsibility — it owns
+the tenant catalog — so it loops :meth:`list` over the tenant ids it resolves.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from iot_client.resources.base import BaseResource, TenantScope
+
+_BASE = "/alerts/definitions"
+
+
+class AlertsResource(BaseResource):
+    """CRUD for alert definitions."""
+
+    def list(
+        self, tenants: TenantScope = None, meter_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        params: Dict[str, Any] = {}
+        if tenants:
+            params["tenant"] = str(list(tenants)[0])
+        if meter_id:
+            params["meter_id"] = meter_id
+        return self._request("GET", _BASE, params=params)
+
+    def get(self, definition_id, tenants: TenantScope = None) -> Dict[str, Any]:
+        return self._request("GET", f"{_BASE}/{definition_id}")
+
+    def create(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", _BASE, json=payload)
+
+    def update(
+        self, definition_id, payload: Dict[str, Any], tenants: TenantScope = None
+    ) -> Dict[str, Any]:
+        return self._request("PATCH", f"{_BASE}/{definition_id}", json=payload)
+
+    def delete(self, definition_id, tenants: TenantScope = None) -> None:
+        return self._request("DELETE", f"{_BASE}/{definition_id}")

ngits_drf_iot_client-0.1.0/iot_client/resources/automations.py

@@ -0,0 +1,71 @@
+"""Automation resource sub-client (``/api/v1/automations``)."""
+
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from iot_client.resources.base import BaseResource, TenantScope, scope_params
+
+
+class AutomationsResource(BaseResource):
+    """CRUD + lifecycle + wizard catalog for automations."""
+
+    # -- uniform CRUD (consumed by IotResourceProxyViewSet) ----------------
+
+    def list(self, tenants: TenantScope = None, **filters: Any) -> Dict[str, Any]:
+        params = {k: v for k, v in filters.items() if v is not None}
+        params.update(scope_params(tenants))
+        return self._request("GET", "/automations", params=params)
+
+    def get(self, automation_id, tenants: TenantScope = None) -> Dict[str, Any]:
+        return self._request(
+            "GET", f"/automations/{automation_id}", params=scope_params(tenants)
+        )
+
+    def create(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/automations", json=payload)
+
+    def update(
+        self, automation_id, payload: Dict[str, Any], tenants: TenantScope = None
+    ) -> Dict[str, Any]:
+        return self._request(
+            "PATCH",
+            f"/automations/{automation_id}",
+            params=scope_params(tenants),
+            json=payload,
+        )
+
+    def delete(self, automation_id, tenants: TenantScope = None) -> None:
+        return self._request(
+            "DELETE",
+            f"/automations/{automation_id}",
+            params=scope_params(tenants),
+        )
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def activate(self, automation_id, tenants: TenantScope = None) -> Dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/automations/{automation_id}/activate",
+            params=scope_params(tenants),
+        )
+
+    def deactivate(self, automation_id, tenants: TenantScope = None) -> Dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/automations/{automation_id}/deactivate",
+            params=scope_params(tenants),
+        )
+
+    # -- wizard catalog ----------------------------------------------------
+
+    def rule_types(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/automations/catalog/rule-types")
+
+    def actions(
+        self, tenant: UUID, device_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        params: Dict[str, Any] = {"tenant": str(tenant)}
+        if device_id:
+            params["device_id"] = device_id
+        return self._request("GET", "/automations/catalog/actions", params=params)

ngits_drf_iot_client-0.1.0/iot_client/resources/base.py

@@ -0,0 +1,29 @@
+"""Base class and helpers for ESB resource sub-clients.
+
+A resource sub-client groups the operations of one ESB resource (automations,
+commands, alert definitions, ...) and shares the transport of its parent
+:class:`~iot_client.client.IotEsbClient`. Adding a new ESB resource = a new
+``BaseResource`` subclass + a property on the client; nothing else changes.
+"""
+
+from typing import Any, Dict, Optional, Sequence
+from uuid import UUID
+
+TenantScope = Optional[Sequence[UUID]]
+
+
+def scope_params(tenants: TenantScope) -> Dict[str, Any]:
+    """Render a tenant scope as repeatable ``tenants`` query params."""
+    if not tenants:
+        return {}
+    return {"tenants": [str(t) for t in tenants]}
+
+
+class BaseResource:
+    """Holds a reference to the client and delegates HTTP to its transport."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def _request(self, method: str, path: str, **kwargs):
+        return self._client._request(method, path, **kwargs)

ngits_drf_iot_client-0.1.0/iot_client/resources/commands.py

@@ -0,0 +1,15 @@
+"""Command resource sub-client (``/api/v1/iot/commands``)."""
+
+from typing import Any, Dict
+
+from iot_client.resources.base import BaseResource
+
+
+class CommandsResource(BaseResource):
+    """Device command dispatch + status."""
+
+    def create(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/iot/commands", json=payload)
+
+    def get(self, command_id) -> Dict[str, Any]:
+        return self._request("GET", f"/iot/commands/{command_id}")