leadtune 0.0.1

data/.gitignore

@@ -0,0 +1,10 @@
+pkg/*
+*.gem
+.bundle
+*~
+.#*
+doc/
+html/
+TAGS
+tags
+.yardoc/

data/.rspec

@@ -0,0 +1,3 @@
+--colour
+--format
+nested

data/Gemfile

@@ -0,0 +1,31 @@
+# LeadTune API Ruby Gem
+#
+# http://github.com/leadtune/leadtune-ruby
+# Eric Wollesen (mailto:devs@leadtune.com)
+# Copyright 2010 LeadTune LLC
+
+source :gemcutter
+
+unless RUBY_PLATFORM == "java"
+  case RUBY_VERSION
+  when /^1.9.2/
+    gem "ruby-debug19"
+  when /^1.8/
+    gem "ruby-debug"
+  end
+end
+
+gem "rake"
+gem "cucumber"
+gem "rdoc"
+gem "rspec", "2.0.0.beta.19"
+gem "rspec-core", "2.0.0.beta.19"
+gem "rspec-expectations", "2.0.0.beta.19"
+gem "rspec-mocks"
+gem "json"
+gem "activemodel"
+gem "curb"
+gem "rack"
+gem "tcpsocket-wait"
+gem "webmock", :git => "http://github.com/phiggins/webmock.git"
+gem "tcpsocket-wait"

data/Gemfile.lock

@@ -0,0 +1,72 @@
+GIT
+  remote: http://github.com/phiggins/webmock.git
+  revision: 68a0708b9e55648252315bd9ec8f5f30ace0d132
+  specs:
+    webmock (1.3.5)
+      addressable (>= 2.1.1)
+      crack (>= 0.1.7)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.0)
+      activesupport (= 3.0.0)
+      builder (~> 2.1.2)
+      i18n (~> 0.4.1)
+    activesupport (3.0.0)
+    addressable (2.2.1)
+    builder (2.1.2)
+    columnize (0.3.1)
+    crack (0.1.8)
+    cucumber (0.8.5)
+      builder (~> 2.1.2)
+      diff-lcs (~> 1.1.2)
+      gherkin (~> 2.1.4)
+      json_pure (~> 1.4.3)
+      term-ansicolor (~> 1.0.4)
+    curb (0.7.8)
+    diff-lcs (1.1.2)
+    gherkin (2.1.5)
+      trollop (~> 1.16.2)
+    i18n (0.4.1)
+    json (1.4.6)
+    json_pure (1.4.6)
+    linecache (0.43)
+    rack (1.2.1)
+    rake (0.8.7)
+    rdoc (2.5.11)
+    rspec (2.0.0.beta.19)
+      rspec-core (= 2.0.0.beta.19)
+      rspec-expectations (= 2.0.0.beta.19)
+      rspec-mocks (= 2.0.0.beta.19)
+    rspec-core (2.0.0.beta.19)
+    rspec-expectations (2.0.0.beta.19)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.0.beta.19)
+    ruby-debug (0.10.3)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.3.0)
+    ruby-debug-base (0.10.3)
+      linecache (>= 0.3)
+    tcpsocket-wait (1.0.0)
+    term-ansicolor (1.0.5)
+    trollop (1.16.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activemodel
+  cucumber
+  curb
+  json
+  rack
+  rake
+  rdoc
+  rspec (= 2.0.0.beta.19)
+  rspec-core (= 2.0.0.beta.19)
+  rspec-expectations (= 2.0.0.beta.19)
+  rspec-mocks
+  ruby-debug
+  tcpsocket-wait
+  webmock!

data/README.rdoc

@@ -0,0 +1,94 @@
+= LeadTune API Ruby Gem
+
+http://github.com/leadtune/leadtune-ruby
+
+Copyright 2010 LeadTune, LLC
+
+Eric Wollesen (mailto:devs@leadtune.com)
+
+For details about the LeadTune API, see: http://leadtune.com/api
+
+== Configuration
+
+Authentication credentials can be specified by any of several methods, as
+detailed below.  Available configuration values include:
+
+* username
+* password
+* organization
+
+=== Configuration File
+
+The configuration file can be specified when calling Prospect#new.  If no
+file is specified, the gem will also look for +leadtune.yml+ in the
+current directory.
+
+==== Format
+
+The configuration file is a YAML file, an example of which is:
+ username: me@mycorp.com
+ password: my_secret
+ organization: MYC
+
+=== Environment Variables
+
+Your LeadTune username, password, and organization can be specified in the
++LEADTUNE_USERNAME+, +LEADTUNE_PASSWORD+, and +LEADTUNE_ORGANIZATION+
+environment variables. <em>These values take precedence over values read
+from the configuration file.</em>
+
+=== Factors Hash
+
+When initializing your Leadtune::Prospect, you can include your username,
+password, and organization along with any factors you wish to
+submit. <em>These values take precedence over values read from environment
+variables, or the configuration file.</em>
+
+=== Instance Methods
+
+You can also set your username, password, and organization by calling the
+Leadtune::Prospect object's #username=, #password=, and #organization=
+methods. <em>These values take precedence over values read from
+environment variables, a configuration file, or the factors hash.</em>
+
+== Example Usage
+
+An attempt was made to allow for an ActiveModel-like interface.
+
+ require "rubygems"
+ require "leadtune"
+
+ prospect = Leadtune::Prospect.post({
+   :username => "admin@loleads.com"        # required (See Leadtune::Config)
+   :password => "secret"                   # required (See Leadtune::Config)
+   :organization => "LOL",                 # required (See Leadtune::Config)
+   :event => "offers_prepared",            # required
+   :email => "test@example.com"            # required
+   :target_buyers => ["TB-LOL", "AcmeU",]  # required
+   # ... include optional factors here, see http://leadtune.com/factors for details
+ })
+
+<em>Or alternatively</em>
+
+ prospect = Leadtune::Prospect.post do |p|
+   p.event = "offers_prepared"
+   p.email = "test@example.com"   
+   ... and so on
+ end
+
+<em>Or even</em>
+
+ prospect = Leadtune::Prospect.new
+ prospect.event = "offers_prepared"
+ prosepct.email = "test@example.com"   
+ ... and so on
+ prospect.post
+
+== Automatic Environment Determination
+
+At initialization, an attempt is made to determine your application's current
+environment.  If a rack or rails production environment is detected, prospects
+will be posted to LeadTune's production host.  Otherwise prospects will be
+posted to LeadTune's sandbox host.  The application environment can be
+overriden via the +APP_ENV+ environment variable, which takes precedence over
+all other methods.

data/Rakefile

@@ -0,0 +1,42 @@
+# -*- ruby -*-
+
+# LeadTune API Ruby Gem
+#
+# http://github.com/leadtune/leadtune-ruby
+# Eric Wollesen (mailto:devs@leadtune.com)
+# Copyright 2010 LeadTune LLC
+
+require 'bundler'
+Bundler.setup
+Bundler::GemHelper.install_tasks
+
+require 'rake'
+require 'yaml'
+
+require 'rake/rdoctask'
+require 'rspec/core/rake_task'
+require 'cucumber/rake/task'
+
+RSpec::Core::RakeTask.new
+Cucumber::Rake::Task.new
+Rake::RDocTask.new(:rdoc) do |rd|
+  rd.options << "-t LeadTune API Ruby Gem"
+  rd.options << "--exclude=Gemfile"
+  rd.options << "--exclude=TAGS"
+  rd.options << "--exclude=Rakefile"
+  rd.options << "--exclude=spec/"
+end
+
+desc 'clobber generated files'
+task :clobber => [:clobber_rdoc,] do
+  rm_rf "pkg"
+  rm_rf "tmp"
+  rm_rf "doc"
+end
+
+task :hudson => [:spec, :rdoc,]
+
+task :default => [:spec, :cucumber,]
+
+
+

data/leadtune.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8; mode: ruby; -*-
+
+# LeadTune API Ruby Gem
+#
+# http://github.com/leadtune/leadtune-ruby
+# Eric Wollesen (mailto:devs@leadtune.com)
+# Copyright 2010 LeadTune LLC
+
+require File.expand_path("../lib/leadtune/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "leadtune"
+  s.version     = Leadtune::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Eric Wollesen"]
+  s.email       = ["devs@leadtune.com"]
+  s.homepage    = "http://github.com/leadtune/leadtune-ruby"
+  s.summary     = "LeadTune Ruby API Gem"
+  s.description = "LeadTune Ruby API Gem"
+
+  s.required_rubygems_version = ">= 1.3.6"
+
+  s.add_development_dependency "bundler", ">= 1.0.0"
+
+  s.files        = `git ls-files`.split("\n")
+  s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

data/lib/array_extensions.rb

@@ -0,0 +1,12 @@
+# LeadTune API Ruby Gem
+#
+# http://github.com/leadtune/leadtune-ruby
+# Eric Wollesen (mailto:devs@leadtune.com)
+# Copyright 2010 LeadTune LLC
+
+class Array
+  # stolen from ActiveSupport
+  def extract_options!
+    last.is_a?(::Hash) ? pop : {}
+  end
+end

data/lib/hash_extensions.rb

@@ -0,0 +1,34 @@
+# LeadTune API Ruby Gem
+#
+# http://github.com/leadtune/leadtune-ruby
+# Eric Wollesen (mailto:devs@leadtune.com)
+# Copyright 2010 LeadTune LLC
+
+class Hash
+  # File merb/core_ext/hash.rb, line 87
+  def to_params
+    params = ''
+    stack = []
+
+    each do |k, v|
+      if v.is_a?(Hash)
+        stack << [k,v]
+      else
+        params << "#{k}=#{v}&"
+      end
+    end
+
+    stack.each do |parent, hash|
+      hash.each do |k, v|
+        if v.is_a?(Hash)
+          stack << ["#{parent}[#{k}]", v]
+        else
+          params << "#{parent}[#{k}]=#{v}&"
+        end
+      end
+    end
+
+    params.chop! # trailing &
+    params
+  end
+end

data/lib/leadtune/appraisals.rb

@@ -0,0 +1,17 @@
+# LeadTune API Ruby Gem
+#
+# http://github.com/leadtune/leadtune-ruby
+# Eric Wollesen (mailto:devs@leadtune.com)
+# Copyright 2010 LeadTune LLC
+
+# Extends Array by adding a few convenience methods for find duplicate,
+# or non-duplicate appraisals.
+class Leadtune::Appraisals < Array
+  def non_duplicates
+    find_all {|a| 0 < a["value"]}
+  end
+
+  def duplicates
+    find_all {|a| 0 == a["value"]}
+  end
+end

data/lib/leadtune/config.rb

@@ -0,0 +1,89 @@
+# LeadTune API Ruby Gem
+#
+# http://github.com/leadtune/leadtune-ruby
+# Eric Wollesen (mailto:devs@leadtune.com)
+# Copyright 2010 LeadTune LLC
+
+module Leadtune
+
+  class Config #:nodoc:all
+
+    attr_accessor :environment, :leadtune_host, :username, :password, :timeout
+
+    def initialize(config_file=nil)
+      load_config_file_values(config_file)
+    end
+
+    def username
+      @username ||= ENV["LEADTUNE_USERNAME"] || @config_file_values["username"]
+    end
+
+    def password
+      @password ||= ENV["LEADTUNE_PASSWORD"] || @config_file_values["password"]
+    end
+
+    def timeout
+      @timeout ||= (ENV["LEADTUNE_TIMEOUT"] || 
+                    @config_file_values["timeout"] || 
+                    DEFAULT_TIMEOUT).to_i
+    end
+
+    def organization
+      ENV["LEADTUNE_ORGANIZATION"] || @config_file_values["organization"]
+    end
+
+    def leadtune_host
+      @leadtune_host ||= (ENV["LEADTUNE_HOST"] || 
+                          @config_file_values["host"] ||
+                          LEADTUNE_HOSTS[environment])
+    end
+
+    def environment
+      @environment ||= production_environment_detected? ? :production : :sandbox
+    end
+
+    def production_environment_detected?
+      if ENV.include?("APP_ENV")
+        "production" == ENV["APP_ENV"]
+      else
+        defined?(Rails) && Rails.env.production? ||
+          "production" == ENV["RACK_ENV"] ||
+          "production" == ENV["RAILS_ENV"] ||
+          defined?(RAILS_ENV) && "production" == RAILS_ENV
+      end
+    end
+
+
+    private
+
+    def load_config_file_values(config_file)
+      @config_file_values = {}
+
+      find_config_file(config_file) do |config_file|
+        @config_file_values = YAML::load(config_file)
+      end
+    end
+
+    def find_config_file(config_file)
+      case config_file
+      when String
+        yield File.open(config_file)
+      when File, StringIO
+        yield config_file
+      when nil
+        if File.exist?("leadtune.yml")
+          yield File.open("leadtune.yml") 
+        end
+      end
+    end
+
+
+    DEFAULT_TIMEOUT = 5
+    LEADTUNE_HOST_SANDBOX = "https://sandbox-appraiser.leadtune.com".freeze 
+    LEADTUNE_HOST_PRODUCTION = "https://appraiser.leadtune.com".freeze
+    LEADTUNE_HOSTS = {
+      :production => LEADTUNE_HOST_PRODUCTION,
+      :sandbox => LEADTUNE_HOST_SANDBOX,
+    }
+  end
+end

data/lib/leadtune/prospect.rb

@@ -0,0 +1,237 @@
+# LeadTune API Ruby Gem
+#
+# http://github.com/leadtune/leadtune-ruby
+# Eric Wollesen (mailto:devs@leadtune.com)
+# Copyright 2010 LeadTune LLC
+
+require "yaml"
+require "curb"
+require "uri"
+
+require "leadtune/appraisals"
+require "leadtune/rest"
+require "leadtune/config"
+
+
+module Leadtune
+
+  # Simplify the process of submitting prospects to LeadTune for duplicate
+  # checking and appraisal.
+  # 
+  # For details about the LeadTune API, see: http://leadtune.com/api
+  #
+  # == Dynamic Factor Access
+  #
+  # Getter and setter methods are dynamically defined for factors as they're
+  # set. See http://leadtune.com/factors for a list of LeadTune recognized
+  # factors.
+
+  class Prospect
+    attr_accessor :decision  #:nodoc:
+
+    # Initialize a new Leadtune::Prospect object.  
+    #
+    # [+config_file+] An optional filename or a file-like object
+    # [+factors+]     A hash of factors with which to initialize the Prospect
+
+    def initialize(*args, &block)
+      @factors = {}
+      @decision = nil
+      @config = Config.new(args.first)
+      @rest = Rest.new(@config)
+
+      load_options_and_factors(args.extract_options!)
+      block.call(self) if block_given?
+    end
+
+    # Get a prospect from the LeadTune Appraiser service.
+    #
+    # Raises a Leadtune::LeadtuneError if a non-2XX response is received.
+
+    def self.get(options={}, &block)
+      new(options, &block).get
+    end
+
+    # Post a prospect to the LeadTune Appraiser service.
+    #
+    # Raises a Leadtune::LeadtuneError if a non-2XX response is received.
+
+    def self.post(options={}, &block)
+      new(options, &block).post
+    end
+
+    # Update a prospect from the LeadTune Appraiser service.
+    #
+    # Raises a Leadtune::LeadtuneError if a non-2XX response is received.
+
+    def self.put(options={}, &block)
+      new(options, &block).put
+    end
+
+    # Get a prospect from the LeadTune Appraiser service.
+    #
+    # Raises a Leadtune::LeadtuneError if a non-2XX response is received.
+
+    def get
+      json = @rest.get(post_data)
+      parse_response(json)
+      self
+    end
+
+    # Post this prospect to the LeadTune Appraiser service.
+    #
+    # Raises a Leadtune::LeadtuneError if a non-2XX response is received.
+
+    def post
+      json = @rest.post(post_data)
+      parse_response(json)
+      self
+    end
+
+    # Update a prospect from the LeadTune Appraiser service.
+    #
+    # Raises a Leadtune::LeadtuneError if a non-2XX response is received.
+
+    def put
+      json = @rest.put(post_data)
+      parse_response(json)
+      self
+    end
+
+    # The unique +decision_id+ for this prospect.
+
+    def decision_id
+      @decision ||= {}
+      @decision["decision_id"]
+    end
+
+    # The appraisals for this Prospect.
+    #
+    # The Array returned has been extended to include two methods,
+    # +duplicates+ and +non_duplicates+.  Each returns the appraisals of the
+    # target_buyers for whom this lead is or is not a known duplicate.
+    
+    def appraisals
+      @decision ||= {}
+      @decision["appraisals"]
+    end
+
+    # Return a hash of the factors specified for this Prospect.
+    
+    def factors
+      @factors
+    end
+
+    # Assign an array of organization codes for the prospect's target buyers.
+
+    def target_buyers=(target_buyers)
+      unless target_buyers.is_a?(Array)
+        raise ArgumentError.new("target_buyers must be an Array")
+      end
+
+      @decision = {"target_buyers" => target_buyers}
+    end
+
+    # Return an array of organization codes for the prospect's target buyers.
+
+    def target_buyers
+      @decision ||= {}
+      @decision["target_buyers"] ||= []
+    end
+
+    def organization #:nodoc:
+      @factors["organization"] ||= @config.organization
+    end
+    
+    def prospect_id #:nodoc:
+      @factors["prospect_id"]
+    end
+
+    def prospect_ref #:nodoc:
+      @factors["prospect_ref"]
+    end
+
+    def leadtune_host=(host) #:nodoc:
+      @config.leadtune_host = host
+    end
+
+    def leadtune_host #:nodoc:
+      @config.leadtune_host
+    end
+
+    def username=(username)
+      @config.username = username
+    end
+
+    def password=(password)
+      @config.password = password
+    end
+
+
+    private 
+
+    def post_data #:nodoc:
+      @factors.merge("decision" => decision)
+    end
+
+    def load_options_and_factors(options) #:nodoc:
+      load_options(options)
+      load_factors(options)
+    end
+
+    def load_options(options) #:nodoc:
+      @rest.username = options.delete("username") if options["username"]
+      @rest.password = options.delete("password") if options["password"]
+      @config.timeout = options.delete("timeout") if options["timeout"]
+      @config.leadtune_host = options.delete("timeout") if options["leadtune_host"]
+    end
+
+    def load_factors(factors) #:nodoc:
+      factors.each_pair do |key, value|
+        self.send("#{key}=", value)
+      end
+    end
+
+    def parse_response(response) #:nodoc:
+      load_decision(response)
+      load_factors(response)
+    end
+
+    def load_decision(response) #:nodoc:
+      return unless response.include?("decision")
+
+      @decision = response.delete("decision")
+      if @decision.include?("appraisals")
+        @decision["appraisals"] = Appraisals.new(@decision["appraisals"])
+      end
+    end
+
+    def method_missing(name, *args, &block) #:nodoc:
+      if /=$/ === name.to_s
+        memoize_new_factor(name)
+        self.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def memoize_new_factor(name) #:nodoc:
+      getter_name = name.to_s.sub(/=$/, "")
+
+      self.class.class_eval do
+        define_method(name) do |value|
+          @factors[getter_name] = value
+        end
+      end
+
+      unless respond_to?(getter_name)
+        self.class.class_eval do
+          define_method(getter_name) do
+            @factors[getter_name]
+          end
+        end
+      end
+    end
+
+  end
+end