nexalware 0.1.0__tar.gz

nexalware-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexalware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexalware-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: nexalware
+Version: 0.1.0
+Summary: Typed client for the Nexalware API - control physical devices and read their telemetry from any Python agent or app.
+Author: Nexalware
+License-Expression: MIT
+Project-URL: Homepage, https://nexalware.com
+Project-URL: Documentation, https://docs.nexalware.com/docs/sdk/sdk-python
+Project-URL: Repository, https://github.com/Darrey1/nexalware-homepage
+Project-URL: Issues, https://github.com/Darrey1/nexalware-homepage/issues
+Keywords: nexalware,iot,device-control,robotics,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nexalware
+
+Typed client for the [Nexalware](https://nexalware.com) API, control physical devices and read their telemetry from any Python agent or app. Zero third-party dependencies, built on `urllib` from the standard library, so dropping it into any existing agent environment can never trigger a version conflict.
+
+Writing in TypeScript instead? See [`@nexalware/sdk`](https://www.npmjs.com/package/@nexalware/sdk) on npm. Want an MCP-aware host to discover these as tools automatically instead of calling them from code? See [`@nexalware/mcp`](https://www.npmjs.com/package/@nexalware/mcp).
+
+## Install
+
+```bash
+pip install nexalware
+```
+
+## Quickstart
+
+```python
+from nexalware import NexalwareClient
+
+client = NexalwareClient(api_key="nxw_live_sk_your_key_here")
+
+client.turn_on("dev_a1b2c3")
+
+latest = client.get_latest_telemetry("dev_a1b2c3")
+print(latest["state"], latest["telemetry"])
+```
+
+Get an API key from the [dashboard](https://nexalware.com) (API Keys), and make sure it has a DeviceGrant covering the device(s) and command(s) you call, an ungranted key authenticates fine but every call is rejected with a 403.
+
+> **Field names match the API's own JSON, not snake_case.** Return values are plain `dict`s (typed as `TypedDict` for editor/type-checker support), with the same field names the REST API itself uses, e.g. `latest["subDeviceId"]`, not `latest["sub_device_id"]`. Method and argument names are proper Python `snake_case`, only the data payloads keep the wire format.
+
+## `NexalwareClient(api_key, base_url=...)`
+
+| Param | Type | Required | Meaning |
+|---|---|---|---|
+| `api_key` | str | yes | A secret key from the dashboard. |
+| `base_url` | str | no | Override for a self-hosted or staging deployment. Defaults to `https://api.nexalware.com`. |
+| `timeout` | float | no | Abort a request after this many seconds. Defaults to `30.0`. |
+
+## Errors
+
+Every method raises `NexalwareApiError` on a non-2xx response, it never returns a "silent" error value.
+
+| Attribute | Type | Meaning |
+|---|---|---|
+| `status` | int | HTTP status code. |
+| `error` | str | Short machine-readable code, e.g. `"FORBIDDEN"`, `"NOT_FOUND"`. |
+| `message` | str \| None | Human-readable reason, same text a dashboard user would see. |
+| `details` | list \| None | Only present on a 400 validation failure. |
+
+```python
+from nexalware import NexalwareApiError
+
+try:
+    client.send_command("dev_a1b2c3", "SET_BRIGHTNESS", params={"level": 60})
+except NexalwareApiError as err:
+    print(err.status, err.error, err.message)
+```
+
+## Methods
+
+- `list_devices(project_id=None)` - the devices this key can actually act on, only what its own DeviceGrant(s) cover. Call this first to discover valid `device_id` values instead of needing them hardcoded or pasted in.
+- `get_commands(device_id)` - the command catalog this device accepts.
+- `send_command(device_id, cmd, params=None, target=None)` - send a command to a device, or, with `target` set, to one specific sub-device behind it.
+- `turn_on(device_id)` / `turn_off(device_id)` - shorthand for `send_command(device_id, "ON" | "OFF")`.
+- `get_telemetry(device_id, metric=None, limit=None, since=None)` - historical telemetry readings, newest first.
+- `get_latest_telemetry(device_id)` - current state snapshot plus the most recent reading per metric.
+- `list_sub_devices(device_id)` / `get_sub_device(device_id, sub_device_id)` - physical devices connected locally behind a master device.
+- `get_sub_device_telemetry(device_id, sub_device_id, metric=None, limit=None, since=None)` - same shape as `get_telemetry`, scoped to one sub-device.
+- `send_sub_device_command(device_id, sub_device_id, cmd, params=None)` - convenience wrapper over `send_command` with `target` already set.
+- `list_schedules(device_id)` / `get_schedule_context(device_id)` - a device's active schedules, and the commands available to schedule.
+- `create_schedule(device_id, slot, on_ts, off_ts, ...)` / `update_schedule(...)` / `delete_schedule(device_id, slot)` - manage a device's schedule slots (0-4).
+- `get_schedule_history(device_id)` - a device's completed or cancelled schedules, most recent first.
+
+Full parameter/return types for every method: **[SDK Reference](https://docs.nexalware.com/docs/sdk/sdk-python)**.
+
+## Links
+
+- [Docs](https://docs.nexalware.com)
+- [Device Orchestration](https://docs.nexalware.com/docs/device-orchestration) - sub-devices, and the contract a master implements to report them.
+- [Authentication & Access](https://docs.nexalware.com/docs/concepts/authentication-and-access) - API keys and DeviceGrants.
+
+## License
+
+MIT

nexalware-0.1.0/README.md

@@ -0,0 +1,83 @@
+# nexalware
+
+Typed client for the [Nexalware](https://nexalware.com) API, control physical devices and read their telemetry from any Python agent or app. Zero third-party dependencies, built on `urllib` from the standard library, so dropping it into any existing agent environment can never trigger a version conflict.
+
+Writing in TypeScript instead? See [`@nexalware/sdk`](https://www.npmjs.com/package/@nexalware/sdk) on npm. Want an MCP-aware host to discover these as tools automatically instead of calling them from code? See [`@nexalware/mcp`](https://www.npmjs.com/package/@nexalware/mcp).
+
+## Install
+
+```bash
+pip install nexalware
+```
+
+## Quickstart
+
+```python
+from nexalware import NexalwareClient
+
+client = NexalwareClient(api_key="nxw_live_sk_your_key_here")
+
+client.turn_on("dev_a1b2c3")
+
+latest = client.get_latest_telemetry("dev_a1b2c3")
+print(latest["state"], latest["telemetry"])
+```
+
+Get an API key from the [dashboard](https://nexalware.com) (API Keys), and make sure it has a DeviceGrant covering the device(s) and command(s) you call, an ungranted key authenticates fine but every call is rejected with a 403.
+
+> **Field names match the API's own JSON, not snake_case.** Return values are plain `dict`s (typed as `TypedDict` for editor/type-checker support), with the same field names the REST API itself uses, e.g. `latest["subDeviceId"]`, not `latest["sub_device_id"]`. Method and argument names are proper Python `snake_case`, only the data payloads keep the wire format.
+
+## `NexalwareClient(api_key, base_url=...)`
+
+| Param | Type | Required | Meaning |
+|---|---|---|---|
+| `api_key` | str | yes | A secret key from the dashboard. |
+| `base_url` | str | no | Override for a self-hosted or staging deployment. Defaults to `https://api.nexalware.com`. |
+| `timeout` | float | no | Abort a request after this many seconds. Defaults to `30.0`. |
+
+## Errors
+
+Every method raises `NexalwareApiError` on a non-2xx response, it never returns a "silent" error value.
+
+| Attribute | Type | Meaning |
+|---|---|---|
+| `status` | int | HTTP status code. |
+| `error` | str | Short machine-readable code, e.g. `"FORBIDDEN"`, `"NOT_FOUND"`. |
+| `message` | str \| None | Human-readable reason, same text a dashboard user would see. |
+| `details` | list \| None | Only present on a 400 validation failure. |
+
+```python
+from nexalware import NexalwareApiError
+
+try:
+    client.send_command("dev_a1b2c3", "SET_BRIGHTNESS", params={"level": 60})
+except NexalwareApiError as err:
+    print(err.status, err.error, err.message)
+```
+
+## Methods
+
+- `list_devices(project_id=None)` - the devices this key can actually act on, only what its own DeviceGrant(s) cover. Call this first to discover valid `device_id` values instead of needing them hardcoded or pasted in.
+- `get_commands(device_id)` - the command catalog this device accepts.
+- `send_command(device_id, cmd, params=None, target=None)` - send a command to a device, or, with `target` set, to one specific sub-device behind it.
+- `turn_on(device_id)` / `turn_off(device_id)` - shorthand for `send_command(device_id, "ON" | "OFF")`.
+- `get_telemetry(device_id, metric=None, limit=None, since=None)` - historical telemetry readings, newest first.
+- `get_latest_telemetry(device_id)` - current state snapshot plus the most recent reading per metric.
+- `list_sub_devices(device_id)` / `get_sub_device(device_id, sub_device_id)` - physical devices connected locally behind a master device.
+- `get_sub_device_telemetry(device_id, sub_device_id, metric=None, limit=None, since=None)` - same shape as `get_telemetry`, scoped to one sub-device.
+- `send_sub_device_command(device_id, sub_device_id, cmd, params=None)` - convenience wrapper over `send_command` with `target` already set.
+- `list_schedules(device_id)` / `get_schedule_context(device_id)` - a device's active schedules, and the commands available to schedule.
+- `create_schedule(device_id, slot, on_ts, off_ts, ...)` / `update_schedule(...)` / `delete_schedule(device_id, slot)` - manage a device's schedule slots (0-4).
+- `get_schedule_history(device_id)` - a device's completed or cancelled schedules, most recent first.
+
+Full parameter/return types for every method: **[SDK Reference](https://docs.nexalware.com/docs/sdk/sdk-python)**.
+
+## Links
+
+- [Docs](https://docs.nexalware.com)
+- [Device Orchestration](https://docs.nexalware.com/docs/device-orchestration) - sub-devices, and the contract a master implements to report them.
+- [Authentication & Access](https://docs.nexalware.com/docs/concepts/authentication-and-access) - API keys and DeviceGrants.
+
+## License
+
+MIT

nexalware-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nexalware"
+version = "0.1.0"
+description = "Typed client for the Nexalware API - control physical devices and read their telemetry from any Python agent or app."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Nexalware" }]
+keywords = ["nexalware", "iot", "device-control", "robotics", "sdk"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Home Automation",
+]
+# Deliberately zero third-party dependencies, built on urllib from the
+# standard library, so dropping this into any existing agent environment
+# can never trigger a dependency conflict.
+dependencies = []
+
+[project.urls]
+Homepage = "https://nexalware.com"
+Documentation = "https://docs.nexalware.com/docs/sdk/sdk-python"
+Repository = "https://github.com/Darrey1/nexalware-homepage"
+Issues = "https://github.com/Darrey1/nexalware-homepage/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nexalware = ["py.typed"]

nexalware-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nexalware-0.1.0/src/nexalware/__init__.py

@@ -0,0 +1,39 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import DEFAULT_BASE_URL, NexalwareClient
+from .errors import NexalwareApiError
+from .types import (
+    Action,
+    CommandDefinition,
+    Device,
+    LatestTelemetry,
+    Schedule,
+    SendCommandResult,
+    SubDevice,
+    SubDeviceCapabilities,
+    TelemetryReading,
+)
+
+__all__ = [
+    "NexalwareClient",
+    "NexalwareApiError",
+    "DEFAULT_BASE_URL",
+    "Action",
+    "CommandDefinition",
+    "Device",
+    "LatestTelemetry",
+    "Schedule",
+    "SendCommandResult",
+    "SubDevice",
+    "SubDeviceCapabilities",
+    "TelemetryReading",
+]
+
+try:
+    # Single source of truth is pyproject.toml's version - read it back at
+    # runtime instead of hand-duplicating it here, so the two can never
+    # drift out of sync.
+    __version__ = version("nexalware")
+except PackageNotFoundError:
+    # Editable/local checkout with no installed distribution metadata yet.
+    __version__ = "0.0.0+unknown"

nexalware-0.1.0/src/nexalware/client.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional, cast
+
+from .errors import NexalwareApiError
+from .types import (
+    Action,
+    CommandDefinition,
+    Device,
+    LatestTelemetry,
+    Schedule,
+    SendCommandResult,
+    SubDevice,
+    TelemetryReading,
+)
+
+DEFAULT_BASE_URL = "https://api.nexalware.com"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+class NexalwareClient:
+    """Thin typed wrapper over the Nexalware "Device Control" API tier, the
+    same endpoints an API key can already call today. Built on ``urllib``
+    from the standard library only, no third-party dependency, so dropping
+    this into any existing agent environment can never trigger a version
+    conflict.
+
+    A key's actual reach is decided entirely by its DeviceGrant(s) on the
+    dashboard, this client never expands or assumes permissions beyond that.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        if not api_key:
+            raise ValueError("NexalwareClient requires an api_key")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self._base_url}/api/v1{path}"
+        if query:
+            filtered = {k: v for k, v in query.items() if v is not None}
+            if filtered:
+                url += "?" + urllib.parse.urlencode(filtered)
+
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        request = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "X-Api-Key": self._api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "nexalware-sdk-python",
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                text = response.read().decode("utf-8")
+                if not text:
+                    return None
+                try:
+                    return json.loads(text)
+                except ValueError:
+                    raise NexalwareApiError(
+                        status=response.status,
+                        error="INVALID_RESPONSE",
+                        message=f"Nexalware API returned a non-JSON response from {path}",
+                    ) from None
+        except urllib.error.HTTPError as err:
+            text = err.read().decode("utf-8")
+            # The API always returns JSON, but a proxy/CDN error page in
+            # front of it (502, WAF block) won't - fail with a clear
+            # NexalwareApiError either way, not an unhandled ValueError.
+            try:
+                payload = json.loads(text) if text else {}
+            except ValueError:
+                payload = {"message": text[:200]} if text else {}
+            raise NexalwareApiError(
+                status=err.code,
+                error=payload.get("error", "UNKNOWN_ERROR"),
+                message=payload.get("message"),
+                details=payload.get("details"),
+            ) from None
+        except socket.timeout:
+            # socket.timeout is TimeoutError itself on 3.10+, but stays a
+            # distinct class pre-3.10 (this package supports 3.9+), so
+            # catch it by its always-correct name rather than TimeoutError.
+            raise TimeoutError(f"Nexalware API request to {path} timed out after {self._timeout}s") from None
+
+    def list_devices(self, project_id: Optional[str] = None) -> List[Device]:
+        """The devices this key can actually act on - only what its own
+        DeviceGrant(s) cover, never the rest of the account. Call this
+        first to discover valid device_id values instead of needing them
+        hardcoded or pasted in from the dashboard.
+        """
+        return cast(List[Device], self._request("GET", "/devices", query={"projectId": project_id}))
+
+    def get_commands(self, device_id: str) -> List[CommandDefinition]:
+        """The command catalog this device accepts."""
+        return cast(List[CommandDefinition], self._request("GET", f"/devices/{device_id}/commands"))
+
+    def send_command(
+        self,
+        device_id: str,
+        cmd: str,
+        params: Optional[Dict[str, Any]] = None,
+        target: Optional[str] = None,
+    ) -> SendCommandResult:
+        """Send a command to a device, or, with ``target`` set, to one
+        specific sub-device behind it (see ``send_sub_device_command`` for
+        the convenience form). Raises ``NexalwareApiError`` (status 403) if
+        the calling key has no DeviceGrant covering this command.
+        """
+        body: Dict[str, Any] = {"cmd": cmd}
+        if params is not None:
+            body["params"] = params
+        if target is not None:
+            body["target"] = target
+        return cast(SendCommandResult, self._request("POST", f"/devices/{device_id}/command", body=body))
+
+    def turn_on(self, device_id: str) -> SendCommandResult:
+        """Shorthand for ``send_command(device_id, "ON")``."""
+        return cast(SendCommandResult, self._request("POST", f"/devices/{device_id}/command/on"))
+
+    def turn_off(self, device_id: str) -> SendCommandResult:
+        """Shorthand for ``send_command(device_id, "OFF")``."""
+        return cast(SendCommandResult, self._request("POST", f"/devices/{device_id}/command/off"))
+
+    def get_telemetry(
+        self,
+        device_id: str,
+        metric: Optional[str] = None,
+        limit: Optional[int] = None,
+        since: Optional[int] = None,
+    ) -> List[TelemetryReading]:
+        """Historical telemetry readings, newest first."""
+        return cast(
+            List[TelemetryReading],
+            self._request(
+                "GET",
+                f"/devices/{device_id}/telemetry",
+                query={"metric": metric, "limit": limit, "since": since},
+            ),
+        )
+
+    def get_latest_telemetry(self, device_id: str) -> LatestTelemetry:
+        """The device's current state plus the most recent reading per metric."""
+        return cast(LatestTelemetry, self._request("GET", f"/devices/{device_id}/telemetry/latest"))
+
+    def list_sub_devices(self, device_id: str) -> List[SubDevice]:
+        """Physical devices connected locally behind this one, acting as an
+        orchestrator ("master"). Empty until the master actually reports one.
+        """
+        return cast(List[SubDevice], self._request("GET", f"/devices/{device_id}/sub-devices"))
+
+    def get_sub_device(self, device_id: str, sub_device_id: str) -> SubDevice:
+        return cast(SubDevice, self._request("GET", f"/devices/{device_id}/sub-devices/{sub_device_id}"))
+
+    def get_sub_device_telemetry(
+        self,
+        device_id: str,
+        sub_device_id: str,
+        metric: Optional[str] = None,
+        limit: Optional[int] = None,
+        since: Optional[int] = None,
+    ) -> List[TelemetryReading]:
+        return cast(
+            List[TelemetryReading],
+            self._request(
+                "GET",
+                f"/devices/{device_id}/sub-devices/{sub_device_id}/telemetry",
+                query={"metric": metric, "limit": limit, "since": since},
+            ),
+        )
+
+    def send_sub_device_command(
+        self,
+        device_id: str,
+        sub_device_id: str,
+        cmd: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> SendCommandResult:
+        """Convenience wrapper over ``send_command`` with ``target`` set to a sub-device."""
+        return self.send_command(device_id, cmd, params, target=sub_device_id)
+
+    def list_schedules(self, device_id: str) -> List[Schedule]:
+        """A device's active (pending or currently running) schedules."""
+        return cast(List[Schedule], self._request("GET", f"/devices/{device_id}/schedules"))
+
+    def get_schedule_context(self, device_id: str) -> Dict[str, List[CommandDefinition]]:
+        """The commands available to schedule, same catalog ``get_commands`` returns."""
+        return cast(
+            Dict[str, List[CommandDefinition]],
+            self._request("GET", f"/devices/{device_id}/schedules/context"),
+        )
+
+    def create_schedule(
+        self,
+        device_id: str,
+        slot: int,
+        on_ts: int,
+        off_ts: int,
+        label: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        on_command: Optional[Action] = None,
+        off_command: Optional[Action] = None,
+    ) -> Schedule:
+        """Create or replace one of a device's schedule slots (0-4), firing
+        ``on_command`` at ``on_ts`` and ``off_command`` at ``off_ts``.
+        ``on_command``/``off_command`` default to plain ON/OFF, any other
+        command still fires reliably from the server at the scheduled time,
+        but only the plain ON/OFF case also syncs to firmware for offline
+        self-execution. Raises ``NexalwareApiError`` (status 403) if the
+        calling key has no permission for either command.
+        """
+        body: Dict[str, Any] = {"slot": slot, "onTs": on_ts, "offTs": off_ts}
+        if label is not None:
+            body["label"] = label
+        if enabled is not None:
+            body["enabled"] = enabled
+        if on_command is not None:
+            body["onCommand"] = on_command
+        if off_command is not None:
+            body["offCommand"] = off_command
+        return cast(Schedule, self._request("POST", f"/devices/{device_id}/schedules", body=body))
+
+    def update_schedule(
+        self,
+        device_id: str,
+        slot: int,
+        on_ts: Optional[int] = None,
+        off_ts: Optional[int] = None,
+        label: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        on_command: Optional[Action] = None,
+        off_command: Optional[Action] = None,
+    ) -> Schedule:
+        """Update an existing schedule slot, only the fields provided are changed."""
+        body: Dict[str, Any] = {}
+        if on_ts is not None:
+            body["onTs"] = on_ts
+        if off_ts is not None:
+            body["offTs"] = off_ts
+        if label is not None:
+            body["label"] = label
+        if enabled is not None:
+            body["enabled"] = enabled
+        if on_command is not None:
+            body["onCommand"] = on_command
+        if off_command is not None:
+            body["offCommand"] = off_command
+        return cast(Schedule, self._request("PUT", f"/devices/{device_id}/schedules/{slot}", body=body))
+
+    def delete_schedule(self, device_id: str, slot: int) -> Dict[str, bool]:
+        """Cancel a schedule slot."""
+        return cast(Dict[str, bool], self._request("DELETE", f"/devices/{device_id}/schedules/{slot}"))
+
+    def get_schedule_history(self, device_id: str) -> List[Schedule]:
+        """A device's completed or cancelled schedules, most recent first."""
+        return cast(List[Schedule], self._request("GET", f"/devices/{device_id}/schedules/history"))

nexalware-0.1.0/src/nexalware/errors.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+
+class NexalwareApiError(Exception):
+    """Raised for any non-2xx response from the Nexalware API. Mirrors the
+    platform's own error envelope (``{ error, message?, details? }``) so
+    callers get the same reason a dashboard user or curl call would see,
+    not a generic HTTP failure.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        error: str,
+        message: Optional[str] = None,
+        details: Optional[List[Any]] = None,
+    ) -> None:
+        self.status = status
+        self.error = error
+        self.message = message
+        self.details = details
+        super().__init__(message or error or f"Nexalware API request failed with status {status}")

nexalware-0.1.0/src/nexalware/types.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+# Field names deliberately match the API's own JSON wire format (camelCase)
+# rather than being renamed to snake_case, so an example or error message
+# from the docs, the REST API, or this SDK all refer to the same field by
+# the same name, nothing to mentally translate between them.
+
+
+class DeviceProject(TypedDict):
+    name: str
+    projectId: str
+
+
+class Device(TypedDict):
+    deviceId: str
+    name: str
+    boardType: str
+    appType: str
+    deviceStatus: Literal["PENDING", "ACTIVE", "DISABLED", "REVOKED"]
+    enabled: bool
+    deviceTypeId: Optional[str]
+    relayState: Optional[bool]
+    isOnline: bool
+    lastSeen: Optional[str]
+    createdAt: str
+    project: Optional[DeviceProject]
+
+
+class CommandDefinition(TypedDict, total=False):
+    commandId: str
+    name: str
+    label: str
+    description: str
+    kind: Literal["ACTION", "QUERY"]
+    paramsSchema: Optional[Dict[str, Any]]
+    shape: Optional[Dict[str, Any]]
+    requiresApproval: bool
+
+
+class SendCommandResult(TypedDict, total=False):
+    ok: Literal[True]
+    approvalRequired: bool
+    approvalId: str
+
+
+class TelemetryReading(TypedDict):
+    id: str
+    deviceId: str
+    accountId: str
+    subDeviceId: Optional[str]
+    metric: str
+    value: Optional[float]
+    valueText: Optional[str]
+    unit: Optional[str]
+    raw: Any
+    recordedAt: str
+
+
+class LatestTelemetry(TypedDict):
+    state: Optional[Dict[str, Any]]
+    relayState: Optional[Literal["ON", "OFF"]]
+    telemetry: List[TelemetryReading]
+
+
+class SubDeviceCapabilities(TypedDict, total=False):
+    commands: List[Dict[str, Any]]
+    telemetry_metrics: List[str]
+    verifiable: bool
+
+
+class SubDevice(TypedDict):
+    subDeviceId: str
+    externalId: str
+    name: str
+    state: Optional[Dict[str, Any]]
+    capabilities: Optional[SubDeviceCapabilities]
+    verifiable: bool
+    enabled: bool
+    isOnline: bool
+    lastSeen: Optional[str]
+    createdAt: str
+
+
+class Action(TypedDict, total=False):
+    command: str
+    params: Dict[str, Any]
+
+
+class Schedule(TypedDict):
+    scheduleId: str
+    deviceId: str
+    slot: int
+    onTs: int
+    offTs: int
+    label: str
+    enabled: bool
+    status: Literal["PENDING", "ACTIVE", "COMPLETED", "CANCELLED"]
+    onCommand: Action
+    offCommand: Action

nexalware-0.1.0/src/nexalware.egg-info/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: nexalware
+Version: 0.1.0
+Summary: Typed client for the Nexalware API - control physical devices and read their telemetry from any Python agent or app.
+Author: Nexalware
+License-Expression: MIT
+Project-URL: Homepage, https://nexalware.com
+Project-URL: Documentation, https://docs.nexalware.com/docs/sdk/sdk-python
+Project-URL: Repository, https://github.com/Darrey1/nexalware-homepage
+Project-URL: Issues, https://github.com/Darrey1/nexalware-homepage/issues
+Keywords: nexalware,iot,device-control,robotics,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nexalware
+
+Typed client for the [Nexalware](https://nexalware.com) API, control physical devices and read their telemetry from any Python agent or app. Zero third-party dependencies, built on `urllib` from the standard library, so dropping it into any existing agent environment can never trigger a version conflict.
+
+Writing in TypeScript instead? See [`@nexalware/sdk`](https://www.npmjs.com/package/@nexalware/sdk) on npm. Want an MCP-aware host to discover these as tools automatically instead of calling them from code? See [`@nexalware/mcp`](https://www.npmjs.com/package/@nexalware/mcp).
+
+## Install
+
+```bash
+pip install nexalware
+```
+
+## Quickstart
+
+```python
+from nexalware import NexalwareClient
+
+client = NexalwareClient(api_key="nxw_live_sk_your_key_here")
+
+client.turn_on("dev_a1b2c3")
+
+latest = client.get_latest_telemetry("dev_a1b2c3")
+print(latest["state"], latest["telemetry"])
+```
+
+Get an API key from the [dashboard](https://nexalware.com) (API Keys), and make sure it has a DeviceGrant covering the device(s) and command(s) you call, an ungranted key authenticates fine but every call is rejected with a 403.
+
+> **Field names match the API's own JSON, not snake_case.** Return values are plain `dict`s (typed as `TypedDict` for editor/type-checker support), with the same field names the REST API itself uses, e.g. `latest["subDeviceId"]`, not `latest["sub_device_id"]`. Method and argument names are proper Python `snake_case`, only the data payloads keep the wire format.
+
+## `NexalwareClient(api_key, base_url=...)`
+
+| Param | Type | Required | Meaning |
+|---|---|---|---|
+| `api_key` | str | yes | A secret key from the dashboard. |
+| `base_url` | str | no | Override for a self-hosted or staging deployment. Defaults to `https://api.nexalware.com`. |
+| `timeout` | float | no | Abort a request after this many seconds. Defaults to `30.0`. |
+
+## Errors
+
+Every method raises `NexalwareApiError` on a non-2xx response, it never returns a "silent" error value.
+
+| Attribute | Type | Meaning |
+|---|---|---|
+| `status` | int | HTTP status code. |
+| `error` | str | Short machine-readable code, e.g. `"FORBIDDEN"`, `"NOT_FOUND"`. |
+| `message` | str \| None | Human-readable reason, same text a dashboard user would see. |
+| `details` | list \| None | Only present on a 400 validation failure. |
+
+```python
+from nexalware import NexalwareApiError
+
+try:
+    client.send_command("dev_a1b2c3", "SET_BRIGHTNESS", params={"level": 60})
+except NexalwareApiError as err:
+    print(err.status, err.error, err.message)
+```
+
+## Methods
+
+- `list_devices(project_id=None)` - the devices this key can actually act on, only what its own DeviceGrant(s) cover. Call this first to discover valid `device_id` values instead of needing them hardcoded or pasted in.
+- `get_commands(device_id)` - the command catalog this device accepts.
+- `send_command(device_id, cmd, params=None, target=None)` - send a command to a device, or, with `target` set, to one specific sub-device behind it.
+- `turn_on(device_id)` / `turn_off(device_id)` - shorthand for `send_command(device_id, "ON" | "OFF")`.
+- `get_telemetry(device_id, metric=None, limit=None, since=None)` - historical telemetry readings, newest first.
+- `get_latest_telemetry(device_id)` - current state snapshot plus the most recent reading per metric.
+- `list_sub_devices(device_id)` / `get_sub_device(device_id, sub_device_id)` - physical devices connected locally behind a master device.
+- `get_sub_device_telemetry(device_id, sub_device_id, metric=None, limit=None, since=None)` - same shape as `get_telemetry`, scoped to one sub-device.
+- `send_sub_device_command(device_id, sub_device_id, cmd, params=None)` - convenience wrapper over `send_command` with `target` already set.
+- `list_schedules(device_id)` / `get_schedule_context(device_id)` - a device's active schedules, and the commands available to schedule.
+- `create_schedule(device_id, slot, on_ts, off_ts, ...)` / `update_schedule(...)` / `delete_schedule(device_id, slot)` - manage a device's schedule slots (0-4).
+- `get_schedule_history(device_id)` - a device's completed or cancelled schedules, most recent first.
+
+Full parameter/return types for every method: **[SDK Reference](https://docs.nexalware.com/docs/sdk/sdk-python)**.
+
+## Links
+
+- [Docs](https://docs.nexalware.com)
+- [Device Orchestration](https://docs.nexalware.com/docs/device-orchestration) - sub-devices, and the contract a master implements to report them.
+- [Authentication & Access](https://docs.nexalware.com/docs/concepts/authentication-and-access) - API keys and DeviceGrants.
+
+## License
+
+MIT

nexalware-0.1.0/src/nexalware.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/nexalware/__init__.py
+src/nexalware/client.py
+src/nexalware/errors.py
+src/nexalware/py.typed
+src/nexalware/types.py
+src/nexalware.egg-info/PKG-INFO
+src/nexalware.egg-info/SOURCES.txt
+src/nexalware.egg-info/dependency_links.txt
+src/nexalware.egg-info/top_level.txt

nexalware-0.1.0/src/nexalware.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nexalware-0.1.0/src/nexalware.egg-info/top_level.txt

@@ -0,0 +1 @@
+nexalware