alpha_card 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f7e8e249cdf49bffd9bbda0825018bc6406e0c52
-  data.tar.gz: 6241892718864310e112ec3c39eb6cdc7efac26f
+  metadata.gz: 6af86a7de326ef53708c81f07ed025792c44841c
+  data.tar.gz: 5a670c2177f9b7ac326f34ea1c3e34decd5ea37c
 SHA512:
-  metadata.gz: d604d1ca794b016047390a7bd9915a54ae3ef4d4b25d4514808ac28f109a5f2aeb9e328793f58df4b706ddc7b3557800c15906df9893e6d23d68687a6beec605
-  data.tar.gz: 7a46b389c6aaeec686a189e5add88b864929ffe1be3169fa5f5e40c285da37efb5e593d8635367ce722329d12dc24d5781aa33970717ca6dc6d0c9c0dd35e65b
+  metadata.gz: ca0333c53125849ca415b73a10d9a4c659d54cff80879bc0f2aadd3aa502ffecc3af758ed87709ce83ba7016d57679b7a6f023f672952d7e9f3788fda29f7ad1
+  data.tar.gz: 0bea0ef881a98bd593a99a20883de46f2b94f1d6cf384caa39dbeaed8f95f53a99afa8855a22becba76f0e0f6b5ac90017263dda9d2473a4564e7938c525d7a9

data/Gemfile

@@ -4,5 +4,4 @@ gemspec
 
 gem 'virtus'
 gem 'rest_client'
-gem 'rack'
 gem 'coveralls', require: false

data/alpha_card.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |gem|
   gem.name = 'alpha_card'
-  gem.version = '0.1.6'
-  gem.date = '2014-06-26'
+  gem.version = '0.1.7'
+  gem.date = '2014-06-27'
   gem.summary = 'Alpha Card Services DirectPost API for Ruby'
   gem.description = 'Gem for creating sales with Alpha Card Services DirectPost API'
   gem.authors = ['Nikita Bulaj']

data/lib/alpha_card.rb

@@ -1,8 +1,9 @@
+# encoding:utf-8
 require 'yaml'
 require 'virtus'
-require 'rack'
 require 'rest_client'
 
+require 'alpha_card/utils'
 require 'alpha_card/object'
 require 'alpha_card/alpha_card_object'
 require 'alpha_card/alpha_card_response'
@@ -14,25 +15,55 @@ require 'alpha_card/billing'
 require 'alpha_card/order'
 require 'alpha_card/sale'
 
+##
+# AlphaCard is a library for processing payments with Alpha Card Services, Inc.
 module AlphaCard
-  # DirectPost API URL
+  ##
+  # Alpha Card Gateway DirectPost API URL
   @api_base = 'https://secure.alphacardgateway.com/api/transact.php'
 
+  ##
   # Global Payment Systems (NDC) Credit Card Authorization Codes
+  #
+  # @see http://floristwiki.ftdi.com/images/c/ce/Appendix_A_-_Credit_Card_Authorization_Codes.pdf Credit Card Authorization Codes
   CREDIT_CARD_CODES = YAML.load_file(File.expand_path('../alpha_card/data/codes.yml', __FILE__)) unless defined? CREDIT_CARD_CODES
 
   class << self
+	# @return [String] Alpha Card Gateway DirectPost API URL.
     attr_accessor :api_base
   end
 
-  # AlphaCard.request(params, account) -> AlphaCardResponse
+  ##
+  # Send the POST request to the AlphaCard Gateway from the
+  # specified account. Request must contains params - Alpha Card
+  # transcation variables.
+  #
+  # @param [Hash] params
+  #   Alpha Card transaction variables.
+  # @param [AlphaCard::Account] account
+  #   An <code>AlphaCard::Account</code> credentials object.
+  #
+  # @return [AlphaCard::AlphaCardResponse]
+  #   Response from Alpha Card Gateway.
   #
-  # Do the POST request to the AlphaCard Gateway with <i>params</i>
-  # from specified AlphaCard <i>account</i>.
+  # @raise [AlphaCard::AlphaCardError]
+  #   AlphaCardError Exception if request failed.
   #
-  #    account = AlphaCard::Account.new('user', 'pass')
-  #    params = {amount: '10.00'}
-  #    r = AlphaCard.request(params, account) #=> AlphaCardResponse
+  # @example
+  #   account = AlphaCard::Account.new('demo', 'password')
+  #   response = AlphaCard.request(
+  #     {
+  #       cexp: '0720',
+  #       ccnumber: '4111111111111111',
+  #       amount: '10.00'
+  #     },
+  #     account
+  #   )
+  #
+  #   #=> #<AlphaCard::AlphaCardResponse:0x1a0fda8 @data={"response"=>"1",
+  #       "responsetext"=>"SUCCESS", "authcode"=>"123", "transactionid"=>"123",
+  #       "avsresponse"=>"", "cvvresponse"=>"N", "orderid"=>"", "type"=>"",
+  #       "response_code"=>"100"}>
   def self.request(params = {}, account)
     unless account.filled?
       raise AlphaCardError.new('You must set credentials to create the sale!')
@@ -52,26 +83,35 @@ module AlphaCard
 
   private
 
-  # AlphaCard.handle_errors(response) -> Exception
-  # AlphaCard.handle_errors(response) -> nil
+  ##
+  # 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 an exception if AlphaCard Gateway return an error or decline
-  # the request.
+  # @raise [AlphaCard::AlphaCardError]
+  #   AlphaCardError Exception if request failed.
   #
-  #    response = AlphaCard.request(params, account)
-  #    handle_errors(response) #=> nil or Exception
+  # @return [String]
+  #   Alpha Card Services response text.
   def self.handle_alpha_card_errors(response)
     code = response.text
     raise AlphaCardError.new(CREDIT_CARD_CODES[code] || code) unless response.success?
   end
 
-  # AlphaCard.handle_connection_errors(exception) -> Exception
+  ##
+  # Raises an exception if a network error occurs. It
+  # could be request timeout, socket error or anything else.
   #
-  # Raise an exception if AlphaCard Gateway return some exception
-  # due to connection problems or some other net errors.
+  # @param [Exception] e
+  #   Exception object.
   #
-  #    response = RestClient.post(URL, {param: 'value'})
-  #    handle_connection_errors(response) #=> Exception
+  # @raise [AlphaCard::AlphaCardError]
+  #   AlphaCardError Exception.
   def self.handle_connection_errors(e)
     case e
       when RestClient::ServerBrokeConnection, RestClient::RequestTimeout

data/lib/alpha_card/account.rb

@@ -1,13 +1,45 @@
 module AlphaCard
+  ##
+  # Implementation of Alpha Card Services account object.
+  # Contains credentials (username and password) for 
+  # the Alpha Card Gateway API access.
   class Account < AlphaCardObject
     attribute :username, String
     attribute :password, String
 
+    ##
+    # <code>AlphaCard::Account</code> constructor.
+    #
+    # @param [String] username
+    # @param [String] password
+    #
+    # @example
+    #   AlphaCard::Account.new('demo', 'password')
+    #
+    #   #=> #<AlphaCard::Account:0x000000039b18a8 @username="demo", @password="password">
     def initialize(username, password)
       self.username = username
       self.password = password
     end
 
+    ##
+    # Say if all the credentials of Account is filled.
+    # Username and password can't be a <code>nil</code>
+    # object or an empty <code>String</code>.
+    #
+    # @return [Boolean]
+    #   True if username and password is filled.
+    #
+    # @example
+    #   account = AlphaCard::Account.new('demo', 'password')
+    #   account.filled?
+    #
+    #   #=> true
+    #
+    #   account = AlphaCard::Account.new('', nil)
+    #   account.filled?
+    #
+    #   #=> false
     def filled?
       [self.username, self.password].all?(&:present?)
     end

data/lib/alpha_card/alpha_card_error.rb

@@ -1,4 +1,6 @@
 module AlphaCard
+  ##
+  # Class for Alpha Card Gateway errors and exceptions.
   class AlphaCardError < StandardError
   end
 end

data/lib/alpha_card/alpha_card_object.rb

@@ -1,16 +1,22 @@
 module AlphaCard
+  ##
+  # Parent class for each Alpha Card Gateway object, such as
+  # Order, Billing, Sale and others.
   class AlphaCardObject
     include Virtus.model
 
-    # filled_attributes -> Hash
+    ##
+    # Returns the <code>Hash</code> with only filled attributes
+    # of the <code>AlphaCard::AlphaCardObject</code>.
     #
-    # Returns only filled attributes, not nil ones.
+    # @return [Hash]
+    #   Filled attributes of the <code>AlphaCard::AlphaCardObject</code>.
     #
-    #    order = AlphaCard::Order.new({})
-    #    order.filled_attributes #=> {}
-
-    #    order = AlphaCard::Order.new({orderid: '1'})
-    #    order.filled_attributes #=> {orderid: '1'}
+    # @example
+    #   order = AlphaCard::Order.new({orderid: '1', tax: nil, ponumber: 'PO123'})
+    #   order.filled_attributes
+    #
+    #   #=> {orderid: '1', ponumber: 'PO123'}
     def filled_attributes
       self.attributes.select { |key, value| value.present? }
     end

data/lib/alpha_card/alpha_card_response.rb

@@ -1,13 +1,20 @@
 module AlphaCard
+  ##
+  # Implementation of Alpha Card Services response.
+  # Contains all the data, that Alpha Card Gateway
+  # returned for the request.
   class AlphaCardResponse
     attr_reader :data
 
+    # Success response code
     APPROVED = '1'
+    # Decline response code
     DECLINED = '2'
+    # Error response code
     ERROR    = '3'
 
     def initialize(request_body)
-      @data = Rack::Utils.parse_nested_query(request_body)
+      @data = AlphaCard::Utils.parse_query(request_body)
     end
 
     def text

data/lib/alpha_card/billing.rb

@@ -1,4 +1,7 @@
 module AlphaCard
+  ##
+  # Implementation of Alpha Card Services order billing information.
+  # Contains all the billing information (customer name, email, email, etc).
   class Billing < AlphaCardObject
     attribute :firstname, String
     attribute :lastname, String

data/lib/alpha_card/object.rb

@@ -1,17 +1,47 @@
-# Object class needed to implement some nice
-# active_support features for projects, that
-# doesn't need active_support.
-#
-# Use-case: standalone Ruby scripts
+##
+# Some stolen methods from the active_support gem.
+# For the clear dependencies.
+# @todo Remove this class, rewrite library code
 class Object
+  # An object is blank if it's false, empty, or a whitespace string.
+  # For example, '', '   ', +nil+, [], and {} are all blank.
+  #
+  # This simplifies
+  #
+  #   address.nil? || address.empty?
+  #
+  # to
+  #
+  #   address.blank?
+  #
+  # @return [true, false]
   def blank?
     respond_to?(:empty?) ? !!empty? : !self
   end
 
+  # An object is present if it's not blank.
+  #
+  # @return [true, false]
   def present?
     !blank?
   end
 
+  # Invokes the public method whose name goes as first argument just like
+  # +public_send+ does, except that if the receiver does not respond to it the
+  # call returns +nil+ rather than raising an exception.
+  #
+  # This method is defined to be able to write
+  #
+  #   @person.try(:name)
+  #
+  # instead of
+  #
+  #   @person ? @person.name : nil
+  #
+  # +try+ returns +nil+ when called on +nil+ regardless of whether it responds
+  # to the method:
+  #
+  #   nil.try(:to_i) # => nil, rather than 0
   def try(*a, &b)
     if a.empty? && block_given?
       yield self

data/lib/alpha_card/order.rb

@@ -1,4 +1,7 @@
 module AlphaCard
+  ##
+  # Implementation of Alpha Card Services Order object.
+  # Contains all the information about order (id, description, etc).
   class Order < AlphaCardObject
     attribute :orderid, Integer
     attribute :orderdescription, String

data/lib/alpha_card/sale.rb

@@ -1,24 +1,44 @@
 module AlphaCard
+  ##
+  # Implementation of Alpha Card Services Sale object.
+  # Contains all the information about Customer Credit Card,
+  # such as CVV, number, expiration date, etc.
+  # Process the Alpha Card Services payment.
   class Sale < AlphaCardObject
     attribute :ccexp, String
     attribute :ccnumber, String
     attribute :amount, String
     attribute :cvv, String
 
-    # Not writable attribute, define the type of transaction (default is 'sale')
+    ##
+    # Not writable attribute, defines the type of transaction (default is 'sale')
+    #
+    # @attribute [r] type
     attribute :type, String, default: 'sale', writer: :private
 
-    # create(order, account) -> true
-    # create(order, account) -> false
-    # create(order, account) -> Exception
+    ##
+    # Creates the sale for the specified <code>AlphaCard::Order</code>
+    # with the <code>AlphaCard::Account</code> credentials.
+    #
+    # @param [AlphaCard::Order] params
+    #    An <code>AlphaCard::Order</code> object.
+    # @param [AlphaCard::Account] account
+    #   An <code>AlphaCard::Account</code> object.
+    #
+    # @return [Boolean]
+    #   True if sale was created successfully.
+    #   Raise an AlphaCardError exception if some error occurred.
+    #
+    # @raise [Exception]
+    #   Exception if one of required attributes doesn't specified.
     #
-    # Creates the sale for the <i>order</i> with specified
-    # attributes, such as <i>ccexp</i>, <i>ccnumber</i>, <i>amount</i>
-    # and <i>cvv</i>.
+    # @example
+    #   account = AlphaCard::Account.new('demo', 'password')
+    #   order = AlphaCard::Order.new({orderid: 1, orderdescription: 'Test order'})
+    #   sale = AlphaCard::Sale.new({ccexp: '0117', ccnumber: '4111111111111111', amount: "5.00" })
+    #   sale.create(order, account)
     #
-    #    attrs = {ccexp: '0117', ccnumber: '123', amount: '10.00'}
-    #    sale = AlphaCard::Sale.new(attrs)
-    #    sale.create(order, account) #=> true or false
+    #   #=> true
     def create(order, account)
       [:ccexp, :ccnumber, :amount].each do |attr|
         raise Exception.new("No #{attr} information provided") if self[attr].blank?

data/lib/alpha_card/shipping.rb

@@ -1,4 +1,7 @@
 module AlphaCard
+  ##
+  # Implementation of Alpha Card Services order shipping information.
+  # Contains all the shipping information (address, city, zip, etc).
   class Shipping < AlphaCardObject
     attribute :address_1, String
     attribute :address_2, String

data/lib/alpha_card/utils.rb

@@ -0,0 +1,90 @@
+module AlphaCard
+  ##
+  # Some stolen methods to clear library dependencies.
+  class Utils
+    ##
+    # This one is from the rack gem. It is useful for
+    # parsing of Alpha Card Gateway response body.
+    # @see https://github.com/rack/rack rack gem GitHub
+    class << self
+      ##
+      # Default separators for query string.
+      DEFAULT_SEP = /[&;] */n
+
+      # A part of the rack gem.
+      class KeySpaceConstrainedParams
+        def initialize(limit = 65536)
+          @limit = limit
+          @size = 0
+          @params = {}
+        end
+
+        def [](key)
+          @params[key]
+        end
+
+        def []=(key, value)
+          @size += key.size if key && !@params.key?(key)
+          raise RangeError, 'exceeded available parameter key space' if @size > @limit
+          @params[key] = value
+        end
+
+        def key?(key)
+          @params.key?(key)
+        end
+
+        def to_params_hash
+          hash = @params
+          hash.keys.each do |key|
+            value = hash[key]
+            if value.kind_of?(self.class)
+              hash[key] = value.to_params_hash
+            elsif value.kind_of?(Array)
+              value.map! { |x| x.kind_of?(self.class) ? x.to_params_hash : x }
+            end
+          end
+          hash
+        end
+      end
+
+      ##
+      # Unescapes a URI escaped string with +encoding+. +encoding+ will be the
+      # target encoding of the string returned, and it defaults to UTF-8
+      if defined?(::Encoding)
+        def unescape(s, encoding = Encoding::UTF_8)
+          URI.decode_www_form_component(s, encoding)
+        end
+      else
+        def unescape(s, encoding = nil)
+          URI.decode_www_form_component(s, encoding)
+        end
+      end
+
+      ##
+      # Parses a query string to a Hash by breaking it up
+      # at the '&' and ';' characters.
+      def parse_query(qs, d = nil, &unescaper)
+        unescaper ||= method(:unescape)
+
+        params = KeySpaceConstrainedParams.new
+
+        (qs || '').split(d ? /[#{d}] */n : DEFAULT_SEP).each do |p|
+          next if p.empty?
+          k, v = p.split('=', 2).map(&unescaper)
+
+          if cur = params[k]
+            if cur.class == Array
+              params[k] << v
+            else
+              params[k] = [cur, v]
+            end
+          else
+            params[k] = v
+          end
+        end
+
+        params.to_params_hash
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alpha_card
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Nikita Bulaj
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-26 00:00:00.000000000 Z
+date: 2014-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -49,6 +49,7 @@ files:
 - lib/alpha_card/order.rb
 - lib/alpha_card/sale.rb
 - lib/alpha_card/shipping.rb
+- lib/alpha_card/utils.rb
 - spec/alpha_card/alpha_card_response_spec.rb
 - spec/alpha_card/alpha_card_spec.rb
 - spec/spec_helper.rb
@@ -77,3 +78,4 @@ signing_key:
 specification_version: 4
 summary: Alpha Card Services DirectPost API for Ruby
 test_files: []
+has_rdoc: