alpha_card 0.3.0 → 0.4.0

data/ROADMAP.md

@@ -1,12 +1,16 @@
 # TODO
 
-* Own `Attribute` class with validations and etc:
-    - default value
-    - writable: `true` / `false`
-    - presence: `true` / `false`
-    - values: `['1', '2']`
-    - coerce ?
-* Configuration with `Account` setup
-    - all objects can use global or local account
+## 0.4.0
+
+* ~~Own `Attribute` class with validations and etc~~:
+    - ~~default value~~
+    - ~~writable: true` / `false`~~
+    - ~~required: `true / `false~~
+    - ~~format: regex~~
+    - ~~values: ['1', '2']`~~
+    - ~~type(s)~~
+* ~~Configuration with `Account` setup~~
+    - ~~all objects can use global or local account~~
 * Add new transactions:
-    - Authorization/Credit/Validate/Offline
+    - ~~Authorization~~/~~Credit~~/~~Validate~~/Offline
+* ~~Change all resources return value to AlphaCard::Response~~

data/alpha_card.gemspec

@@ -5,7 +5,7 @@ require 'alpha_card/version'
 Gem::Specification.new do |gem|
   gem.name = 'alpha_card'
   gem.version = AlphaCard.gem_version
-  gem.date = '2016-09-22'
+  gem.date = '2016-10-07'
   gem.summary = 'Alpha Card Services API for Ruby'
   gem.description = 'Gem for creating sales with Alpha Card Services'
   gem.authors = ['Nikita Bulaj']
@@ -14,10 +14,9 @@ Gem::Specification.new do |gem|
   gem.files = `git ls-files`.split($RS)
   gem.homepage = 'http://github.com/nbulaj/alpha_card'
   gem.license = 'MIT'
-  gem.required_ruby_version = '>= 2.0.0'
+  gem.required_ruby_version = '>= 2.2.2'
 
-  gem.add_runtime_dependency 'virtus', '~> 1.0', '>= 1.0.5'
-  gem.add_runtime_dependency 'rack', '~> 1.2', '>= 1.2'
+  gem.add_runtime_dependency 'rack', '~> 2.0', '>= 2.0'
 
   gem.add_development_dependency 'rspec', '~> 3.5'
 end

data/lib/alpha_card.rb

@@ -1,6 +1,5 @@
 # encoding:utf-8
 require 'yaml'
-require 'virtus'
 require 'net/http'
 require 'uri'
 require 'rack/utils'
@@ -8,24 +7,33 @@ require 'rack/utils'
 # Version
 require 'alpha_card/version'
 
-require 'alpha_card/alpha_card_object'
-require 'alpha_card/alpha_card_response'
+require 'alpha_card/account'
+require 'alpha_card/attribute'
+require 'alpha_card/resource'
+require 'alpha_card/response'
+require 'alpha_card/transaction'
 
 # Errors
-require 'alpha_card/errors/alpha_card_error'
 require 'alpha_card/errors/api_connection_error'
-require 'alpha_card/errors/invalid_object_error'
+require 'alpha_card/errors/invalid_attribute_value'
+require 'alpha_card/errors/invalid_attribute_format'
+require 'alpha_card/errors/invalid_attribute_type'
+require 'alpha_card/errors/validation_error'
 
 # Alpha Card Resources
-require 'alpha_card/objects/account'
-require 'alpha_card/objects/billing'
-require 'alpha_card/objects/capture'
-require 'alpha_card/objects/shipping'
-require 'alpha_card/objects/order'
-require 'alpha_card/objects/void'
-require 'alpha_card/objects/refund'
-require 'alpha_card/objects/sale'
-require 'alpha_card/objects/update'
+require 'alpha_card/resources/billing'
+require 'alpha_card/resources/shipping'
+require 'alpha_card/resources/order'
+
+# Alpha Card Transactions
+require 'alpha_card/transactions/capture'
+require 'alpha_card/transactions/void'
+require 'alpha_card/transactions/refund'
+require 'alpha_card/transactions/sale'
+require 'alpha_card/transactions/update'
+require 'alpha_card/transactions/auth'
+require 'alpha_card/transactions/credit'
+require 'alpha_card/transactions/validate'
 
 ##
 # AlphaCard is a library for processing payments with Alpha Card Services, Inc.
@@ -49,88 +57,55 @@ module AlphaCard
     # specified account. Request must contains params - Alpha Card
     # transaction variables.
     #
-    # @param [Hash] params
-    #   Alpha Card transaction variables.
-    # @param [AlphaCard::Account] account
-    #   An <code>AlphaCard::Account</code> credentials object.
+    # @param params [Hash]
+    #   hash with Alpha Card transaction variables and it's values
     #
-    # @return [AlphaCard::AlphaCardResponse]
+    # @param credentials [Hash]
+    #   Alpha Card merchant account credentials
+    #
+    # @return [AlphaCard::Response]
     #   Response from Alpha Card Gateway.
     #
-    # @raise [AlphaCard::AlphaCardError]
-    #   AlphaCardError Exception if request failed.
+    # @raise [APIConnectionError] HTTP request error
     #
     # @example
-    #   account = AlphaCard::Account.new('demo', 'password')
     #   response = AlphaCard.request(
-    #     account,
     #     {
     #       cexp: '0720',
     #       ccnumber: '4111111111111111',
     #       amount: '10.00'
+    #     },
+    #     {
+    #       username: 'demo',
+    #       password: 'password'
     #     }
     #   )
     #
-    #   #=> #<AlphaCard::AlphaCardResponse:0x1a0fda8 @data={"response"=>"1",
+    #   #=> #<AlphaCard::Response:0x1a0fda8 @data={"response"=>"1",
     #       "responsetext"=>"SUCCESS", "authcode"=>"123", "transactionid"=>"123",
     #       "avsresponse"=>"", "cvvresponse"=>"N", "orderid"=>"", "type"=>"",
     #       "response_code"=>"100"}>
     #
-    #   account = AlphaCard::Account.new('demo', 'password')
-    #   response = AlphaCard.request(
-    #     account,
-    #     {
-    #       cexp: '0720',
-    #       ccnumber: '123',
-    #       amount: '10.00'
-    #     }
-    #   )
-    #
-    #   #=> AlphaCard::AlphaCardError: AlphaCard::AlphaCardError
-    def request(account, params = {})
-      raise AlphaCardError, 'You must set credentials to create the sale!' unless account.filled?
+    def request(params = {}, credentials = Account.credentials)
+      raise ArgumentError, 'You must pass a Hash with Account credentials!' unless Account.valid_credentials?(credentials)
 
       begin
-        response = http_post_request(@api_base, params.merge(account.attributes))
+        response = http_post_request(@api_base, params.merge(credentials))
       rescue => e
         handle_connection_errors(e)
       end
 
-      alpha_card_response = AlphaCardResponse.new(response.body)
-      handle_alpha_card_errors(alpha_card_response)
-
-      alpha_card_response
-    end
-
-    ##
-    # Raises an exception if Alpha Card Gateway return an error or
-    # decline code for the request. Message is taken from the Global
-    # Payment Systems Credit Card Authorization Codes (codes.yml).
-    # If code wasn't found in <code>CREDIT_CARD_CODES</code>, then
-    # message = Alpha Card response text.
-    #
-    # @param [AlphaCard::AlphaCardResponse] response
-    #   Alpha Card Response object.
-    #
-    # @raise [AlphaCard::AlphaCardError]
-    #   AlphaCardError Exception if request failed.
-    #
-    # @return [String]
-    #   Alpha Card Services response text.
-    def handle_alpha_card_errors(response)
-      code = response.text
-      raise AlphaCardError.new(CREDIT_CARD_CODES[code] || code, response) unless response.success?
+      Response.new(response.body)
     end
 
     ##
     # Raises an exception if a network error occurs. It
     # could be request timeout, socket error or anything else.
     #
-    # @param [StandardError]
-    #   Exception object.
+    # @param error [Exception] exception object
     #
-    # @raise [AlphaCard::AlphaCardError]
-    #   AlphaCardError Exception.
+    # @raise [APIConnectionError]
+    #   Failed request exception.
     def handle_connection_errors(error)
       case error
       when Timeout::Error, Errno::EINVAL, Errno::ECONNRESET
@@ -150,13 +125,10 @@ module AlphaCard
     end
 
     ##
-    # Send secure HTTP(S) request with params
-    # to requested URL.
+    # Send secure HTTP(S) request with params to requested URL.
     #
-    # @param [String] url
-    #   URL
-    # @param [Hash] params
-    #   Hash of params for the request
+    # @param url [String] URL
+    # @param params [Hash] hash of params for the request
     #
     # @return [HTTPResponse]
     #   Response of the request as HTTPResponse object

data/lib/alpha_card/account.rb

@@ -0,0 +1,51 @@
+module AlphaCard
+  # AlphaCard Account class for global credentials settings
+  class Account
+    class << self
+      # Global Alpha Card Merchant account credentials
+      #
+      # @return [String] username
+      # @return [String] password
+      #
+      # @example
+      #   AlphaCard::Account.username = 'demo'
+      #   AlphaCard::Account.password = 'password'
+      #
+      attr_accessor :username, :password
+
+      ##
+      # Setups demo Alpha Card credentials
+      def use_demo_credentials!
+        self.username = 'demo'
+        self.password = 'password'
+      end
+
+      ##
+      # Checks credentials not to be nil or empty string
+      #
+      # @param credentials [Hash] hash with :username and :password keys
+      #
+      # @return [Bool] true if credentials present, false in other cases
+      #
+      def valid_credentials?(credentials)
+        !credentials[:username].to_s.empty? && !credentials[:password].to_s.empty?
+      end
+
+      ##
+      # Returns hash with Alpha Card credentials
+      #
+      # @return [Hash] credentials
+      #
+      # @example
+      #   AlphaCard::Account.username = 'john.doe'
+      #   AlphaCard::Account.password = '123qwe!s'
+      #
+      #   AlphaCard::Account.credentials
+      #   #=> { username: "john.doe", password: "123qwe!s" }
+      #
+      def credentials
+        { username: username, password: password }
+      end
+    end
+  end
+end

data/lib/alpha_card/attribute.rb

@@ -0,0 +1,337 @@
+module AlphaCard
+  # Attribute DSL for Alpha Card transaction variables
+  module Attribute
+    # Extends base class with Attributes DSL.
+    #
+    # @param base [Class] baseclass
+    #
+    # @example
+    #   class User
+    #     include AlphaCard::Attribute
+    #   end
+    #
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.send(:include, InstanceMethods)
+    end
+
+    # Attributes class methods
+    #   * attribute
+    #   * remove_attribute
+    #   * attributes_set
+    #
+    module ClassMethods
+      # Defines Attributes Set for the class.
+      # Attributes set contains all the attributes names as key
+      # and it's options as the value.
+      #
+      # @return [Hash] attributes set with options
+      def attributes_set
+        @attributes_set ||= {}
+      end
+
+      # Adds attribute to the class.
+      # Defines reader and writer methods based on options hash.
+      # Adds attribute to the global Attributes Set.
+      #
+      # @param name [Symbol, String] attribute name
+      # @param options [Hash] attribute options
+      #
+      # @example
+      #   class User
+      #     include AlphaCard::Attribute
+      #
+      #     attribute :id, type: Integer, required: true, writable: false
+      #     attribute :email, required: true, format: /.+@.+/
+      #     attribute :name, type: String
+      #     attribute :role, default: 'admin', values: ['admin', 'regular']
+      #     attribute :status, types: [String, Symbol]
+      #
+      #     attribute :metadata, type: Hash
+      #     attribute :additional_info
+      #   end
+      #
+      def attribute(name, options = {})
+        define_reader(name)
+        define_writer(name, options) if options[:writable].nil? || options[:writable]
+
+        attributes_set[name.to_sym] = options
+      end
+
+      # Removes attribute from the class (reader, writer and entry in Attributes Set).
+      #
+      # @param name [String, Symbol] attribute name
+      #
+      # @example
+      #   class User
+      #     include AlphaCard::Attribute
+      #
+      #     attribute :email
+      #     attribute :name, default: 'John'
+      #   end
+      #
+      #   class Person < User
+      #     attribute :email
+      #     remove_attribute :name
+      #   end
+      #
+      def remove_attribute(name)
+        symbolized_name = name.to_sym
+
+        if attributes_set.keys.include?(symbolized_name)
+          undef_method(symbolized_name)
+          undef_method("#{name}=") if method_defined?("#{name}=")
+
+          attributes_set.delete(symbolized_name)
+        end
+      end
+
+      private
+
+      # Writes Attributes Set to the superclass on inheritance.
+      #
+      # @private
+      #
+      # @param subclass [Class] inherited class
+      #
+      def inherited(subclass)
+        subclass.instance_variable_set(:@attributes_set, attributes_set.dup)
+      end
+
+      # Creates a reader method for the attribute.
+      #
+      # @private
+      #
+      # @param name [String, Symbol] attribute name
+      #
+      def define_reader(name)
+        attr_reader name.to_sym
+      end
+
+      # Creates a writer method for the attribute with validation
+      # of setting value if options[:values] was passed.
+      #
+      # @private
+      #
+      # @raise [InvalidAttributeValue] when value is not included in the possible values list
+      # @raise [InvalidAttributeFormat] when value doesn't match the required format
+      # @raise [InvalidAttributeType] when value is not of valid type
+      #
+      # @param name [Symbol] attribute name
+      # @param options [Hash] attribute options
+      #
+      def define_writer(name, options = {})
+        values = extract_values_from(options)
+        format = extract_format_from(options)
+        types = extract_types_from(options)
+
+        define_method("#{name}=") do |value|
+          raise InvalidAttributeValue.new(value, values) if values && !values.include?(value)
+
+          raise InvalidAttributeFormat.new(value, format) if !format.nil? && value !~ format
+
+          raise InvalidAttributeType.new(value, types) if value && types && types.none? { |klass| value.is_a?(klass) }
+
+          instance_variable_set(:"@#{name}", value)
+        end
+      end
+
+      # Extract and validate possible attribute values from options hash.
+      #
+      # @private
+      #
+      # @param options [Hash] attribute options
+      #
+      # @return [Array] possible attribute values
+      #
+      def extract_values_from(options = {})
+        values = options[:values] || return
+        raise ArgumentError, ':values option must be an Array or respond to .to_a!' unless values.is_a?(Array) || values.respond_to?(:to_a)
+        raise ArgumentError, ":values option can't be empty!" if values.empty?
+
+        values.to_a
+      end
+
+      # Extract and validate attribute value format from options hash.
+      #
+      # @private
+      #
+      # @param options [Hash] attribute options
+      #
+      # @return [Regexp] attribute value format
+      #
+      def extract_format_from(options = {})
+        format = options[:format] || return
+        raise ArgumentError, ':format must be Regexp!' unless format.is_a?(Regexp)
+
+        format
+      end
+
+      # Extract and validate attribute type class from options hash.
+      #
+      # @private
+      #
+      # @param options [Hash] attribute options
+      #
+      # @return [Object] possible attribute type(s)
+      #
+      def extract_types_from(options = {})
+        types = Array(options[:type] || options[:types])
+        return if types.empty?
+
+        raise ArgumentError, 'attribute type must be a Class!' if types.any? { |type| !type.is_a?(Class) }
+
+        types
+      end
+    end
+
+    # Attributes class methods
+    #   * initialize
+    #   * attributes
+    #   * []
+    module InstanceMethods
+      # Constructor supports setting attributes when creating a new instance of the class.
+      # Sets default values for the attributes if they are present.
+      #
+      # @param attributes [Hash] attributes hash
+      #
+      # @example
+      #   class User
+      #     include AlphaCard::Attribute
+      #
+      #     attribute :email
+      #     attribute :name, default: 'John'
+      #   end
+      #
+      #   User.new(email: 'john.doe@gmail.com')
+      #   #=> #<User:0x29cca00 @email='john.doe@gmail.com', @name="John">
+      #
+      def initialize(attributes = {})
+        set_attributes_defaults!
+
+        attributes.each do |name, value|
+          set_attribute_safely(name, value)
+        end
+      end
+
+      # Returns class instance attributes.
+      #
+      # @return [Hash] attributes of the instance object
+      #
+      # @example
+      #   class User
+      #     include AlphaCard::Attribute
+      #
+      #     attribute :email
+      #     attribute :name, default: 'John'
+      #   end
+      #
+      #   User.new.attributes
+      #   #=> { email: nil, name: 'John' }
+      #
+      def attributes
+        self.class.attributes_set.each_with_object({}) do |(name, _), attributes|
+          attributes[name] = __send__(name)
+        end
+      end
+
+      # Returns attribute value by it's name.
+      #
+      # @param name [String, Symbol] attribute name
+      #
+      # @return [Object] attribute value
+      #
+      # @example
+      #   class User
+      #     include AlphaCard::Attribute
+      #
+      #     attribute :email
+      #   end
+      #
+      #   u = User.new(email: 'john@email.com')
+      #   u[:email]
+      #   #=> 'john@email.com'
+      #
+      def [](name)
+        __send__(name)
+      end
+
+      # Returns names of the attributes that was marked as :required.
+      #
+      # @return [Array] array of attributes names
+      #
+      # @example
+      #   class User
+      #     include AlphaCard::Attribute
+      #
+      #     attribute :id
+      #     attribute :email, required: true
+      #     attribute :name, required: true
+      #   end
+      #
+      #   u = User.new
+      #   u.required_attributes
+      #   #=> [:email, :name]
+      #
+      def required_attributes
+        self.class.attributes_set.select { |_, options| options[:required] }.keys
+      end
+
+      # Indicates if all the attributes with option required: true
+      # are filled with non-nil value.
+      #
+      # @return [Bool]
+      #
+      # @example
+      #   class User
+      #     include AlphaCard::Attribute
+      #
+      #     attribute :email, required: true
+      #     attribute :name
+      #   end
+      #
+      #   u = User.new
+      #   u.required_attributes?
+      #   #=> false
+      #
+      #   u.email = 'john.doe@gmail.com'
+      #   u.required_attributes?
+      #   #=> true
+      #
+      def required_attributes?
+        required_attributes.all? { |attr| !self[attr].nil? }
+      end
+
+      protected
+
+      # Set attribute value only if attribute writable
+      #
+      # @param name [String, Symbol] attribute name
+      # @param value [Object] attribute value
+      #
+      def set_attribute_safely(name, value)
+        __send__("#{name}=", value) if attribute_writable?(name)
+      end
+
+      # Checks if attribute is writable by it's options in the Attributes Set.
+      #
+      # @param name [String, Symbol] attribute name
+      #
+      # @return [Boolean]
+      #
+      def attribute_writable?(name)
+        attribute_options = self.class.attributes_set[name.to_sym]
+        return false if attribute_options.nil?
+
+        attribute_options[:writable].nil? || attribute_options[:writable]
+      end
+
+      # Sets default values for the attributes, based on Attributes Set.
+      def set_attributes_defaults!
+        self.class.attributes_set.each do |attr_name, options|
+          instance_variable_set(:"@#{attr_name}", options[:default])
+        end
+      end
+    end
+  end
+end