stb-reader 0.1.0__tar.gz

stb_reader-0.1.0/.claude/skills/incremental-implementation/SKILL.md

@@ -0,0 +1,44 @@
+# Incremental Implementation Guide
+
+This document outlines a disciplined approach to building features in small, testable increments rather than large, monolithic changes.
+
+## Core Principle
+
+"Build in thin vertical slices — implement one piece, test it, verify it, then expand." Each increment should leave the system in a working, deployable state.
+
+## Key Workflow Phases
+
+The implementation phase follows specification, planning, and task breakdown. Work must proceed through established phase layers—completing setup before foundation work, foundation before core features—without skipping ahead to incomplete levels.
+
+## The Increment Cycle
+
+Each slice follows this pattern:
+1. Implement the smallest complete piece
+2. Run the test suite
+3. Confirm the slice works as expected
+4. Commit with a descriptive message
+5. Proceed to the next slice
+
+## Slicing Approaches
+
+**Vertical slices** deliver end-to-end functionality (database through UI). **Contract-first slicing** defines API specifications before parallel backend/frontend work. **Risk-first slicing** tackles uncertain pieces early to avoid wasted effort.
+
+## Implementation Rules
+
+**Simplicity first**: Question whether abstractions justify their complexity. Three similar code blocks beats premature generalization.
+
+**Scope discipline**: Touch only what the task requires. Don't refactor adjacent code or add unspecified features.
+
+**One thing at a time**: Each commit addresses a single logical change.
+
+**Keep it compilable**: The project must build and existing tests must pass between increments.
+
+**Feature flags**: Hide incomplete work behind toggles when merging to main.
+
+**Safe defaults**: New code should default to conservative, opt-in behavior.
+
+**Rollback-friendly**: Each increment should be independently revertable.
+
+## Critical Gate
+
+Task completion requires validating acceptance criteria explicitly—not merely passing tests, which only prove code does what it does, not what the specification requires.

stb_reader-0.1.0/.claude/skills/planning-and-task-breakdown/SKILL.md

@@ -0,0 +1,40 @@
+# Planning and Task Breakdown Guide
+
+This document outlines a systematic approach for decomposing work into manageable, verifiable tasks—essential when handling large features or unclear requirements.
+
+## Key Principles
+
+The workflow follows four sequential phases: SPECIFY → PLAN → TASKS → IMPLEMENT, with human review at each checkpoint. Planning must occur in read-only mode before any implementation begins.
+
+## When to Apply This Method
+
+Use task breakdown when:
+- You possess specifications requiring implementation units
+- Work feels too expansive to initiate
+- Multiple agents or sessions need parallelization
+- Scope communication to stakeholders is necessary
+- Implementation sequence isn't straightforward
+
+Avoid this approach for "single-file changes with obvious scope" or specs already containing defined tasks.
+
+## Critical Planning Steps
+
+**Step 0** requires identifying unresolved technical questions requiring research spikes before planning proceeds—invalid assumptions necessitate plan rewrites.
+
+**Step 2** maps dependencies bottom-up, ensuring foundations precede dependent components.
+
+**Step 3** emphasizes vertical slicing (one complete feature path) over horizontal slicing (all database, then all API, then UI).
+
+Each task requires:
+- Clear description and acceptance criteria
+- Verification procedures
+- File references
+- Scope estimation (XS through XL)
+
+## Task Sizing Standards
+
+Tasks should remain Small to Medium (1-5 files). Anything exceeding 8 files needs further decomposition. "If a task is L or larger, it should be broken into smaller tasks."
+
+## Quality Assurance
+
+Before implementation, verify every task has acceptance criteria, verification steps, correct dependency ordering, and that all specification requirements map to tasks. Flag gaps as CRITICAL, HIGH, or MEDIUM severity.

stb_reader-0.1.0/.claude/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: spec-driven-development
+
+description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.
+---
+
+## Overview
+
+Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.
+
+## When to Use
+
+- Starting a new project or feature
+- Requirements are ambiguous or incomplete
+- The change touches multiple files or modules
+- You're about to make an architectural decision
+- The task would take more than 30 minutes to implement
+
+**When NOT to use:** Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
+
+## The Gated Workflow
+
+Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.
+
+```
+SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
+   │          │        │          │
+   ▼          ▼        ▼          ▼
+ Human      Human    Human      Human
+ reviews    reviews  reviews    reviews
+```
+
+### Phase 1: Specify
+
+Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.
+
+**Surface assumptions immediately.** Before writing any spec content, list what you're assuming:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. This is a web application (not native mobile)
+2. Authentication uses session-based cookies (not JWT)
+3. The database is PostgreSQL (based on existing Prisma schema)
+4. We're targeting modern browsers only (no IE11)
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. "The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding."
+
+**Handle mid-spec ambiguity with `[NEEDS CLARIFICATION]` markers.** When a requirement is unclear but not blocking enough to stop writing, embed the marker inline and keep going. Cap at **3 markers per spec** — more than 3 means you should stop and ask the human before continuing. When presenting markers for resolution, use a table:
+
+```
+| # | Question | Options | Implication if left open |
+|---|----------|---------|--------------------------|
+| 1 | Should filtering apply server-side or client-side? | Server / Client | Drives whether the API needs filter params |
+| 2 | Is this feature gated by user role? | Yes (admin only) / No (all users) | Changes auth requirements significantly |
+```
+
+Replace all markers before the spec advances to the PLAN phase.
+
+**Write a spec document covering these six core areas:**
+
+1. **Objective** — What are we building and why? Who is the user? What does success look like?
+
+2. **Commands** — Full executable commands with flags, not just tool names.
+   ```
+   Build: npm run build
+   Test: npm test -- --coverage
+   Lint: npm run lint --fix
+   Dev: npm run dev
+   ```
+
+3. **Project Structure** — Where source code lives, where tests go, where docs belong.
+   ```
+   src/           → Application source code
+   src/components → React components (*.test.ts colocated)
+   src/lib        → Shared utilities (*.test.ts colocated)
+   e2e/           → End-to-end tests
+   docs/          → Documentation
+   ```
+   Tests live next to the code they test, not in a separate top-level folder.
+
+4. **Code Style** — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.
+
+5. **Testing Strategy** — What framework, where tests live, coverage expectations, which test levels for which concerns.
+
+6. **Boundaries** — Three-tier system:
+   - **Always do:** Run tests before commits, follow naming conventions, validate inputs
+   - **Ask first:** Database schema changes, adding dependencies, changing CI config
+   - **Never do:** Commit secrets, edit vendor directories, remove failing tests without approval
+
+**Spec template:**
+
+```markdown
+# Spec: [Project/Feature Name]
+
+## Objective
+[What we're building and why.]
+
+## User Stories
+- As a [user type], I want to [action] so that [outcome]
+
+## Functional Requirements
+- FR-1: [requirement]
+- FR-2: [requirement]
+
+## Non-Functional Requirements
+- NFR-1: [performance / security / accessibility requirement]
+
+## Out of Scope
+- [Explicit exclusions for this iteration]
+
+## Assumptions
+- [What we're treating as settled without explicit confirmation]
+
+## Tech Stack
+[Framework, language, key dependencies with versions]
+
+## Commands
+[Build, test, lint, dev — full commands]
+
+## Project Structure
+[Directory layout with descriptions]
+
+## Code Style
+[Example snippet + key conventions]
+
+## Testing Strategy
+[Framework, test locations, coverage requirements, test levels]
+
+## Boundaries
+- Always: [...]
+- Ask first: [...]
+- Never: [...]
+
+## Success Criteria
+[How we'll know this is done — specific, measurable, technology-agnostic conditions]
+
+## Open Questions
+[Anything unresolved that needs human input]
+```
+
+**Reframe instructions as success criteria.** When receiving vague requirements, translate them into concrete conditions:
+
+```
+REQUIREMENT: "Make the dashboard faster"
+
+REFRAMED SUCCESS CRITERIA:
+- Dashboard LCP < 2.5s on 4G connection
+- Initial data load completes in < 500ms
+- No layout shift during load (CLS < 0.1)
+→ Are these the right targets?
+```
+
+This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.
+
+**Success criteria must be technology-agnostic.** Describe observable user outcomes, not implementation choices:
+
+| Bad (tech-coupled) | Good (user-focused) |
+|--------------------|---------------------|
+| "Uses Redis for caching" | "Search returns in < 300ms for 95% of queries" |
+| "Migrates to PostgreSQL" | "All existing user data is preserved and queryable after migration" |
+| "Implements React Query" | "UI reflects server state within 2 seconds of a background update" |
+
+### Phase 2: Plan
+
+With the validated spec, generate a technical implementation plan:
+
+1. Identify the major components and their dependencies
+2. Determine the implementation order (what must be built first)
+3. Note risks and mitigation strategies
+4. Identify what can be built in parallel vs. what must be sequential
+5. Define verification checkpoints between phases
+
+The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."
+
+### Phase 3: Tasks
+
+Break the plan into discrete, implementable tasks:
+
+- Each task should be completable in a single focused session
+- Each task has explicit acceptance criteria
+- Each task includes a verification step (test, build, manual check)
+- Tasks are ordered by dependency, not by perceived importance
+- No task should require changing more than ~5 files
+
+**Task template:**
+```markdown
+- [ ] Task: [Description]
+  - Acceptance: [What must be true when done]
+  - Verify: [How to confirm — test command, build, manual check]
+  - Files: [Which files will be touched]
+```
+
+**Every task list must end with a documentation update task:**
+```markdown
+- [ ] Task: Update Documentation
+  - Acceptance: `AGENTS.md` updated to reflect any new commands, endpoints, models, or boundaries introduced by this feature; relevant `docs/` files updated or created to describe new behavior; no stale references remain in either file
+  - Verify: Review `AGENTS.md` and affected `docs/*.md` for accuracy
+  - Files: `AGENTS.md`, `docs/<relevant>.md`
+```
+
+### Phase 4: Implement
+
+Execute tasks one at a time following `incremental-implementation` and `test-driven-development` skills. Use `context-engineering` to load the right spec sections and source files at each step rather than flooding the agent with the entire spec. The final task of every implement phase is always to update `AGENTS.md` and relevant `docs/` files.
+
+## Keeping the Spec Alive
+
+The spec is a living document, not a one-time artifact:
+
+- **Update when decisions change** — If you discover the data model needs to change, update the spec first, then implement.
+- **Update when scope changes** — Features added or cut should be reflected in the spec.
+- **Commit the spec** — The spec belongs in version control alongside the code.
+- **Reference the spec in PRs** — Link back to the spec section that each PR implements.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "This is simple, I don't need a spec" | Simple tasks don't need *long* specs, but they still need acceptance criteria. A two-line spec is fine. |
+| "I'll write the spec after I code it" | That's documentation, not specification. The spec's value is in forcing clarity *before* code. |
+| "The spec will slow us down" | A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours. |
+| "Requirements will change anyway" | That's why the spec is a living document. An outdated spec is still better than no spec. |
+| "The user knows what they want" | Even clear requests have implicit assumptions. The spec surfaces those assumptions. |
+
+## Red Flags
+
+- Starting to write code without any written requirements
+- Asking "should I just start building?" before clarifying what "done" means
+- Implementing features not mentioned in any spec or task list
+- Making architectural decisions without documenting them
+- Skipping the spec because "it's obvious what to build"
+
+## Verification
+
+This is a quality gate — do not advance to PLAN until every item is checked.
+
+- [ ] The spec covers all six core areas
+- [ ] The human has reviewed and approved the spec
+- [ ] Success criteria are specific, testable, and technology-agnostic
+- [ ] Boundaries (Always/Ask First/Never) are defined
+- [ ] The spec is saved to a file in the repository
+- [ ] Functional requirements are numbered (FR-1, FR-2…) so tasks can reference them
+- [ ] Out of Scope section exists with at least one explicit exclusion
+- [ ] No `[NEEDS CLARIFICATION]` markers remain

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

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install test dependencies
+        run: pip install -e ".[test,server]"
+
+      - name: Run tests with coverage
+        run: python -m pytest --cov=stb_reader --cov-report=term-missing --cov-fail-under=90

stb_reader-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish

stb_reader-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+.coverage
+htmlcov/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.env

stb_reader-0.1.0/AGENTS.md

@@ -0,0 +1,100 @@
+# AGENTS.md
+
+## Build & Setup
+
+```
+Install library:    uv pip install -e .
+Install test deps:  uv pip install -e ".[test]"
+Run tests:          uv run pytest tests/ -v
+Run with coverage:  uv run pytest --cov=stb_reader tests/
+Build distribution: uv build
+Check package:      uv run twine check dist/*
+```
+
+## Project Structure
+
+```
+stb_reader/        Sole importable package
+  __init__.py      Public API: STBClient, all models, all exceptions
+  client.py        STBClient entry point
+  auth.py          handshake(), get_profile()
+  live_tv.py       ITVService — genres, channels, stream URLs
+  vod.py           VODService — categories, content, seasons, episodes, streams
+  models.py        Dataclasses: Genre, Channel, Category, Content, Season, Episode, EpisodeFile, PagedResult
+  _http.py         STBSession (requests wrapper with STB headers and auto-reauth)
+  exceptions.py    STBError, AuthError, StreamError, NotFoundError
+
+tests/             pytest suite; all HTTP mocked via `responses` library
+docs/              STB protocol reference (authentication, live-tv, vod-series)
+spec/              Spec-driven feature specs (NNN-slug/{requirements,plan,implement}.md)
+
+.github/
+  workflows/
+    publish.yml    Publishes to PyPI on v* tag push (requires PYPI_TOKEN secret)
+
+pyproject.toml     Package metadata and hatchling build config
+README.md          Installation and quick-start documentation
+LICENSE            MIT licence
+```
+
+## Public API
+
+```python
+from stb_reader import STBClient
+
+client = STBClient(base_url="http://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)
+url      = client.live_tv.get_stream_url(channels.items[0].cmd)
+
+# VOD
+cats     = client.vod.get_categories()
+content  = client.vod.get_content(category_id="*", page=1)
+seasons  = client.vod.get_seasons(series_id="123")
+episodes = client.vod.get_episodes(series_id="123", season_id=seasons[0].id)
+url      = client.vod.get_stream_url_by_first_file("123", seasons[0].id, episodes[0].id)
+```
+
+All models and exceptions are importable directly from `stb_reader`:
+`Genre`, `Channel`, `Category`, `Content`, `Season`, `Episode`, `EpisodeFile`, `PagedResult`,
+`STBError`, `AuthError`, `StreamError`, `NotFoundError`
+
+## Code Style
+
+- Python 3.11+; snake_case everywhere
+- Dataclasses for all domain models (`stb_reader/models.py`)
+- Full type hints on every function signature
+- No Pydantic, no async in `stb_reader/`
+
+## Testing
+
+- Mock all HTTP with `responses` library — never make real network calls in tests
+- Target: 90%+ coverage on `stb_reader/`
+- Run `uv run pytest tests/ -v` before every commit
+- No test file may import from `server.*`
+
+## Publishing
+
+Releases publish to PyPI automatically when a `v*` tag is pushed:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+The `PYPI_TOKEN` secret must be configured in the GitHub repository settings.
+
+## Boundaries
+
+- **Always:** typed signatures, run pytest before commits, run `uv build` to verify packaging
+- **Ask first:** new runtime dependencies, changing the public `__init__.py` API, adding new STBClient methods
+- **Never:** real HTTP calls in tests, credentials in source, async in `stb_reader/` core
+
+## Documentation
+
+- `docs/` contains protocol-level reference for the Ministra/Stalker STB API
+- Update the relevant `docs/` file when changing protocol behavior
+- Update this file (`AGENTS.md`) when adding commands, models, or boundaries

stb_reader-0.1.0/CLAUDE.md

@@ -0,0 +1,87 @@
+# Claude Instructions
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 0. Spec-Driven Development
+
+**Before implementing any feature, run all three spec skills in order.**
+
+Whenever asked to build, implement, add, or create a new feature, ALWAYS invoke these skills in sequence before writing any code:
+
+1. `/planning-and-task-breakdown` — decompose the request into clear, ordered tasks
+   → **Stop and wait for human review before continuing.**
+2. `/spec-driven-development` — write requirements and a design spec for the feature
+   → **Stop and wait for human review before continuing.**
+3. `/incremental-implementation` — implement task-by-task, verifying each step
+   → **Stop and wait for human review before continuing.**
+
+Do not proceed past any step until the human explicitly approves.
+
+### Spec File Naming & Structure
+
+- Live under `spec/` at the repo root
+- Each feature: `spec/NNN-slug/`
+- Files: `NNN-slug-{requirements,plan,implement}.md`
+- Increment NNN for each new feature (001, 002, 003…)
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

stb_reader-0.1.0/LICENSE

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