/ 
Net-Async-Webservice-UPS-1.0.0
River stage zero No dependents
/ Net::Async::Webservice::UPS

NAME

Net::Async::Webservice::UPS - UPS API client, non-blocking

VERSION

version 1.0.0

SYNOPSIS

use IO::Async::Loop;
use Net::Async::Webservice::UPS;

my $loop = IO::Async::Loop->new;

my $ups = Net::Async::Webservice::UPS->new({
  config_file => $ENV{HOME}.'/.naws_ups.conf',
  loop => $loop,
});

$ups->validate_address($postcode)->then(sub {
  my ($response) = @_;
  say $_->postal_code for @{$response->addresses};
  return Future->wrap();
});

$loop->run;

Alternatively:

use Net::Async::Webservice::UPS;

my $ups = Net::Async::Webservice::UPS->new({
  config_file => $ENV{HOME}.'/.naws_ups.conf',
  user_agent => LWP::UserAgent->new,
});

my $response = $ups->validate_address($postcode)->get;

say $_->postal_code for @{$response->addresses};

DESCRIPTION

This class implements some of the methods of the UPS API, using Net::Async::HTTP as a user agent by default (you can still pass something like LWP::UserAgent and it will work). All methods that perform API calls return Futures (if using a synchronous user agent, all the Futures will be returned already completed).

NOTE: I've kept many names and codes from the original Net::UPS, so the API of this distribution may look a bit strange. It should make it simpler to migrate from Net::UPS, though.

ATTRIBUTES

live_mode

Boolean, defaults to false. When set to true, the live API endpoint will be used, otherwise the test one will. Flipping this attribute will reset "base_url", so you generally don't want to touch this if you're using some custom API endpoint.

base_url

A URI object, coercible from a string. The base URL to use to send API requests to (actual requests will be POSTed to an actual URL built from this by appending the appropriate service path). Defaults to the standard UPS endpoints:

  • https://onlinetools.ups.com/ups.app/xml for live

  • https://wwwcie.ups.com/ups.app/xml for testing

See also "live_mode".

user_id

password

access_key

Strings, required. Authentication credentials.

account_number

String. Used in some requests as "shipper number".

customer_classification

String, usually one of WHOLESALE, OCCASIONAL, RETAIL. Used when requesting rates.

pickup_type

String, defaults to ONE_TIME. Used when requesting rates.

cache

Responses are cached if this is set. You can pass your own cache object (that implements the get and set methods like CHI does), or use the cache_life and cache_root constructor parameters to get a CHI instance based on CHI::Driver::File.

user_agent

A user agent object, looking either like Net::Async::HTTP (has do_request and POST) or like LWP::UserAgent (has request and post). You can pass the loop constructor parameter to get a default Net::Async::HTTP instance.

METHODS

does_caching

Returns a true value if caching is enabled.

new

Async:

my $ups = Net::Async::Webservice::UPS->new({
   loop => $loop,
   config_file => $file_name,
   cache_life => 5,
});

Sync:

my $ups = Net::Async::Webservice::UPS->new({
   user_agent => LWP::UserAgent->new,
   config_file => $file_name,
   cache_life => 5,
});

In addition to passing all the various attributes values, you can use a few shortcuts.

loop

a IO::Async::Loop; a locally-constructed Net::Async::HTTP will be registered to it and set as "user_agent"

config_file

a path name; will be parsed with Config::Any, and the values used as if they had been passed in to the constructor

cache_life

lifetime, in minutes, of cache entries; a "cache" will be built automatically if this is set (using CHI with the File driver)

cache_root

where to store the cache files for the default cache object, defaults to naws_ups under your system's temporary directory

A few more examples:

  • no config file, no cache, async:

    ->new({
  user_id=>$user,password=>$pw,access_key=>$ak,
  loop=>$loop,
}),

  • no config file, no cache, custom user agent (sync or async):

    ->new({
  user_id=>$user,password=>$pw,access_key=>$ak,
  user_agent=>$ua,
}),

    it's your job to register the custom user agent to the event loop, if you're using an async agent

  • config file, async, custom cache:

    ->new({
  loop=>$loop,
  cache=>CHI->new(...),
}),

transaction_reference

Constant data used to fill something in requests. I don't know what it's for, I just copied it from Net::UPS.

access_as_xml

Returns a XML document with the credentials.

request_rate

$ups->request_rate({
  from => $address_a,
  to => $address_b,
  packages => [ $package_1, $package_2 ],
}) ==> (Net::Async::Webservice::UPS::Response::Rate)

from and to are instances of Net::Async::Webservice::UPS::Address, or postcode strings that will be coerced to addresses.

packages is an arrayref of Net::Async::Webservice::UPS::Package (or a single package, will be coerced to a 1-element array ref).

NOTE: the id field of the packages you pass in will be modified, and set to their position in the array.

Optional parameters:

limit_to

only accept some services (see "ServiceLabel" in Net::Async::Webservice::UPS::Types)

exclude

exclude some services (see "ServiceLabel" in Net::Async::Webservice::UPS::Types)

mode

defaults to rate, could be shop

service

defaults to GROUND, see Net::Async::Webservice::UPS::Service

The Future returned will yield an instance of Net::Async::Webservice::UPS::Response::Rate, or fail with an exception.

Identical requests can be cached.

validate_address

$ups->validate_address($address)
  ==> (Net::Async::Webservice::UPS::Response::Address)

$ups->validate_address($address,$tolerance)
  ==> (Net::Async::Webservice::UPS::Response::Address)

$address is an instance of Net::Async::Webservice::UPS::Address, or a postcode string that will be coerced to an address.

Optional parameter: a tolerance (float, between 0 and 1). Returned addresses with quality below the tolerance will be filtered out.

The Future returned will yield an instance of Net::Async::Webservice::UPS::Response::Address, or fail with an exception.

Identical requests can be cached.

validate_street_address

$ups->validate_street_address($address)
  ==> (Net::Async::Webservice::UPS::Response::Address)

$address is an instance of Net::Async::Webservice::UPS::Address, or a postcode string that will be coerced to an address.

The Future returned will yield an instance of Net::Async::Webservice::UPS::Response::Address, or fail with an exception.

Identical requests can be cached.

xml_request

$ups->xml_request({
  url_suffix => $string,
  data => \%request_data,
  XMLout => \%xml_simple_out_options,
  XMLin => \%xml_simple_in_options,
}) ==> ($parsed_response);

This method is mostly internal, you shouldn't need to call it.

It builds a request XML document by concatenating the output of "access_as_xml" with whatever XML::Simple produces from the given data and XMLout options.

It then posts (possibly asynchronously) this to the URL obtained concatenating "base_url" with url_suffix (see the "post" method). If the request is successful, it parses the body (with XML::Simple using the XMLin options) and completes the returned future with the result.

If the parsed response contains a non-zero /Response/ResponseStatusCode, the returned future will fail with a Net::Async::Webservice::UPS::Exception::UPSError instance.

post

$ups->post($url_suffix,$body) ==> ($decoded_content)

Posts the given $body to the URL obtained concatenating "base_url" with $url_suffix. If the request is successful, it completes the returned future with the decoded content of the response, otherwise it fails the future with a Net::Async::Webservice::Common::Exception::HTTPError instance.

generate_cache_key

Generates a cache key (a string) identifying a request. Two requests with the same cache key should return the same response.

AUTHORS

  • Gianni Ceccarelli <gianni.ceccarelli@net-a-porter.com>

  • Sherzod B. Ruzmetov <sherzodr@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Net-a-porter.com.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.