ruby_hubspot_api 0.1.0

data/lib/hubspot/paged_collection.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative './api_client'
+require_relative './exceptions'
+
+module Hubspot
+  # Enumerable class for handling paged data from the API
+  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
+    def initialize(url:, params: {}, resource_class: nil, method: :get)
+      @url = url
+      @params = params
+      @resource_class = resource_class
+      @method = method.to_sym
+    end
+    # rubocop:enable Lint/MissingSuper
+
+    def each_page
+      offset = nil
+      loop do
+        response = fetch_page(offset)
+        results = response['results'] || []
+        mapped_results = @resource_class ? results.map { |result| @resource_class.new(result) } : results
+        yield mapped_results unless mapped_results.empty?
+        offset = response.dig('paging', 'next', 'after')
+        break unless offset
+      end
+    end
+
+    def all
+      results = []
+      each_page do |page|
+        results.concat(page)
+      end
+      results
+    end
+
+    # Override Enumerable's first method so as not to have to call each (via all)
+    def first(limit = 1)
+      resources = []
+      remaining = limit
+
+      # Modify @params directly to set the limit
+      @params[:limit] = [remaining, MAX_LIMIT].min
+
+      # loop through pages in case limit is more than the max limit
+      each_page do |page|
+        resources.concat(page)
+        remaining -= page.size
+        break if remaining <= 0
+      end
+
+      limit == 1 ? resources.first : resources.first(limit)
+    end
+
+    def each(&block)
+      each_page do |page|
+        page.each(&block)
+      end
+    end
+
+    private
+
+    def fetch_page(offset, attempt = 1, params_override = @params)
+      params_with_offset = params_override.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
+    end
+
+    def fetch_response_by_method(params = {})
+      case @method
+      when :get
+        self.class.send(@method, @url, query: params)
+      else
+        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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Hubspot
+  # Properties from the object schema
+  class Property < OpenStruct
+    # :nocov:
+    def inspect
+      included_keys = %i[name type fieldType hubspotDefined]
+      filtered_hash = to_h.slice(*included_keys)
+      formatted_attrs = filtered_hash.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+      "#<#{self.class} #{formatted_attrs}>"
+    end
+    # :nocov:
+  end
+end

data/lib/hubspot/resource.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require_relative './api_client'
+
+module Hubspot
+  # rubocop:disable Metrics/ClassLength
+  # Hubspot::Resource class
+  class Resource < ApiClient
+    METADATA_FIELDS = %w[createdate hs_object_id lastmodifieddate].freeze
+
+    # Allow read/write access to properties and metadata
+    attr_accessor :id, :properties, :changes, :metadata
+
+    class << self
+      # Find a resource by ID and return an instance of the class
+      def find(id)
+        response = get("/crm/v3/objects/#{resource_name}/#{id}")
+        instantiate_from_response(response)
+      end
+
+      def find_by(property, value, properties = nil)
+        params = { idProperty: property }
+        params[:properties] = properties if properties.is_a?(Array)
+        response = get("/crm/v3/objects/#{resource_name}/#{value}", query: params)
+        instantiate_from_response(response)
+      end
+
+      # Create a new resource
+      def create(params)
+        response = post("/crm/v3/objects/#{resource_name}", body: { properties: params }.to_json)
+        instantiate_from_response(response)
+      end
+
+      def update(id, params)
+        response = patch("/crm/v3/objects/#{resource_name}/#{id}", body: { properties: params }.to_json)
+        raise Hubspot.error_from_response(response) unless response.success?
+
+        true
+      end
+
+      def archive(id)
+        response = delete("/crm/v3/objects/#{resource_name}/#{id}")
+        raise Hubspot.error_from_response(response) unless response.success?
+
+        true
+      end
+
+      def list(params = {})
+        PagedCollection.new(
+          url: "/crm/v3/objects/#{resource_name}",
+          params: params,
+          resource_class: self
+        )
+      end
+
+      # Get the complete list of fields (properties) for the object
+      def properties
+        @properties ||= begin
+          response = get("/crm/v3/properties/#{resource_name}")
+          handle_response(response)['results'].map { |hash| Property.new(hash) }
+        end
+      end
+
+      def custom_properties
+        properties.reject { |property| property['hubspotDefined'] }
+      end
+
+      def property(property_name)
+        properties.detect { |prop| prop.name == property_name }
+      end
+
+      # Simplified search interface
+      OPERATOR_MAP = {
+        '_contains' => 'CONTAINS_TOKEN',
+        '_gt' => 'GT',
+        '_lt' => 'LT',
+        '_gte' => 'GTE',
+        '_lte' => 'LTE',
+        '_neq' => 'NEQ',
+        '_in' => 'IN'
+      }.freeze
+
+      # rubocop:disable Metrics/MethodLength
+      def search(query:, properties: [], page_size: 100)
+        search_body = {}
+
+        # Add properties if specified
+        search_body[:properties] = properties unless properties.empty?
+
+        # Handle the query using case-when for RuboCop compliance
+        case query
+        when String
+          search_body[:query] = query
+        when Hash
+          search_body[:filterGroups] = build_filter_groups(query)
+        else
+          raise ArgumentError, 'query must be either a string or a hash'
+        end
+
+        # Add the page size (passed as limit to the API)
+        search_body[:limit] = page_size
+
+        # Perform the search and return a PagedCollection
+        PagedCollection.new(
+          url: "/crm/v3/objects/#{resource_name}/search",
+          params: search_body,
+          resource_class: self,
+          method: :post
+        )
+      end
+
+      # rubocop:enable Metrics/MethodLength
+
+      private
+
+      # Define the resource name based on the class
+      def resource_name
+        name = self.name.split('::').last.downcase
+        if name.end_with?('y')
+          name.gsub(/y$/, 'ies') # Company -> companies
+        else
+          "#{name}s" # Contact -> contacts, Deal -> deals
+        end
+      end
+
+      # Instantiate a single resource object from the response
+      def instantiate_from_response(response)
+        data = handle_response(response)
+        new(data) # Passing full response data to initialize
+      end
+
+      # Convert simple filters to HubSpot's filterGroups format
+      def build_filter_groups(filters)
+        filter_groups = [{ filters: [] }]
+
+        filters.each do |key, value|
+          property_name, operator = extract_property_and_operator(key)
+          filter_groups.first[:filters] << {
+            propertyName: property_name,
+            operator: operator,
+            value: value
+          }
+        end
+
+        filter_groups
+      end
+
+      # Extract property name and operator from the key
+      def extract_property_and_operator(key)
+        OPERATOR_MAP.each do |suffix, hubspot_operator|
+          return [key.to_s.sub(suffix, ''), hubspot_operator] if key.to_s.end_with?(suffix)
+        end
+
+        # Default to 'EQ' operator if no suffix is found
+        [key.to_s, 'EQ']
+      end
+    end
+
+    # rubocop:disable Ling/MissingSuper
+    def initialize(data = {})
+      @id = extract_id(data)
+      @properties = {}
+      @metadata = {}
+
+      if @id
+        initialize_from_api(data)
+      else
+        initialize_new_object(data)
+      end
+    end
+    # rubocop:enable Ling/MissingSuper
+
+    # Instance methods for update (or save)
+    def save
+      if persisted?
+        self.class.update(@id, @changes).tap do |result|
+          return false unless result
+
+          @properties.merge!(@changes)
+          @changes = {}
+        end
+      else
+        create_new
+      end
+    end
+
+    def persisted?
+      @id ? true : false
+    end
+
+    # Update the resource
+    def update(params)
+      raise 'Not able to update as not persisted' unless persisted?
+
+      params.each do |key, value|
+        send("#{key}=", value) # This will trigger the @changes tracking via method_missing
+      end
+
+      save
+    end
+
+    def delete
+      self.class.archive(id)
+    end
+    alias archive delete
+
+    # rubocop:disable Metrics/MethodLength
+    # Handle dynamic getter and setter methods with method_missing
+    def method_missing(method, *args)
+      method_name = method.to_s
+
+      # Handle setters
+      if method_name.end_with?('=')
+        attribute = method_name.chomp('=')
+        new_value = args.first
+
+        # Track changes only if the value has actually changed
+        if @properties[attribute] != new_value
+          @changes[attribute] = new_value
+        else
+          @changes.delete(attribute) # Remove from changes if it reverts to the original value
+        end
+
+        return new_value
+      # Handle getters
+      else
+        return @changes[method_name] if @changes.key?(method_name)
+        return @properties[method_name] if @properties.key?(method_name)
+      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
+
+    # Extract ID from data and convert to integer
+    def extract_id(data)
+      data['id'] ? data['id'].to_i : nil
+    end
+
+    # Initialize from API response, separating metadata from properties
+    def initialize_from_api(data)
+      @metadata = extract_metadata(data)
+      properties_data = data['properties'] || {}
+
+      properties_data.each do |key, value|
+        if METADATA_FIELDS.include?(key)
+          @metadata[key] = value
+        else
+          @properties[key] = value
+        end
+      end
+
+      @changes = {}
+    end
+
+    # Initialize a new object (no API response)
+    def initialize_new_object(data)
+      @properties = {}
+      @changes = data.transform_keys(&:to_s)
+      @metadata = {}
+    end
+
+    # Extract metadata from data, excluding properties
+    def extract_metadata(data)
+      data.reject { |key, _| key == 'properties' }
+    end
+
+    # Create a new resource
+    def create_new
+      created_resource = self.class.create(@changes)
+      @id = created_resource.id
+      @id ? true : false
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/hubspot/user.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Hubspot
+  class User < Resource
+  end
+
+  Owner = User  
+end

data/lib/hubspot/version.rb

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

data/lib/hubspot.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'hubspot/config'
+
+# Main Hubspot module
+module Hubspot
+  class << self
+    extend Forwardable
+
+    # Delegate logger to config.logger
+    def_delegator :config, :logger
+
+    attr_writer :config
+
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield(config) if block_given?
+      set_client_headers if config.access_token
+    end
+
+    def configured?
+      return true unless @config.nil?
+    end
+
+    private
+
+    # Set Authorization header on Hubspot::ApiClient when access_token is configured
+    def set_client_headers
+      Hubspot::ApiClient.headers 'Authorization' => "Bearer #{config.access_token}"
+    end
+  end
+end

data/lib/ruby_hubspot_api.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'logger'
+
+# Load the main Hubspot module, version and configuration
+require_relative 'hubspot'
+require_relative 'hubspot/version'
+require_relative 'hubspot/config'
+
+# define the exception classes, then load the main API client
+require_relative 'hubspot/exceptions'
+require_relative 'hubspot/api_client'
+
+# load base class then modules
+require_relative 'hubspot/resource'
+require_relative 'hubspot/property'
+require_relative 'hubspot/contact'
+require_relative 'hubspot/company'
+require_relative 'hubspot/user'
+
+# Load other components
+require_relative 'hubspot/paged_collection'

data/ruby_hubspot_api.gemspec

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hubspot/version'
+
+# rubocop:disable Metrics/BlockLength
+Gem::Specification.new do |spec|
+  spec.name          = 'ruby_hubspot_api'
+  spec.version       = Hubspot::VERSION
+  spec.authors       = ['Simon Brook']
+  spec.email         = ['simon@datanauts.co.uk']
+
+  spec.summary = 'ruby_hubspot_api is an ORM-like wrapper for the Hubspot API'
+  spec.description = 'ruby_hubspot_api is an ORM-like wrapper for v3 of the Hubspot API'
+  spec.homepage = 'https://github.com/sensadrome/ruby_hubspot_api'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 2.5'
+
+  # Prevent pushing this gem to RubyGems.org.
+  # To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    # spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+
+    spec.metadata['homepage_uri'] = spec.homepage
+    spec.metadata['changelog_uri'] = "#{spec.homepage}/CHANGELOG.md"
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Define development dependencies
+  spec.add_development_dependency 'rake', '>= 11.0', '< 14.0'
+
+  spec.add_dependency 'bundler', '~> 2.3', '< 3.0'
+  spec.add_dependency 'dotenv', '~> 2.8', '< 3.0'
+  spec.add_dependency 'pry', '~> 0.13', '< 1.0'
+  spec.add_dependency 'pry-byebug', '~> 3.9', '< 4.0'
+  spec.add_dependency 'rspec', '~> 3.13', '< 4.0'
+  spec.add_dependency 'simplecov', '~> 0.22', '< 1.0'
+  spec.add_dependency 'vcr', '~> 6.0', '< 7.0'
+  spec.add_dependency 'webmock', '~> 3.23', '< 4.0'
+
+  # Define runtime dependencies
+  spec.add_runtime_dependency 'httparty', '~> 0.21', '< 1.0'
+end
+# rubocop:enable Metrics/BlockLength