signal_api 0.0.1

data/lib/signal_api/mocks/api_mock.rb

@@ -0,0 +1,70 @@
+module SignalApi
+  module ApiMock
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      @@mock_method_definitions = {}
+      @@mock_method_calls = {}
+
+      def mock_method_calls
+        @@mock_method_calls
+      end
+
+      def mock_method_definitions
+        @@mock_method_definitions
+      end
+
+      def mock_method(method, *parameter_names)
+        @@mock_method_definitions[method] = parameter_names
+        @@mock_method_calls[method] = []
+
+        define_method method do |*args|
+          method_args = self.class.mock_method_definitions[method]
+
+          called_args = {}
+          method_args.each_with_index do |method_arg, i|
+            called_args[method_arg] = args[i]
+          end
+
+          additional_info_method = method.to_s + "_additional_info"
+          if self.class.method_defined?(additional_info_method)
+            called_args.merge!(send(additional_info_method))
+          end
+
+          self.class.mock_method_calls[method] << called_args
+        end
+      end
+
+      def mock_class_method(method, *parameter_names)
+        @@mock_method_definitions[method] = parameter_names
+        @@mock_method_calls[method] = []
+
+        (class << self; self; end).instance_eval do
+          define_method method do |*args|
+            method_args = mock_method_definitions[method]
+
+            called_args = {}
+            method_args.each_with_index do |method_arg, i|
+              called_args[method_arg] = args[i]
+            end
+
+            additional_info_method = method.to_s + "_additional_info"
+            if method_defined?(additional_info_method)
+              called_args.merge!(send(additional_info_method))
+            end
+
+            mock_method_calls[method] << called_args
+          end
+        end
+      end
+
+      def clear_mock_data
+        @@mock_method_calls.keys.each { |k| @@mock_method_calls[k] = [] }
+      end
+    end
+
+  end
+end

data/lib/signal_api/mocks/contact.rb

@@ -0,0 +1,13 @@
+require 'signal_api/mocks/api_mock'
+
+module SignalApi
+  class Contact
+    include ApiMock
+
+    mock_method(:save)
+
+    def save_additional_info
+      { :attributes => @attributes }
+    end
+  end
+end

data/lib/signal_api/mocks/deliver_sms.rb

@@ -0,0 +1,14 @@
+require 'signal_api/mocks/api_mock'
+
+module SignalApi
+  class DeliverSms
+    include ApiMock
+
+    mock_method(:deliver, :mobile_phone, :message)
+
+    def deliver_additional_info
+      { :user_name => @username }
+    end
+
+  end
+end

data/lib/signal_api/mocks/list.rb

@@ -0,0 +1,19 @@
+require 'signal_api/mocks/api_mock'
+
+module SignalApi
+  class List
+    include ApiMock
+
+    mock_method(:create_subscription, :subscription_type, :contact, :options)
+
+    def create_subscription_additional_info
+      { :list_id => @list_id }
+    end
+
+    mock_method(:destroy_subscription, :subscription_type, :contact)
+
+    def destroy_subscription_additional_info
+      { :list_id => @list_id }
+    end
+  end
+end

data/lib/signal_api/mocks/short_url.rb

@@ -0,0 +1,9 @@
+require 'signal_api/mocks/api_mock'
+
+module SignalApi
+  class ShortUrl
+    include ApiMock
+
+    mock_class_method(:create, :target, :domain)
+  end
+end

data/lib/signal_api/segment.rb

@@ -0,0 +1,161 @@
+module SignalApi
+
+  # The type of segment
+  class SegmentType
+    DYNAMIC = "DYNAMIC"
+    STATIC = "SEGMENT"
+  end
+
+  # Represents a user to be added to a segment
+  class SegmentUser
+    attr_reader :mobile_phone, :email_address, :user_data
+
+    # Create a new segment on the Signal platform.
+    #
+    # @param [String] identifying_attribute The mobile phone or email address of the user
+    # @param [Hash] user_data <b>Optional</b> A collection of key/value pairs to store along
+    #                         with this user's segment record for later use
+    def initialize(identifying_attribute, user_data={})
+      if Phone.valid?(identifying_attribute)
+        @mobile_phone = identifying_attribute
+      elsif EmailAddress.valid?(identifying_attribute)
+        @email_address = identifying_attribute
+      else
+        raise InvalidParameterException.new("identifying_attribute must be a valid mobile phone number or email address")
+      end
+
+      @user_data = user_data unless user_data.empty?
+    end
+  end
+
+  # Create, manage, and add users to a segment.
+  class Segment < SignalHttpApi
+
+    # The name of the segment
+    attr_reader :name
+
+    # The description of the segment
+    attr_reader :description
+
+    # The ID of the segment
+    attr_reader :id
+
+    # The account_id of the segment
+    attr_reader :account_id
+
+    # Type type of the segment
+    attr_reader :segment_type
+
+
+    def initialize(id, name=nil, description=nil, segment_type=nil, account_id=nil)
+      @name = name
+      @description = description
+      @id = id
+      @account_id = account_id
+
+      if segment_type == "DYNAMIC"
+        @segment_type = SegmentType::DYNAMIC
+      elsif segment_type == "SEGMENT"
+        @segment_type = SegmentType::STATIC
+      end
+    end
+
+    # Create a new segment on the Signal platform.
+    #
+    # @param [String] name The name of the segment
+    # @param [String] description A description of the segment
+    # @param [SegmentType] segment_type The type of the segment
+    #
+    # @return [Segment] A Segment object representing the segment on the Signal platform
+    def self.create(name, description, segment_type)
+      if name.blank? || description.blank? || segment_type.blank?
+        raise InvalidParameterException.new("name, description, and segment_type are all required")
+      end
+
+      unless [SegmentType::DYNAMIC, SegmentType::STATIC].include?(segment_type)
+        raise InvalidParameterException.new("Invalid segment type")
+      end
+
+      builder = Builder::XmlMarkup.new
+      body = builder.filter_group do |filter_group|
+        filter_group.description(description)
+        filter_group.name(name)
+        filter_group.filter_group_type(segment_type)
+      end
+
+      SignalApi.logger.info "Attempting to create a segment: name => #{name}, description => \"#{description}\", type = #{segment_type}}"
+      SignalApi.logger.debug "Segment data: #{body}"
+      with_retries do
+        response = post("/api/filter_groups/create.xml",
+                        :body => body,
+                        :format => :xml,
+                        :headers => common_headers)
+
+        if response.code == 200
+          data = response.parsed_response['subscription_list_filter_group']
+          new(data['id'], data['name'], data['description'], lookup_segment_type(data['filter_group_type_id']), data['account_id'])
+        else
+          handle_api_failure(response)
+        end
+      end
+    end
+
+    # Add mobile phone numbers to a segment.
+    #
+    # @param [Array<SegmentUser>] segment_users An array of SegmentUsers to add to the segment
+    # @return [Hash] A hash containing some stats regarding the operation
+    def add_users(segment_users)
+      if segment_users.blank?
+        raise InvalidParameterException.new("An array of SegmentUser objects must be provided")
+      end
+
+      builder = Builder::XmlMarkup.new
+      body = builder.users(:type => :array) do |users|
+        segment_users.each do |segment_user|
+          users.user do |user|
+            user.mobile_phone(segment_user.mobile_phone) if segment_user.mobile_phone
+            user.email(segment_user.email_address) if segment_user.email_address
+            user.user_data(segment_user.user_data) if segment_user.user_data
+          end
+        end
+      end
+
+      SignalApi.logger.info "Attempting to add users to segment #{@id}"
+      self.class.with_retries do
+        response = self.class.post("/api/filter_segments/#{@id}/update.xml",
+                                   :body => body,
+                                   :format => :xml,
+                                   :headers => self.class.common_headers)
+
+        if response.code == 200
+          data = response.parsed_response['subscription_list_segment_results']
+
+          if data['users_not_found'] && data['users_not_found']['user_not_found']
+            if data['users_not_found']['user_not_found'].respond_to?(:join)
+              SignalApi.logger.warn data['users_not_found']['user_not_found'].join(", ")
+            else
+              SignalApi.logger.warn data['users_not_found']['user_not_found']
+            end
+          end
+
+          { :total_users_processed => (data['total_users_processed'] || 0).to_i,
+            :total_users_added     => (data['total_users_added'] || 0).to_i,
+            :total_users_not_found => (data['total_users_not_found'] || 0).to_i,
+            :total_duplicate_users => (data['total_duplicate_users'] || 0).to_i }
+        else
+          self.class.handle_api_failure(response)
+        end
+      end
+    end
+
+    private
+
+    def self.lookup_segment_type(segment_type_id)
+      case segment_type_id
+      when 1 then SegmentType::DYNAMIC
+      when 2 then SegmentType::STATIC
+      end
+    end
+
+  end
+end

data/lib/signal_api/short_url.rb

@@ -0,0 +1,56 @@
+module SignalApi
+
+  # Manage short URLs via Signal's URL shortening service
+  class ShortUrl < SignalHttpApi
+
+    # The shortened URL
+    attr_reader :short_url
+
+    # The target URL that was shortened
+    attr_reader :target_url
+
+    # The ID of the shortend URL on the Signal platform
+    attr_reader :id
+
+    # The domain of the short URL
+    attr_reader :domain
+
+    def initialize(id, target_url, short_url, domain)
+      @id = id
+      @target_url = target_url
+      @short_url = short_url
+      @domain = domain
+    end
+
+    # Create a short URL for the provided target URL
+    #
+    # @param [String] target The target URL that is to be shortened
+    # @param [String] domain The short URL domain to use
+    #
+    # @return [ShortUrl] A ShortUrl object representing the short URL on the Signal platform
+    def self.create(target, domain)
+      body = <<-END
+<short_url>
+  <target_url><![CDATA[#{target}]]></target_url>
+  <domain_id>1</domain_id>
+</short_url>
+      END
+
+      SignalApi.logger.info "Attempting to create a short URL for #{target}"
+      with_retries do
+        response = post('/api/short_urls.xml',
+                        :body => body,
+                        :format => :xml,
+                        :headers => common_headers)
+
+        if response.code == 201
+          data = response.parsed_response['short_url']
+          new(data['id'], data['target_url'], "http://#{domain}/#{data['slug']}", domain)
+        else
+          handle_api_failure(response)
+        end
+      end
+    end
+  end
+
+end

data/lib/signal_api/signal_http_api.rb

@@ -0,0 +1,49 @@
+module SignalApi
+  class SignalHttpApi
+    include HTTParty
+    base_uri SignalApi.base_uri
+    default_timeout SignalApi.timeout
+
+    protected
+
+    def self.with_retries
+      if SignalApi.retries <= 0
+        yield
+      else
+        retry_counter = 0
+        begin
+          yield
+        rescue NonRetryableException => e
+          SignalApi.logger.error "Non retryable exception: #{e.message}"
+          raise
+        rescue Exception => e
+          SignalApi.logger.error "Exception: #{e.message}"
+          sleep 1
+          retry_counter += 1
+
+          if retry_counter < SignalApi.retries
+            SignalApi.logger.warn "Re-trying..."
+            retry
+          else
+            SignalApi.logger.error "All retry attempts have failed."
+            raise
+          end
+        end
+      end
+    end
+
+    def self.handle_api_failure(response)
+      if response.code == 401
+        raise AuthFailedException.new("Authentication to the Signal platform failed.  Make sure your API key is correct.")
+      else
+        message = "API request failed with a response code of #{response.code}.  Respone body: #{response.body}"
+        SignalApi.logger.error message
+        raise ApiException.new(message)
+      end
+    end
+
+    def self.common_headers
+      { 'Content-Type' => 'application/xml', 'api_token' => SignalApi.api_key }
+    end
+  end
+end

data/lib/signal_api/util/email_address.rb

@@ -0,0 +1,10 @@
+module SignalApi
+  class EmailAddress
+
+    # Check to see if an email address is valid
+    def self.valid?(email)
+      email && !email.strip.empty? && email.strip =~ /^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i
+    end
+
+  end
+end

data/lib/signal_api/util/phone.rb

@@ -0,0 +1,37 @@
+module SignalApi
+  class Phone
+
+    # Clean up phone number by removing special characters and country codes (if provided)
+    def self.sanitize(phone_number)
+      return nil if phone_number.nil?
+
+      # Remove all non-numeric characters, ex - "=", "+", "(", ")", ".", "a", "A", " "
+      sanitized_phone_number = phone_number.gsub(/[^\d]/, '')
+
+      # Remove the US/Canadian country code (+1) if was provided
+      if sanitized_phone_number.length > 10 && sanitized_phone_number[0,1] == "1"
+        sanitized_phone_number = sanitized_phone_number[1, sanitized_phone_number.size]
+      end
+
+      sanitized_phone_number
+    end
+
+    def self.valid?(phone_number)
+      return false if phone_number.nil? || phone_number.strip.empty?
+      return false if self.sanitize(phone_number).size != 10
+      return true
+    end
+
+    def self.format(phone_number, international=false)
+      if Phone.valid?(phone_number)
+        phone_number = Phone.sanitize(phone_number)
+        unless international
+          "#{phone_number[0..2]}-#{phone_number[3..5]}-#{phone_number[6..9]}" # 312-343-1326
+        else
+          phone_number
+        end
+      end
+    end
+
+  end
+end

data/lib/signal_api/version.rb

@@ -0,0 +1,3 @@
+module SignalApi
+  VERSION = "0.0.1"
+end

data/lib/signal_api.rb

@@ -0,0 +1,114 @@
+require "httparty"
+require "builder"
+require "logger"
+
+module SignalApi
+
+  # Interact with the Signal platform via its published web API.
+  class << self
+
+    # Set your Signal API key.
+    #
+    # @param [String] api_key Your Signal API key
+    #
+    # @example
+    #   SignalApi.api_key = 'foobar123456abcxyz77'
+    def api_key=(api_key)
+      @api_key = api_key
+    end
+
+    # Get your Signal API key.
+    def api_key
+      if @api_key.nil? || @api_key.strip == ""
+        raise InvalidApiKeyException.new("The api_key is blank or nil.  Use SignalApi.api_key= to set it.")
+      else
+        @api_key
+      end
+    end
+
+    # Set the logger to be used by Signal.
+    #
+    # @param [Logger] logger The logger you would like Signal to use
+    #
+    # @example
+    #   SignalApi.logger = Rails.logger
+    #   SignalApi.logger = Logger.new(STDERR)
+    def logger=(logger)
+      @logger = logger
+    end
+
+    # Get the logger used by Signal.
+    def logger
+      @logger ||= Logger.new("/dev/null")
+    end
+
+    # Set the number of times failed API calls should be retried.  Defaults to 0.
+    #
+    # @param [Fixnum] retries The number of times API calls should be retried
+    #
+    # @example
+    #   SignalApi.retries = 3
+    def retries=(retries)
+      @retries = retries
+    end
+
+    # Get the number of times failed API calls should be retried.
+    def retries
+      @retries || 0
+    end
+
+    # Set the default timeout for API calls.  Defaults to 15 seconds.
+    #
+    # @param [Fixnum] timeout The default timeout (in seconds) for API calls
+    #
+    # @example
+    #   SignalApi.timeout = 5
+    def timeout=(timeout)
+      @timeout = timeout
+      api_classes.each { |clazz| clazz.default_timeout @timeout }
+    end
+
+    # Get the default timeout for API calls.
+    def timeout
+      @timeout || 15
+    end
+
+    # @private
+    def base_uri=(base_uri)
+      @base_uri = base_uri
+      api_classes.each { |clazz| clazz.base_uri @base_uri }
+    end
+
+    # @private
+    def base_uri
+      @base_uri || "https://app.signalhq.com"
+    end
+
+    private
+
+    def api_classes
+      [ List, Segment, ShortUrl ]
+    end
+  end
+
+end
+
+require "signal_api/core_ext/nil_class"
+require "signal_api/core_ext/string"
+require "signal_api/core_ext/array"
+require "signal_api/core_ext/hash"
+
+require "signal_api/util/phone"
+require "signal_api/util/email_address"
+
+require "signal_api/contact"
+require "signal_api/exceptions"
+require "signal_api/signal_http_api"
+
+require "signal_api/deliver_sms"
+require "signal_api/list"
+require "signal_api/segment"
+require "signal_api/short_url"
+require "signal_api/coupon_group"
+require "signal_api/carrier"
+

data/signal_api.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/signal_api/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["John Wood"]
+  gem.email         = ["john@signalhq.com"]
+  gem.description   = %q{Ruby implementation of the Signal API}
+  gem.summary       = %q{Ruby implementation of the Signal API}
+  gem.homepage      = "http://dev.signalhq.com"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "signal_api"
+  gem.require_paths = ["lib"]
+  gem.version       = SignalApi::VERSION
+
+  gem.add_dependency('httparty', '~> 0.8.1')
+  gem.add_dependency('builder', '~> 3.0.0')
+
+  gem.add_development_dependency('fakeweb', '~> 1.3.0')
+  gem.add_development_dependency('shoulda', '~> 3.0.1')
+  gem.add_development_dependency('rake', '~> 0.9.2.2')
+  gem.add_development_dependency('yard', '~> 0.7.5')
+  gem.add_development_dependency('bluecloth', '~> 2.2.0')
+  gem.add_development_dependency('mocha', '~> 0.10.5')
+end

data/test/api/carrier_test.rb

@@ -0,0 +1,43 @@
+require 'test_helper'
+
+class CarrierTest < Test::Unit::TestCase
+
+  def setup
+    SignalApi.api_key = 'foobar'
+    FakeWeb.allow_net_connect = false
+  end
+
+  def teardown
+    FakeWeb.clean_registry
+    FakeWeb.allow_net_connect = true
+  end
+
+  should "be able to lookup a valid carrier" do
+    body = <<-END
+<?xml version="1.0" encoding="UTF-8"?>
+<carrier>
+  <name>AT&amp;T</name>
+  <id type="integer">6</id>
+</carrier>
+END
+
+    FakeWeb.register_uri(:get, SignalApi.base_uri + '/app/carriers/lookup/3125551212.xml', :content_type => 'application/xml', :status => ['200', 'Ok'], :body => body)
+    carrier = SignalApi::Carrier.lookup('3125551212')
+    assert_equal 6, carrier.id
+    assert_equal "AT&T", carrier.name
+  end
+
+  should "should throw exceptions for missing params" do
+    assert_raise SignalApi::InvalidParameterException do 
+      SignalApi::Carrier.lookup(nil)
+    end
+  end
+
+  should "show throw and exception for mobile not found" do
+    FakeWeb.register_uri(:get, SignalApi.base_uri + '/app/carriers/lookup/3125551212.xml', :content_type => 'application/xml', :status => '404')
+    assert_raise SignalApi::InvalidMobilePhoneException do 
+      SignalApi::Carrier.lookup('3125551212')
+    end
+  end
+
+end