stb-reader 0.2.0__tar.gz → 0.2.1__tar.gz

{stb_reader-0.2.0 → stb_reader-0.2.1}/AGENTS.md

@@ -25,7 +25,8 @@ stb_reader/        Sole importable package
   exceptions.py    STBError, AuthError, StreamError, NotFoundError
 
 tests/             pytest suite; all HTTP mocked via `responses` library
-docs/              STB protocol reference (authentication, live-tv, vod-series)
+docs/protocol/     STB protocol reference (authentication, live-tv, vod-series)
+docs/guide/        User-facing guides (cli.md)
 spec/              Spec-driven feature specs (NNN-slug/{requirements,plan,implement}.md)
 
 .github/
@@ -95,6 +96,7 @@ The `PYPI_TOKEN` secret must be configured in the GitHub repository settings.
 
 ## Documentation
 
-- `docs/` contains protocol-level reference for the Ministra/Stalker STB API
-- Update the relevant `docs/` file when changing protocol behavior
+- `docs/protocol/` contains protocol-level reference for the Ministra/Stalker STB API
+- `docs/guide/` contains user-facing guides (CLI, library usage)
+- Update the relevant `docs/protocol/` file when changing protocol behavior
 - Update this file (`AGENTS.md`) when adding commands, models, or boundaries

{stb_reader-0.2.0 → stb_reader-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stb-reader
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python client library for Ministra/Stalker STB portals
 Project-URL: Homepage, https://github.com/shubhsheth/stb-reader
 Project-URL: Repository, https://github.com/shubhsheth/stb-reader
@@ -49,17 +49,27 @@ Description-Content-Type: text/markdown
 
 # stb-reader
 
-Python client library for [Ministra/Stalker](https://ministra.com/) STB portals. Retrieve live-TV channels, VOD content, series, episodes, and stream URLs with simple method calls.
+Python client library and CLI for [Ministra/Stalker](https://ministra.com/) STB portals. Browse live TV channels, VOD content, and series, or resolve stream URLs — from Python code or straight from the terminal.
 
-## Installation
+## Install
 
 ```bash
 pip install stb-reader
 ```
 
-Requires Python 3.11+ and has a single runtime dependency: `requests`.
+Requires Python 3.11+.
 
-## Quick start
+## Quick start — CLI
+
+```bash
+stb init                       # save portal URL and MAC address once
+stb live channels              # browse channels
+stb stream --type live <cmd>   # get a stream URL
+```
+
+See the [CLI reference](docs/guide/cli.md) for all commands.
+
+## Quick start — Python
 
 ```python
 from stb_reader import STBClient
@@ -71,12 +81,10 @@ client = STBClient(
 client.authenticate()
 
 # Live TV
-genres = client.live_tv.get_genres()
 channels = client.live_tv.get_channels(genre_id="*", page=1)
 stream_url = client.live_tv.get_stream_url(channels.items[0].cmd)
 
 # VOD
-categories = client.vod.get_categories()
 content = client.vod.get_content(category_id="*", page=1)
 
 # Series
@@ -89,57 +97,9 @@ stream_url = client.vod.get_stream_url_by_first_file(
 )
 ```
 
-## API reference
-
-### `STBClient(base_url, mac, serial, lang, timezone, portal_path)`
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `base_url` | required | Portal base URL |
-| `mac` | required | Device MAC address |
-| `serial` | `"000000000000"` | Device serial |
-| `lang` | `"en"` | Portal language |
-| `timezone` | `"Europe/London"` | Portal timezone |
-| `portal_path` | `"stalker_portal/c/portal.php"` | Path to portal PHP endpoint |
-
-### `client.live_tv`
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `get_genres()` | `list[Genre]` | All channel genres |
-| `get_channels(genre_id, page, sort, hd, fav)` | `PagedResult[Channel]` | Paginated channel list |
-| `get_stream_url(cmd)` | `str` | Resolved stream URL for a channel `cmd` |
-| `get_stream_url_by_id(channel_id)` | `str` | Resolved stream URL by channel ID |
-
-### `client.vod`
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `get_categories()` | `list[Category]` | All VOD categories |
-| `get_content(category_id, page, sort, fav)` | `PagedResult[Content]` | Paginated VOD content |
-| `get_seasons(series_id)` | `list[Season]` | Seasons for a series |
-| `get_episodes(series_id, season_id)` | `list[Episode]` | All episodes in a season |
-| `get_episode_files(series_id, season_id, episode_id)` | `list[EpisodeFile]` | Quality variants for an episode |
-| `get_stream_url(cmd)` | `str` | Resolved stream URL for a VOD `cmd` |
-| `get_stream_url_by_content_id(content_id)` | `str` | Stream URL for a movie by ID |
-| `get_stream_url_by_first_file(series_id, season_id, episode_id)` | `str` | Stream URL for first file of an episode |
-| `get_stream_url_by_file_id(series_id, season_id, episode_id, file_id)` | `str` | Stream URL for a specific file |
-
-## Exceptions
-
-All exceptions are importable from `stb_reader`:
-
-| Exception | Raised when |
-|-----------|-------------|
-| `STBError` | Base class for all library errors |
-| `AuthError` | Authentication / token failure |
-| `StreamError` | Portal rejects a stream request |
-| `NotFoundError` | Requested item not found |
-
 ## Documentation
 
-Full guides are in [`docs/guide/`](docs/guide/):
-
+- [CLI reference](docs/guide/cli.md) — `stb` command-line tool
 - [Getting started](docs/guide/getting-started.md) — installation, configuration, first call
 - [Authentication](docs/guide/authentication.md) — token lifecycle, auto-reauth, error handling
 - [Live TV](docs/guide/live-tv.md) — genres, channels, stream URLs

stb_reader-0.2.1/README.md

@@ -0,0 +1,65 @@
+# stb-reader
+
+Python client library and CLI for [Ministra/Stalker](https://ministra.com/) STB portals. Browse live TV channels, VOD content, and series, or resolve stream URLs — from Python code or straight from the terminal.
+
+## Install
+
+```bash
+pip install stb-reader
+```
+
+Requires Python 3.11+.
+
+## Quick start — CLI
+
+```bash
+stb init                       # save portal URL and MAC address once
+stb live channels              # browse channels
+stb stream --type live <cmd>   # get a stream URL
+```
+
+See the [CLI reference](docs/guide/cli.md) for all commands.
+
+## Quick start — Python
+
+```python
+from stb_reader import STBClient
+
+client = STBClient(
+    base_url="http://your-portal.example.com",
+    mac="00:1A:79:XX:XX:XX",
+)
+client.authenticate()
+
+# Live TV
+channels = client.live_tv.get_channels(genre_id="*", page=1)
+stream_url = client.live_tv.get_stream_url(channels.items[0].cmd)
+
+# VOD
+content = client.vod.get_content(category_id="*", page=1)
+
+# Series
+seasons = client.vod.get_seasons(series_id="123")
+episodes = client.vod.get_episodes(series_id="123", season_id=seasons[0].id)
+stream_url = client.vod.get_stream_url_by_first_file(
+    series_id="123",
+    season_id=seasons[0].id,
+    episode_id=episodes[0].id,
+)
+```
+
+## Documentation
+
+- [CLI reference](docs/guide/cli.md) — `stb` command-line tool
+- [Getting started](docs/guide/getting-started.md) — installation, configuration, first call
+- [Authentication](docs/guide/authentication.md) — token lifecycle, auto-reauth, error handling
+- [Live TV](docs/guide/live-tv.md) — genres, channels, stream URLs
+- [VOD — Movies](docs/guide/vod.md) — categories, content listing, movie streams
+- [Series](docs/guide/series.md) — seasons, episodes, quality selection
+- [Pagination](docs/guide/pagination.md) — `PagedResult`, fetch-all-pages pattern
+- [Error handling](docs/guide/error-handling.md) — all exceptions, recovery patterns
+- [API reference](docs/guide/api-reference.md) — complete method, model, and exception reference
+
+## License
+
+MIT

stb_reader-0.2.1/docs/guide/cli.md

@@ -0,0 +1,206 @@
+# CLI Reference
+
+The `stb` command-line tool lets you browse and stream STB portal content from a terminal.
+
+## Installation
+
+```bash
+pip install stb-reader
+```
+
+Verify the tool is available:
+
+```bash
+stb --help
+```
+
+## Configuration
+
+Run `stb init` once to save your portal credentials to `~/.stb/config`:
+
+```bash
+stb init
+```
+
+You will be prompted for:
+
+| Prompt | Default | Notes |
+|---|---|---|
+| Portal URL (no port) | _(required)_ | e.g. `http://192.168.1.10` |
+| Port | _(blank)_ | e.g. `8080`; leave blank if included in URL |
+| MAC address | _(required)_ | e.g. `00:1A:79:XX:XX:XX` |
+| Serial | `000000000000` | Device serial number |
+| Language | `en` | Portal language code |
+| Timezone | `Europe/London` | IANA timezone name |
+| Portal path | `stalker_portal/c/portal.php` | Path to the portal endpoint |
+
+The config is saved as plain JSON and can be edited by hand:
+
+```json
+{
+  "url": "http://192.168.1.10",
+  "port": "8080",
+  "mac": "00:1A:79:XX:XX:XX",
+  "serial": "000000000000",
+  "lang": "en",
+  "timezone": "Europe/London",
+  "portal_path": "stalker_portal/c/portal.php"
+}
+```
+
+All commands except `stb init` read this file and exit with an error if it is missing.
+
+## Global Flags
+
+| Flag | Description |
+|---|---|
+| `--debug` | Print raw portal responses to stderr. Useful for diagnosing auth or stream failures. |
+
+```bash
+stb --debug live genres
+```
+
+## Live TV
+
+### `stb live genres`
+
+List all live TV genres.
+
+```
+ID    Title
+----  -----------
+1     General
+2     Sports
+3     News
+```
+
+### `stb live channels`
+
+List channels, optionally filtered by genre or HD status.
+
+```bash
+stb live channels
+stb live channels --genre 2
+stb live channels --hd
+stb live channels --page 2
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--genre <id>` | `*` | Filter by genre ID (from `stb live genres`) |
+| `--hd` | off | Show HD channels only |
+| `--page <n>` | `1` | Page number |
+
+```
+#     Name            Genre ID  HD   CMD
+----  --------------  --------  ---  -------------------
+101   BBC One         1               ffmpeg://...
+102   Sky Sports HD   2         yes  ffmpeg://...
+
+Page 1 of 5 (48 total)
+```
+
+The `CMD` value is used with `stb stream` to resolve a playable URL.
+
+## VOD
+
+### `stb vod categories`
+
+List all VOD categories.
+
+```
+ID    Title
+----  -----------
+1     Action
+2     Comedy
+```
+
+### `stb vod list`
+
+List VOD content, optionally filtered by category.
+
+```bash
+stb vod list
+stb vod list --category 1
+stb vod list --page 2
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--category <id>` | `*` | Filter by category ID (from `stb vod categories`) |
+| `--page <n>` | `1` | Page number |
+
+```
+ID    Name            Year  Genres   Series  CMD
+----  --------------  ----  -------  ------  -----------
+42    Inception       2010  Action           ffmpeg://...
+99    Breaking Bad    2008  Drama    yes     ffmpeg://...
+
+Page 1 of 12 (115 total)
+```
+
+### `stb vod seasons <series_id>`
+
+List seasons for a series. The `series_id` is the ID from `stb vod list`.
+
+```bash
+stb vod seasons 99
+```
+
+```
+ID    Name
+----  --------
+1     Season 1
+2     Season 2
+```
+
+### `stb vod episodes <series_id> <season_id>`
+
+List episodes for a season.
+
+```bash
+stb vod episodes 99 1
+stb vod episodes 99 1 --page 2
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--page <n>` | `1` | Page number |
+
+```
+ID    Name          #   CMD
+----  ------------  --  -----------
+201   Pilot         1   ffmpeg://...
+202   Cat's in the  2   ffmpeg://...
+
+Page 1 of 7 (62 total)
+```
+
+The `CMD` value is used with `stb stream` to resolve a playable URL.
+
+## Stream URLs
+
+### `stb stream --type <live|vod> <cmd>`
+
+Resolve a stream URL and print it to stdout. The `--type` flag is required. The `<cmd>` value comes from the `CMD` column of a prior listing command.
+
+```bash
+stb stream --type live "ffmpeg://..."
+stb stream --type vod "ffmpeg://..."
+```
+
+Pipe directly to a media player:
+
+```bash
+stb stream --type live "ffmpeg://..." | xargs mpv
+```
+
+## Error Handling
+
+| Situation | Message | Exit code |
+|---|---|---|
+| Config file missing | `No config found. Run 'stb init' first.` | 1 |
+| Authentication failure | Short description to stderr | 1 |
+| Stream resolution failure | Short description to stderr | 1 |
+
+No Python tracebacks are shown. Use `--debug` to see raw portal responses when diagnosing failures.

{stb_reader-0.2.0 → stb_reader-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stb-reader"
-version = "0.2.0"
+version = "0.2.1"
 description = "Python client library for Ministra/Stalker STB portals"
 readme = "README.md"
 license = { file = "LICENSE" }

stb_reader-0.2.1/spec/016-persist-cli-token/016-persist-cli-token-requirements.md

@@ -0,0 +1,150 @@
+# Spec: Persist CLI Auth Token (016)
+
+## Objective
+
+Eliminate the redundant handshake that occurs on every CLI invocation by persisting the session token to disk. On the next CLI call the cached token is loaded and used directly; if it has expired the existing in-process re-auth path fires automatically and the refreshed token is written back to disk.
+
+Target user: anyone running `stb` CLI commands repeatedly (e.g. in scripts or quickly browsing channels). Today each command does a full handshake round-trip before doing its real work; after this change only the first invocation (or the one after a token expiry) pays that cost.
+
+## User Stories
+
+- As a CLI user, I want subsequent `stb` commands to skip the auth handshake so they respond faster.
+- As a CLI user, I want the cache to refresh transparently when my token expires so I never have to manually re-authenticate.
+
+## Functional Requirements
+
+- FR-1: After a successful `authenticate()` call, the CLI writes the session token and any extra headers (`X-Random`, `Random`) to `~/.stb/token` as JSON.
+- FR-2: On every CLI invocation, `get_client()` attempts to load `~/.stb/token`. If a valid token is found, it is applied to the session and `authenticate()` is **not** called.
+- FR-3: When the loaded token causes an auth failure, the existing `_http.py` re-auth path calls `authenticate()` which refreshes the session. The CLI wrapper then saves the new token to `~/.stb/token`.
+- FR-4: If `~/.stb/token` is missing or contains invalid JSON, `get_client()` falls back to a full `authenticate()` call and saves the resulting token.
+- FR-5: The token file is written with the same directory guarantees as the config file (`~/.stb/` created if absent).
+
+## Non-Functional Requirements
+
+- NFR-1: No new runtime dependencies. Uses only `json` and `pathlib` (already in use in `config.py`).
+- NFR-2: The token file is human-readable JSON so users can inspect or delete it manually.
+- NFR-3: No changes to library code (`client.py`, `_http.py`, `auth.py`). All changes are CLI-only.
+- NFR-4: Thread safety is not a concern for the CLI (single-process, sequential commands).
+
+## Out of Scope
+
+- `stb logout` command or explicit token invalidation command.
+- Token expiry timestamps / TTL-based eviction (rely on re-auth-on-failure instead).
+- Library-level token persistence (library callers manage their own sessions).
+- Multi-profile or per-portal token caching.
+- File permissions hardening (e.g. `chmod 600`) — left for a future security hardening pass.
+
+## Assumptions
+
+- The session token returned by the portal is stable enough to reuse across CLI invocations (i.e. not invalidated purely by time between calls in normal usage).
+- `~/.stb/token` is an acceptable path (same parent directory as `~/.stb/config`).
+- `extra_headers` on the session (e.g. `X-Random`) must also be persisted; some portals require them alongside the token on every request.
+- Deleting `~/.stb/token` is the supported manual "logout" / cache-clear mechanism.
+
+## Tech Stack
+
+- Python ≥ 3.11
+- stdlib only: `json`, `pathlib.Path`
+- `pytest` + `responses` + Click's `CliRunner` for tests
+
+## Commands
+
+```
+Test:    pytest tests/
+Install: pip install -e .
+Run CLI: stb --help
+```
+
+## Project Structure
+
+```
+stb_reader/
+  cli/
+    config.py       ← only file changed (add TOKEN_PATH, save_token, load_token; modify get_client)
+tests/
+  test_cli_config.py  ← new test cases added here
+spec/
+  016-persist-cli-token/   ← this spec
+```
+
+## Code Style
+
+Match the existing `config.py` style: plain functions, no classes, type annotations, no comments unless the why is non-obvious.
+
+```python
+TOKEN_PATH = Path.home() / ".stb" / "token"
+
+def save_token(session) -> None:
+    TOKEN_PATH.parent.mkdir(parents=True, exist_ok=True)
+    TOKEN_PATH.write_text(json.dumps({
+        "token": session.token,
+        "extra_headers": session.extra_headers,
+    }))
+
+def load_token() -> dict | None:
+    if not TOKEN_PATH.exists():
+        return None
+    try:
+        return json.loads(TOKEN_PATH.read_text())
+    except (json.JSONDecodeError, KeyError):
+        return None
+```
+
+`get_client()` wraps `client.authenticate` so every auth (initial or re-auth) persists the token:
+
+```python
+def get_client() -> STBClient:
+    cfg = load_config()
+    ...
+    client = STBClient(**kwargs)
+
+    def _auth_and_save():
+        client.authenticate()
+        save_token(client._session)
+
+    client._session.reauth_fn = _auth_and_save
+
+    cached = load_token()
+    if cached:
+        client._session.token = cached["token"]
+        client._session.extra_headers.update(cached.get("extra_headers", {}))
+    else:
+        _auth_and_save()
+
+    return client
+```
+
+## Testing Strategy
+
+- Framework: `pytest` with `monkeypatch` and Click's `CliRunner`.
+- All new tests go in `tests/test_cli_config.py` alongside existing config tests.
+- No new test files needed.
+- Each new functional requirement has at least one happy-path and one error-path test.
+
+Test cases:
+
+| Test | Requirement |
+|------|-------------|
+| `test_save_and_load_token` — round-trip token + extra_headers | FR-1, FR-5 |
+| `test_load_token_missing` — returns `None` when file absent | FR-4 |
+| `test_load_token_corrupt` — returns `None` on bad JSON | FR-4 |
+| `test_get_client_saves_token_on_fresh_auth` — no cache → authenticate called → token written | FR-1, FR-2 |
+| `test_get_client_uses_cached_token` — cache present → authenticate not called → token applied | FR-2 |
+| `test_get_client_reauth_updates_token` — reauth_fn fires → updated token written to disk | FR-3 |
+
+## Boundaries
+
+- **Always:** Run `pytest tests/` before marking done. Keep all changes inside `cli/config.py` and `tests/test_cli_config.py`.
+- **Ask first:** Any change to library files (`client.py`, `_http.py`, `auth.py`). Adding a new CLI command (e.g. `stb logout`). Changing the token file path or format after the spec is approved.
+- **Never:** Silently swallow `IOError` / `PermissionError` when writing the token file (let it surface). Touch files outside `cli/config.py` and its test.
+
+## Success Criteria
+
+- Running `stb live genres` twice in succession: the second invocation does not perform a network handshake (observable via `--debug` logging or by mocking).
+- When the token file contains a stale token, the command still succeeds after a transparent re-auth, and the token file is updated with the new token.
+- Deleting `~/.stb/token` and re-running any command causes a fresh handshake and recreates the file.
+- `pytest tests/` passes with no failures and no regressions in existing tests.
+
+## Open Questions
+
+None — all requirements confirmed with the user.

{stb_reader-0.2.0 → stb_reader-0.2.1}/stb_reader/_http.py

@@ -62,7 +62,7 @@ class STBSession:
         self._cookies["token"] = self.token
         headers = {**self._base_headers, "Authorization": f"Bearer {self.token}", **self.extra_headers}
         resp = self._session.get(url, params=query, headers=headers, cookies=self._cookies, timeout=_REQUEST_TIMEOUT)
-        logger.debug("Response [%s %s]: %s", resp.status_code, action, resp.text[:500])
+        logger.debug("Response [%s %s]: %s", resp.status_code, action, resp.text)
         if not resp.ok:
             raise STBError(f"HTTP {resp.status_code}: {resp.text[:200]}")
         if _is_auth_failure(resp.text):

{stb_reader-0.2.0 → stb_reader-0.2.1}/stb_reader/auth.py

@@ -1,5 +1,4 @@
 from __future__ import annotations
-import hashlib
 from typing import TYPE_CHECKING
 from .exceptions import AuthError
 
@@ -20,15 +19,7 @@ def handshake(session: "STBSession") -> None:
 
 
 def get_profile(session: "STBSession") -> None:
-    device_id = hashlib.sha256(session.serial.encode()).hexdigest()
-    device_id2 = hashlib.sha256(session.mac.encode()).hexdigest()
-    signature = hashlib.sha256((session.serial + session.mac).encode()).hexdigest()
-    data = session.get(
-        "stb", "get_profile",
-        device_id=device_id,
-        device_id2=device_id2,
-        signature=signature,
-    )
+    data = session.get("stb", "get_profile")
     token = data.get("token", "")
     if token:
         session.token = token

{stb_reader-0.2.0 → stb_reader-0.2.1}/stb_reader/cli/config.py

@@ -4,6 +4,7 @@ import click
 from stb_reader import STBClient
 
 CONFIG_PATH = Path.home() / ".stb" / "config"
+TOKEN_PATH = Path.home() / ".stb" / "token"
 
 
 def save_config(data: dict) -> None:
@@ -17,6 +18,23 @@ def load_config() -> dict:
     return json.loads(CONFIG_PATH.read_text())
 
 
+def save_token(session) -> None:
+    TOKEN_PATH.parent.mkdir(parents=True, exist_ok=True)
+    TOKEN_PATH.write_text(json.dumps({
+        "token": session.token,
+        "extra_headers": session.extra_headers,
+    }))
+
+
+def load_token() -> dict | None:
+    if not TOKEN_PATH.exists():
+        return None
+    try:
+        return json.loads(TOKEN_PATH.read_text())
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
 def get_client() -> STBClient:
     cfg = load_config()
     base_url = cfg["url"]
@@ -27,5 +45,18 @@ def get_client() -> STBClient:
         if key in cfg:
             kwargs[key] = cfg[key]
     client = STBClient(**kwargs)
-    client.authenticate()
+
+    def _auth_and_save() -> None:
+        client.authenticate()
+        save_token(client._session)
+
+    client._session.reauth_fn = _auth_and_save
+
+    cached = load_token()
+    if cached:
+        client._session.token = cached["token"]
+        client._session.extra_headers.update(cached.get("extra_headers", {}))
+    else:
+        _auth_and_save()
+
     return client

{stb_reader-0.2.0 → stb_reader-0.2.1}/stb_reader/cli/vod.py

@@ -29,7 +29,7 @@ def list_cmd(category_id: str, page: int) -> None:
         client = get_client()
         result = client.vod.get_content(category_id=category_id, page=page)
         rows = [
-            [c.id, c.name, c.year, c.genres, "yes" if c.is_series else "", c.cmd]
+            [c.id, c.name, c.year, c.genres, "yes" if c.is_series else "", "" if c.is_series else c.cmd]
             for c in result.items
         ]
         total_pages = -(-result.total // result.per_page) if result.per_page else 1

{stb_reader-0.2.0 → stb_reader-0.2.1}/stb_reader/models.py

@@ -53,6 +53,8 @@ class Season:
     id: str
     name: str
     video_id: str
+    season_number: str
+    episode_count: int
 
 
 @dataclass

{stb_reader-0.2.0 → stb_reader-0.2.1}/stb_reader/vod.py

@@ -77,6 +77,8 @@ class VODService:
                 id=str(s["id"]),
                 name=s.get("name", ""),
                 video_id=str(s.get("video_id", "")),
+                season_number=str(s.get("season_number", "")),
+                episode_count=int(s.get("season_series", 0)),
             )
             for s in raw.get("data", [])
         ]

{stb_reader-0.2.0 → stb_reader-0.2.1}/tests/conftest.py

@@ -1,6 +1,7 @@
 import pytest
 import responses as responses_lib
 from stb_reader._http import STBSession
+from stb_reader.cli import config as cli_config
 
 BASE_URL = "http://portal.test"
 MAC = "00:1A:79:00:00:01"
@@ -11,6 +12,11 @@ PORTAL_PATH = "/stalker_portal/c/portal.php"
 PORTAL_URL = f"{BASE_URL}{PORTAL_PATH}"
 
 
+@pytest.fixture(autouse=True)
+def _isolate_token_path(tmp_path, monkeypatch):
+    monkeypatch.setattr(cli_config, "TOKEN_PATH", tmp_path / ".stb" / "token")
+
+
 @pytest.fixture
 def session():
     return STBSession(BASE_URL, MAC, SERIAL, LANG, TIMEZONE)

{stb_reader-0.2.0 → stb_reader-0.2.1}/tests/test_auth.py

@@ -54,20 +54,6 @@ def test_authenticate_token_propagated_to_second_request():
     assert responses_lib.calls[1].request.headers["Authorization"] == "Bearer tok_abc"
 
 
-@responses_lib.activate
-def test_get_profile_sends_device_params():
-    import hashlib
-    from stb_reader._http import STBSession
-    serial = "TESTSERIAL"
-    session = STBSession(BASE_URL, MAC, serial, "en", "Europe/London")
-    session.token = "tok"
-    responses_lib.add(responses_lib.GET, _portal_url(), json={"js": {}})
-    get_profile(session)
-    qs = _qs(responses_lib.calls[0])
-    assert qs["device_id"][0] == hashlib.sha256(serial.encode()).hexdigest()
-    assert qs["device_id2"][0] == hashlib.sha256(MAC.encode()).hexdigest()
-    assert qs["signature"][0] == hashlib.sha256((serial + MAC).encode()).hexdigest()
-
 
 @responses_lib.activate
 def test_get_profile_applies_refreshed_token():

stb_reader-0.2.1/tests/test_cli_config.py

@@ -0,0 +1,161 @@
+import json
+import pytest
+from unittest.mock import MagicMock
+from click.testing import CliRunner
+from stb_reader.cli.main import main
+from stb_reader.cli import config as config_mod
+
+
+@pytest.fixture(autouse=True)
+def tmp_config(tmp_path, monkeypatch):
+    cfg = tmp_path / ".stb" / "config"
+    monkeypatch.setattr(config_mod, "CONFIG_PATH", cfg)
+    return cfg
+
+
+def test_save_and_load_config(tmp_config):
+    config_mod.save_config({"url": "http://portal.test", "mac": "AA:BB:CC:DD:EE:FF"})
+    data = config_mod.load_config()
+    assert data["url"] == "http://portal.test"
+    assert data["mac"] == "AA:BB:CC:DD:EE:FF"
+
+
+def test_load_config_missing_raises(tmp_config):
+    from click import ClickException
+    with pytest.raises(ClickException, match="stb init"):
+        config_mod.load_config()
+
+
+_INIT_DEFAULTS = "http://portal.test\n\nAA:BB:CC:DD:EE:FF\n\n\n\n\n"
+
+
+def test_init_command_writes_config(tmp_config):
+    result = CliRunner().invoke(main, ["init"], input=_INIT_DEFAULTS)
+    assert result.exit_code == 0
+    data = json.loads(tmp_config.read_text())
+    assert data["url"] == "http://portal.test"
+    assert data["mac"] == "AA:BB:CC:DD:EE:FF"
+    assert data["serial"] == "000000000000"
+    assert data["lang"] == "en"
+    assert data["timezone"] == "Europe/London"
+    assert data["portal_path"] == "stalker_portal/c/portal.php"
+    assert "port" not in data
+
+
+def test_init_with_port(tmp_config):
+    CliRunner().invoke(main, ["init"], input="http://portal.test\n8080\nAA:BB:CC:DD:EE:FF\n\n\n\n\n")
+    data = json.loads(tmp_config.read_text())
+    assert data["port"] == "8080"
+
+
+def test_init_custom_portal_path(tmp_config):
+    CliRunner().invoke(main, ["init"], input="http://portal.test\n\nAA:BB:CC:DD:EE:FF\n\n\n\nstalker_portal/server/load.php\n")
+    data = json.loads(tmp_config.read_text())
+    assert data["portal_path"] == "stalker_portal/server/load.php"
+
+
+def test_init_strips_trailing_slash(tmp_config):
+    CliRunner().invoke(main, ["init"], input="http://portal.test/\n\nAA:BB:CC:DD:EE:FF\n\n\n\n\n")
+    data = json.loads(tmp_config.read_text())
+    assert data["url"] == "http://portal.test"
+
+
+def test_get_client_appends_port(tmp_config, monkeypatch):
+    config_mod.save_config({"url": "http://portal.test", "port": "8080", "mac": "AA:BB:CC:DD:EE:FF"})
+    captured = {}
+
+    def fake_init(self, base_url, mac, **kwargs):
+        captured["base_url"] = base_url
+        self._session = MagicMock()
+        self._session.token = "tok"
+        self._session.extra_headers = {}
+
+    monkeypatch.setattr("stb_reader.client.STBClient.__init__", fake_init)
+    monkeypatch.setattr("stb_reader.client.STBClient.authenticate", lambda self: None)
+    config_mod.get_client()
+    assert captured["base_url"] == "http://portal.test:8080"
+
+
+# --- token persistence tests ---
+
+def test_save_and_load_token():
+    session = MagicMock()
+    session.token = "abc123"
+    session.extra_headers = {"X-Random": "xyz"}
+    config_mod.save_token(session)
+    result = config_mod.load_token()
+    assert result == {"token": "abc123", "extra_headers": {"X-Random": "xyz"}}
+
+
+def test_load_token_missing():
+    assert config_mod.load_token() is None
+
+
+def test_load_token_corrupt():
+    config_mod.TOKEN_PATH.parent.mkdir(parents=True, exist_ok=True)
+    config_mod.TOKEN_PATH.write_text("not json{{")
+    assert config_mod.load_token() is None
+
+
+def test_get_client_saves_token_on_fresh_auth(tmp_config, monkeypatch):
+    config_mod.save_config({"url": "http://portal.test", "mac": "AA:BB:CC:DD:EE:FF"})
+
+    def fake_init(self, base_url, mac, **kwargs):
+        self._session = MagicMock()
+        self._session.token = "fresh-token"
+        self._session.extra_headers = {}
+
+    monkeypatch.setattr("stb_reader.client.STBClient.__init__", fake_init)
+    monkeypatch.setattr("stb_reader.client.STBClient.authenticate", lambda self: None)
+
+    config_mod.get_client()
+
+    saved = config_mod.load_token()
+    assert saved["token"] == "fresh-token"
+
+
+def test_get_client_uses_cached_token(tmp_config, monkeypatch):
+    config_mod.save_config({"url": "http://portal.test", "mac": "AA:BB:CC:DD:EE:FF"})
+    config_mod.TOKEN_PATH.parent.mkdir(parents=True, exist_ok=True)
+    config_mod.TOKEN_PATH.write_text(json.dumps({"token": "cached-token", "extra_headers": {"X-Random": "r1"}}))
+
+    auth_called = []
+
+    def fake_init(self, base_url, mac, **kwargs):
+        self._session = MagicMock()
+        self._session.token = ""
+        self._session.extra_headers = {}
+
+    monkeypatch.setattr("stb_reader.client.STBClient.__init__", fake_init)
+    monkeypatch.setattr("stb_reader.client.STBClient.authenticate", lambda self: auth_called.append(1))
+
+    client = config_mod.get_client()
+
+    assert not auth_called
+    assert client._session.token == "cached-token"
+    assert client._session.extra_headers["X-Random"] == "r1"
+
+
+def test_get_client_reauth_updates_token(tmp_config, monkeypatch):
+    config_mod.save_config({"url": "http://portal.test", "mac": "AA:BB:CC:DD:EE:FF"})
+    config_mod.TOKEN_PATH.parent.mkdir(parents=True, exist_ok=True)
+    config_mod.TOKEN_PATH.write_text(json.dumps({"token": "old-token", "extra_headers": {}}))
+
+    def fake_init(self, base_url, mac, **kwargs):
+        self._session = MagicMock()
+        self._session.token = "old-token"
+        self._session.extra_headers = {}
+
+    def fake_authenticate(self):
+        self._session.token = "new-token"
+
+    monkeypatch.setattr("stb_reader.client.STBClient.__init__", fake_init)
+    monkeypatch.setattr("stb_reader.client.STBClient.authenticate", fake_authenticate)
+
+    client = config_mod.get_client()
+
+    # reauth_fn fires on token expiry; simulate it
+    client._session.reauth_fn()
+
+    saved = config_mod.load_token()
+    assert saved["token"] == "new-token"

{stb_reader-0.2.0 → stb_reader-0.2.1}/tests/test_vod.py

@@ -108,6 +108,31 @@ def test_get_seasons_returns_list(session):
     assert "episode_id=0" in url
 
 
+@responses_lib.activate
+def test_get_seasons_exposes_season_number_and_episode_count(session):
+    responses_lib.add(
+        responses_lib.GET, PORTAL_URL,
+        json={"js": {"data": [{"id": "25805", "name": "Season 3", "video_id": "70639",
+                                "season_number": "3", "season_series": 51}]}},
+    )
+    svc = VODService(session)
+    seasons = svc.get_seasons("50")
+    assert seasons[0].season_number == "3"
+    assert seasons[0].episode_count == 51
+
+
+@responses_lib.activate
+def test_get_seasons_defaults_when_fields_absent(session):
+    responses_lib.add(
+        responses_lib.GET, PORTAL_URL,
+        json={"js": {"data": [{"id": "1", "name": "Season 1", "video_id": "200"}]}},
+    )
+    svc = VODService(session)
+    seasons = svc.get_seasons("50")
+    assert seasons[0].season_number == ""
+    assert seasons[0].episode_count == 0
+
+
 # --- get_episodes ---
 
 @responses_lib.activate

{stb_reader-0.2.0 → stb_reader-0.2.1}/uv.lock

@@ -167,6 +167,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/db/8f/61959034484a4a7c527811f4721e75d02d653a35afb0b6054474d8185d4c/charset_normalizer-3.4.7-py3-none-any.whl", hash = "sha256:3dce51d0f5e7951f8bb4900c257dad282f49190fdbebecd4ba99bcc41fef404d", size = 61958, upload-time = "2026-04-02T09:28:37.794Z" },
 ]
 
+[[package]]
+name = "click"
+version = "8.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/23/e4/796662cd90cf80e3a363c99db2b88e0e394b988a575f60a17e16440cd011/click-8.4.0.tar.gz", hash = "sha256:638f1338fe1235c8f4e008e4a8a254fb5c5fbdcbb40ece3c9142ebb78e792973", size = 350843, upload-time = "2026-05-17T00:47:58.425Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ee/ae/8e92f8058baf87f6c7d86ee7e457668690195cc77efedb8d3797a06e3940/click-8.4.0-py3-none-any.whl", hash = "sha256:40c50b7c6c6adac2823d411041ec84f3f103f1b280d5e9ce0d7f998995832f81", size = 116147, upload-time = "2026-05-17T00:47:56.842Z" },
+]
+
 [[package]]
 name = "colorama"
 version = "0.4.6"
@@ -765,9 +777,10 @@ wheels = [
 
 [[package]]
 name = "stb-reader"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
+    { name = "click" },
     { name = "requests" },
 ]
 
@@ -782,6 +795,7 @@ test = [
 
 [package.metadata]
 requires-dist = [
+    { name = "click" },
     { name = "httpx", marker = "extra == 'test'" },
     { name = "pytest", marker = "extra == 'test'" },
     { name = "pytest-cov", marker = "extra == 'test'" },

stb_reader-0.2.0/README.md

@@ -1,105 +0,0 @@
-# stb-reader
-
-Python client library for [Ministra/Stalker](https://ministra.com/) STB portals. Retrieve live-TV channels, VOD content, series, episodes, and stream URLs with simple method calls.
-
-## Installation
-
-```bash
-pip install stb-reader
-```
-
-Requires Python 3.11+ and has a single runtime dependency: `requests`.
-
-## Quick start
-
-```python
-from stb_reader import STBClient
-
-client = STBClient(
-    base_url="http://your-portal.example.com",
-    mac="00:1A:79:XX:XX:XX",
-)
-client.authenticate()
-
-# Live TV
-genres = client.live_tv.get_genres()
-channels = client.live_tv.get_channels(genre_id="*", page=1)
-stream_url = client.live_tv.get_stream_url(channels.items[0].cmd)
-
-# VOD
-categories = client.vod.get_categories()
-content = client.vod.get_content(category_id="*", page=1)
-
-# Series
-seasons = client.vod.get_seasons(series_id="123")
-episodes = client.vod.get_episodes(series_id="123", season_id=seasons[0].id)
-stream_url = client.vod.get_stream_url_by_first_file(
-    series_id="123",
-    season_id=seasons[0].id,
-    episode_id=episodes[0].id,
-)
-```
-
-## API reference
-
-### `STBClient(base_url, mac, serial, lang, timezone, portal_path)`
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `base_url` | required | Portal base URL |
-| `mac` | required | Device MAC address |
-| `serial` | `"000000000000"` | Device serial |
-| `lang` | `"en"` | Portal language |
-| `timezone` | `"Europe/London"` | Portal timezone |
-| `portal_path` | `"stalker_portal/c/portal.php"` | Path to portal PHP endpoint |
-
-### `client.live_tv`
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `get_genres()` | `list[Genre]` | All channel genres |
-| `get_channels(genre_id, page, sort, hd, fav)` | `PagedResult[Channel]` | Paginated channel list |
-| `get_stream_url(cmd)` | `str` | Resolved stream URL for a channel `cmd` |
-| `get_stream_url_by_id(channel_id)` | `str` | Resolved stream URL by channel ID |
-
-### `client.vod`
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `get_categories()` | `list[Category]` | All VOD categories |
-| `get_content(category_id, page, sort, fav)` | `PagedResult[Content]` | Paginated VOD content |
-| `get_seasons(series_id)` | `list[Season]` | Seasons for a series |
-| `get_episodes(series_id, season_id)` | `list[Episode]` | All episodes in a season |
-| `get_episode_files(series_id, season_id, episode_id)` | `list[EpisodeFile]` | Quality variants for an episode |
-| `get_stream_url(cmd)` | `str` | Resolved stream URL for a VOD `cmd` |
-| `get_stream_url_by_content_id(content_id)` | `str` | Stream URL for a movie by ID |
-| `get_stream_url_by_first_file(series_id, season_id, episode_id)` | `str` | Stream URL for first file of an episode |
-| `get_stream_url_by_file_id(series_id, season_id, episode_id, file_id)` | `str` | Stream URL for a specific file |
-
-## Exceptions
-
-All exceptions are importable from `stb_reader`:
-
-| Exception | Raised when |
-|-----------|-------------|
-| `STBError` | Base class for all library errors |
-| `AuthError` | Authentication / token failure |
-| `StreamError` | Portal rejects a stream request |
-| `NotFoundError` | Requested item not found |
-
-## Documentation
-
-Full guides are in [`docs/guide/`](docs/guide/):
-
-- [Getting started](docs/guide/getting-started.md) — installation, configuration, first call
-- [Authentication](docs/guide/authentication.md) — token lifecycle, auto-reauth, error handling
-- [Live TV](docs/guide/live-tv.md) — genres, channels, stream URLs
-- [VOD — Movies](docs/guide/vod.md) — categories, content listing, movie streams
-- [Series](docs/guide/series.md) — seasons, episodes, quality selection
-- [Pagination](docs/guide/pagination.md) — `PagedResult`, fetch-all-pages pattern
-- [Error handling](docs/guide/error-handling.md) — all exceptions, recovery patterns
-- [API reference](docs/guide/api-reference.md) — complete method, model, and exception reference
-
-## License
-
-MIT

stb_reader-0.2.0/tests/test_cli_config.py

@@ -1,72 +0,0 @@
-import json
-import pytest
-from click.testing import CliRunner
-from stb_reader.cli.main import main
-from stb_reader.cli import config as config_mod
-
-
-@pytest.fixture(autouse=True)
-def tmp_config(tmp_path, monkeypatch):
-    cfg = tmp_path / ".stb" / "config"
-    monkeypatch.setattr(config_mod, "CONFIG_PATH", cfg)
-    return cfg
-
-
-def test_save_and_load_config(tmp_config):
-    config_mod.save_config({"url": "http://portal.test", "mac": "AA:BB:CC:DD:EE:FF"})
-    data = config_mod.load_config()
-    assert data["url"] == "http://portal.test"
-    assert data["mac"] == "AA:BB:CC:DD:EE:FF"
-
-
-def test_load_config_missing_raises(tmp_config):
-    from click import ClickException
-    with pytest.raises(ClickException, match="stb init"):
-        config_mod.load_config()
-
-
-_INIT_DEFAULTS = "http://portal.test\n\nAA:BB:CC:DD:EE:FF\n\n\n\n\n"
-
-
-def test_init_command_writes_config(tmp_config):
-    result = CliRunner().invoke(main, ["init"], input=_INIT_DEFAULTS)
-    assert result.exit_code == 0
-    data = json.loads(tmp_config.read_text())
-    assert data["url"] == "http://portal.test"
-    assert data["mac"] == "AA:BB:CC:DD:EE:FF"
-    assert data["serial"] == "000000000000"
-    assert data["lang"] == "en"
-    assert data["timezone"] == "Europe/London"
-    assert data["portal_path"] == "stalker_portal/c/portal.php"
-    assert "port" not in data
-
-
-def test_init_with_port(tmp_config):
-    CliRunner().invoke(main, ["init"], input="http://portal.test\n8080\nAA:BB:CC:DD:EE:FF\n\n\n\n\n")
-    data = json.loads(tmp_config.read_text())
-    assert data["port"] == "8080"
-
-
-def test_init_custom_portal_path(tmp_config):
-    CliRunner().invoke(main, ["init"], input="http://portal.test\n\nAA:BB:CC:DD:EE:FF\n\n\n\nstalker_portal/server/load.php\n")
-    data = json.loads(tmp_config.read_text())
-    assert data["portal_path"] == "stalker_portal/server/load.php"
-
-
-def test_init_strips_trailing_slash(tmp_config):
-    CliRunner().invoke(main, ["init"], input="http://portal.test/\n\nAA:BB:CC:DD:EE:FF\n\n\n\n\n")
-    data = json.loads(tmp_config.read_text())
-    assert data["url"] == "http://portal.test"
-
-
-def test_get_client_appends_port(tmp_config, monkeypatch):
-    config_mod.save_config({"url": "http://portal.test", "port": "8080", "mac": "AA:BB:CC:DD:EE:FF"})
-    captured = {}
-
-    def fake_init(self, base_url, mac, **kwargs):
-        captured["base_url"] = base_url
-
-    monkeypatch.setattr("stb_reader.client.STBClient.__init__", fake_init)
-    monkeypatch.setattr("stb_reader.client.STBClient.authenticate", lambda self: None)
-    config_mod.get_client()
-    assert captured["base_url"] == "http://portal.test:8080"