sophos_central_api 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de42982e7073acef13887732efb277b3f24e31fcf34552f7857100edc20b99a2
-  data.tar.gz: 40425c2083e372ea6434f86723209ddd1673a1055ca8fc26e9bac997fb961305
+  metadata.gz: d47cbadb0dff8019efbbac91b9690e5155653a24ae60eeb724fff45edaa90d87
+  data.tar.gz: a3a28af07f86c764b7fbfbcb03dcfaf47fce8ab23d30a8ddeea4d95407f8909f
 SHA512:
-  metadata.gz: 4c3655439d962b32baef1e85a1ec31e4442c103472a82d0a2388d271fccde35c2fadb43088fd07db5ef3676d99331cea568f4019f61705b54a88577a7f97e073
-  data.tar.gz: 47cc68a252b5ad954f6bb6b48aae862b27e48ab35e0bacdb8c1fb605dd4d322d2af1325ec5457bef5ad6c970d20ac5f01c23e30705bd41f50c58a0c0e55c208b
+  metadata.gz: 1ddc293f17bf92585c4cd21517ca405ab985a7d848d73195b9a4e59649be8950ff773faeba68cc21d895e4e3885600c9add869710cfcd6a68f65472152c34e09
+  data.tar.gz: 40c45c25bd5d6b4d8261b0fa39313f081e81ce350a2818732071a11b9f4347ceb7b3bb42adab53d39513dfca23563d55d01423d263f65cdfeab4b943c9fb6e20

data/CHANGELOG.md

@@ -1,13 +1,26 @@
-## [Unreleased]
+# Changelog
 
 ## [0.1.0] - 2024-02-14
+
 - Initial release
 
 ## [0.1.1] - 2024-02-14
+
 - Convienience method added to get client for a teannt api host
 
 ## [0.1.2] - 2024-02-15
+
 - Fix initialization issue
 
 ## [0.2.0] - 2024-02-20
+
 - Configuration and authentication exceptions changed
+
+## [0.2.1] - 2024-07-17
+
+- Fix issue with paging for endpoints
+
+## [0.2.2] - 2025-03-21
+
+- Update docs, formatting
+

data/Gemfile

@@ -8,4 +8,4 @@ gemspec
 gem 'rake', '~> 13.0'
 gem 'rubocop', '~> 1.7'
 gem 'simplecov', require: false, group: :test
-gem 'wrapi'
+gem 'wrapi'

data/README.md

@@ -1,11 +1,14 @@
 # Sophos Central Partner API
+
 [![Version](https://img.shields.io/gem/v/sophos_central_api.svg)](https://rubygems.org/gems/sophos_central_api)
 [![Maintainability](https://api.codeclimate.com/v1/badges/0e0c212559aad49a915c/maintainability)](https://codeclimate.com/github/jancotanis/sophos/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/0e0c212559aad49a915c/test_coverage)](https://codeclimate.com/github/jancotanis/sophos/test_coverage)
 
-This is a wrapper for the Sophos Central Partner API. You can see the API endpoints here https://developer.sophos.com/getting-started
+This is a wrapper for the Sophos Central Partner API.
+You can see the [API endpoints](https://developer.sophos.com/getting-started)
 
-Currently only the GET requests to customers, endpoints and alerts are implemented (readonly).
+Currently only the GET requests to customers, endpoints and
+alerts are implemented (readonly).
 
 ## Installation
 
@@ -17,17 +20,22 @@ gem 'sophos_central_api'
 
 And then execute:
 
-    $ bundle install
+```console
+> bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install sophos_central_api
+```console
+> gem install sophos_central_api
+```
 
 ## Usage
 
-Before you start making the requests to API provide the client id and client secret and email/password using the configuration wrapping.
+Before you start making the requests to API provide the client id and client secret
+and email/password using the configuration wrapping.
 
-```
+```ruby
 require 'sophos_central_api'
 
 Sophos.configure do |config|
@@ -45,20 +53,25 @@ end
 ```
 
 ## Resources
+
 ### Authentication
-```
+
+```ruby
 # setup configuration
 #
 client.login
 ```
+
 |Resource|API endpoint|Description|
 |:--|:--|:--|
-|.login||
+|.login|||
 
 
 ### Partner
-Endpoint for partner  related requests 
-```
+
+Endpoint for partner  related requests
+
+```ruby
 roles = client.roles
 ```
 
@@ -69,14 +82,14 @@ roles = client.roles
 |.admins, .admin(id)              |/partner/v1/admins/{id}|
 |.admin_role_assignments(admin_id)|/partner/v1/admins/{admin_id}/role-assignments|
 |.admin_role_assignment(admin_id,assignment_id)|/partner/v1/admins/{admin_id}/role-assignments/{assignment_id}|
-|.permission_sets				  |/partner/v1/roles/permission-sets|
-|.billing_usage(year, month)	  |/partner/v1/billing-usage/{year}/{month}|
-
+|.permission_sets				          |/partner/v1/roles/permission-sets|
+|.billing_usage(year, month)	    |/partner/v1/billing-usage/{year}/{month}|
 
 ### Common
+
 This is the OAS 3.0 specification for the Common API in Sophos Central.
 
-```
+```ruby
 @client = Sophos.client()
 @client.login
  :
@@ -88,15 +101,17 @@ tenant = @client.tenant(id)
 
 |Resource|API endpoint|
 |:--|:--|
-|.alerts, .alert(id)								|.../alerts/|
+|.alerts, .alert(id)                      |.../alerts/|
 |.directory_user_groups, .directory_user_groups(id)	|.../directory/user-groups|
-|.directory_user_group_users(id)					|.../directory/user-groups/{id}/users|
-|.directory_users, .directory_user(id)				|.../directory/users|
-|.directory_user_groups(id)							|.../directory/users/{id}/groups|
+|.directory_user_group_users(id)          |.../directory/user-groups/{id}/users|
+|.directory_users, .directory_user(id)    |.../directory/users|
+|.directory_user_groups(id)               |.../directory/users/{id}/groups|
 
 ### Endpoints
+
 Returns endpoint for a provided tenant
-```
+
+```ruby
 @client = Sophos.client()
 @client.login
  :
@@ -107,18 +122,18 @@ tenant = @client.tenant(id)
 
 |Resource|API endpoint|
 |:--|:--|
-|.downloads								|.../downloads/|
-|.endpoint_groups, .endpoint_group(id)	|.../endpoint-groupss/|
-|.migrations, .migration(id)			|.../migrations|
-|.migration_endpoints(migration_id)		|.../migrations/{migration_id}/endpoints|
-|.policies, .policy(id)					|.../policies/{id}|
-|.endpoints								|.../endpoints|
-|.endpoint_isolation(endpoint_id)		|.../endpoints/{id}/isolation|
+|.downloads                              |.../downloads/|
+|.endpoint_groups, .endpoint_group(id)   |.../endpoint-groupss/|
+|.migrations, .migration(id)             |.../migrations|
+|.migration_endpoints(migration_id)      |.../migrations/{migration_id}/endpoints|
+|.policies, .policy(id)                  |.../policies/{id}|
+|.endpoints                              |.../endpoints|
+|.endpoint_isolation(endpoint_id)        |.../endpoints/{id}/isolation|
 |.endpoint_tamper_protection(endpoint_id)|.../endpoints/{id}/tamper-protection|
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jancotanis/sophos.
+Bug reports and pull requests are welcome on [GitHub](https://github.com/jancotanis/sophos).
 
 ## License
 

data/lib/sophos/api.rb

@@ -1,30 +1,53 @@
-require "wrapi"
+# frozen_string_literal: true
+
+require 'wrapi'
 require File.expand_path('configuration', __dir__)
 require File.expand_path('authentication', __dir__)
 
 module Sophos
-  # @private
-  
+  # Handles API configuration, connections, and authentication.
+  # This class manages settings such as API keys, tokens, and endpoint configurations,
+  # and includes necessary modules for making authenticated API calls.
   class API
-    # @private
-    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+    # Attribute accessors for configuration keys
+    # These keys include essential settings such as client ID, client secret, and API endpoint.
+    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
 
-    # Creates a new API and copies settings from singleton
+    # Initializes a new API instance and applies configuration settings.
+    #
+    # @param options [Hash] A hash of options to configure the API.
+    #   These options are merged with global configuration settings.
+    #
+    # @example Initialize a new API instance with custom options:
+    #   api = Sophos::API.new(client_id: 'your_client_id', client_secret: 'your_client_secret')
+    #
     def initialize(options = {})
+      # Merge provided options with the global Sophos configuration
       options = Sophos.options.merge(options)
+
+      # Set instance variables for each valid configuration key
       Configuration::VALID_OPTIONS_KEYS.each do |key|
         send("#{key}=", options[key])
       end
     end
 
+    # Returns the current API configuration as a hash.
+    #
+    # @return [Hash] A hash of the current API configuration.
+    #
+    # @example Retrieve the current API configuration:
+    #   api = Sophos::API.new
+    #   api.config  # => { client_id: 'abc', client_secret: 'xyz' }
+    #
     def config
       conf = {}
       Configuration::VALID_OPTIONS_KEYS.each do |key|
-        conf[key] = send key
+        conf[key] = send(key)
       end
       conf
     end
 
+    # Including modules for API connection, request handling, and authentication
     include Configuration
     include WrAPI::Connection
     include WrAPI::Request

data/lib/sophos/authentication.rb

@@ -1,39 +1,53 @@
+# frozen_string_literal: true
+
 require 'faraday'
 require 'json'
 require 'uri'
 require File.expand_path('error', __dir__)
 
 module Sophos
-  # Deals with authentication flow and stores it within global configuration
+  # Handles authentication flow for accessing Sophos APIs and stores tokens in global configuration.
+  # This module manages OAuth2-based token generation and sets up the API connection with authorization headers.
+  # 
+  # @note Ensure that `client_id` and `client_secret` are configured before calling authentication methods.
+  # @see https://developer.sophos.com/getting-started
   module Authentication
 
-    # Authorize to the Sophos portal and return access_token
-    # @see https://developer.sophos.com/getting-started
-    def auth_token(options = {})
+    # Authorizes with the Sophos portal and retrieves an access token.
+    # This method performs an OAuth2 client credentials flow, returning a valid token.
+    #
+    # @param _options [Hash] (optional) Any additional options for the request.
+    # @return [String] Access token for the Sophos API.
+    # @raise [ConfigurationError] If `client_id` or `client_secret` is not set.
+    # @raise [AuthenticationError] If authentication fails due to invalid credentials or other errors.
+    #
+    # @example Authenticate and retrieve a token:
+    #   api.auth_token
+    #
+    def auth_token(_options = {})
       raise ConfigurationError.new 'Client id and/or secret not configured' unless client_id && client_secret
-      # use id endpoint instead of global api
-      response = connection.post(id_endpoint+'/api/v2/oauth2/token') do |request|
+
+      # POST request to obtain the OAuth2 token using client credentials
+      response = connection.post("#{id_endpoint}/api/v2/oauth2/token") do |request|
         request.headers['Content-Type'] = 'application/x-www-form-urlencoded'
-        request.body = URI.encode_www_form( api_access_token_params )
+        request.body = URI.encode_www_form(api_access_token_params)
       end
+
       api_process_token(response.body)
+      setup_connection
 
-      # use default endpoint and replace it with global endpoint
-      partner = self.get( "/whoami/v1" )
-      if 'partner'.eql?(partner.idType) && partner.id
-        self.partner_id = partner.id
-        self.endpoint = partner.apiHosts.global
-        self.connection_options = { headers: { 'X-partner-id': self.partner_id } }
-      else
-        raise AuthenticationError.new 'Partner id not returned; response ' + response.to_s
-      end
+      # Returns the generated access token
+      self.access_token
     rescue Faraday::UnauthorizedError => e
-        raise AuthenticationError.new 'Unauthorized; response ' + e.to_s
+      raise AuthenticationError.new "Unauthorized; response #{e}"
     end
     alias login auth_token
 
-  private
+    private
 
+    # Builds the request body parameters for the token request.
+    # 
+    # @return [Hash] Parameters required for the client credentials grant type.
     def api_access_token_params
       {
         grant_type: 'client_credentials',
@@ -43,14 +57,36 @@ module Sophos
       }
     end
 
+    # Processes the token response and extracts authentication details.
+    #
+    # @param response [Hash] The HTTP response body containing the OAuth2 token data.
+    # @raise [AuthenticationError] If `access_token` is missing or invalid.
     def api_process_token(response)
-      at = self.access_token = response['access_token']
-      self.token_type        = response['token_type']
-      self.refresh_token     = response['refresh_token']
-      self.token_expires     = response['expires_in']
-      raise AuthenticationError.new 'Could not find valid access_token; response ' + response.to_s if at.nil? || at.empty?
+      self.access_token  = response['access_token']
+      self.token_type    = response['token_type']
+      self.refresh_token = response['refresh_token']
+      self.token_expires = response['expires_in']
 
-      at
+      if self.access_token.nil? || self.access_token.empty?
+        raise AuthenticationError.new "Could not find valid access_token; response #{response}"
+      end
+    end
+
+    # Sets up the API connection using the authenticated token and partner-specific settings.
+    #
+    # This method retrieves the partner ID, sets the global endpoint, and configures headers.
+    # 
+    # @raise [AuthenticationError] If the partner ID is not returned in the `whoami` response.
+    def setup_connection
+      partner = self.get("/whoami/v1")
+
+      if 'partner'.eql?(partner.idType) && partner.id
+        self.partner_id = partner.id
+        self.endpoint = partner.apiHosts.global
+        self.connection_options = { headers: { 'X-partner-id': self.partner_id } }
+      else
+        raise AuthenticationError.new "Partner id not returned; response #{partner}"
+      end
     end
   end
 end

data/lib/sophos/client/common.rb

@@ -1,25 +1,46 @@
-module Sophos
+# frozen_string_literal: true
 
+module Sophos
   class Client
     require File.expand_path('helper', __dir__)
     include Sophos::Client::Helper
 
-    # This is the OAS 3.0 specification for the Common API in Sophos Central.
+    # Common API module for handling various endpoints in Sophos Central.
+    # This module provides access to alerts, directory users, and user groups.
     # @see https://developer.sophos.com/docs/common-v1/1/overview
     module Common
-
+      # Define API calls using helper methods for common endpoints.
+      # These methods automatically create GET calls to the specified URL.
+      #
       # @see https://developer.sophos.com/docs/common-v1/1/routes/alerts/get
       Helper::def_api_call :alerts, Helper::common_url(:alerts)
+
       # @see https://developer.sophos.com/docs/common-v1/1/routes/directory/user-groups/get
       Helper::def_api_call :directory_user_groups, Helper::common_url('directory/user-groups')
+
+      # Fetch paginated users in a specified user group.
+      # @param group_id [String] The ID of the user group.
+      # @param params [Hash] Additional query parameters (e.g., `pageSize`, `page`).
+      # @return [Hash] API response containing users in the specified group.
+      # @see https://developer.sophos.com/docs/common-v1/1/routes/directory/user-groups/get
       def directory_user_group_users(group_id, params = {})
         get_paged(Helper::common_url("directory/user-groups/#{group_id}/users"), params)
       end
+
+      # Define an API call to fetch all directory users.
+      # @see https://developer.sophos.com/docs/common-v1/1/routes/directory/users/get
       Helper::def_api_call :directory_users, Helper::common_url('directory/users')
+
+      # Fetch paginated user groups for a specified user.
+      # @param user_id [String] The ID of the user.
+      # @param params [Hash] Additional query parameters (e.g., `pageSize`, `page`).
+      # @return [Hash] API response containing groups the user belongs to.
+      # @see https://developer.sophos.com/docs/common-v1/1/routes/directory/users/get
       def directory_user_groups(user_id, params = {})
         get_paged(Helper::common_url("directory/users/#{user_id}/groups"), params)
       end
-      # roles and admins can be retrieved using the partner api
+
+      # Additional methods for roles and admins can be retrieved using the partner API.
     end
   end
 end

data/lib/sophos/client/endpoint.rb

@@ -1,40 +1,66 @@
+# frozen_string_literal: true
+
 module Sophos
   class Client
     require File.expand_path('helper', __dir__)
     include Sophos::Client::Helper
 
-    # Sophos Endpoint api
+    # Module to interact with Sophos Endpoint API
     # @see https://developer.sophos.com/docs/endpoint-v1/1/overview
     module Endpoint
 
+      # Define API calls with dynamic helper methods for common endpoints.
+
+      # Fetch available software downloads.
       # @see https://developer.sophos.com/docs/endpoint-v1/1/routes/downloads/get
       Helper::def_api_call :downloads, Helper::endpoint_url(:downloads)
 
+      # Fetch all endpoint groups.
       # @see https://developer.sophos.com/docs/endpoint-v1/1/routes/endpoint-groups/get
       Helper::def_api_call :endpoint_groups, Helper::endpoint_url(:endpoint_groups), :endpoint_group
+
+      # Fetch endpoints belonging to a specific endpoint group.
+      # @param group_id [String] The ID of the endpoint group.
+      # @return [Array<Hash>] Paginated response with endpoint details.
       def endpoint_group_endpoints(group_id)
         get_paged Helper::endpoint_url("endpoint-groups/#{group_id}/endpoints")
       end
 
+      # Fetch details on endpoint migrations.
       # @see https://developer.sophos.com/docs/endpoint-v1/1/routes/migrations/get
       Helper::def_api_call :migrations, Helper::endpoint_url(:migrations), :migration
+
+      # Fetch endpoints involved in a specific migration.
+      # @param migration_id [String] The ID of the migration.
+      # @return [Array<Hash>] Paginated response with endpoints involved in the migration.
       def migration_endpoints(migration_id)
         get_paged Helper::endpoint_url("migrations/#{migration_id}/endpoints")
       end
 
+      # Fetch policy details for the tenant.
       # @see https://developer.sophos.com/docs/endpoint-v1/1/routes/policies/get
       Helper::def_api_call :policies, Helper::endpoint_url(:policies), :policy
 
-      # Get all the endpoints for the specified tenant. No endpoint method defined as this clashes with api endpoint method
+      # Fetch all endpoints for the specified tenant.
+      # @note No specific `endpoint` method due to potential name conflicts with the base API method.
       # @see https://developer.sophos.com/docs/endpoint-v1/1/routes/endpoints/get
       Helper::def_api_call :endpoints, Helper::endpoint_url(:endpoints)
+
+      # Fetch the isolation status for a specific endpoint.
+      # @param endpoint_id [String] The ID of the endpoint.
+      # @return [Hash] Response with the isolation status of the endpoint.
+      # @see https://developer.sophos.com/docs/endpoint-v1/1/routes/endpoints/get
       def endpoint_isolation(endpoint_id)
         get Helper::endpoint_url("endpoints/#{endpoint_id}/isolation")
       end
+
+      # Fetch tamper protection settings for a specific endpoint.
+      # @param endpoint_id [String] The ID of the endpoint.
+      # @return [Hash] Response containing tamper protection details.
+      # @see https://developer.sophos.com/docs/endpoint-v1/1/routes/endpoints/get
       def endpoint_tamper_protection(endpoint_id)
         get Helper::endpoint_url("endpoints/#{endpoint_id}/tamper-protection")
       end
-
     end
   end
 end

data/lib/sophos/client/helper.rb

@@ -1,49 +1,86 @@
+# frozen_string_literal: true
+
 module Sophos
-  
-  # Generate generic api methods
+  # Generate generic API methods dynamically for various Sophos APIs.
   class Client
     module Helper
 
-      def self.sanitize method_name
-        method_name.to_s.gsub('_', '-')
+      # Convert method names to URL-safe format (e.g., 'user_groups' => 'user-groups')
+      # @param method_name [Symbol, String] Method name to be sanitized
+      # @return [String] Sanitized method name for use in URL paths
+      def self.sanitize(method_name)
+        method_name.to_s.tr('_', '-')
+      end
+
+      # Generate a URL path for the common API
+      # @param method [Symbol, String] Method name for the API endpoint
+      # @return [String] Full path for the common API endpoint
+      def self.common_url(method)
+        url('common', method)
+      end
+
+      # Generate a URL path for the endpoint API
+      def self.endpoint_url(method)
+        url('endpoint', method)
       end
 
-      def self.common_url(method) self.url('common', method); end
-      def self.endpoint_url(method) self.url('endpoint', method); end
-      def self.partner_url(method) self.url('partner', method); end
-      
-      def self.url(api,method)
+      # Generate a URL path for the partner API
+      def self.partner_url(method)
+        url('partner', method)
+      end
+
+      # Generic method to generate API URLs
+      # @param api [String] API type (e.g., 'common', 'endpoint', 'partner')
+      # @param method [Symbol, String] Endpoint method name
+      # @return [String] Full API URL path
+      def self.url(api, method)
         "/#{api}/v1/#{sanitize(method)}"
       end
 
-      # generate end point for 'endpoint' and 'endpoints'
+      # Dynamically define API methods for both singular and plural endpoints.
+      # It supports paginated or non-paginated responses.
+      #
+      # @param method [Symbol] Plural method name (e.g., `:alerts`)
+      # @param url [String] Endpoint URL path
+      # @param singular_method [Symbol, nil] Singular method name (e.g., `:alert`), optional
+      # @param paged [Boolean] If true, generate paginated API calls (default: true)
       def self.def_api_call(method, url, singular_method = nil, paged = true)
         if singular_method
-          self.send(:define_method, method) do |id = nil, params = {}|
-            if id
-              get("#{url}/#{id}", params)
-            else
-              get_paged(url, params)
-            end
-          end
-          # strip trailing 's'
-          self.send(:define_method, singular_method) do |id, params = {}|
-            get("#{url}/#{id}", params)
-          end
+          define_singular_and_plural_methods(method, url, singular_method)
         else
-          if paged
-            self.send(:define_method, method) do |params = {}|
-              get_paged(url, params)
-            end
-          else
-            self.send(:define_method, method) do |params = {}|
-              get(url, params)
-            end
-          end
+          paged ? define_paged_method(method, url) : define_plain_method(method, url)
         end
       end
 
+      private
+
+      # Define both singular and plural methods.
+      # Example: `alerts` (for paginated results) and `alert(id)` (for single alert).
+      def self.define_singular_and_plural_methods(method, url, singular_method)
+        # Define plural method: paginated call if no ID, otherwise fetch singular resource.
+        define_method(method) do |id = nil, params = {}|
+          id ? get("#{url}/#{id}", params) : get_paged(url, params)
+        end
+
+        # Define singular method explicitly for single resource retrieval.
+        define_method(singular_method) do |id, params = {}|
+          get("#{url}/#{id}", params)
+        end
+      end
+
+      # Define a paginated method for list-based API endpoints.
+      def self.define_paged_method(method, url)
+        define_method(method) do |params = {}|
+          get_paged(url, params)
+        end
+      end
+
+      # Define a simple, non-paginated API method.
+      def self.define_plain_method(method, url)
+        define_method(method) do |params = {}|
+          get(url, params)
+        end
+      end
     end
   end
-
 end

data/lib/sophos/client/partner.rb

@@ -1,44 +1,61 @@
+# frozen_string_literal: true
+
 module Sophos
   class Client
     require File.expand_path('helper', __dir__)
     include Sophos::Client::Helper
 
-    # Sophos partner api
+    # Sophos Partner API module, providing access to tenants, roles, admins, and billing usage data.
     # @see https://developer.sophos.com/docs/partner-v1/1/overview
     module Partner
-
+      # Retrieve a list of tenants or a single tenant by ID.
       # @see https://developer.sophos.com/docs/partner-v1/1/routes/tenants/get
       Helper::def_api_call :tenants, Helper::partner_url(:tenants), :tenant
 
+      # Retrieve a list of roles or a single role by ID.
       # @see https://developer.sophos.com/docs/partner-v1/1/routes/roles/get
       Helper::def_api_call :roles, Helper::partner_url(:roles), :role
 
+      # Retrieve a list of admins or a single admin by ID.
       # @see https://developer.sophos.com/docs/partner-v1/1/routes/admins/get
       Helper::def_api_call :admins, Helper::partner_url(:admins), :admin
 
-      # Get the list of role assignments for given admin.
+      # Retrieve the role assignments for a given admin.
+      # @param admin_id [String] Admin ID for whom role assignments are requested
+      # @param params [Hash] Optional query parameters
+      # @return [Hash] List of role assignments
       # @see https://developer.sophos.com/docs/partner-v1/1/routes/admins/%7BadminId%7D/role-assignments/get
       def admin_role_assignments(admin_id, params = {})
         get(Helper::partner_url("admins/#{admin_id}/role-assignments"), params)
       end
-      # Get the list of role assignments for given admin.
+
+      # Retrieve a specific role assignment for an admin by assignment ID.
+      # @param admin_id [String] Admin ID
+      # @param assignment_id [String] Role assignment ID
+      # @param params [Hash] Optional query parameters
+      # @return [Hash] Details of the specific role assignment
       # @see https://developer.sophos.com/docs/partner-v1/1/routes/admins/%7BadminId%7D/role-assignments/%7BassignmentId%7D/get
       def admin_role_assignment(admin_id, assignment_id, params = {})
         get(Helper::partner_url("admins/#{admin_id}/role-assignments/#{assignment_id}"), params)
       end
 
-
-      # List all the tenants for a partner
-      def permission_sets( params = {} )
+      # Retrieve the list of permission sets.
+      # @param params [Hash] Optional query parameters
+      # @return [Array<Hash>] List of permission sets
+      # @see https://developer.sophos.com/docs/partner-v1/1/routes/roles/permission-sets/get
+      def permission_sets(params = {})
         get(Helper::partner_url('roles/permission-sets'), params)
       end
 
-      # Usage report.
+      # Retrieve the billing usage report for a specific year and month.
+      # @param year [Integer] Year of the billing report (e.g., 2025)
+      # @param month [Integer] Month of the billing report (e.g., 1 for January)
+      # @param params [Hash] Optional query parameters
+      # @return [Hash] Billing usage data for the specified month
       # @see https://developer.sophos.com/docs/partner-v1/1/routes/billing/usage/%7Byear%7D/%7Bmonth%7D/get
       def billing_usage(year, month, params = {})
         get_paged(Helper::partner_url("billing/usage/#{year}/#{month}"), params)
       end
-
     end
   end
 end

data/lib/sophos/client.rb

@@ -1,42 +1,67 @@
-
+# frozen_string_literal: true
 
 module Sophos
-
-  # Wrapper for the Sophos Central REST API
+  # Wrapper for the Sophos Central REST API.
+  #
+  # This class acts as the main client for interacting with Sophos APIs and provides
+  # methods to create specific clients for tenants.
   #
-  # @note All methods have been separated into modules and follow the same grouping used in api docs
+  # @note All methods are separated into modules based on the Sophos API documentation structure.
   # @see https://developer.sophos.com/getting-started
   class Client < API
     require File.expand_path('client/partner', __dir__)
 
-    # get client to access api host for given tenant
-    # @return [TenantClient]
+    # Returns a tenant-specific client to access the API host for the given tenant.
+    #
+    # @param tenant [Hash] The tenant object containing API host and tenant ID.
+    # @return [TenantClient, nil] A configured tenant client, or nil if the tenant is not provided.
+    #
+    # @example Access tenant-specific APIs:
+    #   tenant_client = client(tenant)
+    #   tenant_client.some_tenant_specific_api_call
     def client(tenant)
       tenant_client(tenant.apiHost, tenant.id) if tenant
     end
 
-    # get teannt client to access api host for given tenant id
-    # @return [TenantClient]
-    def tenant_client( api_host, tenant_id )
-      # create client and copy access_token and set default headers
-      TenantClient.new(self.config.merge({
-        access_token: access_token,
-        endpoint: api_host,
-        tenant_id: tenant_id,
-        connection_options: { headers: { 'X-Tenant-ID': tenant_id } }
-      }))
+    # Returns a configured tenant client to access APIs for a specific tenant ID and API host.
+    #
+    # @param api_host [String] The API host for the tenant.
+    # @param tenant_id [String] The tenant's unique ID.
+    # @return [TenantClient] A client configured with the tenant's API endpoint and headers.
+    #
+    # @example Create a tenant client and access tenant data:
+    #   api_host = tenant.apiHost
+    #   tenant_id = tenant.id
+    #   tenant_client = tenant_client(api_host, tenant_id)
+    def tenant_client(api_host, tenant_id)
+      TenantClient.new(
+        self.config.merge(
+          {
+            access_token: access_token,
+            endpoint: api_host,
+            tenant_id: tenant_id,
+            connection_options: { headers: { 'X-Tenant-ID': tenant_id } }
+          }
+        )
+      )
     end
 
+    # Includes partner-related API methods.
     include Sophos::Client::Partner
   end
 
-  # Wrapper for the Sophos Central REST API for tenant related calls
+  # Wrapper for the Sophos Central REST API for tenant-related calls.
   #
-  # @note All methods have been separated into modules and follow the same grouping used in api docs
+  # This class inherits from `Sophos::Client` and includes additional modules
+  # for tenant-specific endpoints and common API methods.
+  #
+  # @note All tenant methods are separated into modules based on the Sophos API documentation.
   # @see https://developer.sophos.com/getting-started
   class TenantClient < Client
     require File.expand_path('client/common', __dir__)
     require File.expand_path('client/endpoint', __dir__)
+
+    # Includes modules for tenant-related and common API endpoints.
     include Sophos::Client::Common
     include Sophos::Client::Endpoint
   end

data/lib/sophos/configuration.rb

@@ -1,37 +1,46 @@
+# frozen_string_literal: true
+
 require 'wrapi'
 require File.expand_path('version', __dir__)
 require File.expand_path('pagination', __dir__)
 
 module Sophos
-  # Defines constants and methods related to configuration
+  # Configuration module for setting API-related options and defaults.
+  #
+  # This module extends `WrAPI::Configuration` and defines additional constants,
+  # default values, and methods to handle the configuration of the Sophos API wrapper.
   module Configuration
     include WrAPI::Configuration
 
-    # An array of additional valid keys in the options hash when configuring a [Sophos::API]
-    VALID_OPTIONS_KEYS = (WrAPI::Configuration::VALID_OPTIONS_KEYS + [:partner_id, :tenant_id, :id_endpoint]).freeze
+    # Additional valid configuration keys for [Sophos::API].
+    VALID_OPTIONS_KEYS = (WrAPI::Configuration::VALID_OPTIONS_KEYS + %i[
+      partner_id tenant_id id_endpoint
+    ])
 
-    # @private
-    attr_accessor *VALID_OPTIONS_KEYS
+    attr_accessor(*VALID_OPTIONS_KEYS)
 
-    DEFAULT_ENDPOINT = 'https://api.central.sophos.com'.freeze
-    DEFAULT_ID_ENDPOINT = 'https://id.sophos.com'.freeze
-    DEFAULT_UA = "Sophos Ruby API wrapper #{Sophos::VERSION}".freeze
+    # Default settings
+    DEFAULT_ENDPOINT = 'https://api.central.sophos.com'
+    DEFAULT_ID_ENDPOINT = 'https://id.sophos.com'
+    DEFAULT_USER_AGENT = "Sophos Ruby API wrapper #{Sophos::VERSION}"
     DEFAULT_PAGINATION = Sophos::RequestPagination::PagesPagination
     DEFAULT_PAGE_SIZE = 100
 
-    # When this module is extended, set all configuration options to their default values
+    # Initialize configuration defaults when this module is extended.
     def self.extended(base)
       base.reset
     end
 
-    # Create a hash of options and their values
+    # Returns the current configuration as a hash of key-value pairs.
+    #
+    # @return [Hash] Current configuration options.
     def options
-      VALID_OPTIONS_KEYS.inject({}) do |option, key|
-        option.merge!(key => send(key))
+      VALID_OPTIONS_KEYS.each_with_object({}) do |key, option|
+        option[key] = send(key)
       end
     end
 
-    # Reset all configuration options to defaults
+    # Resets all configuration options to their default values.
     def reset
       super
       self.partner_id = nil
@@ -39,10 +48,9 @@ module Sophos
 
       self.endpoint = DEFAULT_ENDPOINT
       self.id_endpoint = DEFAULT_ID_ENDPOINT
-      self.user_agent = DEFAULT_UA
+      self.user_agent = DEFAULT_USER_AGENT
       self.page_size = DEFAULT_PAGE_SIZE
       self.pagination_class = DEFAULT_PAGINATION
     end
   end
 end
-

data/lib/sophos/error.rb

@@ -1,11 +1,17 @@
+# frozen_string_literal: true
+
 module Sophos
-	
-  # Generic error to be able to rescue all Zabbix errors
+  # Base class for all custom errors in the Sophos module.
+  # Allows rescuing all Sophos-related exceptions with a single error class.
   class SophosError < StandardError; end
 
-  # Raised when Zabbix not configured correctly
+  # Raised when configuration is incomplete or invalid.
   class ConfigurationError < SophosError; end
 
-  # Error when authentication fails
+  # Raised when authentication to the Sophos API fails.
   class AuthenticationError < SophosError; end
-end
+
+  # Raised when API requests encounter general HTTP-related errors (optional future usage).
+  # Uncomment or extend if needed.
+  # class ApiError < SophosError; end
+end

data/lib/sophos/pagination.rb

@@ -1,63 +1,77 @@
+# frozen_string_literal: true
+
 require 'json'
 
 module Sophos
   # Defines HTTP request methods
   # required attributes format
   module RequestPagination
-
-    # Sophos uses different pagination for global api and tenant api
+    # Defines HTTP request pagination logic for Sophos APIs.
+    # Sophos supports different pagination approaches for the global API and tenant APIs.
     #
-    # response structure:
-    # { "pages": {
-    #     "current": 1, # page no - not laways present
-    #     "size": 50,
-    #     "total": 3,   # not always present - pages
-    #     "items": 123, # not always present - records
-    #     "maxSize": 100
+    # Expected response structure:
+    # {
+    #   "pages": {
+    #     "current": 1,   # Current page number (optional)
+    #     "size": 50,     # Items per page
+    #     "total": 3,     # Total pages (optional)
+    #     "items": 123,   # Total items (optional)
+    #     "maxSize": 100, # Maximum items per page allowed (optional)
+    #     "nextKey": "abc123" # Key for fetching the next page, used when available
     #   },
-    # "items": []
-    #
+    #   "items": []        # Array of data items for the current page
+    # }
     class PagesPagination
       attr_reader :current, :total, :page_size
 
       def initialize(page_size)
-        # ignore page size
         @page_size = page_size
-        @total = @current = 1
+        @total = 1       # Default total pages
+        @current = 1     # Start at the first page
+        @next_key = nil  # Key for fetching the next page if provided by the API
       end
 
+      # Returns options to be passed as query parameters for the next API request.
       def page_options
-        { 'page': @current, 'pageSize': @page_size, 'pageTotal': true }
+        options = { page: @current, pageSize: @page_size, pageTotal: true }
+        options[:pageFromKey] = @next_key if @current > 1 && @next_key # wellicht nil zetten zonder && @next_key?
+        options
       end
 
+      # Updates the pagination state based on the API response data.
       def next_page!(data)
-
         pages = page_info(data)
         if pages
-          @total = pages['total'].to_i
-          if pages['current']
-            @current = pages['current'].to_i + 1
-          else
-            @current += 1
-          end
+          set_page_state(pages)
         else
-          # no page info so assume single page request
+          # Assume a single-page request if no pagination info is available.
           @total = 0
         end
       end
 
-      def page_info(body) 
+      # Extracts the 'pages' metadata from the response body.
+      def page_info(body)
         body['pages']
       end
 
-      def self.data(body) 
-        body['items'] ? body['items'] : body
+      # Extracts the relevant data items from the API response.
+      def self.data(body)
+        body['items'] || body
       end
 
-      # only single page available
+      # Returns true if more pages are available.
       def more_pages?
         @current <= @total
       end
+
+      private
+
+      # Updates the current page, total pages, and next key (if present) from the pages metadata.
+      def set_page_state(pages)
+        @total = pages['total'].to_i if pages['total']
+        @current = pages['current'] ? pages['current'].to_i + 1 : @current + 1
+        @next_key = pages['nextKey'] if pages['nextKey']
+      end
     end
   end
 end

data/lib/sophos/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sophos
-  VERSION = '0.2.0'
+  VERSION = '0.2.2'
 end

data/lib/sophos_central_api.rb

@@ -1,13 +1,38 @@
-require "wrapi"
+# frozen_string_literal: true
+
+require 'wrapi'
 require File.expand_path('sophos/api', __dir__)
 require File.expand_path('sophos/client', __dir__)
 
+# Main module to interact with the Sophos API.
+# This module provides access to the Sophos client, which handles API calls and manages configurations.
+#
+# @example Initialize a Sophos client:
+#   client = Sophos.client(
+#     client_id: 'your_client_id',
+#     client_secret: 'your_client_secret'
+#   )
+#
 module Sophos
   extend Configuration
   extend WrAPI::RespondTo
 
+  # Initializes and returns a new instance of the Sophos client.
+  #
+  # @param options [Hash] A hash of options to configure the client.
+  #   Supported options include:
+  #   - `:client_id` [String] - Your Sophos API client ID.
+  #   - `:client_secret` [String] - Your Sophos API client secret.
+  #   - `:endpoint` [String] - The base URL for the API (default: Sophos Central endpoint).
+  #
+  # @return [Sophos::Client] An instance of the Sophos client with the provided configuration.
+  #
+  # @example Create a client with default settings:
+  #   Sophos.client
+  #
+  # @example Create a client with custom options:
+  #   Sophos.client(client_id: 'abc123', client_secret: 'xyz789')
   #
-  # @return [Sophos::Client]
   def self.client(options = {})
     Sophos::Client.new(options)
   end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sophos_central_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Janco Tanis
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-20 00:00:00.000000000 Z
+date: 2025-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -94,7 +93,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email: gems@jancology.com
 executables: []
 extensions: []
@@ -126,7 +124,6 @@ licenses:
 metadata:
   homepage_uri: https://rubygems.org/gems/sophos
   source_code_uri: https://github.com/jancotanis/sophos
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -141,8 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.12
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A Ruby wrapper for the Sophos Central REST APIs (readonly)
 test_files: []