feat: list + get chapters under /api/v1/mangas/{id}/chapters

Both endpoints are public reads — anyone browsing can see a manga's
table of contents and chapter metadata. Uploads land in feat/uploads.

- GET /api/v1/mangas/{id}/chapters returns the paged envelope
  ({items, page}) ordered by chapter number ASC. Surfaces 404 if the
  parent manga doesn't exist so an empty result can't be mistaken for
  "no chapters yet" on a real manga.
- GET /api/v1/mangas/{id}/chapters/{number} returns a single chapter,
  404 if either manga or chapter is missing.

repo::chapter exposes list_for_manga, find_by_manga_and_number, and
create. create translates the (manga_id, number) unique violation into
AppError::Conflict so the upload handler can later return a clean 409.

Frontend lib/api/chapters.ts mirrors the shape with listChapters and
getChapter; Vitest asserts the URL shape, paged response handling, and
404 envelope propagation.

Lockstep version bump to 0.4.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/Cargo.lock

@@ -994,7 +994,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "mangalord"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "argon2",

backend/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mangalord"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
 
 [lib]

backend/src/api/chapters.rs

@@ -0,0 +1,59 @@
+//! Chapter list + get. Reads are public — anyone can browse a manga's
+//! table of contents and individual chapter metadata. Uploads land in
+//! feat/uploads under POST /api/v1/mangas/{id}/chapters.
+
+use axum::extract::{Path, Query, State};
+use axum::routing::get;
+use axum::{Json, Router};
+use serde::Deserialize;
+use uuid::Uuid;
+
+use crate::api::pagination::PagedResponse;
+use crate::app::AppState;
+use crate::domain::Chapter;
+use crate::error::AppResult;
+use crate::repo;
+
+pub fn routes() -> Router<AppState> {
+    Router::new()
+        .route("/mangas/:manga_id/chapters", get(list))
+        .route("/mangas/:manga_id/chapters/:number", get(get_one))
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ListParams {
+    #[serde(default = "default_limit")]
+    pub limit: i64,
+    #[serde(default)]
+    pub offset: i64,
+}
+
+fn default_limit() -> i64 {
+    50
+}
+
+async fn list(
+    State(state): State<AppState>,
+    Path(manga_id): Path<Uuid>,
+    Query(params): Query<ListParams>,
+) -> AppResult<Json<PagedResponse<Chapter>>> {
+    // Surface 404 when the parent manga doesn't exist so an empty result
+    // can't be mistaken for "no chapters yet" on a real manga.
+    repo::manga::get(&state.db, manga_id).await?;
+
+    let limit = params.limit.clamp(1, 200);
+    let offset = params.offset.max(0);
+    let items = repo::chapter::list_for_manga(&state.db, manga_id, limit, offset).await?;
+    Ok(Json(PagedResponse::new(items, limit, offset)))
+}
+
+async fn get_one(
+    State(state): State<AppState>,
+    Path((manga_id, number)): Path<(Uuid, i32)>,
+) -> AppResult<Json<Chapter>> {
+    repo::manga::get(&state.db, manga_id).await?;
+    let chapter = repo::chapter::find_by_manga_and_number(&state.db, manga_id, number)
+        .await?
+        .ok_or(crate::error::AppError::NotFound)?;
+    Ok(Json(chapter))
+}

backend/src/api/mod.rs

@@ -1,4 +1,5 @@
 pub mod auth;
+pub mod chapters;
 pub mod files;
 pub mod health;
 pub mod mangas;
@@ -12,6 +13,7 @@ pub fn routes() -> Router<AppState> {
     Router::new()
         .merge(health::routes())
         .merge(mangas::routes())
+        .merge(chapters::routes())
         .merge(files::routes())
         .merge(auth::routes())
 }

backend/src/repo/chapter.rs

@@ -0,0 +1,88 @@
+//! Chapter persistence.
+
+use sqlx::PgPool;
+use uuid::Uuid;
+
+use crate::domain::Chapter;
+use crate::error::AppResult;
+
+pub async fn list_for_manga(
+    pool: &PgPool,
+    manga_id: Uuid,
+    limit: i64,
+    offset: i64,
+) -> AppResult<Vec<Chapter>> {
+    let rows = sqlx::query_as::<_, Chapter>(
+        r#"
+        SELECT id, manga_id, number, title, page_count, created_at
+        FROM chapters
+        WHERE manga_id = $1
+        ORDER BY number ASC
+        LIMIT $2 OFFSET $3
+        "#,
+    )
+    .bind(manga_id)
+    .bind(limit)
+    .bind(offset)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows)
+}
+
+pub async fn find_by_manga_and_number(
+    pool: &PgPool,
+    manga_id: Uuid,
+    number: i32,
+) -> AppResult<Option<Chapter>> {
+    let row = sqlx::query_as::<_, Chapter>(
+        r#"
+        SELECT id, manga_id, number, title, page_count, created_at
+        FROM chapters
+        WHERE manga_id = $1 AND number = $2
+        "#,
+    )
+    .bind(manga_id)
+    .bind(number)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row)
+}
+
+/// Inserts a chapter. Used by tests today and by the upload handler in
+/// feat/uploads. Returns `AppError::Conflict` on the (manga_id, number)
+/// unique violation so handlers can surface a clean 409.
+pub async fn create(
+    pool: &PgPool,
+    manga_id: Uuid,
+    number: i32,
+    title: Option<&str>,
+) -> AppResult<Chapter> {
+    let result = sqlx::query_as::<_, Chapter>(
+        r#"
+        INSERT INTO chapters (manga_id, number, title)
+        VALUES ($1, $2, $3)
+        RETURNING id, manga_id, number, title, page_count, created_at
+        "#,
+    )
+    .bind(manga_id)
+    .bind(number)
+    .bind(title)
+    .fetch_one(pool)
+    .await;
+
+    match result {
+        Ok(c) => Ok(c),
+        Err(e) if is_unique_violation(&e) => Err(crate::error::AppError::Conflict(format!(
+            "chapter {number} already exists for this manga"
+        ))),
+        Err(e) => Err(crate::error::AppError::Database(e)),
+    }
+}
+
+fn is_unique_violation(err: &sqlx::Error) -> bool {
+    if let sqlx::Error::Database(db_err) = err {
+        db_err.code().as_deref() == Some("23505")
+    } else {
+        false
+    }
+}

backend/src/repo/mod.rs

@@ -1,4 +1,5 @@
 pub mod api_token;
+pub mod chapter;
 pub mod manga;
 pub mod session;
 pub mod user;

backend/tests/api_chapters.rs

@@ -0,0 +1,144 @@
+mod common;
+
+use axum::http::StatusCode;
+use serde_json::json;
+use sqlx::PgPool;
+use tower::ServiceExt;
+use uuid::Uuid;
+
+/// Create a manga via the API (which requires auth) and return its id +
+/// the session cookie of the user who owns it.
+async fn seed_manga(h: &common::Harness, cookie: &str, title: &str) -> Uuid {
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::post_json_with_cookie(
+            "/api/v1/mangas",
+            json!({ "title": title }),
+            cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    Uuid::parse_str(body["id"].as_str().unwrap()).unwrap()
+}
+
+/// Insert a chapter directly via the repo (the upload handler that does
+/// this from HTTP lands in feat/uploads).
+async fn seed_chapter(pool: &PgPool, manga_id: Uuid, number: i32, title: Option<&str>) {
+    mangalord::repo::chapter::create(pool, manga_id, number, title)
+        .await
+        .unwrap();
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_chapters_is_empty_initially(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = seed_manga(&h, &cookie, "Berserk").await;
+
+    let resp = h
+        .app
+        .oneshot(common::get(&format!("/api/v1/mangas/{manga_id}/chapters")))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["items"], json!([]));
+    assert_eq!(body["page"]["limit"], 50);
+    assert_eq!(body["page"]["offset"], 0);
+    assert!(body["page"]["total"].is_null());
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_chapters_returned_in_number_order(pool: PgPool) {
+    let h = common::harness(pool.clone());
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = seed_manga(&h, &cookie, "Berserk").await;
+
+    seed_chapter(&pool, manga_id, 3, Some("The Black Swordsman")).await;
+    seed_chapter(&pool, manga_id, 1, Some("The Brand")).await;
+    seed_chapter(&pool, manga_id, 2, None).await;
+
+    let resp = h
+        .app
+        .oneshot(common::get(&format!("/api/v1/mangas/{manga_id}/chapters")))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    let numbers: Vec<i64> = body["items"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|c| c["number"].as_i64().unwrap())
+        .collect();
+    assert_eq!(numbers, vec![1, 2, 3]);
+    assert_eq!(body["items"][1]["title"], serde_json::Value::Null);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_chapters_returns_404_for_unknown_manga(pool: PgPool) {
+    let h = common::harness(pool);
+    let unknown = Uuid::nil();
+    let resp = h
+        .app
+        .oneshot(common::get(&format!("/api/v1/mangas/{unknown}/chapters")))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "not_found");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn get_chapter_by_number(pool: PgPool) {
+    let h = common::harness(pool.clone());
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = seed_manga(&h, &cookie, "Berserk").await;
+    seed_chapter(&pool, manga_id, 1, Some("The Brand")).await;
+
+    let resp = h
+        .app
+        .oneshot(common::get(&format!(
+            "/api/v1/mangas/{manga_id}/chapters/1"
+        )))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["number"], 1);
+    assert_eq!(body["title"], "The Brand");
+    assert_eq!(body["page_count"], 0);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn get_chapter_unknown_number_is_404(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = seed_manga(&h, &cookie, "Berserk").await;
+
+    let resp = h
+        .app
+        .oneshot(common::get(&format!(
+            "/api/v1/mangas/{manga_id}/chapters/99"
+        )))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "not_found");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn get_chapter_unknown_manga_is_404(pool: PgPool) {
+    let h = common::harness(pool);
+    let unknown = Uuid::nil();
+    let resp = h
+        .app
+        .oneshot(common::get(&format!("/api/v1/mangas/{unknown}/chapters/1")))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}