feat(api): series, season and episode endpoints #81

2026-08-22T22:52:42+01:00

naps62-yolo commented

2026-08-22 22:52:42 +01:00

Implements the API half of #39. The UI half is left out — see below.

Adds the series equivalents of the movie endpoints, plus season and
episode granularity:

/api/series CRUD, each response carrying a status derived from its
episodes (§4.2) rather than a stored column.
/api/series/{id}/seasons — read, and create the season a metadata
refresh reveals. Creation runs arr_core::tracking::apply_auto_track
instead of taking wanted from the request, so the §4.1 rule stays in
one place.
PATCH on a season sets tracked and wanted independently:
tracked is the rule for episodes not yet revealed, wanted is the
one-click season grab written onto the episodes already there.
PATCH /api/episodes/{id} sets the only intent the aggregate carries.
/api/episodes/{id}/search, /releases and /releases/{id}/grab,
plus owner tags on series.
GET /api/releases now takes movie_id or episode_id; passing
both or neither is a 422.

Two things worth knowing:

arr-db's MoviePolicy is now TitlePolicy, with MoviePolicy kept as
an alias so arr-daemon is untouched. Episodes needed the same loader
and the old name had become a lie.

The series table has no TVDB ID, so an episode search cannot use
t=tvsearch&tvdbid=; tv_request falls back to a text search carrying
the SxxEyy tag. That is the documented fallback (§6.1), but ID search
stays unavailable until TV metadata refresh lands and can populate one.

The UI is not in this PR. The issue says the UI reuses the phase 5
components — buckets, chips, derived status. Those are #31, #32 and #33,
all still open, so there is nothing to reuse yet and building them here
would be implementing three other issues inline. Series views should
follow once they land.

Verification

just ci green locally: fmt, clippy -D warnings, machete, 208 tests,
biome and tsc.

New tests cover auto_track deciding whether a revealed season arrives
wanted, season versus single-episode intent, the derived status changing
as an episode is imported, blocked stopping episode search, grab scoping
to the episode's own releases, owner filtering, cascade on delete, and
the episode manual search reaching the indexer as q=Bluey S01E02.

Implements the API half of #39. The UI half is left out — see below. Adds the series equivalents of the movie endpoints, plus season and episode granularity: - `/api/series` CRUD, each response carrying a status derived from its episodes (§4.2) rather than a stored column. - `/api/series/{id}/seasons` — read, and create the season a metadata refresh reveals. Creation runs `arr_core::tracking::apply_auto_track` instead of taking `wanted` from the request, so the §4.1 rule stays in one place. - `PATCH` on a season sets `tracked` and `wanted` independently: `tracked` is the rule for episodes not yet revealed, `wanted` is the one-click season grab written onto the episodes already there. - `PATCH /api/episodes/{id}` sets the only intent the aggregate carries. - `/api/episodes/{id}/search`, `/releases` and `/releases/{id}/grab`, plus owner tags on series. - `GET /api/releases` now takes `movie_id` **or** `episode_id`; passing both or neither is a 422. Two things worth knowing: `arr-db`'s `MoviePolicy` is now `TitlePolicy`, with `MoviePolicy` kept as an alias so `arr-daemon` is untouched. Episodes needed the same loader and the old name had become a lie. The series table has no TVDB ID, so an episode search cannot use `t=tvsearch&tvdbid=`; `tv_request` falls back to a text search carrying the `SxxEyy` tag. That is the documented fallback (§6.1), but ID search stays unavailable until TV metadata refresh lands and can populate one. **The UI is not in this PR.** The issue says the UI reuses the phase 5 components — buckets, chips, derived status. Those are #31, #32 and #33, all still open, so there is nothing to reuse yet and building them here would be implementing three other issues inline. Series views should follow once they land. <details> <summary>Verification</summary> `just ci` green locally: fmt, clippy `-D warnings`, machete, 208 tests, biome and tsc. New tests cover auto_track deciding whether a revealed season arrives wanted, season versus single-episode intent, the derived status changing as an episode is imported, blocked stopping episode search, grab scoping to the episode's own releases, owner filtering, cascade on delete, and the episode manual search reaching the indexer as `q=Bluey S01E02`. </details>

naps62-yolo added 1 commit 2026-08-22 22:52:43 +01:00

feat(api): series, season and episode endpoints

ci / web (pull_request) Successful in 29s

Details

ci / rust (pull_request) Successful in 1m14s

Details

e2e / e2e (pull_request) Successful in 1m15s

Details

4cd0298dc1

Series CRUD, seasons with their episodes, and the manual actions the TV
side needs: auto_track on the series, tracked on the season, wanted on
the episode, per-episode search and grab.

Two design points drive the shape. Intent lives at the leaf (§4.1), so
`wanted` is written on episodes even when a season is marked in one
click, and a manual action names an episode even when a season pack
satisfies it. Status is derived, never stored (§4.2), so every series
the API returns carries one computed from its episodes at request time
rather than a column that drifts.

New season creation runs arr-core's `apply_auto_track` rather than
taking `wanted` from the request, so the rule stays in one place.

`GET /api/releases` now takes `movie_id` or `episode_id`. The series
carries no TVDB ID, so the TV branch falls back to a text search built
from the title and the SxxEyy tag.

Refs #39

naps62-yolo referenced this pull request

2026-08-22 22:53:04 +01:00

Series API and UI #39

naps62-yolo reviewed 2026-08-22 22:54:51 +01:00

crates/arr-api/src/series.rs

						
				@@ -0,0 +613,4 @@

				    apply_auto_track(&core_series(&series), &mut revealed);

				    let [revealed] = revealed;

				    let season_id = sqlx::query!(

naps62-yolo commented

2026-08-22 22:54:51 +01:00

Creating the season and its episodes is not atomic. Duplicate episode numbers insert the season and earlier episodes before the unique constraint returns 500, so a retry cannot create the intended season. Validate duplicates before writing or use a transaction.

Creating the season and its episodes is not atomic. Duplicate episode numbers insert the season and earlier episodes before the unique constraint returns 500, so a retry cannot create the intended season. Validate duplicates before writing or use a transaction.

naps62-yolo marked this conversation as resolved

naps62-yolo added 1 commit 2026-08-22 22:56:43 +01:00

fix(api): make season creation atomic

ci / web (pull_request) Successful in 41s

Details

ci / rust (pull_request) Successful in 1m47s

Details

e2e / e2e (pull_request) Successful in 1m45s

Details

2e14e0b19c

A duplicate episode number inserted the season and the earlier episodes
before the unique constraint fired, so the retry that fixed the request
collided with the half-written season instead.

Duplicates are now a 422 before anything is written, and the inserts run
in one transaction.

naps62-yolo reviewed 2026-08-22 22:56:49 +01:00

crates/arr-api/src/series.rs

naps62-yolo commented

2026-08-22 22:56:49 +01:00

Fixed in 2e14e0b. Duplicate episode numbers are now a 422 checked before
anything is written, and the season plus its episodes insert inside one
transaction, so a rejected request leaves the season number free for the
retry.

Test covers it: the duplicate body is rejected, seasons is still empty
afterwards, and the corrected retry succeeds.

Fixed in 2e14e0b. Duplicate episode numbers are now a 422 checked before anything is written, and the season plus its episodes insert inside one transaction, so a rejected request leaves the season number free for the retry. Test covers it: the duplicate body is rejected, `seasons` is still empty afterwards, and the corrected retry succeeds.