fix comments

Author: tmunzer-AIDE

CHANGELOG.md

@@ -3,13 +3,13 @@
 
 **Released**: March 15, 2026
 
-This release improves async support with a new `arun()` helper and makes the Device Utilities module fully non-blocking.
+This release improves async support with a new `arun()` helper, makes the Device Utilities module fully non-blocking, adds VT100 terminal emulation for screen-based commands, and introduces interactive SSH shell access for EX/SRX devices. (PR #16)
 
 ---
 
 ### 1. NEW FEATURES
 
-#### **`mistapi.arun()` - Async Helper**
+#### **`mistapi.arun()` — Async Helper**
 New helper function to run any sync mistapi function without blocking the event loop. Wraps the function call in `asyncio.to_thread()` so blocking HTTP requests run in a thread pool.
 
 ```python
@@ -28,6 +28,33 @@ async def main():
 asyncio.run(main())
 ```
 
+#### **Interactive SSH Shell** (`device_utils.ex` / `device_utils.srx`)
+New `interactiveShell()` and `createShellSession()` functions for SSH-over-WebSocket access to EX and SRX devices.
+
+- `interactiveShell()` — takes over the terminal for human SSH access (uses `sshkeyboard`)
+- `createShellSession()` — returns a `ShellSession` object for programmatic send/recv
+- `ShellSession` — bidirectional WebSocket session with `send()`, `recv()`, `resize()`, context manager support
+
+```python
+from mistapi.device_utils import ex
+
+# Interactive (human at the keyboard)
+ex.interactiveShell(apisession, site_id, device_id)
+
+# Programmatic
+with ex.createShellSession(apisession, site_id, device_id) as session:
+    session.send_text("show version\r\n")
+    import time; time.sleep(3)
+    while (data := session.recv(timeout=0.5)):
+        print(data.decode("utf-8", errors="replace"), end="")
+```
+
+#### **`topCommand`** (`device_utils.ex` / `device_utils.srx`)
+New `topCommand()` function to stream `top` output from EX and SRX devices. Uses VT100 screen-buffer rendering for proper in-place display.
+
+#### **VT100 Terminal Emulation**
+Added ANSI escape stripping and a minimal VT100 screen-buffer renderer for device command output. Stream-mode commands (ping, traceroute) have ANSI codes stripped automatically. Screen-mode commands (top, monitor interface) are rendered through a virtual terminal buffer.
+
 ---
 
 ### 2. IMPROVEMENTS
@@ -63,6 +90,32 @@ for msg in response.receive():
 await response
 ```
 
+#### **Binary WebSocket Frame Support**
+`_MistWebsocket._handle_message()` now handles binary frames (strips null bytes, decodes UTF-8 with replacement characters).
+
+#### **Trigger-Only Commands Run Synchronously**
+Fire-and-forget device commands (e.g., `clearMacTable`, `clearBpduError`, `clearHitCount`) that don't require a WebSocket stream now run the API trigger synchronously, ensuring `trigger_api_response` is immediately available on the returned `UtilResponse`.
+
+#### **SRX Function Renames**
+SRX and SSR OSPF/session functions renamed for clarity:
+- `showDatabase` → `retrieveOspfDatabase`
+- `showNeighbors` → `retrieveOspfNeighbors`
+- `showInterfaces` → `retrieveOspfInterfaces`
+- New: `retrieveOspfSummary`, `retrieveSessions`, `clearSessions`
+
+---
+
+### 3. BUG FIXES
+
+- Fixed double-space typo in API token privilege mismatch error message
+- Fixed `first_message_timeout` timer stop to check timer is active before stopping
+
+---
+
+### 4. DEPENDENCIES
+
+- Added `sshkeyboard>=2.3.1` (for `interactiveShell()`)
+
 ---
 
 ## Version 0.61.0 (March 2026)

src/mistapi/__api_request.py

@@ -46,6 +46,8 @@ def _apitoken_sanitizer(apitoken: str) -> str:
     str
         Substring of the API token to be used in the logs
     """
+    if len(apitoken) <= 16:
+        return "***hidden***"
     return f"{apitoken[:4]}...{apitoken[-4:]}"
 
 

src/mistapi/device_utils/__tools/shell.py

@@ -178,9 +178,7 @@ def send(self, data: bytes) -> None:
 
     def send_text(self, text: str) -> None:
         """Send a text string as binary data to the device shell."""
-        data = bytearray()
-        data.extend(map(ord, f"\x00{text}"))
-        self.send(bytes(data))
+        self.send(f"\x00{text}".encode("utf-8"))
 
     def recv(self, timeout: float = 0.1) -> bytes | None:
         """
@@ -316,8 +314,8 @@ def _reader():
                 sys.stdout.buffer.write(data)
                 sys.stdout.buffer.flush()
 
-    def _on_key_release(key: str) -> None:
-        """Handle a key release event from sshkeyboard."""
+    def _on_key_press(key: str) -> None:
+        """Handle a key press event from sshkeyboard."""
         if not session.connected:
             return
         if key == "enter":
@@ -338,17 +336,14 @@ def _on_key_release(key: str) -> None:
             k = "\x7f"
         else:
             k = key
-        data = f"\x00{k}"
-        data_bytes = bytearray()
-        data_bytes.extend(map(ord, data))
-        session.send(bytes(data_bytes))
+        session.send(f"\x00{k}".encode("utf-8"))
 
     reader_thread = threading.Thread(target=_reader, daemon=True)
     reader_thread.start()
 
     try:
         listen_keyboard(
-            on_release=_on_key_release,
+            on_press=_on_key_press,
             delay_second_char=0,
             delay_other_chars=0,
             lower=False,