feat(thumbnails): add cover image support with rero-invenio-thumbnails

* Add rero-invenio-thumbnails dependency for book cover retrieval
* Configure RERO_INVENIO_THUMBNAILS_FILES_DIR in config.py
* Fix Flask endpoint name: api_thumbnails.get_thumbnail
* Fix URL parameter bug: weight → width

API Endpoints:
* Add /cover/<isbn> API endpoint for cover image retrieval
  - Supports ISBN-10 and ISBN-13 formats
  - Accepts cached, width, and height query parameters
  - Returns JSON with thumbnail URL and metadata

Template Filters:
* Add get_cover_art template filter for Jinja2 templates
  - Supports electronicLocator coverImage URLs
  - Falls back to ISBN-based thumbnail lookup
  - Handles multiple ISBNs in sorted order

CLI Commands:
* Add add_cover_urls command to bulk process documents
  - Supports --commit flag for database persistence
  - Supports --cached/--no-cached for thumbnail caching
  - Supports --scroll for Elasticsearch timeout configuration
  - Supports --pids option for processing specific documents
  - Excludes documents already having cover images
  - Sorts PIDs numerically for consistent processing

Document Extensions:
* Add AddCoverUrlExtension for automatic cover URL injection
  - Automatically adds cover URLs on document create/commit
  - Checks for existing cover images to avoid duplicates
  - Configurable caching support

Tasks:
* Add add_cover_urls shared task for batch processing
  - Used by CLI command and can be called programmatically
  - Supports filtering by PIDs or processing all documents
  - Updates timestamp tracking for monitoring

Co-Authored-by: Peter Weber <[email protected]>

Author: rerowep

data/thumbnails/9782607000423.jpg

@@ -52,6 +52,7 @@ dependencies = [
     ## RERO specific python modules
     "rero-invenio-base (>=0.3.0)",
     "rero-invenio-files (>=1.0.0,<2.0.0)",
+    "rero-invenio-thumbnails @ git+https://github.com/rero/rero-invenio-thumbnails.git",
     "flask-wiki (>=1.0.0)",
     ## RERO ILS specific python modules
     "PyYAML (>=5.3.1)",

pyproject.toml

@@ -3499,6 +3499,9 @@ def _(x):
 #: page is displayed on RERO-ILS frontpage.
 RERO_ILS_UI_GIT_HASH = None
 
+#: Thumbnails directory configuration
+RERO_INVENIO_THUMBNAILS_FILES_DIR = "./data/thumbnails"
+
 #: RERO_ILS MEF base url could be changed.
 RERO_ILS_MEF_REF_BASE_URL = os.environ.get("RERO_ILS_MEF_REF_BASE_URL", "mef.rero.ch")
 #: RERO_ILS MEF specific configurations.
@@ -3536,8 +3539,6 @@ def _(x):
 
 RERO_ILS_HELP_PAGE = "https://github.com/rero/rero-ils/wiki/Public-demo-help"
 
-#: Cover service
-RERO_ILS_THUMBNAIL_SERVICE_URL = "https://services.test.rero.ch/cover"
 
 #: Entities
 RERO_ILS_AGENTS_SOURCES = ["idref", "gnd", "rero"]

rero_ils/config.py

@@ -38,7 +38,6 @@
 import yaml
 from celery import current_app as current_celery
 from dojson.contrib.marc21.utils import create_record
-from elasticsearch_dsl.query import Q
 from flask import current_app
 from flask.cli import with_appcontext
 from invenio_db import db
@@ -55,9 +54,9 @@
 from werkzeug.local import LocalProxy
 from werkzeug.security import gen_salt
 
-from rero_ils.modules.documents.api import Document, DocumentsSearch
+from rero_ils.modules.documents.api import Document
 from rero_ils.modules.documents.dojson.contrib.marc21tojson.rero import marc21
-from rero_ils.modules.documents.views import get_cover_art
+from rero_ils.modules.documents.tasks import add_cover_urls as task_add_cover_urls
 from rero_ils.modules.entities.remote_entities.api import RemoteEntity
 from rero_ils.modules.files.cli import load_files
 from rero_ils.modules.items.api import Item
@@ -1579,26 +1578,25 @@ def token_create(name, user, scopes, internal, access_token):
         click.secho("No user found", fg="red")
 
 
-@utils.command("add_cover_urls")
-@click.option("-v", "--verbose", "verbose", is_flag=True, default=False)
+@utils.command()
+@click.option("-c", "--commit", "commit", is_flag=True, default=False, help="Commit changes to database.")
+@click.option("-v", "--verbose", "verbose", is_flag=True, default=False, help="Verbose print.")
+@click.option("--cached/--no-cached", "cached", default=True, help="Use cached thumbnails.")
+@click.option("-s", "--scroll", "scroll", default="60m", help="Elasticsearch scroll timeout.")
+@click.option(
+    "-p", "--pids", "pids_file", type=click.File("r"), default=None, help="File with document pids to process."
+)
 @with_appcontext
-def add_cover_urls(verbose):
+def add_cover_urls(commit, verbose, cached, scroll, pids_file):
     """Add cover urls to all documents with isbns."""
-    click.secho("Add cover urls.", fg="green")
-    search = (
-        DocumentsSearch()
-        .filter("term", identifiedBy__type="bf:Isbn")
-        .filter("bool", must_not=[Q("term", electronicLocator__content="coverImage")])
-        .params(preserve_order=True)
-        .sort({"pid": {"order": "asc"}})
-        .source("pid")
-    )
-    for idx, hit in enumerate(search.scan()):
-        pid = hit.pid
-        record = Document.get_record_by_pid(pid)
-        url = get_cover_art(record=record, save_cover_url=True)
+
+    pids = None
+    if pids_file:
+        pids = [line.strip() for line in pids_file if line.strip()]
         if verbose:
-            click.echo(f"{idx}:\tdocument: {pid}\t{url}")
+            click.secho(f"Processing {len(pids)} documents from file", fg="green")
+
+    return task_add_cover_urls(commit=commit, verbose=verbose, cached=cached, scroll=scroll, pids=pids)
 
 
 @utils.command()

rero_ils/modules/cli/utils.py

@@ -42,6 +42,7 @@
 
 from .dumpers import document_indexer_dumper, document_replace_refs_dumper
 from .extensions import (
+    AddCoverUrlExtension,
     AddMEFPidExtension,
     EditionStatementExtension,
     ProvisionActivitiesExtension,
@@ -115,13 +116,14 @@ class Document(IlsRecord):
     enable_jsonref = False
 
     _extensions = [
-        OperationLogObserverExtension(),
+        AddCoverUrlExtension(),
         AddMEFPidExtension("subjects", "contribution", "genreForm"),
+        DeleteRelatedLocalFieldExtension(),
+        EditionStatementExtension(),
+        OperationLogObserverExtension(),
         ProvisionActivitiesExtension(),
         SeriesStatementExtension(),
-        EditionStatementExtension(),
         TitleExtension(),
-        DeleteRelatedLocalFieldExtension(),
     ]
 
     def _validate(self, **kwargs):
@@ -490,13 +492,16 @@ def document_types(self):
             document_types.append(main_type)
         return document_types or ["docmaintype_other"]
 
-    def add_cover_url(self, url, dbcommit=False, reindex=False):
+    def add_cover_url(self, url, dbcommit=False, reindex=False, force=False):
         """Adds electronicLocator with coverImage to document."""
         electronic_locators = self.get("electronicLocator", [])
         for electronic_locator in electronic_locators:
             e_content = electronic_locator.get("content")
             e_type = electronic_locator.get("type")
-            if e_content == "coverImage" and e_type == "relatedResource" and electronic_locator.get("url") == url:
+            if e_content == "coverImage" and e_type == "relatedResource":
+                if force:
+                    electronic_locator["url"] = url
+                    break
                 return self, False
         electronic_locators.append({"content": "coverImage", "type": "relatedResource", "url": url})
         self["electronicLocator"] = electronic_locators

rero_ils/modules/documents/api.py

@@ -24,21 +24,25 @@
 from flask import request as flask_request
 from invenio_jsonschemas import current_jsonschemas
 from invenio_jsonschemas.errors import JSONSchemaNotFound
+from rero_invenio_thumbnails import get_thumbnail_url
 
 from rero_ils.modules.decorators import check_logged_as_librarian
 
 from ..utils import cached
 from .api import Document
-from .utils import get_remote_cover
 
 api_blueprint = Blueprint("api_documents", __name__, url_prefix="/document")
 
 
 @api_blueprint.route("/cover/<isbn>")
-@cached(timeout=5 * 60, query_string=True)  # 5 minutes timeout
 def cover(isbn):
     """Document cover service."""
-    return jsonify(get_remote_cover(isbn))
+
+    cached = flask_request.args.get("cached", default="true").lower() != "false"
+    url, provider = get_thumbnail_url(isbn, cached=cached)
+    if url:
+        return jsonify({"success": True, "image": url, "isbn": isbn, "provider": provider})
+    return jsonify({"success": False, "isbn": isbn})
 
 
 @api_blueprint.route("/<pid>/availability", methods=["GET"])

rero_ils/modules/documents/api_views.py

@@ -18,13 +18,15 @@
 
 """Document record extensions."""
 
+from .add_cover_url import AddCoverUrlExtension
 from .add_mef_pid import AddMEFPidExtension
 from .edition_statement import EditionStatementExtension
 from .provision_activities import ProvisionActivitiesExtension
 from .series_statement import SeriesStatementExtension
 from .title import TitleExtension
 
 __all__ = (
+    "AddCoverUrlExtension",
     "AddMEFPidExtension",
     "EditionStatementExtension",
     "ProvisionActivitiesExtension",

rero_ils/modules/documents/extensions/__init__.py

@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+#
+# RERO ILS
+# Copyright (C) 2026 RERO
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+"""Document record extension to add cover URL to electronicLocator."""
+
+from invenio_db import db
+from invenio_records.extensions import RecordExtension
+from rero_invenio_thumbnails import get_thumbnail_url
+
+
+class AddCoverUrlExtension(RecordExtension):
+    """Adds cover URL to electronicLocator based on ISBN."""
+
+    def __init__(self, cached=True):
+        """Initialization.
+
+        :param cached: Use cached thumbnails. Default: True.
+        """
+        self.cached = cached
+
+    def add_cover_url(self, record):
+        """Add cover URL to electronicLocator if ISBN is present.
+
+        :param record: dict - a document record.
+        """
+
+        # Check if cover image already exists
+        electronic_locators = record.get("electronicLocator", [])
+        has_cover = any(loc.get("content") == "coverImage" for loc in electronic_locators)
+
+        if has_cover:
+            return
+
+        # Get ISBNs from identifiedBy
+        isbns = [
+            identified_by.get("value")
+            for identified_by in record.get("identifiedBy", [])
+            if identified_by.get("type") == "bf:Isbn"
+        ]
+
+        if not isbns:
+            return
+
+        # Try to get thumbnail URL for the first ISBN
+        for isbn in sorted(isbns):
+            url, provider = get_thumbnail_url(isbn, cached=self.cached)
+            if url:
+                # Add to electronicLocator
+                record["electronicLocator"] = record.get("electronicLocator", [])
+                record["electronicLocator"].append(
+                    {"type": "relatedResource", "content": "coverImage", "url": url, "note": provider}
+                )
+                break
+
+    def post_create(self, record):
+        """Called after a record is initialized.
+
+        :param record: dict - the record to be modified.
+        """
+        self.add_cover_url(record)
+        if record.model:
+            with db.session.begin_nested():
+                record.model.data = record
+                db.session.add(record.model)
+
+    def post_commit(self, record):
+        """Called before a record is committed.
+
+        :param record: dict - the record to be modified.
+        """
+        self.add_cover_url(record)
+        if record.model:
+            with db.session.begin_nested():
+                record.model.data = record
+                # Note: session merge is not required as it is done by the
+                #       record.commit

rero_ils/modules/documents/extensions/add_cover_url.py

@@ -137,3 +137,60 @@ def reindex_document_items(record):
                 version=hit.meta.version,
                 version_type="external_gte",
             )
+
+
+@shared_task(ignore_result=True)
+def add_cover_urls(commit=False, verbose=False, cached=True, scroll="60m", pids=None):
+    """Add cover urls to all documents with isbns.
+
+    :param commit: if True commit changes to database.
+    :param verbose: Verbose print.
+    :param cached: Use cached thumbnails.
+    :param scroll: Elasticsearch scroll timeout.
+    :param pids: List of document pids to process. If None, process all documents.
+    :returns: count of updated documents.
+    """
+    from rero_invenio_thumbnails import get_thumbnail_url
+
+    from rero_ils.modules.documents.api import Document, DocumentsSearch
+
+    count = 0
+
+    if not pids:
+        # Get pids from search query
+        search = (
+            DocumentsSearch()
+            .filter("term", identifiedBy__type="bf:Isbn")
+            .exclude("term", electronicLocator__content="coverImage")
+            .params(preserve_order=True, scroll=scroll)
+            .source("pid")
+        )
+        pids = [hit.pid for hit in search.source("pid").scan()]
+        # Sort pids as integers
+        pids = sorted(pids, key=lambda x: int(x) if x.isdigit() else x)
+
+    # Process all pids
+    for idx, pid in enumerate(pids):
+        if document := Document.get_record_by_pid(pid):
+            isbns = [
+                identified_by.get("value")
+                for identified_by in document.get("identifiedBy", [])
+                if identified_by.get("type") == "bf:Isbn"
+            ]
+
+            for isbn in sorted(isbns):
+                url, provider = get_thumbnail_url(isbn, cached=cached)
+                if url:
+                    document["electronicLocator"] = document.get("electronicLocator", [])
+                    document["electronicLocator"].append(
+                        {"type": "relatedResource", "content": "coverImage", "url": url, "note": provider}
+                    )
+                    if verbose:
+                        click.echo(f"{idx}:\tdocument: {document.pid:<10} {provider:<15} {url}")
+                    if commit:
+                        document.update(data=document, dbcommit=True, reindex=True)
+                        count += 1
+                    break
+
+    set_timestamp("add_cover_urls", updated=count)
+    return count

rero_ils/modules/documents/tasks.py

@@ -17,12 +17,9 @@
 
 """Documents utils."""
 
-import json
 import re
 
-import requests
 from flask import current_app
-from flask import request as flask_request
 from invenio_jsonschemas.proxies import current_jsonschemas
 from werkzeug.local import LocalProxy
 
@@ -298,27 +295,3 @@ def process_i18n_literal_entity(entity):
             if key not in entity:
                 entity[key] = access_point
     return entity
-
-
-def get_remote_cover(isbn):
-    """Document cover service."""
-    if not isbn:
-        return None
-    cover_service = current_app.config.get("RERO_ILS_THUMBNAIL_SERVICE_URL")
-    url = f"{cover_service}?height=244px&width=244px&jsonpCallbackParam=callback&callback=thumb&type=isbn&value={isbn}"
-    try:
-        host_url = flask_request.host_url
-    except Exception:
-        host_url = current_app.config.get("RERO_ILS_URL", "??")
-        if host_url[-1] != "/":
-            host_url = f"{host_url}/"
-    response = requests.get(url, headers={"referer": host_url})
-    if response.status_code != 200:
-        msg = f"Unable to get cover for isbn: {isbn} {response.status_code}"
-        current_app.logger.debug(msg)
-        return None
-    result = json.loads(response.text[len("thumb(") : -1])
-    if result["success"]:
-        return result
-    current_app.logger.debug(f"Unable to get cover for isbn: {isbn}")
-    return None