google4r 0.0.1

data/CHANGES

@@ -0,0 +1,5 @@
+= google4r Changelog
+
+== 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) 2006 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,75 @@
+= google4r
+
+google4r is a collection of libraries that allow you to access some of Google's web services using Ruby. At the moment, there are wrappers for
+
+* Google Maps
+* Google Checkout.
+
+You have to 'require' each library independently:
+
+  require 'google4r/maps'
+  require 'google4r/checkout'
+
+=== 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/.
+
+== Google Checkout
+
+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 'checkout_command_test.rb' in 'test/checkout' with the configuration for the Google4R::Checkout::Frontend class to use for running the tests.
+
+The file should contain content similar to:
+
+  # 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.
+
+== Google Maps
+
+The only part of the Google Maps API that can be standalone with sense is the Geocoder. The Google4R::Maps::Geocoder class allows to geocode address strings, i.e. finds a number of known locations that match the query to a certain degree. The information about the "known locations" includes the latitude and longitude of the location.
+
+=== Queries To Try Out
+
+<b>Querying for this string</b>:: <b>will yield n results</b>
+Helena:: 0
+1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA:: 1
+Janitell Rd, Colorado Springs, CO:: 2
+
+=== Maps Tests
+
+Note that you wil have to place a file called 'key.rb' in the directory 'test/maps' to be able to run unit tests. It should have the following contents:
+
+  GOOGLE_MAPS_KEY = '<your google maps key>'
+
+== Dependencies
+
+The unit tests use Mocha so you have to install the gem "mocha" to run the tests.
+

data/lib/google4r/checkout.rb

@@ -0,0 +1,36 @@
+#--
+# 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.
+
+# Tweak the paths so hmac works without modifications.
+$LOAD_PATH << File.expand_path(File.dirname(__FILE__) + '/checkout/vendor/hmac')
+
+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,267 @@
+#--
+# 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 'base64'
+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#%.
+      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#%.
+      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
+      
+      # Returns a hash with xml representation of this command and the signature for
+      # this representation. Both values are Base64 encoded.
+      #
+      # This can be used for generating the CheckoutButton when directly posted to
+      # Google.
+      #
+      #   command.sign_and_encode
+      #   # => { :cart => 'asdf', :signature => 'asdfasdf' }
+      def sign_and_encode
+        xml = self.to_xml
+        
+        # Create a signature of the XML using OpenSSL::HMAC. Note that we do not want a 
+        # hexadecimal result from the hash function but a binary result.
+        signature = OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new('sha1'), 
+          frontend.configuration[:merchant_key], xml)
+        
+        # Create Base64 encoded versions of the XML and the signature.
+        encoded_xml = Base64.encode64(xml)
+        encoded_signature = Base64.encode64(signature)
+        
+        return { :cart => encoded_xml, :signature => encoded_signature }
+      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.
+      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.
+      def to_xml
+        raise "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.
+        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 :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)
+        
+        @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 shipping method will be used as the default.
+      #
+      # Raises a RuntimeError if the parameter clazz is invalid.
+      def create_shipping_method(clazz, &block)
+        if not [ PickupShipping, FlatRateShipping ].include?(clazz) then
+          raise "Unknown shipping method: #{type.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
+      
+      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,100 @@
+#--
+# 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)
+    #   command = frontend.create_checkout_command
+    #
+    # == 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 those
+    # objects 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.
+    #
+    #   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 = Frontend.new
+    #  frontend.tax_table_factory = TaxTableFactory.new
+    class Frontend
+      # The configuration for this Frontend class. It will be used by all classes created
+      # by this Frontend instance.
+      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