hubscreen 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5fca1dbf931d9f64c4cb17b7d25f9310c2405ccf
-  data.tar.gz: 18c70a4cd24f52c3b396442c6b184f44a03aea5b
+  metadata.gz: 6466da0961fcb2137144c6b5dbda8accb5a6479d
+  data.tar.gz: 9c812e7003d7855d52db04130d2be6f8b83f2b29
 SHA512:
-  metadata.gz: d853eadb41140f1b11c363c9d714018c76cb52fdd14b32f59530460490b3b9d7cdf02771fc109136020fded4393f65371d54b96eb34a2f00a8d94573104e8afa
-  data.tar.gz: e9927f0c810be10a2220dfee7e98269b31075b23d064a21e75162ccc99def1f5edec15aaff8f1541f705c7233d95943ca6d572c857c2d86bbe781b8582c44a10
+  metadata.gz: 4afbb29d4b4775f37cec9259f0a87b99d4fa954906d9e3b9c9970812bb4ff85507a1dc7419aaf5195ca080997e9bbaf248993ddeb9b6c21489100dad8002f0ff
+  data.tar.gz: a566bcb452938d3888480eac7e86b96dcc981ce9314bb95ac0ec7f955526dad8e68e903c61c9abe5acb35507f1b44d3da8a9eddd0d14ef62acdd22e734b016a6

data/hubscreen.gemspec

@@ -40,7 +40,7 @@ Gem::Specification.new do |spec|
 
   #Gem Dependancies
   spec.add_dependency(%q<activesupport>, [">= 4"])
-  spec.add_dependency('faraday', '>= 0.8')
+  spec.add_dependency('faraday', '>= 0.9')
   spec.add_dependency('multi_json', '>= 1')
   spec.add_dependency('recursive-open-struct', '>= 1.0')
 

data/lib/hubscreen.rb

@@ -12,6 +12,7 @@ require "hubscreen/request"
 require "hubscreen/response"
 
 #Gem Lib Files
+require "hubscreen/utils"
 require "hubscreen/version"
 require "hubscreen/config"
 require "hubscreen/exceptions"

data/lib/hubscreen/api_request.rb

@@ -127,16 +127,20 @@ module Hubscreen
 
     def configure_request(request: nil, params: nil, headers: nil, body: nil)
       if request
+        request.options.params_encoder = Faraday::FlatParamsEncoder
         request.params.merge!(params) if params
         request.headers['Content-Type'] = 'application/json'
         request.headers.merge!(headers) if headers
         request.body = body if body
-        request.options.timeout = self.timeout
+        request.options.timeout = self.timeout        
       end
     end
 
+    # Note REST Client has been modified for Flat Parameter Encoding to support Hubspot's batch search functionality.
+    # This however limit's Faraday's ability to accept nested parameters
     def rest_client
       client = Faraday.new(self.api_url, proxy: self.proxy) do |faraday|
+        
         faraday.response :raise_error
         faraday.adapter adapter
         if @request_builder.debug

data/lib/hubscreen/contact.rb

@@ -6,6 +6,9 @@ module Hubscreen
   # {https://developers.hubspot.com/docs/methods/contacts/contacts-overview}
   #
   # This is a convenience object for single Hubspot contact returned by the API 
+  #
+  # This is a convenience object for handling or retrieving single Hubspot contact returned by the API 
+  # These helpers may not be updated as fast as the API. Use at your own risk
   
   class Contact < Hubscreen::Response
     CONTACT_KEYS = [:properties, 
@@ -15,6 +18,15 @@ module Hubscreen
                     :last_name,
                     :hubspot_owner_id]
 
+    CONTACT_ROOT = "v1/contact"
+    FIND_BY_VID_PATH = "#{CONTACT_ROOT}/vid" #Note full endpoint is GET /contacts/v1/contact/vid/:contact_id/profile
+    FIND_BY_EMAIL_PATH = "#{CONTACT_ROOT}/email" #Note full endpoint is GET /contacts/v1/contact/email/:contact_email/profile
+    CREATE_OR_UPDATE_PATH = '#{CONTACT_ROOT}/createOrUpdate/email' #Note full endpoint is POST /contacts/v1/contact/createOrUpdate/email/:contact_email
+    UPDATE_PATH = "#{CONTACT_ROOT}/vid" #Note full endpoint is POST /contacts/v1/contact/vid/:contact_id/profile
+    UPDATE_BATCH_PATH = "#{CONTACT_ROOT}/batch" # POST /contacts/v1/contact/batch/
+    FIND_BY_EMAIL_BATCH_PATH = "#{CONTACT_ROOT}/emails/batch" # Note full endpoint is GET /contacts/v1/contact/emails/batch/:contact_emails
+
+
     attr_accessor *CONTACT_KEYS
 
     def initialize(response)
@@ -37,6 +49,211 @@ module Hubscreen
       "<Hubscreen::Contact vid:#{@vid}, email:'#{@email}', first_name:'#{@first_name}', last_name:'#{@last_name}', company:'#{@company}', hubspot_owner_id:'#{@hubspot_owner_id}', properties:<Not Shown>, raw_response:<Not Shown>, raw_hash:<Not Shown>>"
     end
 
+    # Convenience Methods
+    class << self
+
+      # Find Contact by vid
+      # 
+      # If Hubspot cannot find the contact, will return the 404 response. Always check for a 200 status code before proceeding
+      def find(vid)
+        begin
+          Hubscreen::Request.new.contacts(FIND_BY_VID_PATH,vid).profile.get.contact
+        rescue Hubscreen::RequestError => e
+          failure_response = Response.new(e.response)
+          failure_response.status_code = e.response[:status_code]
+          return failure_response
+        end
+      end
+
+      # Find Contact by email
+      # 
+      # If Hubspot cannot find the contact, will return the 404 response. Always check for a 200 status code before proceeding
+      def find_by_email(email)
+        begin
+          Hubscreen::Request.new.contacts(FIND_BY_EMAIL_PATH,email).profile.get.contact
+        rescue Hubscreen::RequestError => e
+          failure_response = Response.new(e.response)
+          failure_response.status_code = e.response[:status_code]
+          return failure_response
+        end
+      end
+
+      # Create New Contact 
+      # 
+      # {https://developers.hubspot.com/docs/methods/contacts/create_contact}
+      #
+      # Will return a Contact object representing the new contact
+      def create!(email,properties={})
+        begin
+          params = properties.stringify_keys.merge('email' => email)
+          post_data = {properties: Hubscreen::Utils.hash_to_properties(params)}
+          Hubscreen::Request.new.contacts(CONTACT_ROOT).post(body: post_data).contact
+        rescue Hubscreen::RequestError => e
+          
+          failure_response = Response.new(e.response)
+          failure_response.status_code = e.response[:status_code]
+          return failure_response
+        end
+      end
+
+      # Update New Contact 
+      # 
+      # {https://developers.hubspot.com/docs/methods/contacts/update_contact}
+      #
+      # Will return a Contact object representing the updated contact
+      def update!(vid,properties={})
+        begin
+          params = properties.stringify_keys
+          post_data = {properties: Hubscreen::Utils.hash_to_properties(params)}
+          Hubscreen::Request.new.contacts(UPDATE_PATH,vid).profile.post(body: post_data).contact
+        rescue Hubscreen::RequestError => e
+          #binding.pry
+          failure_response = Response.new(e.response)
+          failure_response.status_code = e.response[:status_code]
+          return failure_response
+        end
+      end
+
+      # Upsert Contact  (Create or Update)
+      # 
+      # {https://developers.hubspot.com/docs/methods/contacts/create_or_update}
+      #
+      # Will return a Contact object representing the new contact
+      def upsert(email,properties={})
+        begin
+          params = properties.stringify_keys.merge('email' => email)
+          post_data = {properties: Hubscreen::Utils.hash_to_properties(params)}
+          Hubscreen::Request.new.contacts(CREATE_OR_UPDATE_PATH,email).post(body: post_data).contact
+        rescue Hubscreen::RequestError => e
+          
+          failure_response = Response.new(e.response)
+          failure_response.status_code = e.response[:status_code]
+          return failure_response
+        end
+      end
+    
+      # Batch Methods
+
+      # Create or update a group of contacts
+      #
+      # {https://developers.hubspot.com/docs/methods/contacts/batch_create_or_update}
+      #
+      # POST /contacts/v1/contact/batch/
+      #
+      # From Hubspot:
+      # Create a group of contacts or update them if they already exist. Particularly useful for periodic syncs from another contacts database to HubSpot.
+      #
+      # Performance is best when calls are limited to 100 or fewer contacts.
+      #
+      # When using this endpoint, please keep in mind that any errors with a single contact in your batch will prevent the entire batch from processing. If this happens, we'll return a 400 response with additional details as to the cause.
+      #
+      # This method only supports update by vid (vid is mandatory)
+      # To use this method, pass in a array of hashes using the following structure:
+      #
+      # [
+      #   {
+      #     vid: 5464,
+      #     firstname: "George",
+      #     lastname: "Henry"
+      #   },
+      #   {
+      #     vid: 5464,
+      #     firstname: "Codey",
+      #     lastname: "Lang"
+      #   }
+      # ]      
+      def upsert_batch_by_vid(contacts = [])
+        begin
+          params = []
+          contacts.each do |contact|
+            params << {'vid': contact[:vid],'properties': Hubscreen::Utils.hash_to_properties(contact.except(:vid).stringify_keys)}
+          end
+          post_data = params
+          Hubscreen::Request.new.contacts(UPDATE_BATCH_PATH).post(body: post_data)
+        rescue Hubscreen::RequestError => e
+          
+          failure_response = Response.new(e.response)
+          failure_response.status_code = e.response[:status_code]
+          return failure_response
+        end
+      end
+
+      # Create or update a group of contacts
+      #
+      # {https://developers.hubspot.com/docs/methods/contacts/batch_create_or_update}
+      #
+      # POST /contacts/v1/contact/batch/
+      #
+      # From Hubspot:
+      # Create a group of contacts or update them if they already exist. Particularly useful for periodic syncs from another contacts database to HubSpot.
+      #
+      # Performance is best when calls are limited to 100 or fewer contacts.
+      #
+      # When using this endpoint, please keep in mind that any errors with a single contact in your batch will prevent the entire batch from processing. If this happens, we'll return a 400 response with additional details as to the cause.
+      #
+      # This method only supports update by emails (email is manatory)
+      # DO NOT PASS VID
+      #
+      # To use this method, pass in a array of hashes using the following structure:
+      #
+      # [
+      #   {
+      #     email: "first@email.com",
+      #     firstname: "George",
+      #     lastname: "Henry"
+      #   },
+      #   {
+      #     email: "second@email.com",
+      #     firstname: "Codey",
+      #     lastname: "Lang"
+      #   }
+      # ]      
+      def upsert_batch_by_email(contacts = [])
+        begin
+          params = []
+          contacts.each do |contact|
+            params << {'email': contact[:email],'properties': Hubscreen::Utils.hash_to_properties(contact.except(:email).stringify_keys)}
+          end
+          post_data = params
+          Hubscreen::Request.new.contacts(UPDATE_BATCH_PATH).post(body: post_data)
+        rescue Hubscreen::RequestError => e
+          
+          failure_response = Response.new(e.response)
+          failure_response.status_code = e.response[:status_code]
+          return failure_response
+        end
+      end
+
+      # Search for a batch of contacts by email address
+      #
+      # {https://developers.hubspot.com/docs/methods/contacts/get_batch_by_email}
+      #
+      # GET /contacts/v1/contact/emails/batch/:contact_emails
+      #
+      # This method will return an array of Contact objects representing the search results
+      #
+      # If there is a connection error, the status code of the first element will reflect it. Always check this.
+      def find_by_emails(emails = [])
+        
+        begin
+          params = {email: emails} # Based on Faraday code >= v0.9
+          response = Hubscreen::Request.new.contacts(FIND_BY_EMAIL_BATCH_PATH).get(params: params)
+          results = []
+          response.raw_hash.each do |key,value|
+            results << new(Response.new(value))
+          end       
+          return results   
+        rescue Hubscreen::RequestError => e
+          failure_response = Response.new(e.response)
+          failure_response.status_code = e.response[:status_code]
+          return [failure_response]
+        end
+
+      end
+
+
+
+    end
 
   end
 

data/lib/hubscreen/request.rb

@@ -1,4 +1,8 @@
 module Hubscreen
+  #
+  # Primary Request Object for API Access
+  #
+  # Remember to protect all API requests with error handling to catch non 200 response codes
   class Request
     attr_accessor :api_key, :api_endpoint, :timeout, :proxy, :faraday_adapter, :debug
 

data/lib/hubscreen/response.rb

@@ -7,7 +7,7 @@ module Hubscreen
   # By default all APIRequests will return a Response object. To disable this, set Hubscreen.configure(encapsulate_response: false)
 
   class Response
-    attr_accessor :raw_hash, :raw_response
+    attr_accessor :raw_hash, :raw_response, :status_code
 
     def initialize(response_json_hash)
       @raw_hash = response_json_hash

data/lib/hubscreen/utils.rb

@@ -0,0 +1,125 @@
+# Based on [hubspot-crm gem](https://github.com/adimichele/hubspot-ruby)
+
+module Hubscreen
+  class Utils
+    class << self
+      
+      # Parses the hubspot properties format into a key-value hash
+      def properties_to_hash(props)
+        newprops = HashWithIndifferentAccess.new
+        props.each { |k, v| newprops[k] = v["value"] }
+        newprops
+      end
+
+      # Turns a hash into the hubspot properties format
+      def hash_to_properties(hash, opts = {})
+        key_name = opts[:key_name] || "property"
+        hash.map { |k, v| { key_name => k.to_s, "value" => v } }
+      end
+
+      def dump_properties(klass, hapikey=ENV['HUBSPOT_API_KEY'], filter={})
+        with_hapikey(hapikey) do
+          { 'groups'     => klass.groups({}, filter),
+            'properties' => klass.all({}, filter).select { |p| !p['hubspotDefined'] }
+          }
+        end
+      end
+
+      def restore_properties(klass, hapikey=ENV['HUPSPOT_API_KEY'], properties={}, dry_run=false)
+        existing_properties                       = dump_properties(klass, hapikey)
+        skip, new_groups, new_props, update_props = compare_property_lists(klass, properties, existing_properties)
+        puts '', 'Dry Run - Changes will not be applied' if dry_run
+        puts '','Skipping'
+        skip.each { |h| puts "#{h[:reason]} - #{h[:prop]['groupName']}:#{h[:prop]['name']}" }
+        with_hapikey(hapikey) do
+          create_groups(klass, new_groups, dry_run)
+          create_properties(klass, new_props, dry_run)
+          update_properties(klass, update_props, dry_run)
+        end
+      end
+
+      def create_groups(klass, groups, dry_run=false)
+        puts '','Creating new groups'
+        groups.each do |g|
+          if dry_run || klass.create_group!(g)
+            puts "Created: #{g['name']}"
+          else
+            puts "Failed: #{g['name']}"
+          end
+        end
+      end
+
+      def create_properties(klass, props, dry_run=false)
+        puts '','Creating new properties'
+        props.each do |p|
+          if dry_run || klass.create!(p)
+            puts "Created: #{p['groupName']}:#{p['name']}"
+          else
+            puts "Failed: #{p['groupName']}:#{p['name']}"
+          end
+        end
+      end
+
+      def update_properties(klass, props, dry_run=false)
+        puts '','Updating existing properties'
+        props.each do |p|
+          if dry_run || klass.update!(p['name'], p)
+            puts "Updated: #{p['groupName']}:#{p['name']}"
+          else
+            puts "Failed: #{p['groupName']}:#{p['name']}"
+          end
+        end
+      end
+
+      def compare_property_lists(klass, source, target)
+        skip         = [] # Array of skipped properties and the reason
+        new_groups   = Set.new # Array of groups to create
+        new_props    = [] # Array of properties to add
+        update_props = [] # Array of properties to update
+        src_groups   = source['groups']
+        dst_groups   = target['groups']
+        src_props    = source['properties']
+        dst_props    = target['properties']
+
+        src_props.each do |src|
+          group = find_by_name(src['groupName'], src_groups)
+          if src['createdUserId'].blank? && src['updatedUserId'].blank? then
+            skip << { prop: src, reason: 'Not user created' }
+          else
+            dst = find_by_name(src['name'], dst_props)
+            if dst
+              if dst['readOnlyDefinition']
+                skip << { prop: src, reason: 'Definition is read-only' }
+              elsif klass.same?(src, dst)
+                skip << { prop: src, reason: 'No change' }
+              else
+                new_groups << group unless group.blank? || find_by_name(group['name'], dst_groups)
+                update_props << src
+              end
+            else
+              new_groups << group unless group.blank? || find_by_name(group['name'], dst_groups)
+              new_props << src
+            end
+          end
+        end
+        [skip, new_groups.to_a, new_props, update_props]
+      end
+
+      def with_hapikey(hapikey)
+        begin
+          Hubspot.configure(hapikey: hapikey) unless hapikey.blank?
+          yield if block_given?
+        ensure
+          Hubspot.configure(hapikey: ENV['HUBSPOT_API_KEY']) unless hapikey.blank?
+        end
+      end
+
+      private
+
+      def find_by_name(name, set)
+        set.detect { |item| item['name'] == name }
+      end
+      
+    end
+  end
+end

data/lib/hubscreen/version.rb

@@ -1,3 +1,3 @@
 module Hubscreen
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubscreen
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Bryan Vaz
@@ -114,14 +114,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
@@ -178,6 +178,7 @@ files:
 - lib/hubscreen/exceptions.rb
 - lib/hubscreen/request.rb
 - lib/hubscreen/response.rb
+- lib/hubscreen/utils.rb
 - lib/hubscreen/version.rb
 homepage: https://github.com/bryanvaz/hubscreen
 licenses: