File Coverage

blib/lib/Net/SMS/TextMagic.pm

Criterion	Covered	Total	%
statement	35	175	20.0
branch	5	46	10.8
condition	3	12	25.0
subroutine	7	19	36.8
pod	13	13	100.0
total	63	265	23.7

#
# Net::SMS::TextMagic  This module provides access to TextMagic SMS service
#
# Author: Matti Lattu
#
# Copyright (c) 2011 Matti Lattu. All rights reserved.
# This program is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
# For TextMagic and its possible Copyright see http://www.textmagic.com/

package Net::SMS::TextMagic;

use strict;
use warnings;

our $VERSION = '1.00';

use JSON;
use LWP::UserAgent;
use URI::Escape qw(uri_escape uri_escape_utf8);
use Encode qw(encode decode);

=encoding utf8

=head1 SYNOPSIS

use Net::SMS::TextMagic;

 my $sms = Net::SMS::TextMagic->new( USER => $username, API_ID => $api_id );
 $sms->message_send(text=>'This is a test!', phone=>'35891911');

=head1 DESCRIPTION

TextMagic (http://www.textmagic.com) is a commercial service that allows its users to send
SMS messages to anyone in the world.

Net::SMS::TextMagic provides OO methods that allow to send SMS messages through
TextMagic service. The TextMagic HTTPS API is documented at
L. This module implements all HTTPS API commands
and return values.
However, all command parameters and return values are not necessary mentioned or thorougly
described in this document. Please consult the original API document for details.

Note that whether this software nor the author are related to TextMagic in any way.

=head1 METHODS

=over 4

=item new

Creates the TextMagic object.

Usage:

 my $sms = Net::SMS::TextMagic->new( USER => $username, API_ID => $api_id );

The complete list of arguments is:

B
Your TextMagic username. Same as your username to TextMagic web service.
Required.

B
Your TextMagic API ID. The API ID is not your password to TextMagic
web service. You can get your API ID from the
TextMagic web service. Required.

B
TextMagic API URL. Defaults to https://www.textmagic.com/app/api.

B
Name of the user agent you want to display to TextMagic service.
Defaults to "Net::SMS::TextMagic"

B
UserAgent timeout. Defaults to 10 seconds.

Returns Net::SMS::TextMagic object or false (in case USER or API_ID are missing).

=cut

sub new {
	my ($class, %params) = @_;

	my $self = {};

	# Store TextMagic username (required)

	if ($params{'USER'}) {
		$self->{'USER'} = $params{'USER'};
		}
	else {
		# USER parameter is missing - return false
		return;
		}

	# Store TextMagic API ID (required)

	if ($params{'API_ID'}) {
		$self->{'API_ID'} = $params{'API_ID'};
		}
	else {
		# API_ID parameter is missing - return false
		return;
		}

	# Create LWP::UserAgent
	$self->{'UA'} = LWP::UserAgent->new;

	# Set TextMagic API URL (optional)

	if (defined($params{'API_URL'}) and $params{'API_URL'} ne '') {
		$self->{'API_URL'} = $params{'API_URL'};
		}
	else {
		$self->{'API_URL'} = 'https://www.textmagic.com/app/api';
		}

	# Set UserAgent string (optional)

	if (defined($params{'UserAgent'}) and $params{'UserAgent'} ne '') {
		$self->{'UA'}->agent($params{'UserAgent'});
		}
	else {
		$self->{'UA'}->agent('Net::SMS::TextMagic');
		}

	# Set UserAgent timeout (optional)

	if (defined($params{'Timeout'}) and $params{'Timeout'} ne '') {
		$self->{'UA'}->timeout($params{'Timeout'});
		}
	else {
		# Default timeout is 10 seconds

		$self->{'UA'}->timeout(10);
		}

	# Current error message
	$self->{'ERROR'} = undef;

	# Unprocessed error messages
	$self->{'ERROR_UNPROC'} = [];

	bless($self, $class);

	return $self;
	}

=item message_send

Sends SMS message. Equals to HTTPS API command "send" but renamed in
the module to avoid conflict with built-in send function.

Usage:

 my %response = $sms->message_send(text=>'This is a test!', phone=>'35891911');
 print "Sent message $response{'sent_text'} chopped in $response{'parts_count'} parts\n";

The complete list of arguments is:

B
Message text in Perl internal charset. Required.

B
Phone number(s). The numbers are sent "as is". Currently the API supports up to
100 numbers separated by commas (,). Required.

B
If set to true the message text is sent as UTF-8. Otherwise the text is sent
in GSM 03.38 encoding. Defaults to true (UTF-8).

B, B, B
See TextMagic HTTPS API documentation.

Returns a hash containing following keys:

B
The text (in Perl internal charset) that was actually sent.

B
The number of parts the message has.

B
A hash containing pairs of numbers (keys) and message_ids (values) that were
sent.

=cut

sub message_send {
	my ($class, %params) = @_;

	# Check for required parameters
	if ((!$params{'text'}) or (!$params{'phone'})) {
		set_error($class, "method 'message_send' was called without required parameters");
		return;
		}

	# UNICODE defaults to true
	if (!defined($params{'unicode'})) {
		$params{'unicode'} = 1;
		}

	if ($params{'unicode'}) {
		# Encode message as UTF8
		$params{'text'} = uri_escape($params{'text'});
		}
	else {
		# Encode message as GSM 03.38
		$params{'text'} = encode("gsm0338", $params{'text'});
		$params{'text'} = uri_escape($params{'text'});
		}

	my $r_json = contact_api($class, 'send', %params);

	if (defined($r_json)) {
		# No errors

		my %response = ();

		$response{'sent_text'} = $r_json->{'sent_text'};

		$response{'parts_count'} = $r_json->{'parts_count'};

		while (my ($id, $number) = each %{$r_json->{"message_id"}} ) {
			  $response{'message_id'}{$number} = $id;
			  }

		return %response;
		}
	else {
		# Errors, we expect that error flag was raised in contact_api()

		return;
		}
	}

=item account

Get the current SMS credit balance.

Usage:

 my %response = $sms->account();
 print "Your balance is $response{'balance'}\n";

Returns a hash containing following key:

B
The amount of available SMS credits on your account.

=cut

sub account {
	my ($class) = @_;

	my $r_json = contact_api($class, 'account');

	if (defined($r_json)) {
		# No errors

		my %response = ();

		$response{'balance'} = $r_json->{'balance'};

		return %response;
		}
	else {
		# Errors, we expect that error flag was raised in contact_api()

		return;
		}
	}

=item message_status

This method allows you to retrieve the delivery status of any SMS you have
already sent. The message ID is returned by message_send command.

Usage:

 my $this_id = 123456;
 my %response = $sms->message_status($this_id);
 print 'Message text was '.$response{$this_id}{'text'}."\n";
 print 'The cost was '.$response{$this_id}{'credits_cost'}." credits\n";

The only parameter is a string containing message ID or several IDs
separated by commas and without spaces (e.g. "8624389,8624390,8624391").
Up to 100 IDs can be retrieved with a single command.

Returns a two-level hash containing status of message IDs. Each ID has following
fields:

B
SMS text sent.

B
The current status of the message. The status codes are explained at
L.

B
The time TextMagic sent the message. Unix timestamp.

B
See API documentation for details.

B
Cost of the message in SMS credits. Set when message is delivered.

B
The time your message achieves final status, returned by the mobile operator.
Unix timestamp.

=cut

sub message_status {
	my ($class, $ids) = @_;

	# Check for required parameters
	if (!$ids) {
		set_error($class, "method 'message_status' was called without parameters");
		return;
		}

	my %params = ('ids' => $ids);

	my $r_json = contact_api($class, 'message_status', %params);

	if (defined($r_json)) {
		# No errors

		my %response = ();

		foreach my $this_id (keys %{$r_json}) {
			$response{$this_id} = ();
			$response{$this_id}{'text'} = encode("utf8", $r_json->{$this_id}->{'text'});
			$response{$this_id}{'status'} = $r_json->{$this_id}->{'status'};
			$response{$this_id}{'created_time'} = $r_json->{$this_id}->{'created_time'};
			$response{$this_id}{'reply_number'} = $r_json->{$this_id}->{'reply_number'};
			$response{$this_id}{'credits_cost'} = $r_json->{$this_id}->{'credits_cost'};
			$response{$this_id}{'completed_time'} = $r_json->{$this_id}->{'completed_time'};
			}

		return %response;
		}
	else {
		# Errors, we expect that error flag was raised in contact_api()

		return;
		}
	}

=item receive

This method retrieves the incoming SMS messages from the server.
The server is limited to returning a maximum of 100 messages for
each request. Please use last_retrieved_id parameter to page through
your inbox.

The only optional parameter is B. The server will
only return messages with identifiers greater than B.
The default value is 0 which fetches up to the first 100 replies from
your inbox.

Returns a hash containing following keys:

B
The number of messages with identifiers greater than B
remaining unreturned due to the limit on returned messages per request.

B
Number of messages in the current B hash.

B
An array containing all messages. Each object in the array is a hash
with following keys:

=over 4

B
The identifier of the incoming message.

B
The sender's phone number.

B
The message's reception time expressed in Unix time format.

B
The message text.

=back

=cut

sub receive {
	my ($class,$lrid) = @_;

	if (!defined($lrid)) {
		# Default value for last_retrieved_id
		$lrid = 0;
		}

	my %params = ('last_retrieved_id' => $lrid);

	my $r_json = contact_api($class, 'receive', %params);

	if (defined($r_json)) {
		# No errors

		my %response = ();

		$response{'unread'} = $r_json->{'unread'};
		$response{'messages_count'} = scalar(@{$r_json->{'messages'}});

		print "messages count: ".scalar(@{$r_json->{'messages'}})."\n";

		for (my $i=0; $i < scalar(@{$r_json->{'messages'}}); $i++) {
			my %this_msg_data = ();
			$this_msg_data{'message_id'} = @{$r_json->{'messages'}}[$i]->{'message_id'};
			$this_msg_data{'from'} = @{$r_json->{'messages'}}[$i]->{'from'};
			$this_msg_data{'timestamp'} = @{$r_json->{'messages'}}[$i]->{'timestamp'};
			$this_msg_data{'text'} = encode("utf8", @{$r_json->{'messages'}}[$i]->{'text'});
			push(@{$response{'messages'}}, {%this_msg_data});
			}

		return %response;
		}
	else {
		# Errors, we expect that error flag was raised in contact_api()

		return;
		}
	}

=item delete_reply

This command helps you to delete any incoming SMS messages from the server.

Usage:

 my @response = $sms->delete_reply('123456,123457,123458');
 print "Following messages were deleted: ".join(', ', @response)."\n";

The only required parameter is a string containing message IDs to be deleted.
The IDs should be separated with commas without spaces. Up to 100 messages
can be deleted with single command.

Returns an array containing message IDs that were deleted.

=cut

sub delete_reply {
	my ($class, $delids) = @_;

	if (!defined($delids)) {
		set_error($class, "method 'delete_reply' was called without parameters");
		return;
		}

	my %params = ('ids' => $delids);

	my $r_json = contact_api($class, 'delete_reply', %params);

	if (defined($r_json)) {
		# No errors

		return @{$r_json->{'deleted'}};
		}
	else {
		# Errors, we expect that error flag was raised in contact_api()

		return;
		}
	}

=item check_number

This command helps you to validate a phone number's format and to check a
message's price to its destination.

Usage:

 my %response = $sms->check_number('35891911,35891912');

 foreach my $this_number (keys %response) {
   print "Number $this_number is in ".
     $response{$this_number}{'country'}.
     'and the SMS cost is '.
     $response{$this_number}{'price'}.
     "credits.\n";
   }

The only required parameter is a string containing phone numbers to be checked.
The numbers should be separated with commas without spaces. The TextMagic HTTPS
API documentation does not specify the maximum number of phone numbers that
can be checked with a single command.

Returns a two-level hash containing status of numbers. Each number has following
fields:

B
The cost in SMS credits of sending a single message to the number.

B
The number's country code. A full list of country codes can be found at
L.

=cut

sub check_number {
	my ($class, $numbers) = @_;

	if (!defined($numbers)) {
		set_error($class, "method 'check_number' was called without parameters");
		return;
		}

	my %params = ('phone' => $numbers);

	my $r_json = contact_api($class, 'check_number', %params);

	if (defined($r_json)) {
		# No errors

		my %response = ();

		foreach my $this_number (keys %{$r_json}) {
			$response{$this_number}{'price'} = $r_json->{$this_number}->{'price'};
			$response{$this_number}{'country'} = $r_json->{$this_number}->{'country'};
			}

		return %response;
		}
	else {
		# Errors, we expect that error flag was raised in contact_api()

		return;
		}
	}

=item contact_api

Contacts TextMagic API. This in mainly for internal use, but can be used
to contact TextMagic API directly.

Usage:

 my $r_json = $sms->contact_api('some_api_command', %parameters);

Parameters:
- a string containing TextMagic HTTPS API command
- a hash containing command parameters

Returns a JSON object containing the result.

=cut

sub contact_api {
	my ($class, $cmd, %params) = @_;

	$params{'cmd'} = $cmd;
	$params{'username'} = $class->{'USER'};
	$params{'password'} = $class->{'API_ID'};

	my $response = $class->{'UA'}->post($class->{'API_URL'}, Content=>\%params);

	if ($response->is_success) {
		# For debugging
		# print "---JSON begins:\n".$response->decoded_content."\n---JSON ends\n";
		my $json_obj = decode_json($response->decoded_content);
		if ($json_obj->{'error_code'}) {
			# API error, set error message

			set_error($class, 'API error #'.$json_obj->{'error_code'}.': '.$json_obj->{'error_message'});
			return;
			}
		else {
			# API ok, return JSON object

			return $json_obj;
			}
		}
	else {
		# HTTP POST failed
		set_error($class, "HTTP POST failed: ".$response->status_line);
		return;
		}
	}

=item set_error

Sets Net::SMS::TextMagic error code. Mainly for internal use.

If there is already an unprocessed error message, this message
is appended to the unprocessed error array. The array can be read
and emptied with get_unprocessed_errors().

Usage:

 $sms->set_error('Out of credit');

=cut

sub set_error {
	my ($class, $errormsg) = @_;

	# If there are alredy current error, add error to error buffer
	if ($class->{'ERROR'}) {
		push(@{$class->{'ERROR_UNPROC'}}, $class->{'ERROR'});
		}

	$class->{'ERROR'} = $errormsg;

	return 1;
	}

=item get_error

Gets and clears Net::SMS::TextMagic error code. This does not affect the
array of unprocessed error messages (see get_unprocessed_errors()).

Usage:

 my %response = $sms->message_send('phone' => '123456', 'text' => 'Howdy!');
 if ($sms->if_error()) {
   my $errormsg = $sms->get_error();
   if ($errormsg) {
     print "Dough! $errormsg\n";
 	  }
 	}

No parameters. Returns a error string if error flag is up. If no error message is
present returns undef.

=cut

sub get_error {
	my ($class) = @_;

	my $errormsg = $class->{'ERROR'};
	$class->{'ERROR'} = undef;

	return $errormsg;
	}

=item if_error

Returns true if there is a pending error code (see get_error()).
Returns false if no error flag is set.

Usage:

 if ($sms->if_error()) {
   print STDERR "SMS error: ".$sms->get_error()."\n";
   }

=cut

sub if_error {
	my ($class) = @_;

	if ($class->{'ERROR'}) {
		return 1;
		}
	else {
		return;
		}
	}

=item get_unprocessed_errors

Returns and flushes the array of unprocessed errors. See set_error().

=cut

sub get_unprocessed_errors {
	my ($class) = @_;

	my @errors = @{$class->{'ERRORS_UNPROC'}};

	$class->{'ERRORS_UNPROC'} = [];

	return @errors;
	}

=item if_unprocessed_errors

Returns a number of items in the array of unprocessed errors. If
there are no errors returns undef (false).

=back

=cut

sub if_unprocessed_errors {
	my ($class) = @_;

	my $n = scalar(@{$class->{'ERRORS_UNPROC'}});

	if ($n == 0) {
		return;
		}

	return $n;
	}

1;

__END__