bborn-simplepay 0.2.2

data/lib/simplepay/services/subscription.rb

@@ -0,0 +1,96 @@
+module Simplepay
+  module Services
+  
+    ##
+    # A Simple Pay Subscription is an automatically recurring payment which is
+    # charged every interval (Simplepay::Support::BillingFrequency) until
+    # a limiting period (Simplepay::Support::SubscriptionPeriod) is met.
+    # 
+    # With this type of payment, for example, you may charge your customer:
+    # 
+    #     $10.00 every 3 days until 9 days.
+    #     $9.95 every 1 month until forever.
+    # 
+    # === Simple Pay Subscription Fields
+    # 
+    # === Required Fields
+    # 
+    # The following attributes are required when creating a Simple Pay 
+    # Subscription form (in addition to those listed in +Simplepay::Service+):
+    # 
+    # amount:: The dollar value you'd like to collect.
+    # description:: A summary of the reason for the payment, this is displayed to your customer during checkout.
+    # recurring_frequency:: Defines how often to charge your customer (ex. "1 month")
+    # 
+    # ==== Optional Fields
+    # 
+    # abandon_url:: The fully-qualified URL to send your custom if they cancel during payment.
+    # auto_renew:: Instructs Amazon to automatically renew the subscription after the +subscription_period+ ends.
+    # cobranding_style:: Defines the type of cobranding to use during the checkout process.
+    # collect_shipping_address:: Tells Amazon whether or not to ask for shipping address and contact information.
+    # immediate_return:: Immediately returns the customer to your +return_url+ directly after payment.
+    # ipn_url:: Fully-qualified URL to which Amazon will POST instant payment notifications.
+    # process_immediately:: Instructs Amazon to immediately process the payment.
+    # reference_id:: A custom string your can set to identify this transaction, it will be returned with the IPNs and other returned data.
+    # return_url:: Fully-qualified URL for where to send your customer following payment.
+    # start_date:: Instructs Amazon with the timestamp to start the recurring subscription charges.
+    # subscription_period:: Defines the expiration window of the subscription (i.e. charge +amount+ every +recurring_frequency+ for "36 months")
+    # 
+    # === Example
+    # 
+    #     (in your view, using the form helper)
+    #     
+    #     <%= simplepay_form_for(:subscription, {
+    #           :amount               => 12.95,
+    #           :recurring_frequency  => "1 year",
+    #           :description          => "My.Url Yearly Dues"
+    #     }) %>
+    # 
+    class Subscription < Service
+      
+      required_field :access_key
+      required_field :signature
+      required_field :account_id,           :as     => :amazon_payments_account_id
+      required_field :signature_method,     :value => 'HmacSHA256'
+      required_field :signature_version,    :value => '2'
+      
+      
+      
+      required_field :recurring_frequency,  :class  => Support::BillingFrequency
+      required_field :description
+      required_field :amount,               :class  => Support::Amount
+      required_field :cobranding_style,     :value  => 'logo'
+      
+      field :subscription_period,           :class  => Support::SubscriptionPeriod
+      field :reference_id
+      field :immediate_return,              :class  => Support::Boolean
+
+      field :start_date,                    :class  => Support::Epoch,
+                                            :as     => :recurring_start_date
+      
+      field :collect_shipping_address,      :class  => Support::Boolean      
+      
+      field :process_immediately,           :class  => Support::Boolean,
+                                            :as     => :process_immediate
+
+      field :auto_renew,                    :class  => Support::Boolean,
+                                            :as     => :is_auto_renewal
+      
+      field :return_url
+      field :ipn_url
+      field :abandon_url
+      
+      # Used for trial periods
+      field :promotion_amount,              :class  => Support::Amount
+      field :number_of_promotion_transactions, :as  => :no_of_promotion_transactions
+      
+      # These fields are not currently utilized by the service
+      field :variable_marketplace_fee,      :value  => ''
+      field :donation_widget,               :as     => :is_donation_widget,
+                                            :value  => '0'
+      field :fixed_marketplace_fee,         :value  => ''
+      
+    end
+    
+  end
+end

data/lib/simplepay/support.rb

@@ -0,0 +1,16 @@
+require 'simplepay/support/amount'
+require 'simplepay/support/billing_frequency'
+require 'simplepay/support/boolean'
+require 'simplepay/support/currency'
+require 'simplepay/support/epoch'
+require 'simplepay/support/field'
+require 'simplepay/support/interval'
+require 'simplepay/support/simple_amount'
+require 'simplepay/support/subscription_period'
+
+module Simplepay
+  
+  module Support
+  end
+  
+end

data/lib/simplepay/support/amount.rb

@@ -0,0 +1,55 @@
+require 'bigdecimal'
+
+module Simplepay
+  module Support
+    
+    ##
+    # Amazon often represents dollar values as a combination of a value and a 
+    # currency.  In several types of requests, the combination is required for
+    # communication.
+    # 
+    # At the present time, Amazon only uses USD.
+    # 
+    class Amount
+      
+      attr_reader :amount
+      attr_reader :currency
+      
+      def initialize(amount, currency = Simplepay::Currency::USD)
+        self.amount   = amount
+        self.currency = currency
+      end
+      
+      
+      ##
+      # Sets the amount of the currency value, such as "1" for 1 USD.  This
+      # amount cannot be negative.
+      # 
+      def amount=(amount)
+        raise(ArgumentError, "Amount cannot be nil") unless amount
+        raise(ArgumentError, "Amount cannot be negative") if amount < 0
+        @amount = BigDecimal.new(amount.to_s)
+      end
+      
+      ##
+      # Sets the type of currency to use in the transaction.  The parameter
+      # can either be a known currency code (see Simplepay::Currency) or a
+      # custom Simplepay::Currency::Currency instance.
+      # 
+      def currency=(currency)
+        raise(ArgumentError, "Invalid currency, expected Simplepay::Support::Currency or currency code string.") unless currency.kind_of?(Simplepay::Support::Currency) || currency.kind_of?(String)
+        if currency.kind_of?(String)
+          currency =  Simplepay::Currencies.detect { |c| c.code == currency } ||
+                      raise(ArgumentError, "Invalid currency, '#{currency}'. Must be one of: #{Simplepay::Currencies.join(', ')}")
+        end
+        @currency = currency
+      end
+      
+      def to_s
+        "#{currency.code} #{currency.format % amount}"
+      end
+      
+    end
+    
+  end
+end

data/lib/simplepay/support/billing_frequency.rb

@@ -0,0 +1,14 @@
+require 'simplepay/support/interval'
+
+module Simplepay
+  module Support
+    
+    class BillingFrequency < Interval
+      ALLOWED_INTERVALS       = Simplepay::Intervals
+      
+      # Limited to 2 digits.
+      ALLOWED_QUANTITY_RANGE  = (1...100)
+    end
+    
+  end
+end

data/lib/simplepay/support/boolean.rb

@@ -0,0 +1,28 @@
+module Simplepay
+  module Support
+    
+    ##
+    # Acts as a delegator for Simplepay::Support::Field <tt>:class</tt>.
+    # 
+    # This class acts as a helper for sending boolean values to Amazon.  In
+    # their forms, booleans are expected to be either "0" or "1", for false or
+    # true, respectively.
+    # 
+    class Boolean
+      
+      def initialize(value)
+        @value = value
+      end
+      
+      ##
+      # Returns "1" if the boolean is true, "0" otherwise.
+      # 
+      def to_s
+        return '' if @value.nil?
+        @value ? Simplepay::Boolean::True : Simplepay::Boolean::False
+      end
+      
+    end
+    
+  end
+end

data/lib/simplepay/support/currency.rb

@@ -0,0 +1,21 @@
+module Simplepay
+  module Support
+    
+    ##
+    # Contains a name, recognized code, and basic formatting for a particular
+    # international monetary currency.
+    # 
+    class Currency
+      attr_reader :name, :code, :format
+      
+      def initialize(name, code, format)
+        @name, @code, @format = name, code, format
+      end
+      
+      def to_s
+        "#{code}"
+      end
+    end
+    
+  end
+end

data/lib/simplepay/support/epoch.rb

@@ -0,0 +1,39 @@
+module Simplepay
+  module Support
+    
+    ##
+    # Acts as a Simplepay::Support::Field <tt>:class</tt> delegator.
+    # 
+    # This class provides a means to have Time values returned as an integer
+    # since epoch (January 1, 1970).
+    # 
+    class Epoch
+      
+      def initialize(time)
+        @value = time ? parse(time) : Time.now
+      end
+      
+      ##
+      # Returns a String of Integers, representing seconds since epoch.
+      # 
+      def to_s
+        @value.to_i.to_s
+      end
+      
+      
+      private
+      
+      
+      def parse(time)
+        case time
+        when Time, Date, DateTime
+          time
+        else
+          Time.parse(time)
+        end
+      end
+      
+    end
+    
+  end
+end

data/lib/simplepay/support/field.rb

@@ -0,0 +1,147 @@
+require 'active_support'
+
+module Simplepay
+  module Support
+    
+    ##
+    # Represents a data field which will ultimately populate a Simple Pay 
+    # form.  These fields are often unique to their service.
+    # 
+    class Field
+      include Comparable
+      
+      ALLOWED_OPTIONS = [:as, :class, :required, :value]
+      
+      # The parent service of the field
+      attr_reader :service
+      
+      # The name of the field used in your local program (may be different than the service name)
+      attr_reader :name
+      
+      ##
+      # name:: Name which is used when referring to this field in the code.
+      # options:: An optional hash of field options.
+      # 
+      # === Options
+      # 
+      # as:: Overrides the +name+ when used by the service to the exact string or symbol (camelized) given.
+      # class:: Delegate the value mechanics to a separate class.
+      # required:: Tells whether or not this field is required for its service.
+      # value:: Set the value of the field at initialization.
+      # 
+      # === Example
+      # 
+      #     Field.new(:example, :required => true, :as => 'ExAmplE')
+      #     Field.new(:delegated, :class => Simplepay::Support::Boolean, :value => true)
+      # 
+      def initialize(service, name, options)
+        @service, @name, @options = service, name, normalize_options!(options)
+        @delegate   = options[:class]
+        @value      = nil
+        self.value  = options[:value] if options[:value]
+      end
+      
+      ##
+      # Returns the name of the field used by the service.  This may be 
+      # different than the Ruby name given to the field.
+      # 
+      # Symbol names (or :as options) are camelized.  If this is not desired,
+      # use a String, instead.
+      # 
+      def service_name
+        source = @options[:as] || @name
+        case source
+        when Symbol
+          source.to_s.camelize(:lower)
+        else
+          source
+        end
+      end
+      alias :to_s :service_name
+      
+      ##
+      # Returns +true+ if the field is required for the service.
+      # 
+      def required?
+        @options[:required] ? true : false
+      end
+      
+      ##
+      # Converts a Field into an HTML HIDDEN INPUT element as a string.
+      # 
+      def to_input
+        raise(RequiredFieldMissing, "Missing Required Field value for #{name}") if required? && value.blank?
+        value.blank? ? '' : html_input_tag
+      end
+      
+      def delegated? #:nodoc:
+        @delegate
+      end
+      
+      def value=(v) #:nodoc:
+        @value = delegated? ? @delegate.new(v) : v
+      end
+      
+      def value #:nodoc:
+        if delegated?
+          @value.to_s
+        else
+          case @value
+          when Proc
+            @value.call(self)
+          else
+            @value
+          end
+        end
+      end
+      
+      ##
+      # Sorting is based solely by +service_name+.
+      # 
+      def <=>(o)
+        self.service_name <=> o.service_name
+      end
+      
+      def ==(o) #:nodoc:
+        self.service  == o.service &&
+        self.name     == o.name
+      end
+      
+      def inspect #:nodoc:
+        %|#<#{self.class.name} Name:"#{@name}"#{" ServiceName:\"#{service_name}\"" if service_name != @name}#{" REQUIRED" if required?}>|
+      end
+      
+      def clone_for(o) #:nodoc:
+        self.class.new(o, deep_clone(@name), deep_clone(@options))
+      end
+      
+      def delegate #:nodoc:
+        @delegate
+      end
+      
+      
+      private
+      
+      
+      def html_input_tag #:nodoc:
+        Simplepay::Helpers::FormHelper.tag(:input, {
+          :name   => service_name,
+          :value  => value,
+          :type   => 'hidden'
+        })
+      end
+      
+      def normalize_options!(options) #:nodoc:
+        options.symbolize_keys!
+        raise(InvalidOptions, "Unrecognized options passed: #{(options.keys - ALLOWED_OPTIONS).join(', ')}") unless (options.keys - ALLOWED_OPTIONS).empty?
+        options
+      end
+      
+      def deep_clone(o)
+        Marshal::load(Marshal.dump(o))
+      end
+      
+    end
+    
+  end
+end

data/lib/simplepay/support/interval.rb

@@ -0,0 +1,143 @@
+module Simplepay
+  module Support
+    
+    class Interval
+      
+       # If set, limits the quantity to a value within this range
+      ALLOWED_QUANTITY_RANGE  = nil
+      
+      # If set, limits the interval set to a value within this array
+      ALLOWED_INTERVALS       = nil
+      
+      # Sets the default quantity value for new instances
+      DEFAULT_QUANTITY        = nil
+      
+      # Sets the default interval value for new instances
+      DEFAULT_INTERVAL        = nil
+      
+      # The numeric number of intervals
+      attr_reader :quantity
+      
+      # The interval, or "period", of time
+      attr_reader :interval
+      
+      
+      class << self
+        
+        def allowed_intervals
+          const_get(:ALLOWED_INTERVALS)
+        end
+        
+        def allowed_quantity_range
+          const_get(:ALLOWED_QUANTITY_RANGE)
+        end
+        
+        def default_quantity
+          const_get(:DEFAULT_QUANTITY)
+        end
+        
+        def default_interval
+          const_get(:DEFAULT_INTERVAL)
+        end
+        
+      end
+      
+      
+      ##
+      # Creates an instance of the Interval.  This can be called in one of 
+      # several ways:
+      # 
+      # no arguments:: Creates a new interval instance with default values.
+      # one argument, string:: Creates a new interval by parsing the given string to set both the quantity and interval.  Must be formatted as: "3 day" (quantity, space, interval)
+      # one argument, hash:: Creates a new interval and populates it with the given :quantity and :interval.  Uses defaults if not given.
+      # two arguments:: Creates a new interval with the first argument as the quantity, second argument as the interval.
+      # 
+      # === Examples
+      # 
+      # All of these are equivalent:
+      # 
+      #     Interval.new("3 day")
+      #     Interval.new({:quantity => 3, :interval => 'day'})
+      #     Interval.new(3, 'day')
+      # 
+      def initialize(*args)
+        parse_arguments(*args)
+      end
+      
+      ##
+      # Set the interval.
+      # 
+      def interval=(i)
+        raise(ArgumentError, "Interval '#{i}' should be one of: #{allowed_intervals.join(', ')}") if i && allowed_intervals && !allowed_intervals.include?(i)
+        @interval = i
+      end
+      
+      ##
+      # Set the quantity.
+      # 
+      def quantity=(q)
+        raise(ArgumentError, "Quantity '#{q}' should be in #{allowed_quantity_range}") if q && allowed_quantity_range && !allowed_quantity_range.include?(q)
+        @quantity = q
+      end
+      
+      ##
+      # Converts the interval into an Amazon-ready string.
+      # 
+      #     Interval.new(3, 'day').to_s # => "3 day"
+      # 
+      def to_s
+        "#{quantity} #{interval}" if interval
+      end
+      
+      def allowed_intervals #:nodoc:
+        self.class.allowed_intervals
+      end
+      
+      def allowed_quantity_range #:nodoc:
+        self.class.allowed_quantity_range
+      end
+      
+      def default_quantity #:nodoc:
+        self.class.default_quantity
+      end
+      
+      def default_interval #:nodoc:
+        self.class.default_interval
+      end
+      
+      
+      private
+      
+      
+      def parse_arguments(*args)
+        case args.size
+        when 0
+          self.quantity = self.default_quantity
+          self.interval = self.default_interval
+        when 1
+          case args.first
+          when String
+            parse_values_from(args.first)
+          when Hash
+            self.quantity = args.first[:quantity] || self.default_quantity
+            self.interval = args.first[:interval] || self.default_interval
+          end
+        else
+          self.quantity = args.first
+          self.interval = args[1]
+        end
+      end
+      
+      def parse_values_from(s)
+        if s =~ /\A([\d]+)\s+([\w]+)\Z/
+          self.quantity = $1.to_i
+          self.interval = $2
+        else
+          raise ArgumentError, "Unrecognzied initialization string given: #{s.inspect}"
+        end
+      end
+      
+    end
+    
+  end
+end