ruby_hubspot_api 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6052dfd71294e988924beeab1b89662673ceaf93
-  data.tar.gz: 4b2e295931295d639e473a9b139df03ec7df1554
+SHA256:
+  metadata.gz: 85164b2e72737294737730eea14e12955d3f143f5fadc6a586523b002b1d82fa
+  data.tar.gz: 4240f83a2b75521845a0db28a6f7eac72b12542cd0c8c0bd1504f4a5c36c3c00
 SHA512:
-  metadata.gz: caee0d8350205b6bcf45bb4ed4b5421f3fdaacaff87acfcb52c4845858bbafb664f70acbca1a564a34a99a166fd1072a838702d4bf4044b076cfd0b77e87f6a7
-  data.tar.gz: 28cbb5b1ea5ebc076d7177e8f4ee35f450bbe7fbb33224a31c55f0801fc566b705cf9b65faf95453b91154675139fb33cfce557ea74e06afd001a09f710190bf
+  metadata.gz: d74e992af58345457232d6617c6133e1874a85f98925606a954c86c0a766c198bd5e7d0643e5417d8a21ea195f1aba9d823147123c9cf8d631ac9514a4ed268c
+  data.tar.gz: 32be447b0f03a5d86c340f00d1639d61a839c040fbe96789bdaeb7869403fadaf04843167a497e99b6223b0cca4c7e00c62d04ac8554d6ec618db6861cc969f8

data/CHANGELOG.md

@@ -1,139 +1,139 @@
 
 ## 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
+- bump version
+- use safe navigation for extracting id
+- make erb explicitly determined by the file exension (.json.erb)
+- check the env vars before sanitising
+- Finish specs
+- Sanitize web mock output
+- Tests the method missing setter for resource
+- find_by_token method - uses v1 API
+- Contact find_by_token spec
+- Allow ERB in json fixtures
+- No cov for inspect
+- Ensure properties are passed as named argument
+- Update batch spec to check resource_matcher works
+- Drop cadacy for now
+- Ignore gem files
+- Dynamically add a method to batch to allow "resources" to be referred to as the resource_name
+- Adds validation for resource matcher
+- Bump the version
+- Update batch spec
+- Clear up processing results
+- Fix find resources
+- Update the hierarchy to allow more flexibility
+- Tidy comments
+- Adds  :sparkle: attributes method to a resource
+- Improve logic of resource matching
+- Update user model to force specific properties to be retrieved
+- Add some handling of required properties
+- Tidy up somer doc comments
+- adjust some rubocop settings
+- Yep. Back ported to 2.4
+- Tidy up documentation of resource
+- Ensure we always apply the right log_level
+- Adding Codacy badge
+- try to upload the coverage results to codacy too
+- Only apply lcov formatter if running on github
+- Add property check to the contact spec
+- Add read-only properties to resource class
+- Adding lcov format
+- Using earlier bundler
+- adding codecov
+- determine if a Hubspot property is read_only (or by negation updatable)
+- test on ruby 3.0 too
+- ignore ruby version file
+- Use ERB in VCR tests so as to be independent of the env vars
+- try calling rspec directly
+- add ruby 2.5 and reduce log output
+- add plaatforms to Gemfile.lock
+- fix the github workflow properly
+- fix the github workflow
+- Create ruby.yml
+- More usage clarification
+- Clarify usage
 
 ## v0.2.0
 
-- Get the development dependencies right!
-- Bump the version again
-- describe find_by method
-- update lock
-- batch  :sparkle: upsert spec
-- Borrowing Object#blank? method cos it actually really helps...
-- batch implemntation
-- logger.debug the post body and response body
-- Adds a changes? Method on resource
-- Adds instance method resource_name on resource
-- Ensure keys are stringified
-- Add all end points to the batch spec
-- Adds create and archive methods to batches
-- Tidy up resource code
-- Cover the previously nocov'd code
-- Add api client logging spec
-- add configurable timeouts to requests
-- Move rate limit handling to the client
-- Simplify mocked responses in batch spec
-- Adds PagedBatch as pager for batch/read request
-- Update the Readme to add Batch operations
 - bump version
+- Update the Readme to add Batch operations
+- Adds PagedBatch as pager for batch/read request
+- Simplify mocked responses in batch spec
+- Move rate limit handling to the client
+- add configurable timeouts to requests
+- Add api client logging spec
+- Cover the previously nocov'd code
+- Tidy up resource code
+- Adds create and archive methods to batches
+- Add all end points to the batch spec
+- Ensure keys are stringified
+- Adds instance method resource_name on resource
+- Adds a changes? Method on resource
+- logger.debug the post body and response body
+- batch implemntation
+- Borrowing Object#blank? method cos it actually really helps...
+- batch  :sparkle: upsert spec
+- update lock
+- describe find_by method
+- Bump the version again
+- Get the development dependencies right!
 
 ## v0.1.2
 
-- Fix the Readme
-- Sure the search param is values where passing an array
-- update changelog and Gemfile.lock
 - bump version
+- update changelog and Gemfile.lock
+- Sure the search param is values where passing an array
+- Fix the Readme
 
 ## v0.1.1
 
-- adds the version numbers to the gemspec
-- Fix dependencies
 - bump version
+- Fix dependencies
+- adds the version numbers to the gemspec
 
 ## v0.1.0
 
-- Setup the configuration block
-- Adds spec for config
-- Set the auth headers when access_token configured
-- Version spec
-- don't test for client id
-- Load api client and add exception handler
-- Initial bases class Resource for api crud
-- Contact class with spec
-- Cassettes for contact spec
-- company model and spec with cassettes
-- Adds PagedCollection for paged results (list / search)
-- Adds Hubspot configuration to tests
-- Update required files
-- Adds list method to return PagedCollection
-- Add interface for search
-- VCR configuration
-- Contact/search cassette
-- Sample ENV file for developers
-- console with configuration if env vars set
-- Readme file
-- MIT license
-- allow connections if vcr_record_mode is on
-- Fix rubocop config
-- Update Readme
-- Log api requests and add interface to set logging
-- Update exception handing logic and add more exception classes
-- Test all parts of the config code
-- Adds user model (aliased to Owner) and specs
-- Add a configured? method to Hubspot module
-- Adds a dummy Hubspot::Property class
-- Update Paged request handling based on method
-- Adds a find_by mechanism for resources
-- Use the Hubspot::Property class to return properties for a given resource object
-- Update the specs for 100% coverage
-- Update the sample .env file
-- Reorder and clarify Readme
-- When we use limit(1) we should only return the object not an array
-- Test that we only get the properties we ask for or the defaults
-- Flatten the properties array into a comma separated list
-- Improve the intialiser
 - Update the changeling and link in gem spec
+- Improve the intialiser
+- Flatten the properties array into a comma separated list
+- Test that we only get the properties we ask for or the defaults
+- When we use limit(1) we should only return the object not an array
+- Reorder and clarify Readme
+- Update the sample .env file
+- Update the specs for 100% coverage
+- Use the Hubspot::Property class to return properties for a given resource object
+- Adds a find_by mechanism for resources
+- Update Paged request handling based on method
+- Adds a dummy Hubspot::Property class
+- Add a configured? method to Hubspot module
+- Adds user model (aliased to Owner) and specs
+- Test all parts of the config code
+- Update exception handing logic and add more exception classes
+- Log api requests and add interface to set logging
+- Update Readme
+- Fix rubocop config
+- allow connections if vcr_record_mode is on
+- MIT license
+- Readme file
+- console with configuration if env vars set
+- Sample ENV file for developers
+- Contact/search cassette
+- VCR configuration
+- Add interface for search
+- Adds list method to return PagedCollection
+- Update required files
+- Adds Hubspot configuration to tests
+- Adds PagedCollection for paged results (list / search)
+- company model and spec with cassettes
+- Cassettes for contact spec
+- Contact class with spec
+- Initial bases class Resource for api crud
+- Load api client and add exception handler
+- don't test for client id
+- Version spec
+- Set the auth headers when access_token configured
+- Adds spec for config
+- Setup the configuration block
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_hubspot_api (0.3.0)
+    ruby_hubspot_api (0.3.2)
       httparty (>= 0.1, < 1.0)
 
 GEM
@@ -17,15 +17,17 @@ GEM
     crack (1.0.0)
       bigdecimal
       rexml
+    csv (3.3.0)
     diff-lcs (1.5.1)
     docile (1.3.5)
     dotenv (2.8.1)
     hashdiff (1.1.1)
-    httparty (0.21.0)
+    httparty (0.22.0)
+      csv
       mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
     method_source (1.1.0)
-    mini_mime (1.1.2)
+    mini_mime (1.1.5)
     multi_xml (0.6.0)
     pry (0.14.2)
       coderay (~> 1.1)
@@ -80,4 +82,4 @@ DEPENDENCIES
   webmock (>= 3.0)
 
 BUNDLED WITH
-   2.2.34
+   2.3.27

data/README.md

@@ -120,7 +120,7 @@ puts "Contact: #{contact.firstname} #{contact.lastname}"
 
 ### Updating an Existing Object
 
-To update an existing object, you can either modify the object and call `save`, or use the `update` method specifying the properties you want to update. You can test whether or not the object will need to upload changes to the api by using the changes? method
+To update an existing object, you can either modify the object and call `save`, or use the `update` method specifying the properties you want to update. You can test whether or not the object will need to upload changes to the api by using the changes? method. If you don't want to check for changes? you can use the method `save!` on the resource which will raise a Hubspot::NothingToDoError if there are no changes.
 
 Example using `save`:
 
@@ -136,6 +136,22 @@ contact.save # true
 contact.changes? # false
 ```
 
+Example using `save!`:
+
+```ruby
+contact = Hubspot::Contact.find(1)
+
+MyDecorator.new(contact).apply_changes!
+
+begin
+  contact.save!
+rescue Hubspot::NothingToDoError = _
+  puts "Nothing changed, cancelled api call"
+rescue Hubspot::RequestError => e
+  puts "API Error: #{e.message}"
+end
+```
+
 Example using `update`:
 
 ```ruby
@@ -274,6 +290,41 @@ end
 - **lte**: Less than or equal to.
 - **IN**: Matches any of the values in an array.
 
+#### Searching for empty values (NOT_HAS_PROPERTY)
+
+Any empty value in your search will be matched using the correect filter in Hubspot
+
+```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])
+# Request body: {"filterGroups":[{"filters":[{"propertyName":"client_category","operator":"NOT_HAS_PROPERTY"}]}]
+
+puts "Searching for uncategorised customers"
+puts ""
+
+companies.each do |company|
+  category = company_category_by_size(company.number_of_employees)
+  company.update(client_category: category)
+
+  puts "  Found: #{company.name} (size #{company.number_of_employees}) - filed under #{category}"
+end
+```
+
+#### 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(query: { 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.

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
@@ -19,6 +21,8 @@ module Hubspot
   class RateLimitExceededError < RequestError; end
   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/paged_collection.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'json'
 require_relative './api_client'
 require_relative './exceptions'
 
@@ -10,17 +11,24 @@ 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 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?
         offset = response.dig('paging', 'next', 'after')
@@ -37,10 +45,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
 
@@ -51,8 +61,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|
@@ -62,6 +74,33 @@ module Hubspot
 
     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

data/lib/hubspot/resource.rb

@@ -263,6 +263,8 @@ module Hubspot
       #
       # 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
+      #
       # 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
@@ -312,13 +314,8 @@ module Hubspot
           method: :post
         )
       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
@@ -337,6 +334,9 @@ 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
@@ -356,9 +356,9 @@ module Hubspot
         filter_groups = [{ filters: [] }]
 
         filters.each do |key, value|
-          filter = extract_property_and_operator(key)
+          filter = extract_property_and_operator(key, value)
           value_key = value.is_a?(Array) ? :values : :value
-          filter[value_key] = value
+          filter[value_key] = value unless value.blank?
           filter_groups.first[:filters] << filter
         end
 
@@ -366,7 +366,9 @@ module Hubspot
       end
 
       # Extract property name and operator from the key
-      def extract_property_and_operator(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 {
@@ -454,6 +456,12 @@ module Hubspot
       end
     end
 
+    def save!
+      raise NothingToDoError, 'Nothing to save' unless changes?
+
+      save
+    end
+
     # If the resource exists in Hubspot
     #
     # Returns Boolean
@@ -622,6 +630,8 @@ module Hubspot
     def create_new
       created_resource = self.class.create(@changes)
       @id = created_resource.id
+      @properties.merge!(@changes)
+      @changes = {}
       @id ? true : false
     end
   end

data/lib/hubspot/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_hubspot_api
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Simon Brook
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-15 00:00:00.000000000 Z
+date: 2024-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -239,7 +239,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/sensadrome/ruby_hubspot_api
   changelog_uri: https://github.com/sensadrome/ruby_hubspot_api/blob/main/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -254,9 +254,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14
-signing_key: 
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: ruby_hubspot_api is an ORM-like wrapper for the Hubspot API
 test_files: []