hubspot_v3 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d55ee9f31364c57b484162bf1e574a5412e9f207072480c51025f4b624e1bc66
-  data.tar.gz: 6ca13e0d86d8229f188d27b655453271f93e99938d78c36d14231def5bc207b5
+  metadata.gz: e0d20f6a8537ba36435a57682fc297817d8172bc6918e94a114ef8d8f0e5f1cc
+  data.tar.gz: 7c2d6829f3d59310be90b89b5393318865c8723c129f27e71431f855903ceede
 SHA512:
-  metadata.gz: 48b74f1e180b916db063dc5c3f1669d4d4bc3f1c38f64969d6bc3b73035337ea3d1e3b66ba4ab44add9b2e71cd72637645d77b5f22d86e51d195240e42521af0
-  data.tar.gz: cb09957b5b996fb56de04cce204d12dda956524c0dc4df73b5a3569c795a193648f7c9968594508d9d55dfcf9e09def66691ca4f76b2d36903045295861b773f
+  metadata.gz: bca4bf7caba1c559c41cfeba769b2c163d80f160661b5e69064c764f88496431cdd0f0397f8571653619b09355da12b4e40502f2898190e57835641a7366b3b4
+  data.tar.gz: 53359b29589e94b29d1dde13a0d6da7c716df63c0020910c32e187a403f0812f9506db43ac58b2bb7c40382cab116a517f1cba181bcb5bbcd37633151803c51d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hubspot_v3 (0.1.0)
+    hubspot_v3 (1.0.0)
       httparty (~> 0.2)
 
 GEM
@@ -11,9 +11,9 @@ GEM
     httparty (0.20.0)
       mime-types (~> 3.0)
       multi_xml (>= 0.5.2)
-    mime-types (3.3.1)
+    mime-types (3.4.1)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2021.0901)
+    mime-types-data (3.2022.0105)
     multi_xml (0.6.0)
     rake (13.0.6)
     rspec (3.10.0)
@@ -31,6 +31,7 @@ GEM
     rspec-support (3.10.2)
 
 PLATFORMS
+  arm64-darwin-21
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -1,6 +1,6 @@
 # HubspotV3
 
-Ruby gem wrapper around Hubspot API V3 
+Ruby gem wrapper around Hubspot CRM API V3
 
 Currently this gem focuses on **Batch** update/create/search of Contacts. More info in [source code](https://github.com/Pobble/hubspot_v3/blob/master/lib/hubspot_v3.rb)
 
@@ -13,7 +13,8 @@ killing those limits quite quickly.
 
 ## Other solutions out there
 
-Gem currently covers only features that are needed for our use cases, however this repo/gem is open for any Pull Requests with additional features.
+Gem currently covers only features that are needed for our use cases (CRM Contacts & Companies),
+however this repo/gem is open for any Pull Requests with additional features.
 
 If you need other features and wish not to contribute to this gem there are 2 existing Hubspot gems out there:
 
@@ -27,19 +28,29 @@ It's possible to use our gem along with  any of these two gems.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'hubspot_v3', github: 'Pobble/hubspot_v3'
+gem 'hubspot_v3', '~> 1.0'
 ```
 
+[![Gem Version](https://badge.fury.io/rb/hubspot_v3.svg)](https://badge.fury.io/rb/hubspot_v3)
+
 And then execute:
 
     $ bundle install
 
 ## Usage
 
-### set API key
+### set App Token (API key)
+
+> **NOTE**: Starting November 30, 2022, HubSpot API keys will no longer be able to be used as an
+> authentication method to access HubSpot APIs [source](https://developers.hubspot.com/changelog/upcoming-api-key-sunset)
+
+This means you cannot use Hubspot API KEY (a.k.a hapikey) to authenticate but rather create Hubspot Private App and use it's auth token
+ ([how to setup Hubspot private app](https://developers.hubspot.com/docs/api/private-apps#make-api-calls-with-your-app-s-access-token))
+
 
 ```
-HubspotV3.config.apikey = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+# Hubspot private app token (It's not the same as API KEY)
+HubspotV3.config.token = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
 ```
 
 ### Contacts - Search
@@ -184,6 +195,121 @@ bodyhash = {
 HubspotV3.contacts_update(bodyhash)
 ```
 
+### Companies - Search
+
+```
+bodyhash = {
+  "filterGroups":[
+    {
+      "filters": [
+        {
+          "propertyName": "name",
+          "operator": "EQ",
+          "value": "ACME Company"
+        }
+      ]
+    }
+  ]
+}
+HubspotV3.companies_search(bodyhash)
+```
+
+### Companies - Search by id
+
+```
+HubspotV3.companies_search_by_ids(['9582682125'])
+#=> [
+#  {
+#    "id"=>"9582682125",
+#    "properties"=> {
+#      "createdate"=>"2022-09-13T15:06:03.116Z",
+#      "domain"=>nil,
+#      "hs_lastmodifieddate"=>"2022-09-13T15:20:48.331Z",
+#      "hs_object_id"=>"9582682125",
+#      "name"=>"ACME Company"},
+#    "createdAt"=>"2022-09-13T15:06:03.116Z",
+#    "updatedAt"=>"2022-09-13T15:20:48.331Z",
+#    "archived"=>false
+#  }
+#]
+
+HubspotV3.companies_search_by_ids(['66666'])
+#=> []
+
+```
+
+
+* Full list of search filters and operators can be found in [official hubspot docs](https://developers.hubspot.com/docs/api/crm/companies)
+
+### Companies - Batch Create
+
+```
+bodyhash = {
+  "inputs": [
+    {
+      "properties": {
+        "name": "ACME Corporation"
+      }
+    },
+    {
+      "city": "Cambridge",
+      "domain": "biglytics.net",
+      "industry": "Technology",
+      "name": "Biglytics",
+      "phone": "(877) 929-0687",
+      "state": "Massachusetts"
+    }
+  ]
+}
+
+begin
+  HubspotV3.companies_create(bodyhash)
+rescue HubspotV3::RequestFailedError => e
+  puts e.message
+  # => 409 - some error reason (I never encounterd an error when creating company)
+
+  httparty_response_object = e.httparty_response
+  # =>  #<HTTParty::Response:0x1d920 parsed_response={"status"=>"error"...
+end
+```
+
+return value:
+
+```
+[
+  {
+    "id"=>"9674616673",
+    "properties"=> {
+      ...
+    }
+    ...
+  },
+  {
+    "id"=>"9674616674",
+    "properties"=> {
+      ...
+    }
+    ...
+  }
+]
+```
+
+### Companies - Batch Update
+
+```
+bodyhash = {
+  "inputs": [
+    {
+      "id": "9582682125",
+      "properties": {
+        "name": "ACME Company"
+      }
+    }
+  ]
+}
+HubspotV3.companies_update(bodyhash)
+```
+
 ## Test your app
 
 You can use http interceptor like [webmock](https://github.com/bblimke/webmock), [vcr](https://github.com/vcr/vcr).
@@ -197,13 +323,15 @@ require 'hubspot_v3/mock_contract'
 HubspotV3::MockContract.contacts_search_by_emails(["hello@pobble.com", "notfound@pobble.com", "info@pobble.com"])
 # [
 #   {
-#     "id" => 1589, "properties" => {
+#     "id" => 1589,
+#     "properties" => {
 #       "email"=>"hello@pobble.com",
 #       ...
 #     }
 #   },
-    {
-#    "id" => 1485, "properties" => {
+#   {
+#    "id" => 1485,
+#    "properties" => {
 #       "email"=>"info@pobble.com",
 #       ...
 #       }
@@ -214,11 +342,32 @@ HubspotV3::MockContract.contacts_search_by_emails_mapped(["hello@pobble.com", "n
 # => ["hello@pobble.com", "info@pobble.com"]
 ```
 
-`id` field of test Contact contracts is calculated as `'info@pobble.com'.bytes.sum == 1485`, create contacts will be `'info@pobble.com'.bytes.sum + 1_000_000 == 1001485`
+`id` field of test Contact contracts is calculated as `'info@pobble.com'.bytes.sum == 1485` ([source](https://github.com/Pobble/hubspot_v3/blob/master/lib/hubspot_v3/mock_contract.rb#L181)), create contacts will be `'info@pobble.com'.bytes.sum + 1_000_000 == 1001485` ([source](https://github.com/Pobble/hubspot_v3/blob/master/lib/hubspot_v3/mock_contract.rb#L29))
 
 > More info on how to use [Contract tests](https://blog.eq8.eu/article/explicit-contracts-for-rails-http-api-usecase.html)
 
+## Troubleshooting
+
+#### Error - Cannot deserialize value of type
+```
+`post': 400 - Invalid input JSON on line 1, column 1: Cannot deserialize value of type `com.hubspot.apiutils.core.models.batch.BatchInput$Json<com.hubspot.inbounddb.publicobject.core.v2.SimplePublicObjectBatchInput>` from Array value (token `JsonToken.START_ARRAY`) (HubspotV3::RequestFailedError)
+```
+
+You probably forgot to wrap your batch call  body hash  in `inputs`.
+
+E.g.:
+
+instead of
+
+```
+HubspotV3.companies_update([{"id"=>"1234", "properties"=> {"city" => "Cambridge"}}])
+```
+
+you need to do:
 
+```
+HubspotV3.companies_update("inputs" => [{"id"=>"1234", "properties"=> {"city" => "Cambridge"}}])
+```
 
 ## Development
 

data/hubspot_v3.gemspec

@@ -6,10 +6,10 @@ Gem::Specification.new do |spec|
   spec.name          = "hubspot_v3"
   spec.version       = HubspotV3::VERSION
   spec.authors       = ["Tomas Valent"]
-  spec.email         = ["equivalent@eq8.eu"]
+  spec.email         = ["tomas.valent@gmail.com"]
 
-  spec.summary       = "Hubspot API v3 Ruby gem"
-  spec.description   = "Ruby wrapper around Hubspot API v3 with simple implementation and batch endpoints support"
+  spec.summary       = "Hubspot CRM API (v3) Ruby gem"
+  spec.description   = "Ruby wrapper around Hubspot CRM API v3 with simple implementation around batch endpoints and private apps token support"
   spec.homepage      = "https://github.com/Pobble/hubspot_v3"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")

data/lib/hubspot_v3/config.rb

@@ -1,9 +1,15 @@
 module HubspotV3
   class Config
-    attr_writer :apikey, :contract
+    attr_writer :token, :contract
 
-    def apikey
-      @apikey || raise('Hubspot API key is not set. Set it with HubspotV3.config.apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"')
+    def token
+      @token || raise('Hubspot API key is not set. Set it with HubspotV3.config.token="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"')
+    end
+
+    def apikey=(*)
+      raise 'Hubspot API keys are deprecated. Don\'t use HubspotV3.config.apikey="hubspotApiKeyNoLongerWorks".' +
+       ' Make sure you set up Hubspot private app and set the token for this gem' +
+       ' with HubspotV3.config.token="xxMyHubspotPrivateAppTokenxx"'
     end
   end
 

data/lib/hubspot_v3/mock_contract.rb

@@ -83,8 +83,103 @@ module HubspotV3
       HubspotV3::Helpers.map_search_by_email(contacts_search_by_emails(emails_ary))
     end
 
-    def _calculate_id(email)
-      email.bytes.sum  # sum of asci values of the email string
+    def contacts_search(bodyhash)
+      puts _general_batch_search_should_be_overridden_msg('contacts_search')
+      raise "HubspotV3::MockContract.contacts_search should be stubbed or overridden"
+    end
+
+    def companies_create(bodyhash)
+      inputs = _fetch_inputs(bodyhash)
+      inputs.map do |input|
+        properties = _fetch_input_properties(input)
+
+        #note: Hubspot API doesn't really require name, but for sake of this
+        # contract functionality we need properties.name
+        name = properties.fetch('name') { raise KeyError.new("Item in Inputs hash must contain key 'properties.name' - hash['inputs'][0]['properties']['name']") }
+
+        id = _calculate_id(name) + 1_000_000
+
+        default_properties = {
+          "createdate"=>"2022-09-13T15:06:03.116Z",
+          "hs_lastmodifieddate"=>"2022-09-13T15:06:03.116Z",
+          "hs_object_id"=>id.to_s,
+          "hs_pipeline"=>"companies-lifecycle-pipeline",
+          "lifecyclestage"=>"lead",
+          "name"=>name
+        }
+
+        properties = default_properties.merge(properties)
+
+        {
+          "id"=>id.to_s,
+          "properties"=> properties,
+          "createdAt"=>"2022-09-13T15:06:03.116Z",
+          "updatedAt"=>"2022-09-13T15:06:03.116Z",
+          "archived"=>false
+        }
+      end
+    end
+
+    def companies_update(bodyhash)
+      inputs = _fetch_inputs(bodyhash)
+
+      inputs.map do |input|
+        id = _fetch_input_id(input)
+        properties = _fetch_input_properties(input)
+
+        default_properties = {
+          "hs_lastmodifieddate"=>"2022-09-13T15:06:33.116Z",
+          "createdate"=>"2022-09-13T15:06:03.116Z",
+          "hs_object_id"=>id.to_s,
+          "hs_pipeline"=>"companies-lifecycle-pipeline",
+          "lifecyclestage"=>"lead"
+        }
+        properties = default_properties.merge(properties)
+
+        {
+          "id"=>id.to_s,
+          "properties"=>properties,
+          "createdAt"=>"2022-09-13T15:06:03.116Z",
+          "updatedAt"=>"2022-09-13T15:06:33.116Z",
+          "archived"=>false
+        }
+      end
+    end
+
+    def companies_search_by_ids(ids)
+      raise 'argument must be an Array' unless ids.is_a?(Array)
+      raise 'Array must include only String ids' if ids.select { |x| ! x.is_a?(String) }.any?
+
+      resp = ids.map do |id|
+        if id.match(/666666/)
+          # this represents not found records
+          nil
+        else
+          {
+            "id"=>id,
+            "properties"=>{
+              "createdate"=>"2022-09-13T15:06:03.116Z",
+              "domain"=>nil,
+              "hs_lastmodifieddate"=>"2022-09-13T15:20:48.331Z",
+              "hs_object_id"=>id,
+              "name"=>"ACME Company #{id}"},
+            "createdAt"=>"2022-09-13T15:06:03.116Z",
+            "updatedAt"=>"2022-09-13T15:20:48.331Z",
+            "archived"=>false
+          }
+        end
+      end
+
+      resp.compact
+    end
+
+    def companies_search(*)
+      puts _general_batch_search_should_be_overridden_msg('companies_search')
+      raise "HubspotV3::MockContract.companies_search should be stubbed or overridden"
+    end
+
+    def _calculate_id(whatever)
+      whatever.bytes.sum  # sum of asci values of the email string
     end
 
     def _sanitize_email_as_hubspot_would(email)
@@ -103,5 +198,13 @@ module HubspotV3
     def _fetch_input_id(input)
       input.fetch('id') { raise KeyError.new("Item in Inputs hash must contain key 'id' - hash['inputs'][0]['id']") }
     end
+
+    def _general_batch_search_should_be_overridden_msg(name)
+      "General search queries are not covered by test contract and should be customly" +
+      "\noverridden based on your usecase.  E.g.:" +
+      "\n    expect(HubspotV3::MockContract)" +
+      "\n      .to receive(:#{name})" +
+      "\n      .and_return([{'id'=>'12345', 'properties'=>{  }])\n\n"
+    end
   end
 end

data/lib/hubspot_v3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HubspotV3
-  VERSION = "0.1.0"
+  VERSION = "1.1.0"
 end

data/lib/hubspot_v3.rb

@@ -15,10 +15,15 @@ module HubspotV3
     end
   end
 
+  HubspotRequestLimitReached = Class.new(RequestFailedError)
+
   API_URL='https://api.hubapi.com'
   CONTACTS_SEARCH='/crm/v3/objects/contacts/search'
   CONTACTS_CREATE='/crm/v3/objects/contacts/batch/create'
   CONTACTS_UPDATE='/crm/v3/objects/contacts/batch/update'
+  COMPANIES_SEARCH='/crm/v3/objects/companies/search'
+  COMPANIES_CREATE='/crm/v3/objects/companies/batch/create'
+  COMPANIES_UPDATE='/crm/v3/objects/companies/batch/update'
 
   def self.contacts_create(bodyhash)
     post(CONTACTS_CREATE, bodyhash)
@@ -53,20 +58,79 @@ module HubspotV3
     HubspotV3::Helpers.map_search_by_email(contacts_search_by_emails(emails_ary))
   end
 
+  def self.companies_create(bodyhash)
+    post(COMPANIES_CREATE, bodyhash)
+  end
+
+  def self.companies_update(bodyhash)
+    post(COMPANIES_UPDATE, bodyhash)
+  end
+
+  def self.companies_search(bodyhash)
+    post(COMPANIES_SEARCH, bodyhash)
+  end
+
+  def self.companies_search_by_ids(hubspot_object_ids_ary)
+    filters_group_ary = hubspot_object_ids_ary.map do |e|
+      {
+        "filters": [
+          {
+            "propertyName": "hs_object_id",
+            "operator": "EQ",
+            "value": e
+          }
+        ]
+      }
+    end
+
+    bodyhash = { "filterGroups": filters_group_ary }
+    companies_search(bodyhash)
+  end
+
   def self.url(path)
-    "#{API_URL}#{path}?hapikey=#{config.apikey}"
+    "#{API_URL}#{path}"
   end
 
   def self.post(path, bodyhash)
-    res = HTTParty.post(url(path), {
+    httparty_response = HTTParty.post(url(path), {
       body: bodyhash.to_json,
-      headers: {'Content-Type' => 'application/json'}
+      headers: headers
     })
-    case res.code
+    case httparty_response.code
     when 200, 201
-      res.parsed_response['results']
+      httparty_response.parsed_response['results']
+    when 429
+      # Hubspot error 429 - You have reached your secondly limit.
+      raise _hubspot_request_limit_reached_error(httparty_response)
+    when 500
+      if httparty_response.parsed_response["category"] == "RATE_LIMITS"
+        # e.g.: {"status":"error","message":"You have reached your secondly limit.","category":"RATE_LIMITS"}
+        # Yes, Hubspot will sometimes give 429 or 500 when limit reached
+        raise _hubspot_request_limit_reached_error(httparty_response)
+      else
+        raise _hubspot_request_failed_error(httparty_response)
+      end
     else
-      raise HubspotV3::RequestFailedError.new("#{res.code} - #{res.parsed_response['message']}", res)
+      raise _hubspot_request_failed_error(httparty_response)
     end
   end
+
+  def self.headers
+    {
+      'Content-Type' => 'application/json',
+      'Authorization': "Bearer #{config.token}"
+    }
+  end
+
+  def self._hubspot_request_limit_reached_error(httparty_response)
+    code = httparty_response.code
+    message = httparty_response.parsed_response['message']
+    HubspotV3::HubspotRequestLimitReached.new("#{code} - #{message}", httparty_response)
+  end
+
+  def self._hubspot_request_failed_error(httparty_response)
+    code = httparty_response.code
+    message = httparty_response.parsed_response['message']
+    HubspotV3::RequestFailedError.new("#{code} - #{message}", httparty_response)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hubspot_v3
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Tomas Valent
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-27 00:00:00.000000000 Z
+date: 2022-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -24,10 +24,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
-description: Ruby wrapper around Hubspot API v3 with simple implementation and batch
-  endpoints support
+description: Ruby wrapper around Hubspot CRM API v3 with simple implementation around
+  batch endpoints and private apps token support
 email:
-- equivalent@eq8.eu
+- tomas.valent@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -72,5 +72,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: Hubspot API v3 Ruby gem
+summary: Hubspot CRM API (v3) Ruby gem
 test_files: []