Rishwanth Yeddula > WWW-SEOGears-0.04 > WWW::SEOGears

Download:
WWW-SEOGears-0.04.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.04   Source   Latest Release: WWW-SEOGears-0.05

NAME ^

WWW::SEOGears - Perl Interface for SEOGears API.

VERSION ^

Version 0.04

SYNOPSIS ^

This module provides you with an perl interface to interact with the Seogears API.

        use WWW::SEOGears;
        my $api = WWW::SEOGears->new( { 'brandname' => $brandname,
                                        'brandkey' => $brandkey,
                                        'sandbox' => $boolean 
        });
        $api->newuser($params_for_newuser);
        $api->statuscheck($params_for_statuscheck);
        $api->inactivate($params_for_inactivate);
        $api->update($params_for_update);
        $api->get_tempauth($params_for_update);

SUBROUTINES/METHODS ^

new

Constructor.

Input takes a hashref that contains:

        Required:

        brandname  => Brandname as listed on seogears' end.
        brandkey   => Brandkey received from seogears.
        
        Will croak if the above keys are not present.

        Optional:
        sandbox    => If specified the sandbox API url is used instead of production.
        http_opts  => Hashref of options that are passed on to the HTTP::Tiny object that is used internally.
                      Example value: { 'agent' => 'WWW-SEOGears', 'timeout' => 20, 'verify_SSL' => 0, 'SSL_options' => {'SSL_verify_mode' => 0x00} }

        Deprecated (will be dropped in the upcoming update): Will emit a warning if used.
        lwp        => hash of options for LWP::UserAgent - will be converted to their corresponding HTTP::Tiny options.
                      Example value: {'parse_head' => 0, 'ssl_opts' => {'verify_hostname' => 0, 'SSL_verify_mode' => 0x00}}

newuser

Creates a new user via the 'action=new' API call. Since the 'userid' and 'email' can be used to fetch details about the seogears account, storing these values locally is recommended.

Input Requires that you pass in the following parameters for the call:

        userid    => '123456789'
        email     => 'test1@testing123.com'
        name      => 'Testing User'
        phone     => '1.5552223333'
        domain    => 'somedomain.com'
        rep       => 'rep@domain.com'
        placement => 'reg'
        pack      => '32'
        price     => '14.99'
        months    => '12'

Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.

Output Hash containing the data returned by the API:

        "success"   => 1
        "authkey"   => "GB0353566P163045n07157LUFGZntgqNF042MO692S19567CIGHj727437179300tE5nt8C362803K686Yrbj4643zausyiw"
        "bzid"      => "30928"
        "debuginfo" => "Success"
        "message"   => "New Account Created"

statuscheck

Fetches information about a user via the 'action=statuscheck' API call.

Input Requires that you pass in the following parameters for the call:

        userid    => '123456789'
        email     => 'test1@testing123.com'

Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.

Output Hash containing the data returned by the API:

        "success"   =>  1,
        "inactive"  => "0"
        "authkey"   => "WO8407914M283278j87070OPWZGkmvsEG847ZB845Q28584YSBDt684478133472pV3ws1X655571X005Zlhh6810hsxjjka"
        "bzid"      => "30724"
        "brand"     => "brandname"
        "message"   => User is active. See variables for package details."
        "expdate"   => "2014-01-01 12:00:00"
        "debuginfo" => "User exists. See variables for status and package details."
        "pack"      => "32"
        "price"     => "14.99"
        "months"    => "12"

inactivate

Inactivates a user via the 'action=inactivate' API call.

Input Requires that you pass in the following parameters for the call:

        "bzid"      => "30724"
        "authkey"   => "WO8407914M283278j87070OPWZGkmvsEG847ZB845Q28584YSBDt684478133472pV3ws1X655571X005Zlhh6810hsxjjka"

Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.

Output Hash containing the data returned by the API:

        'success'   => 1,
        'bzid'      => '30724',
        'debuginfo' => 'Success BZID30724 WO8407914M283278j87070OPWZGkmvsEG847ZB845Q28584YSBDt684478133472pV3ws1X655571X005Zlhh6810hsxjjka'

activate

Activates a previously inactivated user via the 'action=activate' API call.

Input Requires that you pass in the following parameters for the call:

        'bzid' => '32999'
        'authkey' => 'BC1052837T155165x75618ZUKZDlbpfMW795RS245L23288ORUUq323360091155yP1ng7E548072L030Zssq0043pldkebf'

Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.

Output Hash containing the data returned by the API:

        'success' => 1,
        'bzid' => '32999',
        'debuginfo' => 'Success BZID32999 BC1052837T155165x75618ZUKZDlbpfMW795RS245L23288ORUUq323360091155yP1ng7E548072L030Zssq0043pldkebf'

update

Updates/Renews a user via the 'action=update' API call.

Input Requires that you pass in the following parameters for the call:

        "bzid"      => "30724"
        "authkey"   => "WO8407914M283278j87070OPWZGkmvsEG847ZB845Q28584YSBDt684478133472pV3ws1X655571X005Zlhh6810hsxjjka"

        Optional params:
        "email"     => "newemail@testing123.com"
        "phone"     => "1.5552224444"
        "pack"      => "33"
        "months"    => "24"
        "price"     => "14.99"

If pack is specified, then a price must be specified along with it.

Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.

Output Hash containing the data returned by the API:

        'success' => 1,
        'bzid' => '30724',
        'debuginfo' => 'Success'

get_tempauth

Retrieves the tempauth key for an account from the API.

Input Requires that you pass in the following parameters for the call:

        bzid      => '31037'
        authkey   => 'HH1815009C705940t76917IWWAQdvyoDR077CO567M05324BHUCa744638889409oM8kw5E097737M626Gynd3974rsetvzf'

Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.

Output Hash containing the data returned by the API:

        'success'     => 1,
        'bzid'        => '31037',
        'tempauthkey' => 'OU8937pI03R56Lz493j0958US34Ui9mgJG831JY756X0Tz04WGXVu762IuIxg7643vV6ju9M96J951V430Qvnw41b4qzgp2pu',
        'message'     => ''

get_templogin_url

Generates the temporary login URL with which you can access the seogears' control panel. Essentially acts as a wrapper that stringifies the data returned by get_tempauth.

Input Requires that you pass in either:

        userid    => '123456789'
        email     => 'test1@testing123.com'

Or

        bzid      => '31037'
        authkey   => 'HH1815009C705940t76917IWWAQdvyoDR077CO567M05324BHUCa744638889409oM8kw5E097737M626Gynd3974rsetvzf'

If the bzid/authkey are not provied, then it will attempt to look up the proper information using the userid and email provided.

Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.

Output Returns the login url that can be used to access the control panel on SEOgears. Example: https://seogearstools.com/api/login.html?bzid=31037&tempauthkey=OU8937pI03R56Lz493j0958US34Ui9mgJG831JY756X0Tz04WGXVu762IuIxg7643vV6ju9M96J951V430Qvnw41b4qzgp2pu

get_userurl, get_authurl, get_loginurl

Return the corresponding api url that is being used.

get_error

Returns $self->{'error'}

get_brandname

Returns $self->{'brandname'}

get_brandkey

Returns $self->{'brandkey'}

Internal Subroutines ^

The following are not meant to be used directly, but are available if 'finer' control is required.

_make_request_handler

Wraps the call to _make_request and handles error checks.

INPUT Takes the 'action' and sanitized paramaters hashref as input.

Output Returns undef on failure (sets $self->{error} with the proper error). Returns a hash with the decoded json data from the API server if successful.

_make_request

Makes the HTTP request to the API server.

Input The full uri to perform the HTTP request on.

Output Returns an array containing the http response, and error. If the HTTP request was successful, then the error is blank. If the HTTP request failed, then the response is blank and the error is the status line from the HTTP response.

_stringify_params

Stringifies the content of a hash such that the output can be used as the URI body of a GET request.

Input A hashref containing the sanatizied parameters for an API call.

Output String with the keys and values stringified as so '&key1=value1&key2=value2'

_sanitize_params

sanitizes the data in the hashref passed for the action specified.

Input The 'action', and a hashref that has the data that will be sanitized.

Output Boolean value indicating success. The hash is altered in place as needed.

_check_params

Input: Three hashrefs that contain the following in the specified order:

        1) the hashref to the params that need to be checked.
        2) the hashref to the 'required' set of params
        3) the hashref to the 'optional' set of params

Outupt: Undef if everything is good. If errors are detected, it will:

        either return a hashref that has two arrays:
                'required_params' - which will list the required params that are missing. And
                'blank_params'    - which will list the params that have blank values specified for them.
        
        or a string with a specific error message.

This also 'prunes' the first hashref of params that are not specified in either the required or the optional hashrefs.

_valid_months

Returns true if the 'months' value specified is a valid. Currently, you can set renewals to occur on a monthly or yearly (upto 3 years), so the valid values are:

        1
        12
        24
        36

_get_apiurl

Depending on the action passed, it will return the initial part of the URL that you can use along with the _stringify_params method to generate the full GET url.

Valid actions and the corresponding strings that are returned:

        'auth'        => get_authurl().'?'
        'login'       => get_loginurl().'?'
        'new'         => get_userurl().'?action=new'
        'statuscheck' => get_userurl().'?action=statuscheck'
        'inactivate'  => get_userurl().'?action=inactivate'
        'update'      => get_userurl().'?action=update'

If no valid action is specified, it will set the $self->{error} and return;

_error

Internal method that is used to report and set $self->{'error'}.

It will croak if called with a true second argument. Such as:

        $self->_error($msg, 1);

_months_from_now

Internal helper method that will calculate the expiration date thats x months in the future - calculated via Date::Calc's Add_Delta_YMDHMS().

_translate_lwp_to_http_opts

Helper method that translates the passed in LWP opts hashref to a corresponding HTTP::Tiny opts hashref.

AUTHOR ^

Rishwanth Yeddula, <ryeddula@cpan.org>

ACKNOWLEDGMENTS ^

Thanks to Hostgator.com for funding the development of this module and providing test resources.

BUGS ^

Please report any bugs or feature requests to bug-www-seogears at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-SEOGears. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT ^

You can find documentation for this module with the perldoc command.

        perldoc WWW::SEOGears

You can also review the API documentation provided by SEOgears for more information.

LICENSE AND COPYRIGHT ^

Copyright 2013 Rishwanth Yeddula.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

syntax highlighting: