fullcontacter 0.3.2

data/lib/fullcontact/client/provisioning.rb

@@ -0,0 +1,28 @@
+module FullContact
+  class Client
+    module Provisioning
+      # Public:The Provisioning method creates a new API key based on an
+      # Account Key. This method is useful when your application has many end
+      # users that you would like to track separately. An account key is
+      # required for accessing this api method. This account key can be
+      # initialized through the configure method. For getting an account key,
+      # send an email to  support@fullcontact.com.
+      #
+      # Example
+      #
+      #   api_key = FullContact.create_new_api_key
+      #
+      # Returns a hash which contains the generated api_key and monthly quota
+      def create_new_api_key
+        # return error if no provisioning key defined
+        return unless FullContact.options[:account_key]
+        self.endpoint = 'https://api.fullcontact.com/apiKey'
+        options = {:accountKey => FullContact.options[:account_key]}
+        get('new', options)
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/fullcontact/client/snapshot.rb

@@ -0,0 +1,31 @@
+module FullContact
+  class Client
+    module Snapshot
+      # Public: Creates a snapshot in order to store a point-in-time backup of a contactList
+      #
+      # list_id - id of the contact list to be backed-up
+      # options - hash containing additonal arguments
+      #           :name - Name of the snapshot
+      #
+      # Example
+      #
+      #   response = FullContact.create_snapshot(list_id, {:name => 'foo'})
+      #   response.result now contains the snapshot name and timestamp
+      def create_snapshot(list_id, options)
+        post("contactList/#{list_id}/snapshot", options)
+      end
+
+      # Public: List all snapshots associated with a contact list
+      #
+      # list_id - id of the contact list for which snapshots need to be fetched
+      #
+      # Example
+      #
+      #   response = FullContact.list_snapshots(list_id)
+      #   response.snapshots gives a list of snapshot names
+      def list_snapshots(list_id)
+        get("contactList/#{list_id}/snapshot")
+      end
+    end
+  end
+end

data/lib/fullcontact/client/subscription.rb

@@ -0,0 +1,45 @@
+module FullContact
+  class Client
+    module Subscription
+      # Public: Creates a subscription to a contactList in order to receive webhook notifications for certain events
+      #
+      # list_id - id of the contact list for which subscription is to be created
+      # options - hash containing additional arguments
+      #           :event Type of event. Only 'enriched' is supported right now
+      #           :callback Callback URL to post to when event occurs
+      #
+      # Example
+      #
+      #   response = FullContact.create_subscription(list_id, {:event => 'enriched', :callback => callback_url })
+      #   response.id contains the subscription id
+      def create_subscription(list_id, options)
+        post("contactList/#{list_id}/subscribe", options)
+      end
+
+      # Public: Lists all subscriptions associated with a contactList
+      #
+      # list_id - id of the contact list for which subscription is to be created
+      #
+      # Example
+      #
+      #   response = FullContact.list_subscriptions(list_id)
+      #   response.subscriptions contains list of all subscriptions for this contact list
+      def list_subscriptions(list_id)
+        get("contactList/#{list_id}/subscribe")
+      end
+
+      # Public: Delete a subscription associated with a contactList
+      #
+      # list_id - id of the contact list for which subscription is to be created
+      # options - hash containing additional arguments
+      #           :subscription id of the subscription to delete
+      #
+      # Example
+      #
+      #   response = FullContact.delete_subscriptions(list_id, {:subscription => subscription_id})
+      def delete_subscription(list_id, options)
+        delete("contactList/#{list_id}/subscribe", options)
+      end
+    end
+  end
+end

data/lib/fullcontact/client/user.rb

@@ -0,0 +1,28 @@
+module FullContact
+  class Client
+    module User
+      # Public: Authenticate a user using the username and password. If 
+      # authenticated, sets the returned access_token in a access_token config
+      # variable 
+      # 
+      # options - a hash containing the user's username and password
+      #
+      # Example
+      #
+      #   FullContact.authenticate({ :username => 'prafullakiran@gmail.com',
+      #                              :password => 'grizzlybear' })
+      #   # we're authenticated now
+      #   contact_lists = FullContact.get_contact_lists
+      def authenticate(options = {})
+        self.endpoint = 'https://api.fullcontact.com/auth/'
+        self.format = ''
+        access_token = post('token', options)
+
+        FullContact.configure do |config|
+          config.access_token = access_token
+        end
+
+      end
+    end
+  end
+end

data/lib/fullcontact/configuration.rb

@@ -0,0 +1,95 @@
+require 'faraday'
+
+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,
+      :account_key,
+      :get_request_url_only,
+      :endpoint,
+      :format,
+      :access_token,
+      :gateway,
+      :proxy,
+      :user_agent].freeze
+
+    # An array of valid request/response formats
+    #
+    # @note Not all methods support the XML format.
+    VALID_FORMATS = [
+      :json,
+      :xml].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 api key
+    DEFAULT_API_KEY = nil
+    
+    # By default, don't set an access key
+    DEFAULT_ACCESS_TOKEN = nil
+
+    # By default, don't set an account key
+    DEFAULT_ACCOUNT_KEY = nil
+    
+    # By default, get full response
+    GET_REQUEST_URL_ONLY = false
+
+    # 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
+
+     # 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 Gem".freeze
+
+    DEFAULT_GATEWAY = nil
+
+    # @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.access_token         = DEFAULT_ACCESS_TOKEN
+      self.account_key          = DEFAULT_ACCOUNT_KEY
+      self.get_request_url_only = GET_REQUEST_URL_ONLY
+      self.endpoint             = DEFAULT_ENDPOINT
+      self.format               = DEFAULT_FORMAT
+      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,36 @@
+require 'faraday_middleware'
+require 'faraday/request/gateway'
+require 'faraday/response/fullcontact_errors'
+
+
+module FullContact
+  # @private
+  module Connection
+    private
+
+    def connection(raw=false)
+      options = {
+        :headers => {'Accept' => "application/#{format}", 'User-Agent' => user_agent},
+        :proxy => proxy,
+        :ssl => {:verify => false},
+        :url => api_endpoint,
+      }
+
+      Faraday.new(options) do |builder|
+        builder.use Faraday::Request::UrlEncoded
+        builder.use Faraday::Request::Gateway, gateway if gateway
+        builder.use Faraday::Response::Rashify unless raw
+        unless raw
+          case format.to_s.downcase
+          when 'json'
+            builder.use Faraday::Response::ParseJson
+          when 'xml'
+            builder.use Faraday::Response::ParseXml
+          end
+        end
+        builder.use Faraday::Response::FullContactErrors
+        builder.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/fullcontact/error.rb

@@ -0,0 +1,35 @@
+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 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

data/lib/fullcontact/request.rb

@@ -0,0 +1,43 @@
+module FullContact
+  # Defines HTTP request methods
+  module Request
+    # Perform an HTTP GET request
+    def get(path, options={}, raw=false)
+      request(:get, path, options, raw)
+    end
+
+    # Perform an HTTP POST request
+    def post(path, options={}, raw=false)
+      request(:post, path, options, raw)
+    end
+
+    # Perform an HTTP DELETE request
+    def delete(path, options={}, raw=false)
+      request(:delete, path, options, raw)
+    end
+
+    private
+
+    # Perform an HTTP request
+    def request(method, path, options, raw=false)
+      if FullContact.options[:get_request_url_only]
+        return connection(raw).build_url(formatted_path(path), options)
+      end
+      options[:apiKey] = FullContact.options[:api_key]
+      unless FullContact.options[:access_token].nil?
+        options[:accessToken] = FullContact.options[:access_token]
+      end
+      response = connection(raw).send(method) do |request|
+        request.url(formatted_path(path), options)
+        request.headers["Content-Type"] = options[:content_type] if options.include?(:content_type)
+        request.body = options[:request_body] if options.include?(:request_body)
+      end
+      raw ? response : response.body
+    end
+
+    def formatted_path(path)
+      return path if format.to_s.empty?
+      [path, format].compact.join('.')
+    end
+  end
+end

data/lib/fullcontact/version.rb

@@ -0,0 +1,3 @@
+module FullContact
+	VERSION = "0.3.2"
+end

data/spec/faraday/response_spec.rb

@@ -0,0 +1,56 @@
+require 'helper'
+require 'faraday'
+require 'fullcontact'
+
+describe Faraday::Response do
+  before do
+    FullContact.configure do |config|
+      config.api_key = "api_key"
+	  end
+    @client = FullContact::Client.new
+  end
+
+  {
+    400 => FullContact::BadRequest,
+    401 => FullContact::Unauthorized,
+    403 => FullContact::Forbidden,
+    404 => FullContact::NotFound,
+    422 => FullContact::Invalid,
+    500 => FullContact::InternalServerError,
+    502 => FullContact::BadGateway,
+    503 => FullContact::ServiceUnavailable,
+  }.each do |status, exception|
+    if (status >= 500)
+      context "when HTTP status is #{status}" do
+        before do
+          stub_get('person.json').
+            with(:query => {:apiKey => "api_key", :email => 'brawest@gmail.com'}).
+            to_return(:status => status)
+        end
+
+        it "should raise #{exception.name} error" do
+          lambda do
+            @client.lookup_by_email('brawest@gmail.com')
+          end.should raise_error(exception)
+        end
+      end
+    else
+      [nil, "error", "errors"].each do |body|
+        context "when HTTP status is #{status} and body is #{body||='nil'}" do
+          before do
+            body_message = '{"'+body+'":"test"}' unless body.nil?
+         	stub_get('person.json').
+				with(:query => {:apiKey => "api_key", :email => 'brawest@gmail.com'}).
+               to_return(:status => status, :body => body_message)
+          end
+
+          it "should raise #{exception.name} error" do
+            lambda do
+             @client.lookup_by_email('brawest@gmail.com')
+            end.should raise_error(exception)
+          end
+        end
+      end
+    end
+  end
+end

data/spec/fixtures/clear_contact_list.json

@@ -0,0 +1,3 @@
+{
+  "status": 200
+}

data/spec/fixtures/contact_history.json

@@ -0,0 +1,16 @@
+{
+  "history":
+  [
+    {
+      "eTag": "fffffec9b5094cf18aaef4da318436755124a12d2422eaf2c9c44b95",
+      "date": "2012-03-25T17:45:43.441Z",
+      "action": "Enriched"
+    },
+    {
+      "eTag": "fffffec9b536c589363364e51a5dc9800f54d11cdbf1a21fe94ef35b",
+      "date": "2012-03-25T16:56:03.448Z",
+      "action": "Added"
+    }
+  ],
+  "status": 200
+}

data/spec/fixtures/create_contact_list.json

@@ -0,0 +1,4 @@
+{
+  "listId": "fd4e7ca63f79ea5113b2a2ebcf0759c5ebecc250",
+  "status": 200
+}