feat: nest API under /api/v1, structured error envelope, paged lists

Move every handler from /api/* to /api/v1/*. /api/* is now reserved for
future versioning.

Standardise the error response shape across the API as
{"error": {"code": "snake_case", "message": "..."}}. AppError gains a
`code()` whose top-level variants are matched exhaustively without a
wildcard — new variants are a compile error until coded. 500-class
responses always emit the fixed "internal error" string and log the
real cause via tracing only.

Lock in the list pagination envelope as {"items": [...], "page": {
"limit", "offset", "total"}} and apply it to GET /api/v1/mangas. `total`
serialises as null until feat/list-search-polish lands an indexed count.

The frontend client parses the envelope into ApiError.code with an
http_error fallback for non-JSON bodies. listMangas now returns the
paged shape; the root route consumes .items. New client.test.ts covers
envelope parsing and the fallback paths.

Lockstep version bump to 0.2.0.

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

backend/Cargo.toml

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

backend/src/api/mangas.rs

@@ -4,6 +4,7 @@ use axum::{Json, Router};
 use serde::Deserialize;
 use uuid::Uuid;
 
+use crate::api::pagination::PagedResponse;
 use crate::app::AppState;
 use crate::domain::manga::{Manga, NewManga};
 use crate::error::{AppError, AppResult};
@@ -32,13 +33,16 @@ fn default_limit() -> i64 {
 async fn list(
     State(state): State<AppState>,
     Query(params): Query<ListParams>,
-) -> AppResult<Json<Vec<Manga>>> {
+) -> AppResult<Json<PagedResponse<Manga>>> {
+    let limit = params.limit.clamp(1, 200);
+    let offset = params.offset.max(0);
     let q = repo::manga::ListQuery {
         search: params.search.filter(|s| !s.trim().is_empty()),
-        limit: params.limit.clamp(1, 200),
-        offset: params.offset.max(0),
+        limit,
+        offset,
     };
-    Ok(Json(repo::manga::list(&state.db, &q).await?))
+    let items = repo::manga::list(&state.db, &q).await?;
+    Ok(Json(PagedResponse::new(items, limit, offset)))
 }
 
 async fn get_one(

backend/src/api/mod.rs

@@ -1,6 +1,7 @@
 pub mod files;
 pub mod health;
 pub mod mangas;
+pub mod pagination;
 
 use axum::Router;
 

backend/src/api/pagination.rs

@@ -0,0 +1,30 @@
+//! Shared pagination envelope for list endpoints.
+//!
+//! `total` is `Option<i64>` and is always serialised — `null` when the
+//! handler hasn't computed it yet, a number once it has. The shape is fixed
+//! across `/mangas`, `/chapters`, `/bookmarks`, etc. so consumers can
+//! handle pagination uniformly.
+
+use serde::Serialize;
+
+#[derive(Debug, Serialize)]
+pub struct PageInfo {
+    pub limit: i64,
+    pub offset: i64,
+    pub total: Option<i64>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct PagedResponse<T> {
+    pub items: Vec<T>,
+    pub page: PageInfo,
+}
+
+impl<T> PagedResponse<T> {
+    pub fn new(items: Vec<T>, limit: i64, offset: i64) -> Self {
+        Self {
+            items,
+            page: PageInfo { limit, offset, total: None },
+        }
+    }
+}

backend/src/app.rs

@@ -30,7 +30,7 @@ pub async fn build(config: Config) -> anyhow::Result<Router> {
 /// so they can swap in a test DB pool and a `tempfile`-backed storage.
 pub fn router(state: AppState) -> Router {
     Router::new()
-        .nest("/api", crate::api::routes())
+        .nest("/api/v1", crate::api::routes())
         .with_state(state)
         .layer(TraceLayer::new_for_http())
 }

backend/src/error.rs

@@ -21,11 +21,30 @@ pub enum AppError {
 
 pub type AppResult<T> = Result<T, AppError>;
 
+impl AppError {
+    /// Stable, snake_case code that clients pattern-match on. Every top-level
+    /// variant is matched explicitly — adding a new variant without giving it
+    /// a code is a compile error, on purpose.
+    pub fn code(&self) -> &'static str {
+        match self {
+            AppError::NotFound => "not_found",
+            AppError::InvalidInput(_) => "invalid_input",
+            AppError::Database(sqlx::Error::RowNotFound) => "not_found",
+            AppError::Database(_) => "internal_error",
+            AppError::Storage(StorageError::NotFound) => "not_found",
+            AppError::Storage(StorageError::BadKey) => "bad_file_key",
+            AppError::Storage(StorageError::Io(_)) => "internal_error",
+            AppError::Other(_) => "internal_error",
+        }
+    }
+}
+
 impl IntoResponse for AppError {
     fn into_response(self) -> Response {
+        let code = self.code();
         let (status, message) = match &self {
-            AppError::NotFound => (StatusCode::NOT_FOUND, self.to_string()),
-            AppError::InvalidInput(_) => (StatusCode::BAD_REQUEST, self.to_string()),
+            AppError::NotFound => (StatusCode::NOT_FOUND, "not found".to_string()),
+            AppError::InvalidInput(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
             AppError::Database(sqlx::Error::RowNotFound) => {
                 (StatusCode::NOT_FOUND, "not found".to_string())
             }
@@ -40,6 +59,22 @@ impl IntoResponse for AppError {
                 (StatusCode::INTERNAL_SERVER_ERROR, "internal error".to_string())
             }
         };
-        (status, Json(json!({ "error": message }))).into_response()
+        let body = json!({ "error": { "code": code, "message": message } });
+        (status, Json(body)).into_response()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn codes_are_stable() {
+        assert_eq!(AppError::NotFound.code(), "not_found");
+        assert_eq!(AppError::InvalidInput("x".into()).code(), "invalid_input");
+        assert_eq!(AppError::Storage(StorageError::BadKey).code(), "bad_file_key");
+        assert_eq!(AppError::Storage(StorageError::NotFound).code(), "not_found");
+        assert_eq!(AppError::Database(sqlx::Error::RowNotFound).code(), "not_found");
+        assert_eq!(AppError::Other(anyhow::anyhow!("oops")).code(), "internal_error");
     }
 }

backend/tests/api_mangas.rs

@@ -8,29 +8,39 @@ use tower::ServiceExt;
 #[sqlx::test(migrations = "./migrations")]
 async fn list_is_empty_initially(pool: PgPool) {
     let h = common::harness(pool);
-    let resp = h.app.oneshot(common::get("/api/mangas")).await.unwrap();
+    let resp = h.app.oneshot(common::get("/api/v1/mangas")).await.unwrap();
     assert_eq!(resp.status(), StatusCode::OK);
-    assert_eq!(common::body_json(resp).await, json!([]));
+    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 create_then_list_roundtrip(pool: PgPool) {
     let h = common::harness(pool);
 
-    let created = h.app.clone().oneshot(common::post_json(
-        "/api/mangas",
-        json!({ "title": "Berserk", "author": "Kentaro Miura", "description": null }),
-    )).await.unwrap();
+    let created = h
+        .app
+        .clone()
+        .oneshot(common::post_json(
+            "/api/v1/mangas",
+            json!({ "title": "Berserk", "author": "Kentaro Miura", "description": null }),
+        ))
+        .await
+        .unwrap();
     assert_eq!(created.status(), StatusCode::OK);
     let body = common::body_json(created).await;
     assert_eq!(body["title"], "Berserk");
     assert_eq!(body["author"], "Kentaro Miura");
     assert!(body["id"].as_str().is_some());
 
-    let listed = h.app.oneshot(common::get("/api/mangas")).await.unwrap();
+    let listed = h.app.oneshot(common::get("/api/v1/mangas")).await.unwrap();
     let listed_body = common::body_json(listed).await;
-    assert_eq!(listed_body.as_array().unwrap().len(), 1);
-    assert_eq!(listed_body[0]["title"], "Berserk");
+    let items = listed_body["items"].as_array().unwrap();
+    assert_eq!(items.len(), 1);
+    assert_eq!(items[0]["title"], "Berserk");
 }
 
 #[sqlx::test(migrations = "./migrations")]
@@ -42,36 +52,78 @@ async fn search_filters_by_title_and_author(pool: PgPool) {
         ("Berserk", "Kentaro Miura"),
         ("Vinland Saga", "Makoto Yukimura"),
     ] {
-        let _ = h.app.clone().oneshot(common::post_json(
-            "/api/mangas",
-            json!({ "title": title, "author": author }),
-        )).await.unwrap();
+        let _ = h
+            .app
+            .clone()
+            .oneshot(common::post_json(
+                "/api/v1/mangas",
+                json!({ "title": title, "author": author }),
+            ))
+            .await
+            .unwrap();
     }
 
-    let resp = h.app.clone().oneshot(common::get("/api/mangas?search=miura")).await.unwrap();
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::get("/api/v1/mangas?search=miura"))
+        .await
+        .unwrap();
     let body = common::body_json(resp).await;
-    let titles: Vec<&str> = body.as_array().unwrap().iter().map(|m| m["title"].as_str().unwrap()).collect();
+    let titles: Vec<&str> = body["items"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|m| m["title"].as_str().unwrap())
+        .collect();
     assert_eq!(titles, vec!["Berserk"]);
 
-    let resp = h.app.oneshot(common::get("/api/mangas?search=saga")).await.unwrap();
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?search=saga"))
+        .await
+        .unwrap();
     let body = common::body_json(resp).await;
-    let titles: Vec<&str> = body.as_array().unwrap().iter().map(|m| m["title"].as_str().unwrap()).collect();
+    let titles: Vec<&str> = body["items"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|m| m["title"].as_str().unwrap())
+        .collect();
     assert_eq!(titles, vec!["Vinland Saga"]);
 }
 
 #[sqlx::test(migrations = "./migrations")]
-async fn create_rejects_empty_title(pool: PgPool) {
+async fn create_rejects_empty_title_with_envelope(pool: PgPool) {
     let h = common::harness(pool);
-    let resp = h.app.oneshot(common::post_json(
-        "/api/mangas",
-        json!({ "title": "   ", "author": null }),
-    )).await.unwrap();
+    let resp = h
+        .app
+        .oneshot(common::post_json(
+            "/api/v1/mangas",
+            json!({ "title": "   ", "author": null }),
+        ))
+        .await
+        .unwrap();
     assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "invalid_input");
+    let msg = body["error"]["message"].as_str().expect("message is string");
+    assert!(!msg.is_empty(), "message should be non-empty");
 }
 
 #[sqlx::test(migrations = "./migrations")]
-async fn get_unknown_id_is_404(pool: PgPool) {
+async fn get_unknown_id_is_404_with_envelope(pool: PgPool) {
     let h = common::harness(pool);
-    let resp = h.app.oneshot(common::get("/api/mangas/00000000-0000-0000-0000-000000000000")).await.unwrap();
+    let resp = h
+        .app
+        .oneshot(common::get(
+            "/api/v1/mangas/00000000-0000-0000-0000-000000000000",
+        ))
+        .await
+        .unwrap();
     assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "not_found");
+    let msg = body["error"]["message"].as_str().expect("message is string");
+    assert!(!msg.is_empty(), "message should be non-empty");
 }

backend/tests/common/mod.rs

@@ -1,3 +1,8 @@
+// Shared test helpers. Each integration test binary picks the subset it needs,
+// so dead-code lints on the unused helpers fire per-binary; suppress at the
+// module level.
+#![allow(dead_code)]
+
 use std::sync::Arc;
 
 use axum::body::Body;

backend/tests/health.rs

@@ -7,7 +7,7 @@ use tower::ServiceExt;
 #[sqlx::test(migrations = "./migrations")]
 async fn health_returns_ok(pool: PgPool) {
     let h = common::harness(pool);
-    let resp = h.app.oneshot(common::get("/api/health")).await.unwrap();
+    let resp = h.app.oneshot(common::get("/api/v1/health")).await.unwrap();
     assert_eq!(resp.status(), StatusCode::OK);
     let body = common::body_json(resp).await;
     assert_eq!(body["status"], "ok");