Surface WebSocket errors on UtilResponse (closes #29) (#31)

* feat(device_utils): surface WebSocket errors on UtilResponse (closes #29)

UtilResponse gains ws_error / ws_close_code so a consumer can distinguish a
clean WebSocket completion from an errored, abnormally-closed, or
never-started one (previously the error was only logged and discarded):
- on_error records the first transport error (was a discard-only lambda);
- _on_close records the close code and flags a non-1000 abnormal close;
- start_with_trigger records ws_error when the WS factory returns None or
  raises during setup.

Additive and backward-compatible: ws_error stays None on a clean completion
or a trigger-only command. Adds unit tests for each path.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

* docs(changelog): note ws_error/ws_close_code on UtilResponse (#29)

* chore(release): bump version to 0.63.1

* refactor(device_utils): address Copilot review on ws_error capture

- Guard the WS-factory-None ws_error assignment (first-write-wins, matching
  _on_error / _on_close).
- Neutralize the except-path ws_error message ('trigger/WebSocket setup
  error') since that except also wraps trigger_fn(), not only WS setup.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>

0.63.0

0.62.0 (#27)

* 0.62.0

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

* fix the searchSiteIotEndpoints path

---------

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

refactor Privileges initialization to handle _Privilege instances dir… (

#25)

* refactor Privileges initialization to handle _Privilege instances directly

* 0.61.5

0.61.4 (#22)

* 0.61.4

* fix comments

* Update CHANGELOG.md

Co-authored-by: Copilot <[email protected]>

* Update src/mistapi/__api_session.py

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

0.61.3 (#18)

* Update uv.lock

* Update pyproject.toml

* Update uv.lock

* update sles and ws client

* websocket clietn hardening

* ws client hardening

* ws client hardening

* ws client queue_maxsize hardening

* ws client hardening

* Update __ws_client.py

* Update test_websocket_client.py

* Update __ws_client.py

* Update __ws_client.py

* Update orgs.py

* fix ws dosctrings

* Update CHANGELOG.md

0.61.2 (#17)

* 0.61.2

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

* propagate ws reconnect to other classes

* bug fixes and other improvements

* update tests

* bug fixes

---------

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

fix device_utils (#16)

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**
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
import asyncio
import mistapi
from mistapi.api.v1.sites import devices

async def main():
    session = mistapi.APISession(env_file="~/.mist_env")
    session.login()

    # Run sync API call without blocking the event loop
    response = await mistapi.arun(devices.listSiteDevices, session, site_id)
    print(response.data)

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

#### **Non-Blocking Device Utilities**
All `mistapi.device_utils` functions now return immediately. The HTTP trigger and WebSocket streaming run in background threads, allowing your code to continue executing while data is collected.

**UtilResponse Object:**
| Method/Property | Description |
|-----------------|-------------|
| `.ws_data` | List of processed messages |
| `.done` | `True` if data collection is complete |
| `.wait(timeout)` | Block until complete, returns self |
| `.receive()` | Generator yielding messages as they arrive |
| `.disconnect()` | Stop the WebSocket connection early |
| `await response` | Async-friendly wait (non-blocking event loop) |

**Example Usage:**
```python
from mistapi.device_utils import ex

# Non-blocking - returns immediately, data collected in background
response = ex.ping(apisession, site_id, device_id, host="8.8.8.8")
do_other_work()  # Can do other things while waiting
response.wait()  # Block when ready to collect results
print(response.ws_data)

# Generator style - process messages as they arrive
for msg in response.receive():
    print(msg)

# Async-friendly - doesn't block the event loop
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`.

---

### 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()`)

---

Websocket client (#15)

* adding websocket client

* add ping_interval and ping_timeout params

* add ws.ready() and explicit parameters

* websocket tools added

* refactor: consolidate error handling and improve security

* feat(__api_request): consolidate retry logic into _request_with_retry
  - Extract HTTP operations into inner functions (_do_get, _do_post, etc.)
  - Centralize error handling for all HTTP methods
  - Reduces code duplication by ~55 lines

* security(__api_session): remove SSL verification bypass in Vault client
  - Remove verify=False from hvac.Client initialization
  - Make vault attributes private (_vault_url, _vault_path, etc.)
  - Improve vault credentials cleanup in finally block

* feat(__api_session): improve session management
  - Add _new_session() helper for consistent session initialization
  - Add validate parameter to set_api_token() for optional token validation
  - Fix delete_api_token() to return APIResponse instead of Response
  - Use mist_delete() method instead of raw session.delete()

* perf(__init__): implement lazy loading for heavy subpackages
  - Defer api and cli imports until accessed
  - Improves initial import performance

* fix(__logger): correct logging sanitization
  - Use getMessage() instead of direct msg access
  - Clear record.args after sanitization to prevent re-formatting

This refactoring improves maintainability, security, and performance without
changing the public API surface.

* refactor: improve logging format in APIRequest class

* Refactor API parameter handling and improve documentation

- Updated `searchOrgNacClients` and `searchSiteNacClients` to correct status options from 'session_ended' to 'session_stopped'.
- Rearranged parameters in `searchOrgWanClients`, `searchSiteWanClients`, and `searchSiteWirelessClients` for consistency and clarity.
- Added new parameters `cert_expiry_duration` and `psk_name` to `searchSiteNacClients` and `searchSiteWirelessClients` respectively.
- Removed unused parameters and cleaned up query parameter handling in various search functions.
- Enhanced logging and sanitization in `test_logger.py` to ensure sensitive data is properly redacted.
- Deleted obsolete test file `test.py` to streamline the test suite.
- Improved test readability and structure across multiple test files.

* code scanning fix

0.60.4