NAME
    Net::Magrathea - Perl interface to the Magrathea Telecom NTS API

VERSION
    This document describes Net::Magrathea version 0.03

SYNOPSIS
        use strict;
        use warnings;
        use Net::Magrathea;
        
    my $ntsapi = Net::Magrathea->new(
            username => 'user',
            password => 'pass',
            debug    => 1,
        );
        
    my $index = 1;
        my $dest  = 'S:01224279484@sip.surevoip.co.uk';
        
    my $number = $ntsapi->allocate('01224______');
        
    $ntsapi->activate($number) if $ntsapi->success;
        
    $ntsapi->set( $number, $index, $dest ) if $ntsapi->success;
        
    $ntsapi->status($number) if $ntsapi->success;
        
    $ntsapi->user_info(
            $number, 'Suretec Systems Ltd., 24 Cormack Park,
            Rothienorman, Inverurie, AB51 8GL.'
        ) if $ntsapi->success;
        
    $ntsapi->deactivate($number) if $ntsapi->success;
        $ntsapi->quit;

DESCRIPTION
    This module provides a Perl interface allowing you to connect to and
    operate the Magrathea Telecom 'Number Translation Service' API.

INTERFACE
  quit
    Terminates the session. Should be called after the final command.

        $ntsapi->quit;

  allocate
    Attempt to allocate a phone number. The <number> can either be an entire
    number, or may include underscores, to indicate any digit is acceptable.
    This is the only command that accepts underscores as part of the
    <number> parameter (now allocate_ten also accepts underscores).

    NOTE: This command does NOT reserve the number – you must issue an
    immediate activate command to ensure the number is allocated to your
    account and not available for allocation by others.

        $ntsapi->allocate('01224______');

    Returns an allocated number.

  activate
    Activates a number obtained using the allocate command. This command
    must be used to finalise the reservation process.

        $ntsapi->allocate($number);

    Result available via

        my $message = $ntsapi->result;

  deactivate
    Deactivate the specified number. The number will no longer operate when
    dialled.

    The exact number must be entered; underscores are not permitted when
    using this command.

    NOTE: If you deactivate a number it becomes available for others to
    allocate, so it cannot be guaranteed that you will be able to retrieve
    the number at a later date

        $ntsapi->deactivate($number);

    Result available via

        my $message = $ntsapi->result;

  reactivate
    Reactivates a number that has previously been deactivated using the DEAC
    command (if it has not since been allocated by someone else).

        $ntsapi->reactivate($number);

    Result available via

        my $message = $ntsapi->result;

  status
    Query the current status of the specified number. A successful reply
    contains the information about the number’s current settings.

        $ntsapi->status($number);

    Result available via

        my $message = $ntsapi->result;

  set
    This command sets up destination for when the number is dialled.

        my $index = 1;
        my $dest  = 'S:01224279484@sip.surevoip.co.uk';

        $ntsapi->set( $number, $index, $dest ) if $ntsapi->success;

    See the full NTS API docs for complete information (more than two
    pages).

  user_info
    This command has been added to enable storage of information about the
    user of the number.

        $ntsapi->user_info(
            $number, 'Suretec Systems Ltd., 24 Cormack Park, Rothienorman, 
                      Inverurie, AB51 8GL.'
            if $ntsapi->success;

  feature
    The FEAT command can be used to check, enable or disable a particular
    feature for an account.

    NOTE: Not supported yet.

  secure_pin
    Set a PIN for the number.

    NOTE: Not supported yet.

  time_of_day_route
    This command sets the destination usage by time of day, allowing (for
    advanced NTS only) multiple targets to be setup and configuration when
    each target is active.

    NOTE: Not supported yet.

  allocate_ten
    This command has been provided to help locate ranges of ten numbers that
    are available for allocation. The syntax of the <number> parameter is
    identical to that of ALLO and the system will attempt to find a range of
    ten numbers (0 through to 9) that matches the passed <number> format.

    NOTE: Not supported yet.

  ported_numbers
    NOTE: Not supported yet.

    Control numbers that have been ported to Magrathea, if your NTSAPI
    account has been given permission to do so.

DIAGNOSTICS
    The last message from the Magrathea session can be retrieved via

        print $ntsapi->errormsg

    If you have set $ntsapi->debug(1) the session messages will be printed
    via print

CONFIGURATION AND ENVIRONMENT
    Net::Magrathea requires no configuration files or environment variables.

DEPENDENCIES
    Moose

    Net::Telnet

    namespace::autoclean

INCOMPATIBILITIES
    None reported.

BUGS AND LIMITATIONS
    No bugs have been reported.

    Please report any bugs or feature requests to
    "bug-net-magrathea@rt.cpan.org", or through the web interface at
    <http://rt.cpan.org>.

AUTHOR
    Gavin Henry "<ghenry@suretecsystems.com>"

LICENCE AND COPYRIGHT
    Copyright (C) 2009, Suretec Systems Ltd. <http://www.suretecsystems.com>

    Copyright (c) 2009, Gavin Henry <ghenry@suretecsystems.com>. All rights
    reserved.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY
    BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
    FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
    OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
    PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
    EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
    ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
    YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
    NECESSARY SERVICING, REPAIR, OR CORRECTION.

    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
    WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
    REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
    TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
    SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
    RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
    FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
    SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
    DAMAGES.