hubspot-api-ruby 0.8.0

data/lib/hubspot/contact.rb

@@ -0,0 +1,110 @@
+class Hubspot::Contact < Hubspot::Resource
+  self.id_field = "vid"
+  self.update_method = "post"
+
+  ALL_PATH                = '/contacts/v1/lists/all/contacts/all'
+  CREATE_PATH             = '/contacts/v1/contact'
+  CREATE_OR_UPDATE_PATH   = '/contacts/v1/contact/createOrUpdate/email/:email'
+  DELETE_PATH             = '/contacts/v1/contact/vid/:id'
+  FIND_PATH               = '/contacts/v1/contact/vid/:id/profile'
+  FIND_BY_EMAIL_PATH      = '/contacts/v1/contact/email/:email/profile'
+  FIND_BY_USER_TOKEN_PATH = '/contacts/v1/contact/utk/:token/profile'
+  MERGE_PATH              = '/contacts/v1/contact/merge-vids/:id/'
+  SEARCH_PATH             = '/contacts/v1/search/query'
+  UPDATE_PATH             = '/contacts/v1/contact/vid/:id/profile'
+  UPDATE_PATH             = '/contacts/v1/contact/vid/:id/profile'
+  BATCH_UPDATE_PATH       = '/contacts/v1/contact/batch'
+
+  class << self
+    def all(opts = {})
+      Hubspot::PagedCollection.new(opts) do |options, offset, limit|
+        response = Hubspot::Connection.get_json(
+          ALL_PATH,
+          options.merge("count" => limit, "vidOffset" => offset)
+          )
+
+        contacts = response["contacts"].map { |result| from_result(result) }
+        [contacts, response["vid-offset"], response["has-more"]]
+      end
+    end
+
+    def find_by_email(email)
+      response = Hubspot::Connection.get_json(FIND_BY_EMAIL_PATH, email: email)
+      from_result(response)
+    end
+
+    def find_by_user_token(token)
+      response = Hubspot::Connection.get_json(FIND_BY_USER_TOKEN_PATH, token: token)
+      from_result(response)
+    end
+    alias_method :find_by_utk, :find_by_user_token
+
+    def create(email, properties = {})
+      super(properties.merge("email" => email))
+    end
+
+    def create_or_update(email, properties = {})
+      request = {
+        properties: Hubspot::Utils.hash_to_properties(properties.stringify_keys, key_name: "property")
+      }
+      response = Hubspot::Connection.post_json(CREATE_OR_UPDATE_PATH, params: {email: email}, body: request)
+      from_result(response)
+    end
+
+    def search(query, opts = {})
+      Hubspot::PagedCollection.new(opts) do |options, offset, limit|
+        response = Hubspot::Connection.get_json(
+          SEARCH_PATH,
+          options.merge(q: query, offset: offset, count: limit)
+          )
+
+        contacts = response["contacts"].map { |result| from_result(result) }
+        [contacts, response["offset"], response["has-more"]]
+      end
+    end
+
+    def merge(primary, secondary)
+      Hubspot::Connection.post_json(
+        MERGE_PATH,
+        params: { id: primary.to_i, no_parse: true },
+        body: { "vidToMerge" => secondary.to_i }
+        )
+
+      true
+    end
+    
+    def batch_update(contacts, opts = {})
+      request = contacts.map do |contact|
+        # Use the specified options or update with the changes
+        changes = opts.empty? ? contact.changes : opts
+
+        unless changes.empty?
+          {
+            "vid" => contact.id,
+            "properties" => changes.map { |k, v| { "property" => k, "value" => v } }
+          }
+        end
+      end
+
+      # Remove any objects without changes and return if there is nothing to update
+      request.compact!
+      return true if request.empty?
+
+      Hubspot::Connection.post_json(
+        BATCH_UPDATE_PATH,
+        params: {},
+        body: request
+      )
+
+      true
+    end
+  end
+
+  def name
+    [firstname, lastname].compact.join(' ')
+  end
+
+  def merge(contact)
+    self.class.merge(@id, contact.to_i)
+  end
+end

data/lib/hubspot/contact_list.rb

@@ -0,0 +1,129 @@
+module Hubspot
+  #
+  # HubSpot Contact lists API
+  #
+  class ContactList
+    LISTS_PATH           = '/contacts/v1/lists'
+    LIST_PATH            = '/contacts/v1/lists/:list_id'
+    LIST_BATCH_PATH      = LISTS_PATH + '/batch'
+    CONTACTS_PATH        = LIST_PATH + '/contacts/all'
+    RECENT_CONTACTS_PATH = LIST_PATH + '/contacts/recent'
+    ADD_CONTACT_PATH     = LIST_PATH + '/add'
+    REMOVE_CONTACT_PATH  = LIST_PATH + '/remove'
+    REFRESH_PATH         = LIST_PATH + '/refresh'
+
+    class << self
+      # {http://developers.hubspot.com/docs/methods/lists/create_list}
+      def create!(opts={})
+        dynamic = opts.delete(:dynamic) { false }
+        portal_id = opts.delete(:portal_id) { Hubspot::Config.portal_id }
+
+        response = Hubspot::Connection.post_json(LISTS_PATH, params: {}, body: opts.merge({ dynamic: dynamic, portal_id: portal_id}) )
+        new(response)
+      end
+
+      # {http://developers.hubspot.com/docs/methods/lists/get_lists}
+      # {http://developers.hubspot.com/docs/methods/lists/get_static_lists}
+      # {http://developers.hubspot.com/docs/methods/lists/get_dynamic_lists}
+      def all(opts={})
+        static = opts.delete(:static) { false }
+        dynamic = opts.delete(:dynamic) { false }
+
+        # NOTE: As opposed of what the documentation says, getting the static or dynamic lists returns all the lists, not only 20 lists
+        path = LISTS_PATH + (static ? '/static' : dynamic ? '/dynamic' : '')
+        response = Hubspot::Connection.get_json(path, opts)
+        response['lists'].map { |l| new(l) }
+      end
+
+      # {http://developers.hubspot.com/docs/methods/lists/get_list}
+      # {http://developers.hubspot.com/docs/methods/lists/get_batch_lists}
+      def find(ids)
+        batch_mode, path, params = case ids
+        when Integer then [false, LIST_PATH, { list_id: ids }]
+        when String then [false, LIST_PATH, { list_id: ids.to_i }]
+        when Array then [true, LIST_BATCH_PATH, { batch_list_id: ids.map(&:to_i) }]
+        else raise Hubspot::InvalidParams, 'expecting Integer or Array of Integers parameter'
+        end
+
+        response = Hubspot::Connection.get_json(path, params)
+        batch_mode ? response['lists'].map { |l| new(l) } : new(response)
+      end
+    end
+
+    attr_reader :id
+    attr_reader :portal_id
+    attr_reader :name
+    attr_reader :dynamic
+    attr_reader :properties
+
+    def initialize(hash)
+      self.send(:assign_properties, hash)
+    end
+
+    # {http://developers.hubspot.com/docs/methods/lists/update_list}
+    def update!(opts={})
+      response = Hubspot::Connection.post_json(LIST_PATH, params: { list_id: @id }, body: opts)
+      self.send(:assign_properties, response)
+      self
+    end
+
+    # {http://developers.hubspot.com/docs/methods/lists/delete_list}
+    def destroy!
+      response = Hubspot::Connection.delete_json(LIST_PATH, { list_id: @id })
+      @destroyed = (response.code == 204)
+    end
+
+    # {http://developers.hubspot.com/docs/methods/lists/get_list_contacts}
+    def contacts(opts={})
+      # NOTE: caching functionality can be dependant of the nature of the list, if dynamic or not ...
+      bypass_cache = opts.delete(:bypass_cache) { false }
+      recent = opts.delete(:recent) { false }
+      paged = opts.delete(:paged) { false }
+
+      if bypass_cache || @contacts.nil?
+        path = recent ? RECENT_CONTACTS_PATH : CONTACTS_PATH
+        opts[:list_id] = @id
+
+        response = Hubspot::Connection.get_json(path, Hubspot::ContactProperties.add_default_parameters(opts))
+        @contacts = response['contacts'].map! { |c| Hubspot::Contact.from_result(c) }
+        paged ? response : @contacts
+      else
+        @contacts
+      end
+    end
+
+    # {http://developers.hubspot.com/docs/methods/lists/refresh_list}
+    def refresh
+      response = Hubspot::Connection.post_json(REFRESH_PATH, params: { list_id: @id, no_parse: true }, body: {})
+      response.code == 204
+    end
+
+    # {http://developers.hubspot.com/docs/methods/lists/add_contact_to_list}
+    def add(contacts)
+      contact_ids = [contacts].flatten.uniq.compact.map(&:id)
+      response = Hubspot::Connection.post_json(ADD_CONTACT_PATH, params: { list_id: @id }, body: { vids: contact_ids })
+      response['updated'].sort == contact_ids.sort
+    end
+
+    # {http://developers.hubspot.com/docs/methods/lists/remove_contact_from_list}
+    def remove(contacts)
+      contact_ids = [contacts].flatten.uniq.compact.map(&:id)
+      response = Hubspot::Connection.post_json(REMOVE_CONTACT_PATH, params: { list_id: @id }, body: { vids: contact_ids })
+      response['updated'].sort == contact_ids.sort
+    end
+
+    def destroyed?
+      !!@destroyed
+    end
+
+    private
+
+    def assign_properties(hash)
+      @id = hash['listId']
+      @portal_id = hash['portalId']
+      @name = hash['name']
+      @dynamic = hash['dynamic']
+      @properties = hash
+    end
+  end
+end

data/lib/hubspot/contact_properties.rb

@@ -0,0 +1,59 @@
+module Hubspot
+  class ContactProperties < Properties
+
+    ALL_PROPERTIES_PATH  = "/properties/v1/contacts/properties"
+    ALL_GROUPS_PATH      = "/properties/v1/contacts/groups"
+    CREATE_PROPERTY_PATH = "/properties/v1/contacts/properties"
+    UPDATE_PROPERTY_PATH = "/properties/v1/contacts/properties/named/:property_name"
+    DELETE_PROPERTY_PATH = "/properties/v1/contacts/properties/named/:property_name"
+    CREATE_GROUP_PATH    = "/properties/v1/contacts/groups"
+    UPDATE_GROUP_PATH    = "/properties/v1/contacts/groups/named/:group_name"
+    DELETE_GROUP_PATH    = "/properties/v1/contacts/groups/named/:group_name"
+
+    class << self
+      def add_default_parameters(opts={})
+        superclass.add_default_parameters(opts)
+      end
+
+      def all(opts={}, filter={})
+        superclass.all(ALL_PROPERTIES_PATH, opts, filter)
+      end
+
+      def groups(opts={}, filter={})
+        superclass.groups(ALL_GROUPS_PATH, opts, filter)
+      end
+
+      def create!(params={})
+        superclass.create!(CREATE_PROPERTY_PATH, params)
+      end
+
+      def update!(property_name, params={})
+        superclass.update!(UPDATE_PROPERTY_PATH, property_name, params)
+      end
+
+      def delete!(property_name)
+        superclass.delete!(DELETE_PROPERTY_PATH, property_name)
+      end
+
+      def create_group!(params={})
+        superclass.create_group!(CREATE_GROUP_PATH, params)
+      end
+
+      def update_group!(group_name, params={})
+        superclass.update_group!(UPDATE_GROUP_PATH, group_name, params)
+      end
+
+      def delete_group!(group_name)
+        superclass.delete_group!(DELETE_GROUP_PATH, group_name)
+      end
+
+      def same?(src, dst)
+        superclass.same?(src, dst)
+      end
+
+      def valid_params(params)
+        superclass.valid_params(params)
+      end
+    end
+  end
+end

data/lib/hubspot/deal.rb

@@ -0,0 +1,173 @@
+require 'hubspot/utils'
+
+module Hubspot
+  #
+  # HubSpot Deals API
+  #
+  # {http://developers.hubspot.com/docs/methods/deals/deals_overview}
+  #
+  class Deal
+    ALL_DEALS_PATH = "/deals/v1/deal/paged"
+    CREATE_DEAL_PATH = "/deals/v1/deal"
+    DEAL_PATH = "/deals/v1/deal/:deal_id"
+    RECENT_UPDATED_PATH = "/deals/v1/deal/recent/modified"
+    UPDATE_DEAL_PATH = '/deals/v1/deal/:deal_id'
+    ASSOCIATE_DEAL_PATH = '/deals/v1/deal/:deal_id/associations/:OBJECTTYPE?id=:objectId'
+    ASSOCIATED_DEAL_PATH = "/deals/v1/deal/associated/:objectType/:objectId"
+
+    attr_reader :properties
+    attr_reader :portal_id
+    attr_reader :deal_id
+    attr_reader :company_ids
+    attr_reader :vids
+
+    def initialize(response_hash)
+      @portal_id = response_hash["portalId"]
+      @deal_id = response_hash["dealId"]
+      @company_ids = response_hash["associations"]["associatedCompanyIds"]
+      @vids = response_hash["associations"]["associatedVids"]
+      @properties = Hubspot::Utils.properties_to_hash(response_hash["properties"])
+    end
+
+    class << self
+      def create!(portal_id, company_ids, vids, params={})
+        #TODO: clean following hash, Hubspot::Utils should do the trick
+        associations_hash = {"portalId" => portal_id, "associations" => { "associatedCompanyIds" => company_ids, "associatedVids" => vids}}
+        post_data = associations_hash.merge({ properties: Hubspot::Utils.hash_to_properties(params, key_name: "name") })
+
+        response = Hubspot::Connection.post_json(CREATE_DEAL_PATH, params: {}, body: post_data )
+        new(response)
+      end
+
+      # Updates the properties of a deal
+      # {http://developers.hubspot.com/docs/methods/deals/update_deal}
+      # @param deal_id [Integer] hubspot deal_id
+      # @param params [Hash] hash of properties to update
+      # @return [boolean] success
+      def update(id, properties = {})
+        update!(id, properties)
+      rescue Hubspot::RequestError => e
+        false
+      end
+
+      # Updates the properties of a deal
+      # {http://developers.hubspot.com/docs/methods/deals/update_deal}
+      # @param deal_id [Integer] hubspot deal_id
+      # @param params [Hash] hash of properties to update
+      # @return [Hubspot::Deal] Deal record
+      def update!(id, properties = {})
+        request = { properties: Hubspot::Utils.hash_to_properties(properties.stringify_keys, key_name: 'name') }
+        response = Hubspot::Connection.put_json(UPDATE_DEAL_PATH, params: { deal_id: id, no_parse: true }, body: request)
+        response.success?
+      end
+
+       # Associate a deal with a contact or company
+       # {http://developers.hubspot.com/docs/methods/deals/associate_deal}
+       # Usage
+       # Hubspot::Deal.associate!(45146940, [], [52])
+       def associate!(deal_id, company_ids=[], vids=[])
+         objecttype = company_ids.any? ? 'COMPANY' : 'CONTACT'
+         object_ids = (company_ids.any? ? company_ids : vids).join('&id=')
+         Hubspot::Connection.put_json(ASSOCIATE_DEAL_PATH, params: { deal_id: deal_id, OBJECTTYPE: objecttype, objectId: object_ids}, body: {})
+       end
+
+       # Didssociate a deal with a contact or company
+       # {https://developers.hubspot.com/docs/methods/deals/delete_association}
+       # Usage
+       # Hubspot::Deal.dissociate!(45146940, [], [52])
+       def dissociate!(deal_id, company_ids=[], vids=[])
+         objecttype = company_ids.any? ? 'COMPANY' : 'CONTACT'
+         object_ids = (company_ids.any? ? company_ids : vids).join('&id=')
+         Hubspot::Connection.delete_json(ASSOCIATE_DEAL_PATH, { deal_id: deal_id, OBJECTTYPE: objecttype, objectId: object_ids })
+       end
+
+      def find(deal_id)
+        response = Hubspot::Connection.get_json(DEAL_PATH, { deal_id: deal_id })
+        new(response)
+      end
+
+      def all(opts = {})
+        path = ALL_DEALS_PATH
+
+        opts[:includeAssociations] = true # Needed for initialize to work
+        response = Hubspot::Connection.get_json(path, opts)
+
+        result = {}
+        result['deals'] = response['deals'].map { |d| new(d) }
+        result['offset'] = response['offset']
+        result['hasMore'] = response['hasMore']
+        return result
+      end
+
+      # Find recent updated deals.
+      # {http://developers.hubspot.com/docs/methods/deals/get_deals_modified}
+      # @param count [Integer] the amount of deals to return.
+      # @param offset [Integer] pages back through recent contacts.
+      def recent(opts = {})
+        response = Hubspot::Connection.get_json(RECENT_UPDATED_PATH, opts)
+        response['results'].map { |d| new(d) }
+      end
+
+      # Find all deals associated to a company
+      # {http://developers.hubspot.com/docs/methods/deals/get-associated-deals}
+      # @param company [Hubspot::Company] the company
+      # @return [Array] Array of Hubspot::Deal records
+      def find_by_company(company)
+        find_by_association company
+      end
+
+      # Find all deals associated to a contact
+      # {http://developers.hubspot.com/docs/methods/deals/get-associated-deals}
+      # @param contact [Hubspot::Contact] the contact
+      # @return [Array] Array of Hubspot::Deal records
+      def find_by_contact(contact)
+        find_by_association contact
+      end
+
+      # Find all deals associated to a contact or company
+      # {http://developers.hubspot.com/docs/methods/deals/get-associated-deals}
+      # @param object [Hubspot::Contact || Hubspot::Company] a contact or company
+      # @return [Array] Array of Hubspot::Deal records
+      def find_by_association(object)
+        path = ASSOCIATED_DEAL_PATH
+        objectType =  case object
+                      when Hubspot::Company then :company
+                      when Hubspot::Contact then :contact
+                      else raise(Hubspot::InvalidParams, "Instance type not supported")
+                      end
+
+        params = { objectType: objectType, objectId: object.id }
+        response = Hubspot::Connection.get_json(path, params)
+        response["results"].map { |deal_id| find(deal_id) }
+      end
+    end
+
+    # Archives the contact in hubspot
+    # {https://developers.hubspot.com/docs/methods/contacts/delete_contact}
+    # @return [TrueClass] true
+    def destroy!
+      Hubspot::Connection.delete_json(DEAL_PATH, {deal_id: deal_id})
+      @destroyed = true
+    end
+
+    def destroyed?
+      !!@destroyed
+    end
+
+    def [](property)
+      @properties[property]
+    end
+
+    # Updates the properties of a deal
+    # {https://developers.hubspot.com/docs/methods/deals/update_deal}
+    # @param params [Hash] hash of properties to update
+    # @return [Hubspot::Deal] self
+    def update!(params)
+      query = { 'properties' => Hubspot::Utils.hash_to_properties(params.stringify_keys!, key_name: 'name') }
+      Hubspot::Connection.put_json(UPDATE_DEAL_PATH, params: { deal_id: deal_id }, body: query)
+      @properties.merge!(params)
+      self
+    end
+    alias_method :update, :update!
+  end
+end