rtls-sdk 0.2.0__tar.gz

rtls_sdk-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+.env.local
+.env.*.local
+.idea
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.coverage
+htmlcov/

rtls_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,242 @@
+# Changelog
+
+All notable changes to the RTLS SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-05-12
+
+### Added
+
+#### Places CRUD (M9)
+
+- `client.sites.create / update / delete` — full lifecycle for the
+  wire `locations` resource. `update` uses a conservative `name` /
+  `shift` allowlist mirroring the JS reference client; `create`
+  accepts the wider server payload via `**fields`. Server-side
+  cascade on `delete` (areas / floorplans / anchors / zones go too).
+- `client.areas.create / update / delete` — wire `sublocations`
+  resource. `create` requires `name` + `location_uid`; `update`
+  passes arbitrary placement fields (`position_x`, `position_y`,
+  `width`, `height`, `rotation`) through. Server-side cascade.
+- `client.anchors.create / update / delete` — wire `win_anchors`.
+  `create` enforces `name`, `position`, `type` (`ANCHOR` or
+  `BRIDGE`, validated locally); optional `locked`, `acc_config`,
+  `bt_config`, `state`, `device_config` ride in `**fields`.
+- `normalize_mac()` helper — accepts six input shapes (bare 12-hex
+  upper / lower, `:` or `-` separated) and emits the canonical
+  bare-12-hex-lowercase the server's `mac_regex` requires. Wired
+  through `nodes.create / validate / assign_raw / release_raw /
+  release / import_` and `associations.create / bulk_create`.
+- Live fixtures `writable_site_uid` / `writable_area_uid` for
+  destructive live tests against the shared test server, with
+  `sdk-test-<uuid4>` prefixes and `yield`-style cleanup.
+
+#### Floorplans + image lifecycle (M10)
+
+- `client.floorplans.create` — base64-in-JSON image upload. Image
+  is required; pass `image_bytes` + `original_filename` OR
+  `image_path` (either-or, enforced with `ValueError` before any
+  HTTP call).
+- `client.floorplans.update` — diff-driven; replaces the stored
+  image only when `image_bytes` / `image_path` is provided.
+- `client.floorplans.delete` — removes the row and the stored
+  image.
+- `client.floorplans.download_image` — 180-second read timeout
+  (overrides the default 30 s) for multi-MB PDFs; optional
+  `stream_to=<file>` for incremental writes.
+- Server re-encodes PNGs on storage — documented in the entity
+  page; tests compare IHDR dimensions, not byte content.
+
+### Fixed
+
+#### Schema audit (M12)
+
+- **`tags.create` no longer accepts `mac_address`.** The server's
+  Joi `createTrackObject` schema has no `mac_address` field; the
+  default `stripUnknown` silently dropped it, so the call appeared
+  to succeed but the MAC never bound. Callers who want hardware
+  binding now go through `nodes.create` + `associations.create`
+  (the migration guide and `docs/entities/tags.md` document the
+  three-call replacement).
+- **Canonical MAC format is bare 12-hex lowercase.** The server's
+  `mac_regex` rejects any separator; previous SDK responses /
+  examples that showed colon-separated MACs
+  (`AA:BB:CC:DD:EE:FF`) have been corrected across docs and tests.
+  `normalize_mac()` (introduced in M9) is now applied at every MAC
+  entry-point as a precondition, not a convenience.
+- Regression gate: a live MAC round-trip test exercises the
+  create → list → release cycle to prove the wire format stays
+  canonical on both sides.
+
+#### Wire-shape mismatches caught by the M14 full-stack live test
+
+- **`companies.create` now includes a `role` on the seeded admin user**
+  (defaults to `"company_admin"`; override via `admin_role=`). The Joi
+  `companyCreate.user.role` field is required; previously the SDK omitted
+  it and the server responded `"user.role" is required`.
+- **`projects.create` / `projects.update` now wrap the body under
+  `{"project": {...}}`** to match the Joi `createProject` /
+  `updateProject` schemas. The previously-flat body was rejected with
+  `"project" is required`.
+- **`associations.close` now sends `mac_address` / `obj_uid` instead of
+  the association's own `uid`.** The server's close handler reads only
+  those two keys from the body; passing `{"uid": "..."}` raised
+  `"No mac or trackable object uid specified."`. The signature now
+  accepts an `Association` object, an association uid (with an extra
+  `list()` lookup), or explicit `mac_address` / `trackable_uid` kwargs.
+  `compounds/nodes.release` updated to pass the `Association` object
+  directly.
+
+Each of these has a matching unit-test regression in
+`tests/unit/test_resources_write_m3.py`.
+
+### Documentation
+
+- Reorganized user docs around **entities** instead of workflows
+  (M11). Every entity (tags, sites, areas, …) now has a single page
+  covering methods, examples, model fields, and cross-references —
+  answering "what can I do with X?" in one click from the new
+  `docs/entities/` catalog.
+- Deleted `docs/guides/reading-data.md`,
+  `docs/guides/writing-data.md`, `docs/guides/session-context.md` —
+  superseded by entity pages.
+- Trimmed `docs/guides/compound-workflows.md` to a concept page that
+  points at entity pages for examples.
+- Nav restructure: Entities is now the second section after Quickstart;
+  cross-cutting guides (error handling, scope switching, pagination, …)
+  follow.
+- README rewritten to lead with the entity catalog; previous flat
+  link list (which pointed at the now-deleted reading-data /
+  writing-data / session-context guides) replaced with a grouped
+  Start-here / Cross-cutting / Advanced / Reference structure.
+
+## [0.1.0] — initial release
+
+The first release covers the milestones M1–M8 of the original design.
+The SDK provides a sync surface for the RTLS REST API with built-in
+session management, scope handling, and compound workflows that
+collapse multi-call sagas behind a single Python method.
+
+### Added
+
+#### Core client (M1)
+
+- `RtlsClient(username, password, base_url, ...)` — construct from
+  explicit credentials.
+- `RtlsClient(token, base_url, ...)` — bring-your-own token mode.
+- `RtlsClient.from_env()` — construct from `RTLS_USERNAME` /
+  `RTLS_PASSWORD` / `RTLS_BASE_URL` (+ optional scope vars).
+- Lazy login: no network I/O at construction; the first method call
+  performs `POST /auth/log_in.json`.
+- Transparent 401 re-authentication with `threading.Lock`-protected
+  refresh coalescing.
+- Mandatory secret redaction filter for the `rtls_sdk` named logger
+  (no opt-out). Headers and body keys redacted.
+- Typed exception hierarchy under `RtlsError`:
+  `AuthenticationError`, `PermissionDenied`, `NotFound`,
+  `Conflict`, `ValidationError`, `RateLimited`, `ServerError`,
+  `ConnectionError`.
+
+#### Read surface (M2)
+
+- `client.tags.list/get`, `client.sites.list/get`,
+  `client.areas.list/get`, `client.floorplans.list/get`,
+  `client.zones.list/get`, `client.groups.list/get`,
+  `client.users.list/get/me`, `client.nodes.list/get`,
+  `client.anchors.list/get`, `client.alarms.list/get`,
+  `client.events.list/get`, `client.notifications.list/get`,
+  `client.subscribers.list/get`, `client.projects.list/get`,
+  `client.companies.list/get`, `client.reports.list/get`.
+- `client.auth.whoami()`, `client.auth.capabilities()`.
+- `client.system.host/uptime/connections/version/beta_version/ws_host/helper_link/monitor_link`.
+- `client.messaging.*`, `client.logger.*`.
+- Typed pydantic v2 models for every returned resource.
+
+#### Simple writes (M3)
+
+- `create_raw` / `update_raw` / `delete_raw` for all writable
+  resources — 1:1 wrappers over the REST surface.
+- `auth.change_password(old, new)` with token invalidation.
+- `users.create_raw / update_raw / change_password_raw` and
+  related raw flows.
+
+#### Trackable compounds (M4)
+
+- `tags.create(name, ..., attached_zone=..., groups=...)` — POST + zone
+  attach + groups bind with rollback.
+- `tags.update`, `tags.delete` (incl. bulk-list form returning
+  `BulkResult`).
+- `tags.bulk_update(uids, changes)`.
+- `zones.create/update/delete` with dynamic-binding management.
+- `groups.create/update/delete` with membership cleanup.
+- `associations.bulk_create` continue-on-error.
+
+#### User/Node compounds (M5)
+
+- `users.create(email, password, ..., project_role=...)` — user +
+  project-role binding compound.
+- `users.update(uid, ..., project_role=...)` — with project_role diff
+  semantics (add/remove/replace).
+- `nodes.release(node_uid, project_uid=...)` — cross-scope release
+  with association close and per-thread scope override.
+- `system.health()` — aggregated host + uptime + connections snapshot
+  with `partial`/`errors` fan-out tracking.
+
+#### Session context (M6)
+
+- `client.context.load()` — the dashboard bootstrap. Fans out ~20
+  sub-resource reads into one `SessionContext` snapshot with
+  `partial` / `errors` partial-failure semantics.
+- Cross-scope nodes fetch via internal per-thread scope override.
+
+#### Reports + pagination (M7)
+
+- `client.reports.heatmap(...)` — POST + poll until ready, with
+  `ReportFailed` / `ReportTimeout` outcomes.
+- `client.reports.pws(...)` — aggregate PWS event report.
+- `client.reports.zone_activity_csv(...)` — chunked CSV download
+  following `content-next-page`, with optional streaming and
+  duplicate-header dedup.
+- `client.reports.alarms_csv(...)` — alarms CSV with optional
+  multi-line banner prefix.
+- `client.events.iter_pws(...)` — lazy iterator surface for PWS
+  events; three-style paginator infrastructure
+  (`HeaderCursorPaginator`, `BodyUrlPaginator`,
+  `PageLimitPaginator`).
+- New models: `Heatmap`, `HeatmapInput`, `PwsReport`, `PwsEvent`,
+  `CsvBlob`.
+
+#### Polish + release prep (M8)
+
+- `client.with_scope(project_uid=..., company_uid=...)` — returns a
+  copy of the client bound to a different scope, sharing the same
+  authenticated session and connection pool.
+- `client.use_project(uid)` / `client.use_company(uid)` — in-place
+  scope rebind.
+- `RtlsClient(http_client=...)` — caller-supplied `httpx.Client`
+  for proxies, custom TLS, or other transport tuning.
+- Comprehensive `docs/` site built with `mkdocs-material`
+  (guides, advanced topics, API reference auto-generated via
+  `mkdocstrings-python`, migration guide).
+- Security audit test (`tests/security/test_secret_leaks.py`)
+  walking the public surface to verify redaction.
+- `LICENSE` (MIT). `CHANGELOG.md`. CI workflow.
+
+### Compatibility
+
+- Python **3.10**, **3.11**, **3.12**.
+- Wheel ships `py.typed`. Inline type hints work out of the box with
+  `mypy --strict` and `pyright`.
+
+### Migration
+
+Coming from the JS reference client? Read the migration guide
+(`docs/migration/from-js-client.md`) — a code-by-code translation of
+every common JS idiom into the SDK's equivalent.
+
+[0.2.0]: https://github.com/rpplabs/rtls-sdk/releases/tag/v0.2.0
+[0.1.0]: https://github.com/rpplabs/rtls-sdk/releases/tag/v0.1.0

rtls_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RTLS SDK Maintainers
+
+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.

rtls_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: rtls-sdk
+Version: 0.2.0
+Summary: Python SDK for the RTLS REST API
+Project-URL: Homepage, https://github.com/rpplabs/rtls-sdk
+Project-URL: Documentation, https://github.com/rpplabs/rtls-sdk/tree/master/docs
+Project-URL: Issues, https://github.com/rpplabs/rtls-sdk/issues
+Project-URL: Changelog, https://github.com/rpplabs/rtls-sdk/blob/master/CHANGELOG.md
+Author: RTLS SDK Maintainers
+License: MIT
+License-File: LICENSE
+Keywords: iot,rtls,sdk,tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-httpserver>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# RTLS SDK
+
+A Python SDK for the RTLS REST API. Three-step usage:
+
+```python
+from rtls_sdk import RtlsClient
+
+client = RtlsClient.from_env()
+tags = client.tags.list()
+```
+
+That's it — token, refresh, scoping headers, 401 re-login are all
+internal. The first method call performs a lazy login; subsequent
+calls reuse the session.
+
+## What you get
+
+- **Compound workflows.** One Python call replaces the multi-call
+  REST sagas the JS reference client makes you script — e.g.
+  `tags.create(name="X", attached_zone="Z", groups=[...])` runs the
+  three-step create-and-attach with rollback on partial failure.
+- **One exception hierarchy.** Everything under `RtlsError`:
+  `NotFound`, `ValidationError`, `RateLimited`, `ServerError`,
+  `PartialFailureError`, `ReportFailed` / `ReportTimeout`, …
+- **Typed models.** Pydantic v2 under the hood; `mypy --strict` clean
+  out of the box; ships `py.typed`.
+- **Mandatory redaction.** No password, token, refresh-token, cookie,
+  or `Authorization` header ever reaches a log handler. There is no
+  opt-out flag.
+- **Sync-only for v1.** Async surface and WebSocket support are on the
+  v2 roadmap.
+
+## Install
+
+```bash
+pip install rtls-sdk
+```
+
+Python 3.10+ supported. See [`docs/install.md`](docs/install.md) for
+dev install and verification.
+
+## Quickstart
+
+```bash
+export RTLS_USERNAME="qa@example.com"
+export RTLS_PASSWORD="hunter2"
+export RTLS_BASE_URL="https://rtls.example.com"
+```
+
+```python
+from rtls_sdk import RtlsClient
+
+with RtlsClient.from_env() as client:
+    for tag in client.tags.list():
+        print(tag.uid, tag.name)
+```
+
+For the full 5-minute walkthrough see
+[`docs/quickstart.md`](docs/quickstart.md).
+
+## Documentation
+
+The full docs site (`mkdocs build`):
+
+**Start here**
+
+- **[Entity catalog](docs/entities/index.md)** — one page per entity
+  (tags, sites, areas, floorplans, anchors, zones, nodes, users,
+  reports, …) with methods, examples, and model fields. The fastest
+  path to "what can I do with X?".
+- [Install](docs/install.md) · [Quickstart](docs/quickstart.md)
+
+**Cross-cutting guides**
+
+- [Compound workflows](docs/guides/compound-workflows.md) · [Reports](docs/guides/reports.md) · [Floorplans](docs/guides/floorplans.md)
+- [Error handling](docs/guides/error-handling.md) · [Scope switching](docs/guides/scope-switching.md) · [Pagination](docs/guides/pagination.md)
+- [Rate limiting](docs/guides/rate-limiting.md) · [Timestamps](docs/guides/timestamps.md) · [Credential rotation](docs/guides/credential-rotation.md)
+
+**Advanced**
+
+- [BYO token](docs/advanced/byo-token.md) · [Raw REST methods](docs/advanced/raw-rest-methods.md) · [Logging](docs/advanced/logging.md) · [HTTP client override](docs/advanced/http-client-override.md) · [Security](docs/advanced/security.md)
+
+**Reference**
+
+- [Migrating from the JS client](docs/migration/from-js-client.md)
+- API reference — auto-generated from docstrings via mkdocstrings.
+
+Build locally:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Status
+
+v0.2.0 — adds M9 places CRUD (sites / areas / anchors), M10 floorplans
++ image lifecycle, M11 entity-oriented documentation reorganisation,
+and M12 schema-audit fixes (canonical bare-12-hex MACs;
+`tags.create` no longer accepts the silently-stripped `mac_address`
+argument). See [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

rtls_sdk-0.2.0/README.md

@@ -0,0 +1,105 @@
+# RTLS SDK
+
+A Python SDK for the RTLS REST API. Three-step usage:
+
+```python
+from rtls_sdk import RtlsClient
+
+client = RtlsClient.from_env()
+tags = client.tags.list()
+```
+
+That's it — token, refresh, scoping headers, 401 re-login are all
+internal. The first method call performs a lazy login; subsequent
+calls reuse the session.
+
+## What you get
+
+- **Compound workflows.** One Python call replaces the multi-call
+  REST sagas the JS reference client makes you script — e.g.
+  `tags.create(name="X", attached_zone="Z", groups=[...])` runs the
+  three-step create-and-attach with rollback on partial failure.
+- **One exception hierarchy.** Everything under `RtlsError`:
+  `NotFound`, `ValidationError`, `RateLimited`, `ServerError`,
+  `PartialFailureError`, `ReportFailed` / `ReportTimeout`, …
+- **Typed models.** Pydantic v2 under the hood; `mypy --strict` clean
+  out of the box; ships `py.typed`.
+- **Mandatory redaction.** No password, token, refresh-token, cookie,
+  or `Authorization` header ever reaches a log handler. There is no
+  opt-out flag.
+- **Sync-only for v1.** Async surface and WebSocket support are on the
+  v2 roadmap.
+
+## Install
+
+```bash
+pip install rtls-sdk
+```
+
+Python 3.10+ supported. See [`docs/install.md`](docs/install.md) for
+dev install and verification.
+
+## Quickstart
+
+```bash
+export RTLS_USERNAME="qa@example.com"
+export RTLS_PASSWORD="hunter2"
+export RTLS_BASE_URL="https://rtls.example.com"
+```
+
+```python
+from rtls_sdk import RtlsClient
+
+with RtlsClient.from_env() as client:
+    for tag in client.tags.list():
+        print(tag.uid, tag.name)
+```
+
+For the full 5-minute walkthrough see
+[`docs/quickstart.md`](docs/quickstart.md).
+
+## Documentation
+
+The full docs site (`mkdocs build`):
+
+**Start here**
+
+- **[Entity catalog](docs/entities/index.md)** — one page per entity
+  (tags, sites, areas, floorplans, anchors, zones, nodes, users,
+  reports, …) with methods, examples, and model fields. The fastest
+  path to "what can I do with X?".
+- [Install](docs/install.md) · [Quickstart](docs/quickstart.md)
+
+**Cross-cutting guides**
+
+- [Compound workflows](docs/guides/compound-workflows.md) · [Reports](docs/guides/reports.md) · [Floorplans](docs/guides/floorplans.md)
+- [Error handling](docs/guides/error-handling.md) · [Scope switching](docs/guides/scope-switching.md) · [Pagination](docs/guides/pagination.md)
+- [Rate limiting](docs/guides/rate-limiting.md) · [Timestamps](docs/guides/timestamps.md) · [Credential rotation](docs/guides/credential-rotation.md)
+
+**Advanced**
+
+- [BYO token](docs/advanced/byo-token.md) · [Raw REST methods](docs/advanced/raw-rest-methods.md) · [Logging](docs/advanced/logging.md) · [HTTP client override](docs/advanced/http-client-override.md) · [Security](docs/advanced/security.md)
+
+**Reference**
+
+- [Migrating from the JS client](docs/migration/from-js-client.md)
+- API reference — auto-generated from docstrings via mkdocstrings.
+
+Build locally:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Status
+
+v0.2.0 — adds M9 places CRUD (sites / areas / anchors), M10 floorplans
++ image lifecycle, M11 entity-oriented documentation reorganisation,
+and M12 schema-audit fixes (canonical bare-12-hex MACs;
+`tags.create` no longer accepts the silently-stripped `mac_address`
+argument). See [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

rtls_sdk-0.2.0/prompts/README.md

@@ -0,0 +1,126 @@
+# SDK implementation prompts
+
+These prompts implement the design in `/Users/yzhbankov/rtls/rtls-sdk/DESIGN.md`. Run them sequentially. Each milestone leaves the SDK in a working, tested, lint-clean state. After milestone 8 the SDK is feature-complete for v1 and ready to publish.
+
+| # | Prompt | Milestone | Delivers |
+|---|---|---|---|
+| 03 | `03-m1-foundation.md` | M1 | First end-to-end: `RtlsClient.from_env().tags.list()` works against a mocked server. Auth, errors, redaction, packaging, CI scaffolding. |
+| 04 | `04-m2-read-surface.md` | M2 | All `.list()` / `.get()` methods for every resource the JS client reads. All read-side pydantic models. |
+| 05 | `05-m3-simple-writes.md` | M3 | All `.create()` / `.update()` / `.delete()` as thin REST mirrors (also the escape hatches for compound methods). |
+| 06 | `06-m4-trackable-compounds.md` | M4 | Compound workflows: `tags.create(attached_zone=..., groups=...)`, `tags.update`, `tags.delete` cascade, `tags.bulk_update`, dynamic-zone re-binding, `groups.add_tags` / `groups.delete` cascade. `PartialFailureError` wiring. |
+| 07 | `07-m5-user-node-compounds.md` | M5 | Compound user/node workflows: `users.create` / `users.update` with project-role binding, `nodes.release`, `nodes.import_`, `auth.change_password` with re-login. |
+| 08 | `08-m6-context-load.md` | M6 | The `client.context.load()` mega-method — one call hydrates 16+ entities. |
+| 09 | `09-m7-reports.md` | M7 | Reports + pagination: `reports.heatmap` (polling), `reports.pws`, `reports.zone_activity_csv` (chunked), `events.iter_pws` / `events.pages` (three pagination styles unified). |
+| 10 | `10-m8-polish-docs.md` | M8 | Polish, comprehensive docs site (mkdocs-material), API reference, CHANGELOG, release prep. v0.1.0 ships. |
+| 11 | `11-m9-places-crud.md` | M9 | Site / area / anchor full CRUD — closes the v0.1 gap for the `desktop-site_plan` client. MAC normalization, server-cascade contract, new `writable_site_uid` / `writable_area_uid` live fixtures. |
+| 12 | `12-m10-floorplans-images.md` | M10 | Floorplans full CRUD + image upload (base64-in-JSON) + image download (180 s timeout, streaming). Completes the place-entity gap. |
+| 13 | `13-m11-entity-docs.md` | M11 | Docs-only: reorganize user documentation around **entities**. New `docs/entities/` tree (one page per entity + catalog index) replaces the workflow-oriented guides. Answers "what can I do with X?" on one page. |
+| 14 | `14-m12-schema-audit-mac-fix.md` | M12 | Schema-correctness audit. Fix three real bugs caught by reading the server's Joi schemas directly: MAC format is bare 12-hex (not colon-separated); `tags.create` does not accept `mac_address` (server silently strips); add live MAC round-trip test as a regression gate. |
+| 15 | `15-m13-final-audit.md` | M13 | **Check-only.** Full ship-readiness audit across code quality, documentation site, internal consistency, wire-shape correctness, deep doc-quality analysis (with persona-driven proposals), and release artifacts. Produces `AUDIT.md` at the repo root with a verdict (ready / not ready), itemised blockers, repo-wide markdown link validation, and a prioritised list of documentation improvement proposals. Does not modify code or docs — a separate milestone applies any accepted fixes. |
+
+## Inputs each prompt reads
+
+- `/Users/yzhbankov/rtls/rtls-sdk/DESIGN.md` — authoritative design.
+- `/Users/yzhbankov/rtls/rtls-sdk/RESEARCH.md` — endpoint inventory, compound workflows, quirks.
+- `/Users/yzhbankov/rtls/rtls-frontend/client/src/modules/api/` — reference JS client. When docs and client disagree, client wins.
+- `/Users/yzhbankov/rtls/python-libraries/` — prior art for test scaffolding (`pytest-httpserver` handlers).
+
+## Standing constraints (apply to every milestone)
+
+1. **The three-step user mental model is sacred.** No idiomatic user-facing code touches tokens, refresh, or scoping headers. If a snippet in Section 1 of DESIGN.md would have to change to use what you built, you built the wrong thing.
+2. **§8 of RESEARCH.md is binding.** Stack picks (`httpx`, `pydantic`, sync v1, `ruff`, `pytest`), credential UX, lazy login, 401 re-login, in-memory token only, mandatory secret redaction — all decided.
+3. **Type hints everywhere.** `py.typed` marker shipped; `mypy --strict src/` passes (configured to permit `Any` in pydantic field validators only).
+4. **Tests on every new method.** Unit (`respx`) for behaviour, integration (`pytest-httpserver`) for end-to-end call sequences in compounds.
+5. **Docstrings on every public method, class, and module.** Numpy or Google style — pick one in M1 and keep it. Include a minimal usage example in each public method's docstring.
+6. **Lint clean.** `ruff check` and `ruff format --check` both pass. CI fails on warnings.
+7. **No backwards-compat carry-over.** Each milestone builds on the last with no shims, no deprecated-but-kept methods, no migration guides. If something is wrong, fix it cleanly.
+
+## How to run a prompt
+
+Open the prompt file. It assumes Claude is starting fresh with no memory of the previous prompt — but with access to the files the previous prompt left behind. The prompt is self-contained: it tells Claude what to read, what to build, and how to verify.
+
+---
+
+## Live-server validation protocol (applies to every milestone)
+
+A live RTLS test server is available. **Every milestone has a final "Live verification" gate**: the work isn't done until the milestone's behavior has been validated against the real server, not just against mocks. Mocks catch what we anticipated; the live server catches what we didn't.
+
+### One-time credentials onboarding (do this at the start of M1)
+
+The first prompt (M1) does this once. Subsequent prompts reuse what M1 set up. The agent must:
+
+1. **Ask the user for** (via `AskUserQuestion`):
+   - `RTLS_LIVE_BASE_URL` — e.g. `https://rtls.test.example.com`
+   - `RTLS_LIVE_USERNAME` — superuser email
+   - `RTLS_LIVE_PASSWORD` — superuser password
+   - `RTLS_LIVE_PROJECT_UID` — a project uid the test user has access to (optional but used by M2+)
+   - `RTLS_LIVE_COMPANY_UID` — a company uid (optional; needed for company-scope tests in M5–M6)
+
+2. **Write them to `.env.local`** at the repo root in dotenv format. **Do not commit this file.** M1's `.gitignore` must include `.env.local` (and `.env.*.local`) on its first line.
+
+3. **Create `tests/live/conftest.py`** with this shape:
+
+   ```python
+   import os
+   import pytest
+   from dotenv import load_dotenv
+
+   load_dotenv(".env.local")
+
+   def _require(name: str) -> str:
+       val = os.getenv(name)
+       if not val:
+           pytest.skip(f"{name} not set in .env.local — skipping live tests")
+       return val
+
+   @pytest.fixture(scope="session")
+   def live_creds():
+       return {
+           "base_url": _require("RTLS_LIVE_BASE_URL"),
+           "username": _require("RTLS_LIVE_USERNAME"),
+           "password": _require("RTLS_LIVE_PASSWORD"),
+       }
+
+   @pytest.fixture(scope="session")
+   def live_project_uid() -> str:
+       return _require("RTLS_LIVE_PROJECT_UID")
+
+   @pytest.fixture
+   def live_client(live_creds, live_project_uid):
+       from rtls_sdk import RtlsClient
+       with RtlsClient(**live_creds, project_uid=live_project_uid) as client:
+           yield client
+   ```
+
+4. **Register the `live` pytest marker** in `pyproject.toml`:
+
+   ```toml
+   [tool.pytest.ini_options]
+   markers = ["live: tests that hit a real RTLS server (require .env.local)"]
+   ```
+
+   And in each `tests/live/test_*.py` file, mark tests with `pytestmark = pytest.mark.live` at module top.
+
+5. **Add `python-dotenv` to the dev extras** in `pyproject.toml` (no runtime dep).
+
+### Default vs. live test runs
+
+- `pytest` (no marker filter) runs unit + mocked integration tests only. Live tests are auto-skipped if `.env.local` is missing. CI runs this.
+- `pytest -m live` runs the live tests. Agent runs this at the end of every milestone as the final verification gate.
+- `pytest -m "not live"` is the explicit safe form for CI / sandboxes that must never reach the network.
+
+### Cleanup discipline (binding from M3 onward)
+
+Live tests that **create** server-side state MUST clean it up. Use `yield`-style fixtures or `try/finally`. The live server is shared infrastructure, not scratch space.
+
+Naming convention: every test-created resource gets a deterministic `name` or `description` prefix `sdk-test-<uuid4>` so a periodic cleanup script can sweep stale resources if a test crashes hard. Add a `tests/live/_cleanup.py` helper that the M3 prompt sets up.
+
+If a live test fails mid-flight, the cleanup fixture still runs (that's why we use `yield` fixtures, not `setup/teardown` returns). Tests must be idempotent: running them twice on a fresh database produces the same outcome as running them once.
+
+### Credentials in logs
+
+The redaction filter from M1 strips passwords/tokens from logs. Verify this is working with a live test before treating any subsequent live test output as safe to share. **Never paste raw test logs back to the user without re-checking they don't contain credentials.**
+
+### What a milestone's "Live verification" gate covers
+
+The standing rule: **the milestone's primary user-facing happy path must work against the real server, with cleanup.** Each prompt lists the specific live checks for that milestone. The expected pattern is small (3–8 live tests per milestone, each ~10 LoC), focused on shape and integration, not exhaustive coverage — unit tests still own coverage.