File Coverage

blib/lib/WebService/Async/SmartyStreets.pm

Criterion	Covered	Total	%
statement	79	82	96.3
branch	7	10	70.0
condition	7	15	46.6
subroutine	23	24	95.8
pod	5	9	55.5
total	121	140	86.4

package WebService::Async::SmartyStreets;

# ABSTRACT: Access SmartyStreet API

use strict;
use warnings;

our $VERSION = '0.002';

=head1 NAME

WebService::Async::SmartyStreets - calls the SmartyStreets API and checks for the validity of the address

=head1 SYNOPSIS

    my $ss = WebService::Async::SmartyStreets->new(
        # Obtain these from your SmartyStreets account page.
        # These will be used for US lookups
        us_auth_id => '...',
        us_token   => '...',
        # For non-US address lookups, you would also need an international token
        international_auth_id => '...',
        international_token   => '...',
    );
    IO::Async::Loop->new->add($ss);

    print $ss->verify(
        city => 'Atlanta',
        country => 'US',
        geocode => 1
    )->get->status;

=head1 DESCRIPTION

This module provides basic support for the L.

Note that this module uses L.

=cut

use parent qw(IO::Async::Notifier);

use mro;
no indirect;

use URI;
use URI::QueryParam;

use Future::AsyncAwait;
use Net::Async::HTTP;
use JSON::MaybeUTF8 qw(:v1);
use Syntax::Keyword::Try;
use Scalar::Util qw(blessed);

use WebService::Async::SmartyStreets::Address;

use Log::Any qw($log);

=head2 verify

Makes connection to SmartyStreets API and parses the response into WebService::Async::SmartyStreets::Address.

    my $addr = $ss->verify(%address_to_check)->get;

Takes the following named parameters:

=over 4

=item * C - country (required)

=item * C - address line 1

=item * C - address line 2

=item * C - name of organization (usually building names)

=item * C - city

=item * C - state

=item * C - post code

=item * C - true or false

=back

Returns a L which should resolve to a valid L instance.

=cut

# keyword 'async' will cause critic test fail. disable it
## no critic (RequireEndWithOne.pm)
async sub verify {
    my ($self, %args) = @_;

    my $uri = $self->country_endpoint($args{country})->clone;

    $uri->query_param($_ => $args{$_}) for keys %args;
    $uri->query_param(
        'auth-id' => ($self->auth_id($args{country}) // die 'need an auth ID'),
    );
    $uri->query_param(
        'auth-token' => ($self->token($args{country}) // die 'need an auth token'),
    );
    $uri->query_param(
        'input-id' => $self->next_id,
    );
    $log->tracef('GET %s', '' . $uri);

    my $decoded = await get_decoded_data($self, $uri);

    $log->tracef('=> %s', $decoded);
    $decoded = [$decoded] unless ref($decoded) eq 'ARRAY';

    return map { WebService::Async::SmartyStreets::Address->new(%$_) } @$decoded;
}

=head2 METHODS - Accessors

=cut

sub country_endpoint {
    my ($self, $country) = @_;
    return $self->us_endpoint if uc($country) eq 'US';
    return $self->international_endpoint;
}

sub us_endpoint {
    shift->{us_endpoint} //= URI->new('https://us-street.api.smartystreets.com/street-address');
}

sub international_endpoint {
    shift->{international_endpoint} //= URI->new('https://international-street.api.smartystreets.com/verify');
}

sub auth_id {
    my ($self, $country) = @_;
    return $self->{us_auth_id} if uc($country) eq 'US';
    return $self->{international_auth_id};
}

sub token {
    my ($self, $country) = @_;
    return $self->{us_token} if uc($country) eq 'US';
    return $self->{international_token};
}

=head1 METHODS - Internal

=head2 get_decoded_data

Calls the SmartyStreets API then decode and parses the response give by SmartyStreets

    my $decoded = await get_decoded_data($self, $uri)

Takes the following parameters:

=over 4

=item * C<$uri> - URI for endpoint

=back

More information on the response can be seen in L.

Returns a L which resolves to an arrayref of L instances.

=cut

async sub get_decoded_data {
    my $self = shift;
    my $uri  = shift;

    my $res;
    try {
        $res = await $self->ua->GET($uri);
    } catch ($e) {
        if (blessed($e) and $e->isa('Future::Exception')) {
            my ($payload) = $e->details;

            if (blessed($payload) && $payload->can('content')) {
                if (my $resp = eval { decode_json_utf8($payload->content) }) {
                    my $errors = $resp->{errors} // [];
                    my ($error) = $errors->@*;

                    if ($error && $error->{message}) {

                        # structured response may be useful for further processing
                        die $e;
                    }
                }
            }
        }

        # throw a generic error
        die 'Unable to retrieve response.';
    };

    my $response = decode_json_utf8($res->decoded_content);

    return $response->[0];
}

=head2 configure

Configures the instance.

Takes the following named parameters:

=over 4

=item * C - auth_id obtained from SmartyStreet

=item * C - token obtained from SmartyStreet

=item * C - auth_id obtained from SmartyStreet

=item * C - token obtained from SmartyStreet

=back

Note that you can provide US, international or both API tokens - if an API token
is not available for a L call, then it will return a failed L.

=cut

sub configure {
    my ($self, %args) = @_;
    for my $k (qw(international_auth_id international_token us_auth_id us_token)) {
        $self->{$k} = delete $args{$k} if exists $args{$k};
    }
    $self->next::method(%args);
}

sub next_id {
    ++(shift->{id} //= 'AA00000000');
}

=head2 ua

Accessor for the L instance which will be used for SmartyStreets API requests.

=cut

sub ua {
    my ($self) = @_;
    $self->{ua} //= do {
        $self->add_child(
            my $ua = Net::Async::HTTP->new(
                fail_on_error            => 1,
                decode_content           => 1,
                pipeline                 => 0,
                max_connections_per_host => 4,
                user_agent               =>
                    'Mozilla/4.0 (WebService::Async::SmartyStreets; [e-mail]; https://metacpan.org/pod/WebService::Async::SmartyStreets)',
            ));
        $ua;
    }
}

1;