haaslab 0.1.0__tar.gz

haaslab-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+dist/
+__pycache__/
+.pytest_cache/

haaslab-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## v0.1.0 (2026-10-13)
+
+Initial release of the `haaslab` Python SDK, the first published to PyPI.
+
+### Added
+- `Client` with `jobs` and `tokens` namespaces; `Client()` reads `HAASLAB_TOKEN` and `HAASLAB_BASE_URL` when `token` or `base_url` is not passed
+- `jobs.create(firmware)` — multipart firmware upload
+- `jobs.get(job_id)` — fetch job by ID
+- `jobs.list(limit, page)` — paginated job listing
+- `jobs.serial(job_id)` — full archived serial log
+- `jobs.stream_serial(job_id)` — live SSE serial stream iterator
+- `jobs.wait(job_id, timeout)` — poll until terminal status
+- `tokens.list()` — list PATs (no plaintext)
+- `tokens.create(name)` — create PAT (plaintext shown once)
+- `tokens.revoke(id)` — revoke a PAT
+- `HaasLabError`, `AuthError`, `NotFoundError`, `RateLimitError`, `ServerError` exceptions
+- `Job`, `Token`, `CreatedToken`, `JobList`, `Pagination` dataclasses (synced from /api/v1/openapi.json)

haaslab-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: haaslab
+Version: 0.1.0
+Summary: Python SDK for the haas-lab hardware-as-a-service API
+Project-URL: Homepage, https://haas-lab.com
+Project-URL: Documentation, https://haas-lab.com/docs
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# haaslab Python SDK
+
+Python client for the [haas-lab](https://haas-lab.com) hardware-as-a-service API.
+
+## Install
+
+```bash
+pip install haaslab
+```
+
+Requires Python 3.9+. You need a Personal Access Token: create one at
+https://haas-lab.com/dashboard/tokens after signing in.
+
+## Quickstart
+
+```python
+from haaslab import Client
+
+c = Client(token="pat_xxx")              # or set HAASLAB_TOKEN and call Client()
+job = c.jobs.create("blink.bin")          # multipart upload
+job = c.jobs.wait(job.id, timeout=120)    # poll until terminal
+print(c.jobs.serial(job.id))              # full archived log
+```
+
+## Live streaming
+
+```python
+for line in c.jobs.stream_serial(job.id):
+    print(line)
+```
+
+## Token management
+
+```python
+tok = c.tokens.create("ci-bot")
+print(tok.token)          # plaintext PAT — shown once
+
+c.tokens.list()           # list all tokens
+c.tokens.revoke(tok.id)   # revoke a token
+```
+
+## API Reference
+
+### `Client(token, base_url, timeout)`
+
+| Param | Default | Description |
+|---|---|---|
+| `token` | `$HAASLAB_TOKEN` | Personal Access Token (`pat_xxx`); `ValueError` if neither is set |
+| `base_url` | `$HAASLAB_BASE_URL`, else `https://haas-lab.com` | Base URL of the server |
+| `timeout` | `30.0` | HTTP request timeout in seconds |
+
+### `client.jobs`
+
+| Method | Returns | Description |
+|---|---|---|
+| `create(firmware, name=None, *, profile_key=None, device_id=None, expected_runtime_s=None)` | `Job` | Upload a firmware `.bin` and queue it; `profile_key` asks for any board of that profile, `device_id` for one board, `expected_runtime_s` is the run time you book |
+| `get(job_id)` | `Job` | Fetch job by ID |
+| `list(limit=20, page=1)` | `list[Job]` | List jobs (paginated) |
+| `serial(job_id)` | `str` | Full archived serial log |
+| `stream_serial(job_id)` | `Iterator[str]` | Live SSE serial lines |
+| `wait(job_id, timeout=120)` | `Job` | Poll until COMPLETED/FAILED/CANCELLED |
+
+### `client.tokens`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list()` | `list[Token]` | List PATs (no plaintext) |
+| `create(name)` | `CreatedToken` | Create PAT (plaintext in `.token`, shown once) |
+| `revoke(id)` | `None` | Revoke a PAT |
+
+### Exceptions
+
+| Exception | HTTP status |
+|---|---|
+| `AuthError` | 401 |
+| `NotFoundError` | 404 |
+| `RateLimitError` | 429 |
+| `ServerError` | 5xx |
+| `HaasLabError` | base class / other 4xx |
+
+## Environment variables
+
+`Client()` reads these when `token` or `base_url` is not passed:
+
+```bash
+export HAASLAB_TOKEN=pat_xxx                    # your Personal Access Token
+export HAASLAB_BASE_URL=http://localhost:3000   # optional; defaults to https://haas-lab.com
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```

haaslab-0.1.0/README.md

@@ -0,0 +1,95 @@
+# haaslab Python SDK
+
+Python client for the [haas-lab](https://haas-lab.com) hardware-as-a-service API.
+
+## Install
+
+```bash
+pip install haaslab
+```
+
+Requires Python 3.9+. You need a Personal Access Token: create one at
+https://haas-lab.com/dashboard/tokens after signing in.
+
+## Quickstart
+
+```python
+from haaslab import Client
+
+c = Client(token="pat_xxx")              # or set HAASLAB_TOKEN and call Client()
+job = c.jobs.create("blink.bin")          # multipart upload
+job = c.jobs.wait(job.id, timeout=120)    # poll until terminal
+print(c.jobs.serial(job.id))              # full archived log
+```
+
+## Live streaming
+
+```python
+for line in c.jobs.stream_serial(job.id):
+    print(line)
+```
+
+## Token management
+
+```python
+tok = c.tokens.create("ci-bot")
+print(tok.token)          # plaintext PAT — shown once
+
+c.tokens.list()           # list all tokens
+c.tokens.revoke(tok.id)   # revoke a token
+```
+
+## API Reference
+
+### `Client(token, base_url, timeout)`
+
+| Param | Default | Description |
+|---|---|---|
+| `token` | `$HAASLAB_TOKEN` | Personal Access Token (`pat_xxx`); `ValueError` if neither is set |
+| `base_url` | `$HAASLAB_BASE_URL`, else `https://haas-lab.com` | Base URL of the server |
+| `timeout` | `30.0` | HTTP request timeout in seconds |
+
+### `client.jobs`
+
+| Method | Returns | Description |
+|---|---|---|
+| `create(firmware, name=None, *, profile_key=None, device_id=None, expected_runtime_s=None)` | `Job` | Upload a firmware `.bin` and queue it; `profile_key` asks for any board of that profile, `device_id` for one board, `expected_runtime_s` is the run time you book |
+| `get(job_id)` | `Job` | Fetch job by ID |
+| `list(limit=20, page=1)` | `list[Job]` | List jobs (paginated) |
+| `serial(job_id)` | `str` | Full archived serial log |
+| `stream_serial(job_id)` | `Iterator[str]` | Live SSE serial lines |
+| `wait(job_id, timeout=120)` | `Job` | Poll until COMPLETED/FAILED/CANCELLED |
+
+### `client.tokens`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list()` | `list[Token]` | List PATs (no plaintext) |
+| `create(name)` | `CreatedToken` | Create PAT (plaintext in `.token`, shown once) |
+| `revoke(id)` | `None` | Revoke a PAT |
+
+### Exceptions
+
+| Exception | HTTP status |
+|---|---|
+| `AuthError` | 401 |
+| `NotFoundError` | 404 |
+| `RateLimitError` | 429 |
+| `ServerError` | 5xx |
+| `HaasLabError` | base class / other 4xx |
+
+## Environment variables
+
+`Client()` reads these when `token` or `base_url` is not passed:
+
+```bash
+export HAASLAB_TOKEN=pat_xxx                    # your Personal Access Token
+export HAASLAB_BASE_URL=http://localhost:3000   # optional; defaults to https://haas-lab.com
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```

haaslab-0.1.0/examples/01_quickstart.py

@@ -0,0 +1,26 @@
+"""Quickstart: upload firmware, wait for completion, print serial log."""
+import os
+import sys
+from haaslab import Client
+
+token = os.environ.get("HAASLAB_TOKEN")
+if not token:
+    print("Set HAASLAB_TOKEN environment variable", file=sys.stderr)
+    sys.exit(1)
+
+base_url = os.environ.get("HAASLAB_BASE_URL", "https://haas-lab.com")
+
+c = Client(token=token, base_url=base_url)
+
+firmware_path = sys.argv[1] if len(sys.argv) > 1 else "blink.bin"
+
+job = c.jobs.create(firmware_path)
+print(f"Created job {job.id} (status: {job.status})")
+
+job = c.jobs.wait(job.id, timeout=120)
+print(f"Job finished with status: {job.status}")
+
+if job.status == "COMPLETED":
+    log = c.jobs.serial(job.id)
+    print("--- Serial log ---")
+    print(log)

haaslab-0.1.0/examples/02_stream_serial.py

@@ -0,0 +1,23 @@
+"""Stream live serial output from a running job via SSE."""
+import os
+import sys
+from haaslab import Client
+
+token = os.environ.get("HAASLAB_TOKEN")
+if not token:
+    print("Set HAASLAB_TOKEN environment variable", file=sys.stderr)
+    sys.exit(1)
+
+base_url = os.environ.get("HAASLAB_BASE_URL", "https://haas-lab.com")
+
+if len(sys.argv) < 2:
+    print("Usage: python 02_stream_serial.py <job-id>", file=sys.stderr)
+    sys.exit(1)
+
+job_id = sys.argv[1]
+c = Client(token=token, base_url=base_url)
+
+print(f"Streaming serial output for job {job_id}...")
+for line in c.jobs.stream_serial(job_id):
+    print(line)
+print("Stream ended.")

haaslab-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "haaslab"
+version = "0.1.0"
+description = "Python SDK for the haas-lab hardware-as-a-service API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.27.0",
+    "httpx-sse>=0.4.0",
+]
+
+[project.urls]
+Homepage = "https://haas-lab.com"
+Documentation = "https://haas-lab.com/docs"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-httpx>=0.30.0",
+]
+
+# Only the SDK's own files go into the sdist. Hatchling also always copies the
+# nearest .gitignore into it, which is why this folder has its own: without it,
+# the published sdist carried the repository's root .gitignore (HAAS-388).
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "examples", "README.md", "CHANGELOG.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/haaslab"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

haaslab-0.1.0/src/haaslab/__init__.py

@@ -0,0 +1,19 @@
+from .client import Client
+from .models import Job, Token, CreatedToken, JobList, Pagination
+from .exceptions import HaasLabError, AuthError, NotFoundError, RateLimitError, ServerError
+
+__all__ = [
+    "Client",
+    "Job",
+    "Token",
+    "CreatedToken",
+    "JobList",
+    "Pagination",
+    "HaasLabError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]
+
+__version__ = "0.1.0"

haaslab-0.1.0/src/haaslab/client.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from .jobs import JobsNamespace
+from .tokens import TokensNamespace
+
+DEFAULT_BASE_URL = "https://haas-lab.com"
+_SDK_VERSION = "0.1.0"
+
+
+class Client:
+    """haas-lab API client.
+
+    Usage::
+
+        from haaslab import Client
+        c = Client(token="pat_xxx")
+        job = c.jobs.create("blink.bin")
+        job = c.jobs.wait(job.id)
+        print(job.serial)  # not on Job; call c.jobs.serial(job.id)
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        # The docs page and the README promise these two variables (HAAS-389).
+        token = token or os.environ.get("HAASLAB_TOKEN")
+        if not token:
+            raise ValueError("no token: pass Client(token=...) or set HAASLAB_TOKEN")
+        base_url = base_url or os.environ.get("HAASLAB_BASE_URL") or DEFAULT_BASE_URL
+        api_base = base_url.rstrip("/") + "/api/v1"
+        self._http = httpx.Client(
+            base_url=api_base,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "User-Agent": f"haaslab-python/{_SDK_VERSION}",
+            },
+            timeout=timeout,
+        )
+        self.jobs = JobsNamespace(self._http)
+        self.tokens = TokensNamespace(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

haaslab-0.1.0/src/haaslab/exceptions.py

@@ -0,0 +1,20 @@
+class HaasLabError(Exception):
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(HaasLabError):
+    """401 Unauthorized — invalid or missing PAT."""
+
+
+class NotFoundError(HaasLabError):
+    """404 Not Found."""
+
+
+class RateLimitError(HaasLabError):
+    """429 Too Many Requests."""
+
+
+class ServerError(HaasLabError):
+    """5xx Server Error."""

haaslab-0.1.0/src/haaslab/jobs.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Iterator, Union
+
+import httpx
+
+from .models import Job, JobList, Pagination, TERMINAL_STATUSES
+from .exceptions import HaasLabError
+
+
+class JobsNamespace:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def create(
+        self,
+        firmware: Union[str, Path, bytes],
+        name: str | None = None,
+        *,
+        profile_key: str | None = None,
+        device_id: str | None = None,
+        expected_runtime_s: int | None = None,
+    ) -> Job:
+        """Submit a firmware and book its window.
+
+        ``expected_runtime_s`` is the run time you book; the job's booked window
+        is that plus the profile's flash allowance, and it is what the escrow
+        is reserved against. ``profile_key`` asks for any board of that
+        profile, ``device_id`` for one board in particular; neither means any
+        board that is online. Returns the Job in QUEUED status.
+        """
+        if isinstance(firmware, (str, Path)):
+            path = Path(firmware)
+            data = path.read_bytes()
+            filename = path.name
+        else:
+            data = firmware
+            filename = name or "firmware.bin"
+
+        files = {"firmware": (filename, data, "application/octet-stream")}
+        fields: dict[str, str] = {}
+        if profile_key is not None:
+            fields["profile_key"] = profile_key
+        if device_id is not None:
+            fields["device_id"] = device_id
+        if expected_runtime_s is not None:
+            fields["expected_runtime_s"] = str(expected_runtime_s)
+        resp = self._http.post("/jobs", files=files, data=fields)
+        _raise_for_status(resp)
+        return Job.from_dict(resp.json())
+
+    def get(self, job_id: str) -> Job:
+        resp = self._http.get(f"/jobs/{job_id}")
+        _raise_for_status(resp)
+        return Job.from_dict(resp.json())
+
+    def list(self, limit: int = 20, page: int = 1) -> list[Job]:
+        resp = self._http.get("/jobs", params={"page": page})
+        _raise_for_status(resp)
+        body = resp.json()
+        jobs = [Job.from_dict(j) for j in body["data"]]
+        return jobs[:limit]
+
+    def serial(self, job_id: str) -> str:
+        """Return the full archived serial log as a string."""
+        resp = self._http.get(f"/jobs/{job_id}/serial")
+        _raise_for_status(resp)
+        return resp.text
+
+    def stream_serial(self, job_id: str) -> Iterator[str]:
+        """Yield lines from the live SSE serial stream."""
+        from httpx_sse import connect_sse
+
+        with connect_sse(self._http, "GET", f"/jobs/{job_id}/stream") as event_source:
+            for event in event_source.iter_sse():
+                if event.event == "done":
+                    break
+                if event.data:
+                    yield event.data
+
+    def wait(self, job_id: str, timeout: float = 120, poll_interval: float = 2.0) -> Job:
+        """Poll until the job reaches a terminal status or timeout expires."""
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get(job_id)
+            if job.is_terminal:
+                return job
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise HaasLabError(
+                    f"Job {job_id} did not reach terminal status within {timeout}s "
+                    f"(current status: {job.status})"
+                )
+            time.sleep(min(poll_interval, remaining))
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    from .exceptions import AuthError, NotFoundError, RateLimitError, ServerError
+
+    if resp.status_code < 400:
+        return
+    try:
+        msg = resp.json().get("error", resp.text)
+    except Exception:
+        msg = resp.text
+
+    if resp.status_code == 401:
+        raise AuthError(msg, resp.status_code)
+    if resp.status_code == 404:
+        raise NotFoundError(msg, resp.status_code)
+    if resp.status_code == 429:
+        raise RateLimitError(msg, resp.status_code)
+    if resp.status_code >= 500:
+        raise ServerError(msg, resp.status_code)
+    raise HaasLabError(msg, resp.status_code)

haaslab-0.1.0/src/haaslab/models.py

@@ -0,0 +1,145 @@
+# synced from /api/v1/openapi.json
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+
+# Every status the server can answer with, from the schema's JobStatus enum;
+# the six the API document used to list were a subset, and SETTLED — the
+# state a successful job actually ends in, written by settlement in the same
+# request as completion — was not among them, so `wait` never returned on
+# success (review, 2026-09-05).
+JobStatus = Literal[
+    "DRAFT",
+    "STATIC_CHECK",
+    "STATIC_CHECK_FAILED",
+    "ESTIMATED",
+    "ESCROW_HELD",
+    "QUEUED",
+    "CLAIMED",
+    "FLASHING",
+    "RUNNING",
+    "COMPLETED",
+    "FAILED",
+    "CANCELLED",
+    "DAMAGE_REVIEW",
+    "SETTLED",
+]
+
+# Nothing moves a job out of these. COMPLETED is included because a job that
+# has no escrow to settle stays there; SETTLED is where a settled one ends.
+TERMINAL_STATUSES = {"COMPLETED", "FAILED", "CANCELLED", "SETTLED", "STATIC_CHECK_FAILED"}
+
+
+@dataclass
+class Job:
+    id: str
+    userId: str
+    status: JobStatus
+    firmwareUrl: str
+    firmwareSize: int
+    serialLogUrl: Optional[str]
+    createdAt: str
+    startedAt: Optional[str]
+    completedAt: Optional[str]
+    # One-based place among the jobs waiting for the same boards while the job is
+    # QUEUED; None in every other status, and None from a server older than the
+    # field. Jobs are taken oldest first, so it only falls, except when a job
+    # created earlier is confirmed late or requeued after a board failed it.
+    queuePosition: Optional[int] = None
+    # The booked window (HAAS-20): the board seconds chosen at submit, the
+    # moment the window closes once the job is on a board, and why it ended.
+    # None from a server older than the fields, and for jobs from before them.
+    bookedSeconds: Optional[int] = None
+    expiresAt: Optional[str] = None
+    endedReason: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Job":
+        return cls(
+            id=d["id"],
+            userId=d["userId"],
+            status=d["status"],
+            firmwareUrl=d["firmwareUrl"],
+            firmwareSize=d["firmwareSize"],
+            serialLogUrl=d.get("serialLogUrl"),
+            createdAt=d["createdAt"],
+            startedAt=d.get("startedAt"),
+            completedAt=d.get("completedAt"),
+            queuePosition=d.get("queuePosition"),
+            bookedSeconds=d.get("bookedSeconds"),
+            expiresAt=d.get("expiresAt"),
+            endedReason=d.get("endedReason"),
+        )
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in TERMINAL_STATUSES
+
+    @property
+    def is_queued(self) -> bool:
+        return self.status == "QUEUED"
+
+
+@dataclass
+class Token:
+    id: str
+    name: str
+    createdAt: str
+    lastUsedAt: Optional[str]
+    revokedAt: Optional[str]
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Token":
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            createdAt=d["createdAt"],
+            lastUsedAt=d.get("lastUsedAt"),
+            revokedAt=d.get("revokedAt"),
+        )
+
+
+@dataclass
+class CreatedToken:
+    """Returned once on token creation — includes the plaintext PAT."""
+    id: str
+    name: str
+    createdAt: str
+    lastUsedAt: Optional[str]
+    revokedAt: Optional[str]
+    token: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CreatedToken":
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            createdAt=d["createdAt"],
+            lastUsedAt=d.get("lastUsedAt"),
+            revokedAt=d.get("revokedAt"),
+            token=d["token"],
+        )
+
+
+@dataclass
+class Pagination:
+    page: int
+    pageSize: int
+    total: int
+    totalPages: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Pagination":
+        return cls(
+            page=d["page"],
+            pageSize=d["pageSize"],
+            total=d["total"],
+            totalPages=d["totalPages"],
+        )
+
+
+@dataclass
+class JobList:
+    data: list[Job]
+    meta: Pagination

haaslab-0.1.0/src/haaslab/tokens.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import httpx
+
+from .models import Token, CreatedToken
+from .jobs import _raise_for_status
+
+
+class TokensNamespace:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def list(self) -> list[Token]:
+        resp = self._http.get("/tokens")
+        _raise_for_status(resp)
+        return [Token.from_dict(t) for t in resp.json()]
+
+    def create(self, name: str) -> CreatedToken:
+        """Create a new PAT. The plaintext token is returned once in CreatedToken.token."""
+        resp = self._http.post("/tokens", json={"name": name})
+        _raise_for_status(resp)
+        return CreatedToken.from_dict(resp.json())
+
+    def revoke(self, token_id: str) -> None:
+        resp = self._http.delete(f"/tokens/{token_id}")
+        _raise_for_status(resp)

haaslab-0.1.0/tests/test_client.py

@@ -0,0 +1,228 @@
+"""Tests for haaslab SDK using httpx mock transport."""
+import pytest
+import httpx
+from haaslab import Client, Job, Token, CreatedToken
+from haaslab.exceptions import AuthError, NotFoundError, ServerError, HaasLabError
+
+# Fixtures for canonical API shapes (synced from /api/v1/openapi.json)
+JOB_QUEUED = {
+    "id": "job_abc123",
+    "userId": "user_1",
+    "status": "QUEUED",
+    "firmwareUrl": "jobs/job_abc123/firmware.bin",
+    "firmwareSize": 42000,
+    "serialLogUrl": None,
+    "createdAt": "2024-01-01T00:00:00Z",
+    "startedAt": None,
+    "completedAt": None,
+}
+
+JOB_COMPLETED = {**JOB_QUEUED, "status": "COMPLETED", "serialLogUrl": "jobs/job_abc123/serial.log", "completedAt": "2024-01-01T00:01:00Z"}
+
+TOKEN = {
+    "id": "tok_1",
+    "name": "my-token",
+    "createdAt": "2024-01-01T00:00:00Z",
+    "lastUsedAt": None,
+    "revokedAt": None,
+}
+
+CREATED_TOKEN = {**TOKEN, "token": "pat_deadbeef" * 2}
+
+
+def make_client(handler) -> Client:
+    transport = httpx.MockTransport(handler)
+    c = Client.__new__(Client)
+    c._http = httpx.Client(
+        base_url="http://localhost:3000/api/v1",
+        headers={"Authorization": "Bearer pat_test"},
+        transport=transport,
+    )
+    from haaslab.jobs import JobsNamespace
+    from haaslab.tokens import TokensNamespace
+    c.jobs = JobsNamespace(c._http)
+    c.tokens = TokensNamespace(c._http)
+    return c
+
+
+# ── jobs.create ──────────────────────────────────────────────────────────────
+
+def test_jobs_create_multipart():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert "/jobs" in str(request.url)
+        assert "multipart/form-data" in request.headers.get("content-type", "")
+        return httpx.Response(201, json=JOB_QUEUED)
+
+    c = make_client(handler)
+    job = c.jobs.create(b"\x00\x01\x02", name="blink.bin")
+    assert isinstance(job, Job)
+    assert job.id == "job_abc123"
+    assert job.status == "QUEUED"
+
+
+# ── jobs.get ─────────────────────────────────────────────────────────────────
+
+def test_jobs_get():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert "/jobs/job_abc123" in str(request.url)
+        return httpx.Response(200, json=JOB_QUEUED)
+
+    c = make_client(handler)
+    job = c.jobs.get("job_abc123")
+    assert job.id == "job_abc123"
+
+
+def test_jobs_get_not_found():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"error": "not found"})
+
+    c = make_client(handler)
+    with pytest.raises(NotFoundError):
+        c.jobs.get("missing")
+
+
+# ── jobs.list ─────────────────────────────────────────────────────────────────
+
+def test_jobs_list():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert "page=1" in str(request.url)
+        return httpx.Response(200, json={
+            "data": [JOB_QUEUED],
+            "meta": {"page": 1, "pageSize": 20, "total": 1, "totalPages": 1},
+        })
+
+    c = make_client(handler)
+    jobs = c.jobs.list()
+    assert len(jobs) == 1
+    assert jobs[0].status == "QUEUED"
+
+
+# ── jobs.serial ───────────────────────────────────────────────────────────────
+
+def test_jobs_serial():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert "/jobs/job_abc123/serial" in str(request.url)
+        return httpx.Response(200, text="Hello World\nDone\n", headers={"content-type": "text/plain"})
+
+    c = make_client(handler)
+    log = c.jobs.serial("job_abc123")
+    assert "Hello World" in log
+
+
+# ── jobs.wait ─────────────────────────────────────────────────────────────────
+
+def test_jobs_wait_already_terminal():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=JOB_COMPLETED)
+
+    c = make_client(handler)
+    job = c.jobs.wait("job_abc123", timeout=10)
+    assert job.status == "COMPLETED"
+    assert job.is_terminal
+
+
+def test_jobs_wait_timeout():
+    call_count = 0
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal call_count
+        call_count += 1
+        return httpx.Response(200, json=JOB_QUEUED)  # always QUEUED
+
+    c = make_client(handler)
+    with pytest.raises(HaasLabError, match="did not reach terminal"):
+        c.jobs.wait("job_abc123", timeout=0.01, poll_interval=0.001)
+
+
+# ── tokens ───────────────────────────────────────────────────────────────────
+
+def test_tokens_list():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert "/tokens" in str(request.url)
+        return httpx.Response(200, json=[TOKEN])
+
+    c = make_client(handler)
+    tokens = c.tokens.list()
+    assert len(tokens) == 1
+    assert isinstance(tokens[0], Token)
+    assert tokens[0].name == "my-token"
+
+
+def test_tokens_create():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert "/tokens" in str(request.url)
+        import json
+        body = json.loads(request.content)
+        assert body["name"] == "ci"
+        return httpx.Response(201, json=CREATED_TOKEN)
+
+    c = make_client(handler)
+    tok = c.tokens.create("ci")
+    assert isinstance(tok, CreatedToken)
+    assert tok.token.startswith("pat_")
+
+
+def test_tokens_revoke():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "DELETE"
+        assert "/tokens/tok_1" in str(request.url)
+        return httpx.Response(204)
+
+    c = make_client(handler)
+    c.tokens.revoke("tok_1")  # no exception = success
+
+
+# ── auth errors ───────────────────────────────────────────────────────────────
+
+def test_auth_error_on_401():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, json={"error": "unauthorized"})
+
+    c = make_client(handler)
+    with pytest.raises(AuthError):
+        c.jobs.list()
+
+
+def test_server_error_on_500():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, json={"error": "internal server error"})
+
+    c = make_client(handler)
+    with pytest.raises(ServerError):
+        c.jobs.list()
+
+
+# ── configuration from the environment (HAAS-389) ────────────────────────────
+
+def test_client_reads_token_from_haaslab_token(monkeypatch):
+    monkeypatch.setenv("HAASLAB_TOKEN", "pat_from_env")
+    c = Client()
+    assert c._http.headers["Authorization"] == "Bearer pat_from_env"
+
+
+def test_explicit_token_wins_over_haaslab_token(monkeypatch):
+    monkeypatch.setenv("HAASLAB_TOKEN", "pat_from_env")
+    c = Client(token="pat_explicit")
+    assert c._http.headers["Authorization"] == "Bearer pat_explicit"
+
+
+def test_client_without_any_token_raises_naming_the_variable(monkeypatch):
+    monkeypatch.delenv("HAASLAB_TOKEN", raising=False)
+    with pytest.raises(ValueError, match="HAASLAB_TOKEN"):
+        Client()
+
+
+def test_client_reads_base_url_from_haaslab_base_url(monkeypatch):
+    monkeypatch.setenv("HAASLAB_BASE_URL", "http://localhost:3000/")
+    c = Client(token="pat_test")
+    assert str(c._http.base_url) == "http://localhost:3000/api/v1/"
+
+
+def test_client_defaults_to_haas_lab_com(monkeypatch):
+    monkeypatch.delenv("HAASLAB_BASE_URL", raising=False)
+    c = Client(token="pat_test")
+    assert str(c._http.base_url) == "https://haas-lab.com/api/v1/"

haaslab-0.1.0/tests/test_models.py

@@ -0,0 +1,44 @@
+"""The Job model, against what the v1 API sends (HAAS-141)."""
+
+from haaslab.models import Job
+
+JOB = {
+    "id": "job-1",
+    "userId": "user-1",
+    "status": "QUEUED",
+    "firmwareUrl": "jobs/job-1/firmware.bin",
+    "firmwareSize": 4096,
+    "serialLogUrl": None,
+    "createdAt": "2026-09-04T08:00:00.000Z",
+    "startedAt": None,
+    "completedAt": None,
+}
+
+
+def test_a_queued_job_carries_its_place_in_line() -> None:
+    job = Job.from_dict({**JOB, "queuePosition": 3})
+    assert job.queuePosition == 3
+    assert job.is_queued
+    assert not job.is_terminal
+
+
+def test_a_job_that_is_no_longer_waiting_has_no_position() -> None:
+    job = Job.from_dict({**JOB, "status": "RUNNING", "queuePosition": None})
+    assert job.queuePosition is None
+    assert not job.is_queued
+
+
+def test_a_server_older_than_the_field_is_read_as_no_position() -> None:
+    # The SDK must keep working against a server that does not send it.
+    job = Job.from_dict(JOB)
+    assert job.queuePosition is None
+
+
+def test_a_settled_job_is_terminal_so_wait_returns_on_success() -> None:
+    # SETTLED is the state a successful job ends in: settlement writes it in
+    # the same request as completion. It was missing from the terminal set, so
+    # the documented wait-then-read flow timed out on every success (review,
+    # 2026-09-05).
+    job = Job.from_dict({"id": "j1", "userId": "u1", "status": "SETTLED", "firmwareUrl": "x",
+                         "firmwareSize": 1, "createdAt": "2026-09-05T00:00:00Z"})
+    assert job.is_terminal