ruby_hubspot_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a9081936b5a9201fa61faff7d03946af84e7a655bc8fb4b87216fe904ed8a147
+  data.tar.gz: 7e33a98b6224c769b90327ac2702dbe3752d8ae7d15b7032f1ad195021db7ae8
+SHA512:
+  metadata.gz: 3bf538ac27be73eb2a4dbe97e65d6449aa304b40628779836f482014009361586e129a2b363697d1c3b06264b22cbd295233af961f8d18eeef94146c7c46e3d1
+  data.tar.gz: 82fb453482303e5fc8ff09404fc3b0e7f1aae13614e6fba98c700b781272c731b03f7f461213a8949bb2220d11c1637db68df1a71215523329352f6d39b2eadc

data/.env.sample

@@ -0,0 +1,40 @@
+# Sample .env file
+# If you want to run the tests and re-record the cassettes you will need
+# a private app in hubspot with the correct scopes and you will need to
+# grab the access token and the client secret and portal_id
+# see https://developers.hubspot.com/docs/api/private-apps
+
+export HUBSPOT_ACCESS_TOKEN=your_private_app_access_token
+export HUBSPOT_CLIENT_SECRET=your_client_secret
+export HUBSPOT_PORTAL_ID=portal_id
+
+# 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
+
+# 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
+
+# domain name to test the search by email contains
+export HUBSPOT_SEARCH_TEST_DOMAIN=hubspot.com
+
+# maximum number of records to fetch when testing lists
+export HUBSPOT_SEARCH_LIMIT=5
+
+# email address for search on email = <email>
+export HUBSPOT_TEST_CONTACT_EMAIL=test@hubspot.com

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/coverage/
+/tmp/
+
+.env
+# rspec failure tracking
+.rspec_status
+.pry_history

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,6 @@
+# .rubocop.yml
+
+# Ignore Metrics/BlockLength for the spec directory
+Metrics/BlockLength:
+  Exclude: 
+    - spec/**/*.rb

data/.ruby-version

@@ -0,0 +1 @@
+2.5.3

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+## v0.1.0
+
+- initial setup
+- 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

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in ruby_hubspot_api.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    ruby_hubspot_api (0.1.0)
+      bundler (~> 2.3, < 3.0)
+      dotenv (~> 2.8, < 3.0)
+      httparty (~> 0.21, < 1.0)
+      pry (~> 0.13, < 1.0)
+      pry-byebug (~> 3.9, < 4.0)
+      rspec (~> 3.13, < 4.0)
+      simplecov (~> 0.22, < 1.0)
+      vcr (~> 6.0, < 7.0)
+      webmock (~> 3.23, < 4.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    bigdecimal (3.1.8)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    diff-lcs (1.5.1)
+    docile (1.4.1)
+    dotenv (2.8.1)
+    hashdiff (1.1.1)
+    httparty (0.21.0)
+      mini_mime (>= 1.0.0)
+      multi_xml (>= 0.5.2)
+    method_source (1.1.0)
+    mini_mime (1.1.2)
+    multi_xml (0.6.0)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.9.0)
+      byebug (~> 11.0)
+      pry (~> 0.13.0)
+    public_suffix (4.0.7)
+    rake (13.2.1)
+    rexml (3.3.7)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.1)
+      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)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    vcr (6.0.0)
+    webmock (3.23.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  x86_64-darwin-18
+
+DEPENDENCIES
+  rake (>= 11.0, < 14.0)
+  ruby_hubspot_api!
+
+BUNDLED WITH
+   2.3.26

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Simon Brook
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# Ruby HubSpot API Gem
+
+This gem was largely inspired by [hubspot-api-ruby](https://github.com/captaincontrat/hubspot-api-ruby) which, in turn, was inspired by the [hubspot-ruby](https://github.com/HubspotCommunity/hubspot-ruby) community gem. I wanted to use version 3 of the api and simplify some parts of the interface
+
+The Ruby HubSpot API gem is a starting point for building an ORM-like interface to HubSpot's API. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_hubspot_api'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install ruby_hubspot_api
+```
+
+## Configuration
+
+To authenticate API requests, you need a HubSpot access token. First you will need to add a [private app in hubspot](https://developers.hubspot.com/docs/api/private-apps) When that is setup you can go to the "Auth" tab of your private app page and grab the access token from there
+
+You can configure the gem by adding this code to your initializer (for Rails) or to your startup configuration (in any other environment):
+
+```ruby
+Hubspot.configure do |config|
+  config.access_token = 'your_access_token'
+end
+```
+
+This configuration ensures that your API requests are authenticated using your HubSpot access token.
+
+## Working with Objects
+
+This gem allows you to interact with HubSpot objects such as contacts and companies. You can perform operations on individual instances (e.g., creating or updating records) as well as on collections (e.g., listing or searching).
+
+### Instance Methods
+
+#### Creating and Saving an Object
+
+You can instantiate a new resource (such as a contact) by passing a hash of properties when creating the object. After setting the properties, calling `save` will persist the object to the HubSpot API.
+
+Example:
+
+```ruby
+new_contact = Hubspot::Contact.new(firstname: 'John', lastname: 'Doe', email: 'john.doe@example.com')
+
+# Save the contact to HubSpot
+new_contact.save
+
+# After saving, the contact will be assigned an ID by the API
+puts "New contact ID: #{new_contact.id}"
+```
+
+#### 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
+
+Example using `save`:
+
+```ruby
+contact = Hubspot::Contact.find(1)
+contact.lastname = 'DoeUpdated'
+contact.save # true
+```
+
+Example using `update`:
+
+```ruby
+contact = Hubspot::Contact.find(1)
+contact.update(lastname: 'DoeUpdated') # true
+```
+
+### Class Methods
+
+#### Listing Objects
+
+You can list all objects (such as contacts) using the `list` method, which returns a `PagedCollection`. This collection handles paginated results and responds to methods like `each_page`, `each`, and `all`. You can also pass the `page_size` parameter to control the number of records returned per page.
+
+Example:
+
+```ruby
+contacts = Hubspot::Contact.list(page_size: 10)
+
+# Using each_page to iterate over pages
+contacts.each_page do |page|
+  page.each do |contact|
+    puts "Contact: #{contact.firstname} #{contact.lastname}"
+  end
+end
+
+# Or iterate over all contacts without worrying about pagination
+contacts.each do |contact|
+  puts "Contact: #{contact.firstname} #{contact.lastname}"
+end
+
+# Get all contacts at once (use with caution for large datasets)
+all_contacts = contacts.all
+```
+
+#### Retrieving the first n items
+
+You can use the `first` method to retrieve the first item or a specified number of items:
+
+```ruby
+contacts = Hubspot::Contact.list(page_size: 10)
+
+# Retrieve the first contact
+first_contact = contacts.first
+
+# Retrieve the first 5 contacts
+first_five_contacts = contacts.first(5)
+```
+
+This will automatically set the limits and handle paging for the most efficient API calls while honouring the maximum page count for hubspot resources
+
+#### Searching
+
+You can search for objects by passing query parameters to the `search` method. HubSpot supports several operators such as `eq`, `gte`, `lt`, and `IN` for filtering.
+
+Example:
+
+```ruby
+# Search for contacts with email containing "hubspot.com"
+contacts = Hubspot::Contact.search(query: { email_contains: 'hubspot.com' })
+
+contacts.each do |contact|
+  puts "Found: #{contact.email}"
+end
+
+# Search for companies with number of employees greater than or equal to 100
+companies = Hubspot::Company.search(number_of_employees_gte: 100)
+
+companies.each do |company|
+  puts "Found: #{company.name}, Employees: #{company.number_of_employees}"
+end
+
+# Search for contacts with email in a specific list (IN operator)
+contacts = Hubspot::Contact.search(email_in: ['user1@example.com', 'user2@example.com'])
+
+contacts.each do |contact|
+  puts "Found: #{contact.email}"
+end
+```
+
+### Available Search Operators:
+- **eq**: Equal to.
+- **neq**: Not equal to.
+- **gte**: Greater than or equal to.
+- **lte**: Less than or equal to.
+- **IN**: Matches any of the values in an array.
+
+#### Specifying Properties in Search
+
+When performing a search, you can also specify which properties to return. If you specify any properties, you will only get those properties back, and the default HubSpot properties will not be included automatically.
+
+Example:
+
+```ruby
+# Search for contacts with email containing "hubspot.com" and only return specific properties
+contacts = Hubspot::Contact.search(
+  query: { email_contains: 'hubspot.com' },
+  properties: ['firstname', 'lastname', 'email', 'mobile', 'custom_property_1']
+)
+
+contacts.each do |contact|
+  puts "Name: #{contact.firstname} #{contact.lastname}, Email: #{contact.email}, Mobile: #{contact.mobile}"
+end
+```
+
+## Contributing
+
+There is much to do (including writing a TODO list, or at least adding issues in github!) but this should provide a solid start
+
+If you're interested in contributing to the gem, follow the instructions below.
+
+### Developer Setup
+
+A `.env.sample` file is provided with all the environment variables needed for development, including testing credentials. To set up your environment:
+
+1. Copy the `.env.sample` file to `.env`.
+2. Update the values with your own credentials (e.g., your `HUBSPOT_ACCESS_TOKEN`).
+
+The `.env` file will be used to configure your access to the HubSpot API and ensure that environment variables are properly loaded during development.
+
+### Using VCR for Testing
+
+We use VCR for recording and replaying HTTP requests during testing. You can control the VCR recording mode by setting the `VCR_RECORD_MODE` environment variable as a string. The following modes are supported:
+
+- `none` (default): No new requests are recorded; only replay from existing cassettes.
+- `all`: Records all requests, overwriting existing cassettes.
+- `new_episodes`: Records new requests, but keeps existing cassettes unchanged.
+- `once`: Records the first time tests are run, and replays on subsequent runs.
+
+You can specify the `VCR_RECORD_MODE` either via the command line or in the `.env` file (see the `.env.sample` file for examples).
+
+To change the record mode on the command line, use:
+
+```bash
+$ export VCR_RECORD_MODE=all
+```
+
+For more information on how VCR modes work, refer to the [VCR documentation](https://andrewmcodes.gitbook.io/vcr/record_modes).
+
+### Running Tests
+
+To run the tests, simply execute:
+
+```bash
+$ rspec
+```
+
+Ensure you have your `.env` file configured with a valid `HUBSPOT_ACCESS_TOKEN` for API integration tests if you want to rerecord your interactions.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'dotenv/load'
+require 'pry'
+require 'ruby_hubspot_api'
+require 'openssl'
+
+Hubspot.configure do |config|
+  config.access_token = ENV['HUBSPOT_ACCESS_TOKEN']
+  config.portal_id = ENV['HUBSPOT_PORTAL_ID']
+  config.client_secret = ENV['HUBSPOT_CLIENT_SECRET']
+end
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/hubspot/api_client.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Hubspot
+  # All interations with the Hubspot API happen here...
+  class ApiClient
+    include HTTParty
+    base_uri 'https://api.hubapi.com'
+
+    headers 'Content-Type' => 'application/json'
+
+    def handle_response(response)
+      self.class.handle_response(response)
+    end
+
+    class << self
+      def get(url, options = {})
+        ensure_configuration!
+
+        if options[:query] && options[:query][:properties].is_a?(Array)
+          options[:query][:properties] = options[:query][:properties].join(',')
+        end
+
+        start_time = Time.now
+        response = super(url, options)
+
+        request = HTTParty::Request.new(Net::HTTP::Get, url, options)
+        log_request(:get, request.uri.to_s, response, start_time)
+        response
+      end
+
+      def post(url, options = {})
+        ensure_configuration!
+        start_time = Time.now
+        response = super(url, options)
+        log_request(:post, url, response, start_time)
+        response
+      end
+
+      def patch(url, options = {})
+        ensure_configuration!
+        start_time = Time.now
+        response = super(url, options)
+        log_request(:patch, url, response, start_time)
+        response
+      end
+
+      def delete(url, options = {})
+        ensure_configuration!
+        start_time = Time.now
+        response = super(url, options)
+        log_request(:delete, url, response, start_time)
+        response
+      end
+
+      def log_request(http_method, url, response, start_time)
+        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.debug("Response body: #{response.body}") if Hubspot.logger.debug?
+      end
+
+      def handle_response(response)
+        if response.success?
+          response.parsed_response
+        else
+          Hubspot.logger.error("API Error: #{response.code} - #{response.body}")
+          raise Hubspot.error_from_response(response)
+        end
+      end
+
+      private
+
+      def ensure_configuration!
+        raise NotConfiguredError, 'Hubspot API not configured' unless Hubspot.configured?
+      end
+    end
+  end
+end

data/lib/hubspot/company.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Hubspot
+  class Company < Resource
+  end
+end

data/lib/hubspot/config.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Hubspot
+  # To hold Hubspot configuration
+  class Config
+    attr_accessor :access_token, :portal_id, :client_secret, :logger, :log_level
+
+    def initialize
+      @access_token = nil
+      @portal_id = nil
+      @client_secret = nil
+      @logger = initialize_logger
+      @log_level = determine_log_level
+      apply_log_level
+    end
+
+    private
+
+    # Initialize the default logger
+    def initialize_logger
+      Logger.new($stdout)
+    end
+
+    # Map string values from environment variables to Logger constants
+    # rubocop:disable Metrics/MethodLength
+    def determine_log_level
+      env_log_level = ENV['HUBSPOT_LOG_LEVEL'] || default_log_level
+      case env_log_level.to_s.upcase
+      when 'DEBUG'
+        Logger::DEBUG
+      when 'INFO'
+        Logger::INFO
+      when 'WARN'
+        Logger::WARN
+      when 'ERROR'
+        Logger::ERROR
+      when 'FATAL'
+        Logger::FATAL
+      else
+        Logger::INFO # Default to INFO if unrecognized
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # Apply the log level to the logger
+    def apply_log_level
+      @logger.level = @log_level
+    end
+
+    # Set the default log level based on environment
+    def default_log_level
+      if defined?(Rails) && Rails.env.test?
+        'FATAL'  # Default to FATAL in test environments
+      else
+        'INFO'   # Default to INFO in normal usage
+      end
+    end
+  end
+end

data/lib/hubspot/contact.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Hubspot
+  class Contact < Resource
+  end
+end

data/lib/hubspot/exceptions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# The main hubspot module
+module Hubspot
+  # define the Hubspot specific error classes
+  class RequestError < StandardError
+    attr_accessor :response
+
+    def initialize(response, message = nil)
+      message = response.parsed_response['message'] if !message && response.respond_to?(:parsed_response)
+      message += "\n" if message
+      me = super("#{message}Response body: #{response.body}",)
+      me.response = response
+    end
+  end
+
+  class NotFoundError < RequestError; end
+  class OauthScopeError < RequestError; end
+  class RateLimitExceededError < RequestError; end
+  class NotConfiguredError < StandardError; end
+  class ArgumentError < StandardError; end
+
+  class << self
+    def error_from_response(response)
+      return NotFoundError.new(response) if response.not_found?
+      return RateLimitExceededError.new(response) if response.code == 429
+
+      case response.body
+      when /MISSING_SCOPES/, /You do not have permissions/i
+        OauthScopeError.new(response, 'Private app missing required scopes')
+      else
+        RequestError.new(response)
+      end
+    end
+  end
+end