Koha/REST/V1/Patrons/Account.pm

   1 package Koha::REST::V1::Patrons::Account;
   2
   3 # This file is part of Koha.
   4 #
   5 # Koha is free software; you can redistribute it and/or modify it under the
   6 # terms of the GNU General Public License as published by the Free Software
   7 # Foundation; either version 3 of the License, or (at your option) any later
   8 # version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  12 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU General Public License along
  15 # with Koha; if not, write to the Free Software Foundation, Inc.,
  16 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17
  18 use Modern::Perl;
  19
  20 use Mojo::Base 'Mojolicious::Controller';
  21
  22 use Koha::Patrons;
  23
  24 use Scalar::Util qw(blessed);
  25 use Try::Tiny;
  26
  27 =head1 NAME
  28
  29 Koha::REST::V1::Patrons::Account
  30
  31 =head1 API
  32
  33 =head2 Methods
  34
  35 =head3 get
  36
  37 Controller function that handles retrieving a patron's account balance
  38
  39 =cut
  40
  41 sub get {
  42     my $c = shift->openapi->valid_input or return;
  43
  44     my $patron_id = $c->validation->param('patron_id');
  45     my $patron    = Koha::Patrons->find($patron_id);
  46
  47     unless ($patron) {
  48         return $c->render( status => 404, openapi => { error => "Patron not found." } );
  49     }
  50
  51     my $account = $patron->account;
  52     my $balance;
  53
  54     $balance->{balance} = $account->balance;
  55
  56     # get outstanding debits and credits
  57     my $debits  = $account->outstanding_debits;
  58     my $credits = $account->outstanding_credits;
  59
  60     my @debit_lines = map { _to_api( $_->TO_JSON ) } @{ $debits->as_list };
  61     $balance->{outstanding_debits} = {
  62         total => $debits->total_outstanding,
  63         lines => \@debit_lines
  64     };
  65
  66     my @credit_lines = map { _to_api( $_->TO_JSON ) } @{ $credits->as_list };
  67     $balance->{outstanding_credits} = {
  68         total => $credits->total_outstanding,
  69         lines => \@credit_lines
  70     };
  71
  72     return $c->render( status => 200, openapi => $balance );
  73 }
  74
  75 =head3 add_credit
  76
  77 Controller function that handles adding a credit to a patron's account
  78
  79 =cut
  80
  81 sub add_credit {
  82     my $c = shift->openapi->valid_input or return;
  83
  84     my $patron_id = $c->validation->param('patron_id');
  85     my $patron    = Koha::Patrons->find($patron_id);
  86     my $user      = $c->stash('koha.user');
  87
  88
  89     unless ($patron) {
  90         return $c->render( status => 404, openapi => { error => "Patron not found." } );
  91     }
  92
  93     my $account = $patron->account;
  94     my $body    = $c->validation->param('body');
  95
  96     return try {
  97         my $credit_type = $body->{credit_type} || 'payment';    # default to 'payment'
  98         my $amount = $body->{amount};                           # mandatory, validated by openapi
  99
 100         unless ( $amount > 0 ) {  # until we support newer JSON::Validator and thus minimumExclusive
 101             Koha::Exceptions::BadParameter->throw( { parameter => 'amount' } );
 102         }
 103
 104         # read the rest of the params
 105         my $payment_type = $body->{payment_type};
 106         my $description  = $body->{description};
 107         my $note         = $body->{note};
 108
 109         my $credit = $account->add_credit(
 110             {   amount       => $amount,
 111                 credit_type  => $credit_type,
 112                 payment_type => $payment_type,
 113                 description  => $description,
 114                 note         => $note,
 115                 user_id      => $user->id
 116             }
 117         );
 118         $credit->discard_changes;
 119
 120         my $date = $body->{date};
 121         $credit->date( $date )->store
 122             if $date;
 123
 124         my $debits_ids = $body->{account_lines_ids};
 125         my $debits;
 126         $debits = Koha::Account::Lines->search({ accountlines_id => { -in => $debits_ids } })
 127             if $debits_ids;
 128
 129         my $outstanding_credit = $credit->amountoutstanding;
 130         if ($debits) {
 131             # pay them!
 132             $outstanding_credit = $credit->apply({ debits => $debits, offset_type => 'payment' });
 133         }
 134
 135         if ($outstanding_credit) {
 136             my $outstanding_debits = $account->outstanding_debits;
 137             $credit->apply({ debits => $outstanding_debits, offset_type => 'payment' });
 138         }
 139
 140         return $c->render( status => 200, openapi => { account_line_id => $credit->id } );
 141     }
 142     catch {
 143         if ( blessed $_ && $_->can('rethrow') ) {
 144             return $c->render(
 145                 status  => 400,
 146                 openapi => { error => "$_" }
 147             );
 148         }
 149         else {
 150             # Exception, rely on the stringified exception
 151             return $c->render(
 152                 status  => 500,
 153                 openapi => { error => "Something went wrong, check the logs" }
 154             );
 155         }
 156     };
 157 }
 158
 159
 160 =head3 _to_api
 161
 162 Helper function that maps unblessed Koha::Account::Line objects
 163 into REST API attribute names.
 164
 165 =cut
 166
 167 sub _to_api {
 168     my $account_line = shift;
 169
 170     # Rename attributes
 171     foreach my $column ( keys %{ $Koha::REST::V1::Patrons::Account::to_api_mapping } ) {
 172         my $mapped_column = $Koha::REST::V1::Patrons::Account::to_api_mapping->{$column};
 173         if (    exists $account_line->{ $column }
 174              && defined $mapped_column )
 175         {
 176             # key != undef
 177             $account_line->{ $mapped_column } = delete $account_line->{ $column };
 178         }
 179         elsif (    exists $account_line->{ $column }
 180                 && !defined $mapped_column )
 181         {
 182             # key == undef
 183             delete $account_line->{ $column };
 184         }
 185     }
 186
 187     return $account_line;
 188 }
 189
 190 =head3 _to_model
 191
 192 Helper function that maps REST API objects into Koha::Account::Line
 193 attribute names.
 194
 195 =cut
 196
 197 sub _to_model {
 198     my $account_line = shift;
 199
 200     foreach my $attribute ( keys %{ $Koha::REST::V1::Patrons::Account::to_model_mapping } ) {
 201         my $mapped_attribute = $Koha::REST::V1::Patrons::Account::to_model_mapping->{$attribute};
 202         if (    exists $account_line->{ $attribute }
 203              && defined $mapped_attribute )
 204         {
 205             # key => !undef
 206             $account_line->{ $mapped_attribute } = delete $account_line->{ $attribute };
 207         }
 208         elsif (    exists $account_line->{ $attribute }
 209                 && !defined $mapped_attribute )
 210         {
 211             # key => undef / to be deleted
 212             delete $account_line->{ $attribute };
 213         }
 214     }
 215
 216     return $account_line;
 217 }
 218
 219 =head2 Global variables
 220
 221 =head3 $to_api_mapping
 222
 223 =cut
 224
 225 our $to_api_mapping = {
 226     accountlines_id   => 'account_line_id',
 227     accountno         => undef,                  # removed
 228     accounttype       => 'account_type',
 229     amountoutstanding => 'amount_outstanding',
 230     borrowernumber    => 'patron_id',
 231     dispute           => undef,
 232     issue_id          => 'checkout_id',
 233     itemnumber        => 'item_id',
 234     manager_id        => 'user_id',
 235     note              => 'internal_note',
 236 };
 237
 238 =head3 $to_model_mapping
 239
 240 =cut
 241
 242 our $to_model_mapping = {
 243     account_line_id    => 'accountlines_id',
 244     account_type       => 'accounttype',
 245     amount_outstanding => 'amountoutstanding',
 246     checkout_id        => 'issue_id',
 247     internal_note      => 'note',
 248     item_id            => 'itemnumber',
 249     patron_id          => 'borrowernumber',
 250     user_id            => 'manager_id'
 251 };
 252
 253 1;