piplapis-ruby 5.0.5 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 91ab0c6412cf37cc084601eb3dc9fafb2f531b61
-  data.tar.gz: 9de85f2eec73a3370ad39af6d3237b40744d1716
+SHA256:
+  metadata.gz: 113f611d2dd082289e53720edc079b6397493f344f7cbbcb7a86136fb17eb7a0
+  data.tar.gz: '06916e4e2a57b73b55c05c34d0eeb89a52436d6b19fd8178f682bfaff1149d3f'
 SHA512:
-  metadata.gz: f119adef4b2ee343cbcb6b08145b930659f5eaa48a8be30215a47d11d6ef5babcf768f5d3e0fcb8197764f5b0d0e99f3a0afd8b8e03e65e37f59ef3f43316abc
-  data.tar.gz: 8a2bdecd2d313df8f1014163a33ac6973a5c6eee2022dd37d8bada6d392131fc022104da3b58c74d1b6f6a48b22c98005e4fbfc217beee3b75f855fa60907762
+  metadata.gz: 645882962cf240ced9465bda799ab0620058a5eca2dbc0f409568e7dabe8f41d29b8d7b0ccc6881a33d025609c0a61b18d3c3146675eaa30da64d171f49c0cee
+  data.tar.gz: bb0261752d58e65c4887077f44f7ccc0abb8bd5c0eadd563d94973d6e9e671e02ee0484630394ac89257ca346ed915127922e02fe563d04e5a2e8ce39dabb542

data/LICENSE

@@ -1,11 +1,11 @@
-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
+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/README.md

@@ -1,25 +1,22 @@
-Pipl API Ruby Library
-===========================
-
-This is the official Ruby client library for easily integrating Pipl's APIs into your application.
-
-* Full details about Pipl's API - [https://pipl.com/dev/](https://pipl.com/dev/)  
-* This library is available in other languages - [https://pipl.com/dev/guide/code_libraries](https://pipl.com/dev/guide/code_libraries)
-
-Library Requirements
---------------------
-
-* Ruby 1.9 and above.
-
-Getting Started & Code Snippets
--------------------------------
-
-**Pipl's Search API**
-* Code snippets - [https://pipl.com/dev/guide/code_snippets](https://pipl.com/dev/guide/code_snippets)
-* Full reference - [https://pipl.com/dev/reference/](https://pipl.com/dev/reference/)  
-
-
-Credits
--------
-
-Thanks to [srochy](https://github.com/srochy) for writing the first version this library!
+# Pipl API Ruby Library
+
+This is a Ruby client library for easily integrating Pipl's APIs into your application.
+
+- Full details about Pipl's APIs - [https://pipl.com/api](https://pipl.com/api)
+- This library is available in other languages - [https://docs.pipl.com/docs/code-libraries](https://docs.pipl.com/docs/code-libraries)
+
+## Library Requirements
+
+- From Ruby SDK version 5.2.0 and above, Ruby 3.0 and above is supported
+
+## Getting Started & Code Snippets
+
+**Pipl's Search API**
+
+- API Portal - [https://pipl.com/api/](https://pipl.com/api/)
+- Code snippets - [https://docs.pipl.com/docs/code-snippets](https://docs.pipl.com/docs/code-snippets)
+- Full reference - [https://docs.pipl.com/reference/](https://docs.pipl.com/reference/)
+
+## Credits
+
+Thanks to [srochy](https://github.com/srochy) for writing the first version this library!

data/lib/pipl/client.rb

@@ -1,177 +1,201 @@
-require 'uri'
-require 'net/http'
-
-require_relative 'configurable'
-require_relative 'containers'
-require_relative 'errors'
-require_relative 'fields'
-require_relative 'response'
-
-
-module Pipl
-
-  class Client
-
-    include Pipl::Configurable
-
-    QUERY_PARAMS = %w(minimum_probability minimum_match hide_sponsored live_feeds show_sources match_requirements
-                source_category_requirements infer_persons)
-
-    def initialize(options = {})
-      Pipl::Configurable.keys.each do |key|
-        instance_variable_set(:"@#{key}", options[key] || Pipl.instance_variable_get(:"@#{key}"))
-      end
-
-    end
-
-    def same_options?(opts)
-      opts.hash == options.hash
-    end
-
-    def search(params={})
-      opts = options.merge params
-      create_search_person(opts)
-      validate_search_params(opts)
-      http, req = create_http_request(opts)
-      if opts.key? :callback
-        do_send_async http, req, opts[:callback]
-      elsif opts[:async] and block_given?
-        do_send_async http, req, Proc.new
-      else
-        do_send http, req
-      end
-    end
-
-    private
-
-    def create_search_person(opts)
-      return if opts.key? :search_pointer
-
-      person = opts[:person] || Pipl::Person.new
-      person.add_field Pipl::Name.new(raw: opts[:raw_name]) if opts[:raw_name]
-      person.add_field Pipl::Email.new(address: opts[:email]) if opts[:email]
-      person.add_field Pipl::Username.new(content: opts[:username]) if opts[:username]
-      person.add_field Pipl::Address.new(raw: opts[:raw_address]) if opts[:raw_address]
-
-      if opts[:first_name] || opts[:middle_name] || opts[:last_name]
-        person.add_field Pipl::Name.new(first: opts[:first_name], middle: opts[:middle_name], last: opts[:last_name])
-      end
-
-      if opts[:country] || opts[:state] || opts[:city]
-        person.add_field Pipl::Address.new(country: opts[:country], state: opts[:state], city: opts[:city])
-      end
-
-      if opts[:phone]
-        if opts[:phone].is_a? String
-          person.add_field Pipl::Phone.new(raw: opts[:phone])
-        else
-          person.add_field Pipl::Phone.new(number: opts[:phone])
-        end
-      end
-
-      if opts[:from_age] || opts[:to_age]
-        person.add_field Pipl::DOB.from_age_range((opts[:from_age] || 0).to_i, (opts[:to_age].to_i || 1000).to_i)
-      end
-
-      opts[:person] = person
-    end
-
-    def validate_search_params(opts)
-      unless opts[:api_key] and not opts[:api_key].empty?
-        raise ArgumentError.new('API key is missing')
-      end
-
-      if opts[:search_pointer] and opts[:search_pointer].empty?
-        raise ArgumentError.new('Given search pointer is empty')
-      end
-
-      unless opts.key? :search_pointer
-        unless opts[:person] and opts[:person].is_searchable?
-          raise ArgumentError.new('No valid name/username/user_id/phone/email/address or search pointer in request')
-        end
-      end
-
-      if opts[:strict_validation]
-        if opts[:minimum_probability] and not (0..1).include? opts[:minimum_probability]
-          raise ArgumentError.new('minimum_probability must be a float in 0..1')
-        end
-
-        if opts[:minimum_match] and not (0..1).include? opts[:minimum_match]
-          raise ArgumentError.new('minimum_match must be a float in 0..1')
-        end
-
-        unless [Pipl::Configurable::SHOW_SOURCES_ALL,
-                Pipl::Configurable::SHOW_SOURCES_MATCHING,
-                Pipl::Configurable::SHOW_SOURCES_NONE, nil, true, false].include? opts[:show_sources]
-          raise ArgumentError.new('show_sources must be one of all, matching, false or a boolean value')
-        end
-
-        if opts[:match_requirements] and not opts[:match_requirements].is_a? String
-          raise ArgumentError.new('match_requirements must be a String')
-        end
-
-        if opts[:source_category_requirements] and not opts[:source_category_requirements].is_a? String
-          raise ArgumentError.new('source_category_requirements must be a String')
-        end
-
-        if opts[:infer_persons] and not [nil, false, true].include? opts[:infer_persons]
-          raise ArgumentError.new('infer_persons must be true, false or nil')
-        end
-
-        unless opts.key? :search_pointer
-          unsearchable = opts[:person].unsearchable_fields
-          if unsearchable and not unsearchable.empty?
-            raise ArgumentError.new("Some fields are unsearchable: #{unsearchable}")
-          end
-        end
-      end
-    end
-
-    def create_http_request(opts)
-      uri = URI(opts[:api_endpoint])
-      query_params = ["key=#{opts[:api_key]}"] +
-          QUERY_PARAMS.map { |k| "#{k}=#{opts[k.to_sym]}" unless opts[k.to_sym].nil? }
-      query_params << opts[:extra] or []
-      query_params << uri.query
-      uri.query = URI.escape(query_params.compact.join('&'))
-
-      req = Net::HTTP::Post.new(uri.request_uri)
-      req['User-Agent'] = opts[:user_agent]
-      if opts.key? :search_pointer
-        req.set_form_data search_pointer: opts[:search_pointer]
-      else
-        h = opts[:person].to_hash
-        req.set_form_data person: h.reject { |_, value| value.nil? }.to_json
-      end
-
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == 'https'
-      http.open_timeout = opts[:http_timeout]
-
-      [http, req]
-    end
-
-    def do_send(http, req)
-      response = http.request(req)
-      if response.is_a? Net::HTTPSuccess
-        SearchResponse.from_http_response(response)
-      else
-        raise Pipl::Client::APIError.from_http_response(response)
-      end
-    end
-
-    def do_send_async(http, req, callback)
-      Thread.new do
-        begin
-          response = do_send http, req
-          callback.call response: response
-        rescue Pipl::Client::APIError => err
-          callback.call error: err
-        rescue Exception => msg
-          callback.call error: msg
-        end
-      end
-    end
-
-  end
-end
+require 'uri'
+require 'net/http'
+
+require_relative 'configurable'
+require_relative 'containers'
+require_relative 'errors'
+require_relative 'fields'
+require_relative 'response'
+
+
+module Pipl
+
+  class Client
+
+    include Pipl::Configurable
+
+    QUERY_PARAMS = %w(
+      minimum_probability
+      minimum_match
+      hide_sponsored
+      live_feeds
+      show_sources
+      match_requirements
+      source_category_requirements
+      infer_persons
+      top_match
+      api_version
+    )
+
+    def initialize(options = {})
+      Pipl::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || Pipl.instance_variable_get(:"@#{key}"))
+      end
+
+    end
+
+    def same_options?(opts)
+      opts.hash == options.hash
+    end
+
+    def search(params={})
+      opts = options.merge params
+      create_search_person(opts)
+      validate_search_params(opts)
+      http, req = create_http_request(opts)
+      if opts.key? :callback
+        do_send_async http, req, opts[:callback]
+      elsif opts[:async] && block_given?
+        do_send_async http, req, Proc.new
+      else
+        do_send http, req
+      end
+    end
+
+    private
+
+    def create_search_person(opts)
+      return if opts.key? :search_pointer
+
+      person = opts[:person] || Pipl::Person.new
+      person.add_field Pipl::Name.new(raw: opts[:raw_name]) if opts[:raw_name]
+      person.add_field Pipl::Email.new(address: opts[:email]) if opts[:email]
+      person.add_field Pipl::Username.new(content: opts[:username]) if opts[:username]
+      person.add_field Pipl::Address.new(raw: opts[:raw_address]) if opts[:raw_address]
+      person.add_field Pipl::Url.new(url: opts[:url]) if opts[:url]
+      person.add_field Pipl::Vehicle.new(vin: opts[:vin]) if opts[:vin]
+
+      if opts[:first_name] || opts[:middle_name] || opts[:last_name]
+        person.add_field Pipl::Name.new(first: opts[:first_name], middle: opts[:middle_name], last: opts[:last_name])
+      end
+
+      if opts[:country] || opts[:state] || opts[:city]
+        person.add_field Pipl::Address.new(country: opts[:country], state: opts[:state], city: opts[:city])
+      end
+
+      if opts[:phone]
+        if opts[:phone].is_a? String
+          person.add_field Pipl::Phone.new(raw: opts[:phone])
+        else
+          person.add_field Pipl::Phone.new(number: opts[:phone])
+        end
+      end
+
+      if opts[:from_age] || opts[:to_age]
+        person.add_field Pipl::DOB.from_age_range((opts[:from_age] || 0).to_i, (opts[:to_age].to_i || 1000).to_i)
+      end
+
+      opts[:person] = person
+    end
+
+    def validate_search_params(opts)
+      unless opts[:api_key] && !opts[:api_key].empty?
+        raise ArgumentError.new('API key is missing')
+      end
+
+      if opts[:search_pointer] && opts[:search_pointer].empty?
+        raise ArgumentError.new('Given search pointer is empty')
+      end
+
+      unless opts.key? :search_pointer
+        unless opts[:person] && opts[:person].is_searchable?
+          raise ArgumentError.new('No valid name/username/user_id/phone/email/address/vin or search pointer in request')
+        end
+      end
+
+      if opts[:strict_validation]
+        if opts[:minimum_probability] && !(0..1).include?(opts[:minimum_probability])
+          raise ArgumentError.new('minimum_probability must be a float in 0..1')
+        end
+
+        if opts[:minimum_match] && !(0..1).include?(opts[:minimum_match])
+          raise ArgumentError.new('minimum_match must be a float in 0..1')
+        end
+
+        unless [Pipl::Configurable::SHOW_SOURCES_ALL,
+                Pipl::Configurable::SHOW_SOURCES_MATCHING,
+                Pipl::Configurable::SHOW_SOURCES_NONE, nil, true, false].include? opts[:show_sources]
+          raise ArgumentError.new('show_sources must be one of all, matching, false or a boolean value')
+        end
+
+        if opts[:match_requirements] && !opts[:match_requirements].is_a?(String)
+          raise ArgumentError.new('match_requirements must be a String')
+        end
+
+        if opts[:source_category_requirements] && !opts[:source_category_requirements].is_a?(String)
+          raise ArgumentError.new('source_category_requirements must be a String')
+        end
+
+        if opts[:infer_persons] && ! [nil, false, true].include?(opts[:infer_persons])
+          raise ArgumentError.new('infer_persons must be true, false or nil')
+        end
+
+        if opts[:top_match] && ! [nil, false, true].include?(opts[:top_match])
+          raise ArgumentError.new('top_match must be true, false or nil')
+        end
+
+        unless opts.key? :search_pointer
+          unsearchable = opts[:person].unsearchable_fields
+          if unsearchable && ! unsearchable.empty?
+            raise ArgumentError.new("Some fields are unsearchable: #{unsearchable}")
+          end
+        end
+      end
+    end
+
+    def get_api_version(opts)
+      api_version = opts[:api_version].to_s.gsub(/\.0$/, "") unless opts[:api_version].nil?
+      api_version ? api_version : DEFAULT_API_VERSION
+    end
+
+    def create_http_request(opts)
+      api_version = get_api_version(opts)
+      uri = URI("#{opts[:api_endpoint]}v#{api_version}/")
+      query_params = ["key=#{opts[:api_key]}"]
+      QUERY_PARAMS.each do |k|
+        query_params << "#{k}=#{URI.encode_www_form_component(opts[k.to_sym])}" unless opts[k.to_sym].nil?
+      end
+      query_params << opts[:extra]
+      query_params << uri.query
+      uri.query = query_params.compact.join('&')
+
+      req = Net::HTTP::Post.new(uri.request_uri)
+      req['User-Agent'] = opts[:user_agent]
+      if opts.key? :search_pointer
+        req.set_form_data search_pointer: opts[:search_pointer]
+      else
+        h = opts[:person].to_hash
+        req.set_form_data person: h.reject { |_, value| value.nil? }.to_json
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = opts[:http_timeout]
+
+      [http, req]
+    end
+
+    def do_send(http, req)
+      response = http.request(req)
+      if response.is_a? Net::HTTPSuccess
+        SearchResponse.from_http_response(response)
+      else
+        raise Pipl::Client::APIError.from_http_response(response)
+      end
+    end
+
+    def do_send_async(http, req, callback)
+      Thread.new do
+        begin
+          response = do_send http, req
+          callback.call response: response
+        rescue Pipl::Client::APIError => err
+          callback.call error: err
+        rescue Exception => msg
+          callback.call error: msg
+        end
+      end
+    end
+
+  end
+end

data/lib/pipl/configurable.rb

@@ -1,58 +1,61 @@
-module Pipl
-
-  module Configurable
-
-    SHOW_SOURCES_ALL = 'all'
-    SHOW_SOURCES_MATCHING = 'matching'
-    SHOW_SOURCES_NONE = 'false'
-
-    attr_accessor :api_key, :minimum_probability, :minimum_match, :hide_sponsored, :live_feeds, :show_sources
-    attr_accessor :match_requirements, :source_category_requirements, :infer_persons, :strict_validation, :user_agent
-    attr_writer :api_endpoint
-
-    class << self
-
-      def keys
-        @keys ||= [
-            :api_key,
-            :minimum_probability,
-            :minimum_match,
-            :hide_sponsored,
-            :live_feeds,
-            :show_sources,
-            :match_requirements,
-            :source_category_requirements,
-            :infer_persons,
-            :strict_validation,
-            :api_endpoint,
-            :user_agent
-        ]
-      end
-
-    end
-
-    def configure
-      yield self
-    end
-
-    def reset!
-      Pipl::Configurable.keys.each do |key|
-        instance_variable_set(:"@#{key}", Pipl::Default.options[key])
-      end
-      self
-    end
-
-    alias setup reset!
-
-    def api_endpoint
-      File.join(@api_endpoint, '')
-    end
-
-    private
-
-    def options
-      Hash[Pipl::Configurable.keys.map { |key| [key, instance_variable_get(:"@#{key}")] }]
-    end
-
-  end
-end
+module Pipl
+
+  module Configurable
+
+    SHOW_SOURCES_ALL = 'all'
+    SHOW_SOURCES_MATCHING = 'matching'
+    SHOW_SOURCES_NONE = 'false'
+    DEFAULT_API_VERSION = 5
+
+    attr_accessor :api_key, :minimum_probability, :minimum_match, :hide_sponsored, :live_feeds, :show_sources
+    attr_accessor :match_requirements, :source_category_requirements, :infer_persons, :strict_validation, :user_agent
+    attr_accessor :top_match
+    attr_writer :api_endpoint
+
+    class << self
+
+      def keys
+        @keys ||= [
+          :api_key,
+          :minimum_probability,
+          :minimum_match,
+          :hide_sponsored,
+          :live_feeds,
+          :show_sources,
+          :match_requirements,
+          :source_category_requirements,
+          :infer_persons,
+          :strict_validation,
+          :api_endpoint,
+          :user_agent,
+          :top_match
+        ]
+      end
+
+    end
+
+    def configure
+      yield self
+    end
+
+    def reset!
+      Pipl::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", Pipl::Default.options[key])
+      end
+      self
+    end
+
+    alias setup reset!
+
+    def api_endpoint
+      File.join(@api_endpoint, '')
+    end
+
+    private
+
+    def options
+      Hash[Pipl::Configurable.keys.map { |key| [key, instance_variable_get(:"@#{key}")] }]
+    end
+
+  end
+end