=head1 Description

This is a wrapper interface to the DNS portions of the Tucows OpenSRS

HTTPS XML API.

The client library distributed by OpenSRS can be difficult to integrate

into a custom environment, and their web interface becomes quickly

tedious with heavy usage. This is a clean and relatively quick library

to perform the most common API methods described in the OpenSRS API

documentation.

=head1 Examples

 use Net::OpenSRS;

 my $key = 'Your_API_Key_From_The_Reseller_Interface';

 my $srs = Net::OpenSRS->new();

 $srs->environment('live');

 $srs->set_key( $key );

 $srs->set_manage_auth( 'manage_username', 'manage_password' );

 my $cookie = $srs->get_cookie( 'spime.net' );

 if ($cookie) {

     print "Cookie:  $cookie\n";

 } else {

     print $srs->last_response() . "\n";

 }

 # do a batch of domain locks

 $srs->bulk_lock([ 'example.com', 'example.net', ... ]);

 # renew a domain

 my $result = $srs->renew_domain( 'example.com' );

 ...

=head1 Notes

=head2 Prerequisites

This module requires some setup in the OpenSRS reseller environment

before it will work correctly.

=over 4

=item Reseller account

You need to have an OpenSRS account, of course.  If you aren't an

OpenSRS reseller, this module will be of limited use to you. :)

=item Script API network access

The machine(s) using this module need to have their public IP addresses

added to your 'Script API allow' list in the OpenSRS web interface.

(You'll only need to do this once, assuming your IP doesn't change.)

=item API key generation

You'll need to pregenerate your API keys - also in the the OpenSRS web

interface.  These keys are used for all reseller API authentication.

=back

=head2 Assumptions

OpenSRS allows for a variety of ways to organize your domains.  Because

of this, writing a 'one size fits all' module is rather difficult.

Instead, we make a few assumptions regarding the way people use their

OpenSRS reseller accounts.

**** These assumptions will ultimately determine if this module is right for

you!  Please read them carefully! ****

=over 4

=item Management 'master' account.

We assume that all domains are under one global management owner

account.  If customers want access to the management interface, we're

operating under the idea that you create subaccounts for them -

retainting the master account information for your own use.  (If you

aren't doing this, it really makes things easier for you in the long

run.)

For example, 'spime.net' is my master management account.  Before doing

any register_domain() calls, I call master_domain('spime.net') - then

any transfers or registrations from that point forward are linked to

'spime.net'.  If a customer wants access to the SRS web management

interface, I can then just create a subaccount for just their domain,

so I retain absolute control -- in the event a customer forgets their

password, I'm covered.

=item Usernames

We assume that your management username 'master' account is identical to

your reseller username, and just the passwords differ.

=item Default registration info

We assume you've properly set up default technical contact information,

including your default nameservers, in the OpenSRS reseller web

interface.

=item Return codes

Unless otherwise noted, all methods return true on success, false on

failure, and undefined on caller error.

=back

=head2 Default environment

This library defaults to the TEST environment. (horizon.)  Many API

methods don't work in the test environment (SET COOKIE being the most

notable example, as any API method relying on a cookie doesn't work

either.)  Neither does batch processing.  Most everything else should be

ok.  ( See environment() )

=head2 The '$c' variable

Many methods require customer information.  I leave the method of

fetching this information entirely to you.  All examples below that show

a $c variable expect a hashref (or object) that contain these keys:

    my $c = {

        firstname => 'John',

        lastname  => 'Doe',

        city      => 'Portland',

        state     => 'Oregon',

        country   => 'US',

        address   => '555 Someplace Street',

        email     => 'john@example.com',

        phone     => '503-555-1212',

        company   => 'n/a'

    };

=cut

package Net::OpenSRS;

use strict;

use warnings;

use LWP::UserAgent;

use XML::Simple;

use Digest::MD5;

use Date::Calc qw/ Add_Delta_Days Today This_Year /;

our $VERSION = '0.02';

my $rv;

*hash = \&Digest::MD5::md5_hex;

#----------------------------------------------------------------------

# utility methods

#----------------------------------------------------------------------

=head1 Utility methods

=over 4

=item new()

 my $srs = Net::OpenSRS->new();

Create a new Net::OpenSRS object.  There are no options for this

method.

=cut

sub new

{

    my ($class, %opts) = @_;

    my $self = {};

    bless $self, $class;

    $self->{config} = {

        use_test_env  => 1,

        debug         => 0,

        master_domain => undef,

        bulkhost => 'https://batch.opensrs.net:55443',

        # reseller auth keys, as generated via the reseller website.

        live => {

            key  => undef,

            host => 'https://rr-n1-tor.opensrs.net:55443',

        },

        test => {

            key  => undef,

            host => 'https://horizon.opensrs.net:55443',

        }

    };

    return $self;

}

sub debug

{

    my $self = shift;

    return unless $self->debug_level;

    print STDERR shift() . "\n";

}

=item debug_level()

Setting the debug level will print various pieces of information to

STDERR when connecting to OpenSRS.  Use this if something isn't working

the way you think it should be.

=item 0

Disable debugging.

=item 1

Print current environment, host, and HTTP response.

=item 2

Add XML request and response to output.

=item 3

Add SSL debugging to output.

Debugging is off by default.  When called without an argument, returns

the current debug level.

=cut

sub debug_level

{

    my ($self, $level) = @_;

    return $self->{config}->{debug} unless $level;

    $self->{config}->{debug} = $level;

    return;

}

=item last_response()

All Net::OpenSRS methods set the last OpenSRS API reply in a temporary

variable.  You can view the contents of this variable using the

last_response() method.

Note that it is reset on each method call.

Returns the last OpenSRS return code and result string, or if passed any

true value, instead returns the full XML (parsed into a hashref) of the

last OpenSRS return. (perfect for Data::Dumper)

Examples:

   200: Command Successful

   400: Domain example.com does not exist with OpenSRS

=cut

sub last_response

{

    my ($self, $obj) = @_;

    return $obj ? $rv : $self->{last_response} || '';

}

=item set_manage_auth()

 $srs->set_manage_auth( $username, $password );

Set the owner management username and password.  This is used to fetch

cookies, and perform any API methods that require the management cookie.

For specifics on this, see the OpenSRS API documentation.

=cut

sub set_manage_auth

{

    my ($self, $user, $pass) = @_;

    return undef unless $user && $pass;

    $self->{config}->{username} = $user;

    $self->{config}->{password} = $pass;

    return 1;

}

=item set_key()

Tell the OpenSRS object what secret key to use for authentication.

You can generate a new secret key by using the OpenSRS reseller web

interface.  This key is required to perform any API functions.

set_key() is affected by the current environment().  Calling the

set_key() method while in the test environment only sets the key for the

test environment - likewise for the live environment.  To set a key for

the live environment, you need to call environment('live') B<first>.

=cut

sub set_key

{

    my ($self, $key) = @_;

    return undef unless $key;

    $self->{config}->{ $self->environment }->{key} = $key;

    return 1;

}

=item environment()

 my $env = $srs->environment;

 $srs->environment('live');

Without an argument, returns a string - either 'test', or 'live',

depending on the environment the object is currently using.

The test environment is the default.

If passed an argument (either 'test' or 'live') - switches into the

desired environment.  You will need to set_key() if you were previously

using a different environment, or if you hadn't set_key() yet.

=cut

sub environment

{

    my ($self, $env) = @_;

    return ($self->{config}->{use_test_env} ? 'test' : 'live')

        unless $env && $env =~ /(test|live)/i;

    $self->{config}->{use_test_env} = 

        $1 eq 'test' ? 1 : 0;

    return;

}

=item master_domain()

 my $master = $srs->master_domain;

 $srs->master_domain('spime.net');

Without an argument, returns the currently set 'master domain' account.

Otherwise, it sets the master domain.

New transfers and registrations are linked under this domain, for

centralized management.  See the 'Assumptions' section, above.

=cut

sub master_domain

{

    my ($self, $domain) = @_;

    return $self->{config}->{master_domain} unless $domain;

    $self->{config}->{master_domain} = $domain;

    return;

}

# set last status messages/codes in $self,

# for the benefit of the caller.

sub _set_response

{

    my $self = shift;

    $rv->{response_text} =~ s/Error: //;

    $self->{last_response} = $rv->{response_code} . ": " . $rv->{response_text};

    return;

}

#----------------------------------------------------------------------

# SRS API methods

#----------------------------------------------------------------------

=back

=head1 OpenSRS API methods

=over 4

=item bulk_lock() / bulk_unlock()

Locks or unlocks up to 1000 domains at a time.

 my $result = $srs->bulk_lock([ 'example.com', 'example.net' ]);

Returns remote bulk queue id on successful batch submission.

=cut

sub bulk_lock

{

    my $self = shift;

    return $self->_bulk_action( 'lock', @_ );

}

sub bulk_unlock

{

    my $self = shift;

    return $self->_bulk_action( 'unlock', @_ );

}

sub _bulk_action

{

    my ( $self, $toggle, $domains ) = @_;

    return undef unless $toggle =~ /lock|unlock/i && 

                        ref $domains;

    return undef if scalar @$domains >= 1000;

    $rv = $self->make_request(

        {

            batch   => 1,

            action  => 'submit',

            object  => 'bulk_change',

            attributes => {

                change_type => 'domain_lock',

                change_items => $domains,

                op_type => lc $toggle,

            }

        }

    );

    return undef unless $rv;

    $self->_set_response;

    return $rv->{is_success} ? $rv->{bulk_change_req_id} : 0;

}

=item check_queued_request()

 my $result = $srs->check_queued_request( $queue_id );

Requires queue id - returned from batch methods such as bulk_lock().

Always returns hashref of queue command on success.  

Check $srs->last_response() for status progress.

=cut

sub check_queued_request

{

    my ( $self, $id ) = @_;

    return undef unless $id;

    $rv = $self->make_request(

        {

            action  => 'query_queued_request',

            object  => 'domain',

            attributes => {

                request_id => $id,

            }

        }

    );

    return undef unless $rv;

    $self->_set_response;

    return $rv->{attributes}->{request_data};

}

=item check_transfer()

 my $result = $srs->check_transfer( 'example.com' );

Checks the status of a transfer in progress.  Returns hashref of

'contact_email', 'status', and 'last_update_time' for a given domain

transfer.  The 'status' key is always one of the following:

        pending_owner  (waiting on owner confirmation)

        pending_admin  (waiting on opensrs staff confirmation)

        pending_registry  (waiting on register to complete)

        completed  (transfer done)

        cancelled  (reseller cancelled transfer in progress)

        undefined  (no transfer in progress)

If the domain in question has no transfer in progress - instead checks

to see if the domain is capable of transfer.  Returns hashref of

'transferrable' (boolean) and 'reason' (string).

=cut

sub check_transfer

{

    my ( $self, $domain ) = @_;

    return undef unless $domain;

    $rv = $self->make_request(

        {

            action     => 'check_transfer',

            object     => 'domain',

            attributes => {

                domain              => $domain,

                get_request_address => 1,

            }

        }

    );

    return undef unless $rv;

    $self->_set_response;

    if ( $rv->{attributes}->{status} ) {

        return {

            status           => $rv->{attributes}->{status},

            last_update_time => $rv->{attributes}->{unixtime},

            contact_email    => $rv->{attributes}->{request_address}

        };

    }

    else {

        return $rv->{attributes}; #(transferrable bool and reason)

    }

}

=item get_cookie()

OpenSRS management APIs require a cookie to be generated, and sent along

with the API request.

 $cookie = $srs->get_cookie( 'example.com ');

 ($cookie, $expiration_date) = $srs->get_cookie( 'example.com ');

Make sure you've set_manage_auth() before attempting any cookie required

APIs.

Returns cookie on success, undefined on error.  (Check error with

last_response())

In array context, returns cookie and expiration date of the domain.

=cut

sub get_cookie

{

    my ($self, $domain) = @_;

    return undef unless $domain;

    $rv = $self->make_request(

        {

            action     => 'set',

            object     => 'cookie',

            attributes => {

                reg_username => $self->{config}->{username},

                reg_password => $self->{config}->{password},

                domain => $domain

            }

        }