Net::SMS::Clickatell - Access to Clickatell SMS messaging service

  use Net::SMS::Clickatell;

  my $catell = Net::SMS::Clickatell->new( API_ID => $api_id );
  $catell->auth( USER => $user, PASSWD => $passwd );
  $catell->sendmsg( TO => $mobile_phone, MSG => 'Hi, I\'m using Clickatell.pm' );

#
# Net::SMS::Clickatell . This module provides access to Clickattel SMS messaging service
#
# Author: Roberto Alamos Moreno <ralamosm@cpan.org>
#
# Copyright (c) 2004 Roberto Alamos Moreno. All rights reserved.
# This program is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
# Clickatell is Copyright (c) 2004 Clickatell (Pty) Ltd: Bulk SMS Gateway
#
# November 2004. Antofagasta, Chile.
#
package Net::SMS::Clickatell;

$VERSION = '0.05';

use strict;
use warnings;
use diagnostics;

use LWP::UserAgent;
use URI::Escape qw(uri_escape);

sub new {
  my $class = shift || undef;
  if(!defined $class) {
    return undef;
  }

  # Get arguments
  my %args = (  UseSSL => 1,
		UserAgent => 'Clickatell.pm/'.$Net::SMS::Clickatell::VERSION,
		@_ );

  # Check arguments
  if(!exists $args{API_ID}) {
    # There isn't an API identification number. We can't continue
    return undef;
  }
  if($args{UseSSL} =~ /\D/) {
    # UseSSL argument wasn't valid. Set it to 1
    $args{UseSSL} = 1;
  }
  if(!exists $args{BaseURL}) {
    # BaseURL argument wasn't passed. Set it to default.
    # Check if we have to use SSL.
    if(exists $args{UseSSL}) {
      $args{BaseURL} = 'https://api.clickatell.com';
    } else {
      $args{BaseURL} = 'http://api.clickatell.com';
    }
  } else {
    # Set BaseURL property value.
    # Check if we have to use SSL.
    if(exists $args{UseSSL}) {
      $args{BaseURL} = 'https://'.$args{BaseURL};
    } else {
      $args{BaseURL} = 'http://'.$args{BaseURL};
    }
  }

  return bless { BASE_URL => $args{BaseURL},
		 API_ID => uri_escape($args{API_ID}),
		 USE_SSL => $args{UseSSL},
		 USER_AGENT => $args{UserAgent},
		 SESSION_ID => 0,
		 MSG_ID => 0,
		 ERROR => 0,}, $class;
}

sub auth {
  my $self = shift || undef;
  if(!defined $self) {
    return undef;
  }

  # Get arguments
  my %args = ( @_ );

  # Check arguments
  if(!exists $args{USER} || !exists $args{PASSWD}) {
    # User or password argument wasn't set
    $self->error(1);
    return undef;
  } else {
    # Convert arguments to HTTP-compatible format
    $args{USER} = uri_escape($args{USER});
    $args{PASSWD} = uri_escape($args{PASSWD});
  }

  # We have the arguments. Set session_id and msg_id to 0
  $self->session_id(0);
  $self->msg_id(0);

  # Form Clickatell URL
  my $url = $self->{BASE_URL}.'/http/auth?user='.$args{USER}.'&password='.$args{PASSWD}.'&api_id='.$self->{API_ID};

  # Create LWP object
  my $ua = LWP::UserAgent->new;
  $ua->agent($self->{USER_AGENT});

  # Form GET message
  my $req = HTTP::Request->new(GET => $url);
  $req->header('Accept' => 'text/html');

  # Send authentification request!
  my $res = $ua->request($req);

  # Check the response
  if ($res->is_success) {
      # HTTP transaction was succesfull
      # Parse response (OK: [session id])
      my @content = split(/\:/,$res->content);

      # Check if we logged in
      if($content[0] eq 'OK') {
        # Logged in! Store identification number and set error to 0 (no error)
	$content[1] =~ s/\s//g;
	$self->session_id($content[1]);
	$self->error(0);
      } else {
	# We didn't log in (wrong user or password)
	$self->error(2);
	return undef;
      }
  } else {
    # Something is wrong
    $self->error(3); # Server error ?
    return undef;
  }

  return 1;
}

sub sendmsg {
  my $self = shift || undef;
  if(!defined $self) {
    return undef;
  }

  # Check if we are logged in
  if(!$self->session_id) {
    return undef;
  }

  # Get arguments
  my %args = ( @_ );

  # Check arguments
  # Check destinatary number
  if(!exists $args{TO}) {
    # There isn't a mobile number to send the message
    return undef;
  } elsif($args{TO} =~ /\D/) {
    # The argument has something that isn't a digit
    return undef;
  } else {
    # Argument OK. Convert it to HTTP-compatible
    $args{TO} = uri_escape($args{TO});
  }

  # Check the message that will be sent
  if(!exists $args{MSG}) {
    # There's no message
    return undef;
  } else {
    # Message OK. Convert it to HTTP-compatible
    $args{MSG} = uri_escape($args{MSG});
  }

  # Clickatell URL that will be used to send the message
  my $url = $self->{BASE_URL}.'/http/sendmsg?session_id='.$self->session_id().'&to='.$args{TO}.'&text='.$args{MSG};

  # Create LWP object
  my $ua = LWP::UserAgent->new;
  $ua->agent($self->{USER_AGENT});

  # Prepare the message as POST variables
  my $req = HTTP::Request->new(POST => $self->{BASE_URL}.'/http/sendmsg');
  $req->content_type('application/x-www-form-urlencoded');
  $req->content('session_id='.$self->session_id().'&to='.$args{TO}.'&text='.$args{MSG});

  # Send message!
  my $res = $ua->request($req);

  # Check if the message was successfully sent
  if ($res->is_success) {
      # The HTTP transaction was succesfull
      # Parse response (ID: [message_id])
      my @content = split(/\:/,$res->content);

      if($content[0] eq 'ID') {
	# The message was successfully sent. Store message id and set error to 0 (there's no error)
        $content[1] =~ s/\s//g;
	$self->error(0);
        $self->msg_id($content[1]);
      } else {
	# The message wasn't sent :(
        $self->error(4);  # The message wasn't sent
	$self->msg_id(0); # There isn't a message
        return undef;
      }
  } else {
    # Something is wrong with the HTTP transaction
    $self->error(3);  # Server error ?
    $self->msg_id(0); # There isn't a message
    return undef;
  }

  return 1;
}

sub session_id {
  my $self = shift || undef;
  if(!defined $self) {
    return undef;
  }

  my $ssid = shift || undef;
  if(!$ssid) {
    return $self->{SESSION_ID};
  } else {
    $self->{SESSION_ID} = $ssid;
    return 0;
  }
}

sub msg_id {
  my $self = shift || undef;
  if(!defined $self) {
    return undef;
  }

  my $msid = shift || undef;
  if(!$msid) {
    return $self->{MSG_ID};
  } else {
    $self->{MSG_ID} = $msid;
    return 0;
  }
}

sub error {
  my $self = shift || undef;
  if(!defined $self) {
    return undef;
  }

  my $error = shift || undef;
  if(!defined $error) {
    return $self->{ERROR};
  } else {
    $self->{ERROR} = $error;
    return 1;
  }
}

1;