ruby_hubspot_api 0.1.2.1 → 0.2.1.pre.1

data/lib/hubspot/api_client.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
+# HubSpot API Client
+# Handles all HTTP interactions with the HubSpot API. It manages GET, POST, PATCH, and DELETE requests.
 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 +37,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 +45,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 +57,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
@@ -14,6 +15,11 @@ module Hubspot
       apply_log_level
     end
 
+    # Apply the log level to the logger
+    def apply_log_level
+      @logger.level = @log_level
+    end
+
     private
 
     # Initialize the default logger
@@ -42,11 +48,6 @@ module Hubspot
     end
     # rubocop:enable Metrics/MethodLength
 
-    # Apply the log level to the logger
-    def apply_log_level
-      @logger.level = @log_level
-    end
-
     # Set the default log level based on environment
     def default_log_level
       if defined?(Rails) && Rails.env.test?

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/property.rb

@@ -11,5 +11,9 @@ module Hubspot
       "#<#{self.class} #{formatted_attrs}>"
     end
     # :nocov:
+
+    def read_only?
+      modificationMetadata['readOnlyValue'] == true
+    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
@@ -65,6 +82,14 @@ module Hubspot
         properties.reject { |property| property['hubspotDefined'] }
       end
 
+      def updatable_properties
+        properties.reject(&:read_only?)
+      end
+
+      def read_only_properties
+        properties.select(&:read_only?)
+      end
+
       def property(property_name)
         properties.detect { |prop| prop.name == property_name }
       end
@@ -111,8 +136,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 +146,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 +186,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 +198,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 +236,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 +265,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.1-1'
 end

data/lib/hubspot.rb

@@ -19,6 +19,8 @@ module Hubspot
     def configure
       yield(config) if block_given?
       set_client_headers if config.access_token
+      set_request_timeouts
+      config.apply_log_level
     end
 
     def configured?
@@ -31,5 +33,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,38 @@
+# 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
+
+# At some point this will seem like a bad idea ;)
+
+# :nocov:
+if RUBY_VERSION < '2.5.0'
+  class Hash
+    # Non-mutating version (returns a new hash with transformed keys)
+    def transform_keys
+      return enum_for(:transform_keys) unless block_given?
+      result = {}
+      each_key do |key|
+        result[yield(key)] = self[key]
+      end
+      result
+    end
+
+    # Mutating version (modifies the hash in place)
+    def transform_keys!
+      return enum_for(:transform_keys!) unless block_given?
+      keys.each do |key|
+        self[yield(key)] = delete(key)
+      end
+      self
+    end
+  end
+end
+# :nocov:end