cottongin/NtR-soudcloud-fetcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add historical backfill with --init CLI and episode numbering

Browse Source 
Adds a --init mode that seeds the database with past shows from a given
anchor episode/date forward, batch-fetching likes from SoundCloud and
partitioning them into weekly buckets. Episode numbers are tracked in
the shows table and auto-incremented by the poller for new shows.

Includes full API documentation (docs/api.md) and updated README.

Made-with: Cursor
This commit is contained in:
cottongin
2026-03-12 02:09:15 -04:00
parent c88826ac4d
commit cb3ae403cf
14 changed files with 922 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
README.md
View File

@@ -14,16 +14,34 @@ ntr-fetcher
The API starts at `http://127.0.0.1:8000`.
## Historical Backfill
Seed the database with past shows by providing an anchor episode and its air date:
```bash
NTR_ADMIN_TOKEN=token ntr-fetcher --init --show 521 --aired 2026-01-07
```
This computes every weekly show from the anchor forward to today, batch-fetches
the corresponding likes from SoundCloud, and populates the database. Episode
numbers are assigned automatically (521, 522, ...). After backfill completes,
the normal server mode will auto-increment from the latest episode.
## API
| Endpoint | Description |
|----------|-------------|
| `GET /playlist` | Current week's playlist |
| `GET /playlist/{n}` | Track at position n |
| `GET /shows` | List all shows |
| `GET /shows/{id}` | Specific show's playlist |
| `GET /health` | Service health check |
| `POST /admin/refresh` | Trigger SoundCloud fetch (token required) |
Full documentation: [`docs/api.md`](docs/api.md)
| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/health` | GET | -- | Service health check |
| `/playlist` | GET | -- | Current week's playlist |
| `/playlist/{position}` | GET | -- | Single track by position (1-indexed) |
| `/shows` | GET | -- | List all shows (paginated) |
| `/shows/{show_id}` | GET | -- | Specific show with tracks |
| `/admin/refresh` | POST | Bearer | Trigger immediate SoundCloud fetch |
| `/admin/tracks` | POST | Bearer | Add track to current show |
| `/admin/tracks/{track_id}` | DELETE | Bearer | Remove track from current show |
| `/admin/tracks/{track_id}/position` | PUT | Bearer | Move track to new position |
## Configuration
@@ -33,14 +51,17 @@ Environment variables (prefix `NTR_`):
|----------|---------|-------------|
| `NTR_PORT` | `8000` | API port |
| `NTR_HOST` | `127.0.0.1` | Bind address |
| `NTR_DB_PATH` | `./ntr_fetcher.db` | SQLite path |
| `NTR_POLL_INTERVAL_SECONDS` | `3600` | Poll frequency |
| `NTR_ADMIN_TOKEN` | (required) | Admin bearer token |
| `NTR_SOUNDCLOUD_USER` | `nicktherat` | SoundCloud user |
| `NTR_DB_PATH` | `./ntr_fetcher.db` | SQLite database path |
| `NTR_POLL_INTERVAL_SECONDS` | `3600` | How often to check SoundCloud (seconds) |
| `NTR_ADMIN_TOKEN` | *(required)* | Bearer token for admin endpoints |
| `NTR_SOUNDCLOUD_USER` | `nicktherat` | SoundCloud username to track |
| `NTR_SHOW_DAY` | `2` | Day of week for show (0=Mon, 2=Wed) |
| `NTR_SHOW_HOUR` | `22` | Hour (Eastern Time) when the show starts |
## Development
```bash
pip install -e ".[dev]"
pytest
ruff check src/ tests/
```