braintree 1.0.0

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009 Braintree Payment Solutions
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,62 @@
+= Braintree Ruby Client Library
+
+The Braintree gem provides integration access to the Braintree Gateway.
+
+== Dependencies
+
+* builder
+* libxml-ruby
+
+== Quick Start Example
+
+  require "rubygems"
+  require "braintree"
+
+  Braintree::Configuration.environment = :sandbox
+  Braintree::Configuration.merchant_id = "the_merchant_id"
+  Braintree::Configuration.public_key = "a_public_key"
+  Braintree::Configuration.private_key = "a_private_key"
+
+  transaction = Braintree::Transaction.sale!(
+    :amount => "100.00",
+    :credit_card => {
+      :number => "5105105105105100",
+      :expiration_date => "05/12"
+    }
+  )
+  puts "Transaction ID: #{transaction.id}"
+  puts "Status: #{transaction.status}"
+
+== Bang Methods
+
+Most methods have a bang and a non-bang version (e.g. <tt>Braintree::Customer.create</tt> and <tt>Braintree::Customer.create!</tt>).
+The non-bang version will either return a +SuccessfulResult+ or an +ErrorResult+. The bang version will either return
+the created or updated resource, or it will raise a ValidationsFailed exception.
+
+Example of using non-bang method:
+
+  result = Braintree::Customer.create!(:first_name => "Josh")
+  if result.success?
+    puts "Created customer #{result.customer.id}
+  else
+    puts "Validations failed"
+    result.errors.for(:customer).each do |error|
+      puts error.message
+    end
+  end
+
+Example of using bang method:
+
+  begin
+    customer = Braintree::Customer.create!(:first_name => "Josh")
+    puts "Created customer #{customer.id}
+  rescue Braintree::ValidationsFailed
+    puts "Validations failed"
+  end
+
+We recommend using the bang methods when you assume that the data is valid and do not expect validations to fail.
+Otherwise, we recommend using the non-bang methods.
+
+== License
+
+See the LICENSE file.

data/lib/braintree.rb

@@ -0,0 +1,66 @@
+require "cgi"
+require "digest/sha1"
+require "logger"
+require "net/http"
+require "net/https"
+require "stringio"
+require "time"
+require "zlib"
+
+require "builder"
+require "libxml"
+unless ::LibXML::XML.respond_to?(:default_keep_blanks=)
+  raise LoadError, "The version of libxml that you're using is not compatible with the Braintree gem."
+end
+
+module Braintree # :nodoc:
+  # Super class for all Braintree exceptions.
+  class BraintreeError < ::StandardError; end
+
+  # Raised when authentication fails. This may be caused by an incorrect <tt>Braintree::Configuration</tt>
+  class AuthenticationError < BraintreeError; end
+
+  # Raised when the API key being used is not authorized to perform the attempted action according
+  # to the roles assigned to the user who owns the API key.
+  class AuthorizationError < BraintreeError; end
+
+  # Raised when the Braintree gem is not completely configured. See <tt>Braintree::Configuration</tt>.
+  class ConfigurationError < BraintreeError
+    def initialize(setting, message) # :nodoc:
+      super "Braintree::Configuration.#{setting} #{message}"
+    end
+  end
+
+  # Raised when the gateway is down for maintenance.
+  class DownForMaintenanceError < BraintreeError; end
+
+  # Raised from methods that confirm transparent request requests
+  # when the given query string cannot be verified. This may indicate
+  # an attempted hack on the merchant's transparent redirect
+  # confirmation URL.
+  class ForgedQueryString < BraintreeError; end
+
+  # Raised when a record could not be found.
+  class NotFoundError < BraintreeError; end
+
+  # Raised when an unexpected server error occurs.
+  class ServerError < BraintreeError; end
+
+  # Raised when the SSL certificate fails verification.
+  class SSLCertificateError < BraintreeError; end
+
+  # Raised when an error occurs that the client library is not built to handle.
+  # This shouldn't happen.
+  class UnexpectedError < BraintreeError; end
+
+  # Raised from bang methods when validations fail.
+  class ValidationsFailed < BraintreeError; end
+end
+
+require "braintree/base_module"
+
+Dir.glob("#{File.dirname(__FILE__)}/braintree/**/*.rb").sort.each do |file|
+  next if file =~ /base_module/
+  load file
+end
+Braintree::SSLExpirationCheck.check_dates

data/lib/braintree/address.rb

@@ -0,0 +1,122 @@
+module Braintree
+  # An Address belongs to a Customer. It can be associated to a
+  # CreditCard as the billing address. It can also be used
+  # as the shipping address when creating a Transaction.
+  class Address
+    include BaseModule # :nodoc:
+   
+    attr_reader :company, :country_name, :created_at, :customer_id, :extended_address, :first_name, :id,
+      :last_name, :locality, :postal_code, :region, :street_address, :updated_at
+      
+    def self.create(attributes)
+      Util.verify_keys(_create_signature, attributes)
+      unless attributes[:customer_id]
+        raise ArgumentError, "Expected hash to contain a :customer_id"
+      end
+      unless attributes[:customer_id] =~ /\A[0-9A-Za-z_-]+\z/
+        raise ArgumentError, ":customer_id contains invalid characters"
+      end
+      response = Http.post "/customers/#{attributes.delete(:customer_id)}/addresses", :address => attributes
+      if response[:address]
+        SuccessfulResult.new(:address => new(response[:address]))
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :address or :api_error_response"
+      end
+    end
+    
+    def self.create!(attributes)
+      return_object_or_raise(:address) { create(attributes) }
+    end
+    
+    def self.delete(customer_or_customer_id, address_id)
+      customer_id = _determine_customer_id(customer_or_customer_id)
+      Http.delete("/customers/#{customer_id}/addresses/#{address_id}")
+      SuccessfulResult.new
+    end
+    
+    # Finds the address with the given +address_id+ that is associated to the given +customer_or_customer_id+.
+    # If the address cannot be found, a NotFoundError will be raised.
+    def self.find(customer_or_customer_id, address_id)
+      customer_id = _determine_customer_id(customer_or_customer_id)
+      response = Http.get("/customers/#{customer_id}/addresses/#{address_id}")
+      new(response[:address])
+    rescue NotFoundError
+      raise NotFoundError, "address for customer #{customer_id.inspect} with id #{address_id.inspect} not found"
+    end
+    
+    def self.update(customer_or_customer_id, address_id, attributes)
+      Util.verify_keys(_update_signature, attributes)
+      customer_id = _determine_customer_id(customer_or_customer_id)
+      response = Http.put "/customers/#{customer_id}/addresses/#{address_id}", :address => attributes
+      if response[:address]
+        SuccessfulResult.new(:address => new(response[:address]))
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :address or :api_error_response"
+      end
+    end
+    
+    def self.update!(customer_or_customer_id, address_id, attributes)
+      return_object_or_raise(:address) { update(customer_or_customer_id, address_id, attributes) }
+    end
+    
+    def initialize(attributes) # :nodoc:
+      set_instance_variables_from_hash(attributes)
+    end
+    
+    def ==(other) # :nodoc:
+      return false unless other.is_a?(Address)
+      id == other.id && customer_id == other.customer_id
+    end
+    
+    # Deletes the address.
+    def delete
+      Address.delete(customer_id, self.id)
+    end
+
+    def update(attributes)
+      Util.verify_keys(self.class._update_signature, attributes)
+      response = Http.put "/customers/#{customer_id}/addresses/#{id}", :address => attributes
+      if response[:address]
+        set_instance_variables_from_hash response[:address]
+        SuccessfulResult.new(:address => self)
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :address or :api_error_response"
+      end
+    end
+   
+    def update!(attributes)
+      return_object_or_raise(:address) { update(attributes) }
+    end
+
+    class << self
+      protected :new
+    end
+    
+    def self._create_signature # :nodoc:
+      [:company, :country_name, :customer_id, :extended_address, :first_name,
+        :last_name, :locality, :postal_code, :region, :street_address]
+    end
+    
+    def self._determine_customer_id(customer_or_customer_id) # :nodoc:
+      customer_id = customer_or_customer_id.is_a?(Customer) ? customer_or_customer_id.id : customer_or_customer_id
+      unless customer_id =~ /\A[\w_-]+\z/
+        raise ArgumentError, "customer_id contains invalid characters"
+      end
+      customer_id
+    end
+
+    def self._new(*args) # :nodoc:
+      self.new *args
+    end
+    
+    def self._update_signature # :nodoc:
+      _create_signature
+    end
+  end
+end

data/lib/braintree/base_module.rb

@@ -0,0 +1,29 @@
+module Braintree
+  module BaseModule # :nodoc: all
+    module Methods
+      def return_object_or_raise(object_to_return)
+        result = yield
+        if result.success?
+          result.send object_to_return
+        else
+          raise ValidationsFailed
+        end
+      end
+
+      def set_instance_variables_from_hash(hash)
+        hash.each do |key, value|
+          instance_variable_set "@#{key}", value
+        end
+      end
+  
+      def singleton_class
+        class << self; self; end
+      end
+    end
+    
+    def self.included(klass)
+      klass.extend Methods
+    end
+    include Methods
+  end
+end

data/lib/braintree/configuration.rb

@@ -0,0 +1,99 @@
+module Braintree
+  # The following configuration attributes need to be set to use the gem:
+  # * merchant_id
+  # * public_key
+  # * private_key
+  # * environment
+  #
+  # By default, the logger will log to +STDOUT+. The log level is set to info.
+  # The logger can be set to any Logger object.
+  module Configuration
+    API_VERSION = "1" # :nodoc:
+
+    class << self
+      attr_accessor :logger
+      attr_writer :merchant_id, :public_key, :private_key
+    end
+  
+    def self.expectant_reader(*attributes) # :nodoc:
+      attributes.each do |attribute|
+        (class << self; self; end).send(:define_method, attribute) do
+          attribute_value = instance_variable_get("@#{attribute}")
+          raise ConfigurationError.new(attribute.to_s, "needs to be set") unless attribute_value
+          attribute_value
+        end
+      end
+    end
+    expectant_reader :environment, :merchant_id, :public_key, :private_key
+  
+    def self.base_merchant_url # :nodoc:
+      "#{protocol}://#{server}:#{port}#{base_merchant_path}"
+    end
+  
+    def self.base_merchant_path # :nodoc:
+      "/merchants/#{Braintree::Configuration.merchant_id}"
+    end
+
+    def self.ca_file # :nodoc:
+      case environment
+      when :qa, :sandbox
+        File.expand_path(File.join(File.dirname(__FILE__), "..", "ssl", "valicert_ca.crt"))
+      when :production
+        File.expand_path(File.join(File.dirname(__FILE__), "..", "ssl", "securetrust_ca.crt"))
+      end
+    end
+ 
+    # Sets the Braintree environment to use. Valid values are <tt>:sandbox</tt> and <tt>:production</tt> 
+    def self.environment=(env)
+      unless [:development, :qa, :sandbox, :production].include?(env)
+        raise ArgumentError, "#{env.inspect} is not a valid environment"
+      end
+      @environment = env
+    end
+  
+    def self.logger # :nodoc:
+      @logger ||= _default_logger
+    end
+  
+    def self.port # :nodoc:
+      case environment
+      when :development
+        3000
+      when :production, :qa, :sandbox
+        443
+      end
+    end
+  
+    def self.protocol # :nodoc:
+      ssl? ? "https" : "http"
+    end
+  
+    def self.server # :nodoc:
+      case environment
+      when :development
+        "localhost"
+      when :production
+        "www.braintreegateway.com"
+      when :qa
+        "qa.braintreegateway.com"
+      when :sandbox
+        "sandbox.braintreegateway.com"
+      end    
+    end  
+    
+    def self.ssl? # :nodoc:
+      case environment
+      when :development
+        false
+      when :production, :qa, :sandbox
+        true
+      end    
+    end
+  
+    def self._default_logger # :nodoc:
+      logger = Logger.new(STDOUT)
+      logger.level = Logger::INFO
+      logger
+    end  
+  end
+end

data/lib/braintree/credit_card.rb

@@ -0,0 +1,231 @@
+module Braintree
+  class CreditCard
+    include BaseModule # :nodoc:
+    
+    attr_reader :billing_address, :bin, :card_type, :cardholder_name, :created_at, :customer_id, :expiration_month,
+      :expiration_year, :last_4, :token, :updated_at
+     
+    def self.create(attributes)
+      if attributes.has_key?(:expiration_date) && (attributes.has_key?(:expiration_month) || attributes.has_key?(:expiration_year))
+        raise ArgumentError.new("create with both expiration_month and expiration_year or only expiration_date")
+      end
+      Util.verify_keys(_create_signature, attributes)
+      _do_create("/payment_methods", :credit_card => attributes)
+    end
+    
+    def self.create!(attributes)
+      return_object_or_raise(:credit_card) { create(attributes) }
+    end
+   
+    # The transparent redirect URL to use to create a credit card.
+    def self.create_credit_card_url
+      "#{Braintree::Configuration.base_merchant_url}/payment_methods/all/create_via_transparent_redirect_request"
+    end
+ 
+    def self.create_from_transparent_redirect(query_string)
+      params = TransparentRedirect.parse_and_validate_query_string query_string
+      _do_create("/payment_methods/all/confirm_transparent_redirect_request", :id => params[:id])
+    end
+    
+    def self.credit(token, transaction_attributes)
+      Transaction.credit(transaction_attributes.merge(
+        :payment_method_token => token
+      ))
+    end
+    
+    def self.credit!(token, transaction_attributes)
+      return_object_or_raise(:transaction) { credit(token, transaction_attributes) }
+    end
+    
+    # Returns a PagedCollection of expired credit cards.
+    def self.expired(options = {})
+      page_number = options[:page] || 1
+      response = Http.get("/payment_methods/all/expired?page=#{page_number}")
+      attributes = response[:payment_methods]
+      attributes[:items] = Util.extract_attribute_as_array(attributes, :credit_card).map do |payment_method_attributes|
+        new payment_method_attributes
+      end
+      PagedCollection.new(attributes) { |page_number| CreditCard.expired(:page => page_number) }
+    end
+    
+    # Returns a PagedCollection of credit cards expiring between +start_date+ and +end_date+ inclusive.
+    # Only the month and year of the start and end dates are used.
+    def self.expiring_between(start_date, end_date, options = {})
+      page_number = options[:page] || 1
+      response = Http.get("/payment_methods/all/expiring?page=#{page_number}&start=#{start_date.strftime('%m%Y')}&end=#{end_date.strftime('%m%Y')}")
+      attributes = response[:payment_methods]
+      attributes[:items] = Util.extract_attribute_as_array(attributes, :credit_card).map do |payment_method_attributes|
+        new payment_method_attributes
+      end
+      PagedCollection.new(attributes) { |page_number| CreditCard.expiring_between(start_date, end_date, :page => page_number) }
+    end
+    
+    # Finds the credit card with the given +token+. Raises a NotFoundError if it cannot be found.
+    def self.find(token)
+      response = Http.get "/payment_methods/#{token}"
+      new(response[:credit_card])
+    rescue NotFoundError
+      raise NotFoundError, "payment method with token #{token.inspect} not found"
+    end
+    
+    def self.sale(token, transaction_attributes)
+      Transaction.sale(transaction_attributes.merge(
+        :payment_method_token => token
+      ))
+    end
+    
+    def self.sale!(token, transaction_attributes)
+      return_object_or_raise(:transaction) { sale(token, transaction_attributes) }
+    end
+
+    def self.update_from_transparent_redirect(query_string)
+      params = TransparentRedirect.parse_and_validate_query_string query_string
+      _do_update(:post, "/payment_methods/all/confirm_transparent_redirect_request", :id => params[:id])
+    end
+
+    # The transparent redirect URL to use to update a credit card.
+    def self.update_credit_card_url
+      "#{Braintree::Configuration.base_merchant_url}/payment_methods/all/update_via_transparent_redirect_request"
+    end
+    
+    def initialize(attributes) # :nodoc:
+      _init attributes
+    end
+
+    # Creates a credit transaction for this credit card.
+    def credit(transaction_attributes)
+      Transaction.credit(transaction_attributes.merge(
+        :payment_method_token => self.token
+      ))
+    end
+    
+    def credit!(transaction_attributes)
+      return_object_or_raise(:transaction) { credit(transaction_attributes) }
+    end
+    
+    def delete
+      Http.delete("/payment_methods/#{token}")
+    end
+    
+    # Returns true if this credit card is the customer's default.
+    def default?
+      @default
+    end
+    
+    # Expiration date formatted as MM/YYYY
+    def expiration_date
+      "#{expiration_month}/#{expiration_year}"
+    end
+   
+    # Returns true if the credit card is expired. 
+    def expired?
+      if expiration_year.to_i == Time.now.year
+        return expiration_month.to_i < Time.now.month
+      end
+      expiration_year.to_i < Time.now.year  
+    end
+    
+    def inspect # :nodoc:
+      first = [:token]
+      order = first + (self.class._attributes - first)
+      nice_attributes = order.map do |attr|
+        "#{attr}: #{send(attr).inspect}"
+      end
+      "#<#{self.class} #{nice_attributes.join(', ')}>"
+    end
+    
+    def masked_number
+      "#{bin}******#{last_4}"
+    end
+   
+    # Creates a sale transaction for this credit card. 
+    def sale(transaction_attributes)
+      CreditCard.sale(self.token, transaction_attributes)
+    end
+    
+    def sale!(transaction_attributes)
+      return_object_or_raise(:transaction) { sale(transaction_attributes) }
+    end
+    
+    def update(attributes)
+      Util.verify_keys(self.class._update_signature, attributes)
+      response = Http.put "/payment_methods/#{token}", :credit_card => attributes
+      if response[:credit_card]
+        _init response[:credit_card]
+        SuccessfulResult.new(:credit_card => self)
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :credit_card or :api_error_response"
+      end      
+    end
+    
+    def update!(attributes)
+      return_object_or_raise(:credit_card) { update(attributes) }
+    end
+
+    # Returns true if +other+ is a +CreditCard+ with the same token.
+    def ==(other)
+      return false unless other.is_a?(CreditCard)
+      token == other.token
+    end
+
+    class << self
+      protected :new
+    end
+
+    def self._attributes # :nodoc:
+      [
+        :billing_address, :bin, :card_type, :cardholder_name, :created_at, :customer_id, :expiration_month,
+        :expiration_year, :last_4, :token, :updated_at
+      ]
+    end
+
+    def self._create_signature # :nodoc:
+      [
+        :customer_id, :cardholder_name, :cvv, :number, :expiration_date, :token,
+        {:options => [:verify_card]},
+        {:billing_address => [:first_name, :last_name, :company, :country_name, :extended_address, :locality, :region, :postal_code, :street_address]}
+      ]
+    end
+
+    def self._new(*args) # :nodoc:
+      self.new *args
+    end    
+
+    def self._do_create(url, params) # :nodoc:
+      response = Http.post url, params
+      if response[:credit_card]
+        SuccessfulResult.new(:credit_card => new(response[:credit_card]))
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :credit_card or :api_error_response"
+      end
+    end
+
+    def self._do_update(http_verb, url, params) # :nodoc:
+      response = Http.send http_verb, url, params
+      if response[:credit_card]
+        SuccessfulResult.new(:credit_card => new(response[:credit_card]))
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :credit_card or :api_error_response"
+      end
+    end
+
+    def self._update_signature # :nodoc:
+      [
+        :cardholder_name, :cvv, :number, :expiration_date, :token,
+        {:options => [:verify_card]},
+        {:billing_address => [:first_name, :last_name, :company, :country_name, :extended_address, :locality, :region, :postal_code, :street_address]}
+      ]
+    end
+
+    def _init(attributes) # :nodoc:
+      set_instance_variables_from_hash(attributes)
+      @billing_address = attributes[:billing_address] ? Address._new(attributes[:billing_address]) : nil
+    end
+  end
+end