ruby_hubspot_api 0.1.2.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b77e20469ffc97b7330e7a163ee5ed4d43b1bef4a17ee7a1eb38663157d3faab
-  data.tar.gz: 52088790ea4ccea816e0b2efc0846331dcffbc29fd0d01c80e16baa9dbafb331
+  metadata.gz: 67b58c873d1e9277df15b213a804afe47189c888aab565963950bf9992050e07
+  data.tar.gz: 62028c4b6b0a2ac9a9a29e88cf4762cbbdb909942415d1bc2bf02e3838b405eb
 SHA512:
-  metadata.gz: eab5e7e4ab612428b97b31b81c06c25562f6dd0ef89eba5f47628bb1dbc79dd84fa893c868f6515f0f2d2b435016e8ed50c897e7aa97ac66355b136c1778aea3
-  data.tar.gz: '08dbe5b3847885d286e7f26142e8d2925583195d1c624158d165e023cc2fc3b7cb4482eab4db459c3ecf50aae226457a3487e3fbe8242eb8c59c346c1e0132bb'
+  metadata.gz: 98ec373c58ef3aa92eb963d2ab567bd41204bd1c80552e0abacf4cadc1a6860d5b227dde78f5fbfe8b6d3cdff65536390116f468492c6f639e87c1a83f4e60ff
+  data.tar.gz: 5bea871875782b5fd35ff62de85c11da16f7e763a88972ac3d6cbca3e6b700eca589eed7933058434d9c6574079b71fd5e2d0aabc8fcc3be288dd27d5a9ae405

data/CHANGELOG.md

@@ -1,5 +1,29 @@
+## v.0.2.0
 
-## v0.1.1
+- Get the development dependencies right!
+- Bump the version again
+- describe find_by method
+- update lock
+- batch  :sparkle: upsert spec
+- Borrowing Object#blank? method cos it actually really helps...
+- batch implemntation
+- logger.debug the post body and response body
+- Adds a changes? Method on resource
+- Adds instance method resource_name on resource
+- Ensure keys are stringified
+- Add all end points to the batch spec
+- Adds create and archive methods to batches
+- Tidy up resource code
+- Cover the previously nocov'd code
+- Add api client logging spec
+- add configurable timeouts to requests
+- Move rate limit handling to the client
+- Simplify mocked responses in batch spec
+- Adds PagedBatch as pager for batch/read request
+- Update the Readme to add Batch operations
+- #5 batch_updating
+
+## v0.1.2
 
 - initial setup
 - Setup the configuration block
@@ -46,6 +70,17 @@
 - adds the version numbers to the gemspec
 - Fix dependencies
 - bump version
+- Fix the Readme
+- Sure the search param is values where passing an array
+- update changelog and Gemfile.lock
+- bump version
+
+## v0.1.1
+
+- Fix the Readme
+- Sure the search param is values where passing an array
+- update changelog and Gemfile.lock
+- bump version
 
 ## v0.1.0
 

data/Gemfile.lock

@@ -1,16 +1,8 @@
 PATH
   remote: .
   specs:
-    ruby_hubspot_api (0.1.1)
-      bundler (>= 2.0)
-      dotenv (>= 2.0)
+    ruby_hubspot_api (0.1.2.1)
       httparty (>= 0.1, < 1.0)
-      pry (>= 0.1)
-      pry-byebug (>= 3.0)
-      rspec (>= 3.0)
-      simplecov (>= 0.22, < 1.0)
-      vcr (>= 6.0)
-      webmock (>= 3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -71,8 +63,16 @@ PLATFORMS
   x86_64-darwin-18
 
 DEPENDENCIES
+  bundler (>= 2.0)
+  dotenv (>= 2.0)
+  pry (>= 0.1)
+  pry-byebug (>= 3.0)
   rake (>= 11.0, < 14.0)
+  rspec (>= 3.0)
   ruby_hubspot_api!
+  simplecov (>= 0.22, < 1.0)
+  vcr (>= 6.0)
+  webmock (>= 3.0)
 
 BUNDLED WITH
    2.3.26

data/README.md

@@ -2,7 +2,7 @@
 
 This gem was largely inspired by [hubspot-api-ruby](https://github.com/captaincontrat/hubspot-api-ruby) which, in turn, was inspired by the [hubspot-ruby](https://github.com/HubspotCommunity/hubspot-ruby) community gem. I wanted to use version 3 of the api and simplify some parts of the interface
 
-The Ruby HubSpot API gem is a starting point for building an ORM-like interface to HubSpot's API. 
+The Ruby HubSpot API gem is a starting point for building an ORM-like interface to HubSpot's API.
 
 ## Installation
 
@@ -40,13 +40,13 @@ This configuration ensures that your API requests are authenticated using your H
 
 ## Working with Objects
 
-This gem allows you to interact with HubSpot objects such as contacts and companies. You can perform operations on individual instances (e.g., creating or updating records) as well as on collections (e.g., listing or searching).
+_(N.B when referring to the resources in the api we will refer to them as Objects as per the Hubspot nomenclature)_
 
-### Instance Methods
+This gem allows you to interact with HubSpot objects such as contacts and companies. You can perform operations on individual instances (e.g., creating or updating records) as well as on collections (e.g., listing or searching).
 
-#### Creating and Saving an Object
+### Creating and Saving an Object
 
-You can instantiate a new resource (such as a contact) by passing a hash of properties when creating the object. After setting the properties, calling `save` will persist the object to the HubSpot API.
+Create and instance of the resource passing a hash of properties. Calling `save` on the instance will persist the object to the HubSpot API, as well as set the id property (which you can then store in your own database for example)
 
 Example:
 
@@ -60,44 +60,96 @@ new_contact.save
 puts "New contact ID: #{new_contact.id}"
 ```
 
-#### Updating an Existing Object
+### Retreiving an Object
+
+If you know the id of the object you can fetch it from the api using the find method
+
+```ruby
+contact = Hubspot::Contact.find(1)
+puts "Contact: #{contact.firstname} #{contact.lastname}"
+```
+
+You can also retrieve a single object by using the `find_by` method. Simply specify the property and the value you want to search on:
+
+```ruby
+# find by email
+contact = Hubspot::Contact.find_by('email', 'john.doe@example.org')
+puts "Contact: #{contact.firstname} #{contact.lastname}"
 
-To update an existing object, you can either modify the object and call `save`, or use the `update` method specifying the properties you want to update
+#find by internal id (custom field)
+contact = Hubspot::Contact.find_by('member_id', 123)
+puts "Contact: #{contact.firstname} #{contact.lastname}"
+```
+
+### Updating an Existing Object
+
+To update an existing object, you can either modify the object and call `save`, or use the `update` method specifying the properties you want to update. You can test whether or not the object will need to upload changes to the api by using the changes? method
 
 Example using `save`:
 
 ```ruby
 contact = Hubspot::Contact.find(1)
+contact.changes? # false
+
 contact.lastname = 'DoeUpdated'
+contact.changes? # true
+
+# save the updates to Hubspot
 contact.save # true
+contact.changes? # false
 ```
 
 Example using `update`:
 
 ```ruby
 contact = Hubspot::Contact.find(1)
+# save the updates to Hubspot
 contact.update(lastname: 'DoeUpdated') # true
 ```
 
-### Class Methods
+If you are able to construct an Object with data stored locally you can save the inital `find` api call, but you will need to construct the persisted object specifying the id and a properties hash (as if it came from the api!)
+
+Example:
 
-#### Listing Objects
+```ruby
+local_contact = Contact.find(contact_id)
 
-You can list all objects (such as contacts) using the `list` method, which returns a `PagedCollection`. This collection handles paginated results and responds to methods like `each_page`, `each`, and `all`. You can also pass the `page_size` parameter to control the number of records returned per page.
+hubspot_properties = {
+  firstname: local_contact.first_name,
+  lastname: local_contact.last_name,
+  email: local_contact.email,
+  # ... more properties...
+}
+
+hubspot_contact = Hubspot::Contact.new(id: contact.hs_object_id, properties: hubspot_properties )
+hubspot_contact.changes? # false
+
+# update a custom field "last_contacted"
+# (in the hubspot_contact instance this will be stored in the changes property)
+hubspot_contact.last_contacted = Time.now.utc.iso8601
+hubspot_contact.changes? # true
+
+# persist the change to hubspot
+hubspot_contact.save #true
+```
+
+### Listing Objects
+
+You can list all objects (such as contacts) using the `list` method, which returns a `PagedCollection`. This collection handles paginated results and is Enumerable, so responds to methods like `each_page`, `each`, and `all`. You can also pass the `page_size` parameter to control the number of records returned per page.
 
 Example:
 
 ```ruby
 contacts = Hubspot::Contact.list(page_size: 10)
 
-# Using each_page to iterate over pages
+# Using each_page to iterate over pages, there will be up to 10 contacts per page
 contacts.each_page do |page|
   page.each do |contact|
     puts "Contact: #{contact.firstname} #{contact.lastname}"
   end
 end
 
-# Or iterate over all contacts without worrying about pagination
+# Or iterate over all contacts and the pagination will be handled transparently (page_size still applies)
 contacts.each do |contact|
   puts "Contact: #{contact.firstname} #{contact.lastname}"
 end
@@ -106,23 +158,42 @@ end
 all_contacts = contacts.all
 ```
 
-#### Retrieving the first n items
+#### Retrieving the first n items:
 
-You can use the `first` method to retrieve the first item or a specified number of items:
+As mentioned the list method returns a PagedCollection. You can call `first` on the result to retrieve the first item or a specified number of items:
 
 ```ruby
-contacts = Hubspot::Contact.list(page_size: 10)
+contacts_collection = Hubspot::Contact.list
 
 # Retrieve the first contact
-first_contact = contacts.first
+first_contact = contacts_collection.first
 
 # Retrieve the first 5 contacts
-first_five_contacts = contacts.first(5)
+first_five_contacts = contacts_collection.first(5)
 ```
 
 This will automatically set the limits and handle paging for the most efficient API calls while honouring the maximum page count for hubspot resources
 
-#### Searching
+#### Specifying properties
+
+By default Hubspot will only send back the [default hubspot properties](https://knowledge.hubspot.com/properties/hubspots-default-contact-properties)
+
+You can pass an array of properties to be return as follows:
+
+Example:
+
+```ruby
+# Search for contacts with email containing "hubspot.com" and only return specific properties
+contacts = Hubspot::Contact.list(
+  properties: ['firstname', 'lastname', 'email', 'mobile', 'custom_property_1']
+)
+
+contacts.each do |contact|
+  puts "Name: #{contact.firstname} #{contact.lastname}, Email: #{contact.email}, Mobile: #{contact.mobile} CustomerRef: #{contact.custom_property_1}"
+end
+```
+
+### Searching
 
 You can search for objects by passing query parameters to the `search` method. HubSpot supports several operators such as `eq`, `gte`, `lt`, and `IN` for filtering.
 
@@ -132,15 +203,21 @@ Example:
 # Search for contacts with email containing "hubspot.com"
 contacts = Hubspot::Contact.search(query: { email_contains: 'hubspot.com' })
 
+puts "Searching for Hubspot staff in the contacts CRM"
+puts ""
+
 contacts.each do |contact|
-  puts "Found: #{contact.email}"
+  puts "  Found: #{contact.firstname} #{contact.lastname} (#{contact.email})"
 end
 
 # Search for companies with number of employees greater than or equal to 100
 companies = Hubspot::Company.search(query: { number_of_employees_gte: 100 })
 
+puts "Searching for medium to large companies"
+puts ""
+
 companies.each do |company|
-  puts "Found: #{company.name}, Employees: #{company.number_of_employees}"
+  puts "  Found: #{company.name} (#{company.number_of_employees} employees)"
 end
 
 # Search for contacts with email in a specific list (IN operator)
@@ -152,15 +229,18 @@ end
 ```
 
 ### Available Search Operators:
-- **eq**: Equal to.
+- **contains**: contains <string>
 - **neq**: Not equal to.
+- **gt**: Greater than.
 - **gte**: Greater than or equal to.
+- **lt**: Less than.
 - **lte**: Less than or equal to.
 - **IN**: Matches any of the values in an array.
 
 #### Specifying Properties in Search
 
-When performing a search, you can also specify which properties to return. If you specify any properties, you will only get those properties back, and the default HubSpot properties will not be included automatically.
+When performing a search, you can also specify which properties to return.
+*NB* If you specify any properties, you will only get those properties back, and the default HubSpot properties will not be included automatically.
 
 Example:
 
@@ -172,10 +252,159 @@ contacts = Hubspot::Contact.search(
 )
 
 contacts.each do |contact|
-  puts "Name: #{contact.firstname} #{contact.lastname}, Email: #{contact.email}, Mobile: #{contact.mobile}"
+  puts "Name: #{contact.firstname} #{contact.lastname}, Email: #{contact.email}, Mobile: #{contact.mobile} CustomerRef: #{contact.custom_property_1}"
+end
+```
+
+## Working with batches
+
+### Hubspot::Batch
+
+The `Hubspot::Batch` class allows you to perform batch operations on HubSpot resources, such as contacts or companies. This includes batch `create`, `read`, `update`, `upsert`, and `archive` operations. Below are examples of how to use these methods.
+
+#### Batch Create
+
+To create new resources in bulk, you can use the `create` method.
+
+In this example, `batch.create` triggers the creation of new contacts. After creation, the batch response will include the new IDs assigned to each object by HubSpot which will be assigned to the resources in the batch
+
+```ruby
+contacts = [
+  Hubspot::Contact.new(email: 'new.john@example.com', firstname: 'John', lastname: 'Doe'),
+  Hubspot::Contact.new(email: 'new.jane@example.com', firstname: 'Jane', lastname: 'Doe')
+]
+
+batch = Hubspot::Batch.new(contacts)
+batch.create
+
+batch.resources.each do |contact|
+  hubspot_id = contact.id
+  # store hubspot_id against a contact....
 end
 ```
 
+
+#### Batch Read
+
+To read a batch of Objects by their internal hubspot id or by another uniq property you can use the `read` method. You will need to pass the class of the resource, an array of ids and optionally an id_property.
+
+ For simplicity you can also use the `batch_read` method of the corresponding class (e.g. Hubspot::Contacts, Hubspot::Company etc) passing an array of ids and optionally an id_property (defaults to 'id'). This method will return a Hubspot::Batch and the results will be in "resources"
+
+Example using `read` along with the Hubspot id of several companies...
+
+```ruby
+# Grab an array of hubspot company ids to read from the api...
+company_ids = my_companies.collect(&:hubspot_id).compact
+
+# this will grab all the results from the api handling paging automagically
+batch = Hubspot::Batch.read(Hubspot::Company, company_ids)
+companies = batch.resources
+
+# Or using the domain field
+# Grab an array of company domains
+company_domains = my_companies.collect(&:domain_name).compact
+
+# calls /crm/v3/objects/companies/batch/read
+batch = Hubspot::Batch.read(Hubspot::Company, company_domains, id_property: 'domain')
+companies = batch.resources
+```
+
+Example of reading contacts by email and the helper method `batch_read`
+By using this method you can page through the results as needed or collect them 
+
+```ruby
+email_addresses = my_selected_contacts.collect(&:email).compact
+
+batch = Hubspot::Contact.batch_read(email_addresses, id_property: 'email')
+
+batch.each_page do |contacts|
+  contacts.each do |contact|
+    # persist some data locally
+    update_local_contact_from_hubspot(contact)
+  end
+  # stop the api calls if a condition is met
+  # break if <condition>
+end
+```
+
+Finally there is another helper method on re
+
+#### Batch Update
+
+For updating existing resources in bulk, you can use the `update` method. If you want to locally create an object without calling the API you specify the id and pass any properties in the 'properties' hash (this is how the objects are returned from Hubspot)
+
+```ruby
+contacts = [
+  Hubspot::Contact.new(id: 1, properties: { firstname: 'John', lastname: 'Doe' }),
+  Hubspot::Contact.new(id: 2, properties: { firstname: 'Jane', lastname: 'Doe' })
+]
+
+# make a changes to each contact
+contacts.each { |contact| contact.last_contacted = Time.now.utc.iso8601 }
+
+batch = Hubspot::Batch.new(contacts)
+batch.update
+```
+
+Example using a batch
+```ruby
+contact_ids = my_contacts.collect(&:hubspot_id).compact
+batch = Hubspot::contacts.batch_read(contact_ids)
+
+batch.resources.each do |hubspot_contact|
+  my_contact = my_contacts.find { |c| c.hubspot_id == hubspot_contact.id }
+  # some logic or method to set any new/changed properties on hubspot_contact
+  update_hubspot_contact_from_local(hubspot_contact, my_contact)
+end
+
+# now we have a batch with changed resources we can update the batch
+batch.update # true
+```
+
+#### Batch Upsert
+
+The `upsert` method allows you to insert new records or update existing ones. You’ll need to specify an `id_property` (like `email`) to uniquely identify records
+
+```ruby
+contacts = [
+  Hubspot::Contact.new(email: 'new.john@example.com', firstname: 'John', lastname: 'Doe'),
+  Hubspot::Contact.new(email: 'new.jane@example.com', firstname: 'Jane', lastname: 'Doe')
+]
+
+batch = Hubspot::Batch.new(contacts, id_property: 'email')
+batch.upsert
+```
+
+In this example, if a contact with the given email already exists in HubSpot, it will be updated. If it doesn't, a new contact will be created.
+
+#### Batch Archive
+
+To archive objects in bulk, you can use the `archive` method. This removes the objects from HubSpot.
+
+```ruby
+contacts = Hubspot::Contact.search(query: { email_contains: 'hubspot.com' }).all
+
+batch = Hubspot::Batch.new(contacts)
+batch.archive
+```
+
+The `archive` method sends a batch request to HubSpot to archive the objects. If any of the objects fail to be archived, you can check for partial success using the `partial_success?` method.
+
+#### Error Handling and Success Checks
+
+You can check whether the batch operation was entirely successful, partially successful, or if any failures occurred:
+
+```ruby
+if batch.all_successful?
+  puts "All resources were successfully processed."
+elsif batch.partial_success?
+  puts "Some resources were successfully processed, but others failed."
+else
+  puts "The batch operation failed."
+end
+```
+
+
 ## Contributing
 
 There is much to do (including writing a TODO list, or at least adding issues in github!) but this should provide a solid start

data/lib/hubspot/api_client.rb

@@ -3,6 +3,9 @@
 module Hubspot
   # All interations with the Hubspot API happen here...
   class ApiClient
+    MAX_RETRIES = 3
+    RETRY_WAIT_TIME = 1 # seconds
+
     include HTTParty
     base_uri 'https://api.hubapi.com'
 
@@ -32,7 +35,7 @@ module Hubspot
         ensure_configuration!
         start_time = Time.now
         response = super(url, options)
-        log_request(:post, url, response, start_time)
+        log_request(:post, url, response, start_time, options)
         response
       end
 
@@ -40,7 +43,7 @@ module Hubspot
         ensure_configuration!
         start_time = Time.now
         response = super(url, options)
-        log_request(:patch, url, response, start_time)
+        log_request(:patch, url, response, start_time, options)
         response
       end
 
@@ -52,23 +55,52 @@ module Hubspot
         response
       end
 
-      def log_request(http_method, url, response, start_time)
+      def log_request(http_method, url, response, start_time, extra = nil)
         d = Time.now - start_time
         Hubspot.logger.info("#{http_method.to_s.upcase} #{url} took #{d.round(2)}s with status #{response.code}")
-        Hubspot.logger.debug("Response body: #{response.body}") if Hubspot.logger.debug?
+        return unless Hubspot.logger.debug?
+
+        Hubspot.logger.debug("Request body: #{extra}") if extra
+        Hubspot.logger.debug("Response body: #{response.body}")
       end
 
-      def handle_response(response)
-        if response.success?
+      def handle_response(response, retries = 0)
+        case response.code
+        when 200..299
           response.parsed_response
+        when 429
+          handle_rate_limit(response, retries)
         else
-          Hubspot.logger.error("API Error: #{response.code} - #{response.body}")
-          raise Hubspot.error_from_response(response)
+          log_and_raise_error(response)
         end
       end
 
       private
 
+      def handle_rate_limit(response, retries)
+        if retries < MAX_RETRIES
+          retry_after = response.headers['Retry-After']&.to_i || RETRY_WAIT_TIME
+          Hubspot.logger.warn("Rate limit hit. Retrying in #{retry_after} seconds...")
+          sleep(retry_after)
+          retry_request(response.request, retries + 1)
+        else
+          Hubspot.logger.error('Exceeded maximum retries for rate-limited request.')
+          raise Hubspot.error_from_response(response)
+        end
+      end
+
+      def retry_request(request, retries)
+        # Re-issues the original request using the retry logic
+        http_method = request.http_method::METHOD.downcase # Use the METHOD constant to get the method string
+        response = HTTParty.send(http_method, request.uri, request.options)
+        handle_response(response, retries)
+      end
+
+      def log_and_raise_error(response)
+        Hubspot.logger.error("API Error: #{response.code} - #{response.body}")
+        raise Hubspot.error_from_response(response)
+      end
+
       def ensure_configuration!
         raise NotConfiguredError, 'Hubspot API not configured' unless Hubspot.configured?
       end

data/lib/hubspot/batch.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module Hubspot
+  # exactly the same as a parsed_response but with the status code preserved
+  class BatchResponse < SimpleDelegator
+    attr_reader :status_code
+
+    def initialize(status_code, parsed_response)
+      @status_code = status_code
+      super(parsed_response) # Delegate to the parsed response object
+    end
+
+    # Check if all responses were successful (status 200)
+    def all_successful?
+      @status_code == 200
+    end
+
+    # Check if some responses succeeded and some failed (status 207)
+    def partial_success?
+      @status_code == 207
+    end
+  end
+
+  # Class to handle batch updates of resources
+  # rubocop:disable Metrics/ClassLength
+  class Batch < ApiClient
+    attr_accessor :id_property, :resources, :responses
+
+    CONTACT_LIMIT = 10
+    DEFAULT_LIMIT = 100
+
+    # rubocop:disable Lint/MissingSuper
+    def initialize(resources = [], id_property: 'id')
+      @resources = []
+      @id_property = id_property # Set id_property for the batch (default: 'id')
+      @responses = []            # Store multiple BatchResponse objects here
+      resources.each { |resource| add_resource(resource) }
+    end
+    # rubocop:enable Lint/MissingSuper
+
+    # batch create from the resources
+    def create
+      save(action: 'create')
+    end
+
+    def update
+      # validate_update_conditions
+      save(action: 'update')
+    end
+
+    # Upsert method that calls save with upsert action
+    def upsert
+      validate_upsert_conditions
+      save(action: 'upsert')
+    end
+
+    # Archive method
+    def archive
+      save(action: 'archive')
+    end
+
+    # Check if all responses were successful
+    def all_successful?
+      @responses.all?(&:all_successful?)
+    end
+
+    # Check if some responses were successful and others failed
+    def partial_success?
+      @responses.any?(&:partial_success?) && @responses.none?(&:all_successful?)
+    end
+
+    # Check if any responses failed
+    def any_failed?
+      @responses.any? { |response| !response.all_successful? && !response.partial_success? }
+    end
+
+    def add_resource(resource)
+      if @resources.any? && @resources.first.resource_name != resource.resource_name
+        raise ArgumentError, 'All resources in a batch must be of the same type'
+      end
+
+      @resources << resource
+    end
+
+    private
+
+    # rubocop:disable Metrics/MethodLength
+    def save(action: 'update')
+      @action = action
+      resource_type = check_single_resource_type
+      inputs = gather_inputs
+
+      return false if inputs.empty? # Guard clause
+
+      # Perform the batch updates in chunks based on the resource type's limit
+      batch_limit = batch_size_limit(resource_type)
+      inputs.each_slice(batch_limit) do |batch_inputs|
+        response = batch_request(resource_type, batch_inputs, action)
+        @responses << response
+      end
+
+      process_responses unless @action == 'archive'
+
+      # Check if any responses failed
+      !any_failed?
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def check_single_resource_type
+      raise 'Batch is empty' if @resources.empty?
+
+      @resources.first.resource_name
+    end
+
+    # Gather all the changes, ensuring each resource has an id and changes
+    def gather_inputs
+      return gather_archive_inputs if @action == 'archive'
+
+      @resources.map do |resource|
+        next if resource.changes.empty?
+
+        {
+          id: resource.public_send(@id_property),   # Dynamically get the ID based on the batch's id_property
+          idProperty: determine_id_property,        # Use the helper method to decide whether to include idProperty
+          properties: resource.changes              # Gather the changes for the resource
+        }.compact   # Removes nil keys
+      end.compact   # Removes nil entries
+    end
+
+    # Gather inputs for the archive operation
+    def gather_archive_inputs
+      @resources.map do |resource|
+        {
+          id: resource.public_send(@id_property),   # Use the ID or the custom property
+          idProperty: determine_id_property         # Include idProperty if it's not "id"
+        }.compact
+      end.compact
+    end
+
+    # Only include idProperty if it's not "id"
+    def determine_id_property
+      @id_property == 'id' ? nil : @id_property
+    end
+
+    # Perform batch request based on the provided action (upsert, update, create, or archive)
+    def batch_request(type, inputs, action)
+      response = self.class.post("/crm/v3/objects/#{type}/batch/#{action}", body: { inputs: inputs }.to_json)
+      BatchResponse.new(response.code, handle_response(response))
+    end
+
+    # Validation for upsert conditions
+    def validate_upsert_conditions
+      raise ArgumentError, "id_property cannot be 'id' for upsert" if @id_property == 'id'
+
+      # check if there are any resources without a value from the id_property
+      return unless @resources.any? { |resource| resource.public_send(id_property).blank? }
+
+      raise ArgumentError, "All resources must have a non-blank value for #{@id_property} to perform upsert"
+    end
+
+    # Return the appropriate batch size limit for the resource type
+    def batch_size_limit(resource_type)
+      resource_type == 'contacts' ? CONTACT_LIMIT : DEFAULT_LIMIT
+    end
+
+    # Process responses from the batch API call
+    def process_responses
+      @responses.each do |response|
+        next unless response['results']
+
+        process_results(response['results'])
+      end
+    end
+
+    # Process each result and update the resource accordingly
+    def process_results(results)
+      results.each do |result|
+        resource = find_resource_from_result(result)
+        next unless resource
+
+        # Set the ID on the resource directly
+        resource.id = result['id'].to_i if result['id']
+
+        # Update the resource properties
+        update_resource_properties(resource, result['properties'])
+
+        # Update metadata like updatedAt
+        update_metadata(resource, result['updatedAt'])
+      end
+    end
+
+    def find_resource_from_result(result)
+      case @action
+      when 'update', 'upsert'
+        find_resource_from_id(result['id'].to_i)
+
+      #
+      # when specifying idProperty in the upsert request
+      # the Hubspot API returns the id value (aka the hs_object_id)
+      # instead of the value of the <idProperty> field, so the value of the field
+      # is only stored in results['properties'][@id_property] if it changed!
+      # so this condition is redundant but left here in case Hubspot updates the response
+      #
+      # when 'upsert'
+      #   resource_id = result.dig('properties', @id_property) || result['id']
+      #   find_resource_from_id_property(resource_id)
+      #
+      when 'create'
+        # For create, check if the resource's changes are entirely contained in the result's properties
+        @resources.reject(&:persisted?).find do |resource|
+          resource.changes.any? && resource.changes.all? { |key, value| result['properties'][key.to_s] == value }
+        end
+      end
+    end
+
+    def find_resource_from_id(resource_id)
+      @resources.find { |r| r.id == resource_id }
+    end
+
+    # def find_resource_from_id_property(resource_id)
+    #   @resources.find { |r| r.public_send(@id_property) == resource_id }
+    # end
+
+    def update_resource_properties(resource, properties)
+      properties.each do |key, value|
+        if resource.changes[key]
+          resource.properties[key] = value
+          resource.changes.delete(key)
+        end
+      end
+    end
+
+    def update_metadata(resource, updated_at)
+      resource.metadata['updatedAt'] = updated_at if updated_at
+    end
+
+    class << self
+      def read(object_class, object_ids = [], id_property: 'id')
+        raise ArgumentError, 'Must be a valid Hubspot resource class' unless object_class < Hubspot::Resource
+
+        # fetch all the matching resources with paging handled
+        resources = object_class.batch_read(object_ids, id_property: id_property).all
+
+        # return instance of Hubspot::Batch with the resources set
+        new(resources, id_property: id_property)
+      end
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/hubspot/config.rb

@@ -3,7 +3,8 @@
 module Hubspot
   # To hold Hubspot configuration
   class Config
-    attr_accessor :access_token, :portal_id, :client_secret, :logger, :log_level
+    attr_accessor :access_token, :portal_id, :client_secret, :logger, :log_level,
+                  :timeout, :open_timeout, :read_timeout, :write_timeout
 
     def initialize
       @access_token = nil

data/lib/hubspot/paged_batch.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative './api_client'
+require_relative './exceptions'
+
+module Hubspot
+  # Enumerable class for handling paged data from the API
+  class PagedBatch < ApiClient
+    include Enumerable
+
+    MAX_LIMIT = 100 # HubSpot max items per page
+
+    # rubocop:disable Lint/MissingSuper
+    def initialize(url:, params: {}, resource_class: nil, object_ids: [])
+      @url = url
+      @params = params
+      @resource_class = resource_class
+      @object_ids = object_ids
+    end
+    # rubocop:enable Lint/MissingSuper
+
+    def each_page
+      @object_ids.each_slice(MAX_LIMIT) do |ids|
+        response = fetch_page(ids)
+        results = response['results'] || []
+        mapped_results = @resource_class ? results.map { |result| @resource_class.new(result) } : results
+        yield mapped_results unless mapped_results.empty?
+      end
+    end
+
+    def all
+      results = []
+      each_page do |page|
+        results.concat(page)
+      end
+      results
+    end
+
+    def each(&block)
+      each_page do |page|
+        page.each(&block)
+      end
+    end
+
+    private
+
+    def fetch_page(object_ids)
+      params_with_ids = @params.dup
+      params_with_ids[:inputs] = object_ids.map { |id| { id: id } }
+
+      response = self.class.post(@url, body: params_with_ids.to_json)
+
+      handle_response(response)
+    end
+  end
+end

data/lib/hubspot/paged_collection.rb

@@ -8,9 +8,6 @@ module Hubspot
   class PagedCollection < ApiClient
     include Enumerable
 
-    RATE_LIMIT_STATUS = 429
-    MAX_RETRIES = 3
-    RETRY_WAIT_TIME = 3
     MAX_LIMIT = 100 # HubSpot max items per page
 
     # rubocop:disable Lint/MissingSuper
@@ -68,18 +65,14 @@ module Hubspot
 
     private
 
-    def fetch_page(offset, attempt = 1, params_override = @params)
-      params_with_offset = params_override.dup
+    def fetch_page(offset)
+      params_with_offset = @params.dup
       params_with_offset.merge!(after: offset) if offset
 
       # Handle different HTTP methods
       response = fetch_response_by_method(params_with_offset)
 
-      if response.code == RATE_LIMIT_STATUS
-        handle_rate_limit(response, offset, attempt, params_override)
-      else
-        handle_response(response)
-      end
+      handle_response(response)
     end
 
     def fetch_response_by_method(params = {})
@@ -90,13 +83,5 @@ module Hubspot
         self.class.send(@method, @url, body: params.to_json)
       end
     end
-
-    def handle_rate_limit(response, offset, attempt, params_override)
-      raise Hubspot.error_from_response(response) if attempt > MAX_RETRIES
-
-      retry_after = response.headers['Retry-After']&.to_i || RETRY_WAIT_TIME
-      sleep(retry_after)
-      fetch_page(offset, attempt + 1, params_override)
-    end
   end
 end

data/lib/hubspot/resource.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative './api_client'
+require_relative './paged_collection'
+require_relative './paged_batch'
 
 module Hubspot
   # rubocop:disable Metrics/ClassLength
@@ -53,6 +55,21 @@ module Hubspot
         )
       end
 
+      def batch_read(object_ids = [], id_property: 'id')
+        params = id_property == 'id' ? {} : { idProperty: id_property }
+
+        PagedBatch.new(
+          url: "/crm/v3/objects/#{resource_name}/batch/read",
+          params: params,
+          object_ids: object_ids,
+          resource_class: self
+        )
+      end
+
+      def batch_read_all(object_ids = [], id_property: 'id')
+        Hubspot::Batch.read(self, object_ids, id_property: id_property)
+      end
+
       # Get the complete list of fields (properties) for the object
       def properties
         @properties ||= begin
@@ -111,8 +128,6 @@ module Hubspot
 
       # rubocop:enable Metrics/MethodLength
 
-      private
-
       # Define the resource name based on the class
       def resource_name
         name = self.name.split('::').last.downcase
@@ -123,6 +138,8 @@ module Hubspot
         end
       end
 
+      private
+
       # Instantiate a single resource object from the response
       def instantiate_from_response(response)
         data = handle_response(response)
@@ -161,10 +178,10 @@ module Hubspot
 
     # rubocop:disable Ling/MissingSuper
     def initialize(data = {})
+      data.transform_keys!(&:to_s)
       @id = extract_id(data)
       @properties = {}
       @metadata = {}
-
       if @id
         initialize_from_api(data)
       else
@@ -173,6 +190,10 @@ module Hubspot
     end
     # rubocop:enable Ling/MissingSuper
 
+    def changes?
+      !@changes.empty?
+    end
+
     # Instance methods for update (or save)
     def save
       if persisted?
@@ -207,6 +228,10 @@ module Hubspot
     end
     alias archive delete
 
+    def resource_name
+      self.class.resource_name
+    end
+
     # rubocop:disable Metrics/MethodLength
     # Handle dynamic getter and setter methods with method_missing
     def method_missing(method, *args)
@@ -232,19 +257,15 @@ module Hubspot
       end
 
       # Fallback if the method or attribute is not found
-      # :nocov:
       super
-      # :nocov:
     end
     # rubocop:enable Metrics/MethodLength
 
     # Ensure respond_to_missing? is properly overridden
-    # :nocov:
     def respond_to_missing?(method_name, include_private = false)
       property_name = method_name.to_s.chomp('=')
       @properties.key?(property_name) || @changes.key?(property_name) || super
     end
-    # :nocov:
 
     private
 

data/lib/hubspot/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hubspot
-  VERSION = '0.1.2.1'
+  VERSION = '0.2'
 end

data/lib/hubspot.rb

@@ -19,6 +19,7 @@ module Hubspot
     def configure
       yield(config) if block_given?
       set_client_headers if config.access_token
+      set_request_timeouts
     end
 
     def configured?
@@ -31,5 +32,18 @@ module Hubspot
     def set_client_headers
       Hubspot::ApiClient.headers 'Authorization' => "Bearer #{config.access_token}"
     end
+
+    def set_request_timeouts
+      config.timeout && Hubspot::ApiClient.default_timeout(config.timeout)
+      timeouts = %i[open_timeout read_timeout]
+      timeouts << :write_timeout if RUBY_VERSION >= '2.6'
+
+      timeouts.each do |t|
+        timeout = config.send(t)
+        next unless timeout
+
+        Hubspot::ApiClient.send(t, timeout)
+      end
+    end
   end
 end

data/lib/ruby_hubspot_api.rb

@@ -20,4 +20,7 @@ require_relative 'hubspot/company'
 require_relative 'hubspot/user'
 
 # Load other components
+require_relative 'hubspot/batch'
 require_relative 'hubspot/paged_collection'
+
+require_relative 'support/patches'

data/lib/support/patches.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# simplest monkey patch, honest ;)
+class Object
+  # Only define blank? if it's not already defined
+  unless method_defined?(:blank?)
+    def blank?
+      respond_to?(:empty?) ? empty? : !self
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_hubspot_api
 version: !ruby/object:Gem::Version
-  version: 0.1.2.1
+  version: '0.2'
 platform: ruby
 authors:
 - Simon Brook
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-25 00:00:00.000000000 Z
+date: 2024-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -190,16 +190,19 @@ files:
 - bin/setup
 - lib/hubspot.rb
 - lib/hubspot/api_client.rb
+- lib/hubspot/batch.rb
 - lib/hubspot/company.rb
 - lib/hubspot/config.rb
 - lib/hubspot/contact.rb
 - lib/hubspot/exceptions.rb
+- lib/hubspot/paged_batch.rb
 - lib/hubspot/paged_collection.rb
 - lib/hubspot/property.rb
 - lib/hubspot/resource.rb
 - lib/hubspot/user.rb
 - lib/hubspot/version.rb
 - lib/ruby_hubspot_api.rb
+- lib/support/patches.rb
 - ruby_hubspot_api.gemspec
 homepage: https://github.com/sensadrome/ruby_hubspot_api
 licenses: