ruby_hubspot_api 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 62b690c7e426369cd5979c4f6b5b0cec8b5a7620
-  data.tar.gz: 26047bb4aa34d3a91bf6c1aff80b6e3775220f4f
+  metadata.gz: 1a2e9bcd6887d8ca6e6aadd20459732e94e76114
+  data.tar.gz: '02728d9515a0ef2b5d1eecd6b7b703c7ba9cddb1'
 SHA512:
-  metadata.gz: a6512174b13fa2ef07740690864c79a6c3593c908c1fed37170ef35bf08ca7ae5ceb9a3e53fe12d53079eb4e4bb47a58801430103b96c9a7b78dfd67eaaabaa5
-  data.tar.gz: 6ea719cb62b217fdbbdb2009d64215369608ba8d3423b59245472fb64fcd957174c5cc28a0cbcbd1f5eaf904260d19e1989da528df913292c139b5f4d893110e
+  metadata.gz: 054defa6af013acea911e6f671b4c4d0fb200c25bba22c2969f52cadefa7c5beb2d776989936fff62d573f173acdd85514d3ae1dc0a95d1d35958b5f7fab4f0b
+  data.tar.gz: 959a83f088e542877d37ed660b20a59c062c314c6ae9343bccbaf8eed6fd63e350566ce8591b982db6649b835c8c87257ca3dc726faeba7caf3da10a962246fc

data/.env.sample

@@ -8,33 +8,25 @@ export HUBSPOT_ACCESS_TOKEN=your_private_app_access_token
 export HUBSPOT_CLIENT_SECRET=your_client_secret
 export HUBSPOT_PORTAL_ID=portal_id
 
+export HUBSPOT_NO_AUTH_ACCESS_TOKEN=your_private_app_access_token_with_no_scopes
+
 # VCR configuration
 # record mode can be none, once, newepisodes or all (default none)
 # see https://andrewmcodes.gitbook.io/vcr/record_modes
-export VCR_RECORD_MODE=once
-# to allow new request set to true
-export VCR_ALLOW_REQUESTS=false
-
-# Used in specs....
-# The values of the following are the defaults if the env var is not set
 
-# Company id used to test find and update (should be real)
-export HUBSPOT_TEST_COMPANY_ID=1
+# export VCR_RECORD_MODE=once # (default)
+# export VCR_RECORD_MODE=all # always record http requests (overwrites)
 
-# Company name to test create company
-export HUBSPOT_TEST_COMPANY_NAME="Numenor Capital"
-
-# Company id to test deleting (hint: make a dummy one first!)
-export HUBSPOT_TEST_COMPANY_ID_DELETE=666
-
-# Contact if to test find and update
-export HUBSPOT_TEST_CONTACT_ID=1
+# to allow new request set to true
+export VCR_ALLOW_REQUESTS=false
 
-# domain name to test the search by email contains
-export HUBSPOT_SEARCH_TEST_DOMAIN=hubspot.com
+# SPECS:
+#   the following can be used when running the specs
 
-# maximum number of records to fetch when testing lists
-export HUBSPOT_SEARCH_LIMIT=5
+export HUBSPOT_LOG_LEVEL=FATAL # no output during testing (default)
+# export HUBSPOT_LOG_LEVEL=WARN # will show exceptions and batch load wait message
+# export HUBSPOT_LOG_LEVEL=INFO # adds api request descriptions
+# export HUBSPOT_LOG_LEVEL=DEBUG # adds api request body and full response (lots of output!)
 
-# email address for search on email = <email>
-export HUBSPOT_TEST_CONTACT_EMAIL=test@hubspot.com
+# How long to wait after a batch is created (for propagation)
+export HUBSPOT_BATCH_WAIT=0

data/.rspec

@@ -1,3 +1,4 @@
 --format documentation
 --color
 --require spec_helper
+--order random

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_hubspot_api (0.3.1)
+    ruby_hubspot_api (0.3.3)
       httparty (>= 0.1, < 1.0)
 
 GEM
@@ -40,12 +40,12 @@ GEM
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.1)
+    rspec-core (3.13.2)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.1)
+    rspec-mocks (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
@@ -62,8 +62,6 @@ GEM
 
 PLATFORMS
   ruby
-  x86_64-darwin-18
-  x86_64-linux
 
 DEPENDENCIES
   bundler (>= 2.0, < 2.4.0)
@@ -80,4 +78,4 @@ DEPENDENCIES
   webmock (>= 3.0)
 
 BUNDLED WITH
-   2.2.34
+   2.0.2

data/README.md

@@ -78,7 +78,7 @@ Hubspot::Company  # crm > companies
 Hubspot::User     # hubspot users (also referred to as 'owners')
 Hubspot::Owner    # alias of Hubspot::User if you prefer to use it
 ```
- 
+
 however you can [add custom objects of your own](#user-content-custom-resources) based on your own custom defined Objects in Hubspot
 
 ### Creating and Saving an Object
@@ -254,7 +254,7 @@ Example:
 
 ```ruby
 # Search for contacts with email containing "hubspot.com"
-contacts = Hubspot::Contact.search(query: { email_contains: 'hubspot.com' })
+contacts = Hubspot::Contact.search({ email_contains: 'hubspot.com' }, properties: %w[firstname lastname email])
 
 puts "Searching for Hubspot staff in the contacts CRM"
 puts ""
@@ -264,17 +264,18 @@ contacts.each do |contact|
 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} (#{company.number_of_employees} employees)"
+companies = Hubspot::Company.search(number_of_employees_gte: 100).all # returns a PagedCollection
+companies.each_page do |page_of_companies|
+  page_of_companies.each do |company|
+    puts "  Found: #{company.name} (#{company.number_of_employees} employees)"
+  end
 end
 
 # Search for contacts with email in a specific list (IN operator)
-contacts = Hubspot::Contact.search(query: { email_in: ['user1@example.com', 'user2@example.com'] })
+contacts = Hubspot::Contact.search(email: ['user1@example.com', 'user2@example.com'])
 
 contacts.each do |contact|
   puts "Found: #{contact.email}"
@@ -288,7 +289,6 @@ end
 - **gte**: Greater than or equal to.
 - **lt**: Less than.
 - **lte**: Less than or equal to.
-- **IN**: Matches any of the values in an array.
 
 #### Searching for empty values (NOT_HAS_PROPERTY)
 
@@ -296,7 +296,7 @@ Any empty value in your search will be matched using the correect filter in Hubs
 
 ```ruby
 # Search for companies with no value for a given field
-companies = Hubspot::Company.search(query: { client_category: nil }, properties: %w[name number_of_employees])
+companies = Hubspot::Company.search({ client_category: nil }, properties: %w[name number_of_employees])
 # Request body: {"filterGroups":[{"filters":[{"propertyName":"client_category","operator":"NOT_HAS_PROPERTY"}]}]
 
 puts "Searching for uncategorised customers"
@@ -310,6 +310,47 @@ companies.each do |company|
 end
 ```
 
+#### Searching for any value in an array (IN)
+
+If value is an array the operator will be set to 'IN'
+
+```ruby
+# Search for companies with no value for a given field
+hot_contacts = Hubspot::Contact.search(hs_lead_status: %w[IN_PROGRESS OPEN_DEAL])
+# Request body: {"filterGroups":[{"filters":[{"propertyName":"hs_lead_status","operator":"IN","values":["IN_PROGRESS", "OPEN_DEAL"]}]}]
+
+puts "Current best leads"
+puts ""
+
+hot_contacts.each do |contact|
+  puts "#{contact.name} .... "
+end
+
+```
+
+#### Chaining search conditions (a la Active Record)
+
+You can use the alternative Rails-like interface to return a PagedCollection and can chain calls. Use `where(search_params)` to filter and `.select('firstname', 'lastname', 'email', 'custom_property')` to determine the properties returned by the API.
+
+```ruby
+contact = Hubspot::Contact.where(hs_lead_status: [])
+```
+
+#### Getting the total number of records
+
+Having created a search collection you can retrieve the total number of matching records from Hubspot by calling .total on the collection. This will make a single request to the api to retrieve the number of matching records
+
+```ruby
+contacts_collection = Hubspot::Contact.search(lead_status: 'cold')
+
+if contacts_collection.total > 200
+  puts "Contacts will be processed overnight"
+  # schedule_processing_job
+else
+  puts "Found #{contacts_collection.total} contacts. Processing...."
+  process_contacts(contacts_collection)
+```
+
 #### Specifying Properties in Search
 
 When performing a search, you can also specify which properties to return.
@@ -320,7 +361,7 @@ Example:
 ```ruby
 # Search for contacts with email containing "hubspot.com" and only return specific properties
 contacts = Hubspot::Contact.search(
-  query: { email_contains: 'hubspot.com' },
+  { email_contains: 'hubspot.com' },
   properties: ['firstname', 'lastname', 'email', 'mobile', 'custom_property_1']
 )
 
@@ -383,7 +424,7 @@ 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 
+By using this method you can page through the results as needed or collect them
 
 ```ruby
 email_addresses = my_selected_contacts.collect(&:email).compact
@@ -400,7 +441,7 @@ batch.each_page do |contacts|
 end
 ```
 
-Finally there is another helper method `batch_read_all` on any Hubspot::Resource class (Hubspot::Contact, Hubspot::Company, Hubspot::User etc) which will read all of the resources and return a HubSpot::Batch (with all of the resources). 
+Finally there is another helper method `batch_read_all` on any Hubspot::Resource class (Hubspot::Contact, Hubspot::Company, Hubspot::User etc) which will read all of the resources and return a HubSpot::Batch (with all of the resources).
 
 You can then update the resources and call `update` on the batch.... see below
 
@@ -456,7 +497,7 @@ In this example, if a contact with the given email already exists in HubSpot, it
 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
+contacts = Hubspot::Contact.where(email_contains: 'hubspot.com').all
 
 batch = Hubspot::Batch.new(contacts)
 batch.archive
@@ -489,7 +530,7 @@ require 'ruby_hubspot_api' # if not required by bundler already...
 
 module Hubspot
   class Project < Resource
-    
+
     # resource_name (part of the url in the api) will default
     # to a simple plural of the class name - in this case 'projects'
     # if the url for your custom object is different you can override it
@@ -500,7 +541,7 @@ module Hubspot
   end
 end
 
-projects = Hubspot::Projects.search(query: { status_in: ['upcoming', 'active', 'overrun'] }).all
+projects = Hubspot::Projects.where(status: ['upcoming', 'active', 'overrun']).all
 
 ```
 

data/lib/hubspot/exceptions.rb

@@ -7,7 +7,9 @@ module Hubspot
     attr_accessor :response
 
     def initialize(response, message = nil)
-      message = response.parsed_response['message'] if !message && response.respond_to?(:parsed_response)
+      if !message && response.respond_to?(:parsed_response)
+        message = response.parsed_response['message']
+      end
       message += "\n" if message
       me = super("#{message}Response body: #{response.body}",)
       me.response = response
@@ -20,6 +22,7 @@ module Hubspot
   class NotConfiguredError < StandardError; end
   class ArgumentError < StandardError; end
   class NothingToDoError < StandardError; end
+  class NotImplementedError < StandardError; end
 
   class << self
     def error_from_response(response)

data/lib/hubspot/form.rb

@@ -2,8 +2,6 @@
 
 module Hubspot
   class Form < Resource
-    METADATA_FIELDS = %w[createdAt updatedAt archived].freeze
-
     # :nocov:
     def inspect
       "#<#{self.class.name} " \
@@ -13,6 +11,8 @@ module Hubspot
     # :nocov:
 
     class << self
+      private
+
       def api_root
         '/marketing/v3'
       end
@@ -24,5 +24,9 @@ module Hubspot
     def extract_id(id)
       id
     end
+
+    def metadata_fields
+      %w[createdAt updatedAt archived].freeze
+    end
   end
 end

data/lib/hubspot/paged_collection.rb

@@ -3,27 +3,38 @@
 require 'json'
 require_relative './api_client'
 require_relative './exceptions'
+require_relative './resource_filter'
 
 module Hubspot
   # Enumerable class for handling paged data from the API
   class PagedCollection < ApiClient
     include Enumerable
+    include ResourceFilter::FilterGroupMethods
 
-    MAX_LIMIT = 100 # HubSpot max items per page
+    MAX_LIMIT = 200 # HubSpot max items per page
 
-    def initialize(url:, params: {}, resource_class: nil, method: :get)
+    # rubocop:disable Lint/MissingSuper
+    def initialize(url:, params: {}, resource_class: nil, method: :get, results_param: 'results')
       @url = url
       @params = params
       @resource_class = resource_class
       @method = method.to_sym
+      @results_param = results_param
+    end
+    # rubocop:enable Lint/MissingSuper
+
+    def total
+      @total ||= determine_total
     end
 
     def each_page
       offset = nil
       loop do
         response = fetch_page(offset)
+        @total = response['total'] if response['total']
         mapped_results = process_results(response)
         yield mapped_results unless mapped_results.empty?
+        sleep wait_between_pages
         offset = response.dig('paging', 'next', 'after')
         break unless offset
       end
@@ -38,10 +49,12 @@ module Hubspot
     end
 
     # Override Enumerable's first method so as not to have to call each (via all)
+    # rubocop:disable Metrics/MethodLength
     def first(limit = 1)
       resources = []
       remaining = limit
 
+      original_limit = @params.delete(:limit)
       # Modify @params directly to set the limit
       @params[:limit] = [remaining, MAX_LIMIT].min
 
@@ -52,8 +65,10 @@ module Hubspot
         break if remaining <= 0
       end
 
+      @params[:limit] = original_limit
       limit == 1 ? resources.first : resources.first(limit)
     end
+    # rubocop:enable Metrics/MethodLength
 
     def each(&block)
       each_page do |page|
@@ -61,8 +76,63 @@ module Hubspot
       end
     end
 
+    def where(filters = {})
+      dup.where!(filters)
+    end
+
+    def where!(filters = {})
+      # Build new filter groups from the provided filters
+      new_filter_groups = build_filter_groups(filters)
+
+      # Merge new filters into the existing params structure
+      if @params[:filterGroups]&.any?
+        @params[:filterGroups][0][:filters].concat(new_filter_groups[0][:filters])
+      else
+        @params[:filterGroups] = new_filter_groups
+      end
+
+      self # Returning self for method chaining if needed
+    end
+
+    def select(*properties)
+      unless properties.blank?
+        @params ||= {}
+        @params[:properties] ||= []
+        @params[:properties].concat(properties.flatten)
+      end
+
+      self
+    end
+
     private
 
+    def determine_total
+      # We only get a response['total'] for the search endpoint
+      raise NotImplementedError, 'Total only available for search requests' unless search_request?
+
+      # if we don't already know the total we will make a single request and minimise the response
+      # size by asking for just one property and one record.
+
+      # store the current properties
+      original_properties = @params.delete(:properties)
+
+      # just request hs_object_id
+      @params[:properties] = ['hs_object_id']
+
+      # dummy request. @total will be set during the each_page evaluation
+      _first_page = first
+
+      # restore the original properties
+      @params[:properties] = original_properties
+
+      # return the now set total
+      @total
+    end
+
+    def search_request?
+      @url.include?('/search')
+    end
+
     def fetch_page(offset)
       params_with_offset = @params.dup
       params_with_offset.merge!(after: offset) if offset
@@ -82,8 +152,14 @@ module Hubspot
       end
     end
 
+    def wait_between_pages
+      return 0.2 if search_request?
+
+      0
+    end
+
     def process_results(response)
-      results = response['results'] || []
+      results = response[@results_param] || []
       return results unless @resource_class
 
       results.map { |result| @resource_class.new(result) }

data/lib/hubspot/resource.rb

@@ -3,6 +3,7 @@
 require_relative './api_client'
 require_relative './paged_collection'
 require_relative './paged_batch'
+require_relative './resource_filter'
 
 module Hubspot
   # rubocop:disable Metrics/ClassLength
@@ -26,6 +27,7 @@ module Hubspot
   #
   class Resource < ApiClient
     METADATA_FIELDS = %w[createdate hs_object_id lastmodifieddate].freeze
+    extend ResourceFilter::FilterGroupMethods
 
     # Allow read/write access to id, properties, changes and metadata
 
@@ -42,6 +44,62 @@ module Hubspot
     attr_accessor :metadata
 
     class << self
+      # Return a paged_collection - similar to an ActiveRecord Relation
+      #
+      # Example:
+      #   contacts_collection = Hubspot::Contact.all
+      #     <PagedCollection>
+      #
+      #   contacts_collection.where(email_contains: 'hubspot.com')
+      #     <PagedCollection, @params={:filterGroups=> ....
+      def all
+        PagedCollection.new(
+          url: "#{api_root}/#{resource_name}/search",
+          params: {},
+          resource_class: self,
+          method: :post,
+          results_param: results_param
+        )
+      end
+
+      # Filter resources - allows chaining
+      #
+      # This method allows searching for resources by passing a hash with special suffixes
+      # on the keys to define different comparison operators.
+      #
+      # Available suffixes for query keys (when using a hash):
+      #   - `_contains`: Matches values that contain the given string.
+      #   - `_gt`: Greater than comparison.
+      #   - `_lt`: Less than comparison.
+      #   - `_gte`: Greater than or equal to comparison.
+      #   - `_lte`: Less than or equal to comparison.
+      #   - `_neq`: Not equal to comparison.
+      #
+      # If value is an array the 'IN' operator will be used
+      #
+      # Otherwise if no suffix is provided, the default comparison is equality (`EQ`).
+      #
+      # If no value is provided, or is empty the NOT_HAS_PROPERTY operator will be used
+      #
+      # filters - [Hash] The query for searching.
+      #                  each key represents a property and may have suffixes for the comparison
+      #                  (e.g., `{ email_contains: 'example.org', age_gt: 30 }`).
+
+      # Example:
+      #
+      #   big_companies = Hubspot:Company.where(number_of_employees_gte: 100 )
+      #   live_contacts = Hubspot::Contact.where(hs_lead_status: %w[NEW OPEN IN_PROGRESS])
+      #
+      # Returns a PagedCollection
+      def where(filters = {})
+        all.where!(filters)
+      end
+
+      # Select which properties to return from the api - allows chaining
+      def select(*properties)
+        all.select(*properties)
+      end
+
       # Find a resource by ID and return an instance of the class
       #
       # id - [Integer] The ID (or hs_object_id) of the resource to fetch.
@@ -53,11 +111,14 @@ module Hubspot
       #
       # Returns An instance of the resource.
       def find(id, properties: nil)
-        all_properties = build_property_list(properties)
-        if all_properties.is_a?(Array) && !all_properties.empty?
-          params = { query: { properties: all_properties } }
-        end
-        response = get("#{api_root}/#{resource_name}/#{id}", params || {})
+        response = response_for_find_by_id(id, properties: properties)
+        return if response.not_found?
+
+        instantiate_from_response(response)
+      end
+
+      def find!(id, properties: nil)
+        response = response_for_find_by_id(id, properties: properties)
         instantiate_from_response(response)
       end
 
@@ -69,16 +130,16 @@ module Hubspot
       #
       # Example:
       #   properties = %w[firstname lastname email last_contacted]
-      #   contact = Hubspot::Contact.find_by("email", "john@example.com", properties)
+      #   contact = Hubspot::Contact.find_by("email", "john@example.com", properties: properties)
       #
       # Returns An instance of the resource.
-      def find_by(property, value, properties = nil)
-        params = { idProperty: property }
-
-        all_properties = build_property_list(properties)
-        params[:properties] = all_properties unless all_properties.empty?
+      def find_by(property, value, properties: nil)
+        response = response_for_find_by_property(property, value, properties: properties)
+        instantiate_from_response(response) unless response.not_found?
+      end
 
-        response = get("#{api_root}/#{resource_name}/#{value}", query: params)
+      def find_by!(property, value, properties: nil)
+        response = response_for_find_by_property(property, value, properties: properties)
         instantiate_from_response(response)
       end
 
@@ -231,17 +292,6 @@ module Hubspot
         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
 
       # Search for resources using a flexible query format and optional properties.
@@ -287,11 +337,11 @@ module Hubspot
       #   )
       #
       # Returns [PagedCollection] A paged collection of results that can be iterated over.
-      def search(query:, properties: [], page_size: 100)
+      def search(query, properties: [], page_size: 200)
         search_body = {}
 
         # Add properties if specified
-        search_body[:properties] = properties unless properties.empty?
+        search_body[:properties] = build_property_list(properties) unless properties.empty?
 
         # Handle the query using case-when for RuboCop compliance
         case query
@@ -311,16 +361,12 @@ module Hubspot
           url: "#{api_root}/#{resource_name}/search",
           params: search_body,
           resource_class: self,
-          method: :post
+          method: :post,
+          results_param: results_param
         )
       end
-
       # rubocop:enable Metrics/MethodLength
 
-      # The root of the api call. Mostly this will be "crm"
-      # but you can override this to account for a different
-      # object hierarchy
-
       # Define the resource name based on the class
       def resource_name
         name = self.name.split('::').last.downcase
@@ -339,49 +385,44 @@ module Hubspot
 
       private
 
+      # The root of the api call. Mostly this will be "crm"
+      # but you can override this to account for a different
+      # object hierarchy
       def api_root
         '/crm/v3/objects'
       end
 
-      def list_page_uri
-        "#{api_root}/#{resource_name}"
+      # In the response from the api the resources returned in this key
+      def results_param
+        'results'
       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
+      def list_page_uri
+        "#{api_root}/#{resource_name}"
       end
 
-      # Convert simple filters to HubSpot's filterGroups format
-      def build_filter_groups(filters)
-        filter_groups = [{ filters: [] }]
-
-        filters.each do |key, value|
-          filter = extract_property_and_operator(key, value)
-          value_key = value.is_a?(Array) ? :values : :value
-          filter[value_key] = value unless value.blank?
-          filter_groups.first[:filters] << filter
+      def response_for_find_by_id(id, properties: nil)
+        all_properties = build_property_list(properties)
+        if all_properties.is_a?(Array) && !all_properties.empty?
+          params = { query: { properties: all_properties } }
         end
 
-        filter_groups
+        get("#{api_root}/#{resource_name}/#{id}", params || {})
       end
 
-      # Extract property name and operator from the key
-      def extract_property_and_operator(key, value)
-        return { propertyName: key.to_s, operator: 'NOT_HAS_PROPERTY' } if value.blank?
+      def response_for_find_by_property(property, value, properties: nil)
+        params = { idProperty: property }
+
+        all_properties = build_property_list(properties)
+        params[:properties] = all_properties unless all_properties.empty?
 
-        OPERATOR_MAP.each do |suffix, hubspot_operator|
-          if key.to_s.end_with?(suffix)
-            return {
-              propertyName: key.to_s.sub(suffix, ''),
-              operator: hubspot_operator
-            }
-          end
-        end
+        get("#{api_root}/#{resource_name}/#{value}", query: params)
+      end
 
-        # Default to 'EQ' operator if no suffix is found
-        { propertyName: key.to_s, operator: 'EQ' }
+      # 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
 
       # Internal make a list of properties to request from the API
@@ -420,7 +461,7 @@ module Hubspot
     #   existing_contact = Hubspot::Contact.new(id: hubspot_id, properties: contact.to_hubspot)
     def initialize(data = {})
       data.transform_keys!(&:to_s)
-      @id = extract_id(data.delete('id'))
+      @id = extract_id(data.delete(api_id_field))
       @properties = {}
       @metadata = {}
       if @id
@@ -571,6 +612,10 @@ module Hubspot
 
     private
 
+    def api_id_field
+      'id'
+    end
+
     # Extract ID from data and convert to integer
     def extract_id(id)
       id&.to_i
@@ -616,9 +661,13 @@ module Hubspot
       end
     end
 
-    # allows overwriting in other resource classes
     def metadata_field?(key)
-      METADATA_FIELDS.include?(key)
+      metadata_fields.include?(key)
+    end
+
+    # allows overwriting in other resource classes
+    def metadata_fields
+      METADATA_FIELDS
     end
 
     # Initialize a new object (no API response)

data/lib/hubspot/resource_filter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Hubspot
+  module ResourceFilter
+    module FilterGroupMethods
+      # Simplified search interface
+      OPERATOR_MAP = {
+        '_contains' => 'CONTAINS_TOKEN',
+        '_gt' => 'GT',
+        '_lt' => 'LT',
+        '_gte' => 'GTE',
+        '_lte' => 'LTE',
+        '_neq' => 'NEQ',
+        '_in' => 'IN'
+      }.freeze
+
+      # Convert simple filters to HubSpot's filterGroups format
+      def build_filter_groups(filters)
+        filter_groups = [{ filters: [] }]
+
+        filters.each do |key, value|
+          filter = extract_property_and_operator(key, value)
+          value_key = value.is_a?(Array) ? :values : :value
+          filter[value_key] = value unless value.blank?
+          filter_groups.first[:filters] << filter
+        end
+
+        filter_groups
+      end
+
+      # Extract property name and operator from the key
+      def extract_property_and_operator(key, value)
+        return { propertyName: key.to_s, operator: 'NOT_HAS_PROPERTY' } if value.blank?
+
+        OPERATOR_MAP.each do |suffix, hubspot_operator|
+          if key.to_s.end_with?(suffix)
+            return {
+              propertyName: key.to_s.sub(suffix, ''),
+              operator: hubspot_operator
+            }
+          end
+        end
+
+        # Default to 'EQ' operator if no suffix is found
+        { propertyName: key.to_s, operator: 'EQ' }
+      end
+    end
+  end
+end

data/lib/hubspot/version.rb

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

data/lib/hubspot.rb

@@ -24,14 +24,20 @@ module Hubspot
     end
 
     def configured?
-      return true unless @config.nil?
+      true unless @config.nil?
     end
 
     private
 
-    # Set Authorization header on Hubspot::ApiClient when access_token is configured
+    # Set Authorization header on all the resource classes when access_token is configured
     def set_client_headers
-      Hubspot::ApiClient.headers 'Authorization' => "Bearer #{config.access_token}"
+      api_classes = ObjectSpace.each_object(Class).select do |klass|
+        klass < Hubspot::ApiClient && !klass.singleton_class?
+      end
+
+      api_classes.each do |subclass|
+        subclass.headers 'Authorization' => "Bearer #{config.access_token}"
+      end
     end
 
     def set_request_timeouts

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_hubspot_api
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - Simon Brook
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-10-16 00:00:00.000000000 Z
+date: 2024-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -228,6 +228,7 @@ files:
 - lib/hubspot/paged_collection.rb
 - lib/hubspot/property.rb
 - lib/hubspot/resource.rb
+- lib/hubspot/resource_filter.rb
 - lib/hubspot/user.rb
 - lib/hubspot/version.rb
 - lib/ruby_hubspot_api.rb