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

{invenio_app_ils-6.1.1 → invenio_app_ils-7.0.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,16 @@
 Changes
 =======
 
+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.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invenio-app-ils
-Version: 6.1.1
+Version: 7.0.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,16 @@ https://invenioils.docs.cern.ch
 Changes
 =======
 
+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.0.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.0.0"
 
 __all__ = ("__version__",)

invenio_app_ils-7.0.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.0.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,71 @@ 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."
+        )
+
+
+    if not "extra_data" in loan_dict:
+        loan_dict["extra_data"] = {}
+    loan_dict["extra_data"]["stats"] = stats

invenio_app_ils-7.0.0/invenio_app_ils/circulation/stats/api.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+#
+# 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.
+
+"""APIs for ILS circulation statistics."""
+
+from invenio_search.engine import dsl
+
+from invenio_app_ils.circulation.search import get_most_loaned_documents
+from invenio_app_ils.circulation.stats.schemas import (
+    _OS_NATIVE_AGGREGATE_FUNCTION_TYPES,
+)
+from invenio_app_ils.proxies import current_app_ils
+
+
+def fetch_most_loaned_documents(from_date, to_date, bucket_size):
+    """Fetch the documents with the most loans within the date interval."""
+    # Create loans aggregation
+    most_loaned = get_most_loaned_documents(from_date, to_date, bucket_size)
+
+    # Prepare the loan and extension count
+    document_pids = []
+    document_metadata = {}
+    loan_result = most_loaned.execute()
+    for bucket in loan_result.aggregations.most_loaned_documents.buckets:
+        document_pid = bucket["key"]
+        loan_count = bucket["doc_count"]
+        loan_extensions = int(bucket["extensions"]["value"])
+        document_pids.append(document_pid)
+        document_metadata[document_pid] = dict(
+            loans=loan_count, extensions=loan_extensions
+        )
+
+    # Enhance the document serializer
+    doc_search = current_app_ils.document_search_cls()
+    doc_search = doc_search.with_preference_param().params(version=True)
+    doc_search = doc_search.search_by_pid(*document_pids)
+    doc_search = doc_search[0:bucket_size]
+    result = doc_search.execute()
+
+    for hit in result.hits:
+        pid = hit["pid"]
+        hit["loan_count"] = document_metadata[pid]["loans"]
+        hit["loan_extensions"] = document_metadata[pid]["extensions"]
+
+    res = result.to_dict()
+    res["hits"]["hits"] = sorted(
+        res["hits"]["hits"],
+        key=lambda hit: hit["_source"]["loan_count"],
+        reverse=True,
+    )
+
+    return res
+
+
+def _generate_metric_agg_field_name(metric):
+    """Return the aggregation name used for a metric.
+
+    :param metric: Must include 'field' and 'aggregation' keys.
+    :returns: The aggregation field name in the form '<aggregation>_<field>'.
+    """
+
+    return f"{metric['aggregation']}__{metric['field']}"
+
+
+def get_loan_statistics(date_fields, search, requested_group_by, requested_metrics):
+    """Aggregate loan statistics for requested metrics.
+
+    :param date_fields: List of date fields for the record type.
+        Date fields require different handling when using them to group by.
+    :param search: The base search object to apply aggregations on
+    :param requested_group_by: List of group dictionaries with 'field' and optional 'interval' keys.
+        Example: [{"field": "start_date", "interval": "monthly"}, {"field": "state"}]
+    :param requested_metrics: List of metric dictionaries with 'field' and 'aggregation' keys.
+        Example: [{"field": "loan_duration", "aggregation": "avg"}]
+    :returns: OpenSearch aggregation results with multi-terms histogram and optional metrics
+    """
+
+    # Build composite aggregation
+    sources = []
+    for grouping in requested_group_by:
+        grouping_field = grouping["field"]
+
+        if grouping_field in date_fields:
+            sources.append(
+                {
+                    grouping_field: {
+                        "date_histogram": {
+                            "field": grouping_field,
+                            "calendar_interval": grouping["interval"],
+                            "format": "yyyy-MM-dd",
+                        }
+                    }
+                }
+            )
+        else:
+            sources.append({grouping_field: {"terms": {"field": grouping_field}}})
+
+    composite_agg = dsl.A("composite", sources=sources, size=1000)
+
+    for metric in requested_metrics:
+        agg_name = _generate_metric_agg_field_name(metric)
+
+        grouping_field = metric["field"]
+        agg_type = metric["aggregation"]
+        field_config = {"field": grouping_field}
+        if agg_type in _OS_NATIVE_AGGREGATE_FUNCTION_TYPES:
+            composite_agg = composite_agg.metric(
+                agg_name, dsl.A(agg_type, **field_config)
+            )
+        elif agg_type == "median":
+            composite_agg = composite_agg.metric(
+                agg_name, dsl.A("percentiles", percents=[50], **field_config)
+            )
+
+    search.aggs.bucket("loan_aggregations", composite_agg)
+
+    # Only retrieve aggregation results
+    search = search[:0]
+    result = search.execute()
+
+    # Parse aggregation results
+    buckets = []
+    if hasattr(result.aggregations, "loan_aggregations"):
+        for bucket in result.aggregations.loan_aggregations.buckets:
+            metrics_data = {}
+            for metric in requested_metrics:
+                agg_name = _generate_metric_agg_field_name(metric)
+
+                if hasattr(bucket, agg_name):
+                    agg_result = getattr(bucket, agg_name)
+                    agg_type = metric["aggregation"]
+
+                    if agg_type in _OS_NATIVE_AGGREGATE_FUNCTION_TYPES:
+                        metrics_data[agg_name] = agg_result.value
+                    elif agg_type == "median":
+                        median_value = agg_result.values.get("50.0")
+                        metrics_data[agg_name] = median_value
+
+            bucket_data = {
+                "key": bucket.key.to_dict(),
+                "doc_count": bucket.doc_count,
+                "metrics": metrics_data,
+            }
+
+            buckets.append(bucket_data)
+
+    return buckets

invenio_app_ils-7.0.0/invenio_app_ils/circulation/stats/schemas.py

@@ -0,0 +1,110 @@
+# -*- 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.
+
+"""Marshmallow schemas for loan statistics validation."""
+
+import json
+import re
+
+from marshmallow import (
+    Schema,
+    ValidationError,
+    fields,
+    pre_load,
+    validate,
+    validates_schema,
+)
+
+from invenio_app_ils.errors import InvalidParameterError
+
+_OS_VALID_FIELD_NAME_PATTERN = re.compile(r"^[A-Za-z0-9_.]+$")
+_OS_NATIVE_AGGREGATE_FUNCTION_TYPES = {"avg", "sum", "min", "max"}
+_VALID_AGGREGATE_FUNCTION_TYPES = _OS_NATIVE_AGGREGATE_FUNCTION_TYPES.union({"median"})
+_VALID_DATE_INTERVALS = {"1d", "1w", "1M", "1q", "1y"}
+
+
+def validate_field_name(field_name):
+    """Validate a field name for search to prevent injection attacks.
+
+    :param field_name: The field name to validate
+    :raises InvalidParameterError: If field name is invalid or potentially malicious
+    """
+    if not _OS_VALID_FIELD_NAME_PATTERN.match(field_name):
+        raise InvalidParameterError(
+            description=(
+                f"Invalid field name '{field_name}'. "
+                "Field names may contain only alphanumeric characters, underscores, "
+                "and dots."
+            )
+        )
+
+
+class SecureFieldNameField(fields.String):
+    """Marshmallow field that validates field names to prevent injection attacks."""
+
+    def _deserialize(self, value, attr, data, **kwargs):
+        """Deserialize and validate field name."""
+
+        field_name = super()._deserialize(value, attr, data, **kwargs)
+        validate_field_name(field_name)
+        return field_name
+
+
+class GroupByItemSchema(Schema):
+    field = SecureFieldNameField(required=True)
+    interval = fields.String(validate=validate.OneOf(_VALID_DATE_INTERVALS))
+
+    @validates_schema
+    def validate_date_fields(self, data, **kwargs):
+        """Validate that date fields have an interval and non-date fields do not."""
+
+        date_fields = self.context["date_fields"]
+        field = data.get("field")
+        interval = data.get("interval")
+        if field in date_fields and not interval:
+            raise ValidationError(
+                {"interval": ["Interval is required for date fields."]}
+            )
+        if field not in date_fields and interval is not None:
+            raise ValidationError(
+                {"interval": ["Interval must not be provided for non-date fields."]}
+            )
+
+
+class MetricItemSchema(Schema):
+    """Schema for validating a single metric item."""
+
+    field = SecureFieldNameField(required=True)
+    aggregation = fields.String(
+        required=True, validate=validate.OneOf(_VALID_AGGREGATE_FUNCTION_TYPES)
+    )
+
+
+class HistogramParamsSchema(Schema):
+    """Schema for validating the query string parameters for the histogram endpoint"""
+
+    metrics = fields.List(fields.Nested(MetricItemSchema), required=False)
+    group_by = fields.List(
+        fields.Nested(GroupByItemSchema), required=True, validate=validate.Length(min=1)
+    )
+    q = fields.String()
+
+    def __init__(self, date_fields, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.context = {"date_fields": set(date_fields)}
+
+    @pre_load
+    def parse_query_string(self, data, **kwargs):
+        """Parse the metrics and group_by parameters from JSON strings."""
+
+        try:
+            for key in ("metrics", "group_by"):
+                # default value as the field "metrics" is not required
+                data[key] = json.loads(data.get(key, "[]"))
+        except Exception as e:
+            raise ValidationError from e
+        return data

invenio_app_ils-7.0.0/invenio_app_ils/circulation/stats/serializers/__init__.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+#
+# This file is part of Invenio.
+# Copyright (C) 2025-2025 CERN.
+#
+# Invenio is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+
+from invenio_app_ils.circulation.stats.serializers.response import loan_stats_responsify
+from invenio_app_ils.circulation.stats.serializers.schema import HistogramStatsV1
+
+loan_stats_response = loan_stats_responsify(HistogramStatsV1, "application/json")

invenio_app_ils-7.0.0/invenio_app_ils/circulation/stats/serializers/response.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+#
+# This file is part of Invenio.
+# Copyright (C) 2025-2025 CERN.
+#
+# Invenio 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 loan stats response serializers."""
+
+import json
+
+from flask import current_app
+
+
+def loan_stats_responsify(schema_class, mimetype):
+    """Loan stats response serializer.
+
+    :param schema_class: Schema instance.
+    :param mimetype: MIME type of response.
+    """
+
+    def view(data, code=200, headers=None):
+        """Generate the response object."""
+        # return jsonify(data), code
+        response_data = schema_class().dump(data)
+
+        response = current_app.response_class(
+            json.dumps(response_data), mimetype=mimetype
+        )
+        response.status_code = code
+
+        if headers is not None:
+            response.headers.extend(headers)
+        return response
+
+    return view

invenio_app_ils-7.0.0/invenio_app_ils/circulation/stats/serializers/schema.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+#
+# This file is part of Invenio.
+# Copyright (C) 2025-2025 CERN.
+#
+# Invenio 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 loan stats serializers schema."""
+
+from marshmallow import Schema, fields
+
+
+class BucketSchema(Schema):
+    """Schema for a single histogram bucket."""
+
+    doc_count = fields.Int(required=True)
+    key = fields.Dict(keys=fields.String(), values=fields.String())
+
+    metrics = fields.Dict(
+        keys=fields.String(),
+        values=fields.Float(),
+    )
+
+
+class HistogramStatsV1(Schema):
+    """Schema for a stats histogram response."""
+
+    buckets = fields.List(
+        fields.Nested(BucketSchema),
+        required=True,
+        description="Statistics buckets.",
+    )

{invenio_app_ils-6.1.1 → invenio_app_ils-7.0.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,11 +10,21 @@
 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 invenio_app_ils.circulation.stats.api import fetch_most_loaned_documents
+from marshmallow.exceptions import ValidationError
+
+from invenio_app_ils.circulation.stats.api import (
+    fetch_most_loaned_documents,
+    get_loan_statistics,
+)
+from invenio_app_ils.circulation.stats.schemas import HistogramParamsSchema
+from invenio_app_ils.circulation.stats.serializers import loan_stats_response
+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
@@ -46,11 +56,33 @@ def create_most_loaned_documents_view(blueprint, app):
     )
 
 
+def create_loan_histogram_view(blueprint, app):
+    """Add url rule for loan histogram view."""
+
+    endpoints = app.config.get("RECORDS_REST_ENDPOINTS")
+    document_endpoint = endpoints.get(CIRCULATION_LOAN_PID_TYPE)
+    default_media_type = document_endpoint.get("default_media_type")
+    loan_stats_serializers = {"application/json": loan_stats_response}
+
+    loan_stats_view_func = LoanHistogramResource.as_view(
+        LoanHistogramResource.view_name,
+        serializers=loan_stats_serializers,
+        default_media_type=default_media_type,
+        ctx={},
+    )
+    blueprint.add_url_rule(
+        "/circulation/loans/stats",
+        view_func=loan_stats_view_func,
+        methods=["GET"],
+    )
+
+
 def create_circulation_stats_blueprint(app):
     """Add statistics views to the blueprint."""
     blueprint = Blueprint("invenio_app_ils_circulation_stats", __name__, url_prefix="")
 
     create_most_loaned_documents_view(blueprint, app)
+    create_loan_histogram_view(blueprint, app)
 
     return blueprint
 
@@ -131,3 +163,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_loan_statistics(
+            loan_date_fields,
+            search,
+            parsed_args["group_by"],
+            parsed_args["metrics"],
+        )
+
+        response = {
+            "buckets": aggregation_buckets,
+        }
+
+        return self.make_response(response, 200)