wrapi 0.4.5 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2879998432bd9b2be748b54c21024a68acf5cdba01ecc3040c9e9da45f02268
-  data.tar.gz: 63b482ee658b94a605f92faa52502efe1fa24bee5a918db27c773726f4a1e326
+  metadata.gz: 4a4047745b71ea54dac6be7283fa0353f1e421770edf0f9940224d80bd291194
+  data.tar.gz: 6c8a945ec9bf4dcccfb1484b216c41e4b4582ce7ffcbfde6e47917061aee67ee
 SHA512:
-  metadata.gz: 4913f5e123c1a2211e1c57b2b66e5712d1920ac667e38740d5047134fcc178aa82c1a509652da6f23ee16c54396025ed0959a4b95438d4026a2589b28de4d90e
-  data.tar.gz: 0772f0cdb948a5100df2f08a0fdaf356823f1fdfa0bb658817d3a3626540c54ec29cf92a9d1d4f83b2f957b990a73dce8c20bff8a537fd6e6c226aff7f956706
+  metadata.gz: 7c4c12660ce8746049602aed4fbe4126dd47d4e57fa4dd3092fe831093e9f15b97293d6d1baa9dddf1f7b943ad8022db12d5f2b0f56d7c8a676cb009e6cb6141
+  data.tar.gz: 37e5c8beebe96f750b16d076107b77e55e84d3aeec42eefad3897a539f870e4a45d7f1d8a1ac7fdd0621351e81da03a115206ec0329dc81e9bb2c3697e8a96d9

data/CHANGELOG.md

@@ -39,4 +39,10 @@
 - fix typo and implement clone for entities
 
 ## [0.4.5] - 2024-03-12
-- rafactorings code readability
+- refactorings code readability
+
+## [0.4.6] - 2024-06-17
+- fix issue with loading Entity from yaml
+
+## [0.4.7] - 2025-03-18
+- fix obsolete escape

data/lib/wrapi/api.rb

@@ -1,15 +1,43 @@
+# frozen_string_literal: true
+
 require File.expand_path('configuration', __dir__)
 require File.expand_path('connection', __dir__)
 require File.expand_path('request', __dir__)
 require File.expand_path('authentication', __dir__)
 
 module WrAPI
-  # @private
+  # The API class is responsible for managing the configuration and connections
+  # for the WrAPI library. It includes modules for handling connections, requests,
+  # and authentication.
+  #
+  # @attr_accessor [Hash] options Configuration options for the API instance.
+  #
+  # @example Creating a new API instance
+  #   api = WrAPI::API.new(api_key: 'your_api_key')
+  #
+  # @example Accessing the configuration
+  #   config = api.config
+  #   puts config[:api_key]
+  #
+  # @see WrAPI::Connection
+  # @see WrAPI::Request
+  # @see WrAPI::Authentication
   class API
-    # @private
     attr_accessor *WrAPI::Configuration::VALID_OPTIONS_KEYS
 
-    # Creates a new API and copies settings from singleton
+    # Initializes a new API object with the given options.
+    #
+    # @param options [Hash] A hash of options to configure the API object.
+    #   The options are merged with the default options from `WrAPI.options`.
+    #
+    # @option options [String] :api_key The API key for authentication.
+    # @option options [String] :api_secret The API secret for authentication.
+    # @option options [String] :endpoint The API endpoint URL.
+    # @option options [String] :user_agent The User-Agent header for HTTP requests.
+    # @option options [Integer] :timeout The timeout for HTTP requests.
+    # @option options [Integer] :open_timeout The open timeout for HTTP requests.
+    #
+    # @return [WrAPI::API] A new API object configured with the given options.
     def initialize(options = {})
       options = WrAPI.options.merge(options)
       WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
@@ -17,6 +45,11 @@ module WrAPI
       end
     end
 
+    # Returns a hash of configuration options and their values.
+    # Iterates over each valid configuration key defined in WrAPI::Configuration::VALID_OPTIONS_KEYS,
+    # and assigns the corresponding value by calling the method with the same name as the key.
+    #
+    # @return [Hash] A hash containing the configuration options and their values.
     def config
       conf = {}
       WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|

data/lib/wrapi/authentication.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module WrAPI
   # Deals with authentication flow and stores it within global configuration
   # following attributes should be available:
@@ -7,9 +9,13 @@ module WrAPI
   #  token_type
   #  refresh_token
   #  token_expires
-
   module Authentication
-    # Authorize to the portal and return access_token
+    # Authenticates the API request by merging the provided options with the API access token parameters,
+    # sending a POST request to the specified path, and processing the response to extract the access token.
+    #
+    # @param path [String] the API endpoint path to which the authentication request is sent.
+    # @param options [Hash] additional parameters to be merged with the API access token parameters.
+    # @return [String] the processed access token extracted from the response body.
     def api_auth(path, options = {})
       params = api_access_token_params.merge(options)
       response = post(path, params)
@@ -17,7 +23,11 @@ module WrAPI
       api_process_token(response.body)
     end
 
-    # Return an access token from authorization
+    # Refreshes the API token by making a POST request to the specified path with the given refresh token.
+    #
+    # @param path [String] the endpoint path to send the refresh request to.
+    # @param token [String] the refresh token to be used for obtaining a new access token.
+    # @return [String] the new access token obtained from the response.
     def api_refresh(path, token)
       params = { refreshToken: token }
 
@@ -26,8 +36,14 @@ module WrAPI
       api_process_token(response.body)
     end
 
-  private
+    private
 
+    # Returns a hash containing the API access token parameters.
+    # Override this when passing different parameters
+    #
+    # @return [Hash] a hash with the following keys:
+    #   - :username [String] the username for API authentication
+    #   - :password [String] the password for API authentication
     def api_access_token_params
       {
         username: username,
@@ -35,14 +51,24 @@ module WrAPI
       }
     end
 
+    # Processes the API response to extract and set the authentication tokens.
+    # Raises an ArgumentError if the response is nil.
+    # Override this when passing different parameters
+    #
+    # @param response [Hash] The response from the API containing authentication tokens.
+    # @return [String] The access token extracted from the response.
+    # @raise [ArgumentError] If the response is nil.
+    # @raise [StandardError] If the access token is not found or is empty.
     def api_process_token(response)
-      at = self.access_token = response['accessToken']
+      raise ArgumentError.new("Response cannot be nil") if response.nil?
+
+      token = self.access_token = response['accessToken']
       self.token_type        = response['tokenType']
       self.refresh_token     = response['refreshToken']
       self.token_expires     = response['expiresIn']
-      raise StandardError.new 'Could not find valid accessToken; response ' + response.to_s if at.nil? || at.empty?
+      raise StandardError.new("Could not find valid accessToken; response #{response}") if token.to_s.empty?
 
-      at
+      token
     end
   end
 end

data/lib/wrapi/configuration.rb

@@ -1,8 +1,40 @@
-#require_relative './pagination'
-#require_relative './version'
+# frozen_string_literal: true
 
+# 
+# This module defines constants and methods related to the configuration of the WrAPI.
+# It provides a set of default configuration options and allows these options to be overridden.
+# 
+# Constants:
+# - VALID_OPTIONS_KEYS: An array of valid keys in the options hash when configuring a WrAPI::API.
+# - DEFAULT_CONNECTION_OPTIONS: Default connection options (empty hash).
+# - DEFAULT_FORMAT: Default response format (:json).
+# - DEFAULT_PAGE_SIZE: Default page size for paged responses (500).
+# - DEFAULT_USER_AGENT: Default user agent string.
+# - DEFAULT_PAGINATION: Default pagination class.
+# 
+# Attributes:
+# - access_token: Access token for authentication.
+# - token_type: Type of the token.
+# - refresh_token: Token used to refresh the access token.
+# - token_expires: Expiration time of the token.
+# - client_id: Client ID for authentication.
+# - client_secret: Client secret for authentication.
+# - connection_options: Options for the connection.
+# - username: Username for authentication.
+# - password: Password for authentication.
+# - endpoint: API endpoint.
+# - logger: Logger instance.
+# - format: Response format.
+# - page_size: Page size for paged responses.
+# - user_agent: User agent string.
+# - pagination_class: Pagination class.
+#
+# Methods:
+# - self.extended(base): Sets all configuration options to their default values when the module is extended.
+# - configure: Allows configuration options to be set in a block.
+# - options: Creates a hash of options and their values.
+# - reset: Resets all configuration options to their default values.
 module WrAPI
-
   # Defines constants and methods related to configuration
   # If configuration is overridden, please add following methods
   # @see [self.extended(base)] to initialize the Configuration
@@ -30,7 +62,7 @@ module WrAPI
     ].freeze
 
     # By default, don't set any connection options
-    DEFAULT_CONNECTION_OPTIONS = {}
+    DEFAULT_CONNECTION_OPTIONS = {}.freeze
 
     # The response format appended to the path and sent in the 'Accept' header if none is set
     #
@@ -43,11 +75,12 @@ module WrAPI
     DEFAULT_PAGE_SIZE = 500
 
     # The user agent that will be sent to the API endpoint if none is set
-    DEFAULT_USER_AGENT = "Ruby API wrapper #{WrAPI::VERSION}".freeze
-    
+    DEFAULT_USER_AGENT = "Ruby API wrapper #{WrAPI::VERSION}"
+
+    # DEFAULT_PAGINATION is a constant that sets the default pagination strategy for WrAPI requests.
+    # It uses the DefaultPager class from the WrAPI::RequestPagination module.
     DEFAULT_PAGINATION = WrAPI::RequestPagination::DefaultPager
 
-    # @private
     attr_accessor *VALID_OPTIONS_KEYS
 
     # When this module is extended, set all configuration options to their default values

data/lib/wrapi/connection.rb

@@ -1,16 +1,38 @@
+# frozen_string_literal: true
+
 require 'faraday'
 
 module WrAPI
-  # Create connection including authorization parameters with default Accept format and User-Agent
+  # @private
+  # The Connection module provides methods to establish and configure a Faraday connection.
+  # It includes private methods to set up options, authorization, headers, and logging for the connection.
   # By default
   # - Bearer authorization is access_token is not nil override with @setup_authorization
   # - Headers setup for client-id and client-secret when client_id and client_secret are not nil @setup_headers
-  # @private
+  #
+  # Methods:
+  # - connection: Establishes a Faraday connection with the configured options, authorization, headers, and logging.
+  # - setup_options: Sets up the options for the Faraday connection, including headers and URL.
+  # - setup_authorization: Configures the authorization header for the Faraday connection.
+  # - setup_headers: Configures additional headers for the Faraday connection.
+  # - setup_logger_filtering: Sets up logging and filtering for sensitive information in the Faraday connection.
   module Connection
     private
 
+    # Establishes a Faraday connection with the specified options and configurations.
+    #
+    # @raise [ArgumentError] if the endpoint option is not defined.
+    # @return [Faraday::Connection] a configured Faraday connection.
+    #
+    # The connection is configured with the following:
+    # - Raises errors for HTTP responses.
+    # - Uses the default Faraday adapter.
+    # - Sets up authorization and headers.
+    # - Parses JSON responses.
+    # - Uses URL-encoded requests.
+    # - Optionally sets up logger filtering if a logger is provided.
     def connection
-      raise ArgumentError, "Option for endpoint is not defined" unless endpoint
+      raise ArgumentError, 'Option for endpoint is not defined' unless endpoint
 
       options = setup_options
       Faraday::Connection.new(options) do |connection|
@@ -25,8 +47,16 @@ module WrAPI
       end
     end
 
-    # callback method to setup api authorization
-    def setup_options()
+    # Sets up the options for the connection. acts as a callback method to
+    # setup api authorization
+    #
+    # @return [Hash] A hash containing the headers and URL for the connection,
+    #   merged with any additional connection options.
+    # @option options [Hash] :headers The headers for the connection, including:
+    #   - 'Accept' [String]: The content type to accept, based on the format.
+    #   - 'User-Agent' [String]: The user agent string.
+    # @option options [String] :url The endpoint URL for the connection.
+    def setup_options
       {
         headers: {
           'Accept': "application/#{format}; charset=utf-8",
@@ -36,26 +66,49 @@ module WrAPI
       }.merge(connection_options || {})
     end
 
-    # callback method to setup api authorization
+    # Sets up the authorization header for the given connection.
+    # override  to setup your own header for api authorization
+    #
+    # @param connection [Object] The connection object to which the authorization header will be added.
+    # @return [void]
+    # @note The authorization header will only be set if the access_token is present.
     def setup_authorization(connection)
       connection.headers['Authorization'] = "Bearer #{access_token}" if access_token
     end
 
-    # callback method to setup api headers
+    # Sets up the headers for the given connection. Override to set own headers.
+    #
+    # @param connection [Object] The connection object to set headers on.
+    # @option connection.headers [String] 'client-id' The client ID, if available.
+    # @option connection.headers [String] 'client-secret' The client secret, if available.
+    #
+    # @return [void]
     def setup_headers(connection)
       connection.headers['client-id'] = client_id if client_id
       connection.headers['client-secret'] = client_secret if client_secret
     end
 
-    # callback method to setup logger
+    # Sets up logger filtering for the given connection.
+    #
+    # This method configures the logger to filter sensitive information from the
+    # connection's response. It filters out passwords, access tokens, client secrets,
+    # and authorization headers from the logs.
+    #
+    # @param connection [Faraday::Connection] The connection object to configure the logger for.
+    # @param logger [Logger] The logger instance to use for logging the connection's responses.
+    #
+    # @example
+    #   setup_logger_filtering(connection, logger)
+    #
+    # @note This method assumes that the connection object is a Faraday connection.
     def setup_logger_filtering(connection, logger)
-      connection.response :logger, logger, { headers: true, bodies: true } do |l|
-        # filter json content
-        l.filter(/("password":")(.+?)(".*)/, '\1[REMOVED]\3')
-        l.filter(/("[Aa]ccess_?[Tt]oken":")(.+?)(".*)/, '\1[REMOVED]\3')
-        # filter header content
-        l.filter(/(client[-_]secret[:=].)([^&]+)/, '\1[REMOVED]')
-        l.filter(/(Authorization:.)([^&]+)/, '\1[REMOVED]')
+      connection.response :logger, logger, { headers: true, bodies: true } do |log|
+        # Filter sensitive information from JSON content, such as passwords and access tokens.
+        log.filter(/("password":")(.+?)(".*)/, '\1[REMOVED]\3')
+        log.filter(/("[Aa]ccess_?[Tt]oken":")(.+?)(".*)/, '\1[REMOVED]\3')
+        # filter sensitive header content such as client secrets and authorization headers
+        log.filter(/(client[-_]secret[:=].)([^&]+)/, '\1[REMOVED]')
+        log.filter(/(Authorization:.)([^&]+)/, '\1[REMOVED]')
       end
     end
   end

data/lib/wrapi/entity.rb

@@ -1,45 +1,80 @@
+# frozen_string_literal: true
+
 require 'json'
 
+# This module defines the WrAPI namespace which is used to encapsulate all the classes and modules
+# related to the WrAPI library. The WrAPI library provides functionality for interacting with APIs.
 module WrAPI
   # Defines HTTP request methods
   module Request
+    # Entity class to represent and manipulate API data
     class Entity
-      attr_reader :attributes
-
-      # factory method to create entity or array of entities
-      def self.create(attributes)
-        if attributes.is_a? Array
-          Entity.entify(attributes)
-        else
-          Entity.new(attributes) if attributes
+      # Factory method to create an entity or array of entities
+      #
+      # @param attr [Hash, Array<Hash>] the attributes to create the entity/entities from
+      # @return [Entity, Array<Entity>] the created entity or array of entities
+      def self.create(attr)
+        if attr.is_a? Array
+          Entity.entify(attr)
+        elsif attr
+          Entity.new(attr)
         end
       end
 
-      def initialize(attributes)
-        case attributes
+      # Initializes a new Entity
+      #
+      # @param attr [Hash] the attributes to initialize the entity with
+      def initialize(attr)
+        case attr
         when Hash
-          @attributes = attributes.clone.transform_keys(&:to_s)
+          @attributes = attr.clone.transform_keys(&:to_s)
         else
-          @attributes = attributes.clone
+          @attributes = attr.clone
         end
       end
 
+      # Returns the attributes of the entity
+      #
+      # @return [Hash] the attributes of the entity
+      def attributes
+        @attributes || {}
+      end
+
+      # Sets the attributes of the entity
+      #
+      # @param val [Hash] the new attributes of the entity
+      def attributes=(val)
+        @attributes = val || {}
+      end
+
+      # Handles dynamic method calls for attribute access and assignment
+      #
+      # @param method_sym [Symbol] the method name
+      # @param arguments [Array] the arguments passed to the method
+      # @param block [Proc] an optional block
       def method_missing(method_sym, *arguments, &block)
         # assignment
+        method = method_sym.to_s
         assignment = method_sym[/.*(?==\z)/m]
         if assignment
           raise ArgumentError, "wrong number of arguments (given #{arguments.length}, expected 1)", caller(1) unless arguments.length == 1
 
           @attributes[assignment] = arguments[0]
-        elsif @attributes.include? method_sym.to_s
-          accessor(method_sym.to_s)
+        elsif @attributes.include? method
+          accessor(method)
         else
           # delegate to hash
           @attributes.send(method_sym, *arguments, &block)
         end
       end
 
+      # Checks if the entity responds to a method
+      #
+      # @param method_sym [Symbol] the method name
+      # @param include_private [Boolean] whether to include private methods
+      # @return [Boolean] true if the entity responds to the method, false otherwise
       def respond_to?(method_sym, include_private = false)
+        @attributes ||= {}
         if @attributes.include? method_sym.to_s
           true
         else
@@ -47,36 +82,61 @@ module WrAPI
         end
       end
 
-      def to_json(options = {})
+      # Converts the entity to a JSON string
+      #
+      # @param options [Hash] options for JSON generation
+      # @return [String] the JSON representation of the entity
+      def to_json(_options = {})
         @attributes.to_json
       end
 
+      # Accesses an attribute, converting it to an Entity if it is a Hash or Array
+      #
+      # @param method [String] the attribute name
+      # @return [Object] the attribute value
       def accessor(method)
-          case @attributes[method]
-          when Hash
-            @attributes[method] = self.class.new(@attributes[method])
-          when Array
-            # make deep copy
-            @attributes[method] = Entity.entify(@attributes[method])
-          else
-            @attributes[method]
-          end
+        attribute = @attributes[method]
+        case attribute
+        when Hash
+          @attributes[method] = self.class.new(attribute)
+        when Array
+          # make deep copy
+          @attributes[method] = Entity.entify(attribute)
+        else
+          attribute
+        end
       end
-      
+
+      # Clones the entity
+      #
+      # @return [Entity] the cloned entity
       def clone
-        c = super
-        c.attributes = @attributes.clone
-        c
+        cln = super
+        cln.attributes = @attributes.clone
+        cln
+      end
+
+      # Checks if two entities are equal
+      #
+      # @param other [Entity] the other entity to compare with
+      # @return [Boolean] true if the entities are equal, false otherwise
+      def ==(other)
+        (self.class == other.class) && (self.attributes.eql? other.attributes)
       end
+      alias eql? ==
 
-      def self.entify(a)
-        if ( a.count > 0 ) && ( a.first.is_a? Hash )
-          a.dup.map do |item|
+      # Converts an array of hashes to an array of entities
+      #
+      # @param attribute [Array<Hash>] the array of hashes
+      # @return [Array<Entity>] the array of entities
+      def self.entify(attribute)
+        if attribute.any? && (attribute.first.is_a? Hash)
+          attribute.dup.map do |item|
             #item.is_a?(Hash) ? self.class.new(item) : item
             Entity.create(item)
           end
         else
-          a
+          attribute
         end
       end
     end

data/lib/wrapi/pagination.rb

@@ -1,39 +1,50 @@
+# frozen_string_literal: true
+
 require 'uri'
 require 'json'
 
 module WrAPI
-  # Defines HTTP request methods
-  # required attributes format
+  # Defines HTTP request methods and required attributes format for pagination.
   module RequestPagination
-
-    # Defaut pages asumes all data retrieved in a single go.
+    # DefaultPager handles pagination by assuming all data is retrieved in a single go.
     class DefaultPager
-
-      # initialize with page size
-      def initialize(page_size=nil)
+      # Initializes the pager with an optional page size.
+      #
+      # @param _page_size [Integer, nil] the size of the page (not used in this implementation)
+      def initialize(_page_size = nil)
         @page = 0
       end
 
-      # go to next page
-      # @return true if nore pages
-      def next_page!(data=nil)
+      # Advances to the next page.
+      #
+      # @param _data [Object, nil] the data from the current page (not used in this implementation)
+      # @return [Boolean] true if there are more pages, false otherwise
+      def next_page!(_data = nil)
         @page += 1
         more_pages?
       end
 
-      # assume single page
+      # Checks if there are more pages.
+      #
+      # @return [Boolean] true if there are more pages, false otherwise
       def more_pages?
         @page < 1
       end
 
+      # Returns options for the current page to add to get request.
+      #
+      # @return [Hash] an empty hash as options
       def page_options
         {}
       end
 
-      def self.data(body) 
+      # Processes the data from the response body.
+      #
+      # @param body [Object] the response body
+      # @return [Object] the processed data (in this case, the body itself)
+      def self.data(body)
         body
       end
     end
-
   end
 end

data/lib/wrapi/request.rb

@@ -1,14 +1,20 @@
+# frozen_string_literal: true
+
 require 'uri'
 require 'json'
 
 module WrAPI
   # Defines HTTP request methods
-  # required attributes format
   module Request
     CONTENT_TYPE_HDR = 'Content-Type'.freeze
-    # Perform an HTTP GET request and return entity incase format is :json
-    #  @return if format is :json and !raw an [Entity] is returned, otherwhise the response body
-    def get(path, options = {}, raw=false)
+
+    # Perform an HTTP GET request and return entity in case format is :json
+    #
+    # @param path [String] the request path
+    # @param options [Hash] the request options
+    # @param raw [Boolean] whether to return raw response
+    # @return [Entity, String] the response entity or raw response body
+    def get(path, options = {}, raw = false)
       response = request(:get, path, options) do |request|
         # inject headers...
         yield(request) if block_given?
@@ -16,35 +22,43 @@ module WrAPI
       entity_response(response, raw)
     end
 
-    # Perform an HTTP GET request for paged date sets response
-    #  @return nil if block given, otherwise complete concatenated json result set
+    # Perform an HTTP GET request for paged data sets response
+    #
+    # @param path [String] the request path
+    # @param options [Hash] the request options
+    # @param request_labda [Proc] an optional lambda to modify the request
+    # @return [Array<Entity>, nil] the concatenated result set or nil if block given
     def get_paged(path, options = {}, request_labda = nil)
-      raise ArgumentError,
-            "Pages requests should be json formatted (given format '#{format}')" unless is_json?
-
-      result = []
-      pager = create_pager
-      while pager.more_pages?
-        response = request(:get, path, options.merge(pager.page_options)) do |req|
-          # inject headers...
-          request_labda.call(req) if request_labda
-        end
-        if d = pager.class.data(response.body)
-          d = Entity.create(d)
-          if block_given?
-            yield(d)
-          else
-            result = add_data(result,d)
+      if is_json?
+        result = []
+        pager = create_pager
+        while pager.more_pages?
+          response = request(:get, path, options.merge(pager.page_options)) do |req|
+            # inject headers...
+            request_labda&.call(req)
+          end
+          handle_data(response.body, pager) do |d|
+            if block_given?
+              yield(d)
+            else
+              result = add_data(result, d)
+            end
           end
+          pager.next_page!(response.body)
         end
-        pager.next_page!(response.body)
+        result unless block_given?
+      else
+        raise ArgumentError, "Pages requests should be json formatted (given format '#{format}')"
       end
-      result unless block_given?
     end
 
     # Perform an HTTP POST request
-    # @return response is returned in json if format is :json
-    def post(path, options = {}, raw=true)
+    #
+    # @param path [String] the request path
+    # @param options [Hash] the request options
+    # @param raw [Boolean] whether to return raw response
+    # @return [Entity, String] the response entity or raw response body
+    def post(path, options = {}, raw = true)
       response = request(:post, path, options) do |request|
         yield(request) if block_given?
       end
@@ -52,8 +66,12 @@ module WrAPI
     end
 
     # Perform an HTTP PUT request
-    # @return response is returned in json if format is :json
-    def put(path, options = {}, raw=true)
+    #
+    # @param path [String] the request path
+    # @param options [Hash] the request options
+    # @param raw [Boolean] whether to return raw response
+    # @return [Entity, String] the response entity or raw response body
+    def put(path, options = {}, raw = true)
       response = request(:put, path, options) do |request|
         yield(request) if block_given?
       end
@@ -61,44 +79,66 @@ module WrAPI
     end
 
     # Perform an HTTP DELETE request
-    # @return response is returened
-    def delete(path, options = {}, raw=false)
+    #
+    # @param path [String] the request path
+    # @param options [Hash] the request options
+    # @param raw [Boolean] whether to return raw response
+    # @return [Entity, String] the response entity or raw response body
+    def delete(path, options = {}, raw = false)
       response = request(:delete, path, options) do |request|
         yield(request) if block_given?
       end
       entity_response(response, raw)
     end
 
+    # Checks if the response format is JSON
+    #
+    # @return [Boolean] true if the format is JSON, false otherwise
     def is_json?
       format && 'json'.eql?(format.to_s)
     end
 
-  private
+    private
 
+    # Creates a pager for paginated requests
+    #
+    # @return [Object] the pager instance
     def create_pager
       pagination_class ? pagination_class.new(page_size) : WrAPI::RequestPagination::DefaultPager
     end
 
     # Perform an HTTP request
+    #
+    # @param method [Symbol] the HTTP method
+    # @param path [String] the request path
+    # @param options [Hash] the request options
+    # @yieldparam request [Object] the request object
+    # @return [Object] the response object
     def request(method, path, options)
       response = connection.send(method) do |request|
-        yield(request) if block_given?
+        if block_given?
+          yield(request)
+        end
         request.headers[CONTENT_TYPE_HDR] = "application/#{format}" unless request.headers[CONTENT_TYPE_HDR]
-        uri = URI::Parser.new
-        _path = uri.parse(path)
-        _path.path = uri.escape(_path.path)
+
+        _path = escape_path(path)
         case method
         when :get, :delete
           request.url(_path.to_s, options)
         when :post, :put
           request.path = _path.to_s
-          set_body(request,options)
+          set_body(request, options)
         end
       end
       response
     end
 
-    def entity_response(response, raw=false)
+    # Processes the response and returns an entity if format is JSON
+    #
+    # @param response [Object] the response object
+    # @param raw [Boolean] whether to return raw response
+    # @return [Entity, Object] the response entity or raw response
+    def entity_response(response, raw = false)
       if is_json? && !raw
         Entity.create(pagination_class.data(response.body))
       else
@@ -106,8 +146,11 @@ module WrAPI
       end
     end
 
-    # set post body depending json content-type
-    def set_body(request,options)
+    # Sets the request body depending on the content type
+    #
+    # @param request [Object] the request object
+    # @param options [Hash] the request options
+    def set_body(request, options)
       if is_json? && !options.empty?
         request.body = options.to_json
       else
@@ -115,13 +158,40 @@ module WrAPI
       end
     end
 
-    # add data to array and check if data itself is an array
-    def add_data(result,data)
+    # Handles the data in the response body
+    #
+    # @param body [String] the response body
+    # @param pager [Object] the pager instance
+    # @yieldparam data [Object] the data in the response body
+    def handle_data(body, pager)
+      if d = pager.class.data(body)
+        d = Entity.create(d)
+        yield(d) if block_given?
+      end
+    end
+
+    # Adds data to the result array and checks if data itself is an array
+    #
+    # @param result [Array] the result array
+    # @param data [Object] the data to add
+    # @return [Array] the updated result array
+    def add_data(result, data)
       if data.is_a? Array
         result += data
       else
         result << data
       end
     end
+
+    # Escapes the request path
+    #
+    # @param path [String] the request path
+    # @return [URI::Generic] the escaped path
+    def escape_path(path)
+      uri = URI::Parser.new
+      _path = uri.parse(path)
+      _path.path = URI::RFC2396_PARSER.escape(_path.path)
+      _path
+    end
   end
 end

data/lib/wrapi/respond_to.rb

@@ -1,14 +1,24 @@
+# frozen_string_literal: true
 
 module WrAPI
+  # Module to delegate methods to the Client
   module RespondTo
-
-    # Delegate to Client
+    # Delegate method calls to the Client
+    #
+    # @param method [Symbol] the method name
+    # @param args [Array] the arguments passed to the method
+    # @param block [Proc] an optional block
     def self.method_missing(method, *args, &block)
       return super unless client.respond_to?(method)
+
       client.send(method, *args, &block)
     end
 
-    # Delegate to Client
+    # Checks if the Client responds to a method
+    #
+    # @param method [Symbol] the method name
+    # @param include_all [Boolean] whether to include private methods
+    # @return [Boolean] true if the Client responds to the method, false otherwise
     def self.respond_to?(method, include_all = false)
       client.respond_to?(method, include_all) || super
     end

data/lib/wrapi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WrAPI
-  VERSION = '0.4.5'
+  VERSION = '0.4.7'
 end

data/lib/wrapi.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require File.expand_path('wrapi/version', __dir__)
 require File.expand_path('wrapi/pagination', __dir__)
 require File.expand_path('wrapi/configuration', __dir__)
@@ -8,6 +10,13 @@ require File.expand_path('wrapi/request', __dir__)
 require File.expand_path('wrapi/respond_to', __dir__)
 require File.expand_path('wrapi/authentication', __dir__)
 
+# WrAPI module provides a structure for creating API wrappers.
+# It extends RespondTo and Configuration modules to include their functionalities.
+#
+# Methods:
+# - self.client(_options = {}): Abstract method that should be overridden in the including class.
+#   Raises NotImplementedError if not implemented.
+# - self.reset: Resets the configuration to defaults and sets the user agent string.
 module WrAPI
   extend RespondTo
   extend Configuration
@@ -15,13 +24,13 @@ module WrAPI
   # Abstract method should be overridden
   #
   # @return client
-  def self.client(options = {})
+  def self.client(_options = {})
     raise NotImplementedError, 'Abstract method self.client must implemented when including ResponTo'
   end
 
   # set/override defaults
   def self.reset
     super
-    self.user_agent = "Ruby API wrapper #{WrAPI::VERSION}".freeze
+    self.user_agent = "Ruby API wrapper #{WrAPI::VERSION}"
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: wrapi
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.7
 platform: ruby
 authors:
 - Janco Tanis
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-18 00:00:00.000000000 Z
+date: 2025-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -80,7 +79,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email: gems@jancology.com
 executables: []
 extensions: []
@@ -109,7 +107,6 @@ licenses:
 metadata:
   homepage_uri: https://rubygems.org/gems/wrapi
   source_code_uri: https://github.com/jancotanis/wrapi
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -124,8 +121,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 api wrapper code extracted from real world api clients
 test_files: []