fullcontact-api-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d09d3cb3e713202cecef58ccc41d7eb20d24d44bdb3003d0f39d94ac9702ef77
+  data.tar.gz: d772eff4a0feb59dd6d91adfa129379e13684cedecdd0fc79c51608b13aef909
+SHA512:
+  metadata.gz: 6ff2ffdaec6ba000e42c0eb25f15a55d415c4d0ece8ba36a665dcb2ae2ab1c45c6f149a5a49a3760f2c2c95c1ca82c5d2419d076eddc74377c0150b38e61864e
+  data.tar.gz: ed657af10f2aedddc0ed806efc1a909eaea8025ea3d23587d83bd2b42d0cbfbd03404e15a74444585d0a73fa73bdd6ef59495a2285f43730e16229543580b79e

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.md

data/.gitignore

@@ -0,0 +1,53 @@
+# rcov generated
+coverage
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+
+# For TextMate
+#*.tmproj
+#tmtags
+
+# For emacs:
+#*~
+#\#*
+#.\#*
+
+# For vim:
+#*.swp
+
+# For redcar:
+#.redcar
+
+# For rubinius:
+#*.rbc
+
+.idea/
+*.lock
+
+*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format=documentation
+--backtrace

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+
+rvm:
+  - 2.4.2
+
+gemfile:
+  - Gemfile
+
+sudo: false
+
+cache: bundler
+
+before_script: "bundle update"
+
+script: "bundle exec rake test"
+
+after_success:
+  - "bundle exec codeclimate-test-reporter"

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+ruby "2.7.5"
+
+gemspec
+gem 'nokogiri', '~> 1.12.5' # >= 1.7 is incompatible with Ruby 2.0
+gem 'codeclimate-test-reporter', group: :test, require: nil

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 FullContact Inc. and contributors
+
+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,153 @@
+FullContact Ruby Gem
+====================
+A Ruby wrapper for the [FullContact API](http://www.fullcontact.com/)
+
+[![Build Status](https://travis-ci.org/fullcontact/fullcontact-api-ruby.svg?branch=master)](https://travis-ci.org/fullcontact/fullcontact-api-ruby)
+[![Gem Version](https://badge.fury.io/rb/fullcontact.svg)](http://badge.fury.io/rb/fullcontact)
+[![Code Climate](https://codeclimate.com/github/fullcontact/fullcontact-api-ruby/badges/gpa.svg)](https://codeclimate.com/github/fullcontact/fullcontact-api-ruby)
+[![Test Coverage](https://codeclimate.com/github/fullcontact/fullcontact-api-ruby/badges/coverage.svg)](https://codeclimate.com/github/fullcontact/fullcontact-api-ruby)
+
+Changes
+-------
+- 0.18.1
+  - Always use the token in header even when the option is given as query.
+- 0.18.0
+    - Add ability to query Company API by company name
+    - Fix XML bug in Company API module
+- 0.17.0 - Upgrade Faraday plugin to ~> 0.11.0
+- 0.16.0 - Upgrade Faraday plugin to ~> 0.10.0.
+- 0.15.0 - Add header-based auth via `config.auth_type = :header` control.
+- 0.14.0 - Remove `plissken` gem to support Rails 5 (#42)
+- 0.13.0
+    - Raise `ArgumentError` if query by Facebook ID/username is used.
+    - Remove deprecated messages.
+- 0.12.0 - `include_headers_in_response = true` includes response headers in returned payload
+    - Accessible as `http_headers` in response. Also accessible on thrown errors (e.g. RateLimited)
+- 0.11.0 - Plisskin transformation can be disabled by specifying a `skip_rubyize = true` in config block.
+- 0.10.0 - Support for FullContact Company API
+- 0.9.0 - Removed Rash gem and replaced with Mashify + Plisskin
+- 0.8.2 - Fix for 0.8.0 constant resolution issue.
+- 0.8.0
+    - Hashie now allowed from [2.2, 4.0) to support a wide range of other applications
+    - Default useragent includes version number for our own information
+    - Useless XML mode and dep on `multi_xml` removed
+    - Code reformatting & basic code hygiene, prep for new features in 0.9.0
+- 0.7.0 - Faraday 0.9.0
+- 0.6.0 - Removal of timeoutSeconds parameter. This parameter is automatically stripped from your request if included.
+
+Installation
+------------
+    gem install fullcontact
+
+Documentation
+-------------
+[http://rdoc.info/gems/fullcontact](http://rdoc.info/gems/fullcontact)
+
+Usage Examples
+--------------
+```ruby
+    require 'fullcontact'
+
+    # This could go in an initializer
+    FullContact.configure do |config|
+        config.api_key = 'fullcontact_api_key_goes_here'
+    end
+
+    # Get information about an email address
+    person = FullContact.person(email: 'bart@fullcontact.com')
+```
+All returned values are Hashie structs. You can access fields as if they were fields:
+
+```ruby
+    # Get person's family_name
+    person.contact_info.family_name
+     => "Lorang"
+```
+
+But you can also turn it into a normal hash
+
+```ruby
+    # Get person's family_name
+    person.to_hash['contact_info']['family_name']
+     => "Lorang"
+```
+Authentication is done through query parameters by default. If you want to use headers instead:
+
+```ruby
+    # This could go in an initializer
+    FullContact.configure do |config|
+        config.api_key = 'fullcontact_api_key_goes_here'
+        config.auth_type = :headers # :header or :query
+    end
+```
+
+There's other ways you can query the Person API:
+```ruby
+    # Get information about an email address, organized by hashes vs. lists
+    person2 = FullContact.person(email: 'bart@fullcontact.com', style: 'dictionary')
+
+    # You can pass in any arbitrary parameters the Person API supports
+    person3 = FullContact.person(email: 'bart@fullcontact.com', style: 'dictionary', webhookUrl: 'https://...')
+
+    # Get information about a twitter handle
+    person4 = FullContact.person(twitter: "bartlorang")
+
+    # Get information from a phone number
+    person6 = FullContact.person(phone:13037170414)
+
+    # Get information about a twitter and ensure a 30s socket open timeout and a 15s socket read timeout
+    # Can throw a Faraday::Error::TimeoutError if timeouts are exceeded
+    person7 = FullContact.person({:twitter => "bartlorang"}, {:request => {:timeout => 15, :open_timeout => 30}})
+
+```
+
+Response formats can more closely mirror FullContact's APIs by disabling snake_case transformation:
+```ruby
+    FullContact.configure do |config|
+        config.api_key = "fullcontact_api_key_goes_here"
+        config.skip_rubyize = true
+    end
+
+    person8 = FullContact.person(email: "bart@fullcontact.com")
+
+    => #<Hashie::Mash contactInfo=#<Hashie::Mash chats=[#<Hashie::Mash client="gtalk" handle="lorangb@gmail.com">,
+    #<Hashie::Mash client="skype" handle="bart.lorang">] familyName="Lorang" fullName="Bart Lorang" givenName="Bart...
+```
+
+You can also query the Company API
+```ruby
+    # Get information about a company
+    company1 = FullContact.company(domain: 'fullcontact.com')
+
+    company1.organization.name
+     => "FullContact Inc."
+```
+
+The Company API also supports searching by company name.
+Please see [our API documentation](https://www.fullcontact.com/developer/docs/company/#lookup-by-company-name) for more details.
+```ruby
+    # Gets a list of search results for a company name ordered by relevance
+    companies = FullContact.company(companyName: 'FullContact')
+
+    # Get the API url for full company profile lookup (append api key to use)
+    # Note the array access, we are just grabbing the first (top) result
+    companies[0].company_api_link
+     => "https://api.fullcontact.com/v2/company/lookup?domain=fullcontact.com&apiKey="
+
+    companies[0].org_name
+     => "FullContact Inc."
+```
+
+
+Contributions
+-------------
+A full list of contributors can be found in
+[GitHub](https://github.com/fullcontact/fullcontact-api-ruby/graphs/contributors)
+
+License
+---------
+Copyright (c) 2016 FullContact Inc. and contributors
+
+
+
+See [LICENSE](https://github.com/fullcontact/fullcontact-api-ruby/blob/master/LICENSE.md) for details.

data/Rakefile

@@ -0,0 +1,25 @@
+#!/usr/bin/env rake
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec
+
+namespace :doc do
+  require 'yard'
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ['HISTORY.md', 'LICENSE.md', 'lib/**/*.rb']
+    task.options = [
+      '--protected',
+      '--output-dir', 'doc',
+      '--tag', 'format:Supported formats',
+      '--tag', 'authenticated:Requires Authentication',
+      '--tag', 'rate_limited:Rate Limited',
+      '--markup', 'markdown',
+    ]
+  end
+end

data/fullcontact.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'fullcontact/version'
+
+Gem::Specification.new do |s|
+  s.add_development_dependency 'maruku', '~> 0.7'
+  s.add_development_dependency 'nokogiri', '~> 1.6'
+  s.add_development_dependency 'rake', '~> 0.9'
+  s.add_development_dependency 'rspec', '~> 3.1'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'codeclimate-test-reporter', '~> 1.0.0'
+  s.add_development_dependency 'webmock', '~> 1.6'
+  s.add_development_dependency 'yard', '~> 0.9.11'
+  s.add_runtime_dependency 'hashie', ['>= 2.0', '< 4.0']
+  s.add_runtime_dependency 'faraday', '~> 1'
+  s.add_runtime_dependency 'faraday_middleware', '~> 1'
+
+  s.author = 'Ratnam Yadav'
+  s.description = %q{A Ruby wrapper for the FullContact API}
+  s.email = ['support@fullcontact.com']
+  s.license = 'MIT'
+
+  s.post_install_message = ''
+
+  s.executables = `git ls-files -- bin/*`.split("\n").map{|f| File.basename(f)}
+  s.files = `git ls-files`.split("\n")
+  s.homepage = 'https://github.com/ratnamyadav/fullcontact-api-ruby'
+  s.name = 'fullcontact-api-ruby'
+  s.require_paths = ['lib']
+  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.6')
+  s.summary = %q{Ruby wrapper for the FullContact API}
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.version = FullContact::VERSION
+end

data/lib/faraday/request/gateway.rb

@@ -0,0 +1,18 @@
+require 'faraday'
+
+# @private
+module Faraday
+  # @private
+  class Request::Gateway < Faraday::Middleware
+    def call(env)
+      url = env[:url].dup
+      url.host = @gateway
+      env[:url] = url
+      @app.call(env)
+    end
+
+    def initialize(app, gateway)
+      @app, @gateway = app, gateway
+    end
+  end
+end

data/lib/faraday/response/add_headers.rb

@@ -0,0 +1,8 @@
+module Faraday
+  class Response::AddHeaders < Response::Middleware
+    def on_complete(env)
+      env.body[:http_headers] = env.response_headers
+      env.body
+    end
+  end
+end

data/lib/faraday/response/fullcontact_errors.rb

@@ -0,0 +1,36 @@
+module Faraday
+  class Response::FullContactErrors < Response::Middleware
+    def on_complete(env)
+      case env[:status]
+        when 400
+          raise FullContact::BadRequest.new(error_message(env), env[:response_headers])
+        when 401
+          raise FullContact::Unauthorized.new(error_message(env), env[:response_headers])
+        when 403
+          raise FullContact::Forbidden.new(error_message(env), env[:response_headers])
+        when 404
+          raise FullContact::NotFound.new(error_message(env), env[:response_headers])
+        when 422
+          raise FullContact::Invalid.new(error_message(env), env[:response_headers])
+        when 429
+          # Note: not currently in use
+          raise FullContact::RateLimited.new(error_message(env), env[:response_headers])
+        when 500
+          raise FullContact::InternalServerError.new(error_message(env), env[:response_headers])
+        when 502
+          raise FullContact::BadGateway.new(error_message(env), env[:response_headers])
+        when 503
+          raise FullContact::ServiceUnavailable.new(error_message(env), env[:response_headers])
+      end
+    end
+
+    def error_message(env)
+      "#{env[:method].to_s.upcase} #{env[:url].to_s}: #{env[:status]}"
+    end
+
+    def initialize(app)
+      super
+      @parser = nil
+    end
+  end
+end

data/lib/faraday/response/rubyize.rb

@@ -0,0 +1,14 @@
+module Faraday
+  class Response::Rubyize < Response::Middleware
+    def parse(body)
+      case body
+      when Hash
+        body.to_snake_keys
+      when Array
+        body.map { |item| parse(item) }
+      else
+        body
+      end
+    end
+  end
+end

data/lib/fullcontact/api.rb

@@ -0,0 +1,21 @@
+require 'fullcontact/connection'
+require 'fullcontact/request'
+
+module FullContact
+  # @private
+  class API
+    # @private
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    # Creates a new API
+    def initialize(options={})
+      options = FullContact.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    include Connection
+    include Request
+  end
+end

data/lib/fullcontact/client/company.rb

@@ -0,0 +1,16 @@
+module FullContact
+  class Client
+    module Company
+      # Returns extended information for a given company (email, phone, twitter or facebook)
+      #
+      def company(options={}, faraday_options={})
+        url = "company/lookup"
+        if options[:companyName]
+          url = "company/search"
+        end
+        response = get(url, options, false, faraday_options)
+        format.to_s.downcase == 'xml' ? response['response'] : response
+      end
+    end
+  end
+end

data/lib/fullcontact/client/person.rb

@@ -0,0 +1,20 @@
+module FullContact
+  class Client
+    module Person
+      # Returns extended information for a given person (email, phone, twitter or facebook)
+      #
+      def person(options={}, faraday_options={})
+        if options.is_a?(String)
+          raise ArgumentError, "Supplying an email address directly is not supported. Please use {email: #{options}} instead."
+        end
+
+        if options.has_key?(:facebookUsername) || options.has_key?(:facebookId)
+          raise ArgumentError, "Querying by Facebook ID or username is no longer supported. Please contact support@fullcontact.com for more information."
+        end
+
+        response = get('person', options, false, faraday_options)
+        format.to_s.downcase == 'xml' ? response['person'] : response
+      end
+    end
+  end
+end

data/lib/fullcontact/client.rb

@@ -0,0 +1,16 @@
+module FullContact
+  # Wrapper for the FullContact REST API
+
+  class Client < API
+    # Require client method modules after initializing the Client class in
+    # order to avoid a superclass mismatch error, allowing those modules to be
+    # Client-namespaced.
+    require 'fullcontact/client/person'
+    require 'fullcontact/client/company'
+
+    alias :api_endpoint :endpoint
+
+    include FullContact::Client::Person
+    include FullContact::Client::Company
+  end
+end

data/lib/fullcontact/configuration.rb

@@ -0,0 +1,94 @@
+require 'faraday'
+require 'fullcontact/version'
+
+module FullContact
+  # Defines constants and methods related to configuration
+  module Configuration
+    # An array of valid keys in the options hash when configuring a {FullContact::API}
+    VALID_OPTIONS_KEYS = [
+        :adapter,
+        :api_key,
+        :auth_type,
+        :endpoint,
+        :format,
+        :skip_rubyize,
+        :include_headers_in_response,
+        :gateway,
+        :proxy,
+        :user_agent].freeze
+
+    # An array of valid request/response formats
+    VALID_FORMATS = [:json].freeze
+
+    # The adapter that will be used to connect if none is set
+    #
+    # @note The default faraday adapter is Net::HTTP.
+    DEFAULT_ADAPTER = Faraday.default_adapter
+
+    # By default, don't set an application key
+    DEFAULT_API_KEY = nil
+
+    # By default, use query parameters
+    DEFAULT_AUTH_TYPE = :query
+
+    # The endpoint that will be used to connect if none is set
+    #
+    DEFAULT_ENDPOINT = 'https://api.fullcontact.com/v2/'.freeze
+
+    # The response format appended to the path and sent in the 'Accept' header if none is set
+    #
+    # @note JSON is preferred over XML because it is more concise and faster to parse.
+    DEFAULT_FORMAT = :json
+
+    # Default transformation done to response
+    DEFAULT_SKIP_RUBYIZE = false
+
+    # Includes response headers
+    DEFAULT_INCLUDE_HEADERS_IN_RESPONSE = false
+
+    # By default, don't use a proxy server
+    DEFAULT_PROXY = nil
+
+    # The user agent that will be sent to the API endpoint if none is set
+    DEFAULT_USER_AGENT = "FullContact Ruby Client/#{FullContact::VERSION}".freeze
+
+    DEFAULT_GATEWAY = nil
+
+    AUTH_HEADER_NAME = 'X-FullContact-APIKey'.freeze
+
+    # @private
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # When this module is extended, set all configuration options to their default values
+    def self.extended(base)
+      base.reset
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+    end
+
+    # Create a hash of options and their values
+    def options
+      options = {}
+      VALID_OPTIONS_KEYS.each { |k| options[k] = send(k) }
+      options
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.adapter = DEFAULT_ADAPTER
+      self.api_key = DEFAULT_API_KEY
+      self.auth_type = DEFAULT_AUTH_TYPE
+      self.endpoint = DEFAULT_ENDPOINT
+      self.format = DEFAULT_FORMAT
+      self.skip_rubyize = DEFAULT_SKIP_RUBYIZE
+      self.include_headers_in_response = DEFAULT_INCLUDE_HEADERS_IN_RESPONSE
+      self.proxy = DEFAULT_PROXY
+      self.user_agent = DEFAULT_USER_AGENT
+      self.gateway = DEFAULT_GATEWAY
+      self
+    end
+  end
+end

data/lib/fullcontact/connection.rb

@@ -0,0 +1,39 @@
+require 'faraday_middleware'
+require 'faraday/request/gateway'
+require 'faraday/response/fullcontact_errors'
+require 'faraday/response/add_headers'
+require 'faraday/response/rubyize'
+require 'faraday_middleware/response/mashify'
+
+
+module FullContact
+  # @private
+  module Connection
+    private
+
+    def connection(raw=false, faraday_options={})
+      options = {
+          :headers => {'Accept' => "application/#{format}", 'User-Agent' => user_agent},
+          :proxy => proxy,
+          :ssl => {:verify => false},
+          :url => api_endpoint,
+      }.merge(faraday_options)
+
+      Faraday.new(options) do |builder|
+        builder.use Faraday::Request::UrlEncoded
+        builder.use Faraday::Request::Gateway, gateway if gateway
+        builder.use FaradayMiddleware::Mashify unless raw
+        builder.use Faraday::Response::AddHeaders if FullContact.include_headers_in_response
+        builder.use Faraday::Response::Rubyize unless raw or FullContact.skip_rubyize
+        unless raw
+          case format.to_s.downcase
+            when 'json'
+              builder.use Faraday::Response::ParseJson
+          end
+        end
+        builder.use Faraday::Response::FullContactErrors
+        builder.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/fullcontact/error.rb

@@ -0,0 +1,47 @@
+module FullContact
+  # Custom error class for rescuing from all FullContact errors
+  class Error < StandardError
+    attr_reader :http_headers
+
+    def initialize(message, http_headers)
+      @http_headers = Hash[http_headers]
+      super message
+    end
+  end
+
+  # Raised when FullContact returns the HTTP status code 400
+  class BadRequest < Error;
+  end
+
+  # Raised when FullContact returns the HTTP status code 401
+  class Unauthorized < Error;
+  end
+
+  # Raised when FullContact returns the HTTP status code 403
+  class Forbidden < Error;
+  end
+
+  # Raised when FullContact returns the HTTP status code 404
+  class NotFound < Error;
+  end
+
+  # Raised when FullContact returns the HTTP status code 422
+  class Invalid < Error;
+  end
+
+  # Raised when FullContact returns the HTTP status code 429
+  class RateLimited < Error;
+  end
+
+  # Raised when FullContact returns the HTTP status code 500
+  class InternalServerError < Error;
+  end
+
+  # Raised when FullContact returns the HTTP status code 502
+  class BadGateway < Error;
+  end
+
+  # Raised when FullContact returns the HTTP status code 503
+  class ServiceUnavailable < Error;
+  end
+end