ruby_hubspot_api 0.2.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ae46636189d9ad859e0e342eed9b752ccbd64c06
-  data.tar.gz: 3cf0de6c387b00810af776e6b4ff89bcdcc00230
+  metadata.gz: 6052dfd71294e988924beeab1b89662673ceaf93
+  data.tar.gz: 4b2e295931295d639e473a9b139df03ec7df1554
 SHA512:
-  metadata.gz: ebdaa4d4f2bb6f1f7b6c9fede064598daf78edcf2204322819d2a13e7dbd504ff1792a7afd75037a4eae24171cd9b52d962dc6e2eb7439fe5bb9a84ad6733a22
-  data.tar.gz: fa2dd031fa494b3bd8c68880d68aa19603035bbf32395a7e3650eefa8906507d6e0790020e032002612d59c516c5eb97b371b69f2f1ff563a4819006aa5d6180
+  metadata.gz: caee0d8350205b6bcf45bb4ed4b5421f3fdaacaff87acfcb52c4845858bbafb664f70acbca1a564a34a99a166fd1072a838702d4bf4044b076cfd0b77e87f6a7
+  data.tar.gz: 28cbb5b1ea5ebc076d7177e8f4ee35f450bbe7fbb33224a31c55f0801fc566b705cf9b65faf95453b91154675139fb33cfce557ea74e06afd001a09f710190bf

data/.github/workflows/ruby.yml

@@ -41,7 +41,7 @@ jobs:
       env:
         CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-    - name: Upload coverage to Codacy
-      run: bash <(curl -Ls https://coverage.codacy.com/get.sh)
-      env:
-        CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}
+    # - name: Upload coverage to Codacy
+    #   run: bash <(curl -Ls https://coverage.codacy.com/get.sh)
+    #   env:
+    #     CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}

data/.gitignore

@@ -1,7 +1,7 @@
 /.bundle/
 /coverage/
 /tmp/
-
+*.gem
 .env
 # rspec failure tracking
 .rspec_status

data/.rubocop.yml

@@ -1,6 +1,19 @@
-# .rubocop.yml
+Documentation:
+    Enabled: false
+
+Metrics/LineLength:
+  Max: 100
+  Exclude:
+    - spec/**/*.rb
+
+# Metrics/MethodLength:
+#   Max: 20
+
+# Metrics/ClassLength:
+#   Max: 200
 
-# Ignore Metrics/BlockLength for the spec directory
 Metrics/BlockLength:
-  Exclude: 
-    - spec/**/*.rb
+  #   Max: 50
+  # Ignore Metrics/BlockLength for the spec directory
+  Exclude:
+    - spec/**/*.rb

data/CHANGELOG.md

@@ -1,4 +1,61 @@
-## v.0.2.0
+
+## v0.3.0
+
+- Clarify usage
+- More usage clarification
+- Create ruby.yml
+- fix the github workflow
+- fix the github workflow properly
+- add plaatforms to Gemfile.lock
+- add ruby 2.5 and reduce log output
+- try calling rspec directly
+- Use ERB in VCR tests so as to be independent of the env vars
+- ignore ruby version file
+- test on ruby 3.0 too
+- determine if a Hubspot property is read_only (or by negation updatable)
+- adding codecov
+- Using earlier bundler
+- Adding lcov format
+- Add read-only properties to resource class
+- Add property check to the contact spec
+- Only apply lcov formatter if running on github
+- try to upload the coverage results to codacy too
+- Adding Codacy badge
+- Ensure we always apply the right log_level
+- Tidy up documentation of resource
+- Yep. Back ported to 2.4
+- adjust some rubocop settings
+- Tidy up somer doc comments
+- Add some handling of required properties
+- Update user model to force specific properties to be retrieved
+- Improve logic of resource matching
+- Adds  :sparkle: attributes method to a resource
+- Tidy comments
+- Update the hierarchy to allow more flexibility
+- Fix find resources
+- Clear up processing results
+- Update batch spec
+- Bump the version
+- Adds validation for resource matcher
+- Dynamically add a method to batch to allow "resources" to be referred to as the resource_name
+- Ignore gem files
+- Drop cadacy for now
+- Update batch spec to check resource_matcher works
+- Ensure properties are passed as named argument
+- No cov for inspect
+- Allow ERB in json fixtures
+- Contact find_by_token spec
+- find_by_token method - uses v1 API
+- Tests the method missing setter for resource
+- Sanitize web mock output
+- Finish specs
+- check the env vars before sanitising
+- make erb explicitly determined by the file exension (.json.erb)
+- use safe navigation for extracting id
+- bump version
+- update gem version in lock file
+
+## v0.2.0
 
 - Get the development dependencies right!
 - Bump the version again
@@ -21,11 +78,23 @@
 - Simplify mocked responses in batch spec
 - Adds PagedBatch as pager for batch/read request
 - Update the Readme to add Batch operations
-- #5 batch_updating
+- bump version
 
 ## v0.1.2
 
-- initial setup
+- Fix the Readme
+- Sure the search param is values where passing an array
+- update changelog and Gemfile.lock
+- bump version
+
+## v0.1.1
+
+- adds the version numbers to the gemspec
+- Fix dependencies
+- bump version
+
+## v0.1.0
+
 - Setup the configuration block
 - Adds spec for config
 - Set the auth headers when access_token configured
@@ -67,23 +136,4 @@
 - Flatten the properties array into a comma separated list
 - Improve the intialiser
 - Update the changeling and link in gem spec
-- 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
-
-- adds the version numbers to the gemspec
-- Fix dependencies
-- bump version

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_hubspot_api (0.2.1)
+    ruby_hubspot_api (0.3.0)
       httparty (>= 0.1, < 1.0)
 
 GEM

data/lib/hubspot/api_client.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # HubSpot API Client
-# Handles all HTTP interactions with the HubSpot API. It manages GET, POST, PATCH, and DELETE requests.
+# 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
@@ -59,10 +60,14 @@ module Hubspot
 
       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.info(
+          "#{http_method.to_s.upcase} #{url} took #{d.round(2)}s with status #{response.code}"
+        )
+
         return unless Hubspot.logger.debug?
 
-        Hubspot.logger.debug("Request body: #{extra}") if extra
+        Hubspot.logger.debug("Request body: #{extra[:body]}") if extra
         Hubspot.logger.debug("Response body: #{response.body}")
       end
 
@@ -93,7 +98,7 @@ module Hubspot
 
       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
+        http_method = request.http_method::METHOD.downcase
         response = HTTParty.send(http_method, request.uri, request.options)
         handle_response(response, retries)
       end

data/lib/hubspot/batch.rb

@@ -31,8 +31,20 @@ module Hubspot
     CONTACT_LIMIT = 10
     DEFAULT_LIMIT = 100
 
+    # :nocov:
+    def inspect
+      "#<#{self.class.name} " \
+      "@resource_count=#{@resources.size}, " \
+      "@id_property=#{@id_property.inspect}, " \
+      "@resource_type=#{@resources.first&.resource_name}, " \
+      "@responses_count=#{@responses.size}>"
+    end
+    # :nocov:
+
     # rubocop:disable Lint/MissingSuper
-    def initialize(resources = [], id_property: 'id')
+    def initialize(resources = [], id_property: 'id', resource_matcher: nil)
+      validate_resource_matcher(resource_matcher)
+
       @resources = []
       @id_property = id_property # Set id_property for the batch (default: 'id')
       @responses = []            # Store multiple BatchResponse objects here
@@ -51,11 +63,23 @@ module Hubspot
     end
 
     # Upsert method that calls save with upsert action
-    def upsert
+    def upsert(resource_matcher: nil)
+      validate_resource_matcher(resource_matcher)
+
       validate_upsert_conditions
       save(action: 'upsert')
     end
 
+    def validate_resource_matcher(resource_matcher)
+      return if resource_matcher.blank?
+
+      unless resource_matcher.is_a?(Proc) && resource_matcher.arity == 2
+        raise ArgumentError, 'resource_matcher must be a proc that accepts exactly 2 arguments'
+      end
+
+      @resource_matcher = resource_matcher
+    end
+
     # Archive method
     def archive
       save(action: 'archive')
@@ -77,15 +101,29 @@ module Hubspot
     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'
+      if @resources.any?
+        if @resources.first.resource_name != resource.resource_name
+          raise ArgumentError, 'All resources in a batch must be of the same type'
+        end
+      else
+        add_resource_method(resource.resource_name)
       end
 
       @resources << resource
     end
 
+    def any_changes?
+      @resources.any?(&:changes?)
+    end
+
     private
 
+    def add_resource_method(resource_name)
+      self.class.class_eval do
+        alias_method resource_name.to_sym, :resources
+      end
+    end
+
     # rubocop:disable Metrics/MethodLength
     def save(action: 'update')
       @action = action
@@ -122,9 +160,12 @@ module Hubspot
         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
+          # Dynamically get the ID based on the batch's id_property
+          id: resource.public_send(@id_property),
+          # Use the helper method to decide whether to include idProperty
+          idProperty: determine_id_property,
+          # Gather the changes for the resource
+          properties: resource.changes
         }.compact   # Removes nil keys
       end.compact   # Removes nil entries
     end
@@ -146,7 +187,8 @@ module Hubspot
 
     # 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)
+      response = self.class.post("/crm/v3/objects/#{type}/batch/#{action}",
+                                 body: { inputs: inputs }.to_json)
       BatchResponse.new(response.code, handle_response(response))
     end
 
@@ -157,7 +199,8 @@ module Hubspot
       # 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"
+      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
@@ -167,6 +210,8 @@ module Hubspot
 
     # Process responses from the batch API call
     def process_responses
+      # TODO: issue a warning if the id_property is email and the action is upsert*
+      # people may have more than one email address abd Hubspot views that as one record
       @responses.each do |response|
         next unless response['results']
 
@@ -192,36 +237,56 @@ module Hubspot
     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
+      action_method = method_for_action
+      send(action_method, result) if action_method
+    end
+
+    def method_for_action
+      {
+        'create' => :find_resource_for_created_result,
+        'update' => :find_resource_from_updated_result,
+        'upsert' => :find_resource_from_upserted_result
+      }[@action]
+    end
+
+    def find_resource_for_created_result(result)
+      properties = result['properties']
+
+      @resources.reject(&:persisted?).find do |resource|
+        next unless resource.changes.any?
+
+        resource.changes.all? { |key, value| properties[key.to_s] == value }
       end
     end
 
+    def find_resource_from_updated_result(result)
+      resource_id = id_property == 'id' ? result['id'].to_i : result.dig('properties', id_property)
+      find_resource_from_id(resource_id)
+    end
+
     def find_resource_from_id(resource_id)
-      @resources.find { |r| r.id == resource_id }
+      return find_resource_from_id_property(resource_id) unless @id_property == 'id'
+
+      @resources.find { |resource| resource.id == resource_id }
+    end
+
+    def find_resource_from_id_property(resource_id)
+      @resources.find do |resource|
+        resource.respond_to?(@id_property) && resource.public_send(@id_property) == resource_id
+      end
     end
 
-    # def find_resource_from_id_property(resource_id)
-    #   @resources.find { |r| r.public_send(@id_property) == resource_id }
-    # end
+    def find_resource_from_upserted_result(result)
+      # if this was inserted then match on all the fields
+      return find_resource_for_created_result(result['properties']) if result['new']
+
+      # call the custom resource matcher if specified
+      if @resource_matcher
+        @resources.find { |resource| @resource_matcher.call(resource, result) }
+      else
+        find_resource_from_updated_result(result)
+      end
+    end
 
     def update_resource_properties(resource, properties)
       properties.each do |key, value|
@@ -237,11 +302,15 @@ module Hubspot
     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
+      def read(object_class, object_ids = [], properties: [], id_property: 'id')
+        unless object_class < Hubspot::Resource
+          raise ArgumentError, 'Must be a valid Hubspot resource class'
+        end
 
         # fetch all the matching resources with paging handled
-        resources = object_class.batch_read(object_ids, id_property: id_property).all
+        resources = object_class.batch_read(object_ids,
+                                            properties: properties,
+                                            id_property: id_property).all
 
         # return instance of Hubspot::Batch with the resources set
         new(resources, id_property: id_property)

data/lib/hubspot/contact.rb

@@ -2,5 +2,68 @@
 
 module Hubspot
   class Contact < Resource
+    # def required_properties
+    #   %w[email firstname lastname]
+    # end
+
+    private
+
+    def metadata_field?(key)
+      METADATA_FIELDS.include?(key) || key.start_with?('hs_')
+    end
+
+    class << self
+      # Finds a contact by the hubspotutk cookie
+      #
+      # token - the hubspot tracking token (stored from the hubspotutk cookie value)
+      # properties: - Optional list of properties to return.
+      #   Note: If properties are specified 2 calls to the api will be made because
+      #   at this time you can only search by the token using the v1 api
+      #   from which we
+      #
+      # Example:
+      #   properties = %w[firstname lastname email last_contacted]
+      #   contact = Hubspot::Contact.find_by_token(hubspotutk_cookie_value, properties)
+      #
+      # Returns An instance of the resource.
+      def find_by_token(token, properties: [])
+        all_properties = build_property_list(properties)
+        query_props = all_properties.map { |prop| "property=#{prop}" }
+        query_string = query_props.concat(['propertyMode=value_only']).join('&')
+
+        # Make the original API request, manually appending the query string
+        response = get("/contacts/v1/contact/utk/#{token}/profile?#{query_string}")
+
+        # Only modify the response if it's successful (status 200 OK)
+        if response.success?
+          # Convert the v1 response body (parsed_response) to a v3 structure
+          v3_response_hash = convert_v1_response(response.parsed_response, all_properties)
+
+          # Modify the existing response object by updating its `parsed_response`
+          response.instance_variable_set(:@parsed_response, v3_response_hash)
+        end
+
+        # Pass the (potentially modified) HTTParty response to the next step
+        instantiate_from_response(response)
+      end
+
+      private
+
+      def convert_v1_response(v1_response, property_list)
+        # Extract the `vid` as `id`
+        v3_response = {
+          'id' => v1_response['vid']
+        }
+
+        properties = property_list.each_with_object({}) do |property, hash|
+          hash[property] = v1_response.dig('properties', property, 'value')
+        end
+
+        # Build the v3 structure
+        v3_response['properties'] = properties
+
+        v3_response
+      end
+    end
   end
 end

data/lib/hubspot/form.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Hubspot
+  class Form < Resource
+    METADATA_FIELDS = %w[createdAt updatedAt archived].freeze
+
+    # :nocov:
+    def inspect
+      "#<#{self.class.name} " \
+      "@name=#{name}, " \
+      "@fieldGroups=#{respond_to?('fieldGroups') ? fieldGroups.size : '-'}>"
+    end
+    # :nocov:
+
+    class << self
+      def api_root
+        '/marketing/v3'
+      end
+    end
+
+    private
+
+    # dont convert (from string)
+    def extract_id(id)
+      id
+    end
+  end
+end

data/lib/hubspot/paged_batch.rb

@@ -10,6 +10,16 @@ module Hubspot
 
     MAX_LIMIT = 100 # HubSpot max items per page
 
+    # :nocov:
+    def inspect
+      "#<#{self.class.name} " \
+      "@url=#{@url.inspect}, " \
+      "@params=#{@params.inspect}, " \
+      "@resource_class=#{@resource_class.inspect}, " \
+      "@object_ids_count=#{@object_ids.size}>"
+    end
+    # :nocov:
+
     # rubocop:disable Lint/MissingSuper
     def initialize(url:, params: {}, resource_class: nil, object_ids: [])
       @url = url
@@ -22,8 +32,7 @@ module Hubspot
     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
+        mapped_results = process_results(response)
         yield mapped_results unless mapped_results.empty?
       end
     end
@@ -45,12 +54,19 @@ module Hubspot
     private
 
     def fetch_page(object_ids)
-      params_with_ids = @params.dup
+      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
+
+    def process_results(response)
+      results = response['results'] || []
+      return results unless @resource_class
+
+      results.map { |result| @resource_class.new(result) }
+    end
   end
 end

data/lib/hubspot/paged_collection.rb

@@ -10,21 +10,18 @@ module Hubspot
 
     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
+        mapped_results = process_results(response)
         yield mapped_results unless mapped_results.empty?
         offset = response.dig('paging', 'next', 'after')
         break unless offset
@@ -83,5 +80,12 @@ module Hubspot
         self.class.send(@method, @url, body: params.to_json)
       end
     end
+
+    def process_results(response)
+      results = response['results'] || []
+      return results unless @resource_class
+
+      results.map { |result| @resource_class.new(result) }
+    end
   end
 end

data/lib/hubspot/resource.rb

@@ -6,71 +6,190 @@ require_relative './paged_batch'
 
 module Hubspot
   # rubocop:disable Metrics/ClassLength
-  # Hubspot::Resource class
+
+  # HubSpot Resource Base Class
+  # This class provides common functionality for interacting with
+  # HubSpot API resources such as Contacts, Companies, etc
+  #
+  # It supports common operations like finding, creating, updating,
+  # and deleting resources, as well as batch operations.
+  #
+  # This class is meant to be inherited by specific resources
+  # like `Hubspot::Contact`.
+  #
+  # Example Usage:
+  #   Hubspot::Contact.find(1)
+  #   contact.name # 'Luke'
+  #
+  #   company = Hubspot::Company.create(name: "Acme Corp")
+  #   company.id.nil? # false
+  #
   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
+    # Allow read/write access to id, properties, changes and metadata
+
+    # the id of the object in hubspot
+    attr_accessor :id
+
+    # the properties as if read from the api
+    attr_accessor :properties
+
+    # track any changes made to properties before saving etc
+    attr_accessor :changes
+
+    # any other data sent from the api about the resource
+    attr_accessor :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}")
+      #
+      # id - [Integer] The ID (or hs_object_id) of the resource to fetch.
+      # properties - an array of property names to fetch in the result
+      #
+      # Example:
+      #   contact = Hubspot::Contact.find(1)
+      #   contact = Hubspot::Contact.find(1, properties: %w[email firstname lastname custom_field])
+      #
+      # 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 || {})
         instantiate_from_response(response)
       end
 
+      # Finds a resource by a given property and value.
+      #
+      # property - The property to search by (e.g., "email").
+      # value - The value of the property to match.
+      # properties - Optional list of properties to return.
+      #
+      # Example:
+      #   properties = %w[firstname lastname email last_contacted]
+      #   contact = Hubspot::Contact.find_by("email", "john@example.com", properties)
+      #
+      # Returns An instance of the resource.
       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)
+
+        all_properties = build_property_list(properties)
+        params[:properties] = all_properties unless all_properties.empty?
+
+        response = get("#{api_root}/#{resource_name}/#{value}", query: params)
         instantiate_from_response(response)
       end
 
-      # Create a new resource
+      # Creates a new resource with the given parameters.
+      #
+      # params - The properties to create the resource with.
+      #
+      # Example:
+      #   contact = Hubspot::Contact.create(name: "John Doe", email: "john@example.com")
+      #
+      # Returns [Resource] The newly created resource.
       def create(params)
-        response = post("/crm/v3/objects/#{resource_name}", body: { properties: params }.to_json)
+        response = post("#{api_root}/#{resource_name}", body: { properties: params }.to_json)
         instantiate_from_response(response)
       end
 
+      # Updates an existing resource by ID.
+      #
+      # id - The ID of the resource to update.
+      # params - The properties to update.
+      #
+      # Example:
+      #   contact.update(1, name: "Jane Doe")
+      #
+      # Returns True if the update was successful
       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?
+        response = patch("#{api_root}/#{resource_name}/#{id}",
+                         body: { properties: params }.to_json)
+        handle_response(response)
 
         true
       end
 
+      # Deletes a resource by ID.
+      #
+      # id - The ID of the resource to delete.
+      #
+      # Example:
+      #   Hubspot::Contact.archive(1)
+      #
+      # Returns True if the deletion was successful
       def archive(id)
-        response = delete("/crm/v3/objects/#{resource_name}/#{id}")
-        raise Hubspot.error_from_response(response) unless response.success?
+        response = delete("#{api_root}/#{resource_name}/#{id}")
+        handle_response(response)
 
         true
       end
 
+      # Lists all resources with optional filters and pagination.
+      #
+      # params - Optional parameters to filter or paginate the results.
+      #
+      # Example:
+      #   contacts = Hubspot::Contact.list(limit: 100)
+      #
+      # Returns [PagedCollection] A collection of resources.
       def list(params = {})
+        all_properties = build_property_list(params[:properties])
+
+        if all_properties.is_a?(Array) && !all_properties.empty?
+          params[:properties] = all_properties.join(',')
+        end
+
         PagedCollection.new(
-          url: "/crm/v3/objects/#{resource_name}",
+          url: list_page_uri,
           params: params,
           resource_class: self
         )
       end
 
-      def batch_read(object_ids = [], id_property: 'id')
-        params = id_property == 'id' ? {} : { idProperty: id_property }
+      # Performs a batch read operation to retrieve multiple resources by their IDs.
+      #
+      # object_ids  - A list of resource IDs to fetch.
+      #
+      # id_property - The property to use for identifying resources (default: 'id').
+      #
+      #
+      # Example:
+      #   Hubspot::Contact.batch_read([1, 2, 3])
+      #
+      # Returns [PagedBatch] A paged batch of resources
+      def batch_read(object_ids = [], properties: [], id_property: 'id')
+        params = {}
+        params[:idProperty] = id_property unless id_property == 'id'
+        params[:properties] = properties unless properties.blank?
 
         PagedBatch.new(
-          url: "/crm/v3/objects/#{resource_name}/batch/read",
-          params: params,
+          url: "#{api_root}/#{resource_name}/batch/read",
+          params: params.empty? ? nil : 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)
+      # Performs a batch read operation to retrieve multiple resources by their IDs
+      # until there are none left
+      #
+      # object_ids - A list of resource IDs to fetch. [Array<Integer>]
+      # id_property - The property to use for identifying resources (default: 'id').
+      #
+      # Example:
+      #   Hubspot::Contact.batch_read_all(hubspot_contact_ids)
+      #
+      # Returns [Hubspot::Batch] A batch of resources that can be operated on further
+      def batch_read_all(object_ids = [], properties: [], id_property: 'id')
+        Hubspot::Batch.read(self, object_ids, properties: properties, id_property: id_property)
       end
 
-      # Get the complete list of fields (properties) for the object
+      # Retrieve the complete list of properties for this resource class
+      #
+      # Returns [Array<Hubspot::Property>] An array of hubspot properties
       def properties
         @properties ||= begin
           response = get("/crm/v3/properties/#{resource_name}")
@@ -78,18 +197,36 @@ module Hubspot
         end
       end
 
+      # Retrieve the complete list of user defined properties for this resource class
+      #
+      # Returns [Array<Hubspot::Property>] An array of hubspot properties
       def custom_properties
         properties.reject { |property| property['hubspotDefined'] }
       end
 
+      # Retrieve the complete list of updatable properties for this resource class
+      #
+      # Returns [Array<Hubspot::Property>] An array of updateable hubspot properties
       def updatable_properties
         properties.reject(&:read_only?)
       end
 
+      # Retrieve the complete list of read-only properties for this resource class
+      #
+      # Returns [Array<Hubspot::Property>] An array of read-only hubspot properties
       def read_only_properties
-        properties.select(&:read_only?)
+        properties.select(&:read_only)
       end
 
+      # Retrieve information about a specific property
+      #
+      # Example:
+      #   property = Hubspot::Contact.property('industry_sector')
+      #   values_for_select = property.options.each_with_object({}) do |prop, hash|
+      #     hash[prop['value']] = prop['label']
+      #   end
+      #
+      # Returns [Hubspot::Property] A hubspot property
       def property(property_name)
         properties.detect { |prop| prop.name == property_name }
       end
@@ -106,6 +243,48 @@ module Hubspot
       }.freeze
 
       # rubocop:disable Metrics/MethodLength
+
+      # Search for resources using a flexible query format and optional properties.
+      #
+      # This method allows searching for resources by passing a query in the form of a string
+      # (for full-text search) or a hash with special suffixes on the keys to
+      # define different comparison operators.
+      #
+      # You can also specify which properties to return and the number of results per page.
+      #
+      # 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.
+      #   - `_in`: Matches any of the values in the given array.
+      #
+      # If no suffix is provided, the default comparison is equality (`EQ`).
+      #
+      # query - [String, Hash] The query for searching. This can be either:
+      #   - A String: for full-text search.
+      #   - A Hash: where each key represents a property and may have suffixes for the comparison
+      #     (e.g., `{ email_contains: 'example.org', age_gt: 30 }`).
+      # properties - An optional array of property names to return in the search results.
+      #   If not specified or empty, HubSpot will return the default set of properties.
+      # page_size - The number of results to return per page
+      #   (default is 10 for contacts and 100 for everything else).
+      #
+      # Example Usage:
+      #   # Full-text search for 'example.org':
+      #   props = %w[email firstname lastname]
+      #   contacts = Hubspot::Contact.search(query: "example.org", properties: props, page_size: 50)
+      #
+      #   # Search for contacts whose email contains 'example.org' and are older than 30:
+      #   contacts = Hubspot::Contact.search(
+      #     query: { email_contains: 'example.org', age_gt: 30 },
+      #     properties: ["email", "firstname", "lastname"],
+      #     page_size: 50
+      #   )
+      #
+      # Returns [PagedCollection] A paged collection of results that can be iterated over.
       def search(query:, properties: [], page_size: 100)
         search_body = {}
 
@@ -127,7 +306,7 @@ module Hubspot
 
         # Perform the search and return a PagedCollection
         PagedCollection.new(
-          url: "/crm/v3/objects/#{resource_name}/search",
+          url: "#{api_root}/#{resource_name}/search",
           params: search_body,
           resource_class: self,
           method: :post
@@ -136,6 +315,10 @@ module Hubspot
 
       # 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
@@ -146,8 +329,22 @@ module Hubspot
         end
       end
 
+      # List of properties that will always be retrieved
+      # should be overridden in specific resource class
+      def required_properties
+        []
+      end
+
       private
 
+      def api_root
+        '/crm/v3/objects'
+      end
+
+      def list_page_uri
+        "#{api_root}/#{resource_name}"
+      end
+
       # Instantiate a single resource object from the response
       def instantiate_from_response(response)
         data = handle_response(response)
@@ -182,12 +379,44 @@ module Hubspot
         # Default to 'EQ' operator if no suffix is found
         { propertyName: key.to_s, operator: 'EQ' }
       end
+
+      # Internal make a list of properties to request from the API
+      # will be merged with any required_properties defined on the class
+      def build_property_list(properties)
+        properties = [] unless properties.is_a?(Array)
+        raise 'Must be an array' unless required_properties.is_a?(Array)
+
+        properties.concat(required_properties).uniq
+      end
     end
 
-    # rubocop:disable Ling/MissingSuper
+    # rubocop:disable Lint/MissingSuper
+
+    # Public: Initialize a resouce
+    #
+    # data - [2D Hash, nested Hash] data to initialise:
+    #   - The response from the api will be of the form:
+    #       { id: <hs_object_id>, properties: { "email": "john@example.org" ... }, ... }
+    #
+    #   - A Simple 2D Hash, key value pairs in the form:
+    #       { email: 'john@example.org', firstname: 'John', lastname: 'Smith' }
+    #
+    #   - A structured hash consisting of { id: <hs_object_id>, properties: {}, ... }
+    #     This is the same structure as per the API, and can be rebuilt if you store the id
+    #     of the object against your own data
+    #
+    # Example:
+    #   attrs = { firstname: 'Luke', lastname: 'Skywalker', email: 'luke@jedi.org' }
+    #   contact = Hubspot::Contact.new(attrs)
+    #   contact.persisted? # false
+    #   contact.save # creates the record in Hubspot
+    #   contact.persisted? # true
+    #   puts "Contact saved with hubspot id #{contact.id}"
+    #
+    #   existing_contact = Hubspot::Contact.new(id: hubspot_id, properties: contact.to_hubspot)
     def initialize(data = {})
       data.transform_keys!(&:to_s)
-      @id = extract_id(data)
+      @id = extract_id(data.delete('id'))
       @properties = {}
       @metadata = {}
       if @id
@@ -196,13 +425,22 @@ module Hubspot
         initialize_new_object(data)
       end
     end
-    # rubocop:enable Ling/MissingSuper
+    # rubocop:enable Lint/MissingSuper
 
+    # Determine the state of the object
+    #
+    # Returns Boolean
     def changes?
       !@changes.empty?
     end
 
-    # Instance methods for update (or save)
+    # Create or Update the resource.
+    # If the resource was already persisted (e.g. it was retrieved from the API)
+    # it will be updated using values from @changes
+    #
+    # If the resource is new (no id) it will be created
+    #
+    # Returns Boolean
     def save
       if persisted?
         self.class.update(@id, @changes).tap do |result|
@@ -216,21 +454,57 @@ module Hubspot
       end
     end
 
+    # If the resource exists in Hubspot
+    #
+    # Returns Boolean
     def persisted?
       @id ? true : false
     end
 
-    # Update the resource
-    def update(params)
+    # Public - Update the resource and persist to the api
+    #
+    # attributes - hash of properties to update in key value pairs
+    #
+    # Example:
+    #   contact = Hubspot::Contact.find(hubspot_contact_id)
+    #   contact.update(status: 'gold customer', last_contacted_at: Time.now.utc.iso8601)
+    #
+    # Returns Boolean
+    def update(attributes)
       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
+      update_attributes(attributes)
 
       save
     end
 
+    # Public - Update resource attributes
+    #
+    # Does not persist to the api but processes each attribute correctly
+    #
+    # Example:
+    #   contact = Hubspot::Contact.find(hubspot_contact_id)
+    #   contact.changes? # false
+    #   contact.update_attributes(education: 'Graduate', university: 'Life')
+    #   contact.education # Graduate
+    #   contact.changes? # true
+    #   contact.changes # { "education" => "Graduate", "university" => "Life" }
+    #
+    # Returns Hash of changes
+    def update_attributes(attributes)
+      raise ArgumentError, 'must be a hash' unless attributes.is_a?(Hash)
+
+      attributes.each do |key, value|
+        send("#{key}=", value) # This will trigger the @changes tracking via method_missing
+      end
+    end
+
+    # Archive the object in Hubspot
+    #
+    # Example:
+    #   company = Hubspot::Company.find(hubspot_company_id)
+    #   company.delete
+    #
     def delete
       self.class.archive(id)
     end
@@ -241,7 +515,11 @@ module Hubspot
     end
 
     # rubocop:disable Metrics/MethodLength
-    # Handle dynamic getter and setter methods with method_missing
+
+    # getter: Check the properties and changes hashes to see if the method
+    # being called is a key, and return the corresponding value
+    # setter: If the method ends in "=" persist the value in the changes hash
+    # (when it is different from the corresponding value in properties if set)
     def method_missing(method, *args)
       method_name = method.to_s
 
@@ -249,15 +527,8 @@ module Hubspot
       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
+        add_accessors attribute
+        return send("#{attribute}=", new_value)
       # Handle getters
       else
         return @changes[method_name] if @changes.key?(method_name)
@@ -267,35 +538,77 @@ module Hubspot
       # Fallback if the method or attribute is not found
       super
     end
+
     # rubocop:enable Metrics/MethodLength
 
-    # Ensure respond_to_missing? is properly overridden
+    # Ensure respond_to_missing? handles existing keys in the properties anc changes hashes
     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
 
+    # Initialize from API response, separating metadata from properties
+    def initialize_from_api(data)
+      @changes = data.delete('changes')&.transform_keys!(&:to_s) || {}
+
+      if data['properties']
+        @metadata = data.reject { |key, _v| key == 'properties' }
+        handle_properties(data['properties'])
+      else
+        handle_properties(data)
+      end
+    end
+
     private
 
     # Extract ID from data and convert to integer
-    def extract_id(data)
-      data['id'] ? data['id'].to_i : nil
+    def extract_id(id)
+      id&.to_i
     end
 
-    # Initialize from API response, separating metadata from properties
-    def initialize_from_api(data)
-      @metadata = extract_metadata(data)
-      properties_data = data['properties'] || {}
+    def handle_properties(properties_data)
+      properties_data.each do |attribute, value|
+        if metadata_field?(attribute)
+          @metadata[attribute.to_s] = value
+        else
+          add_accessors attribute.to_s
+          @properties[attribute.to_s] = value
+        end
+      end
+    end
+
+    def add_accessors(attribute)
+      add_accessors_setter(attribute)
+      add_accessors_getter(attribute)
+    end
 
-      properties_data.each do |key, value|
-        if METADATA_FIELDS.include?(key)
-          @metadata[key] = value
+    def add_accessors_setter(attribute)
+      # Define the setter method
+      define_singleton_method("#{attribute}=") do |new_value|
+        # Track changes only if the value has actually changed
+        if @properties[attribute] != new_value
+          @changes[attribute] = new_value
         else
-          @properties[key] = value
+          @changes.delete(attribute) # Remove from changes if it reverts to the original value
         end
+
+        new_value
+      end
+    end
+
+    def add_accessors_getter(attribute)
+      # Define the getter method
+      define_singleton_method(attribute) do
+        # Return from changes if available, else return from properties
+        return @changes[attribute] if @changes.key?(attribute)
+
+        @properties[attribute] if @properties.key?(attribute)
       end
+    end
 
-      @changes = {}
+    # allows overwriting in other resource classes
+    def metadata_field?(key)
+      METADATA_FIELDS.include?(key)
     end
 
     # Initialize a new object (no API response)
@@ -305,11 +618,6 @@ module Hubspot
       @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)

data/lib/hubspot/user.rb

@@ -1,8 +1,32 @@
 # frozen_string_literal: true
 
 module Hubspot
+  # ORM for hubspot users
+  #
+  # Hubspot users consist mostly of read_only attributes (you can add custom properties).
+  # As such we extend this class to ensure that we retrieve useful data back from the API
+  # and provide helper methods to resolve hubspot fields e.g. user.email calls user.hs_email etc
   class User < Resource
+    class << self
+      def required_properties
+        %w[hs_email hs_given_name hs_family_name]
+      end
+    end
+
+    def first_name
+      hs_given_name
+    end
+    alias firstname first_name
+
+    def last_name
+      hs_family_name
+    end
+    alias lastname last_name
+
+    def email
+      hs_email
+    end
   end
 
-  Owner = User  
+  Owner = User
 end

data/lib/hubspot/version.rb

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

data/lib/ruby_hubspot_api.rb

@@ -12,13 +12,18 @@ require_relative 'hubspot/config'
 require_relative 'hubspot/exceptions'
 require_relative 'hubspot/api_client'
 
-# load base class then modules
+# load base class then models
 require_relative 'hubspot/resource'
 require_relative 'hubspot/property'
+
+# load CRM models
 require_relative 'hubspot/contact'
 require_relative 'hubspot/company'
 require_relative 'hubspot/user'
 
+# load marketing models
+require_relative 'hubspot/form'
+
 # Load other components
 require_relative 'hubspot/batch'
 require_relative 'hubspot/paged_collection'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_hubspot_api
 version: !ruby/object:Gem::Version
-  version: 0.2.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Simon Brook
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-10-01 00:00:00.000000000 Z
+date: 2024-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -223,6 +223,7 @@ files:
 - lib/hubspot/config.rb
 - lib/hubspot/contact.rb
 - lib/hubspot/exceptions.rb
+- lib/hubspot/form.rb
 - lib/hubspot/paged_batch.rb
 - lib/hubspot/paged_collection.rb
 - lib/hubspot/property.rb
@@ -254,7 +255,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14.4
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
 summary: ruby_hubspot_api is an ORM-like wrapper for the Hubspot API