invenio-app-ils 6.1.1__tar.gz → 7.1.0__tar.gz

{invenio_app_ils-6.1.1 → invenio_app_ils-7.1.0}/CHANGES.rst

@@ -1,6 +1,6 @@
 
 ..
-    Copyright (C) 2018-2025 CERN.
+    Copyright (C) 2018-2026 CERN.
 
     invenio-app-ils is free software; you can redistribute it and/or modify it
     under the terms of the MIT License; see LICENSE file for more details.
@@ -8,6 +8,23 @@
 Changes
 =======
 
+Version 7.1.0 (released 2026-01-22)
+
+- stats: add document request stats endpoint and extend document request index
+- stats: fix Schema using deserialize to validate
+- stats: add order stats endpoint and extend orders index
+- stats: turn loan histogram endpoint into reusable component
+
+Version 7.0.0 (released 2026-01-06)
+
+- stats: generalize stat tracking loan extensions to track all transitions
+- stats: raise error when loan is indexed while loan transition events index does not exits
+- stats: add feature flag for extending record indices with stats
+- stats: warn when loan gets indexed while loan-transitions index does not exist
+- breaking change: global: update invenio-circulation
+- breaking change: stats: add loan stats endpoint and extend loans index
+- breaking change: stats: add stat to track loan extensions
+
 Version 6.1.1 (released 2025-12-10)
 
 - tests: move covers builder test into correct folder

{invenio_app_ils-6.1.1 → invenio_app_ils-7.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invenio-app-ils
-Version: 6.1.1
+Version: 7.1.0
 Summary: Invenio Integrated Library System.
 Home-page: https://github.com/inveniosoftware/invenio-app-ils
 Author: CERN
@@ -39,7 +39,7 @@ Requires-Dist: invenio-records<4.0.0,>=3.0.2
 Requires-Dist: invenio-files-rest<4.0.0,>=3.2.0
 Requires-Dist: invenio-banners<6.0.0,>=5.0.0
 Requires-Dist: invenio-pages<8.0.0,>=7.1.0
-Requires-Dist: invenio-circulation<4.0.0,>=3.0.0a1
+Requires-Dist: invenio-circulation<5.0.0,>=4.0.0
 Requires-Dist: invenio-opendefinition<3.0.0,>=2.0.0a2
 Requires-Dist: invenio-pidrelations<2.0.0,>=1.0.0
 Requires-Dist: invenio-stats<6.0.0,>=5.1.1
@@ -95,7 +95,7 @@ https://invenioils.docs.cern.ch
 
 
 ..
-    Copyright (C) 2018-2025 CERN.
+    Copyright (C) 2018-2026 CERN.
 
     invenio-app-ils is free software; you can redistribute it and/or modify it
     under the terms of the MIT License; see LICENSE file for more details.
@@ -103,6 +103,23 @@ https://invenioils.docs.cern.ch
 Changes
 =======
 
+Version 7.1.0 (released 2026-01-22)
+
+- stats: add document request stats endpoint and extend document request index
+- stats: fix Schema using deserialize to validate
+- stats: add order stats endpoint and extend orders index
+- stats: turn loan histogram endpoint into reusable component
+
+Version 7.0.0 (released 2026-01-06)
+
+- stats: generalize stat tracking loan extensions to track all transitions
+- stats: raise error when loan is indexed while loan transition events index does not exits
+- stats: add feature flag for extending record indices with stats
+- stats: warn when loan gets indexed while loan-transitions index does not exist
+- breaking change: global: update invenio-circulation
+- breaking change: stats: add loan stats endpoint and extend loans index
+- breaking change: stats: add stat to track loan extensions
+
 Version 6.1.1 (released 2025-12-10)
 
 - tests: move covers builder test into correct folder

{invenio_app_ils-6.1.1 → invenio_app_ils-7.1.0}/invenio_app_ils/__init__.py

@@ -1,12 +1,12 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2018-2024 CERN.
+# Copyright (C) 2018-2026 CERN.
 #
 # invenio-app-ils is free software; you can redistribute it and/or modify it
 # under the terms of the MIT License; see LICENSE file for more details.
 
 """invenio-app-ils."""
 
-__version__ = "6.1.1"
+__version__ = "7.1.0"
 
 __all__ = ("__version__",)

invenio_app_ils-7.1.0/invenio_app_ils/acquisition/indexer.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2025 CERN.
+#
+# invenio-app-ils is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Order indexer APIs."""
+
+from datetime import datetime
+
+from invenio_search import current_search_client
+
+from invenio_app_ils.acquisition.api import ORDER_PID_TYPE
+from invenio_app_ils.proxies import current_app_ils
+
+
+def index_stats_fields_for_order(order_dict):
+    """Indexer hook to modify the order record dict before indexing."""
+
+    # This is done through the hook and not through an indexer class,
+    # as we need access to the `_created` field
+
+    # Only calculate stats if order is received
+    if not order_dict.get("received_date"):
+        return
+
+    stats = {}
+
+    received_date = datetime.fromisoformat(order_dict["received_date"]).date()
+    creation_date = datetime.fromisoformat(order_dict["_created"]).date()
+
+    # Calculate order_processing_time
+    order_processing_time = (received_date - creation_date).days
+    stats["order_processing_time"] = order_processing_time if order_processing_time >= 0 else None
+
+    # Find related document request if any
+    order_pid = order_dict.get("pid")
+    if order_pid:
+        doc_req_search_cls = current_app_ils.document_request_search_cls
+        search_body = {
+            "query": {
+                "bool": {
+                    "must": [
+                        {"term": {"physical_item_provider.pid": order_pid}},
+                        {"term": {"physical_item_provider.pid_type": ORDER_PID_TYPE}},
+                    ],
+                }
+            },
+            "size": 1,
+        }
+
+        search_result = current_search_client.search(
+            index=doc_req_search_cls.Meta.index, body=search_body
+        )
+
+        hits = search_result["hits"]["hits"]
+        if len(hits) > 0:
+            doc_request = hits[0]["_source"]
+            doc_req_creation_date = datetime.fromisoformat(
+                doc_request["_created"]
+            ).date()
+
+            order_dict["doc_request"] = {}
+
+            # Calculate document_request_waiting_time
+            waiting_time = (received_date - doc_req_creation_date).days
+            stats["document_request_waiting_time"] = (
+                waiting_time if waiting_time >= 0 else None
+            )
+
+    order_dict["stats"] = stats

{invenio_app_ils-6.1.1/invenio_app_ils/acquisition/mappings/v7 → invenio_app_ils-7.1.0/invenio_app_ils/acquisition/mappings/os-v2}/acq_orders/order-v1.0.0.json

@@ -358,6 +358,11 @@
       },
       "provider_pid": {
         "type": "keyword"
+      },
+      "stats": {
+        "type": "object",
+        "dynamic": true,
+        "enabled": true
       }
     }
   }

invenio_app_ils-7.1.0/invenio_app_ils/acquisition/stats/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2025 CERN.
+#
+# invenio-app-ils is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Invenio App ILS acquisition stats module."""

invenio_app_ils-7.1.0/invenio_app_ils/acquisition/stats/views.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2025 CERN.
+#
+# invenio-app-ils is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Invenio App ILS acquisition stats views."""
+
+from flask import Blueprint, request
+from invenio_records_rest.query import default_search_factory
+from invenio_rest import ContentNegotiatedMethodView
+from marshmallow.exceptions import ValidationError
+
+from invenio_app_ils.acquisition.api import ORDER_PID_TYPE
+from invenio_app_ils.acquisition.proxies import current_ils_acq
+from invenio_app_ils.errors import InvalidParameterError
+from invenio_app_ils.permissions import need_permissions
+from invenio_app_ils.stats.histogram import (
+    HistogramParamsSchema,
+    create_histogram_view,
+    get_record_statistics,
+)
+
+
+def create_acquisition_stats_blueprint(app):
+    """Add statistics views to the blueprint."""
+    blueprint = Blueprint("invenio_app_ils_acquisition_stats", __name__, url_prefix="")
+
+    create_histogram_view(
+        blueprint, app, ORDER_PID_TYPE, OrderHistogramResource, "/acquisition"
+    )
+
+    return blueprint
+
+
+class OrderHistogramResource(ContentNegotiatedMethodView):
+    """Order stats resource."""
+
+    view_name = "order_histogram"
+
+    def __init__(self, serializers, ctx, *args, **kwargs):
+        """Constructor."""
+        super().__init__(serializers, *args, **kwargs)
+        for key, value in ctx.items():
+            setattr(self, key, value)
+
+    @need_permissions("stats-orders")
+    def get(self, **kwargs):
+        """Get order statistics."""
+
+        order_date_fields = [
+            "order_date",
+            "expected_delivery_date",
+            "received_date",
+            "_created",
+            "_updated",
+        ]
+
+        schema = HistogramParamsSchema(order_date_fields)
+        try:
+            parsed_args = schema.load(request.args.to_dict())
+        except ValidationError as e:
+            raise InvalidParameterError(description=e.messages) from e
+
+        # Construct search to allow for filtering with the q parameter
+        search_cls = current_ils_acq.order_search_cls
+        search = search_cls()
+        search, _ = default_search_factory(self, search)
+
+        aggregation_buckets = get_record_statistics(
+            order_date_fields,
+            search,
+            parsed_args["group_by"],
+            parsed_args["metrics"],
+        )
+
+        response = {
+            "buckets": aggregation_buckets,
+        }
+
+        return self.make_response(response, 200)

invenio_app_ils-7.1.0/invenio_app_ils/circulation/errors.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2025 CERN.
+#
+# Invenio-App-Ils is free software; you can redistribute it and/or modify
+# it under the terms of the MIT License; see LICENSE file for more details.
+
+"""Circulation exceptions."""
+
+
+class LoanTransitionEventsIndexMissingError(Exception):
+    """Error raised when the loan transition events index is missing."""

{invenio_app_ils-6.1.1 → invenio_app_ils-7.1.0}/invenio_app_ils/circulation/indexer.py

@@ -15,7 +15,9 @@ from invenio_circulation.pidstore.pids import CIRCULATION_LOAN_PID_TYPE
 from invenio_circulation.proxies import current_circulation
 from invenio_indexer.api import RecordIndexer
 from invenio_pidstore.errors import PIDDeletedError
+from invenio_search import current_search_client
 
+from invenio_app_ils.circulation.errors import LoanTransitionEventsIndexMissingError
 from invenio_app_ils.circulation.utils import resolve_item_from_loan
 from invenio_app_ils.documents.api import DOCUMENT_PID_TYPE
 from invenio_app_ils.indexer import ReferencedRecordsIndexer
@@ -97,3 +99,73 @@ def index_extra_fields_for_loan(loan_dict):
 
     can_circulate_items_count = document["circulation"]["can_circulate_items_count"]
     loan_dict["can_circulate_items_count"] = can_circulate_items_count
+
+
+def index_stats_fields_for_loan(loan_dict):
+    """Indexer hook to modify the loan record dict before indexing"""
+
+    creation_date = datetime.fromisoformat(loan_dict["_created"]).date()
+    start_date = (
+        datetime.fromisoformat(loan_dict["start_date"]).date()
+        if loan_dict.get("start_date")
+        else None
+    )
+    end_date = (
+        datetime.fromisoformat(loan_dict["end_date"]).date()
+        if loan_dict.get("end_date")
+        else None
+    )
+
+    # Collect extra information relevant for stats
+    stats = {}
+
+    # Time ranges in days
+    if start_date and end_date:
+        loan_duration = (end_date - start_date).days
+        stats["loan_duration"] = loan_duration
+
+    if creation_date and start_date:
+        waiting_time = (start_date - creation_date).days
+        stats["waiting_time"] = waiting_time if waiting_time >= 0 else None
+
+    # Document availability during loan request
+    stat_events_index_name = "events-stats-loan-transitions"
+    if not current_search_client.indices.exists(index=stat_events_index_name):
+        raise LoanTransitionEventsIndexMissingError()
+
+    loan_pid = loan_dict["pid"]
+    search_body = {
+        "query": {
+            "bool": {
+                "must": [
+                    {"term": {"trigger": "request"}},
+                    {"term": {"pid_value": loan_pid}},
+                ],
+            }
+        },
+    }
+
+    search_result = current_search_client.search(
+        index=stat_events_index_name, body=search_body
+    )
+    hits = search_result["hits"]["hits"]
+    if len(hits) == 1:
+        request_transition_event = hits[0]["_source"]
+        available_items_during_request_count = request_transition_event[
+            "extra_data"
+        ]["available_items_during_request_count"]
+        stats["available_items_during_request"] = (
+            available_items_during_request_count > 0
+        )
+    elif len(hits) > 1:
+        raise ValueError(
+            f"Multiple request transition events for loan {loan_pid}."
+            "Expected zero or one."
+        )
+
+
+    # Make use of the `extra_data` property as loans are part of `invenio-circulation`,
+    # which do not expose the `stats` property directly
+    if not "extra_data" in loan_dict:
+        loan_dict["extra_data"] = {}
+    loan_dict["extra_data"]["stats"] = stats

{invenio_app_ils-6.1.1 → invenio_app_ils-7.1.0}/invenio_app_ils/circulation/stats/api.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2019 CERN.
+# Copyright (C) 2019-2025 CERN.
 #
 # invenio-app-ils is free software; you can redistribute it and/or modify it
 # under the terms of the MIT License; see LICENSE file for more details.

{invenio_app_ils-6.1.1 → invenio_app_ils-7.1.0}/invenio_app_ils/circulation/stats/views.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2019 CERN.
+# Copyright (C) 2019-2025 CERN.
 #
 # invenio-app-ils is free software; you can redistribute it and/or modify it
 # under the terms of the MIT License; see LICENSE file for more details.
@@ -10,15 +10,25 @@
 from datetime import datetime
 
 from flask import Blueprint, current_app, request
+from invenio_circulation.pidstore.pids import CIRCULATION_LOAN_PID_TYPE
+from invenio_circulation.proxies import current_circulation
 from invenio_pidstore import current_pidstore
+from invenio_records_rest.query import default_search_factory
 from invenio_records_rest.utils import obj_or_import_string
 from invenio_rest import ContentNegotiatedMethodView
+from marshmallow.exceptions import ValidationError
 
 from invenio_app_ils.circulation.stats.api import fetch_most_loaned_documents
+from invenio_app_ils.circulation.views import IlsCirculationResource
 from invenio_app_ils.config import RECORDS_REST_MAX_RESULT_WINDOW
 from invenio_app_ils.documents.api import DOCUMENT_PID_FETCHER, DOCUMENT_PID_TYPE
 from invenio_app_ils.errors import InvalidParameterError
 from invenio_app_ils.permissions import need_permissions
+from invenio_app_ils.stats.histogram import (
+    HistogramParamsSchema,
+    create_histogram_view,
+    get_record_statistics,
+)
 
 
 def create_most_loaned_documents_view(blueprint, app):
@@ -51,6 +61,13 @@ def create_circulation_stats_blueprint(app):
     blueprint = Blueprint("invenio_app_ils_circulation_stats", __name__, url_prefix="")
 
     create_most_loaned_documents_view(blueprint, app)
+    create_histogram_view(
+        blueprint,
+        app,
+        CIRCULATION_LOAN_PID_TYPE,
+        LoanHistogramResource,
+        "/circulation/loans",
+    )
 
     return blueprint
 
@@ -131,3 +148,42 @@ class MostLoanedDocumentsResource(ContentNegotiatedMethodView):
             pid_fetcher=current_pidstore.fetchers[DOCUMENT_PID_FETCHER],
             search_result=most_loaned_documents,
         )
+
+
+class LoanHistogramResource(IlsCirculationResource):
+    """Loan stats resource."""
+
+    view_name = "loan_histogram"
+
+    @need_permissions("stats-loans")
+    def get(self, **kwargs):
+        """Get loan statistics."""
+
+        loan_cls = current_circulation.loan_record_cls
+        loan_date_fields = (
+            loan_cls.DATE_FIELDS + loan_cls.DATETIME_FIELDS + ["_created"]
+        )
+
+        schema = HistogramParamsSchema(loan_date_fields)
+        try:
+            parsed_args = schema.load(request.args.to_dict())
+        except ValidationError as e:
+            raise InvalidParameterError(description=e.messages) from e
+
+        # Construct search to allow for filtering with the q parameter
+        search_cls = current_circulation.loan_search_cls
+        search = search_cls()
+        search, _ = default_search_factory(self, search)
+
+        aggregation_buckets = get_record_statistics(
+            loan_date_fields,
+            search,
+            parsed_args["group_by"],
+            parsed_args["metrics"],
+        )
+
+        response = {
+            "buckets": aggregation_buckets,
+        }
+
+        return self.make_response(response, 200)

{invenio_app_ils-6.1.1 → invenio_app_ils-7.1.0}/invenio_app_ils/config.py

@@ -43,6 +43,7 @@ from invenio_app_ils.locations.indexer import LocationIndexer
 from invenio_app_ils.patrons.indexer import PatronIndexer
 from invenio_app_ils.series.indexer import SeriesIndexer
 from invenio_app_ils.stats.event_builders import ils_record_changed_event_builder
+from invenio_app_ils.stats.processors import LoansEventsIndexer
 from invenio_app_ils.vocabularies.indexer import VocabularyIndexer
 
 from .document_requests.api import (
@@ -244,13 +245,21 @@ CELERY_BEAT_SCHEDULE = {
                 "ils-record-changes-updates",
                 "ils-record-changes-insertions",
                 "ils-record-changes-deletions",
+                "loan-transitions",
             )
         ],
     },
     "stats-aggregate-events": {
         "task": "invenio_stats.tasks.aggregate_events",
         "schedule": timedelta(hours=3),
-        "args": [("record-view-agg", "file-download-agg", "ils-record-changes-agg")],
+        "args": [
+            (
+                "record-view-agg",
+                "file-download-agg",
+                "ils-record-changes-agg",
+                "loan-transitions-agg",
+            )
+        ],
     },
     "clean_locations_past_closures_exceptions": {
         "task": (
@@ -983,6 +992,25 @@ STATS_EVENTS = {
             "suffix": "%Y",
         },
     },
+    # The following events are used to count loan state transitions.
+    # Additionally, some transitions, e.g. "request", are used to store extra data,
+    # like the number of available items when a loan is requested.
+    # The loan indexer then later queries those events and adds the information to the loan.
+    "loan-transitions": {
+        "signal": "invenio_circulation.signals.loan_state_changed",
+        "templates": "invenio_app_ils.stats.templates.events.loan_transitions",
+        "event_builders": [
+            "invenio_app_ils.stats.event_builders.loan_transition_event_builder",
+        ],
+        "cls": LoansEventsIndexer,
+        "params": {
+            "preprocessors": [
+                "invenio_app_ils.stats.processors.add_loan_transition_unique_id",
+            ],
+            "double_click_window": 0,
+            "suffix": "%Y",
+        },
+    },
 }
 
 STATS_AGGREGATIONS = {
@@ -1042,6 +1070,19 @@ STATS_AGGREGATIONS = {
             query_modifiers=[],
         ),
     ),
+    "loan-transitions-agg": dict(
+        templates="invenio_app_ils.stats.templates.aggregations.loan_transitions",
+        cls=StatAggregator,
+        params=dict(
+            event="loan-transitions",
+            field="trigger",
+            interval="day",
+            index_interval="year",
+            copy_fields=dict(),
+            metric_fields=dict(),
+            query_modifiers=[],
+        ),
+    ),
 }
 
 STATS_QUERIES = {
@@ -1116,6 +1157,18 @@ STATS_QUERIES = {
             aggregated_fields=["user_id"],
         ),
     ),
+    "loan-transitions": dict(
+        cls=DateHistogramQuery,
+        permission_factory=backoffice_read_permission,
+        params=dict(
+            index="stats-loan-transitions",
+            copy_fields=dict(),
+            required_filters=dict(trigger="trigger"),
+            metric_fields=dict(
+                count=("sum", "count", {}),
+            ),
+        ),
+    ),
 }
 
 # List of available vocabularies
@@ -1189,6 +1242,7 @@ DB_VERSIONING_USER_MODEL = None
 
 # Feature Toggles
 ILS_SELF_CHECKOUT_ENABLED = False
+ILS_EXTEND_INDICES_WITH_STATS_ENABLED = False
 
 # Use default frontpage
 THEME_FRONTPAGE = False