halo_msp_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98f866a474dd58a86344301d4265af815a4d6582cabb6de0dfe5a94d572116d8
+  data.tar.gz: 450ae6c2367fd9acb743fb6b81a183f6218de528868de4dafc63c8893f18cffb
+SHA512:
+  metadata.gz: b16bbea790fd1fbc1daf00ba83665261735569d9b0ab4d6fc0ce29562fdad32008220d950e59614712d74a43f476e452ab1e851c5336ea2639362096563c8d47
+  data.tar.gz: 1b09d2963bed4af41b7c0e680cf814cb05981c8379b333ed67316a1bf589cd6f3da08f6ec134ded8dfa6c6a029dac038ce8e61764b5be28a3ab442f2783cd13d

data/.rspec

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

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+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.1.0] - 2025-07-10
+
+### Added
+
+- Initial gem structure and foundation
+- Core API client implementation
+- Resource-based API organization
+- Authentication and configuration system
+- Basic test coverage
+- Documentation and examples

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in halo_api.gemspec
+gemspec
+
+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"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Evo Security
+
+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,240 @@
+# HaloMspApi Ruby Gem
+
+A comprehensive Ruby API wrapper for the Halo ITSM, HaloPSA and HaloCRM REST API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'halo_msp_api'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install halo_msp_api
+
+## Configuration
+
+Configure the gem with your Halo API credentials:
+
+```ruby
+HaloMspApi.configure do |config|
+  config.base_url = "https://your-halo-instance.haloitsm.com/api"
+  config.client_id = "your_client_id"
+  config.client_secret = "your_client_secret"
+  config.tenant = "your_tenant" # Optional
+  config.timeout = 30 # Optional, default is 30 seconds
+  config.retries = 3 # Optional, default is 3 retries
+end
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+# Initialize client
+client = HaloMspApi.client
+
+# Or create a new client with custom configuration
+config = HaloMspApi::Configuration.new
+config.base_url = "https://your-instance.haloitsm.com/api"
+config.client_id = "your_client_id"
+config.client_secret = "your_client_secret"
+client = HaloApi::Client.new(config)
+```
+
+### Working with Tickets
+
+```ruby
+# List all tickets
+tickets = client.tickets.list
+
+# Get a specific ticket
+ticket = client.tickets.get(123)
+
+# Create a new ticket
+new_ticket = client.tickets.create({
+  summary: "New ticket",
+  details: "Ticket description",
+  tickettype_id: 1,
+  client_id: 1
+})
+
+# Update a ticket
+client.tickets.update(123, { summary: "Updated summary" })
+
+# Delete a ticket
+client.tickets.delete(123)
+```
+
+### Working with Users
+
+```ruby
+# List all users
+users = client.users.list
+
+# Get current user
+current_user = client.users.me
+
+# Create a new user
+new_user = client.users.create({
+  name: "John Doe",
+  emailaddress: "john@example.com"
+})
+```
+
+### Working with Assets
+
+```ruby
+# List all assets
+assets = client.assets.list
+
+# Get a specific asset
+asset = client.assets.get(123)
+
+# Create a new asset
+new_asset = client.assets.create({
+  inventory_number: "ASSET001",
+  assettype_id: 1
+})
+```
+
+### Working with Clients
+
+```ruby
+# List all clients
+clients = client.clients.list
+
+# Get a specific client
+client_record = client.clients.get(123)
+
+# Create a new client
+new_client = client.clients.create({
+  name: "ACME Corp",
+  website: "https://acme.com"
+})
+```
+
+### Working with Invoices
+
+```ruby
+# List all invoices
+invoices = client.invoices.list
+
+# Get a specific invoice
+invoice = client.invoices.get(123)
+
+# Create a new invoice
+new_invoice = client.invoices.create({
+  client_id: 1,
+  invoicedate: "2023-01-01"
+})
+
+# Get invoice PDF
+pdf_data = client.invoices.pdf(123)
+```
+
+### Working with Reports
+
+```ruby
+# List all reports
+reports = client.reports.list
+
+# Get a specific report
+report = client.reports.get(123)
+
+# Get report data
+report_data = client.reports.data("published_report_id")
+```
+
+### Working with Integrations
+
+```ruby
+# Get Azure AD data
+azure_data = client.integrations.get_azure_ad
+
+# Get Slack data
+slack_data = client.integrations.get_slack
+
+# Import Jira data
+client.integrations.import_jira(jira_data)
+```
+
+## API Resources
+
+The gem provides access to the following Halo API resources:
+
+### Core Business Objects
+- **Actions** - `client.actions` - Ticket actions and reactions
+- **Agents** - `client.agents` - Agent management, check-ins, presence
+- **Assets** - `client.assets` - Asset management, groups, software, types
+- **Tickets** - `client.tickets` - Comprehensive ticket management
+- **Users** - `client.users` - User management, preferences, roles
+- **Clients** - `client.clients` - Client management, contracts, prepayments
+- **Organisations** - `client.organisations` - Organization management
+
+### Financial Management
+- **Invoices** - `client.invoices` - Invoice management, payments, recurring invoices
+- **Purchase Orders** - `client.purchase_orders` - PO management, approvals, lines
+- **Quotations** - `client.quotations` - Quote management, approvals
+- **Sales Orders** - `client.sales_orders` - Sales order management
+- **Suppliers** - `client.suppliers` - Supplier and contract management
+
+### Service Management
+- **Appointments** - `client.appointments` - Scheduling and availability
+- **Services** - `client.services` - Service management, availability, categories
+- **SLAs** - `client.slas` - SLA policies and targets
+
+### Knowledge & Communication
+- **Knowledge Base** - `client.knowledge_base` - KB articles, categories, keywords
+- **Webhooks** - `client.webhooks` - Webhook management and subscriptions
+
+### Reporting & Analytics
+- **Reports** - `client.reports` - Reporting, bookmarks, repositories
+
+### Integration Services
+- **Integrations** - `client.integrations` - Third-party integration support (Azure, Slack, Jira, etc.)
+
+## Error Handling
+
+The gem provides specific error classes for different types of API errors:
+
+```ruby
+begin
+  ticket = client.tickets.get(999999)
+rescue HaloApi::NotFoundError
+  puts "Ticket not found"
+rescue HaloApi::AuthenticationError
+  puts "Authentication failed"
+rescue HaloApi::AuthorizationError
+  puts "Access forbidden"
+rescue HaloApi::ValidationError => e
+  puts "Validation error: #{e.message}"
+rescue HaloApi::RateLimitError
+  puts "Rate limit exceeded"
+rescue HaloApi::ServerError
+  puts "Server error"
+rescue HaloApi::APIError => e
+  puts "API error: #{e.message} (Status: #{e.status_code})"
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/evosecurity/HaloAPI-Ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 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.
+
+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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/basic_usage.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+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.timeout = 30
+  config.retries = 3
+end
+
+# Get a client instance
+client = HaloMspApi.client
+
+begin
+  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
+
+  # Example 2: Get current user
+  puts "2. Fetching current user..."
+  current_user = client.users.me
+  puts "Current user: #{current_user.dig('name') || 'Unknown'}"
+  puts
+
+  # Example 3: List clients
+  puts "3. Fetching clients..."
+  clients = client.clients.list(count: 5)
+  puts "Found #{clients.dig('clients')&.length || 0} clients"
+  puts
+
+  # Example 4: List assets
+  puts "4. Fetching assets..."
+  assets = client.assets.list(count: 5)
+  puts "Found #{assets.dig('assets')&.length || 0} assets"
+  puts
+
+  # Example 5: List invoices
+  puts "5. Fetching invoices..."
+  invoices = client.invoices.list(count: 5)
+  puts "Found #{invoices.dig('invoices')&.length || 0} invoices"
+  puts
+
+  # Example 6: Get reports
+  puts "6. Fetching reports..."
+  reports = client.reports.list(count: 5)
+  puts "Found #{reports.dig('reports')&.length || 0} reports"
+  puts
+
+  puts "=== Example completed successfully! ==="
+
+rescue HaloMspApi::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+  puts "Please check your client_id and client_secret"
+rescue HaloMspApi::AuthorizationError => e
+  puts "Authorization failed: #{e.message}"
+  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)
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+  puts e.backtrace.first(5)
+end

data/lib/halo_msp_api/client.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module HaloMspApi
+  class Client
+    attr_reader :configuration, :connection
+
+    def initialize(configuration = nil)
+      @configuration = configuration || HaloApi.configuration
+      raise ConfigurationError, "Configuration is required" unless @configuration&.valid?
+
+      @connection = build_connection
+      @access_token = nil
+      @token_expires_at = nil
+    end
+
+    # Resource accessors
+    def actions
+      @actions ||= Resources::Actions.new(self)
+    end
+
+    def agents
+      @agents ||= Resources::Agents.new(self)
+    end
+
+    def appointments
+      @appointments ||= Resources::Appointments.new(self)
+    end
+
+    def assets
+      @assets ||= Resources::Assets.new(self)
+    end
+
+    def clients
+      @clients ||= Resources::Clients.new(self)
+    end
+
+    def integrations
+      @integrations ||= Resources::Integrations.new(self)
+    end
+
+    def invoices
+      @invoices ||= Resources::Invoices.new(self)
+    end
+
+    def knowledge_base
+      @knowledge_base ||= Resources::KnowledgeBase.new(self)
+    end
+
+    def organisations
+      @organisations ||= Resources::Organisations.new(self)
+    end
+
+    def purchase_orders
+      @purchase_orders ||= Resources::PurchaseOrders.new(self)
+    end
+
+    def quotations
+      @quotations ||= Resources::Quotations.new(self)
+    end
+
+    def reports
+      @reports ||= Resources::Reports.new(self)
+    end
+
+    def services
+      @services ||= Resources::Services.new(self)
+    end
+
+    def tickets
+      @tickets ||= Resources::Tickets.new(self)
+    end
+
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+
+    def sales_orders
+      @sales_orders ||= Resources::SalesOrders.new(self)
+    end
+
+    def slas
+      @slas ||= Resources::Slas.new(self)
+    end
+
+    def suppliers
+      @suppliers ||= Resources::Suppliers.new(self)
+    end
+
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(self)
+    end
+
+    # HTTP methods
+    def get(path, params = {})
+      request(:get, path, params)
+    end
+
+    def post(path, body = {})
+      request(:post, path, body)
+    end
+
+    def put(path, body = {})
+      request(:put, path, body)
+    end
+
+    def patch(path, body = {})
+      request(:patch, path, body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    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"
+
+        if %i[post put patch].include?(method) && !data.empty?
+          req.body = data.to_json
+        elsif method == :get && !data.empty?
+          req.params = data
+        end
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError
+      raise TimeoutError, "Request timed out"
+    rescue Faraday::ConnectionFailed
+      raise ConnectionError, "Connection failed"
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        parse_response(response)
+      when 401
+        raise AuthenticationError, "Authentication failed"
+      when 403
+        raise AuthorizationError, "Access forbidden"
+      when 404
+        raise NotFoundError, "Resource not found"
+      when 422
+        raise ValidationError, "Validation error: #{response.body}"
+      when 429
+        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)
+      end
+    end
+
+    def parse_response(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def ensure_authenticated!
+      return if token_valid?
+
+      authenticate!
+    end
+
+    def token_valid?
+      @access_token && @token_expires_at && Time.now < @token_expires_at
+    end
+
+    def authenticate!
+      auth_params = {
+        grant_type: "client_credentials",
+        client_id: configuration.client_id,
+        client_secret: configuration.client_secret,
+        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"
+        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
+    rescue JSON::ParserError
+      raise AuthenticationError, "Invalid authentication response"
+    end
+
+    def build_connection
+      Faraday.new(url: configuration.base_url) do |conn|
+        conn.request :retry, max: configuration.retries
+        conn.options.timeout = configuration.timeout
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/halo_msp_api/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module HaloMspApi
+  class Configuration
+    attr_accessor :base_url, :client_id, :client_secret, :tenant, :timeout, :retries
+
+    def initialize
+      @base_url = nil
+      @client_id = nil
+      @client_secret = nil
+      @tenant = nil
+      @timeout = 30
+      @retries = 3
+    end
+
+    def valid?
+      !base_url.nil? && !client_id.nil? && !client_secret.nil?
+    end
+  end
+end

data/lib/halo_msp_api/error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module HaloMspApi
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+  class AuthorizationError < Error; end
+  class NotFoundError < Error; end
+  class ValidationError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+  class TimeoutError < Error; end
+  class ConnectionError < Error; end
+
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+end