SMS-Send-NANP-Twilio

 view release on metacpan or  search on metacpan

Changes

Revision history for Perl extension SMS::Send::NANP::Twilio

0.04 2018-03-02
  - Added DateTime as build time requirement - RT 124633 (ANDK@cpan.org)
    - Updated Makefile.PL
    - Updated perl-SMS-Send-NANP-Twilio.spec

0.03 2018-02-03
  - API BREAK
    - Changed sid property to API documented name MessagingServiceSid
    - Changed from property to API documented case From
  - Updated sms_send method
    - Added support for MediaUrl property
  - Added support for all optional properties in API documentation

0.02 2018-02-03
  - Status return is different when using copilot

0.01 2018-02-03
  - original version

MANIFEST

Changes
Makefile.PL
MANIFEST
README
t/001_load.t
t/002_send.t
t/003_send_MediaUrl.t
t/004_send_api.t
lib/SMS/Send/NANP/Twilio.pm
perl-SMS-Send-NANP-Twilio.spec
META.yml                                 Module meta-data (added by MakeMaker)

META.yml

--- #YAML:1.0
name:               SMS-Send-NANP-Twilio
version:            0.04
abstract:           SMS::Send driver for Twilio
author:
    - Michael Davis <mdavis@localdomain>
license:            unknown
distribution_type:  module
configure_requires:
    ExtUtils::MakeMaker:  0
build_requires:
    ExtUtils::MakeMaker:  0
requires:
    DateTime:             0
    JSON::XS:             0
    SMS::Send::Driver::WebService:  0.06
    URI:                  0
no_index:
    directory:
        - t
        - inc
generated_by:       ExtUtils::MakeMaker version 6.55_02
meta-spec:
    url:      http://module-build.sourceforge.net/META-spec-v1.4.html
    version:  1.4

Makefile.PL

use ExtUtils::MakeMaker;
WriteMakefile(
    NAME           => 'SMS::Send::NANP::Twilio',
    VERSION_FROM   => 'lib/SMS/Send/NANP/Twilio.pm',
    PREREQ_PM      => {
                        'URI'                           => 0,
                        'JSON::XS'                      => 0,
                        'DateTime'                      => 0, #tests
                        'SMS::Send::Driver::WebService' => 0.06,
                      },
    ABSTRACT_FROM  => 'lib/SMS/Send/NANP/Twilio.pm',
    AUTHOR         => 'Michael Davis <mdavis@localdomain>',
);

README

SMS-Send-Twilio-Config version 0.01
===================================

The README is used to introduce the module and provide instructions on
how to install the module, any machine dependencies it may have (for
example C compilers and installed libraries) and any other information
that should be provided before the module is installed.

A README file is required for CPAN modules since CPAN extracts the
README file from a module distribution so that people browsing the
archive can use it get an idea of the modules uses. It is usually a
good idea to provide version information here so that people can
decide whether fixes for the module are worth downloading.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires these other modules and libraries:

  blah blah blah

COPYRIGHT AND LICENCE

Put the correct copyright and licence information here.

Copyright (C) 2018 by Michael Davis

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.


lib/SMS/Send/NANP/Twilio.pm

package SMS::Send::NANP::Twilio;
use strict;
use warnings;
use URI;
use JSON::XS qw{decode_json};
use base qw{SMS::Send::Driver::WebService};

our $VERSION = '0.04';

=head1 NAME

SMS::Send::NANP::Twilio - SMS::Send driver for Twilio

=head1 SYNOPSIS

  Configure /etc/SMS-Send.ini

  [NANP::Twilio]
  username=accountSid
  password=authToken
  MessagingServiceSid=String
  ;From=+12025551212
  ;StatusCallback=URL
  ;ApplicationSid=String
  ;MaxPrice=USD
  ;ProvideFeedback=true|false
  ;ValidityPeriod=14400

  use SMS::Send;
  my $sms     = SMS::Send->new('NANP::Twilio');
  my $success = $sms->send_sms(text=> 'Hello World!', to =>'+17035551212');

  use SMS::Send::NANP::Twilio;
  my $sms     = SMS::Send::NANP::Twilio->new;
  my $success = $sms->send_sms(text=> 'Hello World!', to =>'+17035551212');
  my $json    = $sms->{__content};
  my $href    = $sms->{__data};

=head1 DESCRIPTION

SMS::Send driver for Twilio

=head1 METHODS

=head2 send_sms

Sends SMS Message via Twilio web service and returns 1 or 0. Method dies on critical error.

  my $status = $sms->send_sms(to =>'+17035551212', text=> 'Hello World!');
  my $status = $sms->send_sms(to =>'+17035551212', text=> 'Image Attached', MediaUrl=>'https://...');

=over

=item to

Passed as "To" in the posted form data. The destination phone number for SMS/MMS or a Channel user address for other 3rd party channels. Destination phone numbers should be formatted with a '+' and country code e.g., +16175551212 (E.164 format).

  to => "+17035551212"

=item text

Passed as "Body" in the posted form data. The text of the message you want to send, limited to 1600 characters.

  text => "My Message Body"

=item MediaUrl

The URL of the media you wish to send out with the message. gif, png, and jpeg content is currently supported and will be formatted correctly on the recipient's device. Other types are also accepted by the API. The media size limit is 5MB. If you wis...

  MediaUrl => "https://...."
  MediaUrl => [$url1, $url2, ...]

=back

=cut

sub send_sms {
  my $self                = shift;
  my %argv                = @_;

  my $to                  = $argv{'to'} or die('Error: to propoerty required');
  my $text                = defined($argv{'text'}) ? $argv{'text'} : '';
  my @form                = (To => $to, Body => $text);

  my $MediaUrl            = $argv{'MediaUrl'} || [];
  $MediaUrl               = [$MediaUrl] unless ref($MediaUrl) eq 'ARRAY';
  die("Error: MediaUrl - You may include up to 10 MediaUrls per message.") if @$MediaUrl > 10;
  push @form, MediaUrl => $_ foreach @$MediaUrl;

  my $status_response;
  if ($self->From) {
    push @form, From                => $self->From;
    $status_response = 'queued'; #When you only specify the From parameter, Twilio will validate the phone
                                 #numbers synchronously and return either a queued status or an error.
  }
  if ($self->MessagingServiceSid) {
    push @form, MessagingServiceSid => $self->MessagingServiceSid;
    $status_response = 'accepted'; #When specifying the MessagingServiceSid parameter, Twilio will first
                                   #return an accepted status.
  }
  die('Error: Property "From" or "MessagingServiceSid" must be configured.') unless $status_response;

  push @form, StatusCallback  => $self->StatusCallback  if $self->StatusCallback;
  push @form, ApplicationSid  => $self->ApplicationSid  if $self->ApplicationSid;
  push @form, MaxPrice        => $self->MaxPrice        if $self->MaxPrice;
  push @form, ProvideFeedback => $self->ProvideFeedback if $self->ProvideFeedback;
  push @form, ValidityPeriod  => $self->ValidityPeriod  if $self->ValidityPeriod;

  my $response            = $self->uat->post_form($self->_url, \@form); #isa HASH from HTTP::Tiny
  die(sprintf("HTTP Error: %s %s", $response->{'status'}, $response->{'reason'})) unless $response->{'success'};
  $self->{'__content'}    = $response->{'content'};
  my $data                = decode_json($response->{'content'});
  $self->{'__data'}       = $data;
  return $data->{'status'} eq $status_response ? 1 : 0;
}

sub _url {
  my $self = shift;
  my $url  = URI->new(join '/', 'https://api.twilio.com/2010-04-01/Accounts', $self->username, 'Messages.json');
  $url->userinfo(join ':', $self->username, $self->password);
  return $url;
}

=head1 PROPERTIES

Properties may be stored in Current Directory, /etc/SMS-Send.ini or C:\Windows\SMS-Send.ini. See L<SMS::Send::Driver::WebService>->cfg_path

=head2 username

The "Account SID" is passed on the URL and sent as the username for basic authentication credentials

=cut

#see SMS::Send::Driver::WebService->username

=head2 password

The "Auth Token" sent as password for basic authentication credentials

=cut

#see SMS::Send::Driver::WebService->password

=head2 From

The "From" parameter passed in the posted form

A Twilio phone number (in E.164 format), alphanumeric sender ID or a Channel Endpoint address enabled for the type of message you wish to send. Phone numbers or short codes purchased from Twilio work here. You cannot (for example) spoof messages from...

=cut

sub From {
  my $self=shift;
  $self->{'From'}=shift if @_;
  $self->{'From'}=$self->cfg_property('From', $self->_From_default) unless defined $self->{'From'};
  return $self->{'From'};
}

sub _From_default {undef};

=head2 MessagingServiceSid

The "MessagingServiceSid" parameter passed in the posted form

The 34 character unique id of the Messaging Service you want to associate with this Message. Set this parameter to use the Messaging Service Settings and Copilot Features you have configured. When only this parameter is set, Twilio will use your enab...

=cut

sub MessagingServiceSid {
  my $self=shift;
  $self->{'MessagingServiceSid'}=shift if @_;
  $self->{'MessagingServiceSid'}=$self->cfg_property('MessagingServiceSid', $self->_MessagingServiceSid_default) unless defined $self->{'MessagingServiceSid'};
  return $self->{'MessagingServiceSid'};
}

sub _MessagingServiceSid_default {undef};

=head2 StatusCallback

The "StatusCallback" parameter passed in the posted form

A URL where Twilio will POST each time your message status changes to one of the following: queued, failed, sent, delivered, or undelivered. Twilio will POST the MessageSid along with the other standard request parameters as well as MessageStatus and...

=cut

sub StatusCallback {
  my $self=shift;
  $self->{'StatusCallback'}=shift if @_;
  $self->{'StatusCallback'}=$self->cfg_property('StatusCallback', $self->_StatusCallback_default) unless defined $self->{'StatusCallback'};
  return $self->{'StatusCallback'};
}

sub _StatusCallback_default {undef};

=head2 ApplicationSid

The "ApplicationSid" parameter passed in the posted form

Twilio will POST MessageSid as well as MessageStatus=sent or MessageStatus=failed to the URL in the MessageStatusCallback property of this Application. If the StatusCallback parameter above is also passed, the Application's MessageStatusCallback para...

=cut

sub ApplicationSid {
  my $self=shift;
  $self->{'ApplicationSid'}=shift if @_;
  $self->{'ApplicationSid'}=$self->cfg_property('ApplicationSid', $self->_ApplicationSid_default) unless defined $self->{'ApplicationSid'};
  return $self->{'ApplicationSid'};
}

sub _ApplicationSid_default {undef};

=head2 MaxPrice

The "MaxPrice" parameter passed in the posted form

The total maximum price up to the fourth decimal (0.0001) in US dollars acceptable for the message to be delivered. All messages regardless of the price point will be queued for delivery. A POST request will later be made to your Status Callback URL ...

=cut

sub MaxPrice {
  my $self=shift;
  $self->{'MaxPrice'}=shift if @_;
  $self->{'MaxPrice'}=$self->cfg_property('MaxPrice', $self->_MaxPrice_default) unless defined $self->{'MaxPrice'};
  return $self->{'MaxPrice'};
}

sub _MaxPrice_default {undef};

=head2 ProvideFeedback

The "ProvideFeedback" parameter passed in the posted form

Set this value to true if you are sending messages that have a trackable user action and you intend to confirm delivery of the message using the Message Feedback API. This parameter is set to false by default.

=cut

sub ProvideFeedback {
  my $self=shift;
  $self->{'ProvideFeedback'}=shift if @_;
  $self->{'ProvideFeedback'}=$self->cfg_property('ProvideFeedback', $self->_ProvideFeedback_default) unless defined $self->{'ProvideFeedback'};
  return $self->{'ProvideFeedback'};
}

sub _ProvideFeedback_default {undef};

=head2 ValidityPeriod

The "ValidityPeriod" parameter passed in the posted form

The number of seconds that the message can remain in a Twilio queue. After exceeding this time limit, the message will fail and a POST request will later be made to your Status Callback URL. Valid values are between 1 and 14400 seconds (the default)....

=cut

sub ValidityPeriod {
  my $self=shift;
  $self->{'ValidityPeriod'}=shift if @_;
  $self->{'ValidityPeriod'}=$self->cfg_property('ValidityPeriod', $self->_ValidityPeriod_default) unless defined $self->{'ValidityPeriod'};
  return $self->{'ValidityPeriod'};
}

sub _ValidityPeriod_default {undef};

=head1 SEE ALSO

L<SMS::Send::Driver::WebService>, L<SMS::Send>, L<https://www.twilio.com/docs/api/messaging/send-messages>

=head1 AUTHOR

Michael R. Davis

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2018 by Michael R. Davis

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

=cut

1;

perl-SMS-Send-NANP-Twilio.spec

Name:           perl-SMS-Send-NANP-Twilio
Version:        0.04
Release:        1%{?dist}
Summary:        SMS::Send driver for Twilio
License:        perl
Group:          Development/Libraries
URL:            http://search.cpan.org/dist/SMS-Send-NANP-Twilio/
Source0:        http://www.cpan.org/modules/by-module/SMS/SMS-Send-NANP-Twilio-%{version}.tar.gz
BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
BuildArch:      noarch
BuildRequires:  perl(ExtUtils::MakeMaker)
BuildRequires:  perl(DateTime)
BuildRequires:  perl(JSON::XS)
BuildRequires:  perl(SMS::Send)
BuildRequires:  perl(SMS::Send::Driver::WebService) >= 0.06
BuildRequires:  perl(URI)
Requires:       perl(JSON::XS)
Requires:       perl(SMS::Send::Driver::WebService) >= 0.06
Requires:       perl(URI)
Requires:       perl(:MODULE_COMPAT_%(eval "`%{__perl} -V:version`"; echo $version))

%description
SMS::Send driver for Twilio

%prep
%setup -q -n SMS-Send-NANP-Twilio-%{version}

%build
%{__perl} Makefile.PL INSTALLDIRS=vendor
make %{?_smp_mflags}

%install
rm -rf $RPM_BUILD_ROOT

make pure_install PERL_INSTALL_ROOT=$RPM_BUILD_ROOT

find $RPM_BUILD_ROOT -type f -name .packlist -exec rm -f {} \;
find $RPM_BUILD_ROOT -depth -type d -exec rmdir {} 2>/dev/null \;

%{_fixperms} $RPM_BUILD_ROOT/*

%check
make test

%clean
rm -rf $RPM_BUILD_ROOT

%files
%defattr(-,root,root,-)
%doc Changes README
%{perl_vendorlib}/*
%{_mandir}/man3/*

%changelog
* Sat Feb 03 2018 Michael R. Davis <mdavis@stopllc.com> 0.01-1
- Specfile autogenerated by cpanspec 1.78.

t/001_load.t

use strict;
use warnings;
use Test::More tests => 17;
BEGIN { use_ok('SMS::Send::NANP::Twilio') };

my $ws = SMS::Send::NANP::Twilio->new(username=>'myusername', password=>'mypassword', From=>'myFrom', MessagingServiceSid=>'');

isa_ok($ws, 'SMS::Send::NANP::Twilio');
can_ok($ws, 'username');
can_ok($ws, 'password');
can_ok($ws, 'url');
can_ok($ws, 'From');
can_ok($ws, 'MessagingServiceSid');
can_ok($ws, 'StatusCallback');
can_ok($ws, 'ApplicationSid');
can_ok($ws, 'MaxPrice');
can_ok($ws, 'ProvideFeedback');
can_ok($ws, 'ValidityPeriod');
isa_ok($ws->uat, 'HTTP::Tiny');

is($ws->username, 'myusername', 'username');
is($ws->password, 'mypassword', 'password');
is($ws->From, 'myFrom', 'From');
ok(!$ws->MessagingServiceSid, 'MessagingServiceSid');

t/002_send.t

# -*- perl -*-
use strict;
use warnings;
use DateTime;
use Data::Dumper qw{Dumper};
use Test::More tests => 4;

BEGIN { use_ok( 'SMS::Send::NANP::Twilio' ); }

my $to   = $ENV{'SMS_TEST_PHONE_NUMBER'};

SKIP: {
  skip 'ENV{SMS_TEST_PHONE_NUMBER} not configured', 3 unless $to;

  my $service = SMS::Send::NANP::Twilio->new;

  isa_ok ($service, 'SMS::Send::NANP::Twilio');
  isa_ok ($service, 'SMS::Send::Driver');

  my $text = sprintf("Message: Test 1, Time: %s", DateTime->now);
  my $status=$service->send_sms(to => $to, text => $text);
  diag(Dumper($service->{"__data"}));
  ok($status, 'status');
}

t/003_send_MediaUrl.t

# -*- perl -*-
use strict;
use warnings;
use DateTime;
use Data::Dumper qw{Dumper};
use Test::More tests => 4;

BEGIN { use_ok( 'SMS::Send::NANP::Twilio' ); }

my $to   = $ENV{'MMS_TEST_PHONE_NUMBER'};

SKIP: {
  skip 'ENV{MMS_TEST_PHONE_NUMBER} not configured', 3 unless $to;

  my $service = SMS::Send::NANP::Twilio->new;

  isa_ok ($service, 'SMS::Send::NANP::Twilio');
  isa_ok ($service, 'SMS::Send::Driver');

  my $text    = sprintf("Title: Map of Clifton, VA, Date: %s", DateTime->now);
  my $url     = 'https://maps.googleapis.com/maps/api/staticmap?size=1024x400&sensor=false&markers=Clifton,VA';
  my $status  = $service->send_sms(to => $to, text => $text, MediaUrl => $url);
  diag(Dumper($service->{"__data"}));
  ok($status, 'status');
}

t/004_send_api.t

# -*- perl -*-
use strict;
use warnings;
use DateTime;
use Data::Dumper qw{Dumper};
use Test::More tests => 4;

BEGIN { use_ok( 'SMS::Send' ); }
BEGIN { use_ok( 'SMS::Send::NANP::Twilio' ); }

my $to   = $ENV{'SMS_TEST_PHONE_NUMBER_API'};

SKIP: {
  skip 'ENV{SMS_TEST_PHONE_NUMBER_API} not configured', 2 unless $to;

  my $service = SMS::Send->new('NANP::Twilio');

  isa_ok ($service, 'SMS::Send');

  my $text = sprintf("Message: Test 2, Time: %s", DateTime->now);
  my $status=$service->send_sms(to => $to, text => $text);
  diag(Dumper($service->{"__data"})); #this is not set
  ok($status, 'status');
}

 view all matches for this distribution
 view release on metacpan -  search on metacpan

( run in 1.165 second using v1.00-cache-1.14-grep-ac7eaf9-cpan-6d591e31851 )