# Changelog

All notable changes to `routeros-py` will be documented here.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [Unreleased]

---

## [1.1.0] — 2026-03-21

### Added

- `routeros.discover_api(client, *, data_dir, force, logger)` — walk the full
  RouterOS API tree and persist the result as a structured JSON schema
- `routeros.load_api_schema(version, *, data_dir)` — load a previously saved
  schema from disk without a live connection
- Both functions exported from the top-level `routeros` namespace and listed
  in `__all__`
- Two discovery strategies, tried in order:
  1. **REST-API `inspect.json`** (preferred) — loads and deep-merges
     `data/mikrotik/rest-api/<version>/inspect.json` with
     `extra/inspect.json` when both are present; covers RouterOS 7.9 – 7.22+
  2. **Binary-API BFS** (fallback) — walks `/console/inspect` with
     comma-separated path components (`ip,address,add`), then queries
     `request=syntax` per command to retrieve parameter names and descriptions
- Partial version matching: `"7.17"` matches `"7.17.1"` subdirectory when an
  exact directory is not found
- `_deep_merge` helper for non-destructive recursive dict merging
- `_count_dir_nodes` helper counting `_type == "dir"` or `"path"` nodes
- 25 unit tests for `discover_api`, `load_api_schema`, `_deep_merge`,
  `_count_dir_nodes`, `_walk_api_binary`, `_try_rest_inspect_json`, and
  `_get_version`; 9 integration tests against a live RouterOS device

### Changed

- **Breaking** — `discover_api` schema format updated:
  - `"endpoints"` key renamed to `"tree"`
  - `tree` is now a **nested inspect.json-compatible tree** instead of a flat
    path-keyed dict; each node carries `_type: "dir" | "cmd" | "arg"` and an
    optional `"desc"` field on arg nodes
  - `endpoint_count` now counts navigable path nodes (`_type` in `"dir"` or
    `"path"`) in the merged tree (was: count of flat endpoint keys)
- `_try_rest_inspect_json` now deep-merges `inspect.json` and
  `extra/inspect.json` (previously returned only the first file found);
  `endpoint_count` for RouterOS 7.20.x rises from 423 → 541
- `_walk_api_binary` now builds a nested tree (was: flat
  `{path: {commands: [...], parameters: [...]}}` dict); each command node
  contains its arg nodes directly, with `desc` omitted when empty

### Removed

- `_parse_inspect_json` internal function (replaced by direct load + merge)
- Flat `parameters` list and `commands` list format from `discover_api` output

---

## [1.0.0] — 2025-03-21

### Added

- Pure-Python RouterOS API client with zero runtime dependencies
- `routeros.dial(address, username, password)` — plain TCP connection factory
- `routeros.dial_tls(address, username, password)` — TLS/SSL connection factory
  with configurable `ssl.SSLContext`
- `Client.run(*words)` / `Client.run_args(words)` — synchronous blocking
  command execution
- `Client.async_start()` — enable concurrent tagged-request mode (background
  reader thread)
- `Client.listen(*words)` / `Client.listen_args(words)` — real-time event
  streaming via `queue.Queue`
- `ListenReply.cancel()` — gracefully cancel a running listener with `/cancel`
- `Sentence.map` — `dict[str, str]` for fast key lookup on every sentence
- `Sentence.pairs` — ordered `List[Pair]` preserving RouterOS key insertion
  order
- Type-casting utilities: `cast()`, `cast_optional()`, `typed_map()`
  - Supported target types: `str`, `int`, `float`, `bool`,
    `datetime.timedelta`, `list`, `bytes`
  - RouterOS duration format: `"1w2d3h4m5s"` → `timedelta`
  - Boolean aliases: `"true"/"yes"` → `True`, `"false"/"no"/"0"/""` → `False`
- Source address / port binding via `source_address=(host, port)` parameter
- Standard `logging` integration (`logging.getLogger("routeros")`) — no
  handlers installed
- Auto-detection of RouterOS auth mode:
  - Post-6.43: single-stage cleartext login
  - Pre-6.43: two-stage MD5 challenge-response login
- `!empty` sentence handling (RouterOS 7.18+)
- Context manager support (`with routeros.dial(...) as c:`)
- `py.typed` marker for PEP 561 full type-checking support
- Example scripts:
  - `routeros.examples.run` — run any RouterOS command and print the reply
  - `routeros.examples.listen` — subscribe to a RouterOS event stream
  - `routeros.examples.tab` — poll `/interface/print` and display a live
    traffic table
  - `routeros.examples.monitor_traffic` — monitor
    `/interface/monitor-traffic` on multiple routers simultaneously using
    threads
- Unit test suite (135 tests) using `socket.socketpair()` mock server — no
  live device required
- Integration test suite (28 tests) against a live RouterOS device via `.env`
  configuration
- Docker RouterOS testing environment (`docker/`)
- Full documentation in `docs/`

[Unreleased]: https://github.com/Butterfly-Student/routeros-py/compare/v1.1.0...HEAD
[1.1.0]: https://github.com/Butterfly-Student/routeros-py/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/Butterfly-Student/routeros-py/releases/tag/v1.0.0
