invenio-app-ils 6.1.1__py2.py3-none-any.whl → 7.1.0__py2.py3-none-any.whl

invenio_app_ils/document_requests/stats/views.py

@@ -0,0 +1,85 @@
+# -*- 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 document requests 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.document_requests.api import DOCUMENT_REQUEST_PID_TYPE
+from invenio_app_ils.errors import InvalidParameterError
+from invenio_app_ils.permissions import need_permissions
+from invenio_app_ils.proxies import current_app_ils
+from invenio_app_ils.stats.histogram import (
+    HistogramParamsSchema,
+    create_histogram_view,
+    get_record_statistics,
+)
+
+
+def create_document_request_stats_blueprint(app):
+    """Add statistics views to the blueprint."""
+    blueprint = Blueprint(
+        "invenio_app_ils_document_request_stats", __name__, url_prefix=""
+    )
+
+    create_histogram_view(
+        blueprint,
+        app,
+        DOCUMENT_REQUEST_PID_TYPE,
+        DocumentRequestHistogramResource,
+        "/document-requests",
+    )
+
+    return blueprint
+
+
+class DocumentRequestHistogramResource(ContentNegotiatedMethodView):
+    """Document request stats resource."""
+
+    view_name = "document_request_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-document-requests")
+    def get(self, **kwargs):
+        """Get document request statistics."""
+
+        document_request_date_fields = [
+            "_created",
+            "_updated",
+        ]
+
+        schema = HistogramParamsSchema(document_request_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_app_ils.document_request_search_cls
+        search = search_cls()
+        search, _ = default_search_factory(self, search)
+
+        aggregation_buckets = get_record_statistics(
+            document_request_date_fields,
+            search,
+            parsed_args["group_by"],
+            parsed_args["metrics"],
+        )
+
+        response = {
+            "buckets": aggregation_buckets,
+        }
+
+        return self.make_response(response, 200)

invenio_app_ils/ext.py

@@ -20,10 +20,15 @@ from invenio_app_ils.records.metadata_extensions import (
 )
 
 from .circulation import config as circulation_config
-from .circulation.indexer import index_extra_fields_for_loan
+from .acquisition.indexer import index_stats_fields_for_order
+from .circulation.indexer import (
+    index_extra_fields_for_loan,
+    index_stats_fields_for_loan,
+)
 from .circulation.receivers import register_circulation_signals
 from .document_requests.api import DOCUMENT_REQUEST_PID_TYPE
-from .documents.api import DOCUMENT_PID_TYPE, Document
+from .document_requests.indexer import index_stats_fields_for_document_request
+from .documents.api import DOCUMENT_PID_TYPE
 from .eitems.api import EITEM_PID_TYPE
 from .files.receivers import register_files_signals
 from .internal_locations.api import INTERNAL_LOCATION_PID_TYPE
@@ -221,6 +226,8 @@ class InvenioAppIls(object):
             self.init_app(app)
             self.init_metadata_extensions(app)
             self.init_loan_indexer_hook(app)
+            self.init_order_indexer_hook(app)
+            self.init_document_request_indexer_hook(app)
 
     def init_app(self, app):
         """Flask application initialization."""
@@ -275,6 +282,24 @@ class InvenioAppIls(object):
             index="{0}s-{0}-v1.0.0".format("loan"),
         )
 
+    def init_order_indexer_hook(self, app):
+        """Custom order indexer hook init."""
+        before_record_index.dynamic_connect(
+            before_order_index_hook,
+            sender=app,
+            weak=False,
+            index="acq_orders-order-v1.0.0",
+        )
+
+    def init_document_request_indexer_hook(self, app):
+        """Custom document request indexer hook init."""
+        before_record_index.dynamic_connect(
+            before_document_request_index_hook,
+            sender=app,
+            weak=False,
+            index="document_requests-document_request-v1.0.0",
+        )
+
     def update_config_records_rest(self, app):
         """Merge overridden circ records rest into global records rest."""
         for k in dir(circulation_config):
@@ -327,3 +352,32 @@ def before_loan_index_hook(sender, json=None, record=None, index=None, **kwargs)
     :param kwargs: Any other parameters.
     """
     index_extra_fields_for_loan(json)
+    if current_app.config["ILS_EXTEND_INDICES_WITH_STATS_ENABLED"]:
+        index_stats_fields_for_loan(json)
+
+
+def before_order_index_hook(sender, json=None, record=None, index=None, **kwargs):
+    """Hook to transform order record before ES indexing.
+
+    :param sender: The entity sending the signal.
+    :param json: The dumped Record dict which will be indexed.
+    :param record: The corresponding Record object.
+    :param index: The index in which the json will be indexed.
+    :param kwargs: Any other parameters.
+    """
+    if current_app.config["ILS_EXTEND_INDICES_WITH_STATS_ENABLED"]:
+        index_stats_fields_for_order(json)
+
+def before_document_request_index_hook(
+    sender, json=None, record=None, index=None, **kwargs
+):
+    """Hook to transform document request record before ES indexing.
+
+    :param sender: The entity sending the signal.
+    :param json: The dumped Record dict which will be indexed.
+    :param record: The corresponding Record object.
+    :param index: The index in which the json will be indexed.
+    :param kwargs: Any other parameters.
+    """
+    if current_app.config["ILS_EXTEND_INDICES_WITH_STATS_ENABLED"]:
+        index_stats_fields_for_document_request(json)

invenio_app_ils/permissions.py

@@ -205,6 +205,9 @@ _is_backoffice_permission = [
 ]
 _is_backoffice_read_permission = [
     "stats-most-loaned",
+    "stats-loans",
+    "stats-orders",
+    "stats-document-requests",
     "get-notifications-sent-to-patron",
 ]
 _is_patron_owner_permission = [

invenio_app_ils/stats/event_builders.py

@@ -14,6 +14,7 @@ from flask import g
 from flask_login import current_user
 
 from invenio_app_ils.permissions import backoffice_permission
+from invenio_app_ils.proxies import current_app_ils
 from invenio_app_ils.records.api import IlsRecord
 
 
@@ -71,3 +72,46 @@ def add_record_pid_to_event(event, sender_app, record=None, **kwargs):
     event.update({"pid_value": record.get("pid")})
 
     return event
+
+
+def loan_transition_event_builder(
+    event,
+    sender_app,
+    transition=None,
+    initial_loan=None,
+    loan=None,
+    trigger=None,
+    **kwargs
+):
+    """Build an event for a loan state transition."""
+    event.update(
+        {
+            "timestamp": datetime.datetime.now(datetime.timezone.utc)
+            .replace(tzinfo=None)
+            .isoformat(),
+            "trigger": trigger,
+            "pid_value": loan["pid"],
+        }
+    )
+
+    if trigger == "request":
+        # Store how many items were available during request.
+        # This information is used by the loan indexer and added to the loan.
+        document_pid = loan["document_pid"]
+        document_class = current_app_ils.document_record_cls
+        document = document_class.get_record_by_pid(document_pid)
+        document_dict = document.replace_refs()
+
+        available_items_during_request_count = document_dict["circulation"][
+            "available_items_for_loan_count"
+        ]
+
+        event.update(
+            {
+                "extra_data": {
+                    "available_items_during_request_count": available_items_during_request_count
+                },
+            }
+        )
+
+    return event

invenio_app_ils/stats/histogram/__init__.py

@@ -0,0 +1,18 @@
+# -*- 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 histogram statistics."""
+
+from invenio_app_ils.stats.histogram.api import get_record_statistics
+from invenio_app_ils.stats.histogram.schemas import HistogramParamsSchema
+from invenio_app_ils.stats.histogram.views import create_histogram_view
+
+__all__ = (
+    "get_record_statistics",
+    "HistogramParamsSchema",
+    "create_histogram_view",
+)

invenio_app_ils/stats/histogram/api.py

@@ -0,0 +1,109 @@
+# -*- 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 histogram statistics."""
+
+from invenio_search.engine import dsl
+
+from invenio_app_ils.stats.histogram.schemas import (
+    _OS_NATIVE_AGGREGATE_FUNCTION_TYPES,
+)
+
+
+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_record_statistics(date_fields, search, requested_group_by, requested_metrics):
+    """Aggregate record 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("aggregations", composite_agg)
+
+    # Only retrieve aggregation results
+    search = search[:0]
+    result = search.execute()
+
+    # Parse aggregation results
+    buckets = []
+    if hasattr(result.aggregations, "aggregations"):
+        for bucket in getattr(result.aggregations, "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/stats/histogram/schemas.py

@@ -0,0 +1,92 @@
+# -*- 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 histogram statistics validation."""
+
+import json
+import re
+
+from marshmallow import (
+    Schema,
+    ValidationError,
+    fields,
+    pre_load,
+    validate,
+    validates_schema,
+)
+
+
+_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"}
+
+
+class SecureSearchFieldNameField(fields.String):
+    """Field that validates field names for search to prevent injection attacks."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs["validate"] = validate.Regexp(_OS_VALID_FIELD_NAME_PATTERN)
+        super().__init__(*args, **kwargs)
+
+
+class GroupByItemSchema(Schema):
+    """Schema for validating a single group_by item."""
+
+    field = SecureSearchFieldNameField(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 = SecureSearchFieldNameField(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/stats/histogram/serializers/__init__.py

@@ -0,0 +1,18 @@
+# -*- 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 histogram stats serializers."""
+
+from invenio_app_ils.stats.histogram.serializers.response import (
+    histogram_stats_responsify,
+)
+from invenio_app_ils.stats.histogram.serializers.schema import HistogramStatsV1
+
+histogram_stats_response = histogram_stats_responsify(
+    HistogramStatsV1, "application/json"
+)

invenio_app_ils/stats/histogram/serializers/response.py

@@ -0,0 +1,36 @@
+# -*- 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 histogram stats response serializers."""
+
+import json
+
+from flask import current_app
+
+
+def histogram_stats_responsify(schema_class, mimetype):
+    """Histogram 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."""
+        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/stats/histogram/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 histogram 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/stats/histogram/views.py

@@ -0,0 +1,34 @@
+# -*- 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 histogram stats views."""
+
+from invenio_app_ils.stats.histogram.serializers import histogram_stats_response
+
+
+def create_histogram_view(blueprint, app, pid_type, resource_cls, url_prefix):
+    """Add url rule for histogram view."""
+
+    assert url_prefix.startswith("/"), "url_prefix must start with /"
+    assert not url_prefix.endswith("/"), "url_prefix must not end with /"
+
+    endpoints = app.config.get("RECORDS_REST_ENDPOINTS")
+    record_endpoint = endpoints.get(pid_type)
+    default_media_type = record_endpoint.get("default_media_type")
+    histogram_serializers = {"application/json": histogram_stats_response}
+
+    histogram_stats_view_func = resource_cls.as_view(
+        resource_cls.view_name,
+        serializers=histogram_serializers,
+        default_media_type=default_media_type,
+        ctx={},
+    )
+    blueprint.add_url_rule(
+        f"{url_prefix}/stats",
+        view_func=histogram_stats_view_func,
+        methods=["GET"],
+    )

invenio_app_ils/stats/processors.py

@@ -8,6 +8,12 @@
 
 """ILS stats preprocessors."""
 
+from invenio_circulation.proxies import current_circulation
+from invenio_search.engine import search
+from invenio_stats.processors import EventsIndexer
+
+from invenio_app_ils.indexer import wait_es_refresh
+
 
 def add_record_change_ids(doc):
     """Add unique_id and aggregation_id to the doc."""
@@ -28,3 +34,53 @@ def add_record_change_ids(doc):
         doc["unique_id"] += f"__{doc['user_id']}"
 
     return doc
+
+
+def add_loan_transition_unique_id(doc):
+    """Add unique_id to the doc for a loan transition event."""
+
+    doc["unique_id"] = f"{doc['pid_value']}__{doc['trigger']}"
+
+    return doc
+
+
+class LoansEventsIndexer(EventsIndexer):
+    """Events indexer for events related to loans.
+
+    Triggers a reindex on affected loans
+    """
+
+    def run(self):
+        """Process events queue and reindex affected loans.
+
+        First index invenio-stats events that are related to loans.
+        Afterwards trigger a reindex of the loans for which an event occurred.
+        The loan indexer can then consume the updated invenio-stats events index.
+        This reindex is triggered so the loan index has up-to-date information.
+
+        Example:
+            When a loan is requested, an event is placed in the queue that stores the
+            loan PID and how many items were available at the time of the request.
+            When the event is indexed with this class, it is moved from the queue into
+            the events index. Afterwards, the loan is reindexed and, during this
+            process, the loan indexer gets the state of the document from the events index.
+        """
+
+        # Collect all loan events that occurred from the queue and index them
+        actions = [action for action in self.actionsiter()]
+        res = search.helpers.bulk(self.client, actions, stats_only=True, chunk_size=50)
+
+        # Refresh changed event indices so new entries are immediately available
+        indices = {action["_index"] for action in actions}
+        for index in indices:
+            wait_es_refresh(index)
+
+        # Reindex loans that had events to ensure their index contains the most recent information
+        loan_pids = {action["_source"]["pid_value"] for action in actions}
+        loan_indexer = current_circulation.loan_indexer()
+        loan_cls = current_circulation.loan_record_cls
+        for loan_pid in loan_pids:
+            loan = loan_cls.get_record_by_pid(loan_pid)
+            loan_indexer.index(loan)
+
+        return res

invenio_app_ils/stats/templates/aggregations/loan_transitions/__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.
+
+"""Loan transitions aggregation templates."""

invenio_app_ils/stats/templates/aggregations/loan_transitions/os-v2/__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.
+
+"""Loan transitions aggregation templates."""