Refactoring resource interface into Hubspot::Resource (#176)

* WIP: Refactoring resource interface into Hubspot::Resource

* Add support for paged collections

* Add recently created and modified to company

* Add support for fetching and adding contacts to a company

* Support removing contacts from a company

* Add batch update to companies

* Replace Company with the resource implementation

* Update Contact2 with new methods

* Add FactoryBot for generating fixtures

* Rework new method and add tests for base resource class

* Lots of updates and tests for Company and Contact

* Fix delegate_missing_to to work with older activesupport versions

* Add Contact search support

* Add merge support for Contact

* Replace old Contact with new Contact resource

* Update methods to return success

* Update the README with the new resource API

Author: cbisnett

.gitignore

@@ -52,3 +52,6 @@ tmp
 
 # Ignore local environment variables
 /.env
+
+# Byebug history
+.byebug_history

README.md

@@ -108,49 +108,159 @@ At this time, OAuth tokens are configured globally rather than on a per-connecti
 
 ## Usage
 
-Here's what you can do for now:
+Classes have been created that map to Hubspot resource types and attempt to abstract away as much of the API specific details as possible. These classes generally follow the [ActiveRecord](https://en.wikipedia.org/wiki/Active_record_pattern) pattern and general Ruby conventions. Anyone familiar with [Ruby On Rails](https://rubyonrails.org/) should find this API closely maps with familiar concepts.
 
-### Create a contact
+
+### Creating a new resource
 
 ```ruby
-Hubspot::Contact.create!("email@address.com", {firstname: "First", lastname: "Last"})
+irb(main):001:0> company = Hubspot::Company.new(name: "My Company LLC.")
+=> #<Hubspot::Company:0x000055b9219cc068 @changes={"name"=>"My Company LLC."}, @properties={}, @id=nil, @persisted=false, @deleted=false>
+
+irb(main):002:0> company.persisted?
+=> false
+
+irb(main):003:0> company.save
+=> true
+
+irb(main):004:0> company.persisted?
+=> true
 ```
 
-#### In batches
+```ruby
+irb(main):001:0> company = Hubspot::Company.create(name: "Second Financial LLC.")
+=> #<Hubspot::Company:0x0000557ea7119fb0 @changes={}, @properties={"hs_lastmodifieddate"=>{"value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"CALCULATED", "sourceId"=>nil, "versions"=>[{"name"=>"hs_lastmodifieddate", "value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"CALCULATED", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}, "name"=>{"value"=>"Second Financial LLC.", "timestamp"=>1552234087467, "source"=>"API", "sourceId"=>nil, "versions"=>[{"name"=>"name", "value"=>"Second Financial LLC.", "timestamp"=>1552234087467, "source"=>"API", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}, "createdate"=>{"value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"API", "sourceId"=>nil, "versions"=>[{"name"=>"createdate", "value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"API", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}, {"name"=>"createdate", "value"=>"1552234087467", "timestamp"=>1552234087467, "sourceId"=>"API", "source"=>"API", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}}, @id=1726317857, @persisted=true, @deleted=false, @metadata={"portalId"=>62515, "companyId"=>1726317857, "isDeleted"=>false, "additionalDomains"=>[], "stateChanges"=>[], "mergeAudits"=>[]}>
+
+irb(main):002:0> company.persisted?
+=> true
+```
+
+
+### Find an existing resource
+
+**Note:** Hubspot uses a combination of different names for the "ID" property of a resource based on what type of resource it is (eg. vid for Contact). This library attempts to abstract that away and generalizes an `id` property for all resources
 
 ```ruby
-Hubspot::Contact.create_or_update!([{email: 'smith@example.com', firstname: 'First', lastname: 'Last'}])
+irb(main):001:0> company = Hubspot::Company.find(1726317857)
+=> #<Hubspot::Company:0x0000562e4988c9a8 @changes={}, @properties={"hs_lastmodifieddate"=>{"value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"CALCULATED", "sourceId"=>nil, "versions"=>[{"name"=>"hs_lastmodifieddate", "value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"CALCULATED", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}, "name"=>{"value"=>"Second Financial LLC.", "timestamp"=>1552234087467, "source"=>"API", "sourceId"=>nil, "versions"=>[{"name"=>"name", "value"=>"Second Financial LLC.", "timestamp"=>1552234087467, "source"=>"API", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}, "createdate"=>{"value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"API", "sourceId"=>nil, "versions"=>[{"name"=>"createdate", "value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"API", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}}, @id=1726317857, @persisted=true, @deleted=false, @metadata={"portalId"=>62515, "companyId"=>1726317857, "isDeleted"=>false, "additionalDomains"=>[], "stateChanges"=>[], "mergeAudits"=>[]}>
+
+irb(main):002:0> company = Hubspot::Company.find(1)
+Traceback (most recent call last):
+        6: from /home/chris/projects/hubspot-ruby/bin/console:20:in `<main>'
+        5: from (irb):2
+        4: from /home/chris/projects/hubspot-ruby/lib/hubspot/resource.rb:17:in `find'
+        3: from /home/chris/projects/hubspot-ruby/lib/hubspot/resource.rb:81:in `reload'
+        2: from /home/chris/projects/hubspot-ruby/lib/hubspot/connection.rb:10:in `get_json'
+        1: from /home/chris/projects/hubspot-ruby/lib/hubspot/connection.rb:52:in `handle_response'
+Hubspot::RequestError (Response body: {"status":"error","message":"resource not found","correlationId":"7c8ba50e-16a4-4a52-a304-ff249175a8f1","requestId":"b4898274bf8992924082b4a460b90cbe"})
 ```
 
-### Find a contact
 
-These methods will return a `Hubspot::Contact` object if successful, `nil` otherwise:
+### Updating resource properties
+
+```ruby
+irb(main):001:0> company = Hubspot::Company.find(1726317857)
+=> #<Hubspot::Company:0x0000563b9f3ee230 @changes={}, @properties={"hs_lastmodifieddate"=>{"value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"CALCULATED", "sourceId"=>nil, "versions"=>[{"name"=>"hs_lastmodifieddate", "value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"CALCULATED", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}, "name"=>{"value"=>"Second Financial LLC.", "timestamp"=>1552234087467, "source"=>"API", "sourceId"=>nil, "versions"=>[{"name"=>"name", "value"=>"Second Financial LLC.", "timestamp"=>1552234087467, "source"=>"API", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}, "createdate"=>{"value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"API", "sourceId"=>nil, "versions"=>[{"name"=>"createdate", "value"=>"1552234087467", "timestamp"=>1552234087467, "source"=>"API", "sourceVid"=>[], "requestId"=>"fd45773b-30d0-4d9d-b3b8-a85e01534e46"}]}}, @id=1726317857, @persisted=true, @deleted=false, @metadata={"portalId"=>62515, "companyId"=>1726317857, "isDeleted"=>false, "additionalDomains"=>[], "stateChanges"=>[], "mergeAudits"=>[]}>
+
+irb(main):002:0> company.name
+=> "Second Financial LLC."
+
+irb(main):003:0> company.name = "Third Financial LLC."
+=> "Third Financial LLC."
+
+irb(main):004:0> company.changed?
+=> true
+
+irb(main):005:0> company.changes
+=> {:name=>"Third Financial LLC."}
+
+irb(main):006:0> company.save
+=> true
+
+irb(main):007:0> company.changed?
+=> false
+
+irb(main):008:0> company.changes
+=> {}
+```
+
+**Note:** Unlike ActiveRecord in Rails, in some cases not all properties of a resource are known. If these properties are not returned by the API then they will not have a getter method defined for them until they've been set first. This may change in the future to improve the user experience and different methods are being tested.
 
 ```ruby
-Hubspot::Contact.find_by_email("email@address.com")
-Hubspot::Contact.find_by_id(12345) # Pass the contact VID
+irb(main):001:0> company = Hubspot::Company.new
+=> #<Hubspot::Company:0x0000561d0a8bdff8 @changes={}, @properties={}, @id=nil, @persisted=false, @deleted=false>
+
+irb(main):002:0> company.name
+Traceback (most recent call last):
+        3: from /home/chris/projects/hubspot-ruby/bin/console:20:in `<main>'
+        2: from (irb):2
+        1: from /home/chris/projects/hubspot-ruby/lib/hubspot/resource.rb:215:in `method_missing'
+NoMethodError (undefined method `name' for #<Hubspot::Company:0x0000561d0a8bdff8>)
+
+irb(main):003:0> company.name = "Foobar"
+=> "Foobar"
+
+irb(main):004:0> company.name
+=> "Foobar"
 ```
 
-### Update a contact
+### Collections
 
-Given an instance of `Hubspot::Contact`, update its attributes with:
+To make working with API endpoints that return multiple resources easier, the returned instances will be wrapped in a collection instance. Just like in Rails, the collection instance provides helper methods for limiting the number of returned resources, paging through the results, and handles passing the options each time a new API call is made. The collection exposes all Ruby Array methods so you can use things like `size()`, `first()`, `last()`, and `map()`.
 
 ```ruby
-contact.update!({firstname: "First", lastname: "Last"})
+irb(main):001:0> contacts = Hubspot::Contact.all
+=> #<Hubspot::PagedCollection:0x000055ba3c2b55d8 @limit_param="limit", @limit=25, @offset_param="offset", @offset=nil, @options={}, @fetch_proc=#<Proc:0x000055ba3c2b5538@/home/chris/projects/hubspot-ruby/lib/hubspot/contact.rb:18>, @resources=[...snip...], @next_offset=9242374, @has_more=true>
+
+irb(main):002:0> contacts.more?
+=> true
+
+irb(main):003:0> contacts.next_offset
+=> 9242374
+
+irb(main):004:0> contacts.size
+=> 25
+
+irb(main):005:0> contacts.first
+=> #<Hubspot::Contact:0x000055ba3c29bac0 @changes={}, @properties={"firstname"=>{"value"=>"My Street X 1551971239 => My Street X 1551971267 => My Street X 1551971279"}, "lastmodifieddate"=>{"value"=>"1551971286841"}, "company"=>{"value"=>"MadKudu"}, "lastname"=>{"value"=>"Test0830181615"}}, @id=9153674, @persisted=true, @deleted=false, @metadata={"addedAt"=>1535664601481, "vid"=>9153674, "canonical-vid"=>9153674, "merged-vids"=>[], "portal-id"=>62515, "is-contact"=>true, "profile-token"=>"AO_T-mPNHk6O7jh8u8D2IlrhZn7GO91w-weZrC93_UaJvdB0U4o6Uc_PkPJ3DOpf15sUplrxMzG9weiTTpPI05Nr04zxnaNYBVcWHOlMbVlJ2Avq1KGoCBVbIoQucOy_YmCBIfOXRtcc", "profile-url"=>"https://app.hubspot.com/contacts/62515/contact/9153674", "form-submissions"=>[], "identity-profiles"=>[{"vid"=>9153674, "saved-at-timestamp"=>1535664601272, "deleted-changed-timestamp"=>0, "identities"=>[{"type"=>"EMAIL", "value"=>"test.0830181615@test.com", "timestamp"=>1535664601151, "is-primary"=>true}, {"type"=>"LEAD_GUID", "value"=>"01a107c4-3872-44e0-ab2e-47061507ffa1", "timestamp"=>1535664601259}]}], "merge-audits"=>[]}>
+
+irb(main):006:0> contacts.next_page
+=> #<Hubspot::PagedCollection:0x000055ba3c2b55d8 @limit_param="limit", @limit=25, @offset_param="offset", @offset=9242374, @options={}, @fetch_proc=#<Proc:0x000055ba3c2b5538@/home/chris/projects/hubspot-ruby/lib/hubspot/contact.rb:18>, @resources=[...snip...], @next_offset=9324874, @has_more=true>
 ```
 
-#### In batches
+For Hubspot resources that support batch updates for updating multiple resources, the collection provides an `update_all()` method:
 
 ```ruby
-Hubspot::Contact.create_or_update!([{vid: '12345', firstname: 'First', lastname: 'Last'}])
+irb(main):001:0> companies = Hubspot::Company.all(limit: 5)
+=> #<Hubspot::PagedCollection:0x000055d5314fe0c8 @limit_param="limit", @limit=5, @offset_param="offset", @offset=nil, @options={}, @fetch_proc=#<Proc:0x000055d5314fe028@/home/chris/projects/hubspot-ruby/lib/hubspot/company.rb:21>, @resources=[...snip...], @next_offset=116011506, @has_more=true>
+
+irb(main):002:0> companies.size
+=> 5
+
+irb(main):003:0> companies.update_all(lifecyclestage: "opportunity")
+=> true
+
+irb(main):004:0> companies.refresh
+=> #<Hubspot::PagedCollection:0x000055d5314fe0c8 @limit_param="limit", @limit=5, @offset_param="offset", @offset=nil, @options={}, @fetch_proc=#<Proc:0x000055d5314fe028@/home/chris/projects/hubspot-ruby/lib/hubspot/company.rb:21>, @resources=[...snip...], @next_offset=116011506, @has_more=true>
 ```
 
-### Create a deal
+### Deleting a resource
 
 ```ruby
-Hubspot::Deal.create!(nil, [company.vid], [contact.vid], pipeline: 'default', dealstage: 'initial_contact')
+irb(main):001:0> contact = Hubspot::Contact.find(9324874)
+=> #<Hubspot::Contact:0x000055a87c87aee0 ...snip... >
+
+irb(main):002:0> contact.delete
+=> true
 ```
 
+## Resource types
+
+**Note:** These are the currently defined classes the support the new resource API. This list will continue to grow as we update other classes. All existing classes will be updated prior to releasing v1.0.
+
+* Contact -> Hubspot::Contact
+* Company -> Hubspot::Company
+
 ## Contributing to hubspot-ruby
 
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

bin/console

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "hubspot-ruby"
+
+# Include Byebug for debugging
+require "byebug"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+# Configure with the demo key by default
+Hubspot.configure(hapikey: 'demo')
+
+require "irb"
+IRB.start(__FILE__)

gemfiles/activesupport_4.2.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 4.2.2"
 

gemfiles/activesupport_5.0.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 5.0.0"
 

gemfiles/activesupport_5.1.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 5.1.0"
 

gemfiles/activesupport_5.2.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 5.2.2"
 

hubspot-ruby.gemspec

@@ -34,5 +34,8 @@ Gem::Specification.new do |s|
   s.add_development_dependency("awesome_print")
   s.add_development_dependency("timecop")
   s.add_development_dependency("guard-rspec")
+  s.add_development_dependency("byebug")
+  s.add_development_dependency("faker")
+  s.add_development_dependency("factory_bot")
 end
 

lib/hubspot-ruby.rb

@@ -2,6 +2,9 @@
 require 'active_support/core_ext'
 require 'httparty'
 require 'hubspot/exceptions'
+require 'hubspot/resource'
+require 'hubspot/collection'
+require 'hubspot/paged_collection'
 require 'hubspot/properties'
 require 'hubspot/company'
 require 'hubspot/company_properties'

lib/hubspot/collection.rb

@@ -0,0 +1,41 @@
+class Hubspot::Collection
+  def initialize(opts = {}, &block)
+    @options = opts
+    @fetch_proc = block
+    fetch
+  end
+
+  def refresh
+    fetch
+    self
+  end
+
+  def resources
+    @resources
+  end
+
+  def update_all(opts = {})
+    return true if empty?
+
+    # This assumes that all resources are the same type
+    resource_class = resources.first.class
+    unless resource_class.respond_to?(:batch_update)
+      raise "#{resource_class} does not support bulk update"
+    end
+
+    resource_class.batch_update(resources, opts)
+  end
+
+protected
+  def fetch
+    @resources = @fetch_proc.call(@options)
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    @resources.respond_to?(name, include_private)
+  end
+
+  def method_missing(method, *args, &block)
+    @resources.public_send(method, *args, &block)
+  end
+end