kickboxer 0.0.1

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in kickboxer.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Solomon White
+
+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,53 @@
+# Kickboxer
+
+Kickboxer is a wrapper around the FullContact API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'kickboxer'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kickboxer
+
+## Usage
+
+The Full Contact API requires an API key.  Register for a free key at
+https://www.fullcontact.com/sign-up/.  Once you receive your key, you can
+configure Kickboxer to use it via:
+
+    Kickboxer.api_key = '01234decafbad'
+
+
+The following API endpoints are implemented:
+
++ Person
+  + lookup (by email, phone number, twitter username, or facebook username)
+- User (TODO)
+- Contact List (TODO)
+- Contact (TODO)
+- Snapshot (TODO)
+- Subscription (TODO)
++ Name
+  + normalize
+  + deduce
+  + similarity
+  + stats
+  + parser
+- Icon (TODO)
+- Provisioning (TODO)
+- Batch Process (TODO)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,13 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc "Run specs"
+task :spec do
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_opts = %w{--colour --format progress}
+    t.pattern = 'spec/**/*_spec.rb'
+  end
+end
+
+desc "Default: run specs."
+task :default => :spec

data/kickboxer.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/kickboxer/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Solomon White"]
+  gem.email         = ["rubysolo@gmail.com"]
+  gem.description   = %q{Kickboxer}
+  gem.summary       = %q{Kickboxer is a Ruby library for accessing the FullContact API}
+  gem.homepage      = "https://github.com/rubysolo/kickboxer"
+
+  gem.add_development_dependency 'pry'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "kickboxer"
+  gem.require_paths = ["lib"]
+  gem.version       = Kickboxer::VERSION
+end

data/lib/kickboxer.rb

@@ -0,0 +1,5 @@
+require "kickboxer/version"
+
+module Kickboxer
+  # Your code goes here...
+end

data/lib/kickboxer/config.rb

@@ -0,0 +1,19 @@
+module Kickboxer
+  def self.api_key=(value)
+    @api_key = value
+  end
+
+  def self.api_key
+    @api_key
+  end
+
+  def self.debug=(value)
+    @debug = value
+  end
+
+  def self.debug
+    @debug
+  end
+
+  class NoApiKeyError < RuntimeError; end
+end

data/lib/kickboxer/name.rb

@@ -0,0 +1,118 @@
+require 'kickboxer/request'
+require 'kickboxer/response'
+
+module Kickboxer
+  class Name
+    # Public: The Name Normalization method takes quasi structured name data
+    # provided as a string and outputs the data in a structured manner. It also
+    # returns a likelihood based only on the order of the given name and family
+    # name as seen in the US population.
+    #
+    # full_name - a string containing the full name.  Can include standard
+    #             prefix, first name, nickname, middle name, last name, and
+    #             suffix.
+    #
+    # Example
+    #
+    #   response = Kickboxer::Name.normalize('Mr. John (Johnny) Michael Smith')
+    #   response.nameDetails.givenName
+    #   # => 'John'
+    #   response.nameDetails.familyName
+    #   # => 'Smith'
+    def self.normalize(full_name)
+      Request.run('name/normalizer', q: full_name)
+    end
+
+    # Public: The Name Deducer method takes a username or email address
+    # provided as a string and attempts to deduce a structured name. It also
+    # returns a likelihood based on US population data. This method is ideal
+    # for business email addresses due to the use of standard convention in
+    # corporate email address formats.
+    #
+    # options - a hash containing the email or username to be interpreted.
+    #           :email - the email address
+    #           :username - the username
+    #           either :email or :username must be populated
+    #
+    # Example
+    #
+    #   response = Kickboxer::Name.deduce(username: 'johndsmith79')
+    #   response.nameDetails.givenName
+    #   # => 'John'
+    #   response.nameDetails.familyName
+    #   # => 'Smith'
+    def self.deduce(options={})
+      require_any_key options, :email, :username
+      Request.run('name/deducer', options)
+    end
+
+    # Public: The Name Similarity endpoint compares two names and returns a
+    # score indicating how similar they are. As the performance of different
+    # similarity algorithms can vary over different data sets, the endpoint
+    # provides 3 separate choices.
+    #
+    # first  - a string containing the first name to compare
+    # second - a string containing the second name to compare
+    #
+    # Example
+    #
+    #   response = Kickboxer::Name.similarity('john', 'johnathan')
+    #   response.result.SimMetrics.jaroWinkler.similarity
+    #   # => 0.8889
+    #   response.result.SecondString.jaroWinkler.similarity
+    #   # => 0.8889
+    #   response.result.FullContact.BigramAnalysis.dice.similarity
+    #   # => 0.5454545455
+    def self.similarity(first, second)
+      Request.run('name/similarity', q1: first, q2: second)
+    end
+
+    # Public: The Name Stats method has a variety of parameters that can be
+    # used to determine more about a name. See the Full Contact documentation
+    # page (http://www.fullcontact.com/docs/?category=name) for a list of
+    # available statistics.
+    #
+    # options - a hash containing the name or name parts to be examined.
+    #           :givenName  - contains a name believed to be a first name.
+    #           :familyName - contains a name believed to be a last name.
+    #           :name       - contains a name of unknown type.
+    #           At least one of the above must be provided.  Both given and
+    #           family name can be provided, if available.
+    #
+    # Example
+    #
+    #   response = Kickboxer::Name.stats(name: 'john')
+    #   response.name.given.likelihood     # likelihood this is a given name
+    #   # => 0.992
+    #   response.name.family.likelihood    # likelihood this is a family name
+    #   # => 0.008
+    def self.stats(options={})
+      require_any_key options, :name, :givenName, :familyName
+      Request.run('name/stats', options)
+    end
+
+    # Public: The Name Parser method can be used when you have two names but
+    # don't know which one is the first name and which is the last name.
+    #
+    # full_name - a string containing the full name in unknown order
+    #
+    # Example
+    #
+    #   response = Kickboxer::Name.parse('smith john')
+    #   response.result.givenName
+    #   # => 'John'
+    #   response.result.familyName
+    #   # => 'Smith'
+    #   response.result.likelihood
+    #   # => 1
+    def self.parse(full_name)
+      Request.run('name/parser', q: full_name)
+    end
+
+    private
+
+    def self.require_any_key(options, *keys)
+      raise "#{ keys.map{|k| ":#{ k }" }.join(' or ') } required" if (options.keys && keys).empty?
+    end
+  end
+end

data/lib/kickboxer/person.rb

@@ -0,0 +1,67 @@
+module Kickboxer
+  class Person
+    # Public: look up a person by email address
+    #
+    # email_address - a string containing the email address
+    #
+    # Example
+    #
+    #   response = Kickboxer::Person.find_by_email('bart@fullcontact.com')
+    #   response.contactInfo.familyName
+    #   # => 'Lorang'
+    #   response.contactInfo.givenName
+    #   # => 'Bart'
+    #
+    def self.find_by_email(email_address)
+      Request.run('person', email: email_address)
+    end
+
+    # Public: look up a person by phone number
+    #
+    # phone_number - a string containing the phone number
+    #
+    # Example
+    #
+    #   response = Kickboxer::Person.find_by_phone_number('+13037170414')
+    #   response.contactInfo.familyName
+    #   # => 'Lorang'
+    #   response.contactInfo.givenName
+    #   # => 'Bart'
+    #
+    def self.find_by_phone_number(phone_number)
+      Request.run('person', phone: phone_number)
+    end
+
+    # Public: look up a person by twitter username
+    #
+    # username - a string containing the twitter username
+    #
+    # Example
+    #
+    #   response = Kickboxer::Person.find_by_twitter('lorangb')
+    #   response.contactInfo.familyName
+    #   # => 'Lorang'
+    #   response.contactInfo.givenName
+    #   # => 'Bart'
+    #
+    def self.find_by_twitter(username)
+      Request.run('person', twitter: username)
+    end
+
+    # Public: look up a person by facebook username
+    #
+    # username - a string containing the facebook username
+    #
+    # Example
+    #
+    #   response = Kickboxer::Person.find_by_facebook('bart.lorang')
+    #   response.contactInfo.familyName
+    #   # => 'Lorang'
+    #   response.contactInfo.givenName
+    #   # => 'Bart'
+    #
+    def self.find_by_facebook(username)
+      Request.run('person', facebookUsername: username)
+    end
+  end
+end

data/lib/kickboxer/request.rb

@@ -0,0 +1,44 @@
+require 'kickboxer/config'
+require 'kickboxer/response'
+
+require 'open-uri'
+require 'json'
+
+module Kickboxer
+  class Request
+    BASE_URL = "https://api.fullcontact.com/v2"
+
+    def initialize(action)
+      @action = action
+    end
+
+    def build_url(options={})
+      options[:apiKey] = Kickboxer.api_key
+      raise NoApiKeyError unless options[:apiKey]
+
+      querystring = options.map{|k,v| "#{ k }=#{ URI.escape v }" } * '&'
+      "#{ BASE_URL }/#{ @action }.json?#{ querystring }"
+    end
+
+    def run(options={})
+      debug = options.delete(:debug) || Kickboxer.debug
+
+      response = open build_url(options)
+      body = response.read
+
+      if debug
+        filename = debug.is_a?(String) ? debug : @action.gsub('/', '-')
+        File.open("#{ filename }.json","w"){|out| out.puts body }
+      end
+
+      data = JSON.parse(body)
+
+      code, text = response.status
+      Response.new data.update(status_code: code.to_i, status_text: text)
+    end
+
+    def self.run(action, options={})
+      new(action).run(options)
+    end
+  end
+end

data/lib/kickboxer/response.rb

@@ -0,0 +1,49 @@
+module Kickboxer
+  class Response
+    def initialize(data={}, &block)
+      @data = normalize data
+      @data.merge!(Collector.new.instance_eval(&block).data) if block_given?
+    end
+
+    def respond_to?(method_id)
+      @data.has_key?(method_id.to_sym) || @data.has_key?(method_id.to_s) || super
+    end
+
+    private
+
+    def normalize(hash)
+      hash.inject({}) do |h, (k,v)|
+        h.update(normalize_key(k) => normalize_value(v))
+      end
+    end
+
+    def normalize_key(key)
+      key.to_sym
+    end
+
+    def normalize_value(value)
+      value.is_a?(Hash) ? Response.new(normalize(value)) : value
+    end
+
+    def method_missing(key, *args)
+      case
+      when @data.has_key?(key.to_sym)
+        @data[key.to_sym]
+      when @data.has_key?(key.to_s)
+        @data[key.to_s]
+      else
+        super
+      end
+    end
+
+    class Collector
+      attr_reader :data
+
+      def method_missing(key, value)
+        @data ||= {}
+        @data[key] = value
+        self
+      end
+    end
+  end
+end