Poor Gem documentation and lack of Wiki

[patrickemuller]

Recently in my current company we decided to move from the unofficial gem hubspot-ruby for this official one, but the lack of Wiki and proper documentation of the Gem is making the transition difficult, since I need to constantly read the internal code of the gem to understand how something is done, mainly with the OAuth part.

Is it possible to write some wiki, or maybe a markdown document inside the Gem with some examples?
This way other can contribute by adding examples and/or use cases of each of the methods/endpoints available in the Gem today.

[thien-duplexpoint]

I have the same suggestion with @patrickemuller

I think you guys (Hubspot) have great API documents and instructions but a poor official gem. This makes me concern about if you guys do it seriously or not. It makes us hard to make a decision to use a 2-year-old gem or using this official one!

[patrickemuller]

As soon as I finish some of the work that I have, I'll fork and submit a pull request with, at least, a few more instructions in the Readme in order to start this improvement.

[gfauredumont]

Hi @patrickemuller,
Have you finished the work you had ? 😉
Same as everybody here (including the thumbsup !): choosing between a 2 year old Gem or yours is difficult but it shouldn't be !

[gfauredumont]

Ho, I just realized that you are the author of the Issue, not the Gem, sorry !
@plaurynovich-hubspot (you seem to be active on the project), can we have some information about this issue please ?

[patrickemuller]

Hi @patrickemuller,
Have you finished the work you had ?
Same as everybody here (including the thumbsup !): choosing between a 2 year old Gem or yours is difficult but it shouldn't be !

I'm sorry if I disappeared here.
I'm really busy with HubSpot in the company I work for (and also with other integrations that came along the way in the past few months).

I didn't have the time to really put some effort into tracking specific use cases for the gem.
I can contribute with something if you guys want.

These are some of the endpoints/classes I have used and tracked into a simple text file just to keep them available when I needed.

INITIALIZE HUBSPOT GEM (before any other command)

::Hubspot.configure do |config|
  config.access_token = 'Your_Token_Here'
end

REFRESH ACCESS TOKEN

oauth = ::Hubspot::OAuth::DefaultApi.new
tokens = oauth.create_token(
  grant_type: :refresh_token,
  refresh_token:'some_refresh_token',
  client_id: ENV['HUBSPOT_CLIENT_ID'],
  client_secret: ENV['HUBSPOT_CLIENT_SECRET'],
  return_type: 'Object'
)

GET ALL PROPERTIES FROM GROUP

properties = ::Hubspot::Crm::Properties::CoreApi.new
# Map the properties and create a hash with name, label and group attributes
properties.get_all('deal', auth_names: 'oauth2').results.map do |object|
  { name: object.name, label: object.label, group: object.group_name }
end

CREATE A NEW GROUP OF PROPERTIES

group = ::Hubspot::Crm::Properties::GroupsApi.new
group.create('deal', { name: 'test', label: 'test properties', displayOrder: -1 } , auth_names: 'oauth2')

UPDATE AN SPECIFIC PROPERTY IN A GROUP

property = ::Hubspot::Crm::Properties::CoreApi.new
property.update('deal', 'term_length', { type: 'string', fieldType: 'text' }, auth_names: 'oauth2')

ASSOCIATE TWO OBJECTS (like contact with a company)

connection = Hubspot::Crm::Associations::BatchApi.new
connection.create('contact', 'company',
                  batch_input_public_association: {
                    inputs: [
                      { from: { id: from_id }, to: { id: to_id }, type: 'contact_to_company' }
                    ]
                  },
                  auth_names: 'oauth2')

[bchellingworth]

Does anyone know how to interact with lists? I need to add a contact to a newsletter list, I can find the docs in the API documentation, but how to do it in the gem is beyond me. As many others have said, its extremely irritating to be held back on such a huge platform by simply poor documentation.

[paul-bonnel-fr]

Really like what your are doing but could you add some documentaion on how to create a new contact and associate it with a a list ?
Anyone can provide an example ? Thank you !

[Sokre95]

Does anyone know how to interact with lists? I need to add a contact to a newsletter list, I can find the docs in the API documentation, but how to do it in the gem is beyond me. As many others have said, its extremely irritating to be held back on such a huge platform by simply poor documentation.

@bchellingworth Sadly, seems like v3 api still does not support Lists :/

https://developers.hubspot.com/docs/api/marketing/contact-lists

[averydev]

The docs on this gem are about as bad as I've ever seen for an official gem for a big company.
It requires fishing around in the internals for hours to figure out how to do basic things. That's not ok.

[oroth8]

Decided it would be quicker to make my own gem then address all the issues with this one. If you want simple functionality please give this a try. https://github.com/oroth8/easy_hubspot

[geoffharcourt]

We also ended up making our own API calls outside of the gem. We found it quite difficult to do basic operations that we were accomplishing on the old API client in the new one due to the lack of examples and Ruby-specific docs. If anyone has a working example for contact creation we'd love to see it.

[Brad-FDI]

Me and my friends Claude and Chat couldn't figure out for 2+ hours how to pull the history of properties for a ticket using this gem. Ended up having AI simply call the REST API using Net::HTTP. Then did that for the other HubSpot API endpoints too and dropped the gem. In part fwiw:

def get_status_history(ticket_id)
  begin
    ticket_url = URI("#{base_url}/crm/v3/objects/tickets/#{ticket_id}?properties=hs_pipeline_stage&propertiesWithHistory=hs_pipeline_stage")
    ticket_response = make_request(ticket_url)
    property_history = ticket_response['propertiesWithHistory']['hs_pipeline_stage'].map do |change|
      ...
    end
    property_history.sort_by { |entry| entry[:timestamp] }.reverse
  rescue => e
    puts "Error fetching ticket history: #{e.message}"
    puts e.backtrace.join("\n")
    []
  end
end

def make_request(url, method = :get, body = nil)
  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  request = case method
            when :get
              Net::HTTP::Get.new(url)
            when :post
              Net::HTTP::Post.new(url)
            else
              raise "Unsupported HTTP method: #{method}"
            end
  request["accept"] = 'application/json'
  request["content-type"] = 'application/json'
  request["authorization"] = "Bearer #{access_token}"
  request.body = body.to_json if body
  response = http.request(request)
  if response.is_a?(Net::HTTPServerError)
    puts "Server error: #{response.code} #{response.message}. Retrying in 1 second..."
    sleep 1
    response = http.request(request)
  end
  return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
  puts "HTTP request failed: #{response.code} #{response.message}"
  raise "HTTP request failed"
rescue => e
  puts "Request failed: #{e.message}"
  raise "HTTP request failed"
end

[stuartchaney]

Glad I found this thread on day 1.

oroth8/easy_hubspot is a great alternative to this gem or integrating using raw Net:HTTP requests