halo_msp_api 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98f866a474dd58a86344301d4265af815a4d6582cabb6de0dfe5a94d572116d8
-  data.tar.gz: 450ae6c2367fd9acb743fb6b81a183f6218de528868de4dafc63c8893f18cffb
+  metadata.gz: 66a71218fe73c35441a0f239ab1c80a3879aac9d9c44116c167a260c6cf6cb3c
+  data.tar.gz: 8602e863b06f0e4fd6ea315da702c6e9f1f8e41fdbdb3f19c22e08c4dd5ab91c
 SHA512:
-  metadata.gz: b16bbea790fd1fbc1daf00ba83665261735569d9b0ab4d6fc0ce29562fdad32008220d950e59614712d74a43f476e452ab1e851c5336ea2639362096563c8d47
-  data.tar.gz: 1b09d2963bed4af41b7c0e680cf814cb05981c8379b333ed67316a1bf589cd6f3da08f6ec134ded8dfa6c6a029dac038ce8e61764b5be28a3ab442f2783cd13d
+  metadata.gz: a4fbc442112b4f78af465735d8b59b74f3cfed6308306d42810a550729aafe6ed8a61815d904841a648e956a11c1aed92f15bfe512423a9c848895962d9d4be8
+  data.tar.gz: 300aebb149d31b354667abc6845598739e74f8b60008702f8c418b3ab0159646e53c40996e1e11c12591097bb5df9b5c33acf227ece2fa56a517978f95605ad7

data/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-09-23
+
+### Added
+- Added methods for grabbing ticket statuses, categories, and other user defined attributes
+
+### Fixed
+- Fixed resource methods not using the correct method from the base class
+
+## [0.2.0] - 2025-09-15
+
+### Added
+- Products Resource Class
+
+### Fixed
+- Renamed Create/Update/Get/Delete methods in resource classes that caused an infinite recursion error
+- Fixed specs that were failing due to naming mismatched/mocking API requests
+
+### Changed
+- Updated `basic_usage.rb` examples to print specific data for verification
+- Updated project to adhere to rubocop linting rules
+- Removed support for Ruby 2.6 and 2.7 due to dependency incompatibilities
+
+### Deleted
+- Removed `/me/` calls from Clients and Users since those calls returned 500 from the HaloPSA API
+
 ## [0.1.0] - 2025-07-10
 
 ### Added

data/Gemfile

@@ -1,17 +1,12 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in halo_api.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
+gem 'rake', '~> 13.0'
 
 group :development, :test do
-  gem "rspec", "~> 3.0"
-  gem "rubocop", "~> 1.21"
-  gem "yard", "~> 0.9"
-  gem "webmock", "~> 3.0"
-  gem "vcr", "~> 6.0"
-  gem "pry", "~> 0.14"
+  gem 'pry'
 end

data/README.md

@@ -1,5 +1,7 @@
 # HaloMspApi Ruby Gem
 
+[![Gem Version](https://img.shields.io/gem/v/halo_msp_api)](https://rubygems.org/gems/halo_msp_api)
+
 A comprehensive Ruby API wrapper for the Halo ITSM, HaloPSA and HaloCRM REST API.
 
 ## Installation
@@ -53,13 +55,13 @@ client = HaloApi::Client.new(config)
 
 ```ruby
 # List all tickets
-tickets = client.tickets.list
+tickets = client.tickets.tickets
 
 # Get a specific ticket
-ticket = client.tickets.get(123)
+ticket = client.tickets.ticket(123)
 
 # Create a new ticket
-new_ticket = client.tickets.create({
+new_ticket = client.tickets.create_ticket({
   summary: "New ticket",
   details: "Ticket description",
   tickettype_id: 1,
@@ -67,23 +69,20 @@ new_ticket = client.tickets.create({
 })
 
 # Update a ticket
-client.tickets.update(123, { summary: "Updated summary" })
+client.tickets.update_ticket(123, { summary: "Updated summary" })
 
 # Delete a ticket
-client.tickets.delete(123)
+client.tickets.delete_ticket(123)
 ```
 
 ### Working with Users
 
 ```ruby
 # List all users
-users = client.users.list
-
-# Get current user
-current_user = client.users.me
+users = client.users.users
 
 # Create a new user
-new_user = client.users.create({
+new_user = client.users.create_user({
   name: "John Doe",
   emailaddress: "john@example.com"
 })
@@ -93,13 +92,13 @@ new_user = client.users.create({
 
 ```ruby
 # List all assets
-assets = client.assets.list
+assets = client.assets.assets
 
 # Get a specific asset
-asset = client.assets.get(123)
+asset = client.assets.asset(123)
 
 # Create a new asset
-new_asset = client.assets.create({
+new_asset = client.assets.create_asset({
   inventory_number: "ASSET001",
   assettype_id: 1
 })
@@ -109,13 +108,13 @@ new_asset = client.assets.create({
 
 ```ruby
 # List all clients
-clients = client.clients.list
+clients = client.clients.clients
 
 # Get a specific client
-client_record = client.clients.get(123)
+client_record = client.clients.client(123)
 
 # Create a new client
-new_client = client.clients.create({
+new_client = client.clients.create_client({
   name: "ACME Corp",
   website: "https://acme.com"
 })
@@ -125,13 +124,13 @@ new_client = client.clients.create({
 
 ```ruby
 # List all invoices
-invoices = client.invoices.list
+invoices = client.invoices.invoices
 
 # Get a specific invoice
-invoice = client.invoices.get(123)
+invoice = client.invoices.invoice(123)
 
 # Create a new invoice
-new_invoice = client.invoices.create({
+new_invoice = client.invoices.create_invoice({
   client_id: 1,
   invoicedate: "2023-01-01"
 })
@@ -144,10 +143,10 @@ pdf_data = client.invoices.pdf(123)
 
 ```ruby
 # List all reports
-reports = client.reports.list
+reports = client.reports.reports
 
 # Get a specific report
-report = client.reports.get(123)
+report = client.reports.report(123)
 
 # Get report data
 report_data = client.reports.data("published_report_id")
@@ -157,10 +156,10 @@ report_data = client.reports.data("published_report_id")
 
 ```ruby
 # Get Azure AD data
-azure_data = client.integrations.get_azure_ad
+azure_data = client.integrations.azure_ad
 
 # Get Slack data
-slack_data = client.integrations.get_slack
+slack_data = client.integrations.slack
 
 # Import Jira data
 client.integrations.import_jira(jira_data)
@@ -185,6 +184,7 @@ The gem provides access to the following Halo API resources:
 - **Quotations** - `client.quotations` - Quote management, approvals
 - **Sales Orders** - `client.sales_orders` - Sales order management
 - **Suppliers** - `client.suppliers` - Supplier and contract management
+- **Products** - `client.products` - Product management
 
 ### Service Management
 - **Appointments** - `client.appointments` - Scheduling and availability
@@ -207,20 +207,20 @@ The gem provides specific error classes for different types of API errors:
 
 ```ruby
 begin
-  ticket = client.tickets.get(999999)
-rescue HaloApi::NotFoundError
+  ticket = client.tickets.ticket(999999)
+rescue HaloMspApi::NotFoundError
   puts "Ticket not found"
-rescue HaloApi::AuthenticationError
+rescue HaloMspApi::AuthenticationError
   puts "Authentication failed"
-rescue HaloApi::AuthorizationError
+rescue HaloMspApi::AuthorizationError
   puts "Access forbidden"
-rescue HaloApi::ValidationError => e
+rescue HaloMspApi::ValidationError => e
   puts "Validation error: #{e.message}"
-rescue HaloApi::RateLimitError
+rescue HaloMspApi::RateLimitError
   puts "Rate limit exceeded"
-rescue HaloApi::ServerError
+rescue HaloMspApi::ServerError
   puts "Server error"
-rescue HaloApi::APIError => e
+rescue HaloMspApi::APIError => e
   puts "API error: #{e.message} (Status: #{e.status_code})"
 end
 ```
@@ -235,6 +235,6 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/examples/basic_usage.rb

@@ -1,70 +1,134 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "halo_msp_api"
+require 'bundler/setup'
+require 'halo_msp_api'
 
 # Configure the HaloMspApi gem
 HaloMspApi.configure do |config|
-  config.base_url = ENV["HALO_BASE_URL"] || "https://your-instance.haloitsm.com/api"
-  config.client_id = ENV["HALO_CLIENT_ID"] || "your_client_id"
-  config.client_secret = ENV["HALO_CLIENT_SECRET"] || "your_client_secret"
-  config.tenant = ENV["HALO_TENANT"] # Optional
+  config.base_url = ENV['HALO_BASE_URL'] || 'https://your-instance.haloitsm.com/api'
+  config.client_id = ENV['HALO_CLIENT_ID'] || 'your_client_id'
+  config.client_secret = ENV['HALO_CLIENT_SECRET'] || 'your_client_secret'
+  config.tenant = ENV['HALO_TENANT'] # Optional
   config.timeout = 30
   config.retries = 3
 end
 
 # Get a client instance
-client = HaloMspApi.client
+instance = HaloMspApi.client
 
 begin
-  puts "=== HaloApi Ruby Gem Example Usage ==="
+  puts '=== HaloApi Ruby Gem Example Usage ==='
   puts
 
   # Example 1: List tickets
-  puts "1. Fetching tickets..."
-  tickets = client.tickets.list(count: 5)
-  puts "Found #{tickets.dig('tickets')&.length || 0} tickets"
+  puts '1. Fetching tickets...'
+  tickets = instance.tickets.tickets(count: 5)
+  puts "Found #{tickets['tickets']&.length || 0} tickets"
+  if tickets['tickets']&.any?
+    puts 'Ticket summaries:'
+    tickets['tickets'].each do |ticket|
+      puts "- #{ticket['summary'] || 'Unknown'}"
+    end
+  end
   puts
 
-  # Example 2: Get current user
-  puts "2. Fetching current user..."
-  current_user = client.users.me
-  puts "Current user: #{current_user.dig('name') || 'Unknown'}"
+  # Example 2: List users
+  puts '2. Fetching users...'
+  users = instance.users.users(count: 5)
+  puts "Found #{users['users']&.length || 0} users"
+  if users['users']&.any?
+    puts 'User names:'
+    users['users'].each do |user|
+      puts "- #{user['name'] || 'Unknown'}"
+    end
+  end
   puts
 
-  # Example 3: List clients
-  puts "3. Fetching clients..."
-  clients = client.clients.list(count: 5)
-  puts "Found #{clients.dig('clients')&.length || 0} clients"
+  # Example 3: List companies
+  puts '3. Fetching clients...'
+  clients = instance.clients.clients(count: 5)
+  puts "Found #{clients['clients']&.length || 0} clients"
+  if clients['clients']&.any?
+    puts 'Client names:'
+    clients['clients'].each do |client_item|
+      puts "- #{client_item['name'] || 'Unknown'}"
+    end
+  end
   puts
 
   # Example 4: List assets
-  puts "4. Fetching assets..."
-  assets = client.assets.list(count: 5)
-  puts "Found #{assets.dig('assets')&.length || 0} assets"
+  puts '4. Fetching assets...'
+  assets = instance.assets.assets(count: 5)
+  puts "Found #{assets['assets']&.length || 0} assets"
+  if assets['assets']&.any?
+    puts 'Asset Inventory Number & Client Association:'
+    assets['assets'].each do |asset|
+      puts "- #{asset['inventory_number'] || 'Unknown'}: #{asset['client_name'] || 'Unknown'}"
+    end
+  end
   puts
 
   # Example 5: List invoices
-  puts "5. Fetching invoices..."
-  invoices = client.invoices.list(count: 5)
-  puts "Found #{invoices.dig('invoices')&.length || 0} invoices"
+  puts '5. Fetching invoices...'
+  invoices = instance.invoices.invoices(count: 5)
+  puts "Found #{invoices['invoices']&.length || 0} invoices"
+  if invoices['invoices']&.any?
+    puts 'Invoice ID and Client Association:'
+    invoices['invoices'].each do |invoice|
+      puts "- #{invoice['id'] || 'Unknown'}: #{invoice['client_name'] || 'Unknown'}"
+    end
+  end
   puts
 
   # Example 6: Get reports
-  puts "6. Fetching reports..."
-  reports = client.reports.list(count: 5)
-  puts "Found #{reports.dig('reports')&.length || 0} reports"
+  puts '6. Fetching reports...'
+  reports = instance.reports.reports(count: 5)
+  puts "Found #{reports['reports']&.length || 0} reports"
+  if reports['reports']&.any?
+    puts 'Report Names:'
+    reports['reports'].each do |report|
+      puts "- #{report['name'] || 'Unknown'}"
+    end
+  end
   puts
 
-  puts "=== Example completed successfully! ==="
+  # Example 7: Get contracts
+  puts '7. Fetching contracts...'
+  contracts = instance.clients.contracts(count: 5)
+  puts "Found #{contracts['contracts']&.length || 0} contracts"
+  if contracts['contracts']&.any?
+    puts 'Contract Client & Active:'
+    contracts['contracts'].each do |contract|
+      puts "- #{contract['client_name'] || 'Unknown'}: #{contract['active'] || 'Unknown'}"
+    end
+  end
+  puts
+
+  # Example 8: Get products
+  puts '8. Fetching products...'
+  products = instance.products.products(count: 5)
+  puts "Found #{products['items']&.length || 0} products"
+  if products['items']&.any?
+    puts 'Product Names:'
+    products['items'].each do |product|
+      puts "- #{product['name'] || 'Unknown'}"
+    end
+  end
+  puts
+
+  puts '9. Listing Statuses'
+  statuses = instance.tickets.statuses
+  puts "Found #{statuses&.length || 0} statuses"
+  puts "First Status: #{statuses.first['name']}"
 
+  puts '=== Example completed successfully! ==='
 rescue HaloMspApi::AuthenticationError => e
   puts "Authentication failed: #{e.message}"
-  puts "Please check your client_id and client_secret"
+  puts 'Please check your client_id and client_secret'
 rescue HaloMspApi::AuthorizationError => e
   puts "Authorization failed: #{e.message}"
-  puts "Please check your permissions"
+  puts 'Please check your permissions'
 rescue HaloMspApi::APIError => e
   puts "API Error: #{e.message}"
   puts "Status Code: #{e.status_code}" if e.respond_to?(:status_code)

data/lib/halo_msp_api/client.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
-require "faraday"
-require "faraday/retry"
-require "json"
+require 'faraday'
+require 'faraday/retry'
+require 'json'
 
 module HaloMspApi
+  # Client class for Halo MSP API
+  # rubocop:disable Metrics/ClassLength
   class Client
     attr_reader :configuration, :connection
 
     def initialize(configuration = nil)
-      @configuration = configuration || HaloApi.configuration
-      raise ConfigurationError, "Configuration is required" unless @configuration&.valid?
+      @configuration = configuration || HaloMspApi.configuration
+      raise ConfigurationError, 'Configuration is required' unless @configuration&.valid?
 
       @connection = build_connection
       @access_token = nil
@@ -38,6 +40,10 @@ module HaloMspApi
       @clients ||= Resources::Clients.new(self)
     end
 
+    def contracts
+      @contracts ||= Resources::Contracts.new(self)
+    end
+
     def integrations
       @integrations ||= Resources::Integrations.new(self)
     end
@@ -54,6 +60,10 @@ module HaloMspApi
       @organisations ||= Resources::Organisations.new(self)
     end
 
+    def products
+      @products ||= Resources::Products.new(self)
+    end
+
     def purchase_orders
       @purchase_orders ||= Resources::PurchaseOrders.new(self)
     end
@@ -117,13 +127,15 @@ module HaloMspApi
 
     private
 
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/MethodLength
     def request(method, path, data = {})
       ensure_authenticated!
 
       response = connection.send(method) do |req|
         req.url path
-        req.headers["Authorization"] = "Bearer #{@access_token}"
-        req.headers["Content-Type"] = "application/json"
+        req.headers['Authorization'] = "Bearer #{@access_token}"
+        req.headers['Content-Type'] = 'application/json'
 
         if %i[post put patch].include?(method) && !data.empty?
           req.body = data.to_json
@@ -134,31 +146,37 @@ module HaloMspApi
 
       handle_response(response)
     rescue Faraday::TimeoutError
-      raise TimeoutError, "Request timed out"
+      raise TimeoutError, 'Request timed out'
     rescue Faraday::ConnectionFailed
-      raise ConnectionError, "Connection failed"
+      raise ConnectionError, 'Connection failed'
     end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
 
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/MethodLength
     def handle_response(response)
       case response.status
       when 200..299
         parse_response(response)
       when 401
-        raise AuthenticationError, "Authentication failed"
+        raise AuthenticationError, 'Authentication failed'
       when 403
-        raise AuthorizationError, "Access forbidden"
+        raise AuthorizationError, 'Access forbidden'
       when 404
-        raise NotFoundError, "Resource not found"
+        raise NotFoundError, 'Resource not found'
       when 422
         raise ValidationError, "Validation error: #{response.body}"
       when 429
-        raise RateLimitError, "Rate limit exceeded"
+        raise RateLimitError, 'Rate limit exceeded'
       when 500..599
         raise ServerError, "Server error: #{response.status}"
       else
-        raise APIError.new("Unexpected response", status_code: response.status, response_body: response.body)
+        raise APIError.new('Unexpected response', status_code: response.status, response_body: response.body)
       end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/MethodLength
 
     def parse_response(response)
       return nil if response.body.nil? || response.body.empty?
@@ -178,32 +196,34 @@ module HaloMspApi
       @access_token && @token_expires_at && Time.now < @token_expires_at
     end
 
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/MethodLength
     def authenticate!
       auth_params = {
-        grant_type: "client_credentials",
+        grant_type: 'client_credentials',
         client_id: configuration.client_id,
         client_secret: configuration.client_secret,
-        scope: "all"
+        scope: 'all'
       }
-      
+
       # Include tenant if configured (required for multi-tenant instances)
       auth_params[:tenant] = configuration.tenant if configuration.tenant
-      
-      auth_response = connection.post("/auth/token") do |req|
-        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+
+      auth_response = connection.post('/auth/token') do |req|
+        req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
         req.body = URI.encode_www_form(auth_params)
       end
 
-      if auth_response.status == 200
-        token_data = JSON.parse(auth_response.body)
-        @access_token = token_data["access_token"]
-        @token_expires_at = Time.now + token_data["expires_in"].to_i
-      else
-        raise AuthenticationError, "Failed to authenticate: #{auth_response.body}"
-      end
+      raise AuthenticationError, "Failed to authenticate: #{auth_response.body}" unless auth_response.status == 200
+
+      token_data = JSON.parse(auth_response.body)
+      @access_token = token_data['access_token']
+      @token_expires_at = Time.now + token_data['expires_in'].to_i
     rescue JSON::ParserError
-      raise AuthenticationError, "Invalid authentication response"
+      raise AuthenticationError, 'Invalid authentication response'
     end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
 
     def build_connection
       Faraday.new(url: configuration.base_url) do |conn|
@@ -214,3 +234,4 @@ module HaloMspApi
     end
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/halo_msp_api/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module HaloMspApi
+  # HaloMspApi Configuration Class
   class Configuration
     attr_accessor :base_url, :client_id, :client_secret, :tenant, :timeout, :retries
 

data/lib/halo_msp_api/error.rb

@@ -13,6 +13,7 @@ module HaloMspApi
   class TimeoutError < Error; end
   class ConnectionError < Error; end
 
+  # Class for handling API Errors
   class APIError < Error
     attr_reader :status_code, :response_body