ranobelib-python-sdk 0.10.0__tar.gz → 0.12.0__tar.gz

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranobelib-python-sdk
-Version: 0.10.0
+Version: 0.12.0
 Summary: Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf
 Keywords: ranobelib,ranobe,novel,webnovel,epub,fb2,sdk
 Author: LLIJIYAPNIK

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.10.0"
+version = "0.12.0"
 description = "Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf"
 readme = "README.md"
 license = "MIT"

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.10.0"
+version = "0.12.0"
 description = "Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf"
 readme = "README.md"
 license = "MIT"

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/__init__.py

@@ -2,6 +2,7 @@
 
 from ranobelib.catalog import Catalog
 from ranobelib.exceptions import (
+    AccessBlockedError,
     AmbiguousChapter,
     AuthRequiredError,
     ChapterNotFoundError,
@@ -20,6 +21,7 @@ from ranobelib.models import (
     Country,
     Footnote,
     Genre,
+    Label,
     Title,
     Volume,
 )
@@ -27,6 +29,7 @@ from ranobelib.sdk import RanobeLib
 from ranobelib.sizing import chapter_size, volume_size
 
 __all__ = [
+    "AccessBlockedError",
     "AmbiguousChapter",
     "AuthRequiredError",
     "Catalog",
@@ -38,6 +41,7 @@ __all__ = [
     "DownloadTitleInterruptedError",
     "Footnote",
     "Genre",
+    "Label",
     "MultipleTitleTranslationsError",
     "MultipleTranslationsError",
     "RanobeLib",

ranobelib_python_sdk-0.12.0/src/ranobelib/_http.py

@@ -0,0 +1,45 @@
+"""HTTP settings shared by every client the SDK opens (not public API).
+
+Lives in its own module rather than in ``client.py`` because it isn't specific to the
+api.cdnlibs.org JSON API: the exporters' image-downloading clients (cover.cdnlibs.org,
+ranobelib.me uploads) need the same headers, and importing them from here keeps the
+exporters from depending on ``ApiClient``'s module just for a constant.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import httpx
+
+SITE_ORIGIN = "https://ranobelib.me"
+"""Origin of the ranobelib.me website, as its own pages send it."""
+
+BROWSER_HEADERS: dict[str, str] = {
+    "Origin": SITE_ORIGIN,
+    "Referer": f"{SITE_ORIGIN}/",
+    "User-Agent": (
+        "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 "
+        "(KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1"
+    ),
+}
+"""Headers a browser on ranobelib.me sends, so requests look like they come from the site.
+
+The DDoS-Guard edge in front of api.cdnlibs.org and cover.cdnlibs.org rejects requests
+without a non-empty ``Referer`` with an HTML 403 page (see docs/api-notes.md, section
+"WAF 403"). Any ``Referer`` value was enough when checked; the site's own one is sent,
+together with ``Origin`` and a real browser ``User-Agent``, so the request as a whole matches
+what the site itself sends rather than advertising ``python-httpx``.
+"""
+
+
+def browser_headers(overrides: Mapping[str, str] | None = None) -> httpx.Headers:
+    """``BROWSER_HEADERS`` with ``overrides`` merged over them.
+
+    A key in ``overrides`` replaces the default one, matched case-insensitively (``httpx``
+    headers semantics) — the same merge ``ApiClient(headers=...)`` does for API requests.
+    """
+    headers = httpx.Headers(BROWSER_HEADERS)
+    if overrides:
+        headers.update(overrides)
+    return headers

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/catalog.py

@@ -7,13 +7,14 @@ its own ``ApiClient``/``DiskCache`` rather than a method on ``RanobeLib``.
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from pathlib import Path
 from types import TracebackType
 from typing import Any, Self
 
 from ranobelib.cache import DEFAULT_CACHE_DIR, DiskCache
 from ranobelib.client import RANOBELIB_SITE_ID, ApiClient
-from ranobelib.models import CatalogPage, Country, Genre, Title
+from ranobelib.models import CatalogPage, Country, Genre, Label, Title
 
 DEFAULT_SORT = "last_chapter_at"
 """Default sort order: title's last-chapter timestamp — the closest real equivalent to
@@ -29,7 +30,7 @@ class Catalog:
     Example:
         ```python
         async with Catalog() as catalog:
-            page = await catalog.list_titles(query="dxd", genres=[34], status=1)
+            page = await catalog.list_titles(query="dxd", genres=[34], statuses=[1])
             for title in page.items:
                 print(title.name)
         ```
@@ -40,6 +41,7 @@ class Catalog:
         *,
         cache_dir: str | Path | None = None,
         cache_ttl: float | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> None:
         """Initialize the catalog client.
 
@@ -51,8 +53,10 @@ class Catalog:
             cache_ttl: Seconds after which a cached page is treated as stale and re-fetched.
                 ``None`` (the default) means cached pages never expire on their own — see
                 ``refresh=True`` on ``list_titles()`` to force one anyway.
+            headers: Extra HTTP headers merged over the SDK's defaults, same as
+                ``RanobeLib(headers=...)`` — see there.
         """
-        self._client = ApiClient()
+        self._client = ApiClient(headers=headers)
         self._cache = DiskCache(
             cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR, ttl=cache_ttl
         )
@@ -80,8 +84,10 @@ class Catalog:
         query: str | None = None,
         genres: list[int] | None = None,
         tags: list[int] | None = None,
-        status: int | None = None,
+        statuses: list[int] | None = None,
         countries: list[int] | None = None,
+        min_chapters: int | None = None,
+        max_chapters: int | None = None,
         sort: str = DEFAULT_SORT,
         refresh: bool = False,
     ) -> CatalogPage:
@@ -103,7 +109,10 @@ class Catalog:
                 against the live API, see docs/api-notes.md; not the OR some might expect
                 from tags being more numerous/specific than genres). Also not validated
                 before sending, same as ``genres``.
-            status: A single ``Title.status.id`` to filter by (e.g. ongoing vs. completed).
+            statuses: ``Title.status.id``s to filter by (e.g. ongoing, completed). A title
+                matches if its own status is *any* of these (OR, same as ``countries`` — a
+                title only has one status, see docs/api-notes.md). ``None`` or an empty list
+                applies no status filter. Ids come from ``list_statuses()``.
             countries: ``Country.id``s to filter by. A title matches if its own country is
                 *any* of these (OR, not AND like ``genres``/``tags`` — a title only has one
                 country of origin, so requiring all of them could never match past the first,
@@ -112,6 +121,11 @@ class Catalog:
                 parameter, not a ``country``/``countries[]`` one — see docs/api-notes.md for
                 why (``Country`` mirrors the API's own "type" concept, which isn't strictly
                 limited to literal countries).
+            min_chapters: Only titles with at least this many chapters (inclusive). Counts
+                the same number as ``Title.chapter_count`` (uploaded chapters). ``None``
+                (the default) applies no lower bound.
+            max_chapters: Only titles with at most this many chapters (inclusive). ``None``
+                (the default) applies no upper bound.
             sort: Sort order. Despite the name, this is sent as the API's ``sort_by``
                 parameter — an actual ``sort`` parameter exists but is silently ignored by
                 the API (see docs/api-notes.md). Known accepted values: ``"name"``,
@@ -126,8 +140,9 @@ class Catalog:
             page exists.
 
         Raises:
-            ValueError: If ``page`` is less than 1, or ``per_page`` is outside
-                ``MIN_PER_PAGE..MAX_PER_PAGE``.
+            ValueError: If ``page`` is less than 1, ``per_page`` is outside
+                ``MIN_PER_PAGE..MAX_PER_PAGE``, ``min_chapters``/``max_chapters`` is
+                negative, or ``min_chapters`` is greater than ``max_chapters``.
         """
         if page < 1:
             raise ValueError(f"page must be at least 1, got {page}.")
@@ -135,6 +150,16 @@ class Catalog:
             raise ValueError(
                 f"per_page must be between {MIN_PER_PAGE} and {MAX_PER_PAGE}, got {per_page}."
             )
+        for name, value in (("min_chapters", min_chapters), ("max_chapters", max_chapters)):
+            if value is not None and value < 0:
+                raise ValueError(f"{name} must be at least 0, got {value}.")
+        if min_chapters is not None and max_chapters is not None and min_chapters > max_chapters:
+            # The API itself silently swaps the bounds instead (see docs/api-notes.md) —
+            # raising here rather than relying on that undocumented behavior.
+            raise ValueError(
+                f"min_chapters ({min_chapters}) must not be greater than "
+                f"max_chapters ({max_chapters})."
+            )
 
         key = _cache_key(
             page=page,
@@ -142,8 +167,10 @@ class Catalog:
             query=query,
             genres=genres,
             tags=tags,
-            status=status,
+            statuses=statuses,
             countries=countries,
+            min_chapters=min_chapters,
+            max_chapters=max_chapters,
             sort=sort,
         )
         if not refresh:
@@ -157,8 +184,10 @@ class Catalog:
             query=query,
             genres=genres,
             tags=tags,
-            status=status,
+            statuses=statuses,
             countries=countries,
+            min_chapters=min_chapters,
+            max_chapters=max_chapters,
             sort=sort,
         )
         self._cache.set(key, data)
@@ -219,6 +248,33 @@ class Catalog:
         self._cache.set(key, data)
         return _build_countries(data)
 
+    async def list_statuses(self, *, refresh: bool = False) -> list[Label]:
+        """Fetch the full list of title statuses (id → label), for use as filter options
+        with ``list_titles(statuses=...)``.
+
+        Mirrors ``list_genres()``/``list_countries()``: the underlying endpoint
+        (``GET /api/constants?fields[]=status``) isn't site-scoped, so entries not tagged for
+        ranobelib.me are dropped before returning (see docs/api-notes.md). Returns the same
+        ``Label`` model as ``Title.status``, so a title's status can be compared against
+        these directly.
+
+        Args:
+            refresh: Bypass the disk cache and re-fetch from the API even if the status list
+                was already cached.
+
+        Returns:
+            Every status (``Label``: id, label) that applies to ranobelib.me.
+        """
+        key = "catalog:statuses"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return _build_statuses(cached)
+
+        data = await self._client.list_statuses()
+        self._cache.set(key, data)
+        return _build_statuses(data)
+
 
 def _cache_key(
     *,
@@ -227,16 +283,19 @@ def _cache_key(
     query: str | None,
     genres: list[int] | None,
     tags: list[int] | None,
-    status: int | None,
+    statuses: list[int] | None,
     countries: list[int] | None,
+    min_chapters: int | None,
+    max_chapters: int | None,
     sort: str,
 ) -> str:
     genres_part = ",".join(str(genre_id) for genre_id in genres or [])
     tags_part = ",".join(str(tag_id) for tag_id in tags or [])
+    statuses_part = ",".join(str(status_id) for status_id in statuses or [])
     countries_part = ",".join(str(country_id) for country_id in countries or [])
     return (
         f"catalog:{page}:{per_page}:{query or ''}:{genres_part}:{tags_part}:"
-        f"{status}:{countries_part}:{sort}"
+        f"{statuses_part}:{countries_part}:{min_chapters}:{max_chapters}:{sort}"
     )
 
 
@@ -254,3 +313,8 @@ def _build_genres(data: list[dict[str, Any]]) -> list[Genre]:
 def _build_countries(data: list[dict[str, Any]]) -> list[Country]:
     site_id = int(RANOBELIB_SITE_ID)
     return [Country.model_validate(item) for item in data if site_id in item.get("site_ids", [])]
+
+
+def _build_statuses(data: list[dict[str, Any]]) -> list[Label]:
+    site_id = int(RANOBELIB_SITE_ID)
+    return [Label.model_validate(item) for item in data if site_id in item.get("site_ids", [])]

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/client.py

@@ -4,13 +4,15 @@ from __future__ import annotations
 
 import asyncio
 import time
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Mapping
 from types import TracebackType
 from typing import Any, Self
 
 import httpx
 
+from ranobelib._http import BROWSER_HEADERS
 from ranobelib.exceptions import (
+    AccessBlockedError,
     AuthRequiredError,
     ChapterNotFoundError,
     RanobeLibError,
@@ -36,6 +38,11 @@ class ApiClient:
     Bounds concurrency with a semaphore, paces request starts with a small fixed delay, and
     retries 429/5xx responses with exponential backoff — see docs/api-notes.md for why a
     manual implementation was chosen over a dependency like ``tenacity`` for this.
+
+    Every request carries browser-like ``Origin``/``Referer``/``User-Agent`` headers on top
+    of the API-specific ``Site-Id``/``Accept``: without a non-empty ``Referer``, the
+    DDoS-Guard edge in front of the API answers every request with an HTML 403 page (see
+    docs/api-notes.md, section "WAF 403").
     """
 
     def __init__(
@@ -44,6 +51,7 @@ class ApiClient:
         base_url: str = API_BASE_URL,
         timeout: float = 15.0,
         transport: httpx.AsyncBaseTransport | None = None,
+        headers: Mapping[str, str] | None = None,
         max_concurrency: int = 5,
         request_delay: float | None = None,
         max_retries: int = 3,
@@ -57,6 +65,13 @@ class ApiClient:
             base_url: API base URL.
             timeout: Per-request timeout, in seconds.
             transport: Custom ``httpx`` transport, e.g. a mock transport for tests.
+            headers: Extra headers merged over the defaults (browser-like ``Origin``/
+                ``Referer``/``User-Agent`` plus the API's ``Site-Id``/``Accept``); a key
+                given here replaces the default one, matched case-insensitively. Meant for
+                swapping in a different ``User-Agent`` if the site's edge protection changes
+                its rules, without waiting for an SDK release. Overriding ``Site-Id`` or
+                ``Accept`` is possible but breaks the API's contract (see
+                docs/api-notes.md) — only do it knowingly.
             max_concurrency: Maximum number of requests in flight at once.
             request_delay: Minimum time, in seconds, between the start of one request and
                 the next, even under ``max_concurrency``. ``None`` (the default) uses
@@ -74,10 +89,13 @@ class ApiClient:
             timeout=timeout,
             transport=transport,
             headers={
+                **BROWSER_HEADERS,
                 "Site-Id": RANOBELIB_SITE_ID,
                 "Accept": "application/json",
             },
         )
+        if headers is not None:
+            self._http.headers.update(headers)
         self._semaphore = asyncio.Semaphore(max_concurrency)
         self._request_delay = DEFAULT_REQUEST_DELAY if request_delay is None else request_delay
         self._max_retries = max_retries
@@ -171,8 +189,10 @@ class ApiClient:
         query: str | None,
         genres: list[int] | None,
         tags: list[int] | None,
-        status: int | None,
+        statuses: list[int] | None,
         countries: list[int] | None,
+        min_chapters: int | None,
+        max_chapters: int | None,
         sort: str,
     ) -> dict[str, Any]:
         """Fetch one page of the catalog listing/search results.
@@ -191,12 +211,16 @@ class ApiClient:
                 see docs/api-notes.md), not just any one.
             tags: Tag ids to filter by. Same AND semantics as ``genres`` — a title must have
                 *all* of them, not just any one (see docs/api-notes.md).
-            status: A single ``Title.status.id`` to filter by.
+            statuses: ``Title.status.id``s to filter by. A title matches if its own status
+                is *any* of these (OR, like ``countries`` — a title only has one status, see
+                docs/api-notes.md). Sent on the wire as repeated ``status[]`` parameters.
             countries: ``Country.id``s to filter by. A title matches if its own country is
                 *any* of these (OR, not AND like ``genres``/``tags`` — a title only has one
                 country, confirmed against the live API, see docs/api-notes.md). Sent on the
                 wire as repeated ``types[]`` parameters — the API's own name for this concept
                 is "type", not "country" (see docs/api-notes.md).
+            min_chapters: Minimum chapter count, inclusive. Sent as ``chap_count_min``.
+            max_chapters: Maximum chapter count, inclusive. Sent as ``chap_count_max``.
             sort: Forwarded as the API's ``sort_by`` parameter, not ``sort`` — the API
                 silently ignores an actual ``sort`` parameter (see docs/api-notes.md); this
                 mismatch between the SDK's public keyword and the wire parameter name is
@@ -217,10 +241,14 @@ class ApiClient:
             params.append(("genres[]", str(genre_id)))
         for tag_id in tags or []:
             params.append(("tags[]", str(tag_id)))
-        if status is not None:
-            params.append(("status[]", str(status)))
+        for status_id in statuses or []:
+            params.append(("status[]", str(status_id)))
         for country_id in countries or []:
             params.append(("types[]", str(country_id)))
+        if min_chapters is not None:
+            params.append(("chap_count_min", str(min_chapters)))
+        if max_chapters is not None:
+            params.append(("chap_count_max", str(max_chapters)))
 
         response = await self._get("/manga", params=httpx.QueryParams(params))
         self._raise_for_status(
@@ -265,6 +293,23 @@ class ApiClient:
         data: list[dict[str, Any]] = response.json()["data"]["types"]
         return data
 
+    async def list_statuses(self) -> list[dict[str, Any]]:
+        """Fetch the raw title status list shared across the whole lib.social network.
+
+        Same shape and caveats as ``list_genres``: not site-scoped by any request parameter,
+        returns every status known to the network at once, each tagged with the site ids it
+        applies to via ``site_ids``.
+
+        Returns:
+            The raw ``data.status`` array from the API response, unfiltered by site.
+        """
+        response = await self._get("/constants", params=httpx.QueryParams([("fields[]", "status")]))
+        self._raise_for_status(
+            response, not_found=RanobeLibError("Unexpected 404 from status list")
+        )
+        data: list[dict[str, Any]] = response.json()["data"]["status"]
+        return data
+
     async def _get(self, url: str, *, params: Any = None) -> httpx.Response:
         """Issue a GET request, bounded by concurrency/pacing and retried on 429/5xx."""
         attempt = 0
@@ -302,6 +347,12 @@ class ApiClient:
         if response.status_code == 404:
             raise not_found
         if response.status_code == 403:
+            # The API's own 403 is JSON; the DDoS-Guard edge in front of it answers with an
+            # HTML page instead. Told apart by Content-Type, not by the page's wording, which
+            # can change (see docs/api-notes.md, section "WAF 403").
+            media_type = response.headers.get("Content-Type", "").split(";")[0].strip().lower()
+            if media_type != "application/json":
+                raise AccessBlockedError(str(response.request.url))
             raise AuthRequiredError(str(response.request.url))
         if response.status_code == 429:
             retry_after = response.headers.get("Retry-After")

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/exceptions.py

@@ -153,6 +153,34 @@ class AuthRequiredError(RanobeLibError):
         super().__init__(f"Authorization required to access: {url}")
 
 
+class AccessBlockedError(RanobeLibError):
+    """Raised when the site's edge protection rejects a request before it reaches the API.
+
+    Not an authorization problem, unlike ``AuthRequiredError``: the DDoS-Guard edge in front
+    of api.cdnlibs.org answers with an HTML 403 page (the API's own 403 is JSON) when it
+    doesn't like the request — so far, a missing or empty ``Referer`` (see
+    docs/api-notes.md, section "WAF 403"). The SDK already sends browser-like headers, so
+    seeing this means either the edge changed its rules — check for an SDK update, or send
+    what it now expects via ``headers=`` on ``RanobeLib``/``Catalog`` (or ``ApiClient``, if
+    using it directly) — or the edge is blocking the network/IP itself, which no header
+    fixes. Not retried: resending the same request gets
+    the same answer.
+
+    Attributes:
+        url: The request URL that returned 403.
+    """
+
+    def __init__(self, url: str) -> None:
+        self.url = url
+        super().__init__(
+            f"Request blocked by the site's protection (not an authorization issue): {url}. "
+            "The site may have changed which requests it accepts: check for an SDK update, "
+            "or send different headers via RanobeLib(..., headers=...) / "
+            "Catalog(headers=...). If the same URL doesn't open in a browser on this network "
+            "either, the IP itself is blocked and no header change will help."
+        )
+
+
 class RateLimitError(RanobeLibError):
     """Raised when the API responds with 429 Too Many Requests.
 

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/exporters/__init__.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import importlib
 import pkgutil
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from typing import ClassVar, Protocol, TypeVar, runtime_checkable
 
@@ -30,6 +30,7 @@ class Exporter(Protocol):
         output_path: Path,
         *,
         on_chapter: Callable[[], None] | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> Path:
         """Write ``chapters`` (in the given order) to ``output_path``.
 
@@ -45,6 +46,10 @@ class Exporter(Protocol):
                 ``RanobeLib.export()``'s progress bar (see CLAUDE.md's roadmap step 23).
                 For epub/pdf this covers the per-chapter embedding step, not the earlier
                 illustration-download step, which isn't itself progress-reported.
+            headers: Extra HTTP headers for any downloads the exporter makes (epub/pdf
+                illustrations), merged over the SDK's browser-like defaults —
+                ``RanobeLib.export()`` passes its own ``headers=`` through here. Exporters
+                that make no requests (txt, fb2) accept and ignore it.
 
         Returns:
             ``output_path``, once the file has been written.

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/exporters/epub.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 import html
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from typing import ClassVar
 
 import httpx
 from ebooklib import epub
 
+from ranobelib._http import browser_headers
 from ranobelib.exporters import register
 from ranobelib.exporters._illustrations import (
     download_images,
@@ -47,6 +48,7 @@ class EpubExporter:
         output_path: Path,
         *,
         on_chapter: Callable[[], None] | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> Path:
         """Write ``chapters`` to ``output_path`` as an EPUB file.
 
@@ -60,6 +62,8 @@ class EpubExporter:
             output_path: Where to write the ``.epub`` file.
             on_chapter: Called once per chapter embedded, if given — after illustrations
                 have already been downloaded, see the ``Exporter`` protocol's docstring.
+            headers: Extra HTTP headers for illustration downloads, merged over the
+                SDK's browser-like defaults (a given key replaces the default one).
 
         Returns:
             ``output_path``.
@@ -71,8 +75,13 @@ class EpubExporter:
         for author in title.authors:
             book.add_author(author.name)
 
+        # Browser headers: cover.cdnlibs.org's edge answers requests without a (non-empty)
+        # Referer with a 403, same as the API (see docs/api-notes.md, section "WAF 403").
         async with httpx.AsyncClient(
-            timeout=15.0, follow_redirects=True, transport=self._transport
+            timeout=15.0,
+            follow_redirects=True,
+            transport=self._transport,
+            headers=browser_headers(headers),
         ) as client:
             cover_url = pick_cover_url(title.cover)
             if cover_url is not None:

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/exporters/fb2.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import datetime
 import xml.etree.ElementTree as ET
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from html.parser import HTMLParser
 from pathlib import Path
 from typing import ClassVar
@@ -153,6 +153,7 @@ class Fb2Exporter:
         output_path: Path,
         *,
         on_chapter: Callable[[], None] | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> Path:
         """Write ``chapters`` to ``output_path`` as FB2 XML.
 
@@ -161,6 +162,8 @@ class Fb2Exporter:
             chapters: The chapters to include, in the order they should appear.
             output_path: Where to write the ``.fb2`` file.
             on_chapter: Called once per chapter written, if given.
+            headers: Accepted for the ``Exporter`` protocol and ignored — this format
+                downloads nothing (no illustrations in fb2, see CLAUDE.md).
 
         Returns:
             ``output_path``.

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/exporters/pdf.py

@@ -5,12 +5,13 @@ from __future__ import annotations
 import asyncio
 import base64
 import html
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from typing import ClassVar
 
 import httpx
 
+from ranobelib._http import browser_headers
 from ranobelib.exporters import register
 from ranobelib.exporters._illustrations import (
     download_images,
@@ -106,6 +107,7 @@ if weasyprint is not None:
             output_path: Path,
             *,
             on_chapter: Callable[[], None] | None = None,
+            headers: Mapping[str, str] | None = None,
         ) -> Path:
             """Write ``chapters`` to ``output_path`` as a PDF file.
 
@@ -116,12 +118,18 @@ if weasyprint is not None:
                 on_chapter: Called once per chapter rendered to HTML, if given — after
                     illustrations have already been downloaded, see the ``Exporter``
                     protocol's docstring.
+                headers: Extra HTTP headers for illustration downloads, merged over the
+                    SDK's browser-like defaults (a given key replaces the default one).
 
             Returns:
                 ``output_path``.
             """
+            # Browser headers for the cover CDN's edge — see the same comment in epub.py.
             async with httpx.AsyncClient(
-                timeout=15.0, follow_redirects=True, transport=self._transport
+                timeout=15.0,
+                follow_redirects=True,
+                transport=self._transport,
+                headers=browser_headers(headers),
             ) as client:
                 cover_url = pick_cover_url(title.cover)
                 cover_data_uri = None

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/exporters/txt.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from html.parser import HTMLParser
 from pathlib import Path
 from typing import ClassVar
@@ -77,6 +77,7 @@ class TxtExporter:
         output_path: Path,
         *,
         on_chapter: Callable[[], None] | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> Path:
         """Write ``chapters`` to ``output_path`` as plain text.
 
@@ -85,6 +86,8 @@ class TxtExporter:
             chapters: The chapters to include, in the order they should appear.
             output_path: Where to write the ``.txt`` file.
             on_chapter: Called once per chapter written, if given.
+            headers: Accepted for the ``Exporter`` protocol and ignored — this format
+                downloads nothing (no illustrations in txt, see CLAUDE.md).
 
         Returns:
             ``output_path``.

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/models.py

@@ -463,6 +463,11 @@ class Title(BaseModel):
     artists: list[Person] = Field(default_factory=list)
     teams: list[Team] = Field(default_factory=list)
     chapter_count: int | None = None
+    last_chapter_at: datetime | None = Field(default=None, alias="last_item_at")
+    """When the most recent chapter was published — the value the catalog's
+    ``sort="last_chapter_at"`` orders by. Only ``RanobeLib.get_info()`` fills it in: the
+    catalog listing endpoint doesn't return it (see docs/api-notes.md), so it's ``None`` on
+    ``Catalog.list_titles()`` items, and on a title with no chapters yet."""
 
     @model_validator(mode="before")
     @classmethod
@@ -581,8 +586,9 @@ class CatalogPage(BaseModel):
     """One page of catalog listing/search results, as returned by ``Catalog.list_titles()``.
 
     ``items`` reuses ``Title`` as-is — a catalog list item has every field ``Title`` requires,
-    the ones it doesn't send (``genres``, ``summary``, ``chapter_count``, ...) just come back
-    at their defaults, same as any other partially-populated ``Title`` (see docs/api-notes.md).
+    the ones it doesn't send (``genres``, ``summary``, ``chapter_count``, ``last_chapter_at``,
+    ...) just come back at their defaults, same as any other partially-populated ``Title``
+    (see docs/api-notes.md).
     """
 
     items: list[Title]

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/sdk.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from types import TracebackType
 from typing import Any, Self
@@ -48,6 +48,7 @@ _INFO_FIELDS = [
     "authors",
     "artists",
     "chap_count",
+    "last_item_at",
 ]
 
 
@@ -68,6 +69,7 @@ class RanobeLib:
         cache_dir: str | Path | None = None,
         cache_ttl: float | None = None,
         verbosity: Verbosity = False,
+        headers: Mapping[str, str] | None = None,
     ) -> None:
         """Initialize the SDK for a title.
 
@@ -85,9 +87,18 @@ class RanobeLib:
                 ``"full"``: the same progress bars, plus a line logged for every title/
                 chapter-list/chapter-content fetch, noting whether it was served from the
                 disk cache or the API.
+            headers: Extra HTTP headers merged over the SDK's defaults (browser-like
+                ``Origin``/``Referer``/``User-Agent``, see docs/api-notes.md, section "WAF
+                403") — a key given here replaces the default one, matched
+                case-insensitively. Applied to every API request and, through ``export()``,
+                to epub/pdf illustration downloads. Meant for when the site's edge protection
+                changes which requests it lets through (``AccessBlockedError``): send what it
+                now expects without waiting for an SDK release. ``None`` (the default) sends
+                the defaults as-is.
         """
         self._slug_url = parse_slug_url(url)
-        self._client = ApiClient()
+        self._headers = dict(headers) if headers is not None else None
+        self._client = ApiClient(headers=self._headers)
         self._cache = DiskCache(
             cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR, ttl=cache_ttl
         )
@@ -457,7 +468,8 @@ class RanobeLib:
             chapters: The chapters to include, in the order they should appear.
             path: Where to write the exported file.
             fmt: Export format — a key of ``ranobelib.exporters.EXPORTERS``
-                (currently: ``"txt"``, ``"fb2"``, ``"epub"``).
+                (currently: ``"txt"``, ``"fb2"``, ``"epub"``, and ``"pdf"`` where
+                WeasyPrint's native libraries are available).
 
         Raises:
             ValueError: If ``fmt`` isn't a registered export format.
@@ -468,7 +480,9 @@ class RanobeLib:
             raise ValueError(f"Unknown export format {fmt!r}. Available: {available}")
         title = await self.get_info()
         with self._reporter.progress(f"Exporting to {fmt}", len(chapters)) as advance:
-            return await exporter_cls().export(title, chapters, Path(path), on_chapter=advance)
+            return await exporter_cls().export(
+                title, chapters, Path(path), on_chapter=advance, headers=self._headers
+            )
 
     async def _build_volume(self, volume: int, raw_chapters: list[dict[str, Any]]) -> Volume:
         volume_str = str(volume)