spook_and_pay 0.3.1.alpha → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b13e26bc3175899e0bc06a254cf58c8af8c20257
-  data.tar.gz: a19c29f21df4f66dbeba4d1143428d105be2ff23
+  metadata.gz: fb962e2e5cb48aa5da0423021039c2e37f0d54cf
+  data.tar.gz: e247fc0540cd4656aab4f18edc31d9c4c853d349
 SHA512:
-  metadata.gz: 7d0ddc7e8b5335a418d08c79dd9d8e66b3bf308fd85fdc0f5721f0890e856509d4edc0dd02a8179c7d817eb401cfddb1e31a48ebe47216f49a6cf5ce2ef50021
-  data.tar.gz: f1033687ba256d2a6aa30e5411d868d263139c132ff0c03a20aaa5825fd056348979aeee583fb7fbe6ac1cb7099b92539b119d357cf4dc0d82e5cfd1821a4313
+  metadata.gz: 25de0492cbc31f34355c366cf2b55f4196ec0fa4914beea0b78f5a5d85d203026ebf6680cfc991b241b01f44760c8facdc2f3d838c7db05d18ed0af18e151b0e
+  data.tar.gz: 9a6240d5ad254c9fb48db134967f7d47e716f2b14f9784d3ad512946ff9ad78c408478d08c16d7b66be2fc9915e272978c21306ea9192a58f321b87f865f744e

data/lib/spook_and_pay/credit_card.rb

@@ -6,7 +6,7 @@ module SpookAndPay
     # This module adds the ::attr_erroring_reader to this class
     extend SpookAndPay::ErroringReader
 
-    # An error raised when trying to perform an action on a card that has 
+    # An error raised when trying to perform an action on a card that has
     # invalid details or has expired.
     class InvalidCardError < StandardError
       def to_s
@@ -48,8 +48,8 @@ module SpookAndPay
       FIELDS.each {|f| instance_variable_set(:"@#{f}", vals[f]) if vals.has_key?(f)}
     end
 
-    # A getter which takes the card number stored and generates a nice masked 
-    # version. It also handles the case where the number isn't available and 
+    # A getter which takes the card number stored and generates a nice masked
+    # version. It also handles the case where the number isn't available and
     # just returns nil instead.
     #
     # @return String
@@ -68,7 +68,7 @@ module SpookAndPay
       end
     end
 
-    # Checks to see if funds can be credited to a card. Depends on the 
+    # Checks to see if funds can be credited to a card. Depends on the
     # gateway/provider supporting crediting and having a valid card.
     #
     # @return [true, false]
@@ -84,7 +84,7 @@ module SpookAndPay
       provider.supports_authorize? and valid? and !expired?
     end
 
-    # Checks to see if this card can be used for a purchase against the 
+    # Checks to see if this card can be used for a purchase against the
     # underlying gateway.
     #
     # @return [true, false]
@@ -157,6 +157,14 @@ module SpookAndPay
       expired
     end
 
+    # Retains the credit card within the payment provider's vault.
+    #
+    # @return SpookAndPay::Result
+    # @raises SpookAndPay::Providers::Base::NotSupportedError
+    def retain!
+      provider.retain_credit_card(self)
+    end
+
     private
 
 

data/lib/spook_and_pay/providers/base.rb

@@ -1,13 +1,13 @@
 module SpookAndPay
   module Providers
     # The abstract class from which other Provider classes should inherit. This
-    # class is intended to behave more as a template than anything else. It 
+    # class is intended to behave more as a template than anything else. It
     # provides very little in the way of actual implementation.
     #
-    # To implement a provider all of the public methods of this class — 
+    # To implement a provider all of the public methods of this class —
     # excluding #initialize — must be implemented.
     #
-    # Some features may not be supported by a provider, in which case the 
+    # Some features may not be supported by a provider, in which case the
     # `NotSupportedError` should be raised in lieu of a real implementation.
     class Base
       # A hash which maps between the fields for a credit card and the actual
@@ -17,8 +17,8 @@ module SpookAndPay
       FORM_FIELD_NAMES = {}.freeze
 
       # An error used when validating the contents of an options hash. Since
-      # many of the methods on the provider classes take additional arguments 
-      # as a Hash, it's important to make sure we give good errors when they 
+      # many of the methods on the provider classes take additional arguments
+      # as a Hash, it's important to make sure we give good errors when they
       # are missing.
       class InvalidOptionsError < StandardError
         def initialize(errors)
@@ -80,14 +80,14 @@ module SpookAndPay
         raise NotImplementedError
       end
 
-      # Returns a hash containing the details necessary for making a 
-      # submission. If you know what you're doing, you can use this directly, 
+      # Returns a hash containing the details necessary for making a
+      # submission. If you know what you're doing, you can use this directly,
       # but otherwise you should be using the form helpers.
       #
       # The details generated by this method are for submitting card details to
       # the provider for storage. Billing etc has to be handled via a separate
       # step after submission.
-      # 
+      #
       # The arguments for this are specific to each provider implementation,
       # but they all return a Hash with the same keys, like so:
       #   {
@@ -95,9 +95,9 @@ module SpookAndPay
       #     :hidden_fields => {...},
       #     :field_names => {...}
       #   }
-      # 
-      # Where :url is the target URL, :hidden_fields should be embedded in a 
-      # form as they are and :field_names provide the mapping between known 
+      #
+      # Where :url is the target URL, :hidden_fields should be embedded in a
+      # form as they are and :field_names provide the mapping between known
       # keys like :number and :cvv to the input names required by the provider.
       def prepare_payment_submission(*args)
         raise NotImplementedError
@@ -132,70 +132,90 @@ module SpookAndPay
         check_support('refund')
       end
 
-      # Checks to see if purchasing is supported. This is dependent on the payment 
-      # provider. The default implementation simply returns true. Specific 
+      # Partially refunds the amount of money captured in a transaction.
+      #
+      # This should not be called directly. Instead, use the #partial_refund! method
+      # provided by a Transaction instance.
+      #
+      # @param [SpookAndPay::Transaction, String] id
+      # @return SpookAndPay::Result
+      def partially_refund_transaction(id)
+        check_support('partial_refund')
+      end
+
+      # Checks to see if purchasing is supported. This is dependent on the payment
+      # provider. The default implementation simply returns true. Specific
       # implementations should over-ride this method.
-      # 
+      #
       # @return [true, false]
       def supports_purchase?
         true
       end
 
-      # Checks to see if voiding is supported. This is dependent on the payment 
-      # provider. The default implementation simply returns true. Specific 
+      # Checks to see if voiding is supported. This is dependent on the payment
+      # provider. The default implementation simply returns true. Specific
       # implementations should over-ride this method.
-      # 
+      #
       # @return [true, false]
       def supports_void?
         true
       end
 
-      # Checks to see if crediting is supported. This is dependent on the payment 
-      # provider. The default implementation simply returns true. Specific 
+      # Checks to see if crediting is supported. This is dependent on the payment
+      # provider. The default implementation simply returns true. Specific
       # implementations should over-ride this method.
-      # 
+      #
       # @return [true, false]
       def supports_credit?
         true
       end
 
-      # Checks to see if refunding is supported. This is dependent on the payment 
-      # provider. The default implementation simply returns true. Specific 
+      # Checks to see if refunding is supported. This is dependent on the payment
+      # provider. The default implementation simply returns true. Specific
       # implementations should over-ride this method.
-      # 
+      #
       # @return [true, false]
       def supports_refund?
         true
       end
 
-      # Checks to see if capturing is supported. This is dependent on the payment 
-      # provider. The default implementation simply returns true. Specific 
+      # Checks to see if partial refunding is supported. This is dependent on
+      # the payment provider. The default implementation simply returns true.
+      # Specific implementations should over-ride this method.
+      #
+      # @return [true, false]
+      def supports_partial_refund?
+        true
+      end
+
+      # Checks to see if capturing is supported. This is dependent on the payment
+      # provider. The default implementation simply returns true. Specific
       # implementations should over-ride this method.
-      # 
+      #
       # @return [true, false]
       def supports_capture?
         true
       end
 
-      # Checks to see if authorizing is supported. This is dependent on the payment 
-      # provider. The default implementation simply returns true. Specific 
+      # Checks to see if authorizing is supported. This is dependent on the payment
+      # provider. The default implementation simply returns true. Specific
       # implementations should over-ride this method.
-      # 
+      #
       # @return [true, false]
       def supports_authorize?
         true
       end
 
       # Checks to see if the deletion of payment details is supported. This is
-      # dependent on the payment provider. The default implementation simply 
+      # dependent on the payment provider. The default implementation simply
       # returns true. Specific implementations should over-ride this method.
-      # 
+      #
       # @return [true, false]
       def supports_delete?
         true
       end
 
-      # Voids an authorization. 
+      # Voids an authorization.
       #
       # This should not be called directly. Instead, use the #void! method
       # provided by a Transaction instance.
@@ -263,13 +283,26 @@ module SpookAndPay
         check_support('delete')
       end
 
+      # Retains a credit card within the provider's vault.
+      #
+      # This should not be called directly. Instead, use the #retain! method
+      # provided by a CreditCard instance.
+      #
+      # @param [SpookAndPay::CreditCard, String] id
+      # @return SpookAndPay::Result
+      # @api private
+      # @abstract Subclass to implement
+      def retain_credit_card(id)
+        check_support('retain')
+      end
+
       private
 
-      # Checks to see if a particular action is defined as being supported and 
+      # Checks to see if a particular action is defined as being supported and
       # raises the appropriate error.
       #
       # The basic semantics is this; if someone implementing a provider says an
-      # action is supported via a #supports_*? predicate, this method should 
+      # action is supported via a #supports_*? predicate, this method should
       # never be called, so we raise NotImplementedError. Otherwise they are
       # saying it's not supported and the appropriate response is to raise a
       # NotSupportedError.

data/lib/spook_and_pay/providers/spreedly.rb

@@ -11,7 +11,7 @@ module SpookAndPay
         :cvv              => "credit_card[verification_value]"
       }.freeze
 
-      # The which refers to a specific gateway. 
+      # The which refers to a specific gateway.
       #
       # @attr_reader String
       attr_reader :gateway_token
@@ -37,7 +37,7 @@ module SpookAndPay
         @gateway_token = config[:gateway_token]
         @currency_code = config[:currency_code] || 'AUD'
         @spreedly = ::Spreedly::Environment.new(
-          config[:environment_key], 
+          config[:environment_key],
           config[:access_secret],
           :currency_code => currency_code
         )
@@ -77,7 +77,7 @@ module SpookAndPay
           case opts[:execute]
           when :authorize then card.authorize!(opts[:amount])
           when :purchase  then card.purchase!(opts[:amount])
-          when :store     then SpookAndPay::Result.new(true, nil, :credit_card => card)
+          else                 SpookAndPay::Result.new(true, nil, :credit_card => card)
           end
         else
           SpookAndPay::Result.new(false, nil, :credit_card => card, :errors => extract_card_errors(card.raw))
@@ -109,12 +109,17 @@ module SpookAndPay
         coerce_result(result)
       end
 
+      def partially_refund_transaction(id, amount)
+        result = spreedly.refund_transaction(transaction_id(id), :amount => (amount.to_f * 100).to_i)
+        coerce_result(result)
+      end
+
       def void_transaction(id)
         result = spreedly.void_transaction(transaction_id(id))
         coerce_result(result)
       end
 
-      # This is a nasty little trick that makes the spreedly gateway class 
+      # This is a nasty little trick that makes the spreedly gateway class
       # store the characteristics XML fragment from the server.
       #
       # @todo In later versions this might not be necessary. When updating the
@@ -162,9 +167,19 @@ module SpookAndPay
         coerce_result(result)
       end
 
+      # Calls the retain action on the provider's vault.
+      #
+      # @param [SpookAndPay::CreditCard, Integer, String] id
+      # @return SpookAndPay::Result
+      # @api private
+      def retain_credit_card(id)
+        result = spreedly.retain_payment_method(credit_card_id(id))
+        coerce_result(result)
+      end
+
       private
 
-      # Retrieves the gateway from Spreedly and then inspects the response to 
+      # Retrieves the gateway from Spreedly and then inspects the response to
       # see what features it supports. This is a helper for the #supports_*?
       # predicates.
       #
@@ -197,7 +212,7 @@ module SpookAndPay
       # A mapping from the names used by Spreedly to the names SpookAndPay uses
       # internally.
       CARD_FIELDS = {
-        "full_name" => :name, 
+        "full_name" => :name,
         "number" => :number,
         "year" => :expiration_year,
         "month" => :expiration_month,
@@ -216,12 +231,12 @@ module SpookAndPay
       #
       # @param Spreedly::CreditCard result
       # @return Array<SpookAndPay::SubmissionError>
-      # @todo If the Spreedly API behaves later, the check for first/last 
+      # @todo If the Spreedly API behaves later, the check for first/last
       #       name might not be needed anymore.
       def extract_card_errors(result)
-        # This gnarly bit of code transforms errors on the first_name or 
+        # This gnarly bit of code transforms errors on the first_name or
         # last_name attributes into an error on full_name. This is because
-        # Spreedly accepts input for full_name, but propogates errors to the 
+        # Spreedly accepts input for full_name, but propogates errors to the
         # separate attributes.
         errors = result.errors.map do |e|
           case e[:attribute]
@@ -243,7 +258,7 @@ module SpookAndPay
         end
       end
 
-      # Extracts/coerces errors from a Spreedly transaction into 
+      # Extracts/coerces errors from a Spreedly transaction into
       # SubmissionError instances.
       #
       # @param Spreedly::Transaction result
@@ -288,11 +303,12 @@ module SpookAndPay
         fields = {}
 
         fields[:type], status = case transaction
-        when ::Spreedly::Authorization  then [:authorize, :authorized]
-        when ::Spreedly::Purchase       then [:purchase, :settled]
-        when ::Spreedly::Capture        then [:capture, :settled]
-        when ::Spreedly::Refund         then [:credit, :refunded]
-        when ::Spreedly::Void           then [:void, :voided]
+        when ::Spreedly::Authorization        then [:authorize, :authorized]
+        when ::Spreedly::Purchase             then [:purchase, :settled]
+        when ::Spreedly::Capture              then [:capture, :settled]
+        when ::Spreedly::Refund               then [:credit, :refunded]
+        when ::Spreedly::Void                 then [:void, :voided]
+        when ::Spreedly::RetainPaymentMethod  then [:retain, :retained]
         end
 
         if transaction.respond_to?(:amount)

data/lib/spook_and_pay/transaction.rb

@@ -1,12 +1,12 @@
 module SpookAndPay
-  # A simple class representing an interaction with a provider. Each 
-  # interaction has an ID, a type and may be successful or not. It is 
+  # A simple class representing an interaction with a provider. Each
+  # interaction has an ID, a type and may be successful or not. It is
   # read-only.
   class Transaction
     # Basic attributes
     attr_reader :provider, :id, :status, :raw
 
-    # Extra set of fields which may or may not be present depending on the 
+    # Extra set of fields which may or may not be present depending on the
     # provider.
     FIELDS = [:created_at, :updated_at, :amount, :credit_card, :type].freeze
     attr_reader *FIELDS
@@ -37,7 +37,7 @@ module SpookAndPay
       end
     end
 
-    # As a bare minimum the transaction captures the transaction ID, it's 
+    # As a bare minimum the transaction captures the transaction ID, it's
     # status and the raw response from the provider. Optionally, it can receive
     # other fields via the opts hash.
     #
@@ -60,7 +60,7 @@ module SpookAndPay
       FIELDS.each {|f| instance_variable_set(:"@#{f}", opts[f]) if opts.has_key?(f)}
     end
 
-    # Implements value comparison i.e. if class and ID match, they are the 
+    # Implements value comparison i.e. if class and ID match, they are the
     # same.
     #
     # @param Class other
@@ -127,7 +127,20 @@ module SpookAndPay
       provider.refund_transaction(self)
     end
 
-    # Captures an authorized transaction. Will only capture the amount 
+    # Refunds the transaction. The related credit card will be credited for
+    # the amount specified. It will only succeed for purchases or captured
+    # authorizations.
+    #
+    # @param Numeric amount
+    # @return SpookAndPay::Result
+    # @raises SpookAndPay::Transaction::InvalidActionError
+    # @raises SpookAndPay::Providers::Base::NotSupportedError
+    def partial_refund!(amount)
+      raise InvalidActionError.new(id, :partial_refund, status) unless settled?
+      provider.partially_refund_transaction(self, amount)
+    end
+
+    # Captures an authorized transaction. Will only capture the amount
     # authorized and will fail if the transaction is already captured.
     #
     # @return SpookAndPay::Result
@@ -138,7 +151,7 @@ module SpookAndPay
       provider.capture_transaction(self)
     end
 
-    # Voids a transaction. Can only be done when the transaction is in the 
+    # Voids a transaction. Can only be done when the transaction is in the
     # authorized status. Otherwise it must be refunded.
     #
     # @return SpookAndPay::Result

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spook_and_pay
 version: !ruby/object:Gem::Version
-  version: 0.3.1.alpha
+  version: 1.0.0
 platform: ruby
 authors:
 - Luke Sutton
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-23 00:00:00.000000000 Z
+date: 2015-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: braintree
@@ -43,14 +43,14 @@ dependencies:
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.4.0
 - !ruby/object:Gem::Dependency
@@ -81,20 +81,6 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.11.0
-- !ruby/object:Gem::Dependency
-  name: debugger
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 1.6.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 1.6.1
 description: 
 email:
 - lukeandben@spookandpuff.com
@@ -126,17 +112,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: A library for handling online payments using services providing transparent