sophos_central_api 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d47cbadb0dff8019efbbac91b9690e5155653a24ae60eeb724fff45edaa90d87
-  data.tar.gz: a3a28af07f86c764b7fbfbcb03dcfaf47fce8ab23d30a8ddeea4d95407f8909f
+  metadata.gz: 7b18fa53d284ea012c44050984a138d3c8c4241b8dcce505b541a92c10951d1c
+  data.tar.gz: 940bcfba27107629b2788cd150aaa6f88687d095bd5653c0a415d47aa073085c
 SHA512:
-  metadata.gz: 1ddc293f17bf92585c4cd21517ca405ab985a7d848d73195b9a4e59649be8950ff773faeba68cc21d895e4e3885600c9add869710cfcd6a68f65472152c34e09
-  data.tar.gz: 40c45c25bd5d6b4d8261b0fa39313f081e81ce350a2818732071a11b9f4347ceb7b3bb42adab53d39513dfca23563d55d01423d263f65cdfeab4b943c9fb6e20
+  metadata.gz: 73aedd595b2ba56026dbe7a871764f2e2636fde292d2bf58b4e5ed07d131b722767e6f3a6587c6dbf0b70fd033441a7b41a27603e4fd253bedcd333ec9dae314
+  data.tar.gz: 2daf707681ea5acb32340c5cacac75d763096eca80d806c1b0d2f468324e6e32b2292353a9fd587b1fafa9cdc958196dc67c459e28643617f71120d997509f8d

data/CHANGELOG.md

@@ -24,3 +24,6 @@
 
 - Update docs, formatting
 
+## [0.2.3] - 2025-11-04
+
+- Sophos requires token type as 'Bearer' and does not support case insensitive token types.

data/README.md

@@ -66,7 +66,6 @@ client.login
 |:--|:--|:--|
 |.login|||
 
-
 ### Partner
 
 Endpoint for partner  related requests
@@ -82,8 +81,8 @@ 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
 
@@ -102,7 +101,7 @@ tenant = @client.tenant(id)
 |Resource|API endpoint|
 |:--|:--|
 |.alerts, .alert(id)                      |.../alerts/|
-|.directory_user_groups, .directory_user_groups(id)	|.../directory/user-groups|
+|.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|

data/lib/sophos/authentication.rb

@@ -12,7 +12,6 @@ module Sophos
   # @note Ensure that `client_id` and `client_secret` are configured before calling authentication methods.
   # @see https://developer.sophos.com/getting-started
   module Authentication
-
     # Authorizes with the Sophos portal and retrieves an access token.
     # This method performs an OAuth2 client credentials flow, returning a valid token.
     #
@@ -25,7 +24,7 @@ module Sophos
     #   api.auth_token
     #
     def auth_token(_options = {})
-      raise ConfigurationError.new 'Client id and/or secret not configured' unless client_id && client_secret
+      raise ConfigurationError, 'Client id and/or secret not configured' unless client_id && client_secret
 
       # POST request to obtain the OAuth2 token using client credentials
       response = connection.post("#{id_endpoint}/api/v2/oauth2/token") do |request|
@@ -39,7 +38,7 @@ module Sophos
       # Returns the generated access token
       self.access_token
     rescue Faraday::UnauthorizedError => e
-      raise AuthenticationError.new "Unauthorized; response #{e}"
+      raise AuthenticationError, "Unauthorized; response #{e}"
     end
     alias login auth_token
 
@@ -63,12 +62,12 @@ module Sophos
     # @raise [AuthenticationError] If `access_token` is missing or invalid.
     def api_process_token(response)
       self.access_token  = response['access_token']
-      self.token_type    = response['token_type']
+      self.token_type    = response['token_type'] unless self.token_type.downcase.eql? response['token_type']
       self.refresh_token = response['refresh_token']
       self.token_expires = response['expires_in']
 
       if self.access_token.nil? || self.access_token.empty?
-        raise AuthenticationError.new "Could not find valid access_token; response #{response}"
+        raise AuthenticationError, "Could not find valid access_token; response #{response}"
       end
     end
 
@@ -85,7 +84,7 @@ module Sophos
         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}"
+        raise AuthenticationError, "Partner id not returned; response #{partner}"
       end
     end
   end

data/lib/sophos/client/endpoint.rb

@@ -8,7 +8,6 @@ module Sophos
     # 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.

data/lib/sophos/client/helper.rb

@@ -1,49 +1,97 @@
 # frozen_string_literal: true
 
 module Sophos
-  # Generate generic API methods dynamically for various Sophos APIs.
+  # This module provides helper methods to dynamically define API calls for the Sophos Client.
+  # It supports paginated and non-paginated API methods, and allows generating
+  # URLs for different API types (`common`, `endpoint`, `partner`).
+  #
+  # == Example:
+  #
+  #   # Define paginated API methods for fetching alerts:
+  #   Helper::def_api_call(:alerts, Helper::common_url(:alerts), :alert)
+  #
+  #   # Generated methods:
+  #   client.alerts        # Fetches paginated alerts
+  #   client.alert(12345)  # Fetches a specific alert by ID (singular)
+  #
+  # @see https://developer.sophos.com/ Sophos API Documentation
   class Client
     module Helper
-
-      # 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
+      # Converts method names to a URL-safe format by replacing underscores with hyphens.
+      #
+      # @param method_name [Symbol, String] The method name to sanitize.
+      # @return [String] The sanitized method name (e.g., 'user_groups' => 'user-groups').
+      #
+      # == Example:
+      #   sanitize(:user_groups) # => "user-groups"
       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
+      # Generates a URL path for the common API.
+      #
+      # @param method [Symbol, String] The endpoint method name.
+      # @return [String] Full path for the common API (e.g., `/common/v1/alerts`).
+      #
+      # == Example:
+      #   common_url(:alerts) # => "/common/v1/alerts"
       def self.common_url(method)
         url('common', method)
       end
 
-      # Generate a URL path for the endpoint API
+      # Generates a URL path for the endpoint API.
+      #
+      # @param method [Symbol, String] The endpoint method name.
+      # @return [String] Full path for the endpoint API.
+      #
+      # == Example:
+      #   endpoint_url(:downloads) # => "/endpoint/v1/downloads"
       def self.endpoint_url(method)
         url('endpoint', method)
       end
 
-      # Generate a URL path for the partner API
+      # Generates a URL path for the partner API.
+      #
+      # @param method [Symbol, String] The endpoint method name.
+      # @return [String] Full path for the partner API.
+      #
+      # == Example:
+      #   partner_url(:tenants) # => "/partner/v1/tenants"
       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
+      # Constructs the full API URL path.
+      #
+      # @param api [String] API type (e.g., 'common', 'endpoint', 'partner').
+      # @param method [Symbol, String] The sanitized endpoint method name.
+      # @return [String] Full API URL path.
+      #
+      # == Example:
+      #   url('common', :alerts) # => "/common/v1/alerts"
       def self.url(api, method)
         "/#{api}/v1/#{sanitize(method)}"
       end
 
-      # Dynamically define API methods for both singular and plural endpoints.
-      # It supports paginated or non-paginated responses.
+      # Dynamically defines API methods for singular and plural endpoints.
+      #
+      # If `singular_method` is provided, it generates:
+      # - A plural method for fetching all resources (e.g., `alerts`).
+      # - A singular method for fetching a specific resource by ID (e.g., `alert(id)`).
+      #
+      # @param method [Symbol] The plural method name (e.g., `:alerts`).
+      # @param url [String] The API endpoint URL path.
+      # @param singular_method [Symbol, nil] The singular method name (optional).
+      # @param paged [Boolean] Whether the method should support pagination (default: true).
       #
-      # @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)
+      # == Example:
+      #   def_api_call(:alerts, "/common/v1/alerts", :alert)
+      #
+      #   # Generates:
+      #   # - alerts(params = {}) – Fetches paginated alerts.
+      #   # - alert(id, params = {}) – Fetches a specific alert by ID.
+      #
+      # @see define_singular_and_plural_methods, define_paged_method, define_plain_method
       def self.def_api_call(method, url, singular_method = nil, paged = true)
         if singular_method
           define_singular_and_plural_methods(method, url, singular_method)
@@ -52,10 +100,22 @@ module Sophos
         end
       end
 
-      private
-
-      # Define both singular and plural methods.
-      # Example: `alerts` (for paginated results) and `alert(id)` (for single alert).
+      # Defines both singular and plural methods for API endpoints.
+      #
+      # - The plural method fetches either paginated resources or a single resource if an ID is passed.
+      # - The singular method explicitly fetches a single resource by ID.
+      #
+      # @param method [Symbol] The plural method name (e.g., `:alerts`).
+      # @param url [String] The API endpoint URL path.
+      # @param singular_method [Symbol] The singular method name (e.g., `:alert`).
+      #
+      # == Example:
+      #   define_singular_and_plural_methods(:alerts, "/common/v1/alerts", :alert)
+      #
+      #   # Generates:
+      #   # - alerts(params = {}) – Fetches paginated alerts.
+      #   # - alerts(id, params = {}) – Fetches a single alert by ID.
+      #   # - alert(id, params = {}) – Fetches a single alert explicitly by ID.
       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 = {}|
@@ -68,14 +128,32 @@ module Sophos
         end
       end
 
-      # Define a paginated method for list-based API endpoints.
+      # Defines a paginated method for list-based API endpoints.
+      #
+      # @param method [Symbol] The method name (e.g., `:alerts`).
+      # @param url [String] The API endpoint URL path.
+      #
+      # == Example:
+      #   define_paged_method(:alerts, "/common/v1/alerts")
+      #
+      #   # Generates:
+      #   # - alerts(params = {}) – Fetches paginated alerts.
       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.
+      # Defines a simple, non-paginated API method.
+      #
+      # @param method [Symbol] The method name (e.g., `:roles`).
+      # @param url [String] The API endpoint URL path.
+      #
+      # == Example:
+      #   define_plain_method(:roles, "/partner/v1/roles")
+      #
+      #   # Generates:
+      #   # - roles(params = {}) – Fetches roles without pagination.
       def self.define_plain_method(method, url)
         define_method(method) do |params = {}|
           get(url, params)

data/lib/sophos/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sophos_central_api
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Janco Tanis
 bindir: exe
 cert_chain: []
-date: 2025-03-21 00:00:00.000000000 Z
+date: 2025-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday