google4r-checkout 0.1.0

data/CHANGES

@@ -0,0 +1,40 @@
+= google4r-checkout Changelog
+
+== HEAD
+
+== 0.1.0 (2007-05-12)
+
+* Added property "shipping_taxed" to TaxRule (contributed by Dan Dukeson).
+* Added XML generation for the tax tables in the shopping cart (contributed by Dan Dukeson).
+* Added Area subclasses WorldArea and PostalArea (contributed by Dan Dukeson).
+* Changed time zones in tests to UTC.
+* Added Test::Unit::TestCase#assert_strings_equal to test_helper.rb.
+* Added "rake test" (alias of "rake test:all")
+* Added GoogleCheckoutError#to_s to return verbose representation.
+* Split google4r into google4r-checkout and google4r-maps.
+* MerchantCode#create_from_element raises an ArgumentError instead of a RuntimeError on invalid elements now.
+* Changed the #create_from_element code to set the properties directly into the objects instead of building Hashes to collect the values first.
+* "Resolved" the problem of converting currency amounts which are fractional numbers into the amount of the minor currency to be passed into the Money class: Instead of converting the fractional number into a float and multiplying by 100, all nonnumeric characters are stripped from the string, the resulting number is converted into an integer and this integer is then passed to Money.new.
+* Added example to NotificationHandler of how to use the class.
+* Added link to simple_http_auth plugin in NotificationHandler which allows for easy HTTP Auth Basic protection of Rails controllers.
+* Renamed CheckoutCommand#cart to CheckoutCommand#shopping_cart
+* CheckoutCommand raises ArgumentError instead of RuntimeError on invalid clazz parameter.
+* Added "Howto freeze google4r in a Rails project" to README
+* Google4R::Checkout::Command#to_xml raises an NotImplementedError instead of a RuntimeError now.
+* Geocoder returns nil on 603 (G_UNAVAILABLE_ADDRESS) results now.
+* Added support for registering GUnload() to be called on window's unload event.
+* The generated Javascript that creates the GMap2() instance (and thus modifies the map div) has been put into a function <var name>_loader that is called in  an onload handler. This should remove a problem with MSIE.
+* Using Syck as the YAML parser now. However, a workaround is needed because of http://code.whytheluckystiff.net/syck/ticket/27.
+* Only require the json gem if objects have no "to_json" method already added to them. This solves a problem with converting arbitrary objects to json because the json gem seemingly only converts simple types.
+* Added GMarker#info_window_html.
+* Added support for onclick handlers in markers.
+* Added support for the value :auto of GMap2#zoom and GMap2#center.
+* Fixed buggy generation of GMarker Javascript.
+* Adding website folder to contain a webgen based website.
+* Fixed a problem with generating XML from Hashes in the "private" data of shopping carts and items.
+* The parse for the <order-adjustment> tag does not expect to see a <shipping> tag in every case any more.
+* Extending Google4R::Maps by the classes GMap2, GIcon and GMarker to allow for easy Google Maps HTML generation.
+
+== 0.0.1 (2007-02-17)
+  
+* initial release, be prepared for some API changes that move the API closer to the XML API

data/LICENSE

@@ -0,0 +1,22 @@
+Unless noted otherwise, the files of this projects are licensed under a MIT
+style license:
+
+Copyright (c) 2007 Manuel Holtgrewe
+
+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

@@ -0,0 +1,76 @@
+= google4r/checkout
+
+google4r/checkout is a library to access the Google Checkout API.
+
+=== License
+
+google4r itself is distributed under an MIT style license.
+
+However, the library includes the cacert.pem:http://curl.haxx.se/ca/cacert.pem file from the Mozilla project. This file is distributed under the MPL:http://www.mozilla.org/MPL/.
+
+== Status
+
+You can find more information on the Google Checkout API here:http://code.google.com/apis/checkout/developer/index.html. Note that the API documentation assumes an understanding of the Google Checkout XML API.
+
+Google4R also contains a partial implementation of the level 2 of the Google Checkout API:
+
+* The <checkout-cart-command> tag and all of its subtags that are not related to the merchant calculation API can be generated.
+* The <new-order-notification> tag and all of its subtags which are not related to the merchant calculation API can be parsed.
+* The <order-state-change-notification> tag can be parsed.
+
+== Google Checkout Tests
+
+You have to place a file called 'frontend_configuration.rb' in the directory'test' with the configuration for the Google4R::Checkout::Frontend class to use for running the tests.
+
+The file should contain content similar to:
+
+  # Uncomment the following line if you are using Google Checkout in Great Britain
+  # and adjust it if you want to test google4r-checkout against any other (future)
+  # Google Checkout service.
+  
+  # Money.default_currency = 'GBP'
+  
+  # The test configuration for the Google4R::Checkout::Frontend class.
+  FRONTEND_CONFIGURATION = 
+    { 
+      :merchant_id => '<your merchant id>', 
+      :merchant_key => '<your merchant key>',
+      :use_sandbox => true
+    }
+
+== TODO
+
+Notifications:
+
+* <risk-information-notification>
+* <charge-amount-notification>
+* <refund-amount-notification>
+* <chargeback-amount-notification>
+* <authorization-amount-notification>
+
+All of the Order Processing API.
+
+== Dependencies
+
+The unit tests use Mocha so you have to install the gem "mocha" to run the tests. You will also need the money gem library.
+
+== How To: Freeze a google4r version in a Rails project
+
+<code>rake rails:freeze:gems</code> only works for the Rails gems. So, how do you freeze your own gems like google4r? It turns out to be pretty straightforward:
+
+  cd RAILS_ROOT
+  cd vendor
+  gem unpack google4r-checkout
+  ls 
+  # ... google4r-checkout-0.1.1 ...
+
+Then, open RAILS_ROOT/config/environment.rb in your favourite text editor and add the following lines at the top of the file just below <code>require File.join(File.dirname(__FILE__), 'boot')</code>:
+
+  # Freeze non-Rails gem.
+  Dir.glob(File.join(RAILS_ROOT, 'vendor', '*', 'lib')) do |path|
+    $LOAD_PATH << path
+  end
+
+Now you can use the following in your own code:
+
+  require 'google4r/checkout'

data/lib/google4r/checkout.rb

@@ -0,0 +1,33 @@
+#--
+# Project:   google4r
+# File:      lib/google4r/checkout.rb
+# Author:    Manuel Holtgrewe <purestorm at ggnore dot net>
+# Copyright: (c) 2007 by Manuel Holtgrewe
+# License:   MIT License as follows:
+#
+# 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. 
+#++
+# Require all the files that provide the code for the Google Checkout wrapper.
+
+require 'google4r/checkout/shared'
+require 'google4r/checkout/commands'
+require 'google4r/checkout/notifications'
+require 'google4r/checkout/xml_generation'
+require 'google4r/checkout/frontend'

data/lib/google4r/checkout/commands.rb

@@ -0,0 +1,260 @@
+#--
+# Project:   google4r
+# File:      lib/google4r/checkout/commands.rb 
+# Author:    Manuel Holtgrewe <purestorm at ggnore dot net>
+# Copyright: (c) 2007 by Manuel Holtgrewe
+# License:   MIT License as follows:
+#
+# 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. 
+#++
+# This file contains the classes and modules that are used by the command
+# generating code.
+
+require 'openssl'
+require 'money'
+require 'net/http'
+require 'net/https'
+require 'uri'
+
+module Google4R #:nodoc:
+  module Checkout #:nodoc:
+    # Abstract super class for all commands that are to be sent to Google. Provides the base
+    # functionality for signing and encoding the cart.
+    class Command
+      # The URL to use for requests to the sandboxed API. The merchant id is to be
+      # put in via String#%.
+      #--
+      # TODO: Move this into a class variable (e.g. via cattr) so it is adaptable.
+      #++
+      SANDBOX_URL = "https://sandbox.google.com/checkout/cws/v2/Merchant/%s/request"
+      
+      # The URL to use for real requests to the Google Checkout API. The merchant id
+      # is to be put in via String#%.
+      #--
+      # TODO: Move this into a class variable (e.g. via cattr) so it is adaptable.
+      #++
+      PRODUCTION_URL = "https://checkout.google.com/cws/v2/Merchant/%s/request"
+      
+      # The Frontent class that was used to create this CheckoutCommand and whose
+      # configuration will be used.
+      attr_reader :frontend
+
+      # Initialize the frontend attribute with the value of the frontend parameter.
+      def initialize(frontend)
+        @frontend = frontend
+      end
+
+      # Sends the cart's XML to GoogleCheckout via HTTPs with Basic Auth.
+      #
+      # Raises an OpenSSL::SSL::SSLError when the SSL certificate verification failed.
+      #
+      # Raises a GoogleCheckoutError when Google returns an error.
+      #
+      # Raises a RuntimeException on unknown responses.
+      #--
+      # TODO: The send-and-expect-response part should be adaptable to other commands and responses.
+      #++
+      def send_to_google_checkout
+        # Create HTTP(S) POST command and set up Basic Authentication.
+        url_str = 
+          if frontend.configuration[:use_sandbox] then
+            SANDBOX_URL % frontend.configuration[:merchant_id]
+          else
+            PRODUCTION_URL % frontend.configuration[:merchant_id]
+          end
+        url = URI.parse(url_str)
+        
+        request = Net::HTTP::Post.new(url.path)
+        request.basic_auth(frontend.configuration[:merchant_id], frontend.configuration[:merchant_key])
+
+        # Set up the HTTP connection object and the SSL layer.
+        https = Net::HTTP.new(url.host, url.port)
+        https.use_ssl = true
+        https.cert_store = self.class.x509_store
+        https.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        https.verify_depth = 5
+
+        # Send the request to Google.
+        result = https.request(request, self.to_xml)
+        
+        case result
+        when Net::HTTPSuccess then
+          xml_doc = REXML::Document.new(result.body)
+          
+          case xml_doc.root.name
+          when 'checkout-redirect'
+            serial_number = xml_doc.elements['/checkout-redirect/@serial-number'].value
+            redirect_url = xml_doc.elements['/checkout-redirect/redirect-url/text()'].value
+            return CheckoutRedirectResponse.new(serial_number, redirect_url)
+          else
+            raise "Unknown response:\n--\n#{xml_doc.to_s}\n--"
+          end
+        when Net::HTTPClientError then
+          xml_doc = REXML::Document.new(result.body)
+          
+          if xml_doc.elements['/error/@serial-number'].nil? or xml_doc.elements['/error/error-message/text()'].nil? then
+            raise "Invalid response from Google:\n---\n#{result.body}\n---"
+          end
+          
+          hash = 
+            {
+              :serial_number => xml_doc.elements['/error/@serial-number'].value,
+              :message       => xml_doc.elements['/error/error-message/text()'].value
+            }
+          
+          raise GoogleCheckoutError.new(hash)
+        when Net::HTTPRedirection, Net::HTTPServerError, Net::HTTPInformation then
+          raise "Unexpected reponse code (#{result.class}): #{result.code} - #{result.message}"
+        else
+          raise "Unknown reponse code: #{result.code} - #{result.message}"
+        end
+      end
+      
+      # Abstract method that is to contain the command's XML representation.
+      #
+      # Raises a NotImplementedError by default, override to remove this.
+      def to_xml
+        raise NotImplementedError, "Command#to_xml is abstract and must be overridden in a subclass."
+      end
+      
+      protected
+      
+        # Class method to return the OpenSSL::X509::Store instance for the
+        # CA certificates.
+        #--
+        # TODO: Is OpenSSL::X509::Store thread safe when reading only? This method most certainly is *not*. It must become so.
+        #++
+        def self.x509_store
+          return @@x509_store if defined?(@@x509_store)
+          
+          cacert_path = File.expand_path(File.dirname(__FILE__) + '/../../../var/cacert.pem')
+          
+          @@x509_store = OpenSSL::X509::Store.new
+          @@x509_store.add_file(cacert_path)
+          
+          return @@x509_store
+        end
+    end
+
+    # The CheckoutCommand represents a <checkout-shopping-cart> command sent
+    # to the server.
+    #
+    # A CheckoutCommand instance can have an arbitrary number of TaxTable
+    # and ShippingMethod instances. You must create these instances using the
+    # create_* methods which CheckoutCommand supplies.
+    # 
+    # CheckoutCommand#send_to_google_checkout returns CheckoutRedirectResponse 
+    # instances.
+    #
+    # Use the Frontend class to create new CheckoutCommand instances and do not
+    # instanciate the class directly.
+    #
+    # Note that you have to create/set the tax tables for CheckoutCommands before you
+    # can add any items to the cart that define a tax table.
+    #
+    # === Example
+    #
+    #   frontend = Google4R::Checkout::Frontend.new(configuration)
+    #   frontend.tax_table_factory = TaxTableFactory.new
+    #   command = frontend.create_checkout_command
+    class CheckoutCommand < Command
+      # The ShoppingCart of this CheckoutCommand.
+      attr_reader :shopping_cart
+      
+      # An array of the TaxTable objects of this CheckoutCommand. They have been
+      # created with the tax table factory of the frontend which created this
+      # command.
+      attr_reader :tax_tables
+      
+      # An array of ShippingMethod objects of this CheckoutCommand. Use 
+      # #create_shipping_method to create new shipping methods.
+      attr_reader :shipping_methods
+
+      # The URL at where the cart can be edited (String, optional).
+      attr_accessor :edit_cart_url
+      
+      # The URL to continue shopping after completing the checkout (String, optional).
+      attr_accessor :continue_shopping_url
+      
+      # A boolean flag; true iff the customer HAS to provide his phone number (optional).
+      attr_accessor :request_buyer_phone_number
+      
+      # Generates the XML for this CheckoutCommand.
+      def to_xml
+        CheckoutCommandXmlGenerator.new(self).generate
+      end
+      
+      # Initialize a new CheckoutCommand with a fresh CheckoutCart and an empty
+      # Array of tax tables and an empty array of ShippingMethod instances.
+      # Do not use this method directly but use Frontent#create_checkout_command
+      # to create CheckoutCommand objects.
+      def initialize(frontend)
+        super(frontend)
+        
+        @shopping_cart = ShoppingCart.new(self)
+        @tax_tables = frontend.tax_table_factory.effective_tax_tables_at(Time.new)
+        @shipping_methods = Array.new
+      end
+      
+      # Use this method to create a new shipping method. You have to pass in one of
+      # { PickupShipping, FlatRateShipping } for clazz. The method will create a 
+      # new instance of the class you passedin object and add it to the internal list 
+      # of shipping methods.
+      #
+      # If you pass a block to this method (preferred) then the newly created
+      # ShippingMethod object will be passed into this block for setting its attributes.
+      # The newly created shipping method will be returned in all cases.
+      #
+      # The first created shipping method will be used as the default.
+      #
+      # Raises a ArgumentError if the parameter clazz is invalid.
+      def create_shipping_method(clazz, &block)
+        if not [ PickupShipping, FlatRateShipping ].include?(clazz) then
+          raise ArgumentError, "Unknown shipping method: #{clazz.inspect}."
+        end
+        
+        shipping_method = clazz.new
+        @shipping_methods << shipping_method
+
+        yield(shipping_method) if block_given?
+        
+        return shipping_method
+      end
+    end
+
+    # CheckoutRedirectResponse instances are returned when a CheckoutCommand is successfully
+    # processed by Google Checkout.
+    class CheckoutRedirectResponse
+      # The serial number of the <checkout-redirect> response.
+      attr_reader :serial_number
+      
+      # The URL to redirect to.
+      attr_reader :redirect_url
+      
+      # Create a new CheckoutRedirectResponse with the given serial number and redirection URL.
+      # Do not create CheckoutRedirectResponse instances in your own code. Google4R creates them
+      # for you.
+      def initialize(serial_number, redirect_url)
+        @serial_number = serial_number
+        @redirect_url = redirect_url
+      end
+    end
+  end
+end

data/lib/google4r/checkout/frontend.rb

@@ -0,0 +1,108 @@
+#--
+# Project:   google4r
+# File:      lib/google4r/checkout/frontend.rb
+# Author:    Manuel Holtgrewe <purestorm at ggnore dot net>
+# Copyright: (c) 2007 by Manuel Holtgrewe
+# License:   MIT License as follows:
+#
+# 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. 
+#++
+# This file provides the Google4R::Checkout::Frontend class that is a factory for the commands
+# to be sent to Google Checkout.
+
+module Google4R #:nodoc:
+  module Checkout #:nodoc:
+    # The Frontend class is the factory that is to be used to create the Command (and later
+    # NotificationHandler) objects.
+    #
+    # === Example
+    #
+    #   configuration = { :merchant_id => '123456789', :merchant_key => '12345abcd' }
+    #
+    #   frontend = Google4R::Checkout::Frontend.new(configuration)
+    #
+    # == Tax Table Factory
+    #
+    # You have to set the tax_table_factory attribute of every Frontend object before you
+    # can call #create_checkout_command or #create_notification_handler because the
+    # objects created by those methods require tax tables.
+    #
+    # The Tax Table Factory must provide the method "effective_tax_tables_at" accept a Time 
+    # object and provide a method that returns an Array of TaxTable object that describe the
+    # effective tax rules at the given point of time.
+    #
+    # Effectively, this means you have to implement the Temporal Property pattern as described
+    # here: http://www.martinfowler.com/ap2/temporalProperty.html.
+    #
+    # == Example
+    #
+    #   class TaxTableFactory
+    #     def effective_tax_tables_at(time)
+    #       if time < Time.parse("Wed Apr 09 08:56:03 CDT 2003") then
+    #         table1, table2 = TaxTable.new, TaxTable.new
+    #         # ... set rules
+    #         [ table1, table 2]
+    #       else
+    #         table3, table4 = TaxTable.new, TaxTable.new
+    #         # ... set rules
+    #         [ table3, table 4]
+    #       end
+    #     end
+    #   end
+    #
+    #   frontend = Google4R::Checkout::Frontend.new(configuration)
+    #   frontend.tax_table_factory = TaxTableFactory.new
+    #
+    #   checkout_command = frontent.create_checkout_command
+    #   # ...
+    #   handler = frontend.create_notification_handler
+    class Frontend
+      # The configuration for this Frontend class. It will be used by all classes created
+      # by this Frontend instance (Hash).
+      attr_reader :configuration
+      
+      # An object with a factory method that can create the effective TaxTable objects 
+      # that were valid at a given point of time.
+      attr_accessor :tax_table_factory
+      
+      # Creates a new Frontend instance and sets the configuration attribute to the parameter
+      # configuration.
+      def initialize(configuration)
+        raise "Missing configuration setting: merchant_id"  if configuration[:merchant_id].nil?
+        raise "Missing configuration setting: merchant_key" if configuration[:merchant_key].nil?
+        raise "Missing configuration setting: use_sandbox"  if configuration[:use_sandbox].nil?
+        
+        @configuration = configuration.dup.freeze
+      end
+      
+      # Factory method that creates a new CheckoutCommand object. Use this method to create 
+      # your CheckoutCommand instances.
+      def create_checkout_command
+        return CheckoutCommand.new(self)
+      end
+      
+      # Factory method that creates a new NotificationHandler object. Use this method to
+      # create your NotificationHandler instances.
+      def create_notification_handler
+        return NotificationHandler.new(self)
+      end
+    end
+  end
+end