Phase 1b — Jellyfin Connect & Sync #3

New issue

Closed

opened 2026-10-08 07:30:16 +00:00 by agent-pi · 2 comments

agent-pi commented

2026-10-08 07:30:16 +00:00

Collaborator

Xique must learn what each user has watched. Today it has accounts but no media history.

This issue connects a user's Jellyfin server (read-only) and syncs their played items into the local ledger, so recommendations have real data to work from. It covers: the media catalog keyed on provider IDs (never Jellyfin internal item IDs), encrypted per-user Jellyfin credentials obtained via AuthenticateByName, the Jellyfin client, and the delta sync job that appends to the watch ledger and mirrors ratings.

Xique must learn what each user has watched. Today it has accounts but no media history. This issue connects a user's Jellyfin server (read-only) and syncs their played items into the local ledger, so recommendations have real data to work from. It covers: the media catalog keyed on provider IDs (never Jellyfin internal item IDs), encrypted per-user Jellyfin credentials obtained via AuthenticateByName, the Jellyfin client, and the delta sync job that appends to the watch ledger and mirrors ratings.

agent-pi added this to the Phase 1 — Core milestone

2026-10-08 07:30:16 +00:00

agent-pi commented

2026-10-08 07:41:25 +00:00

Author

Collaborator

Plan of attack

Full plan: .superpowers/plans/2026-10-08-xique-02-jellyfin-movie-sync.md (local working artifact; not committed per AGENTS.md).

Scope: movies only. TV/episode tracking stays in Phase 3; the media schema carries media_type for later.

Approach. Per-user Jellyfin base URL + Fernet-encrypted access token in jellyfin_connections; token obtained once via AuthenticateByName, password discarded. A media catalog keyed on provider IDs (never Jellyfin item IDs) plus append-only watch_events and updatable ratings. The web enqueues a jellyfin_sync job; the worker does all network work.

Endpoints (verified against Jellyfin OpenAPI 12.2.0): GET /System/Info/Public, POST /Users/AuthenticateByName, GET /Items?userId=…&recursive=true&includeItemTypes=Movie&filters=IsPlayed&enableUserData=true&fields=ProviderIds,UserData,Genres,Overview&sortBy=DatePlayed.

Key files. src/xique/services/{crypto,jellyfin,sync}.py, src/xique/db/{connections,media,ledger,jobs}.py, src/xique/db/schema.py (migration 2), src/xique/worker.py, src/xique/web/routes/settings.py + template, tests alongside.

Sequence (7 tasks, each TDD with its own commit):

Fernet token encryption
Migration 2 (connections/media/ledger) + transactional migrations
Connections/media/ledger data access
Jellyfin client (validate, authenticate, played movies)
Movie delta sync service
Worker hardening + jellyfin_sync dispatch
Jellyfin connect settings route + UI

Issue #7 hardening folded in here: transactional migrations (task 2); jobs.status index, complete/fail status guards, stale-job recovery, poll-interval Setting, bounded worker cycle (task 6). Deferred to a follow-up small PR in this phase: login throttling, session cookie Secure, logout CSRF shape, remaining auth coverage gaps.

Branch: feat/issue-3-phase-1b-jellyfin-movie-sync

PR: opened via curl once work is complete, targeting main, body Closes #3.

## Plan of attack Full plan: `.superpowers/plans/2026-10-08-xique-02-jellyfin-movie-sync.md` (local working artifact; not committed per AGENTS.md). **Scope: movies only.** TV/episode tracking stays in Phase 3; the `media` schema carries `media_type` for later. **Approach.** Per-user Jellyfin base URL + Fernet-encrypted access token in `jellyfin_connections`; token obtained once via `AuthenticateByName`, password discarded. A `media` catalog keyed on provider IDs (never Jellyfin item IDs) plus append-only `watch_events` and updatable `ratings`. The web enqueues a `jellyfin_sync` job; the worker does all network work. **Endpoints (verified against Jellyfin OpenAPI 12.2.0):** `GET /System/Info/Public`, `POST /Users/AuthenticateByName`, `GET /Items?userId=…&recursive=true&includeItemTypes=Movie&filters=IsPlayed&enableUserData=true&fields=ProviderIds,UserData,Genres,Overview&sortBy=DatePlayed`. **Key files.** `src/xique/services/{crypto,jellyfin,sync}.py`, `src/xique/db/{connections,media,ledger,jobs}.py`, `src/xique/db/schema.py` (migration 2), `src/xique/worker.py`, `src/xique/web/routes/settings.py` + template, tests alongside. **Sequence (7 tasks, each TDD with its own commit):** 1. Fernet token encryption 2. Migration 2 (connections/media/ledger) + transactional migrations 3. Connections/media/ledger data access 4. Jellyfin client (validate, authenticate, played movies) 5. Movie delta sync service 6. Worker hardening + `jellyfin_sync` dispatch 7. Jellyfin connect settings route + UI **Issue #7 hardening folded in here:** transactional migrations (task 2); `jobs.status` index, complete/fail status guards, stale-job recovery, poll-interval Setting, bounded worker cycle (task 6). Deferred to a follow-up small PR in this phase: login throttling, session cookie `Secure`, logout CSRF shape, remaining auth coverage gaps. **Branch:** `feat/issue-3-phase-1b-jellyfin-movie-sync` **PR:** opened via curl once work is complete, targeting `main`, body `Closes #3`.

agent-pi referenced this issue from a pull request that will close it,

2026-10-08 09:45:09 +00:00

Phase 1b: Jellyfin connect and movie sync #8

agent-pi commented

2026-10-08 20:16:07 +00:00

Author

Collaborator

Merged in PR #8 (merge commit 135d3bd). Phase 1b delivered: Jellyfin connect with Fernet-encrypted tokens, migration 2 (media/ledger/connections), movie delta sync, worker hardening (status guards, stale-job recovery, bounded cycle, poll-interval setting), transactional migrations, and the zero-JS settings UI. CI green.

Merged in PR #8 (merge commit 135d3bd). Phase 1b delivered: Jellyfin connect with Fernet-encrypted tokens, migration 2 (media/ledger/connections), movie delta sync, worker hardening (status guards, stale-job recovery, bounded cycle, poll-interval setting), transactional migrations, and the zero-JS settings UI. CI green.

agent-pi closed this issue

2026-10-08 20:16:08 +00:00