hubspot_v3 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d55ee9f31364c57b484162bf1e574a5412e9f207072480c51025f4b624e1bc66
-  data.tar.gz: 6ca13e0d86d8229f188d27b655453271f93e99938d78c36d14231def5bc207b5
+  metadata.gz: 831c706b12ca929919b9521451a44350194678d709e200fa5be2344142248fbd
+  data.tar.gz: acc7373fdf69e5d5265c4b5288187920f3cddbc4fd4014be1ad846dcd331ce75
 SHA512:
-  metadata.gz: 48b74f1e180b916db063dc5c3f1669d4d4bc3f1c38f64969d6bc3b73035337ea3d1e3b66ba4ab44add9b2e71cd72637645d77b5f22d86e51d195240e42521af0
-  data.tar.gz: cb09957b5b996fb56de04cce204d12dda956524c0dc4df73b5a3569c795a193648f7c9968594508d9d55dfcf9e09def66691ca4f76b2d36903045295861b773f
+  metadata.gz: c44773f8b1eb6f67e7013692c0ba301ff350426c30e339ef6eb36d441d7f54176a9a5487ff3432e21bc2652758ef8a85001e96daa45a70d2b3363d7c196edc35
+  data.tar.gz: cfe059ca979b2b6153ee18c793a8fd440b714c8be7a68c8811e6ff3ce3cb77c668d61dd59d3f20c3d0370f39bac9fea816ea6c9364d5eced63f28ebb2521b1a5

data/Gemfile.lock

@@ -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:
 
@@ -36,10 +37,18 @@ And then execute:
 
 ## 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 +193,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).
@@ -218,7 +342,28 @@ HubspotV3::MockContract.contacts_search_by_emails_mapped(["hello@pobble.com", "n
 
 > 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.0.0"
 end

data/lib/hubspot_v3.rb

@@ -19,6 +19,9 @@ module HubspotV3
   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,14 +56,43 @@ 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), {
       body: bodyhash.to_json,
-      headers: {'Content-Type' => 'application/json'}
+      headers: headers
     })
     case res.code
     when 200, 201
@@ -69,4 +101,11 @@ module HubspotV3
       raise HubspotV3::RequestFailedError.new("#{res.code} - #{res.parsed_response['message']}", res)
     end
   end
+
+  def self.headers
+    {
+      'Content-Type' => 'application/json',
+      'Authorization': "Bearer #{config.token}"
+    }
+  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.0.0
 platform: ruby
 authors:
 - Tomas Valent
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-27 00:00:00.000000000 Z
+date: 2022-09-28 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: []