isaca 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 62f3b9deda4ee74b614e8cd5d91110bb4eb0da73
-  data.tar.gz: a400dfad4b30039ac630c7318dce4b49aae298ac
+  metadata.gz: 268dab3df3c97c1c62f49e26c3e667429acb7017
+  data.tar.gz: 916311a0bc1f19b868bede5ea267f2310c9a412f
 SHA512:
-  metadata.gz: f70a43588de692625dd4ffcb898eb52dcc3a3c9d45057903b44ff2467e1e1414e97428b2773403913688e795f8ce1c9cba038f640f77faa84d8c5f275d5e49eb
-  data.tar.gz: 97e79e074276c450560219b636168878e063befbec908052f265327572586967b196d471abe33400889ea98328e9312be67bbc3e42ce31cce7b11d26bf9a5ace
+  metadata.gz: 4340024fce029cafe8593391db2be6eb65a8190f5d9de7a2e310dc55220dcc3c8c1873239629831ffb164d608640e51732d0f84c2a4bc6151dec4a997a218012
+  data.tar.gz: de6b0cde98d07991a7f8fce17706c04c1eafb48e161eead69f6449d408a8d77beab387ab39386fb493ec58fecee27e1eed3e36342b9dc879e70676a7e38fd0fc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    isaca (0.2.0)
+    isaca (1.0.1)
       faraday (~> 0.14.0)
 
 GEM

data/lib/isaca/configuration_error.rb

@@ -0,0 +1,4 @@
+module ISACA
+  class ConfigurationError < StandardError
+  end
+end

data/lib/isaca/helpers.rb

@@ -2,17 +2,37 @@ require 'date'
 require 'json'
 
 module ISACA
+  # A series of helper methods for parsing the way ISACA sends some data.
   module Helpers
+    # ISACA seems to use the default format to pass datetimes. This method exists so you don't have to remember
+    # the parse format.
+    #
+    # @param [String] string_time The time passed by ISACA.
+    # @param [String] format The format of the time.
+    #
+    # @return [DateTime]
     def self.strptime(string_time, format='%m/%d/%Y %I:%M:%S %p')
       (string_time.nil? || string_time.empty?) ? nil : DateTime.strptime(string_time, format)
     end
 
+    # ISACA passes booleans as a string representation, this method helps parse these representations.
+    #
+    # @param [String] string The string representation of a boolean. (e.g. "True", "false", "False"). If nil this method will return false.
+    #
+    # @returns [Boolean]
     def self.parse_boolean(string)
-      string == 'True' ? true : false
+      string.downcase == 'true' ? true : false
     end
 
+    # ISACA has an abbreviated member type and this method will break down those abbreviations into one of the three primary types: member, non_member or student.
+    #
+    # @param [String] type The abbreviated member type.
+    #
+    # @return [Symbol] :member, :non_member or :student.
     def self.normalize_member_type(type)
-      case type
+      return :non_member if type.nil?
+
+      case type.upcase
         when 'COMP' then :member
         when 'LIFE' then :member
         when 'STUM' then :student

data/lib/isaca/models/authenticate_user.rb

@@ -1,18 +1,21 @@
 module ISACA
   module Model
-    # Class that is used as an object representation of the response from {ISACA::Request::AuthenticateUser}
+    # Class that is used as an object representation of the response from {ISACA::Request::AuthenticateUser}.
     class AuthenticateUser
-      # The ISACA error -- ISACA documentation on this is currently limited.
       attr_reader :error
-      # The ISACA error code -- ISACA documentation on this is currently limited.
+      # @!attribute error
+      #   @return [Array] The ISACA error -- ISACA documentation on this is currently limited.
       attr_reader :error_code
-      # Whether or not the session is valid
+      # @!attribute error_code
+      #   @return [String] The ISACA error code -- ISACA documentation on this is currently limited.
       attr_reader :is_valid
-      # Session value or error message
+      # @!attribute is_valid
+      #   @return [Boolean]  Whether or not the session is valid.
       attr_reader :value
+      # @!attribute value
+      #   @return [String] Session value or error message.
 
-
-      # @param [Hash] params Parameters to create the object with
+      # @param [Hash] params Parameters to create the object with.
       # @option params [String] :Error Required
       # @option params [String] :ErrorCode Required
       # @option params [String] :IsValid Required

data/lib/isaca/models/countries.rb

@@ -1,12 +1,23 @@
 module ISACA
   module Model
+    # Class that is used as an object representation of the response from {ISACA::Request::Countries} and {ISACA::Request::ExplicitCountries}.
     class Countries
       attr_reader :countries
+      # @!attribute countries
+      #   @return [Array] A list of countries that ISACA recognizes.
 
+      # @param [Array<Hash>] countries Countries to create the object with.
+      # @option countries [String] :CODE Required
+      # @option countries [String] :DESCRIPTION Required
       def initialize(countries)
         @countries = countries.map { |c| Country.new(c[:CODE], c[:DESCRIPTION]) }
       end
 
+      # Method used to see if the a country exists. Searches across both country code and country description. Case insensitive.
+      #
+      # @param [String] value The value to be searched.
+      #
+      # @return [Boolean] Whether or not the country is included.
       def includes_country?(value)
         @countries.each { |country| return true if country_matches?(country, value) }
         false
@@ -14,12 +25,20 @@ module ISACA
 
       private
 
+      # Method used to see if country matches value. Checks across country code and country description. Case insensitive.
+      # Exists for the ease of testing.
+      #
+      # @param [Country] country The country to be searched.
+      # @param [String] value The value to search by.
+      #
+      # @return [Boolean] Whether or not the given country matches the value.
       def country_matches?(country, value)
         value.downcase!
         country.code.downcase == value || country.description.downcase == value
       end
     end
 
+    # Struct that represents an ISACA country data object
     Country = Struct.new(:code, :description)
   end
 end

data/lib/isaca/models/get_user_by_id.rb

@@ -1,23 +1,43 @@
 module ISACA
   module Model
+    # Class is used as an object representation of the response from {ISACA::Request::GetUserByID}.
     class GetUserByID
-      attr_accessor :active_member
-      attr_accessor :expiration_date
-      attr_accessor :member_type
-      attr_accessor :imis_id
+      attr_reader :active_member
+      # @!attribute active_member
+      #   @return [Boolean] Whether or not the membership is active.
 
-      def initialize(hash)
-        @active_member = ISACA::Helpers.parse_boolean(hash['ActiveMember'])
-        @expiration_date = ISACA::Helpers.strptime(hash['ExpirationDate'])
-        @member_type = ISACA::Helpers.normalize_member_type(hash['MemberType'])
+      attr_reader :expiration_date
+      # @!attribute expiration_date
+      #   @return [DateTime|nil] The date the membership expires. Never expires if nil.
 
-        if hash['iMISID'] == ""
-          @imis_id = nil
+      attr_reader :member_type
+      # @!attribute member_type
+      #   @return [Symbol] The membership's classification.
+
+      attr_reader :imis_id
+      # @!attribute imis_id
+      #   @return [String] The membership's unique ID
+
+      # @param [Hash] params The parameters used to create the object
+      # @option params [String] :ActiveMember
+      # @option params [String] :ExpirationDate
+      # @option params [String] :MemberType
+      # @option params [String] :iMISID
+      def initialize(params)
+        @active_member = ISACA::Helpers.parse_boolean(params[:ActiveMember])
+        @expiration_date = ISACA::Helpers.strptime(params[:ExpirationDate])
+        @member_type = ISACA::Helpers.normalize_member_type(params[:MemberType])
+
+        if params[:iMISID].to_s.strip.empty?
+          raise ServiceError.new('User with given IMIS ID not found')
         else
-          @imis_id = hash['iMISID']
+          @imis_id = params[:iMISID]
         end
       end
 
+      # A method that identifies whether or not the membership is active
+      #
+      # @return [Boolean] Whether or not the membership is active.
       def active_member?
         active_member
       end

data/lib/isaca/models/get_user_details_by_token.rb

@@ -1,39 +1,81 @@
 # An object representation of the GetUserDetailsByToken endpoint
 module ISACA
   module Model
+    # Class is used as an object representation of the response from {ISACA::Request::GetUserDetailsByToken}.
     class GetUserDetailsByToken
       attr_reader :imis_id
+      # @!attribute imis_id
+      #   @return [String] The IMIS ID of the requested user
+
       attr_reader :enterprise_id
+      # @!attribute enterprise_id
+      #   @return [String] The Enterprise ID of the requested user
+
       attr_reader :first_name
+      # @!attribute first_name
+      #   @return [String] The first name of the requested user
+
       attr_reader :last_name
+      # @!attribute last_name
+      #   @return [String] The last name of the requested user
+
       attr_reader :email
+      # @!attribute email
+      #   @return [String] The email of the requested user
+
       attr_reader :username
+      # @!attribute username
+      #   @return [String] The username of the requested user
+
       attr_reader :country
+      # @!attribute country
+      #   @return [String] The country of the requested user
+
       attr_reader :privacy
+      # @!attribute privacy
+      #   @return [Boolean|nil] The privacy acceptance status of the requested user
+
       attr_reader :marketing
+      # @!attribute marketing
+      #   @return [Boolean|nil] The marketing acceptance status of the requested user
 
-      def initialize(hash)
-        raise AttributeError.new(:ID, self.class.name, hash) unless hash.has_key?(:ID) && hash[:ID]
+      # @param [Hash] params The parameters used to create the object
+      # @option params [String] :ID Required
+      # @option params [String] :Ent_ID
+      # @option params [String] :First_Name
+      # @option params [String] :Last_Name
+      # @option params [String] :Email
+      # @option params [String] :UserName
+      # @option params [String] :Country
+      # @option params [String] :PRIVACY
+      # @option params [String] :MARKETING
+      #
+      # @raise [ISACA::ServiceError] Raises error if IMIS ID is not present.
+      def initialize(params)
+        if params[:ID].to_s.strip.empty?
+          raise ServiceError.new('User with given IMIS ID not found')
+        else
+          @imis_id = params[:ID]
+        end
 
-        @imis_id = hash[:ID]
-        @enterprise_id = hash[:Ent_ID]
-        @first_name = hash[:First_Name]
-        @last_name = hash[:Last_Name]
-        @email = hash[:Email]
-        @username = hash[:UserName]
-        @country = hash[:Country]
+        @enterprise_id = params[:Ent_ID]
+        @first_name = params[:First_Name]
+        @last_name = params[:Last_Name]
+        @email = params[:Email]
+        @username = params[:UserName]
+        @country = params[:Country]
 
-        if hash[:PRIVACY] == '1'
+        if params[:PRIVACY] == '1'
           @privacy = true
-        elsif hash[:PRIVACY] == '0'
+        elsif params[:PRIVACY] == '0'
           @privacy = false
         else
           @privacy = nil
         end
 
-        if hash[:MARKETING] == '1'
+        if params[:MARKETING] == '1'
           @marketing = true
-        elsif hash[:MARKETING] == '0'
+        elsif params[:MARKETING] == '0'
           @marketing = false
         else
           @marketing = nil

data/lib/isaca/requests/authenticate_user.rb

@@ -1,11 +1,12 @@
 module ISACA
   module Request
+    # Class used to create user sessions.
     class AuthenticateUser
       # Method used to generate a session token.
       #
-      # @raise [ISACA::SessionError] Raised if the returned session is invalid
+      # @raise [ISACA::SessionError] Raised if the returned session is invalid.
       #
-      # @return [ISACA::Model::AuthenticateUser] Returns an object representation of the response
+      # @return [ISACA::Model::AuthenticateUser] An object representation of the response.
       def self.get(username, password)
         response = self.send_request(username, password)
 
@@ -20,6 +21,8 @@ module ISACA
       #
       # @param username [String]
       # @param password [String]
+      #
+      # @return [Faraday::Response]
       def self.send_request(username, password)
         ISACA::Request.get do |request|
           request.path = request.path + '/AuthenticateUser'

data/lib/isaca/requests/countries.rb

@@ -1,7 +1,10 @@
 module ISACA
   module Request
+    # Class used to fetch countries recognized by ISACA.
     module Countries
-      # Method used to fetch all countries
+      # Method used to fetch all countries.
+      #
+      # @return [ISACA::Model::Countries] An object representation of the response.
       def self.get
         response = self.send_request
         ISACA::Model::Countries.new(JSON.parse(response.body, symbolize_names: true))
@@ -10,6 +13,8 @@ module ISACA
       private
 
       # Method used to send the request -- exists for easy testing purposes
+      #
+      # @return [Faraday::Response]
       def self.send_request
         ISACA::Request.get do |request|
           uri = URI(ISACA.configuration.url)

data/lib/isaca/requests/explicit_countries.rb

@@ -1,7 +1,11 @@
 module ISACA
   module Request
+    # Class used to fetch the explicit countries recognized by ISACA. Explicit countries are countries that require
+    # consent for marketing.
     module ExplicitCountries
-      # Method used to fetch all of the ExplicitCountries
+      # Method used to fetch all of the ExplicitCountries.
+      #
+      # @return [ISACA::Model::Countries] An object representation of the response.
       def self.get
         response = self.send_request
         ISACA::Model::Countries.new(JSON.parse(response.body, symbolize_names: true))
@@ -9,7 +13,9 @@ module ISACA
 
       private
 
-      # Method used to send the request -- exists for easy testing purposes
+      # Method used to send the request -- exists for easy testing purposes.
+      #
+      # @return [Faraday::Response]
       def self.send_request
         ISACA::Request.get do |request|
           uri = URI(ISACA.configuration.url)

data/lib/isaca/requests/get_user_by_id.rb

@@ -1,16 +1,29 @@
 module ISACA
   module Request
+    # Class used to fetch an ISACA user by their IMIS ID.
     module GetUserByID
+      # Method fetches ISACA user by IMIS ID.
+      #
+      # @param [String] id The IMIS ID of the requested user.
+      #
+      # @return [ISACA::Model::GetUserByID] An object representation of the response.
       def self.get(id)
-        response = ISACA::Request.get do |request|
+        response = self.send_request(id)
+        ISACA::Model::GetUserByID.new(JSON.parse(response.body, symbolize_names: true))
+      end
+
+      private
+
+      # Method used to send the request -- exists to ease testing.
+      #
+      # @param [String] id The IMIS ID of the requested user.
+      #
+      # @return [Faraday::Response]
+      def self.send_request(id)
+        ISACA::Request.get do |request|
           request.path = request.path + '/GetUserByID'
           request.params['ID'] = id
         end
-
-        data = JSON.parse(response.body)
-        ISACA.logger.debug(data) if ISACA.configuration.debug
-
-        response.status == 200 ? ISACA::Model::GetUserByID.new(data) : nil
       end
     end
   end

data/lib/isaca/requests/get_user_details_by_token.rb

@@ -3,9 +3,11 @@ module ISACA
     class GetUserDetailsByToken
       # Method used to get user information by token
       #
+      # @param token [String] The user's session token
+      #
       # @raise [ISACA::AttributeError] Raised if the returned IMIS ID is nil or the ID key is missing
       #
-      # @return [ISACA::Model::GetUserDetailsByToken] Returns an object representation of the response
+      # @return [ISACA::Model::GetUserDetailsByToken] An object representation of the response
       def self.get(token)
         response = self.send_request(token)
 
@@ -16,7 +18,9 @@ module ISACA
       private
       # Method used to send the request -- exists for easy stubbing during tests
       #
-      # @param token [String]
+      # @param token [String] The user's session token
+      #
+      # @return [Faraday::Response]
       def self.send_request(token)
         ISACA::Request.get do |request|
           request.path = request.path + '/GetUserDetailsByToken'

data/lib/isaca/version.rb

@@ -1,3 +1,3 @@
 module ISACA
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/lib/isaca.rb

@@ -22,6 +22,7 @@ require 'isaca/connection_error'
 require 'isaca/partner_key_error'
 require 'isaca/session_error'
 require 'isaca/attribute_error'
+require 'isaca/configuration_error'
 
 # Everything else where order load order does not matter
 require 'isaca/version'
@@ -29,15 +30,34 @@ require 'fileutils'
 require 'openssl'
 require 'logger'
 
+# Library intended to help ease the implementation of ISACA web services.
 module ISACA
   class << self
     attr_accessor :configuration
+    # @!attribute configuration
+    #   @return [ISACA::Configuration] Object used to configure the library.
+
     attr_accessor :logger
+    # @!attribute logger
+    #   @return [Logger]
 
+    # Method used to fetch the configuration object.
+    #
+    # @return [ISACA::Configuration]
     def configuration
       @configuration ||= Configuration.new
     end
 
+    # Method used to reset the ISACA configuration. Primarily used for testing.
+    #
+    # @return [ISACA::Configuration]
+    def reset
+      @configuration = Configuration.new
+    end
+
+    # Method used to get the logger.
+    #
+    # @return [Logger]
     def logger
       path = 'log/isaca.log'
       dir = File.dirname(path)
@@ -47,25 +67,59 @@ module ISACA
     end
   end
 
+  # Configuration block used to configure the library.
+  #
+  # @yield [ISACA::Configuration]
+  #
+  # @example An example configuration
+  #     ISACA.configure do |config|
+  #       config.url = 'https://partnerapi.isaca.org:8443/ISACAServices/Service1.svc'
+  #       config.secret_pass = '1234567890ABCDEFGHI'
+  #       config.user_agent = 'my_application'
+  #       config.verify_ssl = false
+  #     end
   def self.configure
     self.configuration ||= Configuration.new
     yield(configuration)
     self.configuration
   end
 
+  # Class used to store library configurations.
   class Configuration
     attr_accessor :url
+    # @!attribute url
+    #   @return [String] The root url for the ISACA web service.
+
     attr_accessor :secret_pass
+    # @!attribute secret_pass
+    #   @return [String] Your api key.
+
     attr_accessor :user_agent
+    # @!attribute user_agent
+    #   @return [String] The user agent that will be passed in the request headers.
+
     attr_accessor :verify_ssl
+    # @!attribute verify_ssl
+    #   @return [Boolean] Whether or not SSL certificates should be verified. Recommend true for production.
+
     attr_accessor :logger
+    # @!attribute logger
+    #   @return [Logger] The logger used for logging.
+
     attr_accessor :debug
+    # @!attribute debug
+    #   @return [Boolean] Whether or not logging should be used. Recommend false for production to ease GDPR concerns.
 
     def initialize
       @verify_ssl = true
       @debug = false
     end
 
+    # Returns the secret_pass attribute value
+    #
+    # @raise [ISACA::ConfigurationError] Raises if secret pass was not configured.
+    #
+    # @return [String]
     def secret_pass
       if @secret_pass
         @secret_pass
@@ -77,6 +131,11 @@ module ISACA
       end
     end
 
+    # Returns the url attribute value
+    #
+    # @raise [ISACA::ConfigurationError] Raises if url was not configured.
+    #
+    # @return [String]
     def url
       if @url
         @url
@@ -87,18 +146,21 @@ module ISACA
         raise ConfigurationError.new(msg)
       end
     end
-  end
 
-  def user_agent
-    if @user_agent
-      @user_agent
-    else
-      msg = 'Missing User-Agent configuration. The ISACA Partners API requires a predefined User-Agent.'
-      msg << ' Example: ISACA.configure {|config| config.user_agent = "MyApplication"}'
+    # Returns the user_agent attribute value
+    #
+    # @raise [ISACA::ConfigurationError] Raises if user agent was not configured.
+    #
+    # @return [String]
+    def user_agent
+      if @user_agent
+        @user_agent
+      else
+        msg = 'Missing User-Agent configuration. The ISACA Partners API requires a predefined User-Agent.'
+        msg << ' Example: ISACA.configure {|config| config.user_agent = "MyApplication"}'
 
-      raise ConfigurationError.new(msg)
+        raise ConfigurationError.new(msg)
+      end
     end
   end
-
-  class ConfigurationError < StandardError; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: isaca
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Matt Orahood
@@ -126,6 +126,7 @@ files:
 - isaca.gemspec
 - lib/isaca.rb
 - lib/isaca/attribute_error.rb
+- lib/isaca/configuration_error.rb
 - lib/isaca/connection_error.rb
 - lib/isaca/helpers.rb
 - lib/isaca/models/authenticate_user.rb