Provided by: libnet-opensrs-perl_0.06-3_all bug

NAME

       Net::OpenSRS - Domain registration via the Tucows OpenSRS HTTPS XML API

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.

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' );
        ...

Notes

   Prerequisites
       This module requires some setup in the OpenSRS reseller environment before it will work
       correctly.

       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. :)

       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.)

       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.

   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! ****

       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.

       Usernames
           We assume that your management username 'master' account is identical to your reseller
           username, and just the passwords differ.

       Default registration info
           We assume you've properly set up default technical contact information, including your
           default nameservers, in the OpenSRS reseller web interface.

       Return codes
           Unless otherwise noted, all methods return true on success, false on failure, and
           undefined on caller error.

   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() )

   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'
           };

Utility methods

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

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

       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.

       0   Disable debugging.

       1   Print current environment, host, and HTTP response.

       2   Add XML request and response to output.

       3   Add SSL debugging to output.

           Debugging is off by default.  When called without an argument, returns the current
           debug level.

       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

       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.

       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') first.

       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.

       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.

OpenSRS API methods

       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.

       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.

       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).

       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.

       get_expiring_domains()
            my $results = $srs->get_expiring_domains( 60 );

            Fetch and return OpenSRS hashref of expiring domains, within
            the specified timeperiod.  (In days.)

            Time period defaults to 30 days.

       is_available()
           Hey OpenSRS! Is this domain registered, or is it available?

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

           Returns true if the domain is available, false if it is already registered.

       register_domain()
            my $result = $srs->register_domain( 'example.com', $c );

           Register a new domain.  Default nameserver and tech info used from OpenSRS settings.

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

           Renew a domain for a period of time in years. 1 year is the default.

       revoke_domain()
           Revoke a previously registered domain.  This only works if the domain is still within
           the grace period as defined by the registrar.  Requires you to have called
           set_manage_auth() first.

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

           Returns true if the revoke is successful, false otherwise.  Returns undefined on
           error.

       transfer_domain()
            my $result = $srs->transfer_domain( 'example.com', $c );

           Transfer a domain under your control.  Returns true on success, false on failure, and
           undefined on caller error.

       make_request()
           This method is the real workhorse of this module.  If any OpenSRS API isn't explicity
           implemented in this module as a method call (such as get_cookie(), bulk_lock(), etc),
           you can use make_request() to build and send the API yourself.

           Examples:

            my $result = $srs->make_request(
                {
                    batch   => 1,
                    action  => 'submit',
                    object  => 'bulk_change',
                    attributes => {
                        change_type => 'domain_lock',
                        change_items => [ 'example.com', 'example.net' ],
                        op_type => 'lock',
                    }
                }
            );

            my $result = $srs->make_request(
                {
                    action     => 'lookup',
                    object     => 'domain',
                    attributes => {
                        domain => 'example.com'
                    }
                }
            );

           Returns a hashref containing parsed XML results from OpenSRS.

           Example return:

            {
                'protocol' => 'XCP',
                'object' => 'DOMAIN',
                'response_text' => 'Domain taken',
                'action' => 'REPLY',
                'response_code' => '211',
                'attributes' => {
                    'status' => 'taken',
                    'match' => {}
                },
                'is_success' => '1'
            }

Author

       Mahlon E. Smith mahlon@martini.nu for Spime Solutions Group (www.spime.net)

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 214:
           Expected text after =item, not a number

       Around line 218:
           Expected text after =item, not a number

       Around line 222:
           Expected text after =item, not a number

       Around line 226:
           Expected text after =item, not a number