simple_desk 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d55b96c5dfbfdddf6b0820c5007009fb9bc6a78f
-  data.tar.gz: 84d1f3dd5cb416637b9bb1d04c50fd4d2941c900
+  metadata.gz: 09f1cada1f5f25fab3fc15174dba6053f6163470
+  data.tar.gz: 663bfb4bd57a06391d803ffe37ccee1a7287e4cb
 SHA512:
-  metadata.gz: 0bd834ffbd274617379cabed8bc9d17f15063dac68299fbc2f15f9b51f1d4720de2393d67d1168259c666f87fc8331538beb2cf6008cc700474aa05214f7e52d
-  data.tar.gz: 7a9b3a41b9d5441b2b250377fa26456aa6dfa3990759fcb9e78314a1e3b96180156c3cef159ed25bdd37b535a09bb0293545d1c5f29f28e221b5c9b2d7e9b847
+  metadata.gz: f97b3efc33a63428221a2ad789fe1376ca486fc920478ead81ed461125762c3ed427d985c207b8132683377eb40be0056b3f1d81c7b4e992835a892a115a641d
+  data.tar.gz: abc282a27a6c8124cf7a6eec42ada7234928d864201e6a6cb0b92033c50dd8a517030e3080b8cde616eeaccfd21f98949f2784d3f3d3bd83c44f1074079ca087

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Elijah Murray
+Copyright (c) 2014 John Gesimondo and Elijah Murray
 
 MIT License
 

data/README.md

@@ -1,3 +1,5 @@
+[![Build Status](https://travis-ci.org/getsimpledesk/simple_desk_gem.svg)](https://travis-ci.org/getsimpledesk/simple_desk_gem)
+
 # SimpleDesk
 
 [Simple Desk](https://www.getsimpledesk.com) is an SMS customer engagement platform that allows companies to have 2-way conversations with their customers over SMS - whether it's for sales, customer service, funnel abandonment, or transactional messages.
@@ -6,64 +8,102 @@
 
 Add this line to your application's Gemfile:
 
-    gem 'simple_desk'
+```ruby
+gem 'simple_desk'
+```
 
 And then execute:
 
     $ bundle
 
-Or install it yourself as:
+## Compatibility
+Works with Ruby 1.9.1 or greater
+
+## Changes
+See RELEASE.md
+
+* Configuration is now done through an initializer
+* Support for sandbox server
+* When creating a customer, properties is no longer a separate param (see readme)
+
+
+## Setup
+Initialize the gem by creating an initializer.
+
+* Your production token can be found at https://www.getsimpledesk.com/api_info.
+* Your sandbox token can be found at https://sandbox.getsimpledesk.com/api_info
 
-    $ gem install simple_desk
+```ruby
+# config/initializers/simple_desk.rb
+
+SimpleDesk.configure do |config|
+  if Rails.env.production?
+    config.env = :live
+    config.token = ENV['SIMPLEDESK_PRODUCTION_TOKEN'] || 'YOUR_PRODUCTION_TOKEN'
+
+  elsif Rails.env.staging?
+    config.env = :sandbox
+    config.token = ENV['SIMPLEDESK_SANDBOX_TOKEN'] || 'YOUR_PRODUCTION_TOKEN'
+  end
+end
+```
 
-Then add your API token to your `application_root/.env` file, or create one if you don't have it.
 
-		SIMPLE_DESK_TOKEN=MY_TOKEN
 
 ## Usage
 
-###**Adding Customers**
-To get started and add a new customer, run:
-		SimpleDesk.add_customer({phone_number: "1231231232"})
-
-While `phone_number` is required, you can pass additional properties in:
-		- phone_number (required)
-		- email (optional)
-		- first_name (optional)
-		- last_name (optional)
-
-Like this:
-		
-		params = {phone_number: "1231231232", email: "elijah@example.com", first_name: "Elijah", last_name: "Murray"}
-		SimpleDesk.add_customer(params)
-		
-You can also add any amount of additional properties like so (using phone_number as the identifier):
-		
-		properties = {revenue_amount: "$100", location: "San Francisco"}
-		SimpleDesk.add_customer({phone_number: "1231231232"}, properties)
-		
-The gem will turn the properties into a Base64 encoded json object automatically.
-		
-You can use params and properties in the same add_customer call too!
-
-###**Messaging**
-To message a user the format is similar
-Note: They do not have to be existing in the system to message. You'll automatically create a new user if you message a new phone number
-
-		message_and_phone_number = {to: 5551231234, text: "Howdy partner!"}
-		SimpleDesk.message_customer(message_and_phone_number)
-		
-## To Do List
-
-Features that still need to be implemented
-
-		- Add ability to pass in properties and convert to base 64
-		- Add auto capitalization for names
-		- Parse formatting for phone number
-    - Update readme to explain setting up [IFTTT](https://ifttt.com/recipes/1110-send-an-sms-when-a-new-gmail-is-from-a-specific-email-address)
+The API currently allows sending messages and adding customers.
+
+**Sending Messages**
+
+```ruby
+SimpleDesk.message_customer(text: 'message text', to: '1234567890')
+```
+The response is a `SimpleDesk::Message` object with the following accessors:
+
+  * to (phone number as string)
+  * text
+  * status
+
+Status is one of "queued" or "unsubscribed". Messages with "queued" status are usually sent within seconds. Messages with "unsubscribed" status will not be sent, as customer has previously unsubscribed from API messages.
+
+If you send a message to a new phone number the API will automatically create a new user.
+
+#<SimpleDesk::Message to="1234567890", text="content!", status="queued">
+
+**Adding Customers**
+
+If a customer already exists with the given phone number, that customer will be updated.
+
+```ruby
+SimpleDesk.add_customer(
+  phone_number: "5555555555",
+  email: "user@example.com",
+  first_name: "john",
+  last_name: "doe",
+  properties: { great_customer: "true" }
+)
+```
+You can send an unlimited number of properties with arbitrary keys and values.
+
+The response is a `SimpleDesk::Customer` object with the following accessors:
+
+  * id
+  * phone_number (string)
+  * email
+  * first_name
+  * last_name
+  * subscribed (boolean)
+  * properties (hash)
+
+
+## Support
+Email api-help@getsimpledesk.com if you are having issues with the gem or service.
 
 ## Contributing
 
+Please file an issue on Github and have a conversation with us before creating a pull request
+
 1. Fork it ( https://github.com/[my-github-username]/simple_desk/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)

data/RELEASE.md

@@ -1,3 +1,9 @@
+v 1.0.0
+-------
+Configuration is now done through an initializer
+Support for sandbox server
+When creating a customer, properties is no longer a separate param (see readme)
+
 v 0.3.4
 -------
 Added ability to send properties

data/Rakefile

@@ -1,2 +1,7 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/lib/simple_desk/client.rb

@@ -0,0 +1,24 @@
+module SimpleDesk
+  module Client
+    def self.post(url, payload, headers={}, &block)
+      RestClient::Request.execute(method: :post, url: url, payload: payload, headers: headers,
+        open_timeout: 2, timeout: 4, &block)
+
+    rescue Errno::ECONNREFUSED => e
+      raise ConnectionRefused.new(e)
+
+    rescue RestClient::RequestTimeout => e
+      raise RequestTimeout.new(e)
+
+    rescue RestClient::Exception => e
+      if e.http_code == 400
+        raise BadRequest.new(e)
+      else
+        response = e.response && JSON.parse(e.response) || {}
+        error = response["error"]
+        exception = error && Exceptions::EXCEPTIONS_MAP[error].new(e) || Exception::UnknownRequestError.new(e)
+        raise exception
+      end
+    end
+  end
+end

data/lib/simple_desk/configuration.rb

@@ -0,0 +1,32 @@
+require "yaml"
+
+module SimpleDesk
+  class Configuration
+    ENV_URLS = YAML.load_file(File.expand_path('../endpoints.yml', __FILE__))
+    ALLOWED_ENVS = ENV_URLS.keys
+
+    attr_writer :token
+
+    def env
+      @env || :sandbox
+    end
+
+    def token
+      @token || raise(SimpleDesk::ConfigurationError.new('You need to set your token, see SimpleDesk Readme'))
+    end
+
+    def env=(env_sym)
+      if ALLOWED_ENVS.include?(env_sym.to_s)
+        @env = env_sym.to_s
+      else
+        raise SimpleDesk::ConfigurationError.new("You attempted to set Simpledesk env to #{env_sym}. Should be one of #{env_choices}")
+      end
+    end
+
+    private
+
+    def env_choices
+      (ALLOWED_ENVS - ['local']).join(', ')
+    end
+  end
+end

data/lib/simple_desk/endpoints.yml

@@ -0,0 +1,11 @@
+local:
+  messages: http://localhost:3000/api/v1/messages
+  customers: http://localhost:3000/api/v1/customers
+
+sandbox:
+  messages: https://sandbox.getsimpledesk.com/api/v1/messages
+  customers: https://sandbox.getsimpledesk.com/api/v1/customers
+
+live:
+  messages: https://www.getsimpledesk.com/api/v1/messages
+  customers: https://www.getsimpledesk.com/api/v1/customers

data/lib/simple_desk/exceptions.rb

@@ -0,0 +1,52 @@
+require 'ostruct'
+
+module SimpleDesk
+  class Exception < RuntimeError;end
+  class ConfigurationError < Exception; end
+
+  class RequestException < Exception
+    def initialize(original_exception)
+      @original_exception = original_exception
+    end
+
+    def inspect
+      self.class.name
+    end
+
+    def to_s
+      inspect
+    end
+  end
+
+  class BadRequest < RequestException
+    def initialize(original_exception)
+      @original_exception = original_exception
+    end
+
+    def inspect
+      @original_exception.inspect
+    end
+
+    def to_s
+      inspect
+    end
+  end
+
+  class BadToken < RequestException; end
+  class NoActiveSubscription < RequestException; end
+  class ApiDisabledForCompany < RequestException; end
+  class UnknownRequestError < RequestException; end
+  class RequestTimeout < RequestException; end
+  class ConnectionRefused < RequestException; end
+
+  class Customer < OpenStruct; end
+  class Message < OpenStruct; end
+
+  module Exceptions
+    EXCEPTIONS_MAP = {
+      "Bad Token" => BadToken,
+      "No Active Subscription" => NoActiveSubscription,
+      "Api Disabled For Company" => ApiDisabledForCompany
+    }
+  end
+end

data/lib/simple_desk/version.rb

@@ -1,3 +1,3 @@
 module SimpleDesk
-  VERSION = "0.4.0"
+  VERSION = "1.0.0"
 end

data/lib/simple_desk.rb

@@ -1,64 +1,38 @@
 require "simple_desk/version"
-require "net/http"
-require "uri"
+require "simple_desk/configuration"
+require "simple_desk/exceptions"
+require "simple_desk/client"
+require "rest_client"
+require "ostruct"
+require "json"
 
 module SimpleDesk
-	BASE_URL = "https://www.getsimpledesk.com"
+  extend self
 
-	def self.add_customer(params, customer_properties)
-    unless customer_properties.blank?
-      props = Base64.urlsafe_encode64(customer_properties.to_json)
-      params.merge(properties: props)
-    end
-  	url = URI.parse(post_url("add_customer"))
-  	req = Net::HTTP::Post.new(url.request_uri)
-  	req.set_form_data(params)
-  	http = Net::HTTP.new(url.host, url.port)
-  	http.use_ssl = true
-  	response = http.request(req)
-	end
-	# alias_method :update_customer, :add_customer
+  def configure
+    yield @config ||= Configuration.new
+  end
 
-	def self.message_customer(message_and_phone_number)
-  	url = URI.parse(post_url("message_customer"))
-  	req = Net::HTTP::Post.new(url.request_uri)
-  	req.set_form_data(message_and_phone_number)
-  	http = Net::HTTP.new(url.host, url.port)
-  	http.use_ssl = true
-  	response = http.request(req)
-	end
+  def add_customer(params)
+    resp = Client.post url_for(:customers), params, headers
+    Customer.new(JSON.parse(resp))
+  end
 
-  def self.message_customer(message_and_phone_number)
-    url = URI.parse(post_url("message_customer"))
-    req = Net::HTTP::Post.new(url.request_uri)
-    req.set_form_data(message_and_phone_number)
-    http = Net::HTTP.new(url.host, url.port)
-    http.use_ssl = true
-    response = http.request(req)
+  def message_customer(params)
+    resp = Client.post url_for(:messages), params, headers
+    Message.new(JSON.parse(resp))
   end
 
   private
-  def self.build_url(post_type = nil, params=nil)
-    url = post_url(post_type)
-
-			url << string
-			url = url[0...-1] if (url[-1] == '&')
-		end
 
-		return url
-	end
+  attr_reader :config
 
-	def self.post_url(post_type)
-		if post_type == nil
-			"#{BASE_URL}?token=#{ENV['SIMPLE_DESK_TOKEN'] || CONFIG['simple_desk_token']}"
-		else
-			case post_type
-			when "message_customer"
-				"#{BASE_URL}/api_send_message?token=#{ENV['SIMPLE_DESK_TOKEN'] || CONFIG['simple_desk_token']}"
-			when "add_customer" || "update_customer"
-				"#{BASE_URL}/api_add_customer?token=#{ENV['SIMPLE_DESK_TOKEN'] || CONFIG['simple_desk_token']}"
-			end
-		end
-	end
+  def headers
+    { token: config.token, client: "rubygem #{SimpleDesk::VERSION}" }
+  end
 
+  def url_for(key)
+    Configuration::ENV_URLS[config.env.to_s][key.to_s]
+  end
 end
+

data/simple_desk.gemspec

@@ -6,11 +6,11 @@ require 'simple_desk/version'
 Gem::Specification.new do |spec|
   spec.name          = "simple_desk"
   spec.version       = SimpleDesk::VERSION
-  spec.authors       = ["Elijah Murray"]
-  spec.email         = ["elijah@bluefantail.com"]
-  spec.summary       = %q{Provides a clean and simple gem to connect to Simple Desk}
-  spec.description   = %q{}
-  spec.homepage      = "http://elijahish.com"
+  spec.authors       = ["John Gesimondo", "Elijah Murray"]
+  spec.email         = ["john@jmondo.com", "elijah@bluefantail.com"]
+  spec.summary       = %q{Provides a clean and simple gem to connect to Simpledesk}
+  spec.description   = ""
+  spec.homepage      = "http://github.com/getsimpledesk/simple_desk_gem"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -18,8 +18,11 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "rspec"
-  spec.add_development_dependency "pry"
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake"
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "vcr", "~> 2.6"
+  spec.add_development_dependency "webmock", "~> 1.1"
+
+  spec.add_runtime_dependency "rest-client", '~> 1.7'
 end

data/spec/integrations/simple_desk_spec.rb

@@ -0,0 +1,167 @@
+require 'spec_helper'
+require 'vcr'
+
+VCR.configure do |c|
+  c.cassette_library_dir = 'spec/vcr_cassettes'
+  c.hook_into :webmock # or :fakeweb
+end
+
+describe 'SimpleDesk' do
+  describe '.configure' do
+    context 'token' do
+      it 'has a setter' do
+        SimpleDesk.configure do |config|
+          config.token = 'YOUR_PRODUCTION_TOKEN'
+        end
+      end
+    end
+
+    context 'env' do
+      it 'has a setter' do
+        SimpleDesk.configure do |config|
+          config.env = :live
+        end
+      end
+
+      it 'raises an error if not an allowed option' do
+        expect { SimpleDesk.configure do |config|
+          config.env = :bogus_env
+        end }.to raise_error(SimpleDesk::ConfigurationError)
+      end
+    end
+  end
+
+  shared_examples "a mature, error handling gem" do |context|
+    context 'with an invalid token' do
+      let(:token) { 'FAKE_TOKEN' }
+
+      it 'raises a BadToken error' do
+        VCR.use_cassette("#{cassette_group}_bad_token") do
+          expect { response }.to raise_error(SimpleDesk::BadToken, 'SimpleDesk::BadToken')
+        end
+      end
+    end
+
+    context 'with an inactive subscription' do
+      let(:token) { 'tKux9Vwkt0UuTVJqGUO80MGJHCAeebpe' }
+
+      it 'raises a BadToken error' do
+        VCR.use_cassette("#{cassette_group}_no_subscription") do
+          expect { response }.to raise_error(SimpleDesk::NoActiveSubscription, 'SimpleDesk::NoActiveSubscription')
+        end
+      end
+    end
+
+    context 'with disabled API' do
+      let(:token) { 'ts9mOO_O5Dc7TOBaEAQym-00RGEl3Uel' }
+
+      it 'raises a BadToken error' do
+        VCR.use_cassette("#{cassette_group}_api_disabled") do
+          expect { response }.to raise_error(SimpleDesk::ApiDisabledForCompany, 'SimpleDesk::ApiDisabledForCompany')
+        end
+      end
+    end
+  end
+
+  describe '.add_customer' do
+    before do
+      SimpleDesk.configure do |config|
+        config.token = token
+        config.env = :local
+      end
+    end
+
+    let(:cassette_group) { "add_customer" }
+    let(:response) { SimpleDesk.add_customer(params) }
+    let(:token) { '3Z9L8xFjeNmXL7Yn-pFJUBoxkVWBbl5o' }
+    let(:params) do
+      { phone_number: "5555555557",
+        email: "user@example.com",
+        first_name: "john",
+        last_name: "doe",
+        properties: { great_customer: "true" } }
+    end
+
+    it_behaves_like "a mature, error handling gem"
+
+    context 'with invalid params' do
+      let(:params) do
+        { phone_numbah: "5555555558" }
+      end
+
+      it 'raises a BadRequest error with hint' do
+        VCR.use_cassette("add_customer_bad_params") do
+          expect { response }.to raise_error(SimpleDesk::BadRequest,
+            '400 Bad Request: {"error":"phone_number is missing"}')
+        end
+      end
+    end
+
+    context 'with proper params, active subscription' do
+      it 'returns a new customer' do
+        VCR.use_cassette('add_customer') do
+          expect(response).to be_a(SimpleDesk::Customer)
+        end
+      end
+
+      it 'includes the expected attributes' do
+        VCR.use_cassette('add_customer') do
+          customer = response
+          expect(customer.phone_number).to eq("5555555557")
+          expect(customer.email).to eq("user@example.com")
+          expect(customer.first_name).to eq("john")
+          expect(customer.last_name).to eq("doe")
+          expect(customer.properties).to eq({ "great_customer" => "true" })
+        end
+      end
+    end
+  end
+
+  describe '.message_customer' do
+    before do
+      SimpleDesk.configure do |config|
+        config.token = token
+        config.env = :local
+      end
+    end
+
+    let(:cassette_group) { "message_customer" }
+    let(:response) { SimpleDesk.message_customer(params) }
+    let(:token) { '3Z9L8xFjeNmXL7Yn-pFJUBoxkVWBbl5o' }
+    let(:params) do
+      { to: "5555555557", text: "this is the message text" }
+    end
+
+    it_behaves_like "a mature, error handling gem"
+
+    context 'with invalid params' do
+      let(:params) do
+        { toz: "5555555558" }
+      end
+
+      it 'raises a BadRequest error with hint' do
+        VCR.use_cassette("message_customer_bad_params") do
+          expect { response }.to raise_error(SimpleDesk::BadRequest,
+            '400 Bad Request: {"error":"text is missing, to is missing"}')
+        end
+      end
+    end
+
+    context 'with proper params, active subscription' do
+      it 'returns a new customer' do
+        VCR.use_cassette('message_customer') do
+          expect(response).to be_a(SimpleDesk::Message)
+        end
+      end
+
+      it 'includes the expected attributes' do
+        VCR.use_cassette('message_customer') do
+          message = response
+          expect(message.to).to eq("5555555557")
+          expect(message.text).to eq("this is the message text")
+          expect(message.status).to eq("queued")
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,9 +1,11 @@
-require 'bundler/setup'
-Bundler.setup
-
-require 'simple_desk' # and any other gems you need
-require 'pry'
+require 'simple_desk'
 
 RSpec.configure do |config|
-  # some (optional) config here
-end
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+end