towerdata_api 1.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 53f6bd6c8d2b1d232fdf12fd6506031c51a74d9f
+  data.tar.gz: 36bdb7c4537e8f0b7272b3c0c0ff24ec299abb09
+SHA512:
+  metadata.gz: 7498f850f77e5d0af26dc927d889813f8d3d47a088d55e3d83c27e503d71c49ff97c75a034e203ddfd5db0309cbeb7befd07ac7fc4fd49f1d1efd7bed2a30e36
+  data.tar.gz: ef19b0a10d17c05b47d421ab5874452a0986855b9c7c28d36ec757e9d4d547f4eb9a512e111e8c0af2a7a7810764ea4dc72089103178b6dee69d2274f324ea8b

data/CHANGELOG

@@ -0,0 +1,13 @@
+v1.2.3. Bulk API support
+
+v1.2.2. Downcase emails before hashing
+
+v1.2.1. Support ca_file instead of ca_path in constructor
+
+v1.2.0. Bump version number to match User-Agent
+
+v0.1.1. Bug fixes
+
+v0.1.0. Added support for show_available
+
+v0.0.1. Initial version

data/LICENSE

@@ -0,0 +1,19 @@
+* The Rapleaf Personalization API has separate terms and conditions, which can
+  be found at http://www.rapleaf.com/developers/api_usage.
+* If you send us code, please keep in mind that it will be distributed under
+  the same license as the rest of the project.
+* This code is licensed under the Apache License which follows...
+
+Copyright 2011 Rapleaf
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/Manifest

@@ -0,0 +1,7 @@
+CHANGELOG
+LICENSE
+Manifest
+README.md
+Rakefile
+lib/towerdata_api.rb
+towerdata_api.gemspec

data/README.md

@@ -0,0 +1,86 @@
+How to Use
+==========
+
+Installation
+------------
+> gem install towerdata_api
+
+This gem depends on the "json" gem.
+
+Usage
+-----
+    require 'towerdata_api'
+    api = TowerDataApi::Api.new('my secret API key')
+    h = api.query_by_email('test@rapleaf.com')
+    => {"gender"=>"Male", "age"=>"25-34"}
+
+Or using global configuration
+
+    require 'towerdata_api'
+    TowerDataApi::Configuration.begin do |config|
+      config.api_key= 'my secret API key'
+      config.timeout= 10 
+    end
+    api = TowerDataApi::Api.new
+    h = api.query_by_email('test@rapleaf.com')
+    => {"gender"=>"Male", "age"=>"25-34"}
+
+
+
+Constructor Options
+-------------------
+You can pass in an options hash to the API constructor, like so:
+
+    api = TowerData::Api.new('my secret API key', :timeout => 10)
+
+The possible options/keys accepted by the constructor are:
+
+ - :timeout => The max amount of time to wait for a request to finish. Defaults to 2.
+ - :ca_file => Set this to your system-wide root CA cert path if you're having SSL verification issues. Defaults to nil.
+ 
+Query Options
+-------------
+The gem supports several ways to query TowerData's API: email, hashed email (either MD5 or SHA1 hash), name and postal (NAP), or name and ZIP+4 (NAZ).
+
+### query_by_email(email, options)
+
+This method queries TowerData's API with the specified email. The options hash accepts the following keys:
+
+ - :hash_email    => Whether to (SHA1) hash the email before querying TowerData's API with it. Defaults to nil.
+
+### query_by_md5(md5_email, options)
+### query_by_sha1(sha1_email, options)
+
+### query_by_nap(first, last, street, city, state, options)
+
+This method queries TowerData's API with a name and postal address: first name, last name, street, city, and state acronym (i.e., the state's 2-character postal code). It also accepts the following options hash:
+
+ - :email          => You can include an email in your NAP query to increase the hit rate. Defaults to nil.
+
+### query_by_naz(first, last, zip4, options)
+
+This method queries TowerData's API with a name and ZIP+4 code. The ZIP+4 is a string with a 5-digit ZIP code and 4-digit extension separated by a dash. This method accepts the following options:
+
+ - :email          => You can include an email in your NAP query to increase the hit rate. Defaults to nil.
+
+### email_validation(email)
+
+This method queries TowerData's API with email and return email_validation object. Raise error if email_validation is not enabled. 
+
+### valid_email?(email)
+
+This method queries TowerData's API with email and return boolean or nil if response is timeout. Raise error if email_validation is not enabled. 
+
+
+Contributing
+============
+If you have suggestions or patches, feel free to email us at
+[developer at towerdata dot com]. We look forward to hearing from you!
+
+
+Contributors
+============
+ - Greg Poulos [greg at rapleaf dot com]
+ - Sean Carr [sean at rapleaf dot com]
+ - Vlad Shulman [vlad at rapleaf dot com]
+ - Bojan Milosavljevic [milboj at gmail dot com]

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'rake'
+#require 'echoe'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec
+

data/lib/towerdata_api.rb

@@ -0,0 +1,200 @@
+# Copyright 2011 Rapleaf
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require "json"
+require "net/https"
+require "timeout"
+require "digest"
+require "open-uri"
+require "towerdata_api/configuration"
+require "towerdata_api/errors"
+require "towerdata_api/email_validation"
+
+module TowerDataApi
+  HOST= "api.towerdata.com".freeze
+  PORT= 443.freeze
+  HEADERS = {'User-Agent' => 'TowerDataApi/Ruby/1.3'}.freeze
+  API_VERSION= 5.freeze
+  BASE_PATH= '/td'.freeze
+  BULK_PATH= '/ei/bulk'.freeze
+
+  class Api
+
+    def initialize(api_key=nil, options = {})
+      @api_key = api_key.nil? ? Configuration.api_key : api_key
+      options.each do |key, value|
+        Configuration.send("#{key}=", value)
+      end 
+    end
+
+    # Takes an e-mail and returns a hash which maps attribute fields onto attributes
+    # Options:
+    #  :hash_email     - the email will be hashed before it's sent to Rapleaf
+    def query_by_email(email, options = {})
+      if options[:hash_email]
+        query_by_sha1(Digest::SHA1.hexdigest(email.downcase))
+      else
+        get_json_response("#{base_path}&email=#{url_encode(email)}")
+      end
+    end
+
+    # Takes an e-mail that has already been hashed by md5
+    # and returns a hash which maps attribute fields onto attributes,
+    # optionally showing available data in the response
+    def query_by_md5(md5_email, options = {})
+      get_json_response("#{base_path}&md5_email=#{url_encode(md5_email)}")
+    end
+
+    # Takes an e-mail that has already been hashed by sha1
+    # and returns a hash which maps attribute fields onto attributes,
+    # optionally showing available data in the response
+    def query_by_sha1(sha1_email, options = {})
+      get_json_response("#{base_path}&sha1_email=#{url_encode(sha1_email)}")
+    end
+
+    # Takes first name, last name, and postal (street, city, and state acronym),
+    # and returns a hash which maps attribute fields onto attributes
+    # Options:
+    #  :email          - query with an email to increase the hit rate
+    def query_by_nap(first, last, street, city, state, options = {})
+      if options[:email]
+        url = "#{base_path}&email=#{url_encode(options[:email])}&first=#{url_encode(first)}&last=#{url_encode(last)}" +
+          "&street=#{url_encode(street)}&city=#{url_encode(city)}&state=#{url_encode(state)}"
+      else
+        url = "#{base_path}&first=#{url_encode(first)}&last=#{url_encode(last)}" +
+          "&street=#{url_encode(street)}&city=#{url_encode(city)}&state=#{url_encode(state)}"
+      end
+      get_json_response(url)
+    end
+
+    # Takes first name, last name, and zip4 code (5-digit zip 
+    # and 4-digit extension separated by a dash as a string),
+    # and returns a hash which maps attribute fields onto attributes
+    # Options:
+    #  :email          - query with an email to increase the hit rate
+    def query_by_naz(first, last, zip4, options = {})
+      if options[:email]
+        url = "#{base_path}&email=#{url_encode(options[:email])}&first=#{url_encode(first)}&last=#{url_encode(last)}&zip4=#{zip4}"
+      else
+        url = "#{base_path}&first=#{url_encode(first)}&last=#{url_encode(last)}&zip4=#{zip4}"
+      end
+      get_json_response(url)
+    end
+
+
+    # For given email returns EmailValidation object
+    # This method will rise TowerDataApi::Error::Unsupported 
+    # if yours api key doesn't have email validation field 
+    #
+    def email_validation email
+      begin
+        result = query_by_email email
+      rescue TowerDataApi::Error::BadRequest 
+        result = {'email_validation' => {'ok' => false}}
+      end
+
+      if result.has_key? 'email_validation'
+        EmailValidation.new result['email_validation']
+      else
+        raise TowerDataApi::Error::Unsupported, 'Email validation is not supported with yours api key.' 
+      end
+    end
+
+    # Check is email valid
+    # This method will rise TowerDataApi::Error::Api 
+    # if yours api key doesn't have email validation field 
+    # Value can be true, false and nil 
+    def valid_email? email
+      email_validation(email).valid?
+    end
+
+
+    # Get bulk request 
+    # set - is array of hashes in format
+    #
+    #  [{email: 'first_email'}, {email: 'second_email'}]
+    #
+    def bulk_query(set)
+      get_bulk_response(bulk_path, JSON.generate(set))
+    end
+
+    private
+
+    def url_encode value 
+       URI::encode value
+    end
+
+    def get_bulk_response(path, data)
+      response = Timeout::timeout(@BULK_TIMEOUT) do
+        begin
+          http_client.post(path, data, HEADERS.merge('Content-Type' => 'application/json'))
+        rescue EOFError # Connection cut out. Just try a second time.
+          http_client.post(path, data, HEADERS.merge('Content-Type' => 'application/json'))
+        end
+      end
+
+      if response.code =~ /^2\d\d/
+        (response.body && response.body != "") ? JSON.parse(response.body) : []
+      else
+        raise TowerDataApi::Error::Api, "Error Code #{response.code}: \"#{response.body}\""
+      end
+    end
+
+    # Takes a url and returns a hash mapping attribute fields onto attributes
+    # Note that an exception is raised in the case that
+    # an HTTP response code other than 200 is sent back
+    # The error code and error body are put in the exception's message
+    def get_json_response(path)
+      response = Timeout::timeout(Configuration.timeout) do
+        begin
+          http_client.get(path, HEADERS)
+        rescue EOFError # Connection cut out. Just try a second time.
+          http_client.get(path, HEADERS)
+        end
+      end
+
+      if response.code =~ /^2\d\d/
+        (response.body && response.body != "") ? JSON.parse(response.body) : {}
+      elsif response.code == '400' 
+        raise TowerDataApi::Error::BadRequest, "Bad request#{response.code}: \"#{response.body}\""
+      else
+        raise TowerDataApi::Error::Api, "Error Code #{response.code}: \"#{response.body}\""
+      end
+    end
+
+    # Returns http connection to HOST on PORT
+    def http_client
+      unless defined?(@http_client)
+        @http_client = Net::HTTP.new(HOST, PORT)
+        @http_client.use_ssl = true
+        @http_client.ca_file = Configuration.ca_file if Configuration.ca_file
+        #@http_client.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        @http_client.start
+      end
+      @http_client
+    end
+
+    def bulk_path
+      "#{api_path}#{BULK_PATH}?api_key=#{@api_key}"
+    end
+
+    def base_path
+      "#{api_path}#{BASE_PATH}?api_key=#{@api_key}"
+    end
+
+    def api_path
+      "/v#{API_VERSION}"
+    end
+  end
+end

data/lib/towerdata_api/configuration.rb

@@ -0,0 +1,46 @@
+module TowerDataApi
+  class Configuration
+
+    @@api_key  = nil
+    @@ca_file = nil
+    @@bulk_timeout = 30
+    @@timeout = 2
+    
+    def self.api_key= api_key
+      @@api_key = api_key
+    end
+
+    def self.api_key
+      @@api_key 
+    end
+
+    def self.ca_file= ca_file
+      @@ca_file = ca_file
+    end
+
+    def self.ca_file
+      @@ca_file 
+    end
+    
+    def self.timeout= timeout
+      @@timeout = timeout
+    end
+
+    def self.timeout
+      @@timeout 
+    end
+
+    def self.bulk_timeout= timeout
+      @@bulk_timeout = timeout
+    end
+
+    def self.timeout
+      @@timeout 
+    end
+
+    def self.begin
+      yield self
+    end
+
+  end
+end

data/lib/towerdata_api/email_validation.rb

@@ -0,0 +1,13 @@
+module TowerDataApi
+  class EmailValidation
+    attr_accessor :status_code, :status, :ok, :domain_type, :email_correction
+    alias_method :valid?, :ok
+
+    def initialize values
+      values.each do |key, value|
+        self.send("#{key}=", value)
+      end
+    end
+  end
+  
+end

data/lib/towerdata_api/errors.rb

@@ -0,0 +1,9 @@
+module TowerDataApi
+  module Error
+    class Base < StandardError; end
+    class Configuration < Base; end
+    class Api < Base; end
+    class BadRequest < Base; end
+    class Unsupported < Base; end
+  end
+end

data/towerdata_api.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{towerdata_api}
+  s.version = "1.3.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["TowerData"]
+  s.date = %q{2014-12-17}
+  s.description = %q{A library for interacting with TowerData's Personalization and Utilities APIs.}
+  s.email = %q{developer @nospam@ towerdata.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.md", "lib/towerdata_api.rb"]
+  s.files = Dir["{lib}/**/*"] + ["CHANGELOG", "LICENSE", "Manifest", "README.md", "Rakefile", "towerdata_api.gemspec"]
+  s.homepage = %q{http://www.towerdata.com}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Rapleaf_api", "--main", "README.md"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{towerdata_api}
+  s.license = 'Apache-2.0'
+  
+  s.rubygems_version = ">=1.6.1"
+  s.summary = %q{A library for interacting with TowerData's Personalization API.}
+  s.add_development_dependency "rspec", '~>3.1'
+
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: towerdata_api
+version: !ruby/object:Gem::Version
+  version: 1.3.1
+platform: ruby
+authors:
+- TowerData
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: A library for interacting with TowerData's Personalization and Utilities
+  APIs.
+email: developer @nospam@ towerdata.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG
+- LICENSE
+- README.md
+- lib/towerdata_api.rb
+files:
+- CHANGELOG
+- LICENSE
+- Manifest
+- README.md
+- Rakefile
+- lib/towerdata_api.rb
+- lib/towerdata_api/configuration.rb
+- lib/towerdata_api/email_validation.rb
+- lib/towerdata_api/errors.rb
+- towerdata_api.gemspec
+homepage: http://www.towerdata.com
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--line-numbers"
+- "--inline-source"
+- "--title"
+- Rapleaf_api
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '1.2'
+requirements: []
+rubyforge_project: towerdata_api
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A library for interacting with TowerData's Personalization API.
+test_files: []