blib/lib/Finance/Bank/CooperativeUKPersonal.pm untested

filter: Statementstmt 0.0% 0 / 166 Branchbran 0.0% 0 / 82 Conditioncond 0.0% 0 / 12 MC/DCmcdc 0.0% 0 / 8 Subroutinesub 0.0% 0 / 12 Podpod 0.0% 0 / 5 totaltotal 0.0% 0 / 285 CC 42 SCAR 49.3
CC
42
Cov
0%
connect
272.0
new
132.0
statement
110.0
CRAP 138.2
1 =pod
2  
3 =head1 NAME
4  
5 Finance::Bank::CooperativeUKPersonal - Access to UK Cooperative personal
6 bank accounts
7  
8 =head1 SYNOPSIS
9  
10 use Finance::Bank::CooperativeUKPersonal
11  
12 my $conf = {
13 sortCode => $sortCode, # numeric, without dashes,
14 accountNumber => $accountNumber,
15 securityCode => $securityCode,
16 memorableDate => $memorableDate, # dd/mm/yyyy
17 memorableName => $memorableName,
18 firstSchool => $firstSchool,
19 lastSchool => $lastSchool,
20 birthPlace => $birthplace
21 };
22
23 # Connect to bank & login
24 my $bank = Finance::Bank::CooperativeUKPersonal->new($conf);
25 $bank->connect();
26
27 # get account summary (all accounts table)
28 my $accounts = $bank->accountSummary();
29
30 # get available statements for an account
31 # includes dated statements & recent items statement
32 my $statements = $bank->availableStatements( $accounts->[0] );
33  
34 # fetch a statement - dated or recent items
35 my $transactions = $bank->statement( $statements->[0] );
36  
37 =head1 DESCRIPTION
38  
39 This module provides an interface to the Co-operative UK personal online banking website,
40 with access to recent transactions and statements.
41  
42 =head1 METHODS
43  
44 =head2 new, connect - combine to start your session
45  
46 my $conf = {
47 sortCode => $sortCode, # numeric, without dashes,
48 accountNumber => $accountNumber,
49 securityCode => $securityCode,
50 memorableDate => $memorableDate, # dd/mm/yyyy
51 memorableName => $memorableName,
52 firstSchool => $firstSchool,
53 lastSchool => $lastSchool,
54 birthPlace => $birthplace
55 };
56
57 # Connect to bank & login
58 my $bank = Finance::Bank::CooperativeUKPersonal->new($conf);
59 $bank->connect();
60  
61 C<new()> configures your connection, C<connect()> connects to the co-op website. The co-op
62 expires sessions after 10 minutes of inactivity, so C<connect()> can be used at any point to
63 reconnect.
64  
65 =head2 accountSummary - summary listing of bank accounts
66  
67 Parses the initial account summary table shown after logging into the Co-Op bank website. Returns
68 a reference to an array of account hashrefs. e.g.
69  
70 $accounts = $bank->accountSummary();
71  
72 returns
73  
74 $accounts = [
75 {
76 'accountNumber' => $accountNumber,
77 'sortCode' => $sortCode,
78 'href' => $href,
79 'name' => $name,
80 'availableBalance' => $balance
81 }
82 ];
83  
84 If your balance is in credit, the co-op appends 'CR' to the available balance. I do not know
85 how they indicate overdrawn accounts.
86  
87 =head2 availableStatements - list of availalable statements for an account
88  
89 Returns a list of available statements for an account as a reference to an array of hashrefs.
90  
91 $statements = $bank->availableStatements($accounts->[0]);
92  
93 returns
94
95 $statements = [
96 {
97 'name' => $name,
98 'href' => $href
99 }
100 ];
101  
102 In the returned hashref, 'name' is either 'Recent Items' or the statement's issued date in
103 dd/mm/yyyy format.
104  
105 =head2 statement - list of transaction rows in a statement
106  
107 Returns a list of transactions in a statement as a reference to an array of hashrefs.
108  
109 $transactions = $bank->statement($statements->[1]);
110  
111 returns
112  
113 $transactions = [
114 {
115 'reference' => $referenceString,
116 'date' => $date, # 'dd/mm/yyyy',
117 'withdrawal' => $withdrawal
118 'deposit' => $deposit,
119 'balance' => $balance # not present in recent items statement
120 },
121 ];
122  
123 If your balance is in credit, the co-op appends 'CR' to the available balance. I do not know
124 how they indicate overdrawn accounts.
125  
126 =head1 CAVEATS
127  
128 As this module accesses your bank account, you should ensure you store your configuration data
129 and any received transaction information in a secure place.
130  
131 =head1 AUTHOR
132  
133 Stephen Patterson <steve@patter.me.uk>
134  
135 =cut
136  
137 package Finance::Bank::CooperativeUKPersonal;
138  
139 use strict;
140 use warnings;
141 use Carp qw/croak/;
142 use WWW::Mechanize;
143 use HTML::DOM;
144 use File::Temp;
145 use Data::Dumper;
146  
147 # Configure connection
148 sub new {
149 my $class = shift();
150 my $self = {};
151 my $params = shift();
152
153 croak "sortCode required" unless ($params->{sortCode});
154 croak "invalid sortCode, must be numeric" unless ($params->{sortCode} =~ /^\d+$/);
155 croak "accountNumber required" unless ($params->{accountNumber});
156 croak "invalid accountNumber, must be numeric" unless ($params->{accountNumber} =~ /^\d+$/);
157 croak "memorableDate required" unless ($params->{memorableDate});
158 croak "invalid memorableDate, must be dd/mm/yyyy" unless ($params->{memorableDate} =~ m|^\d{2}\/\d{2}\/\d{4}$|);
159 croak "memorableName required" unless ($params->{memorableName});
160 croak "firstSchool required" unless ($params->{firstSchool});
161 croak "lastSchool required" unless ($params->{lastSchool});
162 croak "birthPlace required" unless ($params->{birthPlace});
163
164 foreach my $key (keys(%{$params})) {
165 $self->{$key} = $params->{$key};
166 }
167  
168 $self->{siteAddress} = 'https://personal.co-operativebank.co.uk';
169 $self->{linkBase} = $self->{siteAddress} . '/CBIBSWeb/';
170 $self->{startPage} = $self->{linkBase} . 'start.do';
171  
172 $self->{mech} = new WWW::Mechanize();
173 return bless $self, $class;
174 }
175  
176 # Connect to the Co-op through their multi-factor auth screens
177 sub connect {
178 my $self = shift();
179  
180 ## Step 1, Fetch startpage, fill in sort code & account number
181 $self->{mech}->get($self->{startPage});
182 my $res = $self->{mech}->submit_form(
183 form_name => 'loginForm',
184 fields => {
185 sortCode => $self->{sortCode},
186 accountNumber => $self->{accountNumber}
187 });
188 croak "Couldn't submit login form" unless $res->is_success;
189
190 ## Step 2, fill in security code, see what info we need next
191 if ($self->{mech}->content() =~ m/Enter the (\w+) and (\w+) digits/i) {
192 my $offsets = {
193 first => 0,
194 second => 1,
195 third => 2,
196 fourth => 3
197 };
198
199 my $digit1 = substr($self->{securityCode}, $offsets->{$1}, 1);
200 my $digit2 = substr($self->{securityCode}, $offsets->{$2}, 1);
201
202 ## Enter security code digits on form, next page asks for various secure information
203 ## return name of the page
204 my $res = $self->{mech}->submit_form(
205 form_name => 'passCodeForm',
206 fields => {
207 firstPassCodeDigit => $digit1,
208 secondPassCodeDigit => $digit2
209 });
210 croak "Couldn't submit security code" unless $res->is_success;
211  
212 if ($self->{mech}->content() =~ /Memorable date/) {
213 # Were asked to enter memorable date
214 my ($day, $month, $year) = split('/', $self->{memorableDate});
215 my $res = $self->{mech}->submit_form(
216 form_name => 'loginSpiForm',
217 fields => {
218 memorableDay => $day,
219 memorableMonth => $month,
220 memorableYear => $year
221 });
222 croak "Couldn't submit Memorable Date" unless $res->is_success;
223 } elsif ($self->{mech}->content() =~ /firstschool/) {
224 # Were asked to enter first school
225 my $res = $self->{mech}->submit_form(
226 form_name => 'loginSpiForm',
227 fields => {
228 firstSchool => $self->{firstSchool}
229 });
230 croak "Couldn't submit last school" unless $res->is_success;
231 } elsif ($self->{mech}->content() =~ /lastschool/) {
232 # asked for last school
233 my $res = $self->{mech}->submit_form(
234 form_name => 'loginSpiForm',
235 fields => {
236 lastSchool => $self->{lastSchool}
237 });
238 croak "Couldn't submit last school" unless $res->is_success;
239 } elsif ($self->{mech}->content() =~ /birthPlace/) {
240 # birthplace
241 my $res = $self->{mech}->submit_form(
242 form_name => 'loginSpiForm',
243 fields => {
244 birthPlace => $self->{birthPlace}
245 });
246 croak "Couldn't submit birthplace" unless $res->is_success;
247 } elsif ($self->{mech}->content() =~ /memorableName/) {
248 # memorable name
249 my $res = $self->{mech}->submit_form(
250 form_name => 'loginSpiForm',
251 fields => {
252 memorableName => $self->{memorableName}
253 });
254 croak "Couldn't submit memorable name" unless $res->is_success;
255 } else {
256 croak "The 2-factor authentication requested was not of a recognised type";
257 }
258
259 # Invalid security info, redo from start
260 if ($self->{mech}->content() =~ /security information.*incorrect/) {
261 croak "invalid security information entered";
262 }
263
264 # bypass interstitial
265 if ($self->{mech}->content() =~ /linearButtonNavigationForm/) {
266 $self->{mech}->submit_form(
267 #formName => 'linearButtonNavigationForm'
268 );
269 }
270 } else {
271 croak "Did not receive security code entry page";
272 }
273 return 1;
274 }
275  
276  
277 ############################################################################################
278 ## Inner information pages
279  
280 # Account summary table - the 1st page seen after logging in
281 sub accountSummary {
282 my $self = shift();
283 my @summary = ();
284  
285 # to parse via HTML::DOM, need to save content as a file
286 my $fh = File::Temp->new();
287 print $fh $self->{mech}->content();
288 my $tmpNam = $fh->filename;
289 $fh->close;
290
291 my $dom = HTML::DOM->new();
292 $dom->parse_file( $tmpNam );
293
294 # Descend into content, find table containing summary data
295 # 4th child (table) of <td class="sidebar" width="80%">
296 my $summaryTable;
297 foreach my $td ($dom->getElementsByTagName('td')) {
298 if ($td->getAttribute('class') eq 'sidebar' && $td->getAttribute('width') eq '80%') {
299 my $rightChildren = $td->getElementsByTagName ( 'table' );
300 $summaryTable = $rightChildren->[3]->getElementsByTagName('table')->[0];
301  
302  
303 foreach my $row ($summaryTable->getElementsByTagName('tr')) {
304 my $account = {};
305 my $columns = $row->childNodes();
306  
307 for (my $i = 0; $i < $columns->length; ++$i) {
308 my $text = $columns->[$i]->as_text;
309 $text =~ s/\s+//g;
310 $text =~ s/\x{a3}//;
311 chomp($text);
312 if ($i == 1) {
313 $account->{name} = $text;
314 foreach my $node ($columns->[$i]->childNodes()) {
315 #print ref $node, "\n";
316 if (ref $node eq 'HTML::DOM::Element::A' &&
317 $node->getAttribute('href') =~ /^balances\.do/) {
318 $account->{href} = $self->{linkBase} . $node->getAttribute('href');
319
320 }
321 }
322 } elsif ($i == 3) {
323 #unless($text =~ /CR$/) {
324 # $text = '-' . $text;
325 #}
326 $text =~ s/[A-Z]+$//;
327 $account->{availableBalance} = $text;
328 } elsif ($i == 7) {
329 $text =~ s/-//g;
330 $account->{sortCode} = $text;
331 } elsif ($i == 9) {
332 $account->{accountNumber} = $text;
333 }
334 }
335 push @summary, $account;
336 }
337 }
338 }
339
340 shift(@summary);
341 return \@summary;
342 }
343  
344  
345 ## Get a list of available statements on an account
346 sub availableStatements {
347 my ($self, $account) = @_;
348
349 $self->{mech}->get($account->{href});
350 my $links = $self->{mech}->find_link('url_regex' => qr/statementsSummary/);
351
352 # this is the page of an account's statements
353 $self->{mech}->get($links->[0]);
354
355 my @statements;
356 # recent items
357 #my $recent = {
358 # name => 'Recent Items',
359 # href => $account->{href}
360 #};
361 my $recentLink= $self->{mech}->find_link('url_regex' => qr/domesticRecentItems/);
362 my $tmp = {
363 name => $recentLink->text(),
364 href => $self->{siteAddress} . $recentLink->url()
365 };
366 push @statements, $tmp;
367
368 # Main statement links
369 my @statementLinks = $self->{mech}->find_all_links('url_regex' => qr/getDomesticStatement/);
370 foreach my $link (@statementLinks) {
371 if ($link->text() =~ m|^\d{2}\/\d{2}\/\d{4}$|) {
372 my $tmp = {
373 name => $link->text(),
374 href => $self->{siteAddress} . $link->url()
375 };
376 push @statements, $tmp;
377 }
378 }
379 return \@statements;
380 }
381  
382 sub statement {
383 my $self = shift();
384 my $statement = shift();
385
386 #print "Fetching: ", $statement->{href}, "\n";
387 $self->{mech}->get($statement->{href});
388 if (! $self->{mech}->success()) {
389 print "HTTP ", $self->{mech}->status(), "\n";
390 print Dumper($self->{mech}->response()), "\n";
391 }
392  
393 #print $self->{mech}->content();
394  
395 # to parse via HTML::DOM, need to save content as a file
396 my $fh = File::Temp->new();
397 print $fh $self->{mech}->content();
398 my $tmpNam = $fh->filename;
399 $fh->close;
400
401 my $dom = HTML::DOM->new();
402 $dom->parse_file( $tmpNam );
403
404 # Descend into content, find table containing summary data
405 # 4th or 5th child (table) of <td class="sidebar" width="80%">
406 # remember, we're parsing HTML so may change if Co-op regen the pages
407 my $outerTable;
408 my $innerTable;
409 if ($statement->{name} eq 'Recent Items') {
410 $outerTable = 3;
411 $innerTable = 0;
412 } else {
413 $outerTable = 3;
414 $innerTable = 0;
415 #$outerTable = 2;
416 #$innerTable = 2;
417 }
418
419 my @transactions;
420 foreach my $td ($dom->getElementsByTagName('td')) {
421 if ($td->getAttribute('class') eq 'sidebar' && $td->getAttribute('width') eq '80%') {
422 my $rightChildren = $td->getElementsByTagName ( 'table' );
423 my $summaryTable = $rightChildren->[$outerTable]->getElementsByTagName('table')
424 ->[$innerTable];
425  
426  
427 foreach my $row ($summaryTable->getElementsByTagName('tr')) {
428 my $account = {};
429 my $columns = $row->childNodes();
430  
431 for (my $i = 0; $i < $columns->length; ++$i) {
432 my $text = $columns->[$i]->as_text;
433 $text =~ s/\s+//g;
434 $text =~ s/\x{a3}//;
435 chomp($text);
436 if ($i == 1) {
437 # transaction date
438 $account->{date} = $text;
439 } elsif ($i == 3) {
440 # transaction reference
441 $account->{reference} = $text;
442 } elsif ($i == 5) {
443 # deposit
444 $account->{deposit} = $text;
445 } elsif ($i == 7) {
446 $account->{withdrawal} = $text;
447 } elsif ($i == 9) {
448 $account->{balance} = $text;
449 }
450 }
451 # don't include the table header row in returned results
452 if ($account->{reference} !~ /LastStatement/
453 && $account->{reference} !~/Transaction/) {
454 push @transactions, $account;
455 }
456 }
457
458 }
459 }
460
461 return \@transactions;
462 }
463 1;