pp-adaptive 0.0.2

data/lib/pp-adaptive/set_payment_options_request.rb

@@ -0,0 +1,33 @@
+module AdaptivePayments
+  class SetPaymentOptionsRequest < AbstractRequest
+    operation :SetPaymentOptions
+
+    attribute :pay_key,             String,                     :param => "payKey"
+    attribute :initiating_entity,   Node[InitiatingEntity],     :param => "initiatingEntity"
+    attribute :display_options,     Node[DisplayOptions],       :param => "displayOptions"
+    attribute :shipping_address_id, String,                     :param => "shippingAddressId"
+    attribute :sender_options,      Node[SenderOptions],        :param => "senderOptions"
+    attribute :receiver_options,    NodeList[ReceiverOptions],  :param => "receiverOptions"
+
+    alias_params :initiating_entity, {
+      :institution_id          => :institution_id,
+      :customer_first_name     => :customer_first_name,
+      :customer_last_name      => :customer_last_name,
+      :customer_display_name   => :customer_display_name,
+      :institution_customer_id => :institution_customer_id,
+      :customer_country_code   => :customer_country_code,
+      :customer_email          => :customer_email
+    }
+
+    alias_params :display_options, {
+      :email_header_image_url    => :email_header_image_url,
+      :email_marketing_image_url => :email_marketing_image_url,
+      :header_image_url          => :header_image_url,
+      :business_name             => :business_name
+    }
+
+    alias_params :sender_options, {
+      :require_shipping_address_selection => :require_shipping_address_selection
+    }
+  end
+end

data/lib/pp-adaptive/set_payment_options_response.rb

@@ -0,0 +1,7 @@
+module AdaptivePayments
+  class SetPaymentOptionsResponse < AbstractResponse
+    operation :SetPaymentOptions
+
+    # no fields to define
+  end
+end

data/lib/pp-adaptive/support/aliases.rb

@@ -0,0 +1,33 @@
+require "forwardable"
+require "virtus"
+
+module AdaptivePayments
+  # Provides an interface to create shortcuts to child nodes without traversing an object graph
+  module Aliases
+    include Forwardable
+
+    # Invoke alias_name as if original_name were invoked on attr
+    #
+    # @param [Symbol] attr
+    #   the name of the attribute containing the child node
+    # @param [Symbol] alias_name
+    #   the name of the alias method to define
+    # @param [Symbol] original_name
+    #   the name of the original method in attr
+    def alias_param(attr, alias_name, original_name)
+      def_delegator attr, original_name,        alias_name
+      def_delegator attr, :"#{original_name}=", :"#{alias_name}="
+      def_delegator attr, :"#{original_name}?", :"#{alias_name}?" # FIXME: Only alias this for Booleans
+    end
+
+    # Shortcut for definining multiple aliases in a single call
+    #
+    # @param [Symbol] attr
+    #   the name of the attribute containing the child node
+    # @param [Hash] aliases
+    #   a Hash mapping { :alias_name => :original_name }
+    def alias_params(attr, aliases)
+      aliases.each { |k, v| alias_param(attr, k, v) }
+    end
+  end
+end

data/lib/pp-adaptive/support/coerced_array.rb

@@ -0,0 +1,52 @@
+module AdaptivePayments
+  # Array that coerces all input values to a JsonModel of the given type
+  class CoercedArray < Array
+    # Initialize the CoercedArray for the given type
+    #
+    # @param [Class<JsonModel>] type
+    #   the JsonModel descendant to coerce to
+    def initialize(type)
+      raise ArgumentError, "The type in a CoercedArray must be a JsonModel" unless type <= JsonModel
+
+      super()
+      @type = type
+    end
+
+    # Append the given value to the Array
+    # The value may be a Hash to coerce, or a valid JsonModel
+    #
+    # @param [Hash, JsonModel] object
+    #   the object to append
+    #
+    # @return CoercedArray
+    def push(object)
+      object = @type.new(object) unless object.kind_of?(@type)
+      super
+    end
+
+    alias_method :<<, :push
+
+    # Concatenate another Array with this one and return the result as a new Array
+    # All items in other will be coerced to the correct type
+    #
+    # @param [Array] other
+    #   another Array to concatenate with
+    #
+    # @return CoercedArray
+    def +(other)
+      raise ArgumentError, "Cannot union #{other.class} with #{self.class}<#{@type}>" unless other.kind_of?(Array)
+      super(CoercedArray.new(@type).concat(other))
+    end
+
+    # Concatenate another Array with this one and modify the Array in place
+    #
+    # @param [Array] other
+    #   another Array to concatenate with
+    #
+    # @return CoercedArray
+    def concat(other)
+      raise ArgumentError, "Cannot append #{other.class} to #{self.class}<#{@type}>" unless other.kind_of?(Array)
+      super(other.inject(CoercedArray.new(@type)) { |ary, v| ary.push(v) })
+    end
+  end
+end

data/lib/pp-adaptive/support/json_model.rb

@@ -0,0 +1,140 @@
+require "virtus"
+require "json"
+
+module AdaptivePayments
+  # A client-side, nestable, model based on Virtus, mapping JSON parameters to method names and vice-versa
+  #
+  # All types defined in the Adaptive Payments API documentation (both request and response) are built from this class.
+  #
+  #   class CurrencyConversion < JsonModel
+  #     attribute :from,          Node[CurrencyType]
+  #     attribute :to,            Node[CurrencyType]
+  #     attribute :exchange_rate, Decimal, :param => "exchangeRate"
+  #
+  #     alias_params :from, {
+  #       :from_amount        => :amount,
+  #       :from_currency_code => :code
+  #     }
+  #
+  #     alias_params :to, {
+  #       :to_amount        => :amount,
+  #       :to_currency_code => :code
+  #     }
+  #   end
+  #
+  # Virtus will allow varying input types and will cast them accordingly, so assigning '0.8767' to #exchange_rate in the
+  # above example will actually store BigDecimal('0.8767') in the model.
+  #
+  # The optional :param option defines the name of the property in the JSON representation, if it is different from the
+  # name of the attribute itself.
+  #
+  # In the above example, #alias_params has been used to create shortcuts to the #amount and #code attributes of the
+  # two [CurrencyType] attributes, #from and #to.  So:
+  #
+  #   conversion.from_amount == conversion.from.amount
+  #   conversion.from_currency_code == conversion.from.code
+  #
+  # It's possible to repeatedly create aliases like this, by chaining them together through multiple levels of the object
+  # graph.  The Adaptive Payments API is rather deeply nested and verbose by default, so to be a little easier to use and
+  # feel more ruby-esque, pp-adaptive define aliases where it seems logical to do so.  The fully qualified paths will always
+  # work, however.
+  class JsonModel
+    include Virtus
+    extend  Aliases
+
+    # Methods used for building a JsonModel given a JSON string.
+    module Parsing
+      # Process JSON input and return a JsonModel for the data.
+      #
+      # This method must be invoked on a subclass of the correct type.  Invoking it on JsonModel itself will do nothing.
+      # All parameters in the JSON are recursively mapped to their attribute names, based on :param on the attribute.
+      # Unknown parameters are ignored.
+      #
+      # @param [String] json
+      #   the raw JSON string as returned by the API
+      #
+      # @return [JsonModel]
+      #   a JsonModel mapped against the provided JSON
+      def from_json(json)
+        new(to_attributes(JSON.parse(json)))
+      end
+
+      # Given a ruby Hash representation of raw JSON from the API (or a subset thereof), map all JSON parameter keys to attribute names
+      #
+      # @param [Hash] json
+      #   a ruby Hash representing a subset of the overall JSON structure
+      #
+      # @return [Hash]
+      #   a new Hash with all keys mapped to their attribute names
+      def to_attributes(json)
+        json = {} unless json.kind_of?(Hash)
+        json.inject({}) { |hash, (key, value)| (attr_value = attribute_value(key, value)) ? hash.merge(attribute_key(key) => attr_value) : hash }
+      end
+
+      private
+
+      def attribute_key(key)
+        Hash[attributes.map { |attr| [attr.options.fetch(:param, attr.name).to_s, attr.name.to_sym] }][key] || key.to_sym
+      end
+
+      def attribute_value(key, value)
+        return unless attribute = attributes[attribute_key(key)]
+
+        case attribute
+          when Node
+            attribute.type.to_attributes(value)
+          when NodeList
+            value.map { |v| attribute.type.to_attributes(v) } if value.kind_of?(Array)
+          else
+            value
+        end
+      end
+    end
+
+    # Methods for converting a JsonModel into a JSON string for transport to the API
+    module Writing
+      # Recursively read all attributes in a ruby Hash, mapping attribute names to JSON parameters, according to the :param option
+      #
+      # @return [Hash]
+      #   the JSON representation in ruby Hash form
+      def to_hash
+        attributes.inject({}) { |hash, (key, value)| value.nil? ? hash : hash.merge(json_key(key) => json_value(value)) } \
+          .reject { |key, value| value.kind_of?(Enumerable) && value.none? }
+      end
+
+      # Convert this JsonModel into a JSON string for transport to the PayPal API
+      #
+      # @return [String]
+      #   the JSON string, containing all children, if any
+      def to_json(*)
+        to_hash.to_json
+      end
+
+      private
+
+      def json_key(key)
+        if self.class.attributes[key]
+          self.class.attributes[key].options.fetch(:param, key).to_s
+        else
+          key.to_s
+        end
+      end
+
+      def json_value(value)
+        case value
+          when JsonModel
+            value.to_hash
+          when CoercedArray
+            value.collect { |v| v.to_hash }
+          when BigDecimal, Float
+            "%.2f" % value
+          else
+            value
+        end
+      end
+    end
+
+    include Writing
+    extend  Parsing
+  end
+end

data/lib/pp-adaptive/support/node.rb

@@ -0,0 +1,45 @@
+require "virtus"
+
+module AdaptivePayments
+  # A Virtus Attribute used to box a type from the API to an Attribute in a JsonModel
+  #
+  # The Node type should not be used directly.  Instead it should be given a type to box.
+  #
+  #   attribute :child, Node[Child], :param => "childItem"
+  #
+  # In the above, the model gets an Attribute named #child, mapping to a JSON parameter named 'childItem'.
+  # The object at `model.child` is present by default, and is an object of type Child.
+  #
+  # Assigning a Hash directly to the attribute will store an object of the boxed type, based on the elements
+  # in the Hash.
+  class Node < Virtus::Attribute::Object
+    # Provide access to the boxed type
+    attr_reader :type
+
+    class << self
+      # Returns a descendant of Node, boxing the given type
+      #
+      # @param [Class<JsonModel>] type
+      #   the class definition to box
+      #
+      # @return [Node<type>]
+      #   an anonymous descendant of Node boxing the given type
+      def [](type)
+        raise ArgumentError, "Child nodes may only be other JsonModel classes" unless type <= JsonModel
+
+        @generated_class_map       ||= {}
+        @generated_class_map[type] ||= Class.new(self) do
+          default lambda { |m, a| type.new }
+
+          define_method :type do
+            type
+          end
+
+          define_method :coerce do |value|
+            value.kind_of?(Hash) ? type.new(value) : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pp-adaptive/support/node_list.rb

@@ -0,0 +1,45 @@
+require "virtus"
+
+module AdaptivePayments
+  # A Virtus Attribute used to hold a collection of objects boxed to a given type.
+  #
+  # The NodeList Attribute should not be used directly. Instead, it should be given a type to box.
+  #
+  #   attribute :children, NodeList[Child], :param => "child"
+  #
+  # In the above, the model gets an Array accessible through model.children.  All objects contained
+  # in the Array will be coerced to the boxed type. If an Array is assigned directly to the attribute,
+  # all items inside it will be coerced to the boxed type.  If a Hash is pushed onto the existing
+  # Array, it will be coerced to the boxed type.
+  class NodeList < Virtus::Attribute::Object
+    primitive ::Array
+
+    # Allow access to the boxed type
+    attr_reader :type
+
+    class << self
+      # Return a descendant of NodeList boxing the given type.
+      #
+      # @param [Class<JsonModel>] type
+      #   the type to box
+      #
+      # @return [NodeList]
+      #   an anonymous descendant of NodeList boxing the given type
+      def [](type)
+        raise ArgumentError, "Lists may only be created from JsonModel classes" unless type <= JsonModel
+
+        Class.new(self) do
+          default lambda { |m, a| CoercedArray.new(type) }
+
+          define_method :type do
+            type
+          end
+
+          define_method :coerce do |value|
+            CoercedArray.new(type) + Array(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pp-adaptive/types/account_identifier.rb

@@ -0,0 +1,6 @@
+module AdaptivePayments
+  class AccountIdentifier < JsonModel
+    attribute :email, String
+    attribute :phone, Node[PhoneNumberType]
+  end
+end

data/lib/pp-adaptive/types/address.rb

@@ -0,0 +1,17 @@
+module AdaptivePayments
+  class Address < JsonModel
+    attribute :id,             String,            :param => "addressId"
+    attribute :addressee_name, String,            :param => "addresseeName"
+    attribute :base_address,   Node[BaseAddress], :param => "baseAddress"
+
+    alias_params :base_address, {
+      :line1        => :line1,
+      :line2        => :line2,
+      :city         => :city,
+      :state        => :state,
+      :postal_code  => :postal_code,
+      :country_code => :country_code,
+      :type         => :type
+    }
+  end
+end

data/lib/pp-adaptive/types/address_list.rb

@@ -0,0 +1,5 @@
+module AdaptivePayments
+  class AddressList < JsonModel
+    attribute :addresses, NodeList[Address], :param => "address"
+  end
+end

data/lib/pp-adaptive/types/aliases/receiver_aliases.rb

@@ -0,0 +1,15 @@
+module AdaptivePayments
+  module ReceiverAliases
+    def self.included(base)
+      base.instance_eval do
+        alias_params :receiver, {
+          :receiver_email  => :email,
+          :receiver_amount => :amount,
+          :payment_type    => :payment_type,
+          :payment_subtype => :payment_subtype,
+          :invoice_id      => :invoice_id
+        }
+      end
+    end
+  end
+end

data/lib/pp-adaptive/types/aliases/receiver_list_aliases.rb

@@ -0,0 +1,32 @@
+module AdaptivePayments
+  module ReceiverListAliases
+    def self.included(base)
+      base.instance_eval do
+        alias_params :receiver_list, {
+          :receivers => :receivers
+        }
+
+        alias_params :first_receiver, {
+          :receiver_email  => :email,
+          :receiver_amount => :amount,
+          :payment_type    => :payment_type,
+          :payment_subtype => :payment_subtype,
+          :invoice_id      => :invoice_id,
+          :receiver_phone  => :phone
+        }
+
+        alias_params :receiver_phone, {
+          :receiver_phone_number       => :phone_number,
+          :receiver_phone_country_code => :country_code,
+          :receiver_phone_extension    => :extension
+        }
+      end
+    end
+
+    private
+
+    def first_receiver
+      receivers[0] ||= Receiver.new
+    end
+  end
+end

data/lib/pp-adaptive/types/base_address.rb

@@ -0,0 +1,11 @@
+module AdaptivePayments
+  class BaseAddress < JsonModel
+    attribute :line1,        String
+    attribute :line2,        String
+    attribute :city,         String
+    attribute :state,        String
+    attribute :postal_code,  String, :param => "postalCode"
+    attribute :country_code, String, :param => "countryCode"
+    attribute :type,         String
+  end
+end

data/lib/pp-adaptive/types/client_details_type.rb

@@ -0,0 +1,12 @@
+module AdaptivePayments
+  class ClientDetailsType < JsonModel
+    attribute :ip_address,     String, :param => "ipAddress"
+    attribute :device_id,      String, :param => "deviceId"
+    attribute :application_id, String, :param => "applicationId"
+    attribute :model,          String
+    attribute :geo_location,   String, :param => "geoLocation"
+    attribute :customer_type,  String, :param => "customerType"
+    attribute :partner_name,   String, :param => "partnerName"
+    attribute :customer_id,    String, :param => "customerId"
+  end
+end

data/lib/pp-adaptive/types/currency_code.rb

@@ -0,0 +1,5 @@
+module AdaptivePayments
+  class CurrencyCode < JsonModel
+    attribute :code, String, :param => "currencyCode"
+  end
+end

data/lib/pp-adaptive/types/currency_conversion.rb

@@ -0,0 +1,17 @@
+module AdaptivePayments
+  class CurrencyConversion < JsonModel
+    attribute :from,          Node[CurrencyType]
+    attribute :to,            Node[CurrencyType]
+    attribute :exchange_rate, Decimal, :param => "exchangeRate"
+
+    alias_params :from, {
+      :from_currency_amount => :amount,
+      :from_currency_code   => :code
+    }
+
+    alias_params :to, {
+      :to_currency_amount => :amount,
+      :to_currency_code   => :code
+    }
+  end
+end

data/lib/pp-adaptive/types/currency_conversion_list.rb

@@ -0,0 +1,15 @@
+module AdaptivePayments
+  class CurrencyConversionList < JsonModel
+    attribute :base_amount,   Node[CurrencyType], :param => 'baseAmount'
+    attribute :currency_list, Node[CurrencyList], :param => 'currencyList'
+
+    alias_params :base_amount, {
+      :base_currency_code   => :code,
+      :base_currency_amount => :amount
+    }
+
+    alias_params :currency_list, {
+      :currencies => :currencies
+    }
+  end
+end

data/lib/pp-adaptive/types/currency_conversion_table.rb

@@ -0,0 +1,5 @@
+module AdaptivePayments
+  class CurrencyConversionTable < JsonModel
+    attribute :currency_conversion_list, NodeList[CurrencyConversionList], :param => 'currencyConversionList'
+  end
+end

data/lib/pp-adaptive/types/currency_list.rb

@@ -0,0 +1,5 @@
+module AdaptivePayments
+  class CurrencyList < JsonModel
+    attribute :currencies, NodeList[CurrencyType], :param => "currency"
+  end
+end

data/lib/pp-adaptive/types/currency_type.rb

@@ -0,0 +1,6 @@
+module AdaptivePayments
+  class CurrencyType < JsonModel
+    attribute :amount, Decimal
+    attribute :code,   String
+  end
+end

data/lib/pp-adaptive/types/display_options.rb

@@ -0,0 +1,8 @@
+module AdaptivePayments
+  class DisplayOptions < JsonModel
+    attribute :email_header_image_url,    String, :param => "emailHeaderImageUrl"
+    attribute :email_marketing_image_url, String, :param => "emailMarketingImageUrl"
+    attribute :header_image_url,          String, :param => "headerImageUrl"
+    attribute :business_name,             String, :param => "businessName"
+  end
+end

data/lib/pp-adaptive/types/error_data.rb

@@ -0,0 +1,11 @@
+module AdaptivePayments
+  class ErrorData < JsonModel
+    attribute :id,         Integer, :param => "errorId"
+    attribute :domain,     String,  :param => "domain"
+    attribute :subdomain,  String,  :param => "subdomain"
+    attribute :severity,   String,  :param => "severity"
+    attribute :category,   String,  :param => "category"
+    attribute :message,    String,  :param => "message"
+    attribute :parameters, Array,   :param => "parameter", :default => lambda { |m, a| [] }
+  end
+end

data/lib/pp-adaptive/types/error_list.rb

@@ -0,0 +1,5 @@
+module AdaptivePayments
+  class ErrorList < JsonModel
+    attribute :errors, NodeList[ErrorData], :param => "error"
+  end
+end

data/lib/pp-adaptive/types/fault_message.rb

@@ -0,0 +1,23 @@
+module AdaptivePayments
+  module FaultMessage
+    def self.included(base)
+      base.instance_eval do
+        attribute :errors, NodeList[ErrorData], :param => "error"
+
+        alias_params :first_error, {
+          :error_id         => :id,
+          :error_domain     => :domain,
+          :error_subdomain  => :subdomain,
+          :error_severity   => :severity,
+          :error_category   => :category,
+          :error_message    => :message,
+          :error_parameters => :parameters
+        }
+      end
+    end
+
+    def first_error
+      errors.first || ErrorData.new
+    end
+  end
+end

data/lib/pp-adaptive/types/funding_constraint.rb

@@ -0,0 +1,5 @@
+module AdaptivePayments
+  class FundingConstraint < JsonModel
+    attribute :allowed_funding_type, Node[FundingTypeList], :param => "allowedFundingType"
+  end
+end

data/lib/pp-adaptive/types/funding_plan.rb

@@ -0,0 +1,28 @@
+module AdaptivePayments
+  class FundingPlan < JsonModel
+    attribute :id,                    String,                      :param => "fundingPlanId"
+    attribute :funding_amount,        Node[CurrencyType],          :param => "fundingAmount"
+    attribute :backup_funding_source, Node[FundingSource],         :param => "backupFundingSource"
+    attribute :sender_fees,           Node[CurrencyType],          :param => "senderFees"
+    attribute :currency_conversion,   Node[CurrencyConversion],    :param => "currencyConversion"
+    attribute :charges,               NodeList[FundingPlanCharge], :param => "charge"
+
+    alias_params :funding_amount, {
+      :amount        => :amount,
+      :currency_code => :code
+    }
+
+    alias_params :sender_fees, {
+      :sender_fees_amount        => :amount,
+      :sender_fees_currency_code => :code
+    }
+
+    alias_params :currency_conversion, {
+      :from_currency_amount => :from_currency_amount,
+      :from_currency_code   => :from_currency_code,
+      :to_currency_amount   => :to_currency_amount,
+      :to_currency_code     => :to_currency_code,
+      :exchange_rate        => :exchange_rate
+    }
+  end
+end

data/lib/pp-adaptive/types/funding_plan_charge.rb

@@ -0,0 +1,11 @@
+module AdaptivePayments
+  class FundingPlanCharge < JsonModel
+    attribute :charge,         Node[CurrencyType]
+    attribute :funding_source, Node[FundingSource], :param => "fundingSource"
+
+    alias_params :charge, {
+      :amount        => :amount,
+      :currency_code => :code
+    }
+  end
+end

data/lib/pp-adaptive/types/funding_source.rb

@@ -0,0 +1,9 @@
+module AdaptivePayments
+  class FundingSource < JsonModel
+    attribute :id,                          String,  :param => "fundingSourceId"
+    attribute :last_four_digits_of_account, String,  :param => "lastFourOfAccountNumber"
+    attribute :type,                        String
+    attribute :display_name,                String,  :param => "displayName"
+    attribute :allowed,                     Boolean
+  end
+end

data/lib/pp-adaptive/types/funding_type_info.rb

@@ -0,0 +1,5 @@
+module AdaptivePayments
+  class FundingTypeInfo < JsonModel
+    attribute :funding_type, String, :param => "fundingType"
+  end
+end

data/lib/pp-adaptive/types/funding_type_list.rb

@@ -0,0 +1,5 @@
+module AdaptivePayments
+  class FundingTypeList < JsonModel
+    attribute :funding_type_info, NodeList[FundingTypeInfo], :param => "fundingTypeInfo"
+  end
+end