skykick 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e219c7c7f5e5af499eb2dfa75b4f26ec1b44a0feec1f388debf960f7c623e91
-  data.tar.gz: 2cec92749ffd33a36a0ea36d583dd025f304c8672c5bf1469146986642bd72f2
+  metadata.gz: 7e19ac5551a5eed6f335941a38736d4db275db2f296ae65e922f986755f5ca26
+  data.tar.gz: 103c52067a848103220e77b575b1a9faeb33312331ab3f8529b0c084b43e1ff6
 SHA512:
-  metadata.gz: b152d1d931fd129b0c921c3d9634831c6037f0d5cca1eb10f9ea16daaae1d886c5234e8a736be2a1a13b76daa3eae0b196bc81eacdc45703d42f8595e35359b0
-  data.tar.gz: dda82313a9f6208348f1381ae01e08773591033cce4a90d2cc61d215bd8a189a9025d2bdf96aae5861b504c4de68432f230523c8309159b0c456fc643887e575
+  metadata.gz: 90814f525c34d0970de21e27dca62e190fc2402596ed71052224a024d3b4bc1b5eb4f502255be8d4f2231b11a06bc432b1e29240eb6b6c791c09f8904d93b247
+  data.tar.gz: d4e4f31bd103929aa777b8c6d70f3bae5753fd51eed364d61173f9fcee7875d4ee67df88980c024d68f00f7d4efef704a8458cf726738a9871eb24763c4182e8

data/CHANGELOG.md

@@ -1,13 +1,21 @@
-## [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

data/README.md

@@ -1,9 +1,11 @@
 # 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).
 
@@ -17,15 +19,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,19 +52,23 @@ 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.skykick.com/auth/token|
 
 ### Backup
-Endpoint for backup related requests 
+
+Endpoint for backup related requests
+
 ```ruby
 subscriptions = client.subscriptions
 ```
@@ -77,9 +88,10 @@ subscriptions = client.subscriptions
 |subscriptions                    |https://apis.skykick.com/Backup/                                     |
 |partner_subscriptions(partner_id)|https://apis.skykick.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 +104,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.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.2.2'
 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.skykick.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,13 @@
 --- !ruby/object:Gem::Specification
 name: skykick
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Janco Tanis
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-07 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: []
@@ -124,7 +122,6 @@ licenses:
 metadata:
   homepage_uri: https://rubygems.org/gems/skykick
   source_code_uri: https://github.com/jancotanis/skykick
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -139,8 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A Ruby wrapper for the Skykick backup Portal REST APIs (readonly)
 test_files: []