aiotransperth 0.1.0__tar.gz

aiotransperth-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: mypy src
+      - run: pytest -v  # live tests are deselected via addopts

aiotransperth-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+# One-time setup before this works: on pypi.org, add a "trusted publisher"
+# for this repo (workflow: release.yml, environment: pypi), and create a
+# GitHub environment named "pypi" in the repo settings. No API token needed.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

aiotransperth-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.claude/settings.local.json

aiotransperth-0.1.0/CLAUDE.md

@@ -0,0 +1,41 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`aiotransperth` — async Python client (aiohttp, Python 3.12+) for Transperth's **unofficial** website APIs, the only channel carrying Perth realtime bus/train data. Because the API is unofficial, response shapes are pinned by live contract tests rather than a spec.
+
+## Commands
+
+A `.venv` exists at the repo root (Python 3.14). Dev setup: `pip install -e ".[dev]"`.
+
+```bash
+pytest                                    # offline tests only (fixtures via aioresponses; live tests deselected via addopts)
+pytest tests/test_client_bus.py           # one file
+pytest tests/test_models.py -k delay      # one test by keyword
+pytest -m live                            # contract tests against the REAL API — run sparingly, never in loops
+ruff check src tests
+mypy src                                  # strict mode
+```
+
+**Live-test caution:** Transperth's HTTP 429 cooldown is sticky (>60 s) and shared with their public website. Don't re-run `-m live` in tight iteration; CI never runs it.
+
+**Dev dependency pin:** `aiohttp<3.14` is constrained in the `dev` extra only, because aioresponses 0.7.9 can't mock aiohttp ≥3.14. Runtime stays `aiohttp>=3.9`. Don't "fix" this by bumping either side without checking aioresponses compatibility.
+
+## Architecture
+
+Single package `src/aiotransperth/`, all public API re-exported from `__init__.py` (keep `__all__` in sync — `tests/test_public_api.py` checks it).
+
+Two distinct API families, both behind one `TransperthClient` (`client.py`):
+
+- **Bus (SilverRail endpoints)** — form-POSTs requiring a CSRF token. `auth.py` owns this: tokens are scoped per `AuthContext` (ROUTE vs STOP — different ModuleId/TabId headers and issuing pages; using the wrong one gets HTTP 401). `TokenManager` caches one token per context, scraped by regex from the issuing HTML page. `_bus_post` retries exactly once on 401 after invalidating the token — that is the client's *only* retry; it never sleeps, and back-off policy deliberately belongs to the caller.
+- **Train** — plain GETs with static headers (`const.py`), no token. Line/station catalogs have no JSON endpoint; `stations.py` regex-parses the server-rendered dropdowns on the Live Train Times page.
+
+`models.py` holds frozen slotted dataclasses plus the time-parsing rules. All API times are naive Perth-local strings; **every datetime this library emits must be timezone-aware `Australia/Perth`** (`PERTH_TZ`). `parse_clock_near` anchors bare clock strings ("1:48pm") to a reference datetime and rolls forward a day for just-past-midnight displays; it returns `None` for unparseable text because the API puts status strings in time fields. Parsing is lenient by design: malformed trip entries are skipped, missing fields default to `""`/`None`.
+
+All errors subclass `TransperthError` (`exceptions.py`): `RateLimitError` (429), `AuthError` (token issues, bus only), `NetworkError` (wraps `aiohttp.ClientError`), `InvalidStopError` (bad stop code / station name — trains signal this via "check spelling" text in the response, not a status code).
+
+## Tests
+
+Offline tests mock HTTP with `aioresponses` against captured payloads in `tests/fixtures/`. If the real API changes shape, update the fixture *and* verify with `pytest -m live` (`tests/live/test_contract.py`, fixed inputs: bus 414, stop 12627, Maylands Stn). pytest-asyncio runs in `asyncio_mode = "auto"` — no `@pytest.mark.asyncio` needed.

aiotransperth-0.1.0/LICENSE

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

aiotransperth-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: aiotransperth
+Version: 0.1.0
+Summary: Async Python client for Transperth (Perth, WA) bus and train departures, with realtime data
+Author: Chris
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: aiohttp<3.14; extra == 'dev'
+Requires-Dist: aioresponses>=0.7.6; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aiotransperth
+
+Live Perth bus and train departures in Python — including realtime delays.
+
+Transperth (Perth, Western Australia's public transport operator) publishes
+no official realtime API. Live delay data exists in exactly one place: the
+Transperth website itself. This library talks to the same internal endpoints
+the website uses and hands you the results as plain, typed Python objects —
+the only way to get Perth realtime data into your own code.
+
+- **Buses** — upcoming departures at any stop, live delays for buses already
+  on the road, and stop-by-stop trip details.
+- **Trains** — live departures for any station: destination, platform, delay
+  status, car count.
+
+Async (`aiohttp` is the only dependency), fully typed, Python 3.12+, MIT.
+
+## Getting started
+
+Not on PyPI yet — install from a checkout:
+
+```bash
+git clone https://github.com/Chris112/aiotransperth
+cd aiotransperth
+pip install .
+```
+
+Then:
+
+```python
+import asyncio
+
+from aiotransperth import TransperthClient
+
+
+async def main() -> None:
+    async with TransperthClient() as client:
+        # ---- Buses: next departures at stop 12627 ----
+        timetable = await client.get_stop_timetable("12627")
+        print(f"Stop {timetable.stop.code}: {timetable.stop.name}")
+        for dep in timetable.departures[:3]:
+            when = dep.estimated or dep.scheduled  # live estimate if available
+            live = f"live, {dep.live.description}" if dep.live.is_live else "scheduled"
+            print(f"  {dep.route:>4} to {dep.headsign:<20} {when:%H:%M} ({live})")
+
+        # ---- Trains: live status at Maylands on the Midland line ----
+        trains = await client.get_train_departures("Midland Line", "Maylands Stn")
+        print("Maylands Stn (Midland Line):")
+        for train in trains[:3]:
+            when = train.estimated or train.scheduled
+            print(
+                f"  to {train.destination:<8} plat {train.platform} "
+                f"{when:%H:%M} ({train.live.description}, {train.cars} cars)"
+            )
+
+
+asyncio.run(main())
+```
+
+Real output (Monday afternoon, Perth):
+
+```
+Stop 12627: Main St After Royal St
+   404 to Tuart Hill           15:20 (scheduled)
+   402 to Perth Busport        15:22 (scheduled)
+   414 to Glendalough Stn      15:33 (scheduled)
+Maylands Stn (Midland Line):
+  to Midland  plat 2 14:50 (On Time, 4 cars)
+  to Perth    plat 1 14:57 (On Time, 4 cars)
+  to Midland  plat 2 15:01 (On Time, 4 cars)
+```
+
+When a bus is live-tracked (typically the imminent departure), `dep.live.is_live`
+is true, `dep.estimated` carries the actual expected time, and
+`dep.delay_minutes` the difference — e.g. `3` for a bus running three minutes
+late. Trains are always live-tracked while services run.
+
+## Finding your inputs
+
+- **Bus stop code** — the 5-digit number printed on the physical stop sign,
+  also shown when you click a stop in the
+  [Transperth journey planner](https://www.transperth.wa.gov.au). Verify one
+  with `await client.validate_stop("12627")`, which returns the stop's name or
+  raises `InvalidStopError`.
+- **Train line and station names** — display names exactly as the Transperth
+  site spells them: lines like `"Midland Line"`, stations like `"Maylands Stn"`.
+  Don't guess; fetch the catalog:
+
+  ```python
+  lines = await client.get_train_lines()        # ("Airport Line", ..., "Yanchep Line")
+  stations = await client.get_train_stations()  # (TrainStation(id="130", name="Maylands Stn"), ...)
+  ```
+
+## API
+
+All methods are coroutines on `TransperthClient`. Construct it bare (it
+manages its own `aiohttp` session as an async context manager) or pass your
+own session, which will not be closed for you.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `get_stop_timetable(stop_code, *, when=None, max_trips=100)` | `StopTimetable` (stop + `BusDeparture` tuple) | Realtime always requested. `when` defaults to now (Perth). |
+| `validate_stop(stop_code)` | `Stop` | Raises `InvalidStopError` for unknown codes. |
+| `get_route_trips(route, *, when=None, max_options=4)` | `tuple[RouteTrip, ...]` | Upcoming trips for a route, e.g. `"414"`. |
+| `get_trip_stops(trip)` | `tuple[TripStop, ...]` | Every stop on a trip, with times, boarding flags, GPS. |
+| `get_train_departures(line, station)` | `tuple[TrainDeparture, ...]` | Live status; raises `InvalidStopError` for unknown stations. |
+| `get_train_lines()` | `tuple[str, ...]` | The 8 line names. Fetched once, cached per client. |
+| `get_train_stations()` | `tuple[TrainStation, ...]` | All ~80 stations. Fetched once, cached per client. |
+
+Departure models share a core: `scheduled` and `estimated` (aware datetimes;
+`estimated` is `None` when not live), `live` (a `LiveStatus` with `is_live`,
+raw `status_code`, and a human `description`), and a `delay_minutes` property.
+Buses add `route`, `headsign`, `origin`, `destination`, `trip_uid`; trains add
+`line`, `destination`, `platform`, `cars`, `pattern`, `trip_id`.
+
+## Errors
+
+Everything raises a subclass of `TransperthError`:
+
+| Exception | Meaning | What to do |
+|---|---|---|
+| `RateLimitError` | HTTP 429 — Transperth's cooldown is sticky (>60 s) and shared with their public website | Back off for minutes, not seconds |
+| `AuthError` | A CSRF token couldn't be obtained or was rejected (bus endpoints only) | Usually transient; the client already retried once |
+| `NetworkError` | DNS/timeout/connection failure | Retry with your own policy |
+| `InvalidStopError` | Unknown stop code or station name | Fix the input |
+
+The client itself never sleeps and never retries beyond one automatic token
+refresh on HTTP 401 — back-off policy belongs to the caller.
+
+## Data caveats
+
+- This is an **unofficial** API; Transperth can change or break it without
+  notice. A `-m live` contract test suite pins the shapes this library reads.
+- Individual departures the API garbles are skipped, not raised — a response
+  with one malformed entry still returns the rest.
+- Bus realtime only lights up for vehicles already on the road — usually the
+  next imminent departure. Everything else is scheduled times.
+- The bus timetable endpoint self-caps its response window (~2 hours of
+  departures) regardless of `max_trips`.
+- Be respectful: one or two requests per query, no tight polling loops.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                # offline tests only (fixtures, no network)
+pytest -m live        # contract tests against the real API — run sparingly
+ruff check src tests && mypy src
+```
+
+The package version lives in `src/aiotransperth/__init__.py` (`__version__`);
+`pyproject.toml` reads it from there, so bump it in one place only.
+
+## License
+
+MIT

aiotransperth-0.1.0/README.md

@@ -0,0 +1,156 @@
+# aiotransperth
+
+Live Perth bus and train departures in Python — including realtime delays.
+
+Transperth (Perth, Western Australia's public transport operator) publishes
+no official realtime API. Live delay data exists in exactly one place: the
+Transperth website itself. This library talks to the same internal endpoints
+the website uses and hands you the results as plain, typed Python objects —
+the only way to get Perth realtime data into your own code.
+
+- **Buses** — upcoming departures at any stop, live delays for buses already
+  on the road, and stop-by-stop trip details.
+- **Trains** — live departures for any station: destination, platform, delay
+  status, car count.
+
+Async (`aiohttp` is the only dependency), fully typed, Python 3.12+, MIT.
+
+## Getting started
+
+Not on PyPI yet — install from a checkout:
+
+```bash
+git clone https://github.com/Chris112/aiotransperth
+cd aiotransperth
+pip install .
+```
+
+Then:
+
+```python
+import asyncio
+
+from aiotransperth import TransperthClient
+
+
+async def main() -> None:
+    async with TransperthClient() as client:
+        # ---- Buses: next departures at stop 12627 ----
+        timetable = await client.get_stop_timetable("12627")
+        print(f"Stop {timetable.stop.code}: {timetable.stop.name}")
+        for dep in timetable.departures[:3]:
+            when = dep.estimated or dep.scheduled  # live estimate if available
+            live = f"live, {dep.live.description}" if dep.live.is_live else "scheduled"
+            print(f"  {dep.route:>4} to {dep.headsign:<20} {when:%H:%M} ({live})")
+
+        # ---- Trains: live status at Maylands on the Midland line ----
+        trains = await client.get_train_departures("Midland Line", "Maylands Stn")
+        print("Maylands Stn (Midland Line):")
+        for train in trains[:3]:
+            when = train.estimated or train.scheduled
+            print(
+                f"  to {train.destination:<8} plat {train.platform} "
+                f"{when:%H:%M} ({train.live.description}, {train.cars} cars)"
+            )
+
+
+asyncio.run(main())
+```
+
+Real output (Monday afternoon, Perth):
+
+```
+Stop 12627: Main St After Royal St
+   404 to Tuart Hill           15:20 (scheduled)
+   402 to Perth Busport        15:22 (scheduled)
+   414 to Glendalough Stn      15:33 (scheduled)
+Maylands Stn (Midland Line):
+  to Midland  plat 2 14:50 (On Time, 4 cars)
+  to Perth    plat 1 14:57 (On Time, 4 cars)
+  to Midland  plat 2 15:01 (On Time, 4 cars)
+```
+
+When a bus is live-tracked (typically the imminent departure), `dep.live.is_live`
+is true, `dep.estimated` carries the actual expected time, and
+`dep.delay_minutes` the difference — e.g. `3` for a bus running three minutes
+late. Trains are always live-tracked while services run.
+
+## Finding your inputs
+
+- **Bus stop code** — the 5-digit number printed on the physical stop sign,
+  also shown when you click a stop in the
+  [Transperth journey planner](https://www.transperth.wa.gov.au). Verify one
+  with `await client.validate_stop("12627")`, which returns the stop's name or
+  raises `InvalidStopError`.
+- **Train line and station names** — display names exactly as the Transperth
+  site spells them: lines like `"Midland Line"`, stations like `"Maylands Stn"`.
+  Don't guess; fetch the catalog:
+
+  ```python
+  lines = await client.get_train_lines()        # ("Airport Line", ..., "Yanchep Line")
+  stations = await client.get_train_stations()  # (TrainStation(id="130", name="Maylands Stn"), ...)
+  ```
+
+## API
+
+All methods are coroutines on `TransperthClient`. Construct it bare (it
+manages its own `aiohttp` session as an async context manager) or pass your
+own session, which will not be closed for you.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `get_stop_timetable(stop_code, *, when=None, max_trips=100)` | `StopTimetable` (stop + `BusDeparture` tuple) | Realtime always requested. `when` defaults to now (Perth). |
+| `validate_stop(stop_code)` | `Stop` | Raises `InvalidStopError` for unknown codes. |
+| `get_route_trips(route, *, when=None, max_options=4)` | `tuple[RouteTrip, ...]` | Upcoming trips for a route, e.g. `"414"`. |
+| `get_trip_stops(trip)` | `tuple[TripStop, ...]` | Every stop on a trip, with times, boarding flags, GPS. |
+| `get_train_departures(line, station)` | `tuple[TrainDeparture, ...]` | Live status; raises `InvalidStopError` for unknown stations. |
+| `get_train_lines()` | `tuple[str, ...]` | The 8 line names. Fetched once, cached per client. |
+| `get_train_stations()` | `tuple[TrainStation, ...]` | All ~80 stations. Fetched once, cached per client. |
+
+Departure models share a core: `scheduled` and `estimated` (aware datetimes;
+`estimated` is `None` when not live), `live` (a `LiveStatus` with `is_live`,
+raw `status_code`, and a human `description`), and a `delay_minutes` property.
+Buses add `route`, `headsign`, `origin`, `destination`, `trip_uid`; trains add
+`line`, `destination`, `platform`, `cars`, `pattern`, `trip_id`.
+
+## Errors
+
+Everything raises a subclass of `TransperthError`:
+
+| Exception | Meaning | What to do |
+|---|---|---|
+| `RateLimitError` | HTTP 429 — Transperth's cooldown is sticky (>60 s) and shared with their public website | Back off for minutes, not seconds |
+| `AuthError` | A CSRF token couldn't be obtained or was rejected (bus endpoints only) | Usually transient; the client already retried once |
+| `NetworkError` | DNS/timeout/connection failure | Retry with your own policy |
+| `InvalidStopError` | Unknown stop code or station name | Fix the input |
+
+The client itself never sleeps and never retries beyond one automatic token
+refresh on HTTP 401 — back-off policy belongs to the caller.
+
+## Data caveats
+
+- This is an **unofficial** API; Transperth can change or break it without
+  notice. A `-m live` contract test suite pins the shapes this library reads.
+- Individual departures the API garbles are skipped, not raised — a response
+  with one malformed entry still returns the rest.
+- Bus realtime only lights up for vehicles already on the road — usually the
+  next imminent departure. Everything else is scheduled times.
+- The bus timetable endpoint self-caps its response window (~2 hours of
+  departures) regardless of `max_trips`.
+- Be respectful: one or two requests per query, no tight polling loops.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                # offline tests only (fixtures, no network)
+pytest -m live        # contract tests against the real API — run sparingly
+ruff check src tests && mypy src
+```
+
+The package version lives in `src/aiotransperth/__init__.py` (`__version__`);
+`pyproject.toml` reads it from there, so bump it in one place only.
+
+## License
+
+MIT

aiotransperth-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aiotransperth"
+dynamic = ["version"]
+description = "Async Python client for Transperth (Perth, WA) bus and train departures, with realtime data"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Chris" }]
+dependencies = ["aiohttp>=3.9"]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "aioresponses>=0.7.6",
+  # aioresponses 0.7.9 can't mock aiohttp >=3.14 (ClientResponse signature
+  # change); constrain the test env only — runtime stays aiohttp>=3.9.
+  "aiohttp<3.14",
+  "ruff>=0.7",
+  "mypy>=1.11",
+]
+
+[tool.hatch.version]
+# Single source of truth: __version__ in the package.
+path = "src/aiotransperth/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = ["live: hits the real Transperth API (deselected by default)"]
+addopts = "-m 'not live'"
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true

aiotransperth-0.1.0/src/aiotransperth/__init__.py

@@ -0,0 +1,43 @@
+"""Async client for Transperth (Perth, WA) bus and train departures."""
+
+from .client import TransperthClient
+from .exceptions import (
+    AuthError,
+    InvalidStopError,
+    NetworkError,
+    RateLimitError,
+    TransperthError,
+)
+from .models import (
+    PERTH_TZ,
+    BusDeparture,
+    LiveStatus,
+    Mode,
+    RouteTrip,
+    Stop,
+    StopTimetable,
+    TrainDeparture,
+    TrainStation,
+    TripStop,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PERTH_TZ",
+    "AuthError",
+    "BusDeparture",
+    "InvalidStopError",
+    "LiveStatus",
+    "Mode",
+    "NetworkError",
+    "RateLimitError",
+    "RouteTrip",
+    "Stop",
+    "StopTimetable",
+    "TrainDeparture",
+    "TrainStation",
+    "TransperthClient",
+    "TransperthError",
+    "TripStop",
+]

aiotransperth-0.1.0/src/aiotransperth/auth.py

@@ -0,0 +1,98 @@
+"""CSRF token management for the bus (SilverRail) endpoints.
+
+Tokens are scoped to the page that issued them: route pages and stop pages
+issue different tokens, sent with different ModuleId/TabId headers. Using
+the wrong one returns HTTP 401. Train endpoints need no token.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+import aiohttp
+
+from .const import BASE_URL, USER_AGENT
+from .exceptions import AuthError, NetworkError
+
+_TOKEN_RE = re.compile(
+    r'<input\s+name="__RequestVerificationToken"\s+type="hidden"\s+value="([^"]+)"'
+)
+
+
+class AuthContext(Enum):
+    ROUTE = "route"
+    STOP = "stop"
+
+
+@dataclass(frozen=True)
+class _ContextSpec:
+    module_id: str
+    tab_id: str
+    page_url: str  # str.format template taking ref=
+
+
+_SPECS: dict[AuthContext, _ContextSpec] = {
+    AuthContext.ROUTE: _ContextSpec(
+        "5345", "133", BASE_URL + "/timetables/details?Bus={ref}"
+    ),
+    AuthContext.STOP: _ContextSpec(
+        "5310",
+        "141",
+        BASE_URL + "/Journey-Planner/Stops-Near-You?locationtype=stop&location={ref}",
+    ),
+}
+
+
+def bus_headers(context: AuthContext, token: str, ref: str) -> dict[str, str]:
+    """Request headers for a SilverRail API call in the given auth context."""
+    spec = _SPECS[context]
+    headers = {
+        "RequestVerificationToken": token,
+        "ModuleId": spec.module_id,
+        "TabId": spec.tab_id,
+        "Content-Type": "application/x-www-form-urlencoded",
+        "User-Agent": USER_AGENT,
+        "Accept": "application/json, text/javascript, */*; q=0.01",
+        "X-Requested-With": "XMLHttpRequest",
+    }
+    if context is AuthContext.STOP:
+        headers["Referer"] = spec.page_url.format(ref=ref)
+        headers["Origin"] = BASE_URL
+    return headers
+
+
+class TokenManager:
+    """Caches one token per auth context; refetches after invalidate()."""
+
+    def __init__(self) -> None:
+        self._tokens: dict[AuthContext, str] = {}
+
+    async def get_token(
+        self,
+        session: aiohttp.ClientSession,
+        context: AuthContext,
+        ref: str,
+        timeout: aiohttp.ClientTimeout,
+    ) -> str:
+        if context in self._tokens:
+            return self._tokens[context]
+        url = _SPECS[context].page_url.format(ref=ref)
+        try:
+            async with session.get(
+                url, headers={"User-Agent": USER_AGENT}, timeout=timeout
+            ) as resp:
+                if resp.status != 200:
+                    raise AuthError(f"Token page returned HTTP {resp.status}")
+                html = await resp.text()
+        except aiohttp.ClientError as err:
+            raise NetworkError(f"Could not reach Transperth: {err}") from err
+        match = _TOKEN_RE.search(html)
+        if not match:
+            raise AuthError(f"No verification token found on {url}")
+        self._tokens[context] = match.group(1)
+        return self._tokens[context]
+
+    def invalidate(self, context: AuthContext) -> None:
+        self._tokens.pop(context, None)