jnap 0.1.0__tar.gz

jnap-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

jnap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync
+      - run: uv run pytest
+      - run: uv run ruff check
+      - run: uv run ruff format --check

jnap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

jnap-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

jnap-0.1.0/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

jnap-0.1.0/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+  </profile>
+</component>

jnap-0.1.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

jnap-0.1.0/.idea/jnap.iml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module external.system.id="pyproject.toml" type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/tests" isTestSource="true" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="uv (jnap)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="PLAIN" />
+    <option name="myDocStringFormat" value="Plain" />
+  </component>
+  <component name="TestRunnerService">
+    <option name="PROJECT_TEST_RUNNER" value="py.test" />
+  </component>
+</module>

jnap-0.1.0/.idea/misc.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv (jnap)" />
+  </component>
+  <component name="KubernetesApiPersistence">{}</component>
+  <component name="KubernetesApiProvider"><![CDATA[{
+  "isMigrated": true
+}]]></component>
+</project>

jnap-0.1.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/jnap.iml" filepath="$PROJECT_DIR$/.idea/jnap.iml" />
+    </modules>
+  </component>
+</project>

jnap-0.1.0/.idea/pyLspTools.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="RuffConfiguration">
+    <option name="enabled" value="true" />
+  </component>
+</project>

jnap-0.1.0/.idea/pyProjectModel.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="PyProjectModelSettings">
+    <option name="showConfigurationNotification" value="false" />
+    <option name="usePyprojectToml" value="true" />
+  </component>
+</project>

jnap-0.1.0/.idea/vcs.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="GitSharedSettings">
+    <option name="FORCE_PUSH_PROHIBITED_PATTERNS">
+      <list />
+    </option>
+    <option name="synchronizeBranchProtectionRules" value="false" />
+  </component>
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

jnap-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

jnap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Malčić
+
+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.

jnap-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: jnap
+Version: 0.1.0
+Summary: Async Python client for the Linksys JNAP API
+Project-URL: Repository, https://github.com/jmalcic/jnap
+Project-URL: Bug Tracker, https://github.com/jmalcic/jnap/issues
+Author-email: Justin Malčić <j.malcic@me.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aiohttp,async,home-automation,jnap,linksys,router
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Description-Content-Type: text/markdown
+
+# jnap
+
+Async Python client for the [Linksys JNAP API](http://linksys.com/jnap/).
+
+## Installation
+
+```
+pip install jnap
+```
+
+## Usage
+
+```python
+import asyncio
+import aiohttp
+from jnap import JNAPClient
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = JNAPClient("192.168.1.1", session, password="your-password")
+
+        info = await client.get_device_info()
+        print(info.description, info.serial_number)
+
+        response = await client.get_devices()
+        for device in response.devices:
+            print(device.name, device.mac, device.ip_address)
+
+asyncio.run(main())
+```
+
+## API
+
+### `JNAPClient(host, session, password, *, username="admin")`
+
+The main client class. Accepts an existing `aiohttp.ClientSession` so you can manage connection pooling and lifecycle yourself.
+
+#### Methods
+
+- `await client.get_device_info()` → `GetDeviceInfoResponse`  
+  Returns the router's description and serial number.
+
+- `await client.get_devices()` → `GetDevicesResponse`  
+  Returns all devices currently connected to the router. Only devices with a known MAC address and an active connection are included.
+
+### Models
+
+| Class | Fields |
+|---|---|
+| `GetDeviceInfoResponse` | `description`, `serial_number` |
+| `GetDevicesResponse` | `devices: list[JNAPDevice]` |
+| `JNAPDevice` | `mac`, `name`, `ip_address`, `hostname` |
+
+Device names are resolved in priority order: user-assigned name → friendly name → device ID.
+
+### Exceptions
+
+All exceptions inherit from `JNAPError`.
+
+| Exception | Raised when |
+|---|---|
+| `JNAPUnauthorizedError` | Authentication failed |
+| `JNAPUnknownActionError` | The device does not recognise the action |
+| `JNAPInvalidInputError` | The request was rejected as invalid |
+
+## License
+
+MIT

jnap-0.1.0/README.md

@@ -0,0 +1,68 @@
+# jnap
+
+Async Python client for the [Linksys JNAP API](http://linksys.com/jnap/).
+
+## Installation
+
+```
+pip install jnap
+```
+
+## Usage
+
+```python
+import asyncio
+import aiohttp
+from jnap import JNAPClient
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = JNAPClient("192.168.1.1", session, password="your-password")
+
+        info = await client.get_device_info()
+        print(info.description, info.serial_number)
+
+        response = await client.get_devices()
+        for device in response.devices:
+            print(device.name, device.mac, device.ip_address)
+
+asyncio.run(main())
+```
+
+## API
+
+### `JNAPClient(host, session, password, *, username="admin")`
+
+The main client class. Accepts an existing `aiohttp.ClientSession` so you can manage connection pooling and lifecycle yourself.
+
+#### Methods
+
+- `await client.get_device_info()` → `GetDeviceInfoResponse`  
+  Returns the router's description and serial number.
+
+- `await client.get_devices()` → `GetDevicesResponse`  
+  Returns all devices currently connected to the router. Only devices with a known MAC address and an active connection are included.
+
+### Models
+
+| Class | Fields |
+|---|---|
+| `GetDeviceInfoResponse` | `description`, `serial_number` |
+| `GetDevicesResponse` | `devices: list[JNAPDevice]` |
+| `JNAPDevice` | `mac`, `name`, `ip_address`, `hostname` |
+
+Device names are resolved in priority order: user-assigned name → friendly name → device ID.
+
+### Exceptions
+
+All exceptions inherit from `JNAPError`.
+
+| Exception | Raised when |
+|---|---|
+| `JNAPUnauthorizedError` | Authentication failed |
+| `JNAPUnknownActionError` | The device does not recognise the action |
+| `JNAPInvalidInputError` | The request was rejected as invalid |
+
+## License
+
+MIT

jnap-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "jnap"
+version = "0.1.0"
+description = "Async Python client for the Linksys JNAP API"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Justin Malčić", email = "j.malcic@me.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.9",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+keywords = ["linksys", "jnap", "router", "async", "home-automation", "aiohttp"]
+
+[project.urls]
+Repository = "https://github.com/jmalcic/jnap"
+"Bug Tracker" = "https://github.com/jmalcic/jnap/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "aioresponses>=0.7",
+    "aiohttp>=3.9,<3.14",  # aioresponses 0.7.x is not yet compatible with aiohttp 3.14
+    "ruff>=0.8",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "ANN"]

jnap-0.1.0/src/jnap/__init__.py

@@ -0,0 +1,29 @@
+"""Async Python client for the Linksys JNAP API."""
+
+from .client import JNAPClient
+from .exceptions import (
+    JNAPError,
+    JNAPInvalidInputError,
+    JNAPUnauthorizedError,
+    JNAPUnknownActionError,
+)
+from .models import (
+    GetDeviceInfoResponse,
+    GetDevicesResponse,
+    JNAPAction,
+    JNAPDevice,
+    JNAPRequest,
+)
+
+__all__ = [
+    "GetDeviceInfoResponse",
+    "GetDevicesResponse",
+    "JNAPAction",
+    "JNAPClient",
+    "JNAPDevice",
+    "JNAPError",
+    "JNAPInvalidInputError",
+    "JNAPRequest",
+    "JNAPUnauthorizedError",
+    "JNAPUnknownActionError",
+]

jnap-0.1.0/src/jnap/client.py

@@ -0,0 +1,88 @@
+"""JNAP HTTP client."""
+
+from base64 import b64encode
+from dataclasses import asdict
+
+import aiohttp
+
+from .exceptions import (
+    JNAPError,
+    JNAPInvalidInputError,
+    JNAPUnauthorizedError,
+    JNAPUnknownActionError,
+)
+from .models import GetDeviceInfoResponse, GetDevicesResponse, JNAPAction, JNAPRequest
+
+
+class JNAPClient:
+    """Async client for the Linksys JNAP API."""
+
+    DEFAULT_TIMEOUT = aiohttp.ClientTimeout(total=10)
+    _JNAP_HEADER = "X-JNAP-Action"
+    _JNAP_AUTH_HEADER = "X-JNAP-Authorization"
+    _JNAP_PATH = "/JNAP/"
+    _DEFAULT_USERNAME = "admin"
+    _JNAP_ERRORS: dict[str, type[JNAPError]] = {
+        "_ErrorUnknownAction": JNAPUnknownActionError,
+        "_ErrorUnauthorized": JNAPUnauthorizedError,
+        "_ErrorInvalidInput": JNAPInvalidInputError,
+    }
+
+    def __init__(
+        self,
+        host: str,
+        session: aiohttp.ClientSession,
+        password: str,
+        *,
+        username: str = _DEFAULT_USERNAME,
+    ) -> None:
+        """Initialise the client."""
+        self._url = f"http://{host}{self._JNAP_PATH}"
+        self._session = session
+        credentials = b64encode(f"{username}:{password}".encode()).decode()
+        self._auth_header = f"Basic {credentials}"
+
+    async def get_device_info(self) -> GetDeviceInfoResponse:
+        """Return information about the router."""
+        responses = await self._transaction(
+            [JNAPRequest(action=JNAPAction.GET_DEVICE_INFO)]
+        )
+        try:
+            return GetDeviceInfoResponse.from_dict(responses[0])
+        except (KeyError, IndexError) as err:
+            raise JNAPError("Unexpected response structure") from err
+
+    async def get_devices(self) -> GetDevicesResponse:
+        """Return all devices currently connected to the router."""
+        responses = await self._transaction(
+            [JNAPRequest(action=JNAPAction.GET_DEVICES, request={"sinceRevision": 0})]
+        )
+        try:
+            return GetDevicesResponse.from_dict(responses[0])
+        except (KeyError, IndexError) as err:
+            raise JNAPError("Unexpected response structure") from err
+
+    async def _transaction(self, actions: list[JNAPRequest]) -> list[dict]:
+        """POST a JNAP transaction and return the responses list."""
+        try:
+            async with self._session.post(
+                self._url,
+                headers={
+                    self._JNAP_HEADER: JNAPAction.TRANSACTION,
+                    self._JNAP_AUTH_HEADER: self._auth_header,
+                },
+                json=[asdict(a) for a in actions],
+                timeout=self.DEFAULT_TIMEOUT,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+        except aiohttp.ClientError as err:
+            raise JNAPError("Communication error") from err
+        result = data.get("result")
+        if error_cls := self._JNAP_ERRORS.get(result):
+            raise error_cls
+        if result == "Error":
+            response_result = data.get("responses", [{}])[0].get("result")
+            if error_cls := self._JNAP_ERRORS.get(response_result):
+                raise error_cls
+        return data["responses"]

jnap-0.1.0/src/jnap/exceptions.py

@@ -0,0 +1,17 @@
+"""Exceptions for the JNAP client."""
+
+
+class JNAPError(Exception):
+    """Raised when the JNAP API returns an unexpected response."""
+
+
+class JNAPUnknownActionError(JNAPError):
+    """Raised when the JNAP action is not recognised by the device."""
+
+
+class JNAPUnauthorizedError(JNAPError):
+    """Raised when JNAP authentication fails."""
+
+
+class JNAPInvalidInputError(JNAPError):
+    """Raised when JNAP request input is rejected by the device."""

jnap-0.1.0/src/jnap/models.py

@@ -0,0 +1,93 @@
+"""Data models for the JNAP API."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class JNAPAction(StrEnum):
+    """JNAP action URIs."""
+
+    _JNAP_BASE_URL = "http://linksys.com/jnap/"
+
+    TRANSACTION = f"{_JNAP_BASE_URL}core/Transaction"
+    GET_DEVICE_INFO = f"{_JNAP_BASE_URL}core/GetDeviceInfo"
+    GET_DEVICES = f"{_JNAP_BASE_URL}devicelist/GetDevices"
+
+
+@dataclass
+class JNAPRequest:
+    """A single action within a JNAP transaction."""
+
+    action: JNAPAction
+    request: dict = field(default_factory=dict)
+
+
+@dataclass
+class JNAPDevice:
+    """A device seen by the router."""
+
+    mac: str
+    name: str
+    ip_address: str | None = None
+    hostname: str | None = None
+
+
+@dataclass
+class GetDeviceInfoResponse:
+    """Parsed response from core/GetDeviceInfo."""
+
+    description: str
+    serial_number: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "GetDeviceInfoResponse":
+        """Parse a JNAP response dict."""
+        output = data["output"]
+        return cls(
+            description=output["description"], serial_number=output["serialNumber"]
+        )
+
+
+@dataclass
+class GetDevicesResponse:
+    """Parsed response from devicelist/GetDevices."""
+
+    _KNOWN_MACS = "knownMACAddresses"
+    _CONNECTIONS = "connections"
+    _PROPERTIES = "properties"
+    _FRIENDLY_NAME = "friendlyName"
+    _DEVICE_ID = "deviceID"
+    _USER_DEVICE_NAME = "userDeviceName"
+    _IP_ADDRESS = "ipAddress"
+
+    devices: list[JNAPDevice]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "GetDevicesResponse":
+        """Parse a JNAP response dict."""
+        devices = []
+        for item in data["output"]["devices"]:
+            if not (macs := item.get(cls._KNOWN_MACS)):
+                continue
+            connections = item.get(cls._CONNECTIONS, [])
+            if not connections:
+                continue
+            mac = macs[-1]
+            hostname = item.get(cls._FRIENDLY_NAME)
+            name = (
+                next(
+                    (
+                        p["value"]
+                        for p in item.get(cls._PROPERTIES, [])
+                        if p["name"] == cls._USER_DEVICE_NAME
+                    ),
+                    None,
+                )
+                or hostname
+                or item[cls._DEVICE_ID]
+            )
+            ip_address = connections[0].get(cls._IP_ADDRESS)
+            devices.append(
+                JNAPDevice(mac=mac, name=name, ip_address=ip_address, hostname=hostname)
+            )
+        return cls(devices=devices)