fullcontacter 0.3.2

data/lib/fullcontact/client/contact.rb

@@ -0,0 +1,119 @@
+module FullContact
+  class Client
+    module Contact
+      # Public: Creates/Modifies a contact
+      #
+      # list_id - id of the contact list to which this contact is to be added
+      # options - Hash containing contact data and other options
+      #           :contact_data       - Hash representing the contact information in POCO format
+      #           :generateIds(0|1)   - Whether or not ids need to be generated by the system (optional) (default: 0)
+      #           :queue(true|false)  - Check for updates on creation if true (optional) (default: false)
+      #
+      # Example
+      #
+      #   contact = FullContact.update_contact(list_id, { :contact_data => data , :generateIds => 1 })
+      #   # 'contact' contains the newly created contact
+      def update_contact(list_id, options)
+        options[:content_type] = 'application/json'
+        options[:request_body] = options[:contact_data]
+        options.delete(:contact_data)
+        contacts = post("contactLists/#{list_id}", options)
+      end
+
+      # Public: Retrieves a contact
+      #
+      # list_id    - id of the contact list from which this contact is to be retrieved
+      # contact_id - id of the contact which is to be retrieved
+      # options    - Hash containing additonal arguments (optional) (default: {})
+      #              :eTag - represents a unique version of the contact. Retrieves latest version if not specified (optional)
+      #
+      # Example
+      #
+      #   contact = FullContact.get_contact(list_id, contact_id)
+      #   # contact now contains details about this contact
+      def get_contact(list_id, contact_id, options = {})
+        get("contactLists/#{list_id}/#{contact_id}", options)
+      end
+
+      # Public: Delete contact
+      #
+      # list_id    - id of the contact list from which this contact is to be deleted
+      # contact_id - id of the contact which is to be deleted
+      #
+      # Example
+      #
+      #   FullContact.delete_contact(list_id, contact_id)
+      def delete_contact(list_id, contact_id)
+        delete("contactLists/#{list_id}/#{contact_id}")
+      end
+
+      # Public: Checks if a contact has new enrichment updates available
+      #
+      # list_id    - id of the contact list to which this contact belongs
+      # contact_id - id of the contact which needs to be checked for enrichment updates
+      # options    - Hash containing additonal arguments (optional) (default: {})
+      #              :eTag - represents a unique version of the contact. Retrieves latest version if not specified (optional)
+      #
+      # Example
+      #
+      #   response = FullContact.has_enriched_updates?(list_id, contact_id)
+      #   response.hasUpdates is now either true/false
+      def has_enriched_updates?(list_id, contact_id, options = {})
+        get("contactLists/#{list_id}/#{contact_id}/hasUpdates", options)
+      end
+
+      # Public: Gets latest updates for this contact
+      #
+      # list_id    - id of the contact list to which this contact belongs
+      # contact_id - id of the contact whose updates are needed
+      #
+      # Example
+      #
+      #   response = FullContact.get_updates(list_id, contact_id)
+      #   response.updates now contains the hash denoting the updates for this user
+      def get_updates(list_id, contact_id)
+        get("contactLists/#{list_id}/#{contact_id}/updates")
+      end
+
+      # Public: Gets fully enriched version of the contact
+      #
+      # list_id    - id of the contact list to which this contact belongs
+      # contact_id - id of the contact whose enriched version is needed
+      #
+      # Example
+      #
+      #   response = FullContact.get_enriched_contact(list_id, contact_id)
+      #   response.data now contains the hash denoting the enriched information for this contact
+      def get_enriched_contact(list_id, contact_id)
+        get("contactLists/#{list_id}/#{contact_id}/enriched")
+      end
+
+      # Public: Saves fully enriched version of the contact
+      #
+      # list_id    - id of the contact list to which this contact belongs
+      # contact_id - id of the contact whose enriched version is to be saved
+      #
+      # Example
+      #
+      #   response = FullContact.save_enriched_contact(list_id, contact_id)
+      def save_enriched_contact(list_id, contact_id)
+        post("contactLists/#{list_id}/#{contact_id}/enriched")
+      end
+
+      # Public: Retrieves a list of eTags representing the history of a contact
+      #
+      # list_id    - id of the contact list to which this contact belongs
+      # contact_id - id of the contact whose history is needed
+      # options    - Hash containing additional arguments (optional) (default: {})
+      #              :actionType("Added"|"Updated"|"Deleted"|"Enriched") - filters list based on the given action type
+      #
+      # Example
+      #
+      #   response = FullContact.history(list_id, contact_id, "Updated")
+      #   response.history now contains a list of 'Update' actions, with corresponding eTags for this contact
+      def contact_history(list_id, contact_id, options = {})
+        get("contactLists/#{list_id}/#{contact_id}/history", options)
+      end
+    end
+  end
+end

data/lib/fullcontact/client/contact_list.rb

@@ -0,0 +1,84 @@
+module FullContact
+  class Client
+    module ContactList
+      # Public: Creates a contact list for the authenticating user
+      #
+      # options - a Hash containing the alias(optional) for the new list
+      #
+      # Example
+      #
+      #   list = FullContact.create_contact_list(:alias => 'dummy')
+      #   # 'list' contains the newly created contact list
+      def create_contact_list(options = {})
+        post('contactLists', options)
+      end
+
+      # Public: Deletes a contact list of the authenticating user
+      #
+      # list_id - id of the list object to be deleted
+      #
+      # Example
+      #
+      #   list = FullContact.create_contact_list(:alias => 'dummy')
+      #   # Delete this list now...
+      #   FullContact.delete_contact_list(list.list_id)
+      def delete_contact_list(list_id)
+        delete("contactLists/#{list_id}")
+      end
+
+      # Public: Retrieves all the contact lists for the authenticating user
+      #
+      # Example
+      #
+      #   lists = FullContact.get_contact_lists
+      #   # Iterate over this list now..
+      #   lists.each { |list| puts list.inspect }
+      def get_contact_lists
+        contact_lists = get('contactLists').lists
+        contact_lists.map do |list|
+          list.list_id = list.id
+        end
+        contact_lists
+      end
+
+      # Public: Gets the contacts within a contact list
+      #
+      # list_id - Id of the list from which contacts need to be retrieved
+      #
+      # Example
+      #
+      #   lists = FullContact.get_contact_lists
+      #   # Get contacts in first list now
+      #   FullContacts.get_contacts_in_a_list(lists[0].list_id)
+      def get_contacts_in_a_list(list_id, options={})
+        get("contactLists/#{list_id}", options)
+      end
+
+      # Public: Queues a contact list for enrichment to search for new contact information
+      #
+      # list_id - Id of the list which needs to be queued for enrichment
+      #
+      # Example
+      #
+      #   lists = FullContact.get_contact_lists
+      #   # Enrich the contacts in first list
+      #   FullContacts.queue_contact_list_for_enrichment(lists[0].list_id)
+      def queue_contact_list_for_enrichment(list_id)
+        post("contactLists/#{list_id}/queue")
+      end
+
+      # Public: Removes all contacts in a contact list
+      #
+      # list_id - Id of the list from which contacts need to be cleared
+      #
+      # Example
+      #
+      #   lists = FullContact.get_contact_lists
+      #   # Clear contacts in first list
+      #   FullContacts.clear_contact_list(lists[0].list_id)
+      def clear_contact_list(list_id)
+        post("contactLists/#{list_id}/clear")
+      end
+    end
+  end
+end

data/lib/fullcontact/client/icon.rb

@@ -0,0 +1,35 @@
+module FullContact
+  class Client
+    # Public: Methods for interacting with icon endpoint
+    module Icon
+      # Public: Provies url to different social media icons. All icons are
+      # 24 bit PNG and come in 4 different sizes. Allows you to quickly
+      # incorporate social network icons into FullContact powered your apps.
+      # see http://www.fullcontact.com/docs/?category=icon for list of
+      # available icons
+      #
+      # type_id - String name of the icon you want. (default: 'facebook')
+      # size    - The size parameter allows you to specify the size of icon
+      #           that you want. Icons are available in 16, 24, 32 and 64
+      #           pixels square. (default: '32')
+      # style   - Allows to pick from available styles of icon
+      #           (default: 'default')
+      #
+      # Example
+      #
+      #   angel_list_icon = FullContact.get_social_icon_url('angellist','16','default')
+      #   # 'angel_list_icon' contains url of the icon
+      #
+      # Returns url to the specified social media icon
+      def get_social_icon_url(type_id = 'facebook', size = '32', style = 'default')
+        self.format = ''
+        url = '/' + type_id + '/' + size + '/' + style
+        response = get('icon' + url, {}, true)
+        response.env[:response_headers]['location']
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/fullcontact/client/name.rb

@@ -0,0 +1,167 @@
+module FullContact
+  class Client
+    # Public: Various methods related to name of the person
+    module Name
+      # Public: Takes quasi structured name data provided as a string and
+      # outputs the data in a structured manner.
+      #
+      # query - Query parameter allows you to pass a quasi-structured full
+      #         name String which can include standard prefix, first name,
+      #         nickname, middle name, last name and suffix. 
+      #
+      # Example
+      #
+      #   normalized = FullContact.normalize('John Smith')
+      #   # 'normalized' contains normalized contact
+      #
+      # Returns normalized contact
+      def normalize(query)
+        options = {:q => query}
+        get('name/normalizer', options)
+      end
+      
+      # Public: Attempts to deduce a structured name from email address. 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.
+      #
+      # email - email parameter allows to pass an email address as String
+      #
+      # Example
+      #
+      #   deduced = FullContact.deduce_by_email('johndsmith79@business.com')
+      #   # 'deduced' contains deduced contact
+      #
+      # Returns deduced contact
+      def deduce_by_email(email)
+        options = {:email => email}
+        get('name/deducer', options)
+      end
+      
+      # Public: Attempts to deduce a structured name from username. It
+      # also returns a likelihood based on US population data.
+      #
+      # email - username parameter allows to pass username as String
+      #
+      # Example
+      #
+      #   deduced = FullContact.deduce_by_username('johndsmith79')
+      #   # 'deduced' contains deduced contact
+      #
+      # Returns deduced contact
+      def deduce_by_username(username)
+        options = {:username => username}
+        get('name/deducer', options)
+      end
+      
+      # Public: The Name Similarity endpoint compares two names, given as the
+      # parameters q1 and q2, 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. 
+      #
+      # name_one - String first name to compare
+      # name_two - String second name to compare
+      #
+      # Example
+      #
+      #   similarity = FullContact.similarity('john','johnathan')
+      #   # 'normalized' contains similarity of contact
+      #
+      # Returns similarity in the contact
+      def similarity(name_one, name_two)
+        options = {
+          :q1 => name_one,
+          :q2 => name_two
+        }
+        get('name/similarity', options)
+      end
+      
+      # Public: The method can be used when you only know a single name and
+      # you are uncertain whether it is the given name or family name. 
+      #
+      # name - String first name or last name of person about which you are
+      #        uncertain.
+      #
+      # Example
+      #
+      #   stats = FullContact.stats_by_name('John')
+      #   # 'stats' contains stats about the contact
+      #
+      # Returns stats about the contact
+      def stats_by_name(name)
+        options = {:name => name}
+        get('name/stats', options)
+      end
+      
+      
+      # Public: The method can be used when you know that the name is a given name (first name).
+      #
+      # given_name - String parameter allows to pass given_name of the person
+      #
+      # Example
+      #
+      #   stats = FullContact.stats_by_given_name('john')
+      #   # 'stats' contains stats about the contact
+      #
+      # Returns stats about the contact
+      def stats_by_given_name(given_name)
+        options = {:givenName => given_name}
+        get('name/stats', options)
+      end
+      
+      # Public: The method can be used when you know that the name is a family
+      # name (last name). 
+      #
+      # family_name - String family name of the person
+      #
+      # Example
+      #
+      #   stats = FullContact.stats_by_family_name('smith')
+      #   # 'stats' contains stats about the contact
+      #
+      # Returns stats about the contact
+      def stats_by_family_name(family_name)
+        options = {:familyName => family_name}
+        get('name/stats', options)
+      end
+      
+      # Public: The method can be use when you know both first name and last
+      # name of the person
+      #
+      # given_name  - String first name of the person
+      # family_name - String last name of the person
+      #
+      # Example
+      #
+      #   stats = FullContact.stats_by_given_and_family_name('john', 'smith')
+      #   # 'stats' contains stats about the contact
+      #
+      # Returns stats about the contact
+      def stats_by_given_and_family_name(given_name, family_name)
+        options = {
+          :givenName => given_name,
+          :familyName => family_name
+        }
+        get('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.
+      #
+      # name - String name parameter allows you to pass an ambiguious name and
+      #        determine what the given name and family name is.  
+      #
+      # Example
+      #
+      #   parsed = FullContact.parse('Smith Jon')
+      #   # 'parsed' contains parsed contact
+      #
+      # Returns parsed contact
+      def parse(name)
+        options = {:q => name}
+        get('name/parser', options)
+      end
+      
+    end
+  end
+end

data/lib/fullcontact/client/person.rb

@@ -0,0 +1,94 @@
+module FullContact
+  class Client
+    module Person
+      # Public: Uses the person method to request more information about a specific person by email
+      #
+      # email   - The email address of the person being looked up.
+      # options - Hash containing additional arguments (optional) (default: {})
+      #           :timeOutSeconds - Wait for specified time, before returning a 202 (optional)
+      #           :queue          - Enqueue this email for indexing (optional)
+      #           :callback       - If specified, the response will be wrapped as JSONP in a function call. (optional)
+      #           :webhookUrl     - Delivers lookup response at specified url (required for webhook calls)
+      #           :webhookId      - Id for tracking the webhook
+      #
+      # Example
+      #
+      #   response = FullContact.lookup_by_email('prafulla.kiran@gmail.com')
+      def lookup_by_email(email, options = {})
+        options[:email] = email
+        get('person', options)
+      end
+
+      # Public: Uses the person method to request more information about a specific person by phone
+      #
+      # phone   - The phone number of the person being looked up.
+      # options - Hash containing additional arguments (optional) (default: {})
+      #           :timeOutSeconds - Wait for specified time, before returning a 202 (optional)
+      #           :queue          - Enqueue this email for indexing (optional)
+      #           :callback       - If specified, the response will be wrapped as JSONP in a function call. (optional)
+      #           :webhookUrl     - Delivers lookup response at specified url (required for webhook calls)
+      #           :webhookId      - Id for tracking the webhook
+      #
+      # Example
+      #
+      #   response = FullContact.lookup_by_phone('+910020000200')
+      def lookup_by_phone(phone, options = {})
+        options[:phone] = phone
+        get('person', options)
+      end
+
+      # Public: Uses the person method to request more information about a specific person by twitter
+      #
+      # twitter - The twitter handle of the person being looked up.
+      # options - Hash containing additional arguments (optional) (default: {})
+      #           :timeOutSeconds - Wait for specified time, before returning a 202 (optional)
+      #           :queue          - Enqueue this email for indexing (optional)
+      #           :callback       - If specified, the response will be wrapped as JSONP in a function call. (optional)
+      #           :webhookUrl     - Delivers lookup response at specified url (required for webhook calls)
+      #           :webhookId      - Id for tracking the webhook
+      #
+      # Example
+      #
+      #   response = FullContact.lookup_by_twitter('prafulla')
+      def lookup_by_twitter(twitter, options = {})
+        options[:twitter] = twitter
+        get('person', options)
+      end
+
+      # Public: Uses the person method to request more information about a specific person by facebook
+      #
+      # facebookUsername   - The facebook username of the person being looked up.
+      # options - Hash containing additional arguments (optional) (default: {})
+      #           :timeOutSeconds - Wait for specified time, before returning a 202 (optional)
+      #           :queue          - Enqueue this email for indexing (optional)
+      #           :callback       - If specified, the response will be wrapped as JSONP in a function call. (optional)
+      #           :webhookUrl     - Delivers lookup response at specified url (required for webhook calls)
+      #           :webhookId      - Id for tracking the webhook
+      #
+      # Example
+      #
+      #   response = FullContact.lookup_by_facebook('prafullakiran')
+      def lookup_by_facebook(facebookUsername, options = {})
+        options[:facebookUsername] = facebookUsername
+        get('person', options)
+      end
+
+      # Public: Uses the person method to request more information about a specific person by vCard
+      #
+      # vcard_data  - vcard information of the user being looked up (as a string)
+      # options     - Hash containing additional arguments (optional) (default: {})
+      #             :queue - Enqueue this email for indexing (optional)
+      #
+      # Example
+      #
+      #   response = FullContact.lookup_by_vcard(vcard_data)
+      def lookup_by_vcard(vcard_data, options = {})
+        self.format = 'vcf'
+        options[:content_type] = 'text/x-vcard'
+        options[:request_body] = vcard_data
+        post('person', options)
+      end
+
+    end
+  end
+end