From 764fa8b34cad47e28cd8f356aa4341e0c66da1f9 Mon Sep 17 00:00:00 2001
From: Jeena <hello@jeena.net>
Date: Sat, 10 Oct 2026 10:53:49 +0000
Subject: [PATCH] docs: Record verified watching and history API behavior

Live-tested the the test account account against tube.jeena.net: the watching
endpoint stores the playback position (resume possible via
userHistory=true) and populates user history; history rows carry no
lastViewedAt. Notes feed the v0.2 resume-from-server item.
---
 AGENTS.md  | 14 +++++++++-----
 BACKLOG.md | 12 ++++++++++--
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 80d2623..0068e61 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,7 +39,7 @@ State flow: `MainActivity` observes `AppViewModel.sessionState`; `NeedsSetup` re
 setup/login screen, `Ready` renders `HomeScreen`, which switches content on a
 `Destination` enum. The player pushes a video onto a state and uses a `BackHandler`.
 
-## PeerTube API notes (verified against tube.jeena.net)
+## PeerTube API notes (verified 2026-10-10 against tube.jeena.net, v8.3.1)
 
 - OAuth: `GET /api/v1/oauth-clients/local` → client_id/client_secret;
   `POST /api/v1/users/token` (form: grant_type=password) → access_token + refresh_token.
@@ -53,11 +53,15 @@ setup/login screen, `Ready` renders `HomeScreen`, which switches content on a
   - `GET /api/v1/video-channels?search=…&searchTarget=local` (local channels only)
 - Authenticated (`Bearer` header):
   - `GET /api/v1/users/me/videos` — own videos, ALL privacy levels
-  - `GET /api/v1/users/me/subscriptions/videos`
-  - `GET /api/v1/users/me/history/videos`
+  - `GET /api/v1/users/me/subscriptions/videos` and `users/me/history/videos` return
+    the standard `{ total, data: [...] }` wrapper (verified live); history items are
+    plain video objects — **`lastViewedAt` is NOT returned** (don't rely on it)
   - `GET /api/v1/accounts/{accountName}/video-channels`
-  - `POST /api/v1/videos/{shortUuid}/watching` `{ "currentTime": <seconds> }` — populates
-    server-side history. Report every ~20 s of wall-clock playback once currentTime ≥ 5 s.
+  - `POST /api/v1/videos/{shortUuid}/watching` JSON body `{ "currentTime": <seconds> }`
+    → HTTP 204 (verified). This is what populates server-side history AND the stored
+    playback position. Report every ~20 s of wall-clock playback once currentTime ≥ 5 s.
+  - Resume-from-server possible via `GET /api/v1/videos/{shortUuid}?userHistory=true`
+    → `userHistory: { currentTime, currentPercent }` (verified)
   - `GET /api/v1/videos/{shortUuid}` for playback URLs: prefer
     `streamingPlaylists[].playlistUrl` (HLS) else `files[].fileUrl`.
   - Private/internal media: attach `Authorization: Bearer` to playlist, segment and file
diff --git a/BACKLOG.md b/BACKLOG.md
index 05484e8..b8d95ef 100644
--- a/BACKLOG.md
+++ b/BACKLOG.md
@@ -19,13 +19,21 @@ Status vocabulary: `todo` · `doing` · `done`.
 - Unified "accessible videos" feed: merge public-local + own private into one paged,
   deduplicated list (v0.1 keeps them as two sidebar entries).
 - Logout / "switch account" button on the Home screen.
-- Playback polish: resume from server-recorded position, next/previous video from list,
-  auto-focus currently watched item on history screen.
+- Playback polish: resume from server-recorded position via
+  `GET videos/{shortUuid}?userHistory=true` (verified working, returns
+  `userHistory.currentTime`), next/previous video from list, focus current item in
+  history screen.
 - Thumbnails of private/internal videos may 404 — probe server behavior and add a
   fallback (generic poster) when required.
 - Verify `searchTarget=local` channel search behaves well for instances without
   federation; consider `search/video-channels` endpoint as an alternative.
 - Release build: enable `minifyEnabled` + R8 rules, decide on signing, versioning scheme.
+- Verify `searchTarget=local` channel search behaves well for instances without
+  federation; consider `search/video-channels` endpoint as an alternative.
+- (Verified 2026-10-10 via the test account account) history subscriptions + watching endpoints
+  behave as documented; upload seeding uses **flat multipart form fields** on
+  `/api/v1/videos/upload` (legacy), not a metadata JSON part — only relevant for
+  seeding test data, the app itself doesn't upload.
 - Error UX: friendlier messages (offline, instance down, wrong credentials vs. expired
   token → re-login screen), retry buttons.
 - i18n: move user-facing strings to `strings.xml`, consider German + English.