File Coverage

blib/lib/WWW/MyNewsletterBuilder.pm

Criterion	Covered	Total	%
statement	7	9	77.7
branch			n/a
condition			n/a
subroutine	3	3	100.0
pod			n/a
total	10	12	83.3

#
# Copyright (C) 2010 JBA Network (http://www.jbanetwork.com)
# WWW::MyNewsletterBuilder is free software; you can redistribute it
# and/or modify it under the same terms as Perl itself.
#
# WWW::MyNewsletterBuilder is an interface to the mynewsletterbuilder.com
# XML-RPC API.
#
# $Id: MyNewsletterBuilder.pm 59878 2010-05-04 22:15:50Z bo $
#

package WWW::MyNewsletterBuilder;

use strict;
use warnings;
use Frontier::Client;

our $VERSION = '0.021';

sub new {
	my $class = shift;
	my $args  = ($#_ == 0) ? { %{ (shift) } } : { @_ };

	if (!$args->{api_key}){
		die('you must pass an api_key to WWW::MyNewsletterBuilder->new()');
	}

	my $self  = {
		api_key       => $args->{api_key},
		username      => $args->{username},
		password      => $args->{password},
		timeout       => $args->{timeout}       || 300,
		secure        => $args->{secure}        || 0,
		no_validation => $args->{no_validation} || 0,
		_api_host     => $args->{_api_host}     || 'api.mynewsletterbuilder.com',
		_api_version  => $args->{_api_version}  || '1.0',
		_debug        => $args->{_debug}        || 0,
	};

	bless($self, $class);

	# we have to bless before setting up the url and client
	my $url = $self->_buildUrl();
	if ($self->{_debug}){
		print "url: $url\n";
	}

	$self->{client} = $self->_getClient($url);
	return $self;
}

# the only config var that might need to be changed between calls is timeout
sub Timeout{
	my $self = shift;
	$self->{timeout} = shift;
	$self->{client}->{ua}->timeout($self->{timeout});
	return 1;
}

sub Campaigns{
	my $self    = shift;
	my $filters = ($#_ == 0) ? { %{ (shift) } } : { @_ };

	$filters = $self->_validateHash(
		$filters,
		{
			status => {
				value   => 'string',
				emptyOk => 1,
			},
			archived => {
				value   => 'bool',
				emptyOk => 1,
			},
			published => {
				value   => 'bool',
				emptyOk => 1,
			},
		},
		1
	);

	return $self->_Execute('Campaigns', $filters);
}

sub CampaignDetails{
	my $self = shift;
	my $id   = $self->_intify(shift);

	return $self->_Execute('CampaignDetails', $id);
}

sub CampaignCreate{
	my $self          = shift;
	my $name          = $self->_stringify(shift);
	my $subject       = $self->_stringify(shift);
	my $from          = shift;
	my $reply         = shift;
	my $html          = $self->_stringify(shift);
	my $text          = $self->_stringify(shift || '', 1);
	my $link_tracking = $self->_boolify(shift || 1);
	my $gat           = $self->_boolify(shift || 0);

	$from = $self->_validateHash(
		$from,
		{
			name => {
				value => 'string',
			},
			email => {
				value => 'string',
			},
		},
	);

	$reply = $self->_validateHash(
		$reply,
		{
			name => {
				value => 'string',
				emptyOk => 1,
			},
			email => {
				value => 'string',
				emptyOk => 1,
			},
		},
		1
	);

	return $self->_Execute(
		'CampaignCreate',
		$name,
		$subject,
		$from,
		$reply,
		$html,
		$text,
		$link_tracking,
		$gat,
	);
}

sub CampaignUpdate{
	my $self          = shift;
	my $id            = $self->_intify(shift);
	my $details       = shift;

	my $signature = {};
	$signature->{name}             = {value => 'string'};
	$signature->{subject}          = {value => 'string'};
	$signature->{html}             = {value => 'string'};
	$signature->{text}             = {value => 'string', emptyOk => 1};
	$signature->{link_tracking}    = {value => 'bool',   emptyOk => 1};
	$signature->{gat}              = {value => 'bool',   emptyOk => 1};

	$signature->{from} = {
		value => {
			name => {
				value => 'string',
			},
			email => {
				value => 'string',
			},
		},
	};
	$signature->{reply} = {
		value => {
			name => {
				value => 'string',
				emptyOk => 1,
			},
			email => {
				value => 'string',
				emptyOk => 1,
			},
		},
		emptyOk => 1,
	};

	$details = $self->_validateHash($details, $signature);

	return $self->_Execute(
		'CampaignUpdate',
		$id,
		$details,
	);
}

sub CampaignCopy{
	my $self = shift;
	my $id   = $self->_intify(shift);
	my $name = $self->_stringify(shift || '', 1);

	return $self->_Execute('CampaignCopy', $id, $name);
}

sub CampaignDelete{
	my $self = shift;
	my $id   = $self->_intify(shift);

	return $self->_Execute('CampaignDelete', $id);
}

sub CampaignSchedule{
	my $self      = shift;
	my $id        = $self->_intify(shift);
	my $when      = $self->_stringify(shift);
	my $lists     = shift;
	my $smart     = $self->_boolify(shift || 0);
	my $confirmed = $self->_boolify(shift || 0);

	$lists = $self->_validateArray($lists, 'int', 1);

	return $self->_Execute(
		'CampaignSchedule',
		$id,
		$when,
		$lists,
		$smart,
		$confirmed
	);
}

sub CampaignStats{
	my $self = shift;
	my $id   = $self->_intify(shift);

	return $self->_Execute('CampaignStats', $id);
}

sub CampaignRecipients{
	my $self  = shift;
	my $id    = $self->_intify(shift);
	my $page  = $self->_intify(shift || 0);
	my $limit = $self->_intify(shift || 1000);

	return $self->_Execute(
		'CampaignRecipients',
		$id,
		$page,
		$limit
	);
}

sub CampaignOpens{
	my $self  = shift;
	my $id    = $self->_intify(shift);
	my $page  = $self->_intify(shift || 0);
	my $limit = $self->_intify(shift || 1000);

	return $self->_Execute(
		'CampaignOpens',
		$id,
		$page,
		$limit
	);
}

sub CampaignBounces{
	my $self  = shift;
	my $id    = $self->_intify(shift);
	my $page  = $self->_intify(shift || 0);
	my $limit = $self->_intify(shift || 1000);

	return $self->_Execute(
		'CampaignBounces',
		$id,
		$page,
		$limit
	);
}

sub CampaignClicks{
	my $self   = shift;
	my $id    = $self->_intify(shift);
	my $page  = $self->_intify(shift || 0);
	my $limit = $self->_intify(shift || 1000);

	return $self->_Execute(
		'CampaignClicks',
		$id,
		$page,
		$limit
	);
}

sub CampaignClickDetails{
	my $self   = shift;
	my $id     = $self->_intify(shift);
	my $url_id = $self->_intify(shift);
	my $page   = $self->_intify(shift || 0);
	my $limit  = $self->_intify(shift || 1000);

	return $self->_Execute(
		'CampaignClickDetails',
		$id,
		$url_id,
		$page,
		$limit
	);
}

sub CampaignSubscribes{
    my $self  = shift;
	my $id    = $self->_intify(shift);
	my $page  = $self->_intify(shift || 0);
	my $limit = $self->_intify(shift || 1000);

	return $self->_Execute(
		'CampaignSubscribes',
		$id,
		$page,
		$limit
	);
}

sub CampaignUnsubscribes{
    my $self  = shift;
	my $id    = $self->_intify(shift);
	my $page  = $self->_intify(shift || 0);
	my $limit = $self->_intify(shift || 1000);

	return $self->_Execute(
		'CampaignUnsubscribes',
		$id,
		$page,
		$limit
	);
}

sub CampaignUrls{
    my $self = shift;
	my $id   = $self->_intify(shift);

	return $self->_Execute('CampaignUrls', $id);
}

sub Lists{
	my $self = shift;

	return $self->_Execute('Lists');
}

sub ListDetails{
	my $self = shift;
	my $id   = $self->_intify(shift);

	return $self->_Execute('ListDetails', $id);
}

sub ListCreate{
	my $self        = shift;
	my $name        = $self->_stringify(shift);
	my $description = $self->_stringify(shift || '', 1);
	my $visible     = $self->_boolify(shift || 0);
	my $default     = $self->_boolify(shift || 0);

	return $self->_Execute(
		'ListCreate',
		$name,
		$description,
		$visible,
		$default
	);
}

sub ListUpdate{
	my $self        = shift;
	my $id          = $self->_intify(shift);
	my $details     = shift;

	my $signature = {};
	$signature->{name} = {
		value   => 'string',
		emptyOk => 1,
	};
	$signature->{description} = {
		value   => 'string',
		emptyOk => 1,
	};
	$signature->{visible} = {
		value   => 'bool',
		emptyOk => 1,
	};
	$signature->{default} = {
		value   => 'bool',
		emptyOk => 1,
	};

	$details = $self->_validateHash($details, $signature);

	return $self->_Execute('ListUpdate', $id, $details);
}

sub ListDelete{
	my $self        = shift;
	my $id          = $self->_intify(shift);
	my $delete_subs = $self->_boolify(shift || 0);

	return $self->_Execute('ListDelete', $id, $delete_subs);
}

sub Subscribe{
	my $self            = shift;
	my $details         = shift;
	my $lists           = shift;
	my $skip_opt_in     = $self->_boolify(shift || 0);
	my $update_existing = $self->_boolify(shift || 1);

	my $signature = {};
	$signature->{email}        = {value => 'string'};
	$signature->{first_name}   = {value => 'string', emptyOk => 1};
	$signature->{middle_name}  = {value => 'string', emptyOk => 1};
	$signature->{last_name}    = {value => 'string', emptyOk => 1};
	$signature->{full_name}    = {value => 'string', emptyOk => 1};
	$signature->{company_name} = {value => 'string', emptyOk => 1};
	$signature->{job_title}    = {value => 'string', emptyOk => 1};
	$signature->{phone_work}   = {value => 'string', emptyOk => 1};
	$signature->{phone_home}   = {value => 'string', emptyOk => 1};
	$signature->{address_1}    = {value => 'string', emptyOk => 1};
	$signature->{address_2}    = {value => 'string', emptyOk => 1};
	$signature->{address_3}    = {value => 'string', emptyOk => 1};
	$signature->{city}         = {value => 'string', emptyOk => 1};
	$signature->{state}        = {value => 'string', emptyOk => 1};
	$signature->{zip}          = {value => 'string', emptyOk => 1};
	$signature->{country}      = {value => 'string', emptyOk => 1};

	$details = $self->_validateHash($details, $signature);

	$lists = $self->_validateArray($lists, 'int', 1);

	return $self->_Execute(
		'Subscribe',
		$details,
		$lists,
		$skip_opt_in,
		$update_existing
	);
}

sub SubscribeBatch{
	my $self            = shift;
	my $subscribers     = shift;
	my $lists           = shift;
	my $skip_opt_in     = $self->_boolify(shift || 0);
	my $update_existing = $self->_boolify(shift || 1);

	my $signature = {};
	$signature->{email}        = {value => 'string'};
	$signature->{first_name}   = {value => 'string', emptyOk => 1};
	$signature->{middle_name}  = {value => 'string', emptyOk => 1};
	$signature->{last_name}    = {value => 'string', emptyOk => 1};
	$signature->{full_name}    = {value => 'string', emptyOk => 1};
	$signature->{company_name} = {value => 'string', emptyOk => 1};
	$signature->{job_title}    = {value => 'string', emptyOk => 1};
	$signature->{phone_work}   = {value => 'string', emptyOk => 1};
	$signature->{phone_home}   = {value => 'string', emptyOk => 1};
	$signature->{address_1}    = {value => 'string', emptyOk => 1};
	$signature->{address_2}    = {value => 'string', emptyOk => 1};
	$signature->{address_3}    = {value => 'string', emptyOk => 1};
	$signature->{city}         = {value => 'string', emptyOk => 1};
	$signature->{state}        = {value => 'string', emptyOk => 1};
	$signature->{zip}          = {value => 'string', emptyOk => 1};
	$signature->{country}      = {value => 'string', emptyOk => 1};

	$subscribers = $self->_validateArray($subscribers, $signature);

	$lists = $self->_validateArray($lists, 'int', 1);

	return $self->_Execute(
		'SubscribeBatch',
		$subscribers,
		$lists,
		$skip_opt_in,
		$update_existing
	);
}

sub Subscribers{
	my $self = shift;
	my $statuses = shift;
	my $lists = shift;
	my $page  = $self->_intify(shift || 0);
	my $limit = $self->_intify(shift || 1000);

	return $self->_Execute('Subscribers', $statuses, $lists, $page, $limit);
}

sub SubscriberDetails{
	my $self        = shift;
	my $id_or_email = $self->_stringify(shift);

	return $self->_Execute('SubscriberDetails', $id_or_email);
}

sub SubscriberUpdate{
	my $self        = shift;
	my $id_or_email = $self->_stringify(shift);
	my $details     = shift;
	my $lists       = shift;

	my $signature = {};
	$signature->{email}        = {value => 'string'};
	$signature->{first_name}   = {value => 'string', emptyOk => 1};
	$signature->{middle_name}  = {value => 'string', emptyOk => 1};
	$signature->{last_name}    = {value => 'string', emptyOk => 1};
	$signature->{full_name}    = {value => 'string', emptyOk => 1};
	$signature->{company_name} = {value => 'string', emptyOk => 1};
	$signature->{job_title}    = {value => 'string', emptyOk => 1};
	$signature->{phone_work}   = {value => 'string', emptyOk => 1};
	$signature->{phone_home}   = {value => 'string', emptyOk => 1};
	$signature->{address_1}    = {value => 'string', emptyOk => 1};
	$signature->{address_2}    = {value => 'string', emptyOk => 1};
	$signature->{address_3}    = {value => 'string', emptyOk => 1};
	$signature->{city}         = {value => 'string', emptyOk => 1};
	$signature->{state}        = {value => 'string', emptyOk => 1};
	$signature->{zip}          = {value => 'string', emptyOk => 1};
	$signature->{country}      = {value => 'string', emptyOk => 1};

	$details = $self->_validateHash($details, $signature);

	$lists = $self->_validateArray($lists, 'int', 1);

	return $self->_Execute(
		'SubscriberUpdate',
		$id_or_email,
		$details,
		$lists,
	);
}

sub SubscriberUnsubscribe{
	my $self        = shift;
	my $id_or_email = $self->_stringify(shift);

	return $self->_Execute('SubscriberUnsubscribe', $id_or_email);
}

sub SubscriberUnsubscribeBatch{
	my $self          = shift;
	my $ids_or_emails = shift;

	$ids_or_emails = $self->_validateArray($ids_or_emails, 'string');

	return $self->_Execute('SubscriberUnsubscribeBatch', $ids_or_emails);
}

sub SubscriberDelete{
	my $self        = shift;
	my $id_or_email = $self->_stringify(shift);

	return $self->_Execute('SubscriberDelete', $id_or_email);
}

sub SubscriberDeleteBatch{
	my $self          = shift;
	my $ids_or_emails = shift;

	$ids_or_emails = $self->_validateArray($ids_or_emails, 'string');

	return $self->_Execute('SubscriberDeleteBatch', $ids_or_emails);
}

sub AccountKeys{
	my $self     = shift;
	my $username = $self->_stringify(shift);
	my $password = $self->_stringify(shift);
	my $disabled = $self->_boolify(shift || 0);

	return $self->_Execute(
		'AccountKeys',
		$username,
		$password,
		$disabled,
	);
}

sub AccountKeyCreate{
	my $self     = shift;
	my $username = $self->_stringify(shift);
	my $password = $self->_stringify(shift);

	return $self->_Execute('AccountKeyCreate', $username, $password);
}

sub AccountKeyEnable{
	my $self      = shift;
	my $username  = $self->_stringify(shift);
	my $password  = $self->_stringify(shift);
	my $id_or_key = $self->_stringify(shift);

	return $self->_Execute(
		'AccounKeyEnable',
		$username,
		$password,
		$id_or_key
	);
}

sub AccountKeyDisable{
	my $self      = shift;
	my $username  = $self->_stringify(shift);
	my $password  = $self->_stringify(shift);
	my $id_or_key = $self->_stringify(shift);

	return $self->_Execute(
		'AccounKeyDisable',
		$username,
		$password,
		$id_or_key
	);
}

sub HelloWorld{
	my $self = shift;
	my $val  = $self->_stringify(shift || '', 1);

	return $self->_Execute('HelloWorld', $val);
}

sub _Execute{
	my $self   = shift;
	my $method = shift;

	$self->{errno}  = '';
	$self->{errstr} = '';

	my $data;
	eval{
		$data = $self->{client}->call($method, $self->{api_key}, @_);
	};

	if ($self->{_debug}){
		use Data::Dumper;
		print "returned data\n";
		print Dumper $data;
	}

	if ($@){
		$self->{errno}  = 2;
		$self->{errstr} = $@;

		if ($self->{_debug}){
			print 'errors: '. $self->{errno} .'--'. $self->{errstr} ."\n";
		}

		return 0;
	}
	elsif (!$data){
		$self->{errno}  = 2;
		$self->{errstr} = 'Empty response from API server';

		if ($self->{_debug}){
			print 'errors: '. $self->{errno} .'--'. $self->{errstr} ."\n";
		}

		return 0;
	}

	if (ref($data) eq 'HASH' && $data->{'errno'}){
		$self->{errno}  = $data->{'errno'};
		$self->{errstr} = $data->{'errstr'};
		return 0;
	}

	return $self->_unBoolify($data);
}

sub _buildUrl{
	my $self = shift;
	my $url;
	if ($self->{secure}){
		$url = 'https://';
	}
	else{
		$url = 'http://';
	}

	return $url . $self->{_api_host} . '/' . $self->{_api_version};
}

sub _getClient{
	my $self = shift;
	my $url  = shift;

	my $client = Frontier::Client->new(
		url   => $url,
		debug => 0,
	);

	# we have to modify Frontier's LWP instance a little bit.
	$client->{ua}->agent('MNB_API Perl ' . $self->{_api_version} . '/' . $VERSION . '-' . '$Rev: 59878 $');
	$client->{ua}->requests_redirectable(['GET', 'HEAD', 'POST' ]);
	$client->{ua}->timeout($self->{timeout});

	return $client;
}

sub _error{
	my $self = shift;
	my $msg  = shift;
	my $warn = shift || 0;

	if ($self->{no_validation} || $warn){
		warn($msg);
	}
	else{
		die($msg);
	}
}

sub _validateArray{
	my $self      = shift;
	my $array     = shift;
	my $signature = shift;
	my $emptyOk   = shift || 0;

	my $isHash = 0;
	if (ref($signature) eq 'HASH'){
		$isHash = 1;
	}

	if (!$array and !$emptyOk){
		$self->_error('invalid param passed to '. (caller(1))[3] .':'. (caller(0))[2] .' from '. (caller(1))[1]  .':'. (caller(1))[2] .' expected array got '. $array);
	}

	foreach (@$array){
		if ($isHash){
			$_ = validateHash($_, $signature, $emptyOk);
		}
		else{
			my $function = '_' . $signature . 'ify';
			$_ = $self->$function($_, $emptyOk);
		}
	}
	return $array;
}

##
#
# takes a hash and a signature for that hash and validates the hash's
# values then makes sure they are the proper xml-rpc types.
#
##
sub _validateHash{
	my $self      = shift;
	my $hash      = shift;
	my $signature = shift;
	my $emptyOk   = shift || 0;

	if (!$hash and !$emptyOk){
		$self->_error('invalid param passed to '. (caller(1))[3] .':'. (caller(0))[2] .' from '. (caller(1))[1]  .':'. (caller(1))[2] .' expected hash got '. $hash);
	}

	##
	#
	# we loop through the signature keys.  if the value is a hash
	# we need recursively call this function.  if it is a string
	# we validate it based on the type.
	#
	##
	foreach (keys(%$signature)){
		if (ref($signature->{$_}->{value}) eq 'HASH'){
			$hash->{$_} = $self->_validateHash($hash->{$_}, $signature->{$_}->{value}, $signature->{$_}->{emptyOk}) if (defined($hash->{$_}));
		}
		else{
			my $function = '_' . $signature->{$_}->{value} . 'ify';
			$hash->{$_} = $self->$function($hash->{$_}, $signature->{$_}->{emptyOk}) if (defined($hash->{$_}));
		}
	}

	return $hash;
}

##
#
# $self->_intify( int $var, bool $require)
# validates value of $var as an int... throws error if it isn't
# converts to Frontier int data type if test passed (or we aren't validating data))
#
##
sub _intify{
	my $self    = shift;
	my $var     = shift;
	my $emptyOk = shift || 0;

	my $check = '\d+';
	$check = '\d*' if ($emptyOk);

	$self->_error('invalid param passed to '. (caller(1))[3] .':'. (caller(0))[2] .' from '. (caller(1))[1]  .':'. (caller(1))[2] .' expected int got '. $var) unless ($var =~ /^($check)$/);

	return $self->{client}->int($var);
}

##
#
# $self->_stringify( string $var, bool $require)
# validates value of $var as an string... throws error if it isn't
# converts to Frontier string data type if test passed (or we aren't validating data))
#
##
sub _stringify{
	my $self    = shift;
	my $var     = shift;
	my $emptyOk = shift || 0;

	my $check = '.+';
	$check = '.*' if ($emptyOk);

	$self->_error('invalid param passed to '. (caller(1))[3] .':'. (caller(0))[2] .' from '. (caller(1))[1] .':'. (caller(1))[2] .' expected string got '. $var) unless ($var =~ /^($check)$/);

	return $self->{client}->string($var);
}

##
#
# $self->boolfy( int $var, bool $require)
# validates value of $var as a bool... throws error if it isn't
# converts to Frontier bool data type if test passed (or we aren't validating data))
#
##
sub _boolify{
	my $self    = shift;
	my $var     = shift;

	$self->_error('invalid param passed to '. (caller(1))[3] .':'. (caller(0))[2] .' from '. (caller(1))[1]  .':'. (caller(1))[2] .' expected bool(0 or 1) got '. $var) unless ($var =~ /^(0|1)$/);

	return $self->{client}->boolean($var);
}

sub _unBoolify{
	my $self    = shift;
	my $var     = shift;

	if (ref($var) eq 'ARRAY'){
		foreach my $v (@$var){
			$v = $self->_unBoolify($v);
		}
	}

	if (ref($var) eq 'HASH'){
		foreach (keys(%$var)){
			$var->{$_} = $self->_unBoolify($var->{$_});
		}
	}

	if (ref($var) ne 'Frontier::RPC2::Boolean'){
		return $var;
	}
	return $var->value;
}

1;
__END__