From af6773d1e6631ce67c6902356c551069abe60a70 Mon Sep 17 00:00:00 2001
From: Alex Arnaud <alex.arnaud@biblibre.com>
Date: Wed, 10 Apr 2024 14:03:14 +0200
Subject: [PATCH] Bug 22613: Add GET endpoint /patrons/{patron_id}/checkouts

This patch adds a new endpoint, for fetching checkouts from a specific
patron.

Test plan:

1. Apply this patch
2. Run:
   $ ktd --shell
  k$ prove t/db_dependent/api/v1/patrons_checkouts.t
=> SUCCESS: Tests pass!
3. Run:
   $ curl -v -s -u koha:koha --request GET \
        http://kohadev.local/api/v1/patrons/{id}/checkouts
test with query parameters (they are the same as for /patrons/{id}/holds
=> SUCCESS: The API works!
---
 Koha/REST/V1/Patrons/Checkouts.pm           | 61 ++++++++++++++
 api/v1/swagger/paths/patrons_checkouts.yaml | 63 ++++++++++++++
 api/v1/swagger/swagger.yaml                 |  2 +
 t/db_dependent/api/v1/patrons_checkouts.t   | 92 +++++++++++++++++++++
 4 files changed, 218 insertions(+)
 create mode 100644 Koha/REST/V1/Patrons/Checkouts.pm
 create mode 100644 api/v1/swagger/paths/patrons_checkouts.yaml
 create mode 100755 t/db_dependent/api/v1/patrons_checkouts.t

diff --git a/Koha/REST/V1/Patrons/Checkouts.pm b/Koha/REST/V1/Patrons/Checkouts.pm
new file mode 100644
index 00000000000..bce1bedee0b
--- /dev/null
+++ b/Koha/REST/V1/Patrons/Checkouts.pm
@@ -0,0 +1,61 @@
+package Koha::REST::V1::Patrons::Checkouts;
+
+# This file is part of Koha.
+#
+# Koha is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# Koha 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Koha; if not, see <http://www.gnu.org/licenses>.
+
+use Modern::Perl;
+
+use Mojo::Base 'Mojolicious::Controller';
+
+use Koha::Patrons;
+
+=head1 NAME
+
+Koha::REST::V1::Patrons::Checkouts
+
+=head1 API
+
+=head2 Methods
+
+=head3 list
+
+Controller function that handles listing Koha::Checkout objects for the requested patron
+
+=cut
+
+sub list {
+    my $c = shift->openapi->valid_input or return;
+
+    my $patron = Koha::Patrons->find( $c->param('patron_id') );
+
+    unless ($patron) {
+        return $c->render(
+            status  => 404,
+            openapi => { error => 'Patron not found' }
+        );
+    }
+
+    return try {
+
+        return $c->render(
+            status  => 200,
+            openapi => $c->objects->search( $patron->checkouts ),
+        );
+    } catch {
+        $c->unhandled_exception($_);
+    };
+}
+
+1;
diff --git a/api/v1/swagger/paths/patrons_checkouts.yaml b/api/v1/swagger/paths/patrons_checkouts.yaml
new file mode 100644
index 00000000000..b5d35634267
--- /dev/null
+++ b/api/v1/swagger/paths/patrons_checkouts.yaml
@@ -0,0 +1,63 @@
+---
+"/patrons/{patron_id}/checkouts":
+  get:
+    x-mojo-to: Patrons::Checkouts#list
+    operationId: getPatronCheckouts
+    tags:
+      - checkouts
+    summary: List checkouts for a patron
+    parameters:
+      - $ref: "../swagger.yaml#/parameters/patron_id_pp"
+      - $ref: "../swagger.yaml#/parameters/match"
+      - $ref: "../swagger.yaml#/parameters/order_by"
+      - $ref: "../swagger.yaml#/parameters/page"
+      - $ref: "../swagger.yaml#/parameters/per_page"
+      - $ref: "../swagger.yaml#/parameters/q_param"
+      - $ref: "../swagger.yaml#/parameters/q_body"
+      - $ref: "../swagger.yaml#/parameters/request_id_header"
+      - name: x-koha-embed
+        in: header
+        required: false
+        description: Embed list sent as a request header
+        type: array
+        items:
+          type: string
+          enum:
+            - cancellation_requested
+        collectionFormat: csv
+    produces:
+      - application/json
+    responses:
+      "200":
+        description: The patron checkouts
+        schema:
+          type: array
+          items:
+            $ref: "../swagger.yaml#/definitions/checkout"
+      "401":
+        description: Authentication required
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "403":
+        description: Access forbidden
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "404":
+        description: Patron not found
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "500":
+        description: |
+          Internal server error. Possible `error_code` attribute values:
+
+          * `internal_server_error`
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "503":
+        description: Under maintenance
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+    x-koha-authorization:
+      permissions:
+        - circulate: circulate_remaining_permissions
+        - circulate: manage_bookings
diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml
index 8b80908dcd1..a2aa11e4bf9 100644
--- a/api/v1/swagger/swagger.yaml
+++ b/api/v1/swagger/swagger.yaml
@@ -427,6 +427,8 @@ paths:
     $ref: "./paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes~1{extended_attribute_id}"
   "/patrons/{patron_id}/holds":
     $ref: "./paths/patrons_holds.yaml#/~1patrons~1{patron_id}~1holds"
+  "/patrons/{patron_id}/checkouts":
+    $ref: "./paths/patrons_checkouts.yaml#/~1patrons~1{patron_id}~1checkouts"
   "/patrons/{patron_id}/password":
     $ref: "./paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password"
   "/patrons/{patron_id}/password/expiration_date":
diff --git a/t/db_dependent/api/v1/patrons_checkouts.t b/t/db_dependent/api/v1/patrons_checkouts.t
new file mode 100755
index 00000000000..05a78787dac
--- /dev/null
+++ b/t/db_dependent/api/v1/patrons_checkouts.t
@@ -0,0 +1,92 @@
+#!/usr/bin/env perl
+
+# This file is part of Koha.
+#
+# Koha is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# Koha 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Koha; if not, see <http://www.gnu.org/licenses>.
+
+use Modern::Perl;
+
+use Test::More tests => 1;
+use Test::MockModule;
+use Test::Mojo;
+
+use t::lib::TestBuilder;
+use t::lib::Mocks;
+
+use Koha::Database;
+use Koha::DateUtils qw(dt_from_string);
+
+my $schema  = Koha::Database->new->schema;
+my $builder = t::lib::TestBuilder->new();
+
+my $t = Test::Mojo->new('Koha::REST::V1');
+
+t::lib::Mocks::mock_preference( 'RESTBasicAuth', 1 );
+
+subtest 'Patron checkouts list() tests' => sub {
+
+    plan tests => 13;
+
+    $schema->storage->txn_begin;
+
+    my $librarian = $builder->build_object(
+        {
+            class => 'Koha::Patrons',
+            value => { flags => 2 }
+        }
+    );
+    my $password = 'thePassword123';
+    $librarian->set_password( { password => $password, skip_validation => 1 } );
+    my $userid = $librarian->userid;
+
+    my $patron = $builder->build_object(
+        {
+            class => 'Koha::Patrons',
+            value => { flags => 0 }
+        }
+    );
+
+    $t->get_ok( "//$userid:$password@/api/v1/patrons/" . $patron->id . '/checkouts' )->status_is(200)->json_is( [] );
+
+    my $date_due = dt_from_string->add( weeks => 2 );
+    my $item1    = $builder->build_sample_item;
+    my $item2    = $builder->build_sample_item;
+
+    my $issue1 = C4::Circulation::AddIssue( $patron, $item1->barcode, $date_due );
+    my $issue2 = C4::Circulation::AddIssue( $patron, $item2->barcode, $date_due );
+
+    $t->get_ok( "//$userid:$password@/api/v1/patrons/" . $patron->id . '/checkouts' )->status_is(200)
+        ->json_is( '/0/item_id' => $item1->itemnumber )->json_is( '/1/item_id' => $item2->itemnumber );
+
+    my $non_existent_patron    = $builder->build_object( { class => 'Koha::Patrons' } );
+    my $non_existent_patron_id = $non_existent_patron->id;
+    $non_existent_patron->delete;
+
+    $t->get_ok( "//$userid:$password@/api/v1/patrons/" . $non_existent_patron_id . '/checkouts' )->status_is(404)
+        ->json_is( '/error' => 'Patron not found' );
+
+    my $unauthorized_patron = $builder->build_object(
+        {
+            class => 'Koha::Patrons',
+            value => { flags => 0 }
+        }
+    );
+    my $unauthorized_password = 'thePassword456';
+
+    $unauthorized_patron->set_password( { password => $unauthorized_password, skip_validation => 1 } );
+    my $unauthorized_userid = $unauthorized_patron->userid;
+
+    $t->get_ok( "//$unauthorized_userid:$unauthorized_password@/api/v1/patrons/" . $patron->id . '/checkouts' )
+        ->status_is(403)->json_is( '/error' => 'Authorization failure. Missing required permission(s).' );
+    }
-- 
2.44.0