NAME

Webservice::Shipment::Carrier - A base class for carrier objects used by Webservice::Shipment

SYNOPSIS

DESCRIPTION

Webservice::Shipment::Carrier is an abstract base class used to defined carrier objects which interact with external APIs. For security, "add_carrier" in Webservice::Shipment requires that added carriers be a subclass of this one.

ATTRIBUTES

Webservice::Shipment::Carrier inherits all of the attributes from Mojo::Base and implements the following new ones.

api_url

A Mojo::URL instance for specifying the base url of the api. It is expected that this attribute will be overloaded in a subclass.

date_format

If specified, this format string is used to convert Time::Piece objects to string representations.

password

Password for the external api call. The default implementation dies if used without being specified.

ua

An instance of Mojo::UserAgent, presumably used to make the "request". This is provided as a convenience for subclass implementations, and as an injection mechanism for a user agent which can mock the external service. See Webservice::Shipment::MockUserAgent for more details.

usename

Username for the external api call. The default implementation dies if used without being specified.

validation_regex

A regexp (qr) applied to a tracking id to determine if the carrier can handle the request. Currently, this is the only mechanism by which "validate" determines this ability. It is expected that this attribute will be overloaded in a subclass. The default value is undef which "validate" interprets as false.

METHODS

extract_destination

  my $dest = $carrier->extract_destination($id, $res, $type);

Returns a string of the response's destination field of a given type. Currently those types are

address1

address2

city

state

postal_code

country

An implementation should return an empty string if the type is not understood or if no information is available.

extract_service

  my $service = $carrier->extract_service($id, $res);

Returns a string representing the level of service the shipment as transported with. By convention this string also should included the carrier name. An example might be USPS First Class Mail.

An implementation should return an empty string at the minimum if the information is unavailable. That said, to follow the convention, most implementations should at least return the carrier name in any case.

extract_status

  my ($description, $date, $delievered) = $carrier->extract_status($id, $res);

Extract either the final or current status of the shipment. Returns three values, the textual description of the current status, a Time::Piece object, and a boolean 1/0 representing whether the shipment has been delivered. It is likely that if the shipment has been delivered that the description and date will correspond to that even, but it is not specifically guaranteed.

extract_weight

  my $weight = $carrier->extract_weight($id, $res);

Extract the shipping weight of the parcel. An implementation should return an empty string if the information is not available.

human_url

  my $url = $carrier->human_url($id, $res);

Returns an instance of Mojo::URL which represents a url for to human interaction rather than API interaction. An implementation should return a Mojo::URL object (presumably empty) even if information is not available.

Note that though a response parameter is accepted, an implementation is likely able to generate a human_url from an id alone.

parse

  my $info = $carrier->parse($id, $res);

Returns a hash reference of data obtained from the id and the result obtained from "request". It contains the following structure with results obtained from many of the other methods.

  {
    'status' => {
      'description' => 'DELIVERED',
      'date' => Time::Piece->new(...), # this is a string if date_format is set
      'delivered' => 1,
    },
    'destination' => {
      'address1' => '',
      'address2' => '',
      'city' => 'BEVERLY HILLS',
      'state' => 'CA',
      'country' => '',
      'postal_code' => '90210',
    },
    'weight' => '0.70 LBS',
    'service' => 'UPS NEXT DAY AIR',
    'human_url' => 'http://wwwapps.ups.com/WebTracking/track?trackNums=1Z584056NW00605000&track.x=Track',
  }

request

  my $res = $carrier->request($id);

  # or nonblocking with callback
  $carrier->request($id, sub { my ($carrier, $err, $res) = @_; ... });

Given a valid id, this methods should return some native result for which other methods may extract or generate information. The actual response will be carrier dependent and should not be relied upon other than the fact that it should be able to be passed to the extraction methods and function correctly. Must be overridden by subclass, the default implementation throws an exception.

track

  my $info = $carrier->track($id);

  # or nonblocking with callback
  $carrier->track($id, sub { my ($carrier, $err, $info) = @_; ... });

A shortcut for calling "request" and then "parse" returning those results. Note that this method throws an exception if "request" returns a falsey value.

validate

  $bool = $carrier->validate($id);

Given an id, check that the class can handle it. The default implementation tests against the "validation_regex".

cpanm Webservice::Shipment

perl -MCPAN -e shell
install Webservice::Shipment