File Coverage

blib/lib/Finance/LocalBitcoins/API.pm

Criterion	Covered	Total	%
statement	212	247	85.8
branch	15	30	50.0
condition	6	9	66.6
subroutine	74	99	74.7
pod	5	54	9.2
total	312	439	71.0

package Finance::LocalBitcoins::API;

use 5.014002;
use strict;
use warnings;

our $VERSION = '0.01';

use constant DEBUG   => 0;
use constant VERBOSE => 0;

# you can use a lower version, but then you are responsible for SSL cert verification code...
use LWP::UserAgent 6;
use URI;
use JSON;
use Data::Dumper;

## PUBLIC requests..
use Finance::LocalBitcoins::API::Request::Ticker;
use Finance::LocalBitcoins::API::Request::TradeBook;
use Finance::LocalBitcoins::API::Request::OrderBook;

# PRIVATE requests..
use Finance::LocalBitcoins::API::Request::User;
use Finance::LocalBitcoins::API::Request::Me;
use Finance::LocalBitcoins::API::Request::Pin;
use Finance::LocalBitcoins::API::Request::Dash;
use Finance::LocalBitcoins::API::Request::Wallet;
use Finance::LocalBitcoins::API::Request::Balance;
use Finance::LocalBitcoins::API::Request::ReleaseEscrow;
use Finance::LocalBitcoins::API::Request::Paid;
use Finance::LocalBitcoins::API::Request::Messages;
use Finance::LocalBitcoins::API::Request::Message;
use Finance::LocalBitcoins::API::Request::Dispute;
use Finance::LocalBitcoins::API::Request::Cancel;
use Finance::LocalBitcoins::API::Request::Fund;
use Finance::LocalBitcoins::API::Request::NewContact;
use Finance::LocalBitcoins::API::Request::Contact;
use Finance::LocalBitcoins::API::Request::Contacts;
use Finance::LocalBitcoins::API::Request::Send;
use Finance::LocalBitcoins::API::Request::SendPin;
use Finance::LocalBitcoins::API::Request::Address;
use Finance::LocalBitcoins::API::Request::Logout;
use Finance::LocalBitcoins::API::Request::Ads;
use Finance::LocalBitcoins::API::Request::AdGet;
use Finance::LocalBitcoins::API::Request::AdsGet;
use Finance::LocalBitcoins::API::Request::AdUpdate;
use Finance::LocalBitcoins::API::Request::Ad;

use constant COMPANY              => 'LocalBitcoins';
use constant ERROR_NO_REQUEST     => 'No request object to send';
use constant ERROR_NOT_READY      => 'Not enough information to send a %s request';
use constant ERROR_IS_IT_READY    => "The request is%s READY to send\n";
use constant ERROR_RESPONSE       => COMPANY . ' error';
use constant ERROR_UNKNOWN_STATUS => COMPANY . " returned an unknown status\n";

use constant ATTRIBUTES => qw(token);

use constant CLASS_ACTION_MAP => {
    user           => 'Finance::LocalBitcoins::API::Request::User',
    me             => 'Finance::LocalBitcoins::API::Request::Me',
    pin            => 'Finance::LocalBitcoins::API::Request::Pin',
    dash           => 'Finance::LocalBitcoins::API::Request::Dash',
    release_escrow => 'Finance::LocalBitcoins::API::Request::ReleaseEscrow',
    paid           => 'Finance::LocalBitcoins::API::Request::Paid',
    messages       => 'Finance::LocalBitcoins::API::Request::Messages',
    message        => 'Finance::LocalBitcoins::API::Request::Message',
    dispute        => 'Finance::LocalBitcoins::API::Request::Dispute',
    cancel         => 'Finance::LocalBitcoins::API::Request::Cancel',
    fund           => 'Finance::LocalBitcoins::API::Request::Fund',
    new_contact    => 'Finance::LocalBitcoins::API::Request::NewContact',
    contact        => 'Finance::LocalBitcoins::API::Request::Contact',
    contacts       => 'Finance::LocalBitcoins::API::Request::Contacts',
    wallet         => 'Finance::LocalBitcoins::API::Request::Wallet',
    balance        => 'Finance::LocalBitcoins::API::Request::Balance',
    'send'         => 'Finance::LocalBitcoins::API::Request::Send',
    sendpin        => 'Finance::LocalBitcoins::API::Request::SendPin',
    address        => 'Finance::LocalBitcoins::API::Request::Address',
    logout         => 'Finance::LocalBitcoins::API::Request::Logout',
    ads            => 'Finance::LocalBitcoins::API::Request::Ads',
    ad_get         => 'Finance::LocalBitcoins::API::Request::AdGet',
    ads_get        => 'Finance::LocalBitcoins::API::Request::AdsGet',
    ad_update      => 'Finance::LocalBitcoins::API::Request::AdUpdate',
    ad             => 'Finance::LocalBitcoins::API::Request::Ad',
    ticker         => 'Finance::LocalBitcoins::API::Request::Ticker',
    tradebook      => 'Finance::LocalBitcoins::API::Request::TradeBook',
    orderbook      => 'Finance::LocalBitcoins::API::Request::OrderBook',
};

sub is_ready_to_send {
    my $self = shift;
    my $ready = 0;
    # here we are checking whether or not to default to '0' (not ready to send) based on this objects settings.
    # the setting in here is the token provided to you by LocalBitcoins.
    # if we dont have to add a token, then just check if its ready...
    if (not $self->private or defined $self->token) {
       $ready = $self->request->is_ready_to_send;
    }
    warn sprintf ERROR_IS_IT_READY, ($ready ? '' : ' NOT') if DEBUG;

    return $ready;
}

sub send {
    my $self = shift;

    # clear any previous response values... because if you wan it, you shoulda put a variable on it.
    $self->response(undef);
    $self->error(undef);

    unless ($self->request) {
        $self->error({
            type    => __PACKAGE__,
            message => ERROR_NO_REQUEST,
        });
    }
    else {
        # validate that the minimum required request attributes are set here.
        if (not $self->is_ready_to_send) {
             $self->error({
                 type    => __PACKAGE__,
                 message => sprintf(ERROR_NOT_READY, ref $self->request),
             });
        }
        else {
            # make sure we have an request to send...
            my $request = $self->http_request(HTTP::Request->new);
            $request->method($self->request->request_type);
            $request->uri($self->request->url);
            my %query_form = %{$self->request_content};
#
# This block will be removed once we have basic testing completed.
# ...because printing these variables on a live system is not a good idea...
#
#if ($self->private) {
#    print Data::Dumper->Dump([\%query_form],['Query Form']);
#    printf "Token: %s\n", $self->token;
#    printf "Path: %s\n", $self->path;
#}
#
            if ($self->private) {
                $query_form{access_token} = $self->token;
            }

            my $uri = URI->new;
            $uri->query_form(%query_form);
            if ($self->request->request_type eq 'POST') {
                $request->content($uri->query);
                $request->content_type($self->request->content_type);
            }
            elsif ($self->request->request_type eq 'GET' and $uri->query) {
                $request->uri($request->uri . '?' . $uri->query);
            }

            $request->header(Accept => 'application/json');

            # create a new user_agent each time...
            $self->user_agent(LWP::UserAgent->new);
            $self->user_agent->agent('Mozilla/8.0');
            $self->user_agent->ssl_opts(verify_hostname => 1);

            warn Data::Dumper->Dump([$self->user_agent, $request],[qw(UserAgent Request)]) if DEBUG;

            $self->http_response($self->user_agent->request($request));
            $self->process_response;
        }
    }
    return $self->is_success;
}

sub process_response {
    my $self = shift;

    warn sprintf "Content: %s\n", $self->http_response->content if DEBUG;

    eval {
        my $content;
        warn Data::Dumper->Dump([$self->http_response],['Response']) if DEBUG;
        $content = $self->json->decode($self->http_response->content);
        if (ref $content eq 'ARRAY') {
            $self->response($content);
        }
        elsif (exists $content->{error}) {
            $self->error({
                type    => ERROR_RESPONSE,
                %{$content->{error}},
            });
        }
        elsif ($self->http_response->code != 200) {
            warn sprintf "Invalid Server Response Code: %s\n", $self->http_response->code if VERBOSE;
            $self->error({
                type    => 'Server Response Error',
                message => sprintf('%s Server Response: %s', COMPANY, $self->http_response->code),
            });
        }
        else {
            $self->response($content);
        }
        1;
    } or do {
        warn "eval error: $@\n";
        $self->error({
            type    => 'eval/json error',
            message => $@,
        });
    };

    return $self->is_success;
}

sub new             { (bless {} => shift)->init(@_)                  }
sub path            { URI->new(shift->http_request->uri)->path       }
sub request_content { shift->request->request_content                }
sub json            { shift->{json} ||= JSON->new                    }
sub is_success      { defined shift->response                        }
sub private         { shift->request->is_private                     }
sub public          { not shift->private                             }
sub attributes      { ATTRIBUTES                                     }

sub user            { class_action(@_) }
sub me              { class_action(@_) }
sub pin             { class_action(@_) }
sub dash            { class_action(@_) }
sub release_escrow  { class_action(@_) }
sub paid            { class_action(@_) }
sub messages        { class_action(@_) }
sub message         { class_action(@_) }
sub dispute         { class_action(@_) }
sub cancel          { class_action(@_) }
sub fund            { class_action(@_) }
sub new_contact     { class_action(@_) }
sub contact         { class_action(@_) }
sub contacts        { class_action(@_) }
sub wallet          { class_action(@_) }
sub balance         { class_action(@_) }
sub send_coin       { class_action(@_) }
sub send_pin        { class_action(@_) }
sub address         { class_action(@_) }
sub logout          { class_action(@_) }
sub ads             { class_action(@_) }
sub ad_get          { class_action(@_) }
sub ads_get         { class_action(@_) }
sub ad_update       { class_action(@_) }
sub ad              { class_action(@_) }
sub ticker          { class_action(@_) }
sub tradebook       { class_action(@_) }
sub orderbook       { class_action(@_) }

sub token           { get_set(@_) }
sub error           { get_set(@_) }
sub http_response   { get_set(@_) }
sub request         { get_set(@_) }
sub response        { get_set(@_) }
sub http_request    { get_set(@_) }
sub user_agent      { get_set(@_) }

sub init {
    my $self = shift;
    my %args = @_;
    foreach my $attribute ($self->attributes) {
        $self->$attribute($args{$attribute}) if exists $args{$attribute};
    }
    return $self;
}

# this method simply makes all the get/setter attribute methods below very tidy...
sub get_set {
   my $self      = shift;
   my $attribute = ((caller(1))[3] =~ /::(\w+)$/)[0];
   $self->{$attribute} = shift if scalar @_;
   return $self->{$attribute};
}

sub class_action {
    my $self = shift;
    my $class = CLASS_ACTION_MAP->{((caller(1))[3] =~ /::(\w+)$/)[0]};
    $self->request($class->new(@_));
    return $self->send ? $self->response : undef;
}

# These additional routines will allow you to easily encrypt your API secret using a similar but random text string as a key.
# Generate and store a random string of 40 hex chars in your script.
#   perl -e 'use Finance::CaVirtex::API qw(string_encrypt); print "Encrypted: %s\n", string_encrypt('put your token here', $random_key);
# to output the cyphertext of the real secret encrypted using your key.
# Your script should then load the cyphertext from an external file and call this:
#   my $api_secret = string_decrypt($cyphertext, $random_key);
# Since both the random_key and the cyphertext are in separate files, a breach would require both files to be compromised.
# If you also put the token into a database table that is accessed during runtime... then you are further protected.
# This setup would require 3 distinct components which would all need to be compromised to gain unwanted access to your API keys and functions.
#
# From the command line, you can generate a set of semi-random strings that should be good enough for this using:
#  perl -e 'print join("",("a".."z",0..9)[map rand$_,(36) x 22])."\n"for 1..20;'
#
# select one of those as your random_key.
#

# encryption works by assigning an ordinal value to each character '0' = 0 ... 'Z' = 35
# these values are then added for each character in the cypher and the random key.
# the modulus of the sum is then taken to remain within the 36 available characters.
# this number is then converted back to character.
# once each character of the string is calculated, the complete cyphertext is generated.
#
# the end result is that we are adding the secret string to the random key string to obtain the cyphertext:
#    Cypher = Secret + Key
#
# decryption is exactly like encryption except we take the difference of each character
# instead of the sum.
#
# the end result is thatIn this way we are subtracting the random key from the cyphertext to get back the secret string.
#    Secret = Cypher - Key
#
# I believe this method is equivalent to XOR encryption, which is very strong as long as the key is random and kept secret.
#
sub alphanum_to_digit { ord($_[0]) > 57 ? ord($_[0]) - 87 : ord($_[0]) - 48  }
sub digit_to_alphanum { chr($_[0]  >  9 ?     $_[0]  + 87 :     $_[0]  + 48) }
sub string_encrypt    { join '', map(digit_to_alphanum((alphanum_to_digit(substr $_[0], $_, 1) + alphanum_to_digit(substr $_[1], $_, 1)) % 36), 0 .. length($_[0]) - 1) }
sub string_decrypt    { join '', map(digit_to_alphanum((alphanum_to_digit(substr $_[0], $_, 1) - alphanum_to_digit(substr $_[1], $_, 1)) % 36), 0 .. length($_[0]) - 1) }
sub gen_random_key    { join("",("a".."f",0..9)[map rand$_,(16) x 40]) }


1;

__END__