invenio-app-ils 4.2.0__py2.py3-none-any.whl → 4.4.0__py2.py3-none-any.whl

invenio_app_ils/__init__.py

@@ -7,6 +7,6 @@
 
 """invenio-app-ils."""
 
-__version__ = "4.2.0"
+__version__ = "4.4.0"
 
 __all__ = ("__version__",)

invenio_app_ils/circulation/api.py

@@ -30,10 +30,15 @@ from invenio_app_ils.circulation.search import (
     get_all_expiring_or_overdue_loans_by_patron_pid,
 )
 from invenio_app_ils.errors import (
+    DocumentOverbookedError,
     IlsException,
     InvalidLoanExtendError,
     InvalidParameterError,
+    ItemCannotCirculateError,
+    ItemHasActiveLoanError,
+    ItemNotFoundError,
     MissingRequiredParameterError,
+    MultipleItemsBarcodeFoundError,
     PatronHasLoanOnDocumentError,
     PatronHasLoanOnItemError,
     PatronHasRequestOnDocumentError,
@@ -119,7 +124,7 @@ def request_loan(
     patron_pid,
     transaction_location_pid,
     transaction_user_pid=None,
-    **kwargs
+    **kwargs,
 ):
     """Create a new loan and trigger the first transition to PENDING."""
     loan_cls = current_circulation.loan_record_cls
@@ -170,13 +175,54 @@ def patron_has_active_loan_on_item(patron_pid, item_pid):
     return search_result.hits.total.value > 0
 
 
+def _checkout_loan(
+    item_pid,
+    patron_pid,
+    transaction_location_pid,
+    trigger="checkout",
+    transaction_user_pid=None,
+    delivery=None,
+    **kwargs,
+):
+    """Checkout a loan."""
+    transaction_user_pid = transaction_user_pid or str(current_user.id)
+    loan_cls = current_circulation.loan_record_cls
+    # create a new loan
+    record_uuid = uuid.uuid4()
+    new_loan = dict(
+        patron_pid=patron_pid,
+        transaction_location_pid=transaction_location_pid,
+        transaction_user_pid=transaction_user_pid,
+    )
+
+    if delivery:
+        new_loan["delivery"] = delivery
+    # check if there is an existing request
+    loan = patron_has_request_on_document(patron_pid, kwargs.get("document_pid"))
+    if loan:
+        loan = loan_cls.get_record_by_pid(loan.pid)
+        pid = IlsCirculationLoanIdProvider.get(loan["pid"]).pid
+        loan.update(new_loan)
+    else:
+        pid = ils_circulation_loan_pid_minter(record_uuid, data=new_loan)
+        loan = loan_cls.create(data=new_loan, id_=record_uuid)
+
+    params = deepcopy(loan)
+    params.update(item_pid=item_pid, **kwargs)
+
+    loan = current_circulation.circulation.trigger(
+        loan, **dict(params, trigger=trigger)
+    )
+    return pid, loan
+
+
 def checkout_loan(
     item_pid,
     patron_pid,
     transaction_location_pid,
     transaction_user_pid=None,
     force=False,
-    **kwargs
+    **kwargs,
 ):
     """Create a new loan and trigger the first transition to ITEM_ON_LOAN.
 
@@ -191,7 +237,7 @@ def checkout_loan(
         the checkout. If False, the checkout will fail when the item cannot
         circulate.
     """
-    loan_cls = current_circulation.loan_record_cls
+
     if patron_has_active_loan_on_item(patron_pid=patron_pid, item_pid=item_pid):
         raise PatronHasLoanOnItemError(patron_pid, item_pid)
     optional_delivery = kwargs.get("delivery")
@@ -201,35 +247,86 @@ def checkout_loan(
     if force:
         _set_item_to_can_circulate(item_pid)
 
-    transaction_user_pid = transaction_user_pid or str(current_user.id)
-
-    # create a new loan
-    record_uuid = uuid.uuid4()
-    new_loan = dict(
-        patron_pid=patron_pid,
-        transaction_location_pid=transaction_location_pid,
+    return _checkout_loan(
+        item_pid,
+        patron_pid,
+        transaction_location_pid,
         transaction_user_pid=transaction_user_pid,
+        **kwargs,
     )
 
-    # check if there is an existing request
-    loan = patron_has_request_on_document(patron_pid, kwargs.get("document_pid"))
-    if loan:
-        loan = loan_cls.get_record_by_pid(loan.pid)
-        pid = IlsCirculationLoanIdProvider.get(loan["pid"]).pid
-        loan.update(new_loan)
-    else:
-        pid = ils_circulation_loan_pid_minter(record_uuid, data=new_loan)
-        loan = loan_cls.create(data=new_loan, id_=record_uuid)
 
-    params = deepcopy(loan)
-    params.update(item_pid=item_pid, **kwargs)
+def _ensure_item_loanable_via_self_checkout(item_pid):
+    """Self-checkout: return loanable item or raise when not loanable.
 
-    # trigger the transition to request
-    loan = current_circulation.circulation.trigger(
-        loan, **dict(params, trigger="checkout")
+    Implements the self-checkout rules to loan an item.
+    """
+    item = current_app_ils.item_record_cls.get_record_by_pid(item_pid)
+    item_dict = item.replace_refs()
+
+    if item_dict["status"] != "CAN_CIRCULATE":
+        raise ItemCannotCirculateError()
+
+    circulation_state = item_dict["circulation"].get("state")
+    has_active_loan = (
+        circulation_state and circulation_state in CIRCULATION_STATES_LOAN_ACTIVE
     )
+    if has_active_loan:
+        raise ItemHasActiveLoanError(loan_pid=item_dict["circulation"]["loan_pid"])
 
-    return pid, loan
+    document = current_app_ils.document_record_cls.get_record_by_pid(
+        item_dict["document_pid"]
+    )
+    document_dict = document.replace_refs()
+    if document_dict["circulation"].get("overbooked", False):
+        raise DocumentOverbookedError(
+            f"Cannot self-checkout the overbooked document {item_dict['document_pid']}"
+        )
+
+    return item
+
+
+def self_checkout_get_item_by_barcode(barcode):
+    """Search for an item by barcode.
+
+    :param barcode: the barcode of the item to search for
+    :return item: the item that was found, or raise in case of errors
+    """
+    item_search = current_app_ils.item_search_cls()
+    items = item_search.search_by_barcode(barcode).execute()
+    if items.hits.total.value == 0:
+        raise ItemNotFoundError(barcode=barcode)
+    if items.hits.total.value > 1:
+        raise MultipleItemsBarcodeFoundError(barcode)
+
+    item_pid = items.hits[0].pid
+    item = _ensure_item_loanable_via_self_checkout(item_pid)
+    return item_pid, item
+
+
+def self_checkout(
+    item_pid, patron_pid, transaction_location_pid, transaction_user_pid=None, **kwargs
+):
+    """Perform self-checkout.
+
+    :param item_pid: a dict containing `value` and `type` fields to
+        uniquely identify the item.
+    :param patron_pid: the PID value of the patron
+    :param transaction_location_pid: the PID value of the location where the
+        checkout is performed
+    :param transaction_user_pid: the PID value of the user that performed the
+        checkout
+    """
+    _ensure_item_loanable_via_self_checkout(item_pid["value"])
+    return _checkout_loan(
+        item_pid,
+        patron_pid,
+        transaction_location_pid,
+        transaction_user_pid=transaction_user_pid,
+        trigger="self_checkout",
+        delivery=dict(method="SELF-CHECKOUT"),
+        **kwargs,
+    )
 
 
 def bulk_extend_loans(patron_pid, **kwargs):
@@ -253,7 +350,7 @@ def bulk_extend_loans(patron_pid, **kwargs):
                     params,
                     trigger="extend",
                     transition_kwargs=dict(send_notification=False),
-                )
+                ),
             )
             extended_loans.append(extended_loan)
         except (CirculationException, InvalidLoanExtendError):

invenio_app_ils/circulation/config.py

@@ -44,7 +44,6 @@ from invenio_app_ils.permissions import (
     PatronOwnerPermission,
     authenticated_user_permission,
     backoffice_permission,
-    loan_checkout_permission,
     loan_extend_circulation_permission,
     patron_owner_permission,
     superuser_permission,
@@ -84,6 +83,7 @@ ILS_CIRCULATION_LOAN_WILL_EXPIRE_DAYS = 7
 ILS_CIRCULATION_DELIVERY_METHODS = {
     "PICKUP": "Pick it up at the library desk",
     "DELIVERY": "Have it delivered to my office",
+    "SELF-CHECKOUT": "Self-checkout",
 }
 
 # Notification message creator for loan notifications
@@ -162,7 +162,13 @@ CIRCULATION_LOAN_TRANSITIONS = {
             dest="ITEM_ON_LOAN",
             trigger="checkout",
             transition=ILSToItemOnLoan,
-            permission_factory=loan_checkout_permission,
+            permission_factory=backoffice_permission,
+        ),
+        dict(
+            dest="ITEM_ON_LOAN",
+            trigger="self_checkout",
+            transition=ILSToItemOnLoan,
+            permission_factory=authenticated_user_permission,
         ),
     ],
     "PENDING": [
@@ -172,6 +178,12 @@ CIRCULATION_LOAN_TRANSITIONS = {
             transition=ILSToItemOnLoan,
             permission_factory=backoffice_permission,
         ),
+        dict(
+            dest="ITEM_ON_LOAN",
+            trigger="self_checkout",
+            transition=ILSToItemOnLoan,
+            permission_factory=authenticated_user_permission,
+        ),
         dict(
             dest="CANCELLED",
             trigger="cancel",

invenio_app_ils/circulation/loaders/__init__.py

@@ -12,9 +12,11 @@ from invenio_app_ils.records.loaders import ils_marshmallow_loader
 from .schemas.json.bulk_extend import BulkExtendLoansSchemaV1
 from .schemas.json.loan_checkout import LoanCheckoutSchemaV1
 from .schemas.json.loan_request import LoanRequestSchemaV1
+from .schemas.json.loan_self_checkout import LoanSelfCheckoutSchemaV1
 from .schemas.json.loan_update_dates import LoanUpdateDatesSchemaV1
 
 loan_request_loader = ils_marshmallow_loader(LoanRequestSchemaV1)
 loan_checkout_loader = ils_marshmallow_loader(LoanCheckoutSchemaV1)
+loan_self_checkout_loader = ils_marshmallow_loader(LoanSelfCheckoutSchemaV1)
 loan_update_dates_loader = ils_marshmallow_loader(LoanUpdateDatesSchemaV1)
 loans_bulk_update_loader = ils_marshmallow_loader(BulkExtendLoansSchemaV1)

invenio_app_ils/circulation/loaders/schemas/json/loan_self_checkout.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2019 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 circulation Loan Checkout loader JSON schema."""
+
+from invenio_circulation.records.loaders.schemas.json import LoanItemPIDSchemaV1
+from marshmallow import fields
+
+from .base import LoanBaseSchemaV1
+
+
+class LoanSelfCheckoutSchemaV1(LoanBaseSchemaV1):
+    """Loan self-checkout schema."""
+
+    item_pid = fields.Nested(LoanItemPIDSchemaV1, required=True)

invenio_app_ils/circulation/notifications/messages.py

@@ -25,6 +25,7 @@ class NotificationLoanMsg(NotificationMsg):
         request="request.html",
         request_no_items="request_no_items.html",
         checkout="checkout.html",
+        self_checkout="self_checkout.html",
         checkin="checkin.html",
         extend="extend.html",
         cancel="cancel.html",

invenio_app_ils/circulation/serializers/__init__.py

@@ -6,6 +6,7 @@
 # under the terms of the MIT License; see LICENSE file for more details.
 
 """Loan serializers."""
+
 from invenio_records_rest.serializers.response import search_responsify
 
 from invenio_app_ils.records.schemas.json import ILSRecordSchemaJSONV1

invenio_app_ils/circulation/serializers/response.py

@@ -6,6 +6,7 @@
 # under the terms of the MIT License; see LICENSE file for more details.
 
 """Response serializers for circulation module."""
+
 import json
 
 from flask import current_app

invenio_app_ils/circulation/templates/invenio_app_ils_circulation/notifications/self_checkout.html

@@ -0,0 +1,19 @@
+{% block title %}
+InvenioILS: loan started for "{{ document.title|safe }}"
+{% endblock %}
+
+{% block body_plain %}
+Dear {{ patron.name }},
+
+your self-checkout loan for "{{ document.full_title }}" <{{ spa_routes.HOST }}{{ spa_routes.PATHS['literature']|format(pid=document.pid) }}> has started.
+
+The due date is {{ loan.end_date }}.
+{% endblock %}
+
+{% block body_html %}
+Dear {{ patron.name }}, <br/><br/>
+
+your self-checkout loan for <a href="{{ spa_routes.HOST }}{{ spa_routes.PATHS['literature']|format(pid=document.pid) }}">"{{ document.full_title }}"</a> has <b>started</b>. <br/><br/>
+
+<b>The due date is {{ loan.end_date }}</b>.<br/>
+{% endblock %}

invenio_app_ils/circulation/views.py

@@ -7,7 +7,7 @@
 
 """Invenio App ILS Circulation views."""
 
-from flask import Blueprint, abort
+from flask import Blueprint, abort, request
 from flask_login import current_user
 from invenio_circulation.links import loan_links_factory
 from invenio_circulation.pidstore.pids import CIRCULATION_LOAN_PID_TYPE
@@ -18,15 +18,35 @@ from invenio_rest import ContentNegotiatedMethodView
 from invenio_app_ils.circulation.loaders import (
     loan_checkout_loader,
     loan_request_loader,
+    loan_self_checkout_loader,
     loan_update_dates_loader,
     loans_bulk_update_loader,
 )
 from invenio_app_ils.circulation.utils import circulation_overdue_loan_days
-from invenio_app_ils.errors import OverdueLoansNotificationError
+from invenio_app_ils.errors import (
+    DocumentOverbookedError,
+    ItemCannotCirculateError,
+    ItemHasActiveLoanError,
+    ItemNotFoundError,
+    LoanSelfCheckoutDocumentOverbooked,
+    LoanSelfCheckoutItemActiveLoan,
+    LoanSelfCheckoutItemInvalidStatus,
+    LoanSelfCheckoutItemNotFound,
+    MissingRequiredParameterError,
+    OverdueLoansNotificationError,
+)
+from invenio_app_ils.items.api import ITEM_PID_TYPE
 from invenio_app_ils.permissions import need_permissions
 
 from ..patrons.api import patron_exists
-from .api import bulk_extend_loans, checkout_loan, request_loan, update_dates_loan
+from .api import (
+    bulk_extend_loans,
+    checkout_loan,
+    request_loan,
+    self_checkout,
+    self_checkout_get_item_by_barcode,
+    update_dates_loan,
+)
 from .notifications.api import (
     send_bulk_extend_notification,
     send_loan_overdue_reminder_notification,
@@ -43,73 +63,97 @@ def create_circulation_blueprint(app):
         url_prefix="",
     )
 
-    endpoints = app.config.get("RECORDS_REST_ENDPOINTS", [])
-    options = endpoints.get(CIRCULATION_LOAN_PID_TYPE, {})
+    options = app.config["RECORDS_REST_ENDPOINTS"][CIRCULATION_LOAN_PID_TYPE]
     default_media_type = options.get("default_media_type", "")
     rec_serializers = options.get("record_serializers", {})
     serializers = {
         mime: obj_or_import_string(func) for mime, func in rec_serializers.items()
     }
 
-    bulk_loan_extension_serializers = {"application/json": bulk_extend_v1_response}
-
+    # /request
     loan_request = LoanRequestResource.as_view(
         LoanRequestResource.view_name,
         serializers=serializers,
         default_media_type=default_media_type,
         ctx=dict(links_factory=loan_links_factory, loader=loan_request_loader),
     )
-
     blueprint.add_url_rule(
         "/circulation/loans/request", view_func=loan_request, methods=["POST"]
     )
 
+    # /checkout
     loan_checkout = LoanCheckoutResource.as_view(
         LoanCheckoutResource.view_name,
         serializers=serializers,
         default_media_type=default_media_type,
         ctx=dict(links_factory=loan_links_factory, loader=loan_checkout_loader),
     )
-
     blueprint.add_url_rule(
         "/circulation/loans/checkout",
         view_func=loan_checkout,
         methods=["POST"],
     )
 
+    # /self-checkout
+    item_rec_serializers = app.config["RECORDS_REST_ENDPOINTS"][ITEM_PID_TYPE].get(
+        "record_serializers", {}
+    )
+    item_serializers = {
+        mime: obj_or_import_string(func) for mime, func in item_rec_serializers.items()
+    }
+    loan_self_checkout_item = LoanSelfCheckoutResource.as_view(
+        LoanSelfCheckoutResource.view_name,
+        serializers={},  # required, even if `method_serializers` will override it
+        method_serializers={
+            "GET": item_serializers,
+            "POST": serializers,  # default loan serializers
+        },
+        default_media_type=default_media_type,
+        ctx=dict(
+            loan_links_factory=loan_links_factory, loader=loan_self_checkout_loader
+        ),
+    )
+    blueprint.add_url_rule(
+        "/circulation/loans/self-checkout",
+        view_func=loan_self_checkout_item,
+        methods=["GET", "POST"],
+    )
+
+    # /notification-overdue
     loan_notification_overdue = LoanNotificationResource.as_view(
         LoanNotificationResource.view_name.format(CIRCULATION_LOAN_PID_TYPE),
         serializers=serializers,
         default_media_type=default_media_type,
         ctx=dict(links_factory=loan_links_factory),
     )
-
     blueprint.add_url_rule(
         "{0}/notification-overdue".format(options["item_route"]),
         view_func=loan_notification_overdue,
         methods=["POST"],
     )
 
+    # /bulk-extend
+    bulk_loan_extension_serializers = {"application/json": bulk_extend_v1_response}
+
     bulk_loan_extension = BulkLoanExtensionResource.as_view(
         BulkLoanExtensionResource.view_name,
         serializers=bulk_loan_extension_serializers,
         default_media_type=default_media_type,
         ctx=dict(loader=loans_bulk_update_loader),
     )
-
     blueprint.add_url_rule(
         "/circulation/bulk-extend",
         view_func=bulk_loan_extension,
         methods=["POST"],
     )
 
+    # /update-dates
     loan_update = LoanUpdateDatesResource.as_view(
         LoanUpdateDatesResource.view_name.format(CIRCULATION_LOAN_PID_TYPE),
         serializers=serializers,
         default_media_type=default_media_type,
         ctx=dict(links_factory=loan_links_factory, loader=loan_update_dates_loader),
     )
-
     blueprint.add_url_rule(
         "{0}/update-dates".format(options["item_route"]),
         view_func=loan_update,
@@ -157,6 +201,50 @@ class LoanCheckoutResource(IlsCirculationResource):
         return self.make_response(pid, loan, 202, links_factory=self.links_factory)
 
 
+class LoanSelfCheckoutResource(IlsCirculationResource):
+    """Loan self-checkout action resource."""
+
+    view_name = "loan_self_checkout"
+
+    @need_permissions("circulation-loan-self-checkout")
+    def get(self, **kwargs):
+        """Loan self-checkout GET method to retrieve items."""
+        try:
+            barcode = request.args["barcode"].upper()
+            assert barcode
+        except (KeyError, AssertionError):
+            msg = "Parameter `barcode` is missing"
+            raise MissingRequiredParameterError(description=msg)
+
+        try:
+            pid, item = self_checkout_get_item_by_barcode(barcode)
+        except ItemCannotCirculateError:
+            raise LoanSelfCheckoutItemInvalidStatus()
+        except ItemHasActiveLoanError:
+            raise LoanSelfCheckoutItemActiveLoan()
+        except DocumentOverbookedError:
+            raise LoanSelfCheckoutDocumentOverbooked()
+        except ItemNotFoundError:
+            raise LoanSelfCheckoutItemNotFound()
+
+        return self.make_response(pid, item, 200)
+
+    @need_permissions("circulation-loan-self-checkout")
+    def post(self, **kwargs):
+        """Loan self-checkout POST method to perform the checkout."""
+        data = self.loader()
+        try:
+            pid, loan = self_checkout(**data)
+        except ItemCannotCirculateError:
+            raise LoanSelfCheckoutItemInvalidStatus()
+        except ItemHasActiveLoanError:
+            raise LoanSelfCheckoutItemActiveLoan()
+        except DocumentOverbookedError:
+            raise LoanSelfCheckoutDocumentOverbooked()
+
+        return self.make_response(pid, loan, 202, links_factory=self.loan_links_factory)
+
+
 class BulkLoanExtensionResource(IlsCirculationResource):
     """Bulk loan extension resource."""