termix-sdk 0.1.0__tar.gz

termix_sdk-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+/docs/
+node_modules/
+.coverage
+coverage.xml
+htmlcov/

termix_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-19
+
+First release. Generated against Termix `release-2.7.1-tag`.
+
+### Added
+
+- `TermixClient` / `AsyncTermixClient`: connection options (`base_url`,
+  per-service `service_urls` override, `api_key` or `jwt`, timeout,
+  retries), a low-level `request()` escape hatch, and context-manager
+  support.
+- `TermixClient.login()` / `AsyncTermixClient.login()`: username/password
+  login handling Termix's native-app-header requirement for getting a
+  usable JWT back, including the TOTP second-factor flow
+  (`PendingTOTP`/`AsyncPendingTOTP`).
+- A typed exception hierarchy (`TermixError` and subclasses —
+  `AuthenticationError`, `PermissionError`, `NotFoundError`,
+  `RateLimitError` with `remaining_time`, `DataLockedError`,
+  `TOTPRequiredError`, `SessionExpiredError`, `InvalidRequestError`,
+  `ServerError`) mapped from Termix's actual error response shapes.
+- `TermixObject`: dict-backed base model with attribute access,
+  `to_dict()`, and secret redaction in `repr()`/logs.
+- 477 of 491 real Termix endpoints, generated across 43 resource
+  modules (`client.hosts`, `client.credentials`, `client.file_manager`,
+  `client.metrics`, ... — see `tools/sdk-gen/config/resource-map.json`
+  for the full list), each with a sync and an async client.
+- `ssh_session()` / `async_ssh_session()`: connect/keepalive/disconnect
+  lifecycle helper for the SSH-backed session pattern `file_manager` and
+  `docker` share.
+- SSE support (`iter_sse_events`/`aiter_sse_events`, `SSEEvent`) for the
+  3 `text/event-stream` endpoints (tunnel status, Proxmox discovery, AI
+  chat streaming).
+- Real multipart file upload (`fleets.transfer_push`) where a field has
+  no JSON equivalent.
+- `tools/sdk-gen/generate.py`: the OpenAPI-spec-to-Python-client
+  generator, plus `tests/contract/`, one generated test per operation.
+- `py.typed` marker, so mypy/pyright pick up the package's inline types.
+
+### Fixed
+
+- `ssh_session()`/`async_ssh_session()` now type-check when passed a
+  generated service (`client.file_manager`, `client.docker`): the
+  session protocol accepted only `**params: Any` methods, which the
+  generated `Unpack[TypedDict]` signatures don't satisfy.
+
+### Known gaps
+
+- 3 `file_manager` endpoints (`uploadFileStream`, `downloadFileStream`,
+  `uploadFileChunk`) send/receive a raw body the spec has no documented
+  schema for — not generated, to avoid inventing behavior the source
+  doesn't support.
+- 11 endpoints are out of scope by design: internal-auth-only routes,
+  browser-redirect OIDC/opkssh flows, and `POST /users/login` /
+  `POST /users/totp/verify-login` (handled by `TermixClient.login()`
+  instead).
+- No live-instance test suite yet (`tests/` and `tests/contract/` run
+  against a scripted fake transport only) — see CONTRIBUTING.md's
+  testing-philosophy section.

termix_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,155 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/MatheusAlves96/termix-sdk.git
+cd termix-sdk
+uv sync --extra dev      # creates .venv from uv.lock (pinned tool versions)
+```
+
+Without [uv](https://docs.astral.sh/uv/): `python -m venv .venv`, activate
+it, `pip install -e ".[dev]"`. You then get whatever `ruff`/`mypy`/`pytest`
+versions resolve today rather than the locked ones CI uses, so a check may
+pass locally and fail in CI (or the reverse) — the lockfile exists to avoid
+exactly that.
+
+## Running the checks
+
+```bash
+uv run pytest            # tests/ (unit) + tests/contract/ (generated)
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy              # src/ and examples/
+```
+
+## What CI checks
+
+`.github/workflows/ci.yml` runs on every push to `main` and every PR:
+
+| Job | What it does |
+|-----|--------------|
+| `lint` | `ruff check`, `ruff format --check`, `mypy` (Python 3.13) |
+| `test (3.10..3.13)` | `pytest` with coverage; the 3.13 run uploads to Codecov (informational, never blocks) |
+| `generated-sync` | runs `tools/sdk-gen/generate.py` and fails if any committed file changes — hand-edits to `resources/`, `models/`, `types/` or `tests/contract/` are caught here |
+| `spec-gen-typecheck` | `npm ci && npm run typecheck` in `tools/spec-gen` |
+| `build` | `uv build`, `twine check`, installs the wheel into a clean venv, imports it and checks `py.typed` is shipped; uploads `dist/` |
+
+`uv.lock` is enforced (`UV_LOCKED=1`): if you change `pyproject.toml`
+dependencies, run `uv lock` and commit the lockfile, or CI fails at
+`uv sync`.
+
+`.github/workflows/zizmor.yml` lints the workflows themselves for
+security issues (unpinned actions, template injection, leaked
+credentials). Actions are pinned by commit SHA; Dependabot
+(`.github/dependabot.yml`) opens weekly PRs to bump them, plus Python
+and `tools/spec-gen` npm dependencies.
+
+## Releasing
+
+Publishing is driven by a `vX.Y.Z` tag (`.github/workflows/release.yml`)
+and goes to PyPI through Trusted Publishing — no API token lives in the
+repo. The `pypi` GitHub environment requires a manual approval before
+the publish step runs.
+
+1. Bump `__version__` in `src/termix_sdk/_version.py`.
+2. In `CHANGELOG.md`, rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`
+   and add a fresh empty `## [Unreleased]` above it. The release notes on
+   GitHub are that section, verbatim.
+3. Open a PR with those two changes and merge it.
+4. `git tag vX.Y.Z main && git push origin vX.Y.Z`.
+5. The `preflight` job checks the tag matches `__version__` and that the
+   CHANGELOG section exists, then the full CI runs again against the tag.
+6. Approve the `pypi` environment deployment in the Actions UI. The
+   workflow publishes to PyPI and creates the GitHub Release with
+   `dist/` attached.
+
+## How this repo is put together
+
+Three layers, in dependency order:
+
+1. **`tools/spec-gen/`** (TypeScript) — mines the Termix backend source
+   for every route, its auth, its request/response shape, and the
+   Drizzle schema, and emits `spec/termix-openapi.json`. See
+   [its own strategy doc](tools/spec-gen/docs/spec-generation-strategy.md)
+   for why this exists instead of trusting Termix's own `openapi.json`.
+   Not something you normally need to touch or re-run — only when
+   targeting a new Termix release (see below).
+
+2. **`tools/sdk-gen/generate.py`** (Python) — reads `spec/termix-
+   openapi.json` plus the curated `tools/sdk-gen/config/resource-map.json`
+   (which operations exist, what Python method name and module each
+   gets — the spec alone doesn't have good naming) and writes
+   `src/termix_sdk/resources/*.py`, `models/*.py`, `types/*.py`, and
+   `tests/contract/test_*.py`. **Never hand-edit any of those** — the
+   next `python tools/sdk-gen/generate.py` run overwrites them.
+
+3. **Hand-written core** (`src/termix_sdk/_*.py`) — the client,
+   requestor, error hierarchy, object model, session helper, SSE/stream
+   parsing. This is what the generated code in (2) is built on top of,
+   and most of it is adapted from
+   [stripe-python](https://github.com/stripe/stripe-python) (see
+   [NOTICE](NOTICE)) rather than written from scratch.
+
+## Adding or fixing a generated operation
+
+1. Confirm the operation exists in `spec/termix-openapi.json` (search by
+   path). If it's missing entirely, that's a `tools/spec-gen` gap, not
+   an `sdk-gen` one.
+2. Add (or fix) its entry in `tools/sdk-gen/config/resource-map.json`,
+   under the right module. An empty `{}` takes the default name from
+   `generate.py`'s `default_method_name()`; most operations need an
+   explicit `"method"` override — the default rule only really fits
+   plain CRUD on a bare `{id}`.
+3. Run `python tools/sdk-gen/generate.py`. It also runs `ruff format` +
+   `ruff check --fix` on everything it just wrote, and fails loudly (not
+   silently) on:
+   - a method name that collides with another in the same module
+     (`ruff`'s `F811`, at the `ruff check --fix` step)
+   - a method name that's a Python keyword (raised directly)
+   - a `resource-map.json` entry naming an `operationId` the spec
+     doesn't have (raised directly)
+4. Run `uv run pytest`, `uv run mypy`, `uv run ruff check .` — same as CI.
+   Commit the regenerated files: the `generated-sync` CI job regenerates
+   and fails on any diff.
+5. A field typed `Dict[str, Any]`/`List[...]` (or a list of a generated
+   model) is, at runtime, wrapped as a nested `TermixObject`/list of
+   `TermixObject` regardless of that static annotation — compare via
+   `.to_dict()` in any test you hand-write against generated code, not
+   field-by-field attribute equality against a plain dict/list literal.
+
+`tools/sdk-gen/generate.py`'s own module docstring lists the known
+simplifications this makes (every request-body field optional in the
+generated `TypedDict` regardless of the spec's `required` list, no
+per-operation `x-requires-admin`/`x-requires-data-access` docstring
+callouts, etc.) — read it before making a structural change to the
+generator itself.
+
+## Regenerating against a new Termix release
+
+```bash
+cd tools/spec-gen
+npm ci
+npm run generate -- --tag <release-tag>   # or --tag latest
+cd ../..
+python tools/sdk-gen/generate.py
+pytest
+```
+
+Diff the new `spec/termix-openapi.json` against the previous one for new
+or removed operations before touching `resource-map.json` — `sdk-gen`
+only processes what the map lists, so a brand-new endpoint won't appear
+in the SDK until it's added there.
+
+## Testing philosophy
+
+`tests/` (hand-written) and `tests/contract/` (generated, one test per
+operation) both run against a scripted fake transport
+(`tests/http_client_mock.py`) — nothing here talks to a real Termix
+instance. That's a deliberate scope decision, not an oversight: broad
+live-instance coverage would need real SSH hosts, Docker containers, and
+tmux sessions to test against, plus care around endpoints with real
+side effects (`database/export`, `encryption/regenerate-jwt`,
+`delete-account`, fleet actions across real hosts) that shouldn't run
+unattended in CI. If you want to exercise the SDK against a real
+instance, do so manually — there's no `tests/live/` yet.

termix_sdk-0.1.0/LICENSE

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

termix_sdk-0.1.0/NOTICE

@@ -0,0 +1,43 @@
+termix-sdk includes code adapted from stripe-python
+(https://github.com/stripe/stripe-python), used under the MIT License:
+
+  The MIT License
+
+  Copyright (c) 2010-2018 Stripe (http://stripe.com)
+
+  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.
+
+Files adapted from stripe-python (each carries its own header pointing back
+here) as of 2026-09-19, per docs/sdk-plan.md section 5:
+
+  src/termix_sdk/_error.py            <- stripe/_error.py
+  src/termix_sdk/_object.py           <- stripe/_stripe_object.py
+  src/termix_sdk/_response.py         <- stripe/_stripe_response.py
+  src/termix_sdk/_client_options.py   <- stripe/_client_options.py, stripe/_requestor_options.py
+  src/termix_sdk/_request_options.py  <- stripe/_request_options.py
+  src/termix_sdk/_http_client.py      <- stripe/_http_client.py
+  src/termix_sdk/_api_requestor.py    <- stripe/_api_requestor.py
+  src/termix_sdk/_service.py          <- stripe/_stripe_service.py
+  src/termix_sdk/_client.py           <- stripe/_stripe_client.py
+  src/termix_sdk/_async_client.py     <- stripe/_stripe_client.py
+  src/termix_sdk/_util.py             <- stripe/_util.py
+
+None of this implies any endorsement by or affiliation with Stripe. Termix
+is a separate, unrelated project; termix-sdk is an independent, unofficial
+client for it.

termix_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: termix-sdk
+Version: 0.1.0
+Summary: Unofficial Python client SDK for the Termix REST API
+Project-URL: Homepage, https://github.com/MatheusAlves96/termix-sdk
+Project-URL: Issues, https://github.com/MatheusAlves96/termix-sdk/issues
+Project-URL: Changelog, https://github.com/MatheusAlves96/termix-sdk/blob/main/CHANGELOG.md
+Author-email: Matheus Alves <matheusalves965@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: api-client,sdk,ssh,termix
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: typing-extensions>=4.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# termix-sdk
+
+Unofficial Python client SDK for the [Termix](https://github.com/Termix-SSH/Termix) REST API.
+
+Generated from a spec this repo derives directly from the Termix backend
+source, not from Termix's own hand-written `openapi.json` — see
+[Generating our own Termix API spec](tools/spec-gen/docs/spec-generation-strategy.md)
+for why. As of `release-2.7.1-tag`, that covers **477 of 491** real
+endpoints; the rest are either genuinely out of scope (browser-redirect
+OIDC flows, internal-only routes) or need a documented request/response
+shape the spec doesn't have (3 `file_manager` streaming-upload endpoints).
+
+## Install
+
+```bash
+pip install termix-sdk
+```
+
+Requires Python 3.10+. The only runtime dependencies are `httpx` and
+`typing-extensions`.
+
+## Quickstart
+
+An API key (`tmx_...`, created in Termix under Settings → API Keys) is the
+recommended way to authenticate — it skips the login/TOTP dance entirely:
+
+```python
+from termix_sdk import TermixClient
+
+client = TermixClient(base_url="https://termix.example.com", api_key="tmx_...")
+
+for host in client.hosts.list():
+    print(host.name, host.ip)
+
+client.close()
+```
+
+`TermixClient` is also a context manager:
+
+```python
+with TermixClient(base_url="https://termix.example.com", api_key="tmx_...") as client:
+    host = client.hosts.retrieve("42")
+```
+
+### Username/password login
+
+`TermixClient.login()` handles Termix's login quirk for you: the backend
+only puts the JWT in the response body (rather than only in a cookie a
+Python client can't use) when the request looks like it came from a
+native app, so this always sends that header.
+
+```python
+from termix_sdk import TermixClient, PendingTOTP
+
+result = TermixClient.login(
+    base_url="https://termix.example.com",
+    username="alice",
+    password="...",
+)
+
+if isinstance(result, PendingTOTP):
+    # The account has TOTP enabled and this device isn't trusted yet.
+    client = result.verify(input("6-digit code: "))
+else:
+    client = result
+```
+
+### Async
+
+Every resource has an async twin, via a separate client rather than
+`_async` suffixed methods:
+
+```python
+import asyncio
+from termix_sdk import AsyncTermixClient
+
+
+async def main():
+    async with AsyncTermixClient(
+        base_url="https://termix.example.com", api_key="tmx_..."
+    ) as client:
+        hosts = await client.hosts.list()
+        print([h.name for h in hosts])
+
+
+asyncio.run(main())
+```
+
+### SSH-backed sessions (file manager, Docker)
+
+`file_manager` and `docker` open an SSH-backed session server-side
+before you can call anything else on them. `ssh_session()` (and its
+async twin `async_ssh_session()`) manage that lifecycle — connect,
+optional keepalive, disconnect on exit, even on error:
+
+```python
+from termix_sdk import ssh_session
+
+with ssh_session(client.file_manager, host_id=42) as fm:
+    for entry in fm.list_files(path="/"):
+        print(entry)
+# disconnected automatically here
+```
+
+Every method is still callable directly with an explicit `session_id` if
+you'd rather manage the lifecycle yourself — `ssh_session()` is a
+convenience layer on top, not a requirement.
+
+### Errors
+
+Every non-2xx response raises a typed subclass of `TermixError`:
+
+```python
+from termix_sdk import AuthenticationError, NotFoundError, RateLimitError, TermixError
+
+try:
+    client.hosts.retrieve("does-not-exist")
+except NotFoundError as e:
+    print(e.code, e.details)
+except RateLimitError as e:
+    print("retry after", e.remaining_time, "seconds")
+except TermixError as e:
+    print(e.http_status, e)
+```
+
+## What's generated vs. hand-written
+
+`src/termix_sdk/resources/`, `models/`, and `types/` are generated by
+`tools/sdk-gen/generate.py` from `spec/termix-openapi.json` and
+`tools/sdk-gen/config/resource-map.json` — don't hand-edit them, changes
+will be overwritten on the next run. Everything else (`_client.py`,
+`_error.py`, `_object.py`, `_session.py`, `_sse.py`, ...) is hand-written
+core, adapted from [stripe/stripe-python](https://github.com/stripe/stripe-python)
+where noted — see [NOTICE](NOTICE) for the MIT attribution this carries.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how the spec/generator/tests
+fit together and how to regenerate the SDK after a Termix release.
+
+## Documentation
+
+- [Generating our own Termix API spec](tools/spec-gen/docs/spec-generation-strategy.md): why the SDK does not rely on the official `openapi.json`, and how the spec is derived from the Termix backend source (route discovery, auth, typed request bodies, every response per status code, Drizzle schema, test examples).
+- [CHANGELOG.md](CHANGELOG.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE). Portions adapted from stripe-python are
+also MIT; see [NOTICE](NOTICE).

termix_sdk-0.1.0/README.md

@@ -0,0 +1,157 @@
+# termix-sdk
+
+Unofficial Python client SDK for the [Termix](https://github.com/Termix-SSH/Termix) REST API.
+
+Generated from a spec this repo derives directly from the Termix backend
+source, not from Termix's own hand-written `openapi.json` — see
+[Generating our own Termix API spec](tools/spec-gen/docs/spec-generation-strategy.md)
+for why. As of `release-2.7.1-tag`, that covers **477 of 491** real
+endpoints; the rest are either genuinely out of scope (browser-redirect
+OIDC flows, internal-only routes) or need a documented request/response
+shape the spec doesn't have (3 `file_manager` streaming-upload endpoints).
+
+## Install
+
+```bash
+pip install termix-sdk
+```
+
+Requires Python 3.10+. The only runtime dependencies are `httpx` and
+`typing-extensions`.
+
+## Quickstart
+
+An API key (`tmx_...`, created in Termix under Settings → API Keys) is the
+recommended way to authenticate — it skips the login/TOTP dance entirely:
+
+```python
+from termix_sdk import TermixClient
+
+client = TermixClient(base_url="https://termix.example.com", api_key="tmx_...")
+
+for host in client.hosts.list():
+    print(host.name, host.ip)
+
+client.close()
+```
+
+`TermixClient` is also a context manager:
+
+```python
+with TermixClient(base_url="https://termix.example.com", api_key="tmx_...") as client:
+    host = client.hosts.retrieve("42")
+```
+
+### Username/password login
+
+`TermixClient.login()` handles Termix's login quirk for you: the backend
+only puts the JWT in the response body (rather than only in a cookie a
+Python client can't use) when the request looks like it came from a
+native app, so this always sends that header.
+
+```python
+from termix_sdk import TermixClient, PendingTOTP
+
+result = TermixClient.login(
+    base_url="https://termix.example.com",
+    username="alice",
+    password="...",
+)
+
+if isinstance(result, PendingTOTP):
+    # The account has TOTP enabled and this device isn't trusted yet.
+    client = result.verify(input("6-digit code: "))
+else:
+    client = result
+```
+
+### Async
+
+Every resource has an async twin, via a separate client rather than
+`_async` suffixed methods:
+
+```python
+import asyncio
+from termix_sdk import AsyncTermixClient
+
+
+async def main():
+    async with AsyncTermixClient(
+        base_url="https://termix.example.com", api_key="tmx_..."
+    ) as client:
+        hosts = await client.hosts.list()
+        print([h.name for h in hosts])
+
+
+asyncio.run(main())
+```
+
+### SSH-backed sessions (file manager, Docker)
+
+`file_manager` and `docker` open an SSH-backed session server-side
+before you can call anything else on them. `ssh_session()` (and its
+async twin `async_ssh_session()`) manage that lifecycle — connect,
+optional keepalive, disconnect on exit, even on error:
+
+```python
+from termix_sdk import ssh_session
+
+with ssh_session(client.file_manager, host_id=42) as fm:
+    for entry in fm.list_files(path="/"):
+        print(entry)
+# disconnected automatically here
+```
+
+Every method is still callable directly with an explicit `session_id` if
+you'd rather manage the lifecycle yourself — `ssh_session()` is a
+convenience layer on top, not a requirement.
+
+### Errors
+
+Every non-2xx response raises a typed subclass of `TermixError`:
+
+```python
+from termix_sdk import AuthenticationError, NotFoundError, RateLimitError, TermixError
+
+try:
+    client.hosts.retrieve("does-not-exist")
+except NotFoundError as e:
+    print(e.code, e.details)
+except RateLimitError as e:
+    print("retry after", e.remaining_time, "seconds")
+except TermixError as e:
+    print(e.http_status, e)
+```
+
+## What's generated vs. hand-written
+
+`src/termix_sdk/resources/`, `models/`, and `types/` are generated by
+`tools/sdk-gen/generate.py` from `spec/termix-openapi.json` and
+`tools/sdk-gen/config/resource-map.json` — don't hand-edit them, changes
+will be overwritten on the next run. Everything else (`_client.py`,
+`_error.py`, `_object.py`, `_session.py`, `_sse.py`, ...) is hand-written
+core, adapted from [stripe/stripe-python](https://github.com/stripe/stripe-python)
+where noted — see [NOTICE](NOTICE) for the MIT attribution this carries.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how the spec/generator/tests
+fit together and how to regenerate the SDK after a Termix release.
+
+## Documentation
+
+- [Generating our own Termix API spec](tools/spec-gen/docs/spec-generation-strategy.md): why the SDK does not rely on the official `openapi.json`, and how the spec is derived from the Termix backend source (route discovery, auth, typed request bodies, every response per status code, Drizzle schema, test examples).
+- [CHANGELOG.md](CHANGELOG.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE). Portions adapted from stripe-python are
+also MIT; see [NOTICE](NOTICE).

termix_sdk-0.1.0/examples/README.md

@@ -0,0 +1,21 @@
+# Examples
+
+Each script expects a real, reachable Termix instance and reads its
+connection details from environment variables — nothing here talks to a
+mock. Set at least:
+
+```bash
+export TERMIX_BASE_URL="https://termix.example.com"
+export TERMIX_API_KEY="tmx_..."          # sync_quickstart.py, async_quickstart.py, file_manager_session.py
+export TERMIX_USERNAME="alice"           # login_with_totp.py
+export TERMIX_PASSWORD="..."             # login_with_totp.py
+```
+
+| Script | Shows |
+|---|---|
+| [`sync_quickstart.py`](sync_quickstart.py) | `TermixClient`, listing hosts, error handling |
+| [`async_quickstart.py`](async_quickstart.py) | `AsyncTermixClient`, the same thing with `asyncio` |
+| [`login_with_totp.py`](login_with_totp.py) | `TermixClient.login()`, handling `PendingTOTP` |
+| [`file_manager_session.py`](file_manager_session.py) | `ssh_session()` against `client.file_manager` |
+
+Run any of them with `python examples/<script>.py`.