google_checkout 0.1.0

data/doc/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2006 Peter Elmore (pete.elmore at gmail.com)
+
+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/doc/README

@@ -0,0 +1,108 @@
+= GoogleCheckout
+
+== Installation
+
+Currently, it's only available as a gem.
+
+== What is Google Checkout?
+
+Well, according to Google, "Google Checkout helps you increase sales.  And
+process them for free when you advertise with Google."  What it really amounts
+to is that Google will process your orders for a 10% fee and you get a little
+shopping cart icon in your ad if you advertise through AdWords.  The fee can
+be paid by running AdWords ads on your site.  You can read about it and get an
+account at http://checkout.google.com/sell .
+
+== What is google-checkout?
+
+google-checkout is a module for working with the Google Checkout API
+(http://code.google.com/apis/checkout/index.html).  Specifically, if you have
+a Google Checkout account, you can use this module to do things like add
+"Checkout" and "Buy Now" buttons to your site.
+
+== Brief Example
+
+  require 'rubygems'
+  require 'google-checkout'
+
+  merchant_id = 'Your merchant id.'
+  merchant_key = 'Your merchant key.  Keep this a secret!'
+
+  cart = GoogleCheckout::Cart.new(merchant_id, merchant_key)
+  cart.add_item(:name => 'Chair', :description => 'A sturdy, wooden chair',
+                :price => 44.99)
+  puts cart.checkout_button
+
+== Usage
+
+First, you'll need a merchant ID and a merchant key, which you can get from
+the Google Checkout site once you have an account.  After you have that, you
+can start writing code.  
+
+The class you'll be working with is GoogleCheckout::Cart.  Of course, it
+represents a cart, and you can fill it with items.  
+
+  cart = GoogleCheckout::Cart.new(merchant_id, merchant_key, item1, item2)
+  cart.add_item item3
+
+The items you put into the cart should be one of two types:
+* A Hash containing the following
+** :name
+** :description
+** :price
+** :quantity (default 1)
+** :currency (default 'USD')
+** :regular_shipping, the shipping cost (default $0)
+* Or any Object that has a method called to_google_product that returns a hash
+  like the one described.
+
+Once you have a cart full of items, you can generate the XML for the API call
+by calling Cart#checkout_xml, although you'll probably just want to add a
+checkout button to your page with Cart#checkout_button.  This method generates
+HTML for a form containing a button and the hidden inputs necessary to call
+Google Checkout.  Cart#checkout_button has plenty of options for controlling
+the look of the button.  Once again, the arguments are passed as a hash,
+although the defaults are usually reasonable so you might not need to pass
+anything.
+
+* :size is the size of the button, one of :small, :medium, or :large.  Google
+  is picky about the sizes of these buttons.  See GoogleCheckout::ButtonSizes
+  for more information.  The default is :medium.
+* :variant is one of 'disabled' or 'text'.  'disabled' means that the button 
+  should be greyed-out; it is used in cases that the item you are selling
+  cannot be bought via Google Checkout.  (There's a long list of items that
+  are not allowed at https://checkout.google.com/seller/content_policies.html
+* :buy_or_checkout must be one of :buy_now or :checkout .  This determines the
+  look of the button that will be displayed.  The default is to use :checkout
+  if there are two or more items in the cart.
+* :style must be one of 'white' or 'trans'.  'white' gets you a white button,
+  while 'trans' gets you a transparent button suitable for use on non-white
+  backgrounds.  The default is 'white'.
+
+  cart.checkout_button :size => :small, :style => 'trans'
+
+When users click the button, they will be taken to the Google Checkout page
+with a cart full of the products you specified, and your work is done.
+
+== Missing Features
+
+* Level 1 integration is complete except for tax tables
+* Level 2 integration is missing.  
+
+See
+http://checkout.google.com/support/sell/bin/answer.py?answer=42917&topic=8671
+for more information about the two integration levels.
+
+If there are missing features I haven't thought of, let me know.
+
+== Bugs
+
+No 'hard' bugs, I hope.  My contact information is at the bottom of the page
+if you find one.  There may be more subjective bugs (e.g., design issues);
+feel free to tell me about these, too.
+
+== Contact Information
+
+The home page is at http://debu.gs/google-checkout .  You can email me at pete
+dot elmore at gmail dot com.  Try to mention Google Checkout in the subject
+line.

data/lib/google-checkout.rb

@@ -0,0 +1,228 @@
+require 'rubygems'
+
+require 'hmac-sha1'
+require 'base64'
+
+require 'builder/xmlmarkup'
+
+# For the impatient or forgetful:
+#   item = { :name => 'A Quarter', :description => 'One shiny quarter.', 
+#            :price => 0.25 }
+#   cart = GoogleCheckout::Cart.new(merchant_id, merchant_key, item)
+#   cart.add_item(:name => "Pancakes", :description => "Flapjacks by mail."
+#                 :price => 0.50, :quantity => 10)
+#   File.open('commerce.html', 'w') { |f| 
+#     f.write(
+#       "<html><body>Click this button to buy a quarter and ten pancakes:" +
+#       cart.checkout_button + "</body></html>")
+#   }
+#
+# If you're interested in a little more detail, you'll want to have a look at
+# GoogleCheckout::Cart, Cart#add_item, Cart#checkout_xml, and
+# Cart#checkout_button.
+module GoogleCheckout
+	CheckoutURL = "checkout.google.com"
+	SubmitURL = "https://#{CheckoutURL}/cws/v2/Merchant"
+
+
+	# These are the only sizes allowed by Google.  These shouldn't be needed
+	# by most people; just specify the :size and :buy_or_checkout options to
+	# Cart#checkout_button and the sizes are filled in automatically.
+	ButtonSizes = {
+		:checkout => {
+			:small => { :w => 160, :h => 43 },
+			:medium => { :w => 168, :h => 44 },
+			:large => { :w => 180, :h => 46 },
+		},
+
+		:buy_now => {
+			:small => { :w => 117, :h => 48 },
+			:medium => { :w => 121, :h => 44 },
+			:large => { :w => 121, :h => 44 },
+		},
+	}
+
+	# This class represents a cart for Google Checkout.  After initializing it
+	# with a +merchant_id+ and +merchant_key+, you add items via add_item, 
+	# and can then get xml via checkout_xml, or html code for a form that 
+	# provides a checkout button via checkout_button.
+	class Cart
+		attr_accessor :merchant_id, :merchant_key
+
+		include GoogleCheckout
+
+		# The default options for drawing in the button that are filled in when
+		# checkout_button or button_url is called.
+		DefaultButtonOpts = {
+			:size => :medium,
+			:style => 'white',
+			:variant => 'text',
+			:loc => 'en_US',
+			:buy_or_checkout => nil,
+		}
+
+		# You need to supply, as strings, the +merchant_id+ and +merchant_key+ 
+		# used to identify your store to Google.  You may optionally supply one
+		# or more items to put inside the cart.
+		def initialize(merchant_id, merchant_key, *items)
+			@merchant_id = merchant_id
+			@merchant_key = merchant_key
+			@contents = []
+			items.each { |i| add_item i }
+		end
+
+		def empty?
+			@contents.empty?
+		end
+
+		# Number of items in the cart.
+		def size
+			@contents.size
+		end
+		  
+		# This method returns the URL to which the form should be submitted.
+		def submit_url 
+			[SubmitURL, @merchant_id, 'checkout'].join('/')
+		end
+
+		# This method puts items in the cart.
+		# +item+ may be a hash, or have a method named +to_google_product+ that
+		# returns a hash with the required values.
+		# * name 
+		# * description (a brief description as it will appear on the bill)
+		# * price
+		# You may fill in some optional values as well:
+		# * quantity (defaults to 1)
+		# * currency (defaults to 'USD')
+		def add_item(item)
+			@xml = nil
+			if item.respond_to? :to_google_product
+				item = item.to_google_product
+			end
+
+			# We need to check that the necessary keys are in the hash,
+			# Otherwise the error will happen in the middle of checkout_xml,
+			# and the bug will be harder to track.
+			missing_keys = [ :name, :description, :price ].select { |key|
+				!item.include? key
+			}
+
+			unless missing_keys.empty?
+				raise ArgumentError, 
+					"Required keys missing: #{missing_keys.inspect}"
+			end
+
+			@contents << { :quantity => 1, :currency => 'USD' }.merge(item)
+			item
+		end
+
+		# This is the important method; it generatest the XML call.  
+		# It's fairly lengthy, but trivial.  It follows the docs at
+		# http://code.google.com/apis/checkout/developer/index.html#checkout_api
+		#
+		# It returns the raw XML string, not encoded.  
+		def checkout_xml
+			raise RuntimeError, "Empty cart" if self.empty?
+
+			xml = Builder::XmlMarkup.new
+			xml.instruct!
+			@xml = xml.tag!('checkout-shopping-cart', 
+					 :xmlns => "http://checkout.google.com/schema/2") {
+				xml.tag!("shopping-cart") {
+					xml.items { 
+						@contents.each { |item|
+							xml.item {
+								xml.tag!('item-name') {
+									xml.text! item[:name].to_s
+								}
+								xml.tag!('item-description') {
+									xml.text! item[:description].to_s
+								}
+								xml.tag!('unit-price', 
+									:currency => (item[:currency] || 'USD')) {
+									xml.text! item[:price].to_s
+								}
+								xml.quantity {
+									xml.text! item[:quantity].to_s
+								}
+							}
+						}
+					} 
+				}
+				xml.tag!('checkout-flow-support') {
+					xml.tag!('merchant-checkout-flow-support') {
+						xml.tag!('shipping-methods') {
+							xml.tag!('flat-rate-shipping', :name =>'Shipping') {
+								currency = 'USD'
+								shipping = @contents.inject(0) { |total,i| 
+									# Mixing currency not allowed; this library
+									# can't convert between currencies.
+									currency = i[:currency] || currency
+									total + i[:regular_shipping].to_i
+								}.to_s
+								xml.price(:currency => currency) {
+									xml.text! shipping
+								}
+							}
+						}
+					}
+				}
+			}
+			@xml.dup
+		end
+
+		# Returns the signature for the cart XML.
+		def signature
+			@xml or checkout_xml
+			HMAC::SHA1.digest(@merchant_key, @xml)
+		end
+
+		# Returns HTML for a checkout form for buying all the items in the 
+		# cart.  
+		def checkout_button(button_opts = {})
+			@xml or checkout_xml
+			burl = button_url(button_opts)
+			html = Builder::XmlMarkup.new(:indent => 2)
+			html.form(:action => submit_url, :style => 'border: 0;',
+				:id => 'BB_BuyButtonForm', :method => 'post', 
+				:name => 'BB_BuyButtonForm') {
+					html.input(:name => 'cart', :type => 'hidden', 
+						:value => Base64.encode64(@xml).gsub("\n", ''))
+					html.input(:name => 'signature', :type => 'hidden',
+						:value => Base64.encode64(signature).gsub("\n", ''))
+					html.input(:alt => 'Google Checkout',
+						:style => "width: auto;",
+						:src => button_url(button_opts),
+						:type => 'image')
+			}
+		end
+
+		# Given a set of options for the button, button_url returns the URL 
+		# for the button image.
+		# The options are the same as those specified on
+		# http://checkout.google.com/seller/checkout_buttons.html , with a
+		# couple of extra options for convenience.  Rather than specifying the
+		# width and  height  manually, you may specify :size to be one of
+		# :small, :medium,  or :large,  and that you may set :buy_or_checkout
+		# to :buy_now or  :checkout to get  a 'Buy Now' button versus a
+		# 'Checkout' button.  If  you don't specify  :buy_or_checkout, the Cart
+		# will try to guess based  on if the cart has  more than one item in
+		# it.  Whatever you don't pass will be filled in with the defaults from
+		# DefaultButtonOpts.
+		def button_url(opts = {})
+			opts = DefaultButtonOpts.merge opts
+			opts[:buy_or_checkout] ||= @contents.size > 1 ? :checkout : 
+			                                                :buy_now
+			opts.merge! ButtonSizes[opts[:buy_or_checkout]][opts[:size]]
+			bname = opts[:buy_or_checkout] == :buy_now ? 'buy.gif' : 
+			                                             'checkout.gif'
+			opts.delete :size
+			opts.delete :buy_or_checkout
+			opts[:merchant_id] = @merchant_id
+
+			path = opts.map { |k,v| "#{k}=#{v}" }.join('&')
+
+			"http://#{CheckoutURL}/buttons/#{bname}?#{path}"
+		end
+	end
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.8
+specification_version: 1
+name: google_checkout
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2006-12-17
+summary: An interface to the Google Checkout API.
+require_paths: 
+- lib
+email: pete.elmore@gmail.com
+homepage: http://debu.gs/google-checkout
+rubyforge_project: 
+description: 
+autorequire: google-checkout
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+authors: 
+- Pete Elmore
+files: 
+- doc/LICENSE
+- doc/README
+- lib/google-checkout.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: 
+- doc/README
+- doc/LICENSE
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+