skykick 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e219c7c7f5e5af499eb2dfa75b4f26ec1b44a0feec1f388debf960f7c623e91
-  data.tar.gz: 2cec92749ffd33a36a0ea36d583dd025f304c8672c5bf1469146986642bd72f2
+  metadata.gz: 2a6fddb22533868b7d481dab155eba199d22dc107614b504d7b30b2354a8f125
+  data.tar.gz: 4a91206b72d5ee286aa9bb974e4df2ef82631d26c4c9875c87da0308f82557fb
 SHA512:
-  metadata.gz: b152d1d931fd129b0c921c3d9634831c6037f0d5cca1eb10f9ea16daaae1d886c5234e8a736be2a1a13b76daa3eae0b196bc81eacdc45703d42f8595e35359b0
-  data.tar.gz: dda82313a9f6208348f1381ae01e08773591033cce4a90d2cc61d215bd8a189a9025d2bdf96aae5861b504c4de68432f230523c8309159b0c456fc643887e575
+  metadata.gz: b533bf98a520ca3aff074af183b8889807da2960a319dd4c5cf007491d4f49da0c15190671aeb11ccfc1c55842078453e0498f1d87271c8c28b81ea2cecca5d6
+  data.tar.gz: a1ba2fb65958104c88f603c893695b5d1f0c62081b578ec3a372c0e63da5f20db06b33fd29356c2025ad22e19a0d0f06679f040bc01a09191333ea69876e90f8

data/CHANGELOG.md

@@ -1,13 +1,25 @@
-## [Unreleased]
+# Changelog
 
 ## [0.1.0] - 2024-02-05
+
 - Initial release
 
 ## [0.1.1] - 2024-02-08
+
 - Update OData support
 
 ## [0.2.0] - 2024-02-20
+
 - Exception handling harmonized
 
 ## [0.2.1] - 2024-03-06
+
 - Upgrade faraday 2
+
+## [0.2.2] - 2025-03-21
+
+- updated documentation, filter subscription key from logs
+
+## [0.3.0] - 2025-09-01
+
+- updated api endpoint to https://apis.cloudservices.connectwise.com

data/README.md

@@ -1,11 +1,14 @@
 # Skykick Office365 backup API
+
 [![Version](https://img.shields.io/gem/v/skykick.svg)](https://rubygems.org/gems/skykick)
 [![Maintainability](https://api.codeclimate.com/v1/badges/a340908aaf944745eeda/maintainability)](https://codeclimate.com/github/jancotanis/skykick/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/a340908aaf944745eeda/test_coverage)](https://codeclimate.com/github/jancotanis/skykick/test_coverage)
 
-This is a wrapper for the Skykick Office365 backup API. You can see the API endpoints here https://developers.skykick.com/apis
+This is a wrapper for the Skykick Office365 backup API.
+You can see the [API endpoints](https://developers.skykick.com/apis)
 
-Currently only the GET requests to endpoints /Backup and /Alerts are implemented (readonly).
+Currently only the GET requests to endpoints /Backup and /Alerts
+are implemented (readonly).
 
 ## Installation
 
@@ -17,15 +20,20 @@ gem 'skykick'
 
 And then execute:
 
-    $ bundle install
+```console
+> bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install skykick
+```console
+> gem install skykick
+```
 
 ## 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 'skykick'
@@ -45,41 +53,46 @@ end
 ```
 
 ## Resources
+
 ### Authentication
+
 ```ruby
 # setup configuration
 #
 client.login
 ```
-|Resource|API endpoint|Description|
-|:--|:--|:--|
-|.auth_token or .login|https://apis.skykick.com/auth/token|
 
+|Resource|API endpoint|
+|:--|:--|
+|.auth_token or .login|https://apis.cloudservices.connectwise.com/auth/token|
 
 ### Backup
-Endpoint for backup related requests 
+
+Endpoint for backup related requests
+
 ```ruby
 subscriptions = client.subscriptions
 ```
 
 |Resource|API endpoint|
 |:--|:--|
-|autodiscover                     |https://apis.skykick.com/Backup/{id}/autodiscover                    |
-|datacenters                      |https://apis.skykick.com/Backup/datacenters                          |
-|exchange_mailboxe                |https://apis.skykick.com/Backup/{id}/mailboxes/{mailboxId}           |
-|exchange_mailboxes               |https://apis.skykick.com/Backup/{id}/mailboxes                       |
-|lastsnapshotstats                |https://apis.skykick.com/Backup/{backupServiceId}/lastsnapshotstats  |
-|retention_periods                |https://apis.skykick.com/Backup/{id}/retentionperiod                 |
-|sharePoint_sites                 |https://apis.skykick.com/Backup/{id}/sites                           |
-|sku                              |https://apis.skykick.com/Backup/{id}/sku                             |
-|storage_settings                 |https://apis.skykick.com/Backup/{id}/storagesettings                 |
-|subscription_settings            |https://apis.skykick.com/Backup/{id}/subscriptionsettings            |
-|subscriptions                    |https://apis.skykick.com/Backup/                                     |
-|partner_subscriptions(partner_id)|https://apis.skykick.com/Backup/{partner_id}                         |
-
+|autodiscover          |https://apis.cloudservices.connectwise.com/Backup/{id}/autodiscover|
+|datacenters           |https://apis.cloudservices.connectwise.com/Backup/datacenters|
+|exchange_mailboxe     |https://apis.cloudservices.connectwise.com/Backup/{id}/mailboxes/{mailboxId}|
+|exchange_mailboxes    |https://apis.cloudservices.connectwise.com/Backup/{id}/mailboxes|
+|lastsnapshotstats     |https://apis.cloudservices.connectwise.com/Backup/{backupServiceId}/lastsnapshotstats|
+|retention_periods     |https://apis.cloudservices.connectwise.com/Backup/{id}/retentionperiod|
+|sharePoint_sites      |https://apis.cloudservices.connectwise.com/Backup/{id}/sites|
+|sku                   |https://apis.cloudservices.connectwise.com/Backup/{id}/sku|
+|storage_settings      |https://apis.cloudservices.connectwise.com/Backup/{id}/storagesettings|
+|subscription_settings |https://apis.cloudservices.connectwise.com/Backup/{id}/subscriptionsettings|
+|subscriptions         |https://apis.cloudservices.connectwise.com/Backup/|
+|partner_subscriptions(partner_id)|https://apis.cloudservices.connectwise.com/Backup/{partner_id}|
 
 ### Alerts
+
 Returns Alerts for a provided Email Migration Order ID or Backup service ID.
+
 ```ruby
 subscriptions = client.subscriptions
 alerts = client.alerts(subscriptions.first.id)
@@ -92,7 +105,7 @@ alerts = client.alerts(subscriptions.first.id)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jancotanis/skykick.
+Bug reports and pull requests are welcome on [GitHub](https://github.com/jancotanis/skykick).
 
 ## License
 

data/lib/skykick/api.rb

@@ -1,29 +1,55 @@
-require "wrapi"
+# frozen_string_literal: true
+
+require 'wrapi'
 require File.expand_path('connection', __dir__)
 require File.expand_path('authentication', __dir__)
 
 module Skykick
-  # @private
+  # The `Skykick::API` class manages the core configuration and settings for the API client.
+  # It allows customization of options like endpoint, user agent, and pagination handling.
+  # This class copies configuration settings from the Skykick singleton and provides methods to retrieve the client configuration.
   class API
-    # @private
-    attr_accessor *WrAPI::Configuration::VALID_OPTIONS_KEYS
+    # Dynamically create accessor methods for all valid configuration keys.
+    attr_accessor(*WrAPI::Configuration::VALID_OPTIONS_KEYS)
 
-    # Creates a new API and copies settings from singleton
+    # Initializes a new `Skykick::API` instance with the given options.
+    # The options are merged with the global Skykick settings to allow both global and per-instance customization.
+    #
+    # @param options [Hash] A hash of configuration options.
+    #   These options can override the global Skykick configuration.
+    #
+    # @example Create a new API instance with custom options:
+    #   api = Skykick::API.new(endpoint: "https://custom-api.endpoint.com", user_agent: "MyApp UA/1.0")
+    #
+    # @return [Skykick::API] A new instance of the Skykick API with the specified options.
     def initialize(options = {})
+      # Merge the provided options with the global Skykick configuration.
       options = Skykick.options.merge(options)
+
+      # Set each configuration key dynamically using the merged options.
       WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
         send("#{key}=", options[key])
       end
     end
 
+    # Retrieves the current API configuration as a hash.
+    #
+    # @return [Hash] A hash containing the current configuration settings.
+    #   The keys in the hash are the same as `VALID_OPTIONS_KEYS`.
+    #
+    # @example Retrieve the current API configuration:
+    #   api = Skykick::API.new
+    #   api.config  # => { :endpoint => "https://apis.skykick.com", :user_agent => "Skykick API/1.0", ... }
     def config
       conf = {}
+      # Iterate over each valid configuration key and retrieve its current value.
       WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
         conf[key] = send key
       end
       conf
     end
 
+    # Include core modules for API functionality, including HTTP connections, request handling, and authentication.
     include Connection
     include WrAPI::Request
     include WrAPI::Authentication

data/lib/skykick/authentication.rb

@@ -1,31 +1,51 @@
+# frozen_string_literal: true
+
 require File.expand_path('error', __dir__)
 require 'uri'
 
 module Skykick
-  # Deals with authentication flow and stores it within global configuration
+  # The `Skykick::Authentication` module handles the authentication flow for the Skykick API.
+  # It manages access tokens and stores them in the global configuration.
+  # This module provides methods to log in to the Skykick portal using client credentials.
+  #
+  # @see https://developers.skykick.com/Guides/Authentication
   module Authentication
-    # Authorize to the Skykick portal and return access_token
-    # @see https://developers.skykick.com/Guides/Authentication
-    def auth_token(options = {})
+    # Authenticates with the Skykick API and retrieves an access token.
+    #
+    # This method performs a client credentials flow to authenticate with the Skykick API.
+    # The access token is stored in the global configuration for subsequent API calls.
+    #
+    # @param _options [Hash] Options for the authentication request (currently unused).
+    # @return [String] The access token for authenticated API requests.
+    #
+    # @raise [ConfigurationError] If `client_id` or `client_secret` is not configured.
+    # @raise [AuthenticationError] If the authentication fails due to invalid credentials or other issues.
+    #
+    # @example Authenticate and retrieve an access token:
+    #   token = Skykick::Authentication.auth_token
+    def auth_token(_options = {})
       raise ConfigurationError.new 'Client id and/or secret not configured' unless client_id && client_secret
 
-      c = connection
-      c.request :authorization, :basic, client_id, client_secret
-      response = c.post('/auth/token') do |request|
+      con = connection
+      con.request :authorization, :basic, client_id, client_secret
+      response = con.post('/auth/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)
 
       self.access_token
     rescue Faraday::ForbiddenError => e
-      raise AuthenticationError.new 'Unauthorized; response ' + e.to_s
+      raise AuthenticationError.new "Unauthorized; response #{e}"
     end
     alias login auth_token
 
-  private
+    private
 
+    # Prepares the parameters required for the authentication request.
+    #
+    # @return [Hash] The parameters for the API access token request.
     def api_access_token_params
       {
         grant_type: 'client_credentials',
@@ -33,13 +53,22 @@ module Skykick
       }
     end
 
+    # Processes the response from the Skykick API and extracts authentication details.
+    #
+    # @param response [Hash] The parsed response body from the API.
+    #
+    # @return [void]
+    #
+    # @raise [AuthorizationError] If the response does not include a valid `access_token`.
     def api_process_token(response)
       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 AuthorizationError.new 'Could not find valid access_token; response ' + response.to_s if self.access_token.nil? || self.access_token.empty?
+      if self.access_token.nil? || self.access_token.empty?
+        raise AuthorizationError.new "Could not find valid access_token; response #{response}"
+      end
     end
   end
 end

data/lib/skykick/client/alerts.rb

@@ -1,19 +1,32 @@
+# frozen_string_literal: true
+
 module Skykick
   class Client
-
-    # All alert related api calls
-    # @see https://developers.skykick.com/
+    # Contains all alert-related API calls for managing alerts in Skykick.
+    # This module provides methods to retrieve alerts and mark them as complete.
+    #
+    # @see https://developers.skykick.com/ Skykick Developer Documentation
     module Alerts
-
-      # Returns first 500 Alerts for a provided Email Migration Order ID or Backup service ID.
+      # Retrieves the first 500 alerts for a given Email Migration Order ID or Backup Service ID.
+      # This method utilizes OData query parameters like `$top`, which defaults to 25 results
+      # and allows a maximum of 500 results per call.
+      #
+      # @note The `$top` query parameter is not explicitly implemented but can be configured on the endpoint.
+      # @param id [String] The unique identifier for an Email Migration Order or Backup Service.
+      # @return [Array<Hash>] A list of alerts associated with the specified ID.
+      # @example Retrieve alerts for a given order or service
+      #   client.alerts('12345')  # Returns up to 500 alerts
       def alerts(id)
-        # This endpoint supports the following OData query parameters: $top
-        # $top - default of 25 and max of 500 
-        # this is not implemented
+        # Retrieves paged results for alerts using the "Alerts" API endpoint.
         get_paged("Alerts/#{id}")
       end
 
-      # Mark an Alert as complete.
+      # Marks a specific alert as complete.
+      #
+      # @param id [String] The unique identifier for the alert to be marked as complete.
+      # @return [Hash] The response from the API after marking the alert as complete.
+      # @example Mark an alert as complete
+      #   client.mark_as_complete('alert123')  # Marks alert with ID 'alert123' as complete
       def mark_as_complete(id)
         post("Alerts/#{id}")
       end

data/lib/skykick/client/backup.rb

@@ -1,76 +1,123 @@
+# frozen_string_literal: true
+
 module Skykick
   class Client
-
-    # All backup related api calls
-    # @see https://developers.skykick.com/
+    # Contains all backup-related API calls for managing Skykick backup subscriptions and settings.
+    # This module provides methods to interact with backup services, including retrieving subscription
+    # settings, storage settings, and mailbox information.
+    #
+    # @see https://developers.skykick.com/ Skykick Developer Documentation
     module Backup
-
-      # Returns a list of supported Azure data centers.
+      # Retrieves a list of supported Azure data centers.
+      # @return [Array<Hash>] A list of Azure data centers supported by Skykick.
+      # @example Fetch available data centers
+      #   client.datacenters  # => Returns a list of supported data centers
       def datacenters
-          get('Backup/datacenters')
+        get('Backup/datacenters')
       end
 
-      # Gets a list of placed Backup subscription orders
-      def subscriptions()
-          get('Backup')
+      # Retrieves a list of placed Backup subscription orders.
+      # @return [Array<Hash>] A list of backup subscriptions.
+      # @example Get all backup subscriptions
+      #   client.subscriptions  # => Returns a list of placed backup subscription orders
+      def subscriptions
+        get('Backup')
       end
 
-      # Gets a list of placed Backup subscription orders
+      # Retrieves a list of backup subscription orders for a specific partner.
+      # @param partner_id [String] The unique identifier of the partner.
+      # @return [Array<Hash>] A list of partner-specific backup subscriptions.
+      # @example Get partner backup subscriptions
+      #   client.partner_subscriptions('partner123')  # => Returns subscriptions for the partner
       def partner_subscriptions(partner_id)
-          get("Backup/#{partner_id}")
+        get("Backup/#{partner_id}")
       end
 
-      # Returns Backup subscription settings. Settings include the enabled 
-      # state for Exchange and SharePoint Backups and total count of enabled
-      # Exchange mailboxes and SharePoint sites as well as the state of the subscription.
+      # Retrieves backup subscription settings, including the state of Exchange and SharePoint Backups,
+      # the number of enabled mailboxes and SharePoint sites, and the subscription state.
+      # @param id [String] The subscription ID.
+      # @return [Hash] Backup subscription settings.
+      # @example Fetch subscription settings
+      #   client.subscription_settings('sub123')  # => Returns backup subscription settings
       def subscription_settings(id)
-          get("Backup/#{id}/subscriptionsettings")
+        get("Backup/#{id}/subscriptionsettings")
       end
 
-      # Returns storage settings for a Backup subscription.
+      # Retrieves storage settings for a backup subscription.
+      # @param id [String] The subscription ID.
+      # @return [Hash] Storage settings for the specified subscription.
+      # @example Get storage settings
+      #   client.storage_settings('sub123')  # => Returns storage settings
       def storage_settings(id)
-          get("Backup/#{id}/storagesettings")
+        get("Backup/#{id}/storagesettings")
       end
 
-      # Gets SKU/promo details for a Backup service.
+      # Retrieves SKU or promotional details for a backup service.
+      # @param id [String] The subscription ID.
+      # @return [Hash] SKU or promotional details.
+      # @example Fetch SKU details
+      #   client.sku('sub123')  # => Returns SKU or promo details
       def sku(id)
-          get("Backup/#{id}/sku")
+        get("Backup/#{id}/sku")
       end
 
-      # Returns a list of SharePoint site URLs and statuses (enabled/disabled)
-      # for a Backup subscription.
+      # Retrieves a list of SharePoint site URLs and their statuses (enabled/disabled) for a backup subscription.
+      # @param id [String] The subscription ID.
+      # @return [Array<Hash>] A list of SharePoint site URLs and statuses.
+      # @example Get SharePoint sites
+      #   client.sharepoint_sites('sub123')  # => Returns a list of SharePoint sites and their statuses
       def sharepoint_sites(id)
-          get("Backup/#{id}/sites")
+        get("Backup/#{id}/sites")
       end
 
-      # Returns the data retention periods for a Backup subscription. There are different
-      # retention periods for Exchange and SharePoint Data.
+      # Retrieves the data retention periods for a backup subscription.
+      # Different retention periods apply for Exchange and SharePoint data.
       #
-      # Please Note: We are aware of the spelling error of the word "retention" in the response 
-      # field ExchangeRentionPeriodInDays. This is not a mistake in the documentation, but has 
-      # been left this way as not to disrupt any existing integrations with this endpoint.
+      # @note There is a known spelling issue in the response field: `ExchangeRentionPeriodInDays`.
+      #   This is intentional to avoid breaking existing integrations.
+      # @param id [String] The subscription ID.
+      # @return [Hash] Retention period details.
+      # @example Get retention periods
+      #   client.retentionperiod('sub123')  # => Returns retention periods for Exchange and SharePoint data
       def retentionperiod(id)
-          get("Backup/#{id}/retentionperiod")
+        get("Backup/#{id}/retentionperiod")
       end
 
-      # Gets stats for snapshots from SKDataWarehouse for all mailboxes of a given backupServiceId
+      # Retrieves snapshot statistics from SKDataWarehouse for all mailboxes in a given backup subscription.
+      # @param id [String] The subscription ID.
+      # @return [Hash] Snapshot statistics for the mailboxes.
+      # @example Fetch last snapshot stats
+      #   client.lastsnapshotstats('sub123')  # => Returns snapshot stats for the subscription's mailboxes
       def lastsnapshotstats(id)
-          get("Backup/#{id}/lastsnapshotstats")
+        get("Backup/#{id}/lastsnapshotstats")
       end
 
-      # Returns a list of Exchange mailboxes and statuses (enabled/disabled) for a Backup subscription.
+      # Retrieves a list of Exchange mailboxes and their statuses (enabled/disabled) for a backup subscription.
+      # @param id [String] The subscription ID.
+      # @return [Array<Hash>] A list of Exchange mailboxes and their statuses.
+      # @example Get Exchange mailboxes
+      #   client.exchange_mailboxes('sub123')  # => Returns a list of Exchange mailboxes and statuses
       def exchange_mailboxes(id)
-          get("Backup/#{id}/mailboxes")
+        get("Backup/#{id}/mailboxes")
       end
 
-      # Returns a list of Exchange mailboxes and statuses (enabled/disabled) for a Backup subscription.
+      # Retrieves details of a specific Exchange mailbox in a backup subscription.
+      # @param id [String] The subscription ID.
+      # @param mailbox_id [String] The unique identifier of the mailbox.
+      # @return [Hash] Details of the specified Exchange mailbox.
+      # @example Get details of a specific mailbox
+      #   client.exchange_mailbox('sub123', 'mailbox123')  # => Returns mailbox details
       def exchange_mailbox(id, mailbox_id)
-          get("Backup/#{id}/mailboxes/#{mailbox_id}")
+        get("Backup/#{id}/mailboxes/#{mailbox_id}")
       end
 
-      # Returns the Exchange and SharePoint auto-discover states (enabled/disabled) of a Backup subscription.
+      # Retrieves the auto-discover state (enabled/disabled) for Exchange and SharePoint backups in a subscription.
+      # @param id [String] The subscription ID.
+      # @return [Hash] Auto-discover states for Exchange and SharePoint.
+      # @example Check auto-discover state
+      #   client.autodiscover('sub123')  # => Returns the auto-discover state of the subscription
       def autodiscover(id)
-          get("Backup/#{id}/autodiscover")
+        get("Backup/#{id}/autodiscover")
       end
     end
   end

data/lib/skykick/client.rb

@@ -1,11 +1,20 @@
+# frozen_string_literal: true
+
 module Skykick
-  # Wrapper for the Skykick REST API
+  # The `Skykick::Client` class acts as a wrapper for the Skykick REST API.
+  # This class inherits from the `Skykick::API` class and includes modules that group
+  # the API methods according to the structure in the Skykick API documentation.
   #
-  # @note All methods have been separated into modules and follow the same grouping used in api docs
+  # @note All methods are grouped in separate modules for better organization and follow the structure provided in the official API documentation.
   # @see https://developers.skykick.com/Guides/Authentication
   class Client < API
+    # Dynamically require all files in the `client` directory.
+    # This will load additional API modules as separate files for better modularity and code organization.
     Dir[File.expand_path('client/*.rb', __dir__)].each { |f| require f }
 
+    # Include API client modules for specific Skykick API functionalities.
+    # These modules provide methods for interacting with specific parts of the Skykick API,
+    # such as managing backups and handling alerts.
     include Skykick::Client::Backup
     include Skykick::Client::Alerts
   end

data/lib/skykick/connection.rb

@@ -1,31 +1,44 @@
+# frozen_string_literal: true
+
 require 'faraday'
 
 module Skykick
-
-  # Create connection including authorization parameters with default Accept format and User-Agent
-  # By default
-  # - Bearer authorization is access_token is not nil override with @setup_authorization
-  # - Headers setup for Ocp-Apim-Subscription-Key when client_id and client_secret are not nil @setup_headers
-  # @private
+  # The `Skykick::Connection` module is responsible for establishing an API connection.
+  # It includes authorization and header setup and ensures that sensitive information
+  # (e.g., access tokens, client secrets, etc.) is filtered from logs for security purposes.
+  #
+  # @note This module is designed to extend and customize the `WrAPI::Connection` functionalities.
   module Connection
     include WrAPI::Connection
 
-    # callback method to setup api headers
+    # Sets up API headers for the Skykick connection.
+    # If `client_secret` is present, it adds the `Ocp-Apim-Subscription-Key` header.
+    #
+    # @param connection [Faraday::Connection] The connection object used to configure headers.
+    # @return [void]
     def setup_headers(connection)
       connection.headers['Ocp-Apim-Subscription-Key'] = client_secret if client_secret
     end
 
-    # callback method to setup logger
+    # Configures a logger with filters to redact sensitive data from logs.
+    # This method sets up a logger that captures and logs request headers and bodies while
+    # filtering sensitive information such as passwords, access tokens, and authorization headers.
+    #
+    # @param connection [Faraday::Connection] The connection object where the logger is applied.
+    # @param logger [Logger] The logger instance that records request and response information.
+    # @return [void]
     def setup_logger_filtering(connection, logger)
       connection.response :logger, logger, { headers: true, bodies: true } do |l|
-        # filter json content
+        # Filter sensitive data from JSON content
         l.filter(/("password":")(.+?)(".*)/, '\1[REMOVED]\3')
         l.filter(/("accessToken":")(.+?)(".*)/, '\1[REMOVED]\3')
-        # filter header content
+
+        # Filter sensitive data from request headers
         l.filter(/(client-secret:.)([^&]+)/, '\1[REMOVED]')
         l.filter(/(Authorization:.)([^&]+)/, '\1[REMOVED]')
-        # skykick
-        l.filter(/(Ocp-Apim-Subscription-Key: ")(.+?)(\")/, '\1[REMOVED]\3')
+
+        # Filter Skykick-specific sensitive header and token information
+        l.filter(/(Ocp-Apim-Subscription-Key: ")(.+?)(")/, '\1[REMOVED]\3')
         l.filter(/("access_token":")(.+?)(".*)/, '\1[REMOVED]\3')
       end
     end

data/lib/skykick/error.rb

@@ -1,11 +1,30 @@
+# frozen_string_literal: true
+
 module Skykick
-	
-  # Generic error to be able to rescue all Skykick errors
+  # Base error class for all exceptions raised by the Skykick API.
+  # This allows rescuing all Skykick-related errors in a single block if desired.
+  # Example:
+  #   begin
+  #     # Code that interacts with the Skykick API
+  #   rescue Skykick::SkykickError => e
+  #     puts "An error occurred: #{e.message}"
+  #   end
   class SkykickError < StandardError; end
 
-  # Error when configuration not sufficient
+  # Raised when the Skykick API configuration is incomplete or incorrect.
+  # This might occur if required configuration options such as `client_id`, `client_secret`,
+  # or `endpoint` are missing or improperly set.
+  #
+  # Example:
+  #   raise Skykick::ConfigurationError, "Client ID and secret must be configured"
   class ConfigurationError < SkykickError; end
 
-  # Error when authentication fails
+  # Raised when authentication to the Skykick API fails.
+  # This might be due to incorrect credentials, an expired token, or insufficient permissions.
+  #
+  # Example:
+  #   raise Skykick::AuthenticationError, "Invalid client credentials"
+  #
+  # @see https://developers.skykick.com/Guides/Authentication
   class AuthenticationError < SkykickError; end
-end
+end

data/lib/skykick/pagination.rb

@@ -1,43 +1,79 @@
+# frozen_string_literal: true
+
 require 'uri'
 require 'json'
 
 module Skykick
-  # Defines HTTP request methods
-  # required attributes format
+  # Defines HTTP request pagination methods for Skykick's API.
+  # This module handles the pagination strategy required when dealing with paginated
+  # API results. Skykick uses OData pagination, which supports parameters like `$top` but not `$skip`.
+  #
+  # Note: Using `$skip` in requests results in an error:
+  # "The query specified in the URI is not valid. Query option 'Skip' is not allowed.
+  # To allow it, set the 'AllowedQueryOptions' property on EnableQueryAttribute or QueryValidationSettings."
   module RequestPagination
-
-    # Skykick uses Odata pagination but unfortunately does not support skipping pages.
-    # Using skip responds with "The query specified in the URI is not valid. Query option 
-    # 'Skip' is not allowed. To allow it, set the 'AllowedQueryOptions' property on 
-    # EnableQueryAttribute or QueryValidationSettings."
+    # Handles OData pagination.
+    # This class maintains pagination state, including the offset, limit (page size), and total results.
+    # Since skipping pages isn't allowed by Skykick, the pagination assumes a simplified logic with a single page.
+    #
+    # @example Pagination Initialization
+    #   paginator = Skykick::RequestPagination::ODataPagination.new(100)
+    #   options = paginator.page_options
+    #
+    # @see https://docs.oasis-open.org/odata/odata/v4.0/os/abnf/odata-abnf-construction-rules.html OData Query Parameters
     class ODataPagination
       attr_reader :offset, :limit, :total
+
+      # Initializes the pagination object with the specified page size.
+      # Assumes that pagination starts at the first page (offset 0).
+      #
+      # @param page_size [Integer] Number of results per page
       def initialize(page_size)
         @offset = 0
         @limit = page_size
-        # we always have a first page
+        # Assume we have at least one page initially
         @total = @limit
       end
+
+      # Returns the pagination options to be sent as query parameters.
+      # Due to Skykick's limitation, only the `$top` parameter is included.
+      #
+      # @return [Hash<Symbol, Integer>] Query parameters for pagination
       def page_options
-        { '$top': @limit, '$skip': @offset }
         { '$top': @limit }
       end
+
+      # Updates the pagination state for the next page based on the current page's data.
+      # Skykick's API does not allow skipping, so the offset and total are adjusted
+      # based on the size of the current data.
+      #
+      # @param data [Array] The data array from the current page
       def next_page!(data)
-        # assume array
+        # Update the total number of results based on the size of the current data set.
         if data.count
           @total = data.count
         else
-          @total = 1 
+          @total = 1
         end
         @offset += @limit
       end
 
-      def self.data(body) 
+      # Processes the API response body and returns it unchanged.
+      # This method can be overridden to handle specific response parsing needs.
+      #
+      # @param body [Hash, Array, String] The response body from the API
+      # @return [Hash, Array, String] Processed data (unchanged)
+      def self.data(body)
         body
       end
-      # only single page available
+
+      # Checks if more pages are available.
+      # Since Skykick's API supports only a single page (no `$skip`), this method
+      # returns `true` only if the offset is at its initial value (indicating the first page).
+      #
+      # @return [Boolean] `true` if more pages are available, `false` otherwise
       def more_pages?
-        @offset == 0
+        @offset.zero?
       end
     end
   end

data/lib/skykick/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Skykick
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/skykick.rb

@@ -1,19 +1,41 @@
-require "wrapi"
+# frozen_string_literal: true
+
+require 'wrapi'
 require File.expand_path('skykick/api', __dir__)
 require File.expand_path('skykick/client', __dir__)
 require File.expand_path('skykick/pagination', __dir__)
 require File.expand_path('skykick/version', __dir__)
 
+# The `Skykick` module is a wrapper around Skykick's API.
+# It provides a client configuration, including default settings like endpoint URL, user agent,
+# and pagination handling. This module extends `WrAPI::Configuration` to provide configuration
+# options and `WrAPI::RespondTo` for dynamic response handling.
 module Skykick
   extend WrAPI::Configuration
   extend WrAPI::RespondTo
 
-  DEFAULT_ENDPOINT = 'https://apis.skykick.com'.freeze
-  DEFAULT_UA = "Skykick Ruby API wrapper #{Skykick::VERSION}".freeze
+  # Default API endpoint for the Skykick service.
+  DEFAULT_ENDPOINT = 'https://apis.cloudservices.connectwise.com'
+
+  # Default User-Agent header sent with API requests, including gem version information.
+  DEFAULT_UA = "Skykick Ruby API wrapper #{Skykick::VERSION}"
+
+  # Default pagination class used for handling paginated API responses.
   DEFAULT_PAGINATION = Skykick::RequestPagination::ODataPagination
 
+  # Creates and returns a new Skykick API client with the given options.
+  #
+  # @param options [Hash] A hash of configuration options to initialize the client.
+  #   This method merges the provided options with default values such as endpoint, user agent, and pagination class.
   #
-  # @return [Skykick::Client]
+  # @option options [String] :endpoint The base URL for the Skykick API (default: `DEFAULT_ENDPOINT`).
+  # @option options [String] :user_agent The User-Agent header to send with each API request (default: `DEFAULT_UA`).
+  # @option options [Class] :pagination_class The pagination class to handle paginated responses (default: `DEFAULT_PAGINATION`).
+  #
+  # @return [Skykick::Client] A new instance of the Skykick API client.
+  #
+  # @example Create a Skykick client:
+  #   client = Skykick.client(endpoint: "https://api.custom-endpoint.com", user_agent: "Custom UA/1.0")
   def self.client(options = {})
     Skykick::Client.new({
       endpoint: DEFAULT_ENDPOINT,
@@ -22,6 +44,15 @@ module Skykick
     }.merge(options))
   end
 
+  # Resets the Skykick configuration to default values.
+  #
+  # This method resets the configuration values to their defaults:
+  # - `DEFAULT_ENDPOINT` for the API endpoint
+  # - `DEFAULT_UA` for the User-Agent
+  # - `DEFAULT_PAGINATION` for the pagination handling class
+  #
+  # @example Reset the Skykick configuration:
+  #   Skykick.reset
   def self.reset
     super
     self.endpoint = DEFAULT_ENDPOINT

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skykick
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Janco Tanis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-07 00:00:00.000000000 Z
+date: 2025-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -139,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: A Ruby wrapper for the Skykick backup Portal REST APIs (readonly)