diff --git a/README.md b/README.md
index 16362b6..7401e24 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,8 @@ the same mount, otherwise moving turns into copy + delete.
2. **Search** – look up a title (ebooks: Hardcover, Google Books and Open
Library, audiobooks: Audible plus MusicBrainz, manga: AniList) and request
it, or add it by hand. The language filter narrows ebook and audiobook hits. For a series,
- *Ganze Serie…* requests every episode at once.
+ *Ganze Serie…* requests every part at once — audiobooks from Audible's keyword
+ crawl, ebooks from Hardcover's series listing (needs the token).
3. **Import** – scan the download folder. wordarr suggests file→request matches,
which you confirm or correct; entries can be merged, split, or turned into
requests from their folder names. Every row names its format and size, and
diff --git a/static/app.js b/static/app.js
index e053937..2508867 100644
--- a/static/app.js
+++ b/static/app.js
@@ -239,7 +239,9 @@ $("#search-form").addEventListener("submit", async (e) => {
)
.join("");
box.querySelectorAll("[data-series]").forEach((btn) =>
- btn.addEventListener("click", () => openSeriesDialog(results[btn.dataset.series]))
+ btn.addEventListener("click", () =>
+ openSeriesDialog(results[btn.dataset.series], type, language)
+ )
);
box.querySelectorAll("[data-req]").forEach((btn) =>
btn.addEventListener("click", async () => {
@@ -274,6 +276,7 @@ $("#search-form").addEventListener("submit", async (e) => {
// ---- request a whole series ----
let seriesEpisodes = [];
+let seriesType = "audiobook";
function renderSeriesList() {
const from = parseInt($("#series-from").value);
@@ -288,7 +291,9 @@ function renderSeriesList() {
let gap = "";
if (e.volume != null && previous != null && e.volume > previous + 1) {
const missing = e.volume - previous - 1;
- gap = `… ${missing} Folge${missing > 1 ? "n" : ""} nicht bei Audible gefunden (${previous + 1}–${e.volume - 1})
`;
+ const ebook = seriesType === "ebook";
+ const unit = ebook ? (missing > 1 ? "Bände" : "Band") : `Folge${missing > 1 ? "n" : ""}`;
+ gap = `… ${missing} ${unit} nicht ${ebook ? "bei Hardcover" : "bei Audible"} gefunden (${previous + 1}–${e.volume - 1})
`;
}
if (e.volume != null) previous = e.volume;
return `${gap}
@@ -314,20 +319,23 @@ function updateSeriesCount() {
btn.disabled = n === 0;
}
-async function openSeriesDialog(result) {
+async function openSeriesDialog(result, type = "audiobook", language = "") {
const dlg = $("#series-dialog");
+ seriesType = type;
+ const unit = type === "ebook" ? "Bände" : "Folgen";
$("#series-title").textContent = result.series || "Serie";
- $("#series-info").innerHTML = '— keine Library — ";
+ $("#series-library").innerHTML = libOptions(type) || "— keine Library — ";
$("#series-submit").disabled = true;
dlg.showModal();
try {
seriesEpisodes = await api(
`/api/search/series?series_id=${encodeURIComponent(result.series_id)}` +
- `&title=${encodeURIComponent(result.series || result.title)}`
+ `&title=${encodeURIComponent(result.series || result.title)}` +
+ `&media_type=${type}&language=${encodeURIComponent(language)}`
);
} catch (err) {
$("#series-info").textContent = err.message;
@@ -335,9 +343,11 @@ async function openSeriesDialog(result) {
}
const numbered = seriesEpisodes.filter((e) => e.volume != null);
$("#series-info").textContent =
- `${seriesEpisodes.length} Folgen gefunden` +
+ `${seriesEpisodes.length} ${unit} gefunden` +
(numbered.length ? ` (Nr. ${numbered[0].volume}–${numbered[numbered.length - 1].volume})` : "") +
- ". Audible hat keine Serien-Abfrage — einzelne Folgen können fehlen.";
+ (type === "ebook"
+ ? ". Bände ohne Ausgabe in der gewählten Sprache stehen mit ihrem Originaltitel da."
+ : ". Audible hat keine Serien-Abfrage — einzelne Folgen können fehlen.");
renderSeriesList();
}
@@ -356,7 +366,7 @@ $("#series-cancel").addEventListener("click", () => $("#series-dialog").close())
$("#series-submit").addEventListener("click", async () => {
const libId = $("#series-library").value;
- if (!libId) { toast("Erst eine Audiobook-Library anlegen (Tab Libraries)", true); return; }
+ if (!libId) { toast(`Erst eine ${seriesType === "ebook" ? "Ebook" : "Audiobook"}-Library anlegen (Tab Libraries)`, true); return; }
const items = seriesChecked().map((e) => ({
title: e.title, authors: e.authors, narrator: e.narrator || "",
external_id: e.external_id, year: e.year, series: e.series,
@@ -370,7 +380,7 @@ $("#series-submit").addEventListener("click", async () => {
method: "POST",
body: JSON.stringify({ library_id: parseInt(libId), items }),
});
- setLastLib("audiobook", libId);
+ setLastLib(seriesType, libId);
toast(
`${res.created.length} Anfragen angelegt` +
(res.skipped ? `, ${res.skipped} bereits vorhanden` : "")
diff --git a/tests/test_ebooks.py b/tests/test_ebooks.py
index ace9c67..cc5825a 100644
--- a/tests/test_ebooks.py
+++ b/tests/test_ebooks.py
@@ -83,6 +83,80 @@ def test_hardcover_drops_books_without_an_edition_in_that_language(monkeypatch):
assert asyncio.run(hardcover.search("hobbit", "german")) == []
+SERIES_ROWS = {
+ "name": "Die drei Fragezeichen",
+ "book_series": [
+ {"position": 1, "book": {
+ "id": 1, "title": "Super-Papagei", "release_year": 1968,
+ "contributions": [{"author": {"name": "Robert Arthur"}}],
+ "cached_image": {"url": "https://example.invalid/1.jpg"}}},
+ {"position": 2, "book": {"id": 2, "title": "Misteri Danau"}},
+ {"position": 2, "book": {"id": 3, "title": "Der Phantomsee"}},
+ {"position": 2, "book": {"id": 2, "title": "duplicate row"}},
+ {"position": 0, "book": {"id": 4, "title": "Sonderband"}},
+ ],
+}
+
+
+def series_client(monkeypatch, editions):
+ seen = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ import json
+ body = json.loads(request.content)
+ seen.append(body["variables"])
+ if "editions" in body["query"]:
+ return httpx.Response(200, json={"data": {"editions": editions}})
+ return httpx.Response(200, json={"data": {"series": [SERIES_ROWS]}})
+
+ monkeypatch.setattr(hardcover, "TOKEN", "test-token")
+ mock_client(monkeypatch, hardcover, handler)
+ return seen
+
+
+def test_hardcover_series_sorts_by_volume_and_keeps_the_first_row(monkeypatch):
+ series_client(monkeypatch, [])
+ books = asyncio.run(hardcover.series_books("10146"))
+ assert [(b.volume, b.title) for b in books] == [
+ (1, "Super-Papagei"), (2, "Misteri Danau"), (None, "Sonderband"),
+ ]
+ first = books[0]
+ assert (first.series, first.series_id, first.authors, first.media_type) == (
+ "Die drei Fragezeichen", "10146", "Robert Arthur", "ebook")
+ assert first.cover_url == "https://example.invalid/1.jpg"
+
+
+def test_hardcover_series_prefers_the_row_with_an_edition_in_the_language(monkeypatch):
+ calls = series_client(monkeypatch, [
+ {"book_id": 3, "title": "Der Phantomsee", "isbn_13": "9783440032251",
+ "release_date": "1969-01-01", "cached_image": None},
+ ])
+ books = asyncio.run(hardcover.series_books("10146", "german"))
+ assert calls[1] == {"ids": [1, 2, 3, 4], "lang": "de"}
+ second = next(b for b in books if b.volume == 2)
+ assert (second.title, second.language, second.external_id, second.year) == (
+ "Der Phantomsee", "german", "9783440032251", 1969)
+ # a volume without a German edition keeps its original row instead of vanishing
+ assert [b.title for b in books] == ["Super-Papagei", "Der Phantomsee", "Sonderband"]
+
+
+def test_hardcover_series_survives_a_broken_edition_lookup(monkeypatch):
+ def handler(request: httpx.Request) -> httpx.Response:
+ import json
+ if "editions" in json.loads(request.content)["query"]:
+ return httpx.Response(500)
+ return httpx.Response(200, json={"data": {"series": [SERIES_ROWS]}})
+
+ monkeypatch.setattr(hardcover, "TOKEN", "test-token")
+ mock_client(monkeypatch, hardcover, handler)
+ assert len(asyncio.run(hardcover.series_books("10146", "german"))) == 3
+
+
+def test_hardcover_series_needs_a_numeric_id(monkeypatch):
+ monkeypatch.setattr(hardcover, "TOKEN", "test-token")
+ assert asyncio.run(hardcover.series_books("")) == []
+
+
def test_google_books_restricts_the_language(monkeypatch):
seen = []
diff --git a/wordarr/api/search.py b/wordarr/api/search.py
index b49c9b4..bfb33b9 100644
--- a/wordarr/api/search.py
+++ b/wordarr/api/search.py
@@ -1,6 +1,6 @@
from fastapi import APIRouter, HTTPException
-from ..metadata import PROVIDERS, audible
+from ..metadata import PROVIDERS, SERIES_PROVIDERS
from ..metadata.base import MetadataResult
router = APIRouter(prefix="/api/search", tags=["search"])
@@ -18,13 +18,16 @@ async def search(media_type: str, q: str, language: str = "", fallback: bool = T
@router.get("/series", response_model=list[MetadataResult])
-async def series(series_id: str, title: str):
- """All episodes of an Audible series, sorted by episode number. Audible has
- no series endpoint, so this is a paged keyword crawl and may miss a few
- episodes - those can still be added by hand."""
+async def series(series_id: str, title: str = "", media_type: str = "audiobook",
+ language: str = ""):
+ """All parts of a series, by number. Audible has no series endpoint, so
+ audiobooks are a keyword crawl that may miss episodes; Hardcover is exact."""
+ lookup = SERIES_PROVIDERS.get(media_type)
+ if not lookup:
+ raise HTTPException(400, f"no series lookup for media_type: {media_type}")
if not series_id:
raise HTTPException(400, "series_id required")
try:
- return await audible.series_episodes(series_id, title)
+ return await lookup(series_id, title, language)
except Exception as exc:
raise HTTPException(502, f"metadata provider error: {exc}")
diff --git a/wordarr/metadata/__init__.py b/wordarr/metadata/__init__.py
index 1b4a152..153fa6d 100644
--- a/wordarr/metadata/__init__.py
+++ b/wordarr/metadata/__init__.py
@@ -85,8 +85,22 @@ async def audiobook_search(query: str, language: str = "",
return hits + [r for r in extra if (r.title.strip().lower(), r.volume) not in seen]
+async def _audiobook_series(series_id: str, title: str, language: str = ""):
+ return await audible.series_episodes(series_id, title)
+
+
+async def _ebook_series(series_id: str, title: str = "", language: str = ""):
+ return await hardcover.series_books(series_id, language)
+
+
PROVIDERS = {
"ebook": ebook_search,
"audiobook": audiobook_search,
"comic": anilist.search,
}
+
+# a media type without an entry gets no "whole series" button
+SERIES_PROVIDERS = {
+ "audiobook": _audiobook_series,
+ "ebook": _ebook_series,
+}
diff --git a/wordarr/metadata/hardcover.py b/wordarr/metadata/hardcover.py
index f8c0487..d1d5857 100644
--- a/wordarr/metadata/hardcover.py
+++ b/wordarr/metadata/hardcover.py
@@ -8,6 +8,7 @@ The GraphQL search is Typesense backed and returns its hits as untyped JSON, so
every field is read defensively. A book row describes the work, not one edition,
so when a language is requested the matching editions are fetched in a second
query and their title/ISBN/cover replace the ones of the original edition.
+Series are one query - unlike Audible, Hardcover knows them.
"""
import logging
@@ -21,6 +22,7 @@ ENDPOINT = "https://api.hardcover.app/v1/graphql"
TOKEN = os.environ.get("WORDARR_HARDCOVER_TOKEN", "").strip()
LANGUAGES = {"german": "de", "english": "en"}
RESULT_LIMIT = 10
+SERIES_LIMIT = 500 # books per series
log = logging.getLogger(__name__)
@@ -49,6 +51,25 @@ query Editions($ids: [Int!]!, $lang: String!) {
"""
+_SERIES = """
+query Series($id: Int!, $limit: Int!) {
+ series(where: {id: {_eq: $id}}) {
+ name
+ book_series(order_by: {position: asc_nulls_last}, limit: $limit) {
+ position
+ book {
+ id
+ title
+ release_year
+ cached_image
+ contributions(limit: 3) { author { name } }
+ }
+ }
+ }
+}
+"""
+
+
async def _post(client: httpx.AsyncClient, query: str, variables: dict) -> dict:
resp = await client.post(
ENDPOINT,
@@ -88,8 +109,27 @@ def _isbn(*candidates) -> str:
return ""
+def _series_of(doc: dict) -> tuple[str, str]:
+ """Name and id of the featured series; series_names[0] can be another one."""
+ featured = ((doc.get("featured_series") or {}).get("series")) or {}
+ if featured.get("name"):
+ return featured["name"], str(featured.get("id") or "")
+ names = doc.get("series_names") or []
+ ids = doc.get("series_ids") or []
+ return (names[0] if names else ""), (str(ids[0]) if ids else "")
+
+
+def _volume(position) -> int | None:
+ # position 0 means "somewhere in this series", not "episode zero"
+ try:
+ number = int(float(position))
+ except (TypeError, ValueError):
+ return None
+ return number or None
+
+
def _to_result(doc: dict, language: str) -> MetadataResult:
- series = doc.get("series_names") or []
+ series, series_id = _series_of(doc)
year = doc.get("release_year")
return MetadataResult(
media_type="ebook",
@@ -97,16 +137,18 @@ def _to_result(doc: dict, language: str) -> MetadataResult:
title=doc.get("title", ""),
authors=_authors(doc),
external_id=_isbn(doc.get("isbns")),
- year=int(year) if str(year).isdigit() else None,
+ year=int(str(year)) if str(year).isdigit() else None,
language=language,
- series=series[0] if series else "",
+ series=series,
+ series_id=series_id,
+ volume=_volume(doc.get("featured_series_position")),
cover_url=_image_url(doc.get("image")),
)
-async def _localize(client: httpx.AsyncClient, results: dict[int, MetadataResult],
- language: str) -> list[MetadataResult]:
- """Replace each hit with its edition in the wanted language, drop the rest."""
+async def _localized(client: httpx.AsyncClient, results: dict[int, MetadataResult],
+ language: str) -> dict[int, MetadataResult]:
+ """The hits that have an edition in the wanted language, swapped in."""
data = await _post(client, _EDITIONS,
{"ids": list(results), "lang": LANGUAGES[language]})
localized: dict[int, MetadataResult] = {}
@@ -118,11 +160,19 @@ async def _localize(client: httpx.AsyncClient, results: dict[int, MetadataResult
release = str(ed.get("release_date") or "")
localized[book_id] = base.model_copy(update={
"title": ed.get("title") or base.title,
- "external_id": _isbn(ed.get("isbn_13"), ed.get("isbn_10")) or base.external_id,
+ "external_id": (_isbn(ed.get("isbn_13"), ed.get("isbn_10"))
+ or base.external_id),
"year": int(release[:4]) if release[:4].isdigit() else base.year,
"language": language,
"cover_url": _image_url(ed.get("cached_image")) or base.cover_url,
})
+ return localized
+
+
+async def _localize(client: httpx.AsyncClient, results: dict[int, MetadataResult],
+ language: str) -> list[MetadataResult]:
+ """Replace each hit with its edition in the wanted language, drop the rest."""
+ localized = await _localized(client, results, language)
return [localized[book_id] for book_id in results if book_id in localized]
@@ -139,7 +189,7 @@ async def search(query: str, language: str = "",
doc = hit.get("document") or {}
book_id = doc.get("id")
try:
- book_id = int(book_id)
+ book_id = int(str(book_id))
except (TypeError, ValueError):
continue
if doc.get("title"):
@@ -152,3 +202,58 @@ async def search(query: str, language: str = "",
# without the edition lookup the hits are still worth showing
log.warning("hardcover edition lookup failed for %r: %s", query, exc)
return list(results.values())
+
+
+async def series_books(series_id: str, language: str = "") -> list[MetadataResult]:
+ """Every volume of a series, by position. A position often holds several book
+ rows (the same story as another work); the one with an edition in the wanted
+ language wins the slot, else the first. Unnumbered books go last."""
+ if not TOKEN:
+ return []
+ try:
+ numeric_id = int(str(series_id))
+ except (TypeError, ValueError):
+ return []
+
+ async with httpx.AsyncClient(timeout=30) as client:
+ data = await _post(client, _SERIES, {"id": numeric_id, "limit": SERIES_LIMIT})
+ row = (data.get("series") or [{}])[0]
+ name = row.get("name", "")
+
+ slots: dict[int, list[int]] = {} # volume -> book rows filed under it
+ loose: list[int] = []
+ books: dict[int, MetadataResult] = {}
+ for entry in row.get("book_series") or []:
+ book = entry.get("book") or {}
+ try:
+ book_id = int(str(book.get("id")))
+ except (TypeError, ValueError):
+ continue
+ if not book.get("title") or book_id in books:
+ continue
+ volume = _volume(entry.get("position"))
+ books[book_id] = _to_result(
+ {**book, "image": book.get("cached_image"),
+ "series_names": [name], "series_ids": [numeric_id],
+ "featured_series_position": volume},
+ "",
+ )
+ if volume is None:
+ loose.append(book_id)
+ else:
+ slots.setdefault(volume, []).append(book_id)
+
+ localized: dict[int, MetadataResult] = {}
+ if language in LANGUAGES and books:
+ try:
+ localized = await _localized(client, books, language)
+ except (httpx.HTTPError, RuntimeError) as exc:
+ log.warning("hardcover series editions failed for %s: %s",
+ series_id, exc)
+
+ def pick(candidates: list[int]) -> MetadataResult:
+ best = next((i for i in candidates if i in localized), candidates[0])
+ return localized.get(best) or books[best]
+
+ return ([pick(slots[volume]) for volume in sorted(slots)]
+ + [localized.get(i) or books[i] for i in loose])