signal_api 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+*.swp
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+log/test.log
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,4 @@
+source :rubygems
+
+gemspec
+

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Signal
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,43 @@
+# SignalApi
+
+A simple library for working with the Signal API (see [http://dev.signalhq.com](http://dev.signalhq.com))
+
+[![Build Status](https://secure.travis-ci.org/signal/signal-ruby.png?branch=master)](http://travis-ci.org/signal/signal-ruby)
+
+## Installation
+------------
+
+### RubyGems ###
+Signal can be installed using RubyGems
+
+    gem install signal_api
+
+Inside your script, be sure to
+
+    require "rubygems"
+    require "signal_api"
+
+### Bundler ###
+If you're using Bundler, add the following to your Gemfile
+
+    gem "signal_api"
+
+and then run
+
+    bundle install
+
+Usage
+------------
+
+Before using any of the APIs, you will need to set your API key:
+
+    SignalApi.api_key = 'foobar123456abcxyz77'
+
+You can find your Signal API key while logged into Signal and looking at your account settings.
+
+You may also specify where Signal should log messages (optional):
+
+    SignalApi.logger = Rails.logger
+    SignalApi.logger = Logger.new(STDERR)
+
+After SignalApi has been configured, you may use any of the API classes to interact with the Signal platform.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'rake/testtask'
+require 'yard'
+
+task :default => :test
+
+namespace :test do
+  Rake::TestTask.new(:api) do |test|
+    test.libs << 'lib' << 'test'
+    test.pattern = ENV['TEST'] || "test/api/**/*_test.rb"
+    test.verbose = true
+  end
+
+  Rake::TestTask.new(:mocks) do |test|
+    test.libs << 'lib' << 'test'
+    test.pattern = ENV['TEST'] || "test/mocks/**/*_test.rb"
+    test.verbose = true
+  end
+end
+
+desc 'Run all of the tests'
+task :test => ["test:api", "test:mocks"]
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+end
+
+desc 'Delete yard, and other generated files'
+task :clobber => [:clobber_yard]
+
+desc 'Delete yard generated files'
+task :clobber_yard do
+  puts 'rm -rf doc .yardoc'
+  FileUtils.rm_rf ['doc', '.yardoc']
+end
+

data/lib/signal_api/carrier.rb

@@ -0,0 +1,43 @@
+module SignalApi
+
+  # Managed carrier from signal api
+  class Carrier < SignalHttpApi
+
+    # The Carrier id from Signal
+    attr_reader :id
+
+    # The Carrier name from Signal
+    attr_reader :name
+
+    def initialize(id, name)
+      @id = id
+      @name = name
+    end
+
+    # Lookup a carrier on textme
+    #
+    # @param [String] mobile_phone The mobile phone to lookup
+    #
+    # @return [carrier] A Carrier object representing the Carrier on the Signal platform
+    def self.lookup(mobile_phone)
+      raise InvalidParameterException.new("mobile_phone cannot be blank") if mobile_phone.blank?
+
+      SignalApi.logger.info "Attempting to lookup carrier for mobile phone #{mobile_phone}"
+
+      with_retries do
+        response = get("/app/carriers/lookup/#{mobile_phone}.xml",
+                       :format => :xml,
+                       :headers => common_headers)
+
+        if response.code == 200 && response.parsed_response['carrier']
+          Carrier.new(response.parsed_response['carrier']['id'], response.parsed_response['carrier']['name'])
+        elsif response.code == 404
+          raise InvalidMobilePhoneException.new("carrier for mobile phone #{mobile_phone} could not be found") 
+        else
+          handle_api_failure(response)
+        end
+      end
+    end
+
+  end
+end

data/lib/signal_api/contact.rb

@@ -0,0 +1,60 @@
+module SignalApi
+
+  # A Contact (person, subscriber, etc) on the Signal platform
+  class Contact
+
+    # The user attributes associated with the contact
+    attr_accessor :attributes
+
+    def initialize(attributes={})
+      @attributes = attributes
+    end
+
+    # Convenience accessor for the contact's mobile phone
+    def mobile_phone
+      @attributes['mobile-phone']
+    end
+
+    # Convenience accessor for the contact's email address
+    def email_address
+      @attributes['email-address']
+    end
+
+    # Update the contact's data on the Signal platform.
+    #
+    # @return true If the contact's data was saved successfully.
+    def save
+      validate_contact_update
+
+      xml = Builder::XmlMarkup.new
+      xml.user_attributes do
+        attributes.each do |key, value|
+          xml.tag!(key, value)
+        end
+      end
+
+      contact_identifier = mobile_phone.blank? ? email_address : mobile_phone
+
+      with_retries do
+        response = put("/api/contacts/#{contact_identifier}.xml",
+                       :body => xml.target!,
+                       :format => :xml,
+                       :headers => common_headers)
+
+        if response.code == 200
+          true
+        else
+          handle_api_failure(response)
+        end
+      end
+    end
+
+    private
+
+    def validate_contact_update
+      raise InvalidParameterException.new("mobile_phone or email is required") if mobile_phone.blank? && email_address.blank?
+      raise InvalidParameterException.new("nothing to update, only identifier provided") if attributes.count < 2
+    end
+
+  end
+end

data/lib/signal_api/core_ext/array.rb

@@ -0,0 +1,7 @@
+class Array
+
+  def blank?
+    empty?
+  end
+
+end

data/lib/signal_api/core_ext/hash.rb

@@ -0,0 +1,7 @@
+class Hash
+
+  def blank?
+    empty?
+  end
+
+end

data/lib/signal_api/core_ext/nil_class.rb

@@ -0,0 +1,7 @@
+class NilClass
+
+  def blank?
+    true
+  end
+  
+end

data/lib/signal_api/core_ext/string.rb

@@ -0,0 +1,7 @@
+class String
+
+  def blank?
+    strip.empty?
+  end
+
+end

data/lib/signal_api/coupon_group.rb

@@ -0,0 +1,47 @@
+module SignalApi
+
+  # manage a copuon group using signals api
+  class CouponGroup < SignalHttpApi
+
+    # Consume a coupon
+    #
+    # @param [String] coupon_group_tag The tag for the coupon group in Textme to consume this coupon from.]
+    # @param [String] mobile_phone The mobile phone to consume this coupon for
+    #
+    # @return a coupon code 
+    def self.consume_coupon(coupon_group_tag, mobile_phone)
+      validate_consume_coupon_parameters(coupon_group_tag, mobile_phone)
+
+      SignalApi.logger.info "Attempting to consume coupon from group #{coupon_group_tag} #{mobile_phone}"
+
+      xml = Builder::XmlMarkup.new
+      xml.request do
+        xml.user do
+          xml.tag!('mobile_phone',mobile_phone)
+        end
+        xml.tag!('coupon_group', coupon_group_tag)
+      end
+
+      with_retries do
+        response = get('/api/coupon_groups/consume_coupon.xml',
+                       :body => xml.target!,
+                       :format => :xml,
+                       :headers => common_headers)
+
+        if response.code == 200
+          response.parsed_response['coupon_code']
+        else
+          handle_api_failure(response)
+        end
+      end
+    end
+
+    private
+
+    def self.validate_consume_coupon_parameters(coupon_group_tag, mobile_phone)
+      raise InvalidParameterException.new("Coupon group tag cannot be blank") if coupon_group_tag.blank?
+      raise InvalidParameterException.new("Mobile_phone cannot be blank") if mobile_phone.blank?
+    end
+
+  end
+end

data/lib/signal_api/deliver_sms.rb

@@ -0,0 +1,54 @@
+module SignalApi
+
+  # Deliver a SMS message using Signal's messaging API
+  class DeliverSms < SignalHttpApi
+
+    base_uri "https://api.imws.us"
+
+    # Create an instance of this class, with your messaging API credentials.
+    # These credentials are separate from the api_key that is used by the
+    # other APIs, and can be found in the API campaign configuration.
+    def initialize(username, password)
+      @username = username
+      @password = password
+
+      if @username.nil? || @password.nil?
+        raise InvalidParameterException.new("username and password must be provided")
+      end
+    end
+
+    # Deliver a SMS message to a mobile phone.  Messages exceeding the 160 character
+    # limit will be split into multiple messages.
+    #
+    # @param [String] mobile_phone The mobile phone to send the message to
+    # @param [String] message The message to send
+    #
+    # @return [String] The unique message ID
+    def deliver(mobile_phone, message)
+      sanitized_mobile_phone = Phone.sanitize(mobile_phone)
+      unless Phone.valid?(sanitized_mobile_phone)
+        raise InvalidParameterException.new("An invalid mobile phone was specified: #{mobile_phone}")
+      end
+
+      if message.nil? || message.strip.empty?
+        raise InvalidParameterException.new("A message must be provided")
+      end
+
+      SignalApi.logger.info "Delivering the following message to #{sanitized_mobile_phone}: #{message}"
+      self.class.with_retries do
+        response = self.class.post('/messages/send',
+                                   :basic_auth => { :username => @username, :password => @password },
+                                   :query => { :mobile_phone => sanitized_mobile_phone, :message => message })
+
+        if response.code == 200
+          response.parsed_response =~ /^Message ID: (.*)$/
+          $1
+        else
+          self.class.handle_api_failure(response)
+        end
+      end
+    end
+  end
+
+end
+

data/lib/signal_api/exceptions.rb

@@ -0,0 +1,19 @@
+module SignalApi
+  # Base class for exceptions that should not be retried
+  class NonRetryableException < StandardError; end
+
+  # Exception raised when a request to the Signal API fails
+  class ApiException < StandardError; end
+
+  # Exception raised when the api key is not properly set
+  class InvalidApiKeyException < StandardError; end
+
+  # Authentication to the Signal platform failed.  Make sure your API key is correct.
+  class AuthFailedException < StandardError; end
+
+  # An invalid parameter was passed to the given method
+  class InvalidParameterException < StandardError; end
+
+  # An invalid mobile phone number was passed
+  class InvalidMobilePhoneException < NonRetryableException; end
+end

data/lib/signal_api/list.rb

@@ -0,0 +1,224 @@
+module SignalApi
+
+  # The type of subscription
+  class SubscriptionType
+    SMS = "SMS"
+    EMAIL = "EMAIL"
+  end
+
+  # Represents a message to be sent to users on a particular carrier
+  class CarrierOverrideMessage
+    attr_accessor :carrier_id, :text
+
+    def initialize(carrier_id, text)
+      @carrier_id = carrier_id
+      @text = text
+    end
+  end
+
+  # Manage subscriptions to, and send messages to subscribers of a List.
+  class List < SignalHttpApi
+
+    # Create a new List object
+    #
+    # @param [Fixnum] list_id The ID of the list in the Signal platform
+    def initialize(list_id)
+      @list_id = list_id
+      raise InvalidParameterException.new("list_id cannot be nil") if @list_id.nil?
+    end
+
+    # Create a new subscription to the list.
+    #
+    # @param [SubscriptionType] subscription_type The type of subscription to create
+    # @param [Contact] contact The contact to create the subscription for.  The contact must contain a valid
+    #                          mobile phone number for SMS subscriptions, and a valid email address for
+    #                          EMAIL subscriptions.  Any other attributes stored with the contact will also
+    #                          be stored on the Signal platform.
+    # @param [Hash] options <b>Optional</b> The options used to create the subscription
+    # @option options [String] :source_keyword The source keyword to use when creating the subscription (for SMS subscriptions)
+    #
+    # @return [Bool] True if a subscription was created, false if the subscription already existed.
+    def create_subscription(subscription_type, contact, options={})
+      validate_create_subscription_request(subscription_type, contact, options)
+
+      builder = Builder::XmlMarkup.new
+      body = builder.subscription do |subscription|
+        subscription.tag!('subscription-type', subscription_type)
+        subscription.tag!('source-keyword', options[:source_keyword]) if options[:source_keyword]
+        subscription.user do |user|
+          contact.attributes.each do |attribute_name, attribute_value|
+            user.__send__(attribute_name, attribute_value)
+          end
+        end
+      end
+
+      SignalApi.logger.info "Attempting to create a subscription to list #{@list_id}"
+      SignalApi.logger.debug "Subscription data: #{body}"
+      self.class.with_retries do
+        response = self.class.post("/api/subscription_campaigns/#{@list_id}/subscriptions.xml",
+                                   :body => body,
+                                   :format => :xml,
+                                   :headers => self.class.common_headers)
+
+        if response.code == 200
+          return true
+        else
+          if response.body.include?("Could not find the carrier for mobile phone")
+            raise SignalApi::InvalidMobilePhoneException.new(response.body)
+          elsif response.body.include?("already signed up")
+            SignalApi.logger.info response.body
+            return false
+          elsif response.body.include?("Subscriber cannot be re-added since they have unsubscribed within the past")
+            SignalApi.logger.info response.body
+            return false
+          elsif response.body.include?("User already subscribed, resending confirmation message")
+            SignalApi.logger.info response.body
+            return false
+          else
+            self.class.handle_api_failure(response)
+          end
+        end
+      end
+    end
+
+    # Destroy a subscription which exists in this list.
+    #
+    # @param [SubscriptionType] subscription_type The type of subscription to destroy
+    # @param [Contact] contact The contact to destroy the subscription for.  The contact must contain a valid
+    #                          mobile phone number for SMS subscriptions, and a valid email address for
+    #                          EMAIL subscriptions.  
+    #
+    # @return [Bool] True if a subscription was desctroyed, false if the subscription did not exist.
+    def destroy_subscription(subscription_type, contact)
+      validate_destroy_subscription_request(subscription_type, contact)
+
+      SignalApi.logger.info "Attempting to destroy a subscription to list #{@list_id}"
+      SignalApi.logger.debug "Contact data: #{contact.inspect}"
+      
+      if subscription_type == SubscriptionType::SMS
+        contact_id = contact.mobile_phone
+      else
+        contact_id = contact.email_address
+      end
+
+      self.class.with_retries do
+        response = self.class.delete("/api/subscription_campaigns/#{@list_id}/subscriptions/#{contact_id}.xml",
+                                     :headers => self.class.common_headers)
+
+        if response.code == 200
+          return true
+        else
+          if response.body.include?("is not subscribed to campaign")
+            SignalApi.logger.info response.body
+            return false
+          elsif response.body.include?("Invalid user ID")
+            SignalApi.logger.info response.body
+            return false
+          else
+            self.class.handle_api_failure(response)
+          end
+        end
+      end
+    end
+
+    # Sends an SMS message to the subscribers of the subscription list.
+    #
+    # @param [String] description A description of the message.
+    # @param [String] text The message to send.  Must not be greater than 160 characters.
+    # @param [Hash] options <b>Optional</b> The options used when sending the message.
+    # @option options [Time] :send_at The date and time to send the message. The message will be
+    #                                 sent immediately if not provided.
+    # @option options [Fixnum] :segment_id The id of the segment to send the message to. If not
+    #                                      specified, the message will be sent to all subscribers in the list.
+    # @option options [Array<Fixnum>] :tags An array of tag ids to tag the scheduled message with.
+    # @option options [Array<CarrierOverrideMessage>] :carrier_overrides An alternate text message to send to
+    #                                      users on a particular carrier.
+    # @return [Fixnum] The ID of the scheduled message on the Signal platform.
+    def send_message(description, text, options={})
+      raise InvalidParameterException.new("A description must be provided") if description.blank?
+      raise InvalidParameterException.new("A text message must be provided") if text.blank?
+      raise InvalidParameterException.new("The text message must not be greater than 160 characters") if text.size > 160
+
+      builder = Builder::XmlMarkup.new
+      body = builder.message do |message|
+        message.description(description)
+        message.text(text)
+        message.send_at(options[:send_at].strftime("%Y-%m-%d %H:%M:%S")) if options[:send_at]
+        message.segment_id(options[:segment_id]) if options[:segment_id]
+
+        if options[:tags]
+          message.tags(:type => :array) do |tags|
+            options[:tags].each { |tag_id| tags.tag(tag_id) }
+          end
+        end
+
+        if options[:carrier_overrides]
+          message.carrier_overrides(:type => :array) do |carrier_overrides|
+            options[:carrier_overrides].each do |carrier_override_message|
+              carrier_overrides.carrier_override do |carrier_override|
+                carrier_override.carrier_id(carrier_override_message.carrier_id)
+                carrier_override.text(carrier_override_message.text)
+              end
+            end
+          end
+        end
+      end
+
+      SignalApi.logger.info "Attempting to send a message to list #{@list_id}"
+      SignalApi.logger.debug "Message data: #{body}"
+      self.class.with_retries do
+        response = self.class.post("/api/subscription_campaigns/#{@list_id}/send_message.xml",
+                                   :body => body,
+                                   :format => :xml,
+                                   :headers => self.class.common_headers)
+
+        if response.code == 200
+          data = response.parsed_response['scheduled_message']
+          data['id']
+        else
+          self.class.handle_api_failure(response)
+        end
+      end
+    end
+
+    private
+
+    def validate_create_subscription_request(subscription_type, contact, options)
+      unless [SubscriptionType::SMS, SubscriptionType::EMAIL].include?(subscription_type)
+        raise InvalidParameterException.new("Invalid subscription type")
+      end
+
+      if contact.nil?
+        raise InvalidParameterException.new("A contact must be provided")
+      end
+
+      if subscription_type == SubscriptionType::SMS && !Phone.valid?(contact.mobile_phone)
+        raise InvalidMobilePhoneException.new("A valid mobile phone number required for SMS subscriptions")
+      end
+
+      if subscription_type == SubscriptionType::EMAIL && !EmailAddress.valid?(contact.email_address)
+        raise InvalidParameterException.new("A valid email address required for EMAIL subscriptions")
+      end
+    end
+
+    def validate_destroy_subscription_request(subscription_type, contact)
+      unless [SubscriptionType::SMS, SubscriptionType::EMAIL].include?(subscription_type)
+        raise InvalidParameterException.new("Invalid subscription type")
+      end
+
+      if contact.nil?
+        raise InvalidParameterException.new("A contact must be provided")
+      end
+
+      if subscription_type == SubscriptionType::SMS && !Phone.valid?(contact.mobile_phone)
+        raise InvalidMobilePhoneException.new("A valid mobile phone number required for SMS subscriptions")
+      end
+
+      if subscription_type == SubscriptionType::EMAIL && !EmailAddress.valid?(contact.email_address)
+        raise InvalidParameterException.new("A valid email address required for EMAIL subscriptions")
+      end
+    end
+
+  end
+end
+