ebay 0.5.0

data/README

@@ -0,0 +1,346 @@
+
+== Welcome to eBay4R
+
+eBay4R is a Ruby wrapper for eBay's Web Services SOAP API (v433). Emphasis is
+on ease of use and small footprint.
+
+<b>This code is currently alpha stage</b>.
+
+Please report bugs and other problems, see "Author" section at the bottom.
+
+Current releases and CVS snapshots can be downloaded from:
+
+http://rubyforge.org/projects/ebay4r
+
+
+== Requirements
+
+* SOAP4R library newer than v1.5.5.  At the time of this writing, the latest
+  version was v1.5.5, which will not work.  You have to get a snapshot that is
+  dated 11-06-2005 or newer.  You can find development snapshots here:
+
+  http://dev.ctor.org/download
+
+  So, for example, to download the 11-06-2005 snapshot (the one I personally
+  used during development), go here:
+
+  http://dev.ctor.org/download/archive/soap4r-20051106.tar.gz
+
+  Note: I _have_ seen one instance of SOAP4R v1.5.5 work out-of-the-box, and
+  that was on a Ruby v1.8.3 source install on NetBSD 2.1.  On my Debian 3.1
+  box, however, I had to install the newer snapshot.  Go figure, I don't 
+  know what the diff is...
+
+
+== Optionals
+
+* RubyGems
+
+
+== Installation
+
+=== tar/gzip
+
+Just unzip the archive anywhere you like, and see "Getting Started" below 
+(you will need to add the ebay4r/lib path to your $RUBYLIB environment
+variable)
+
+=== RubyGems
+
+* To install a gem you already downloaded:
+  
+    gem install ebay-<version>.gem
+
+* For the latest release with no fuss (previous download not required):
+  
+    gem install -r ebay4r
+
+=== CVS
+
+You can download the latest and greatest code using anonymous CVS, just type:
+
+  cvs -d :pserver:anonymous@rubyforge.org:/var/cvs/ebay4r login
+  cvs -d :pserver:anonymous@rubyforge.org:/var/cvs/ebay4r checkout ebay4r
+
+
+== Getting Started
+
+If you installed eBay4R from a tarball or CVS, you will want to add the
+ebay4r/lib directory to your Ruby include path ($RUBYLIB).  Then put
+
+  require 'eBayAPI'
+
+at the top of your programs.
+
+If you installed eBay4R with RubyGems, you don't have to add anything to
+Ruby's include path, just put
+
+  require 'rubygems'
+  require_gem 'ebay'
+
+at the top of your programs.
+
+=== Examples
+
+Look at the examples/ directory.  Edit the file myCredentials.rb and insert
+the appropriate values.  Then you can run any of the example programs.
+
+==== Hello, World!
+
+The simplest eBay API call is "GeteBayOfficialTime".  Here's how to call it
+with eBay4R:
+
+  require 'rubygems'
+  require_gem 'ebay'
+
+  # Put your credentials in this file
+  load('myCredentials.rb')
+
+  # Create new eBay caller object.  Omit last argument to use live platform.
+  eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)
+
+  resp = eBay.GeteBayOfficialTime
+
+  puts "Hello, World!"
+  puts "The eBay time is now: #{resp.timestamp}"
+
+  # Wasn't that easy?!
+
+==== Adding an Item
+
+This is a more complex example that performs a real (useful) function:
+
+  require 'rubygems'
+  require_gem 'ebay'
+
+  load('myCredentials.rb')
+
+  eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)
+
+  # New method of generating complex types, needs some more testing...
+  resp = eBay.AddItem(:Item => EBay.Item(:PrimaryCategory => EBay.Category(:CategoryID => 57882),
+                                         :Title => 'Mouse Pad',
+                                         :Description => 'A really cool mouse pad, you know you want it...',
+                                         :Location => 'On Earth',
+                                         :StartPrice => 12.0,
+                                         :Quantity => 1,
+                                         :ListingDuration => "Days_7",
+                                         :Country => "US",
+                                         :Currency => "USD",
+                                         :PaymentMethods => ["VisaMC", "PersonalCheck"]))
+
+  puts "New Item #" + resp.itemID + " added."
+
+
+=== Format of Requests
+
+If <tt>eBay</tt> is your caller object, then you can issue any eBay API call
+by doing:
+
+  eBay.<call_name>( ... hash of named-arguments ... )
+
+For example, to issue the GetItem call for Item ##4503432058 and return all
+information, you do:
+
+  eBay.GetItem(:DetailLevel => 'ReturnAll', :ItemID => '4503432058')
+
+or to see your last invoice using the GetAccount call, you do:
+
+  eBay.GetAccount(:AccountHistorySelection => 'LastInvoice')
+
+See the "eBay Web Services SOAP API Guide" for acceptable parameters and values
+for each API call.  This guide can be downloaded at eBay's 
+{SOAP Development Center}[http://developer.ebay.com/soap/].
+
+==== Passing Complex Data Types
+
+A number of elements in eBay's schema are XML Schema simple types.  For
+example, CategoryID, Title, and Description are all strings.  But many 
+elements, like Item and Seller, are of types "ItemType" and "SellerType", 
+respectively.  These are complex data types, meaning they are structures
+composed of collections of simple types.
+
+"How do I make a complex type object?", you ask.  Simple:
+
+  EBay.<element_name>( ... hash of named-arguments ... )
+
+creates a new <em><element_name></em> element of type <em><element_name></em>Type.  For
+example,
+
+  EBay.Item(:Title => 'Mouse Pad', :Description => '...')
+
+creates a new ItemType object.  Please note, these factory methods are class
+methods of module EBay, so the upper-case "E" in "EBay" is not a typo.  A
+more common way to see this is:
+
+  EBay::Item( ... )
+
+The only difference is if you do not pass any arguments to the factory method
+and do not explicitly put empty parentheses (), Ruby will assume it is a 
+constant, not a method.
+
+
+=== Format of Responses
+
+There is a one-to-one correspondence between the XML returned by eBay and the
+way you access the values contained therein using the response object returned
+by the call.  For example, let's say you issued a "GetItem" call:
+  
+  resp = eBay.GetItem(:DetailLevel => 'ReturnAll', :ItemID => '4503432058')
+
+and eBay returned the following XML (abbreviated where appropriate):
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
+                    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
+                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+   <soapenv:Body>
+    <GetItemResponse xmlns="urn:ebay:apis:eBLBaseComponents">
+     <Timestamp>2005-12-09T09:40:41.602Z</Timestamp>
+     <Ack>Success</Ack>
+     <Version>437</Version>
+     <Build>e437_core_Bundled_2119808_R1</Build>
+     <Item>
+      ...
+
+      <AutoPay>false</AutoPay>
+      <BuyerProtection>ItemIneligible</BuyerProtection>
+      <BuyItNowPrice currencyID="USD">0.0</BuyItNowPrice>
+      <Country>US</Country>
+      <Currency>USD</Currency>
+      <Description>Fund. of Physics, 5th, by Halliday, Resnick, Walker</Description>
+      <Escrow>None</Escrow>
+      <GiftIcon>0</GiftIcon>
+      ...
+
+      <ShipToLocations>US</ShipToLocations>
+      <ShipToLocations>CA</ShipToLocations>
+     </Item>
+    </GetItemResponse>
+   </soapenv:Body>
+  </soapenv:Envelope>
+
+
+The "resp" object is of type
+  
+  SOAP::Mapping::Object
+
+and contains all the XML elements between <tt><GetItemResponse> ... </GetItemResponse></tt>.
+
+So, if you want to print the item description, just do:
+
+  puts resp.item.description
+
+and you will see:
+  
+  "Fund. of Physics, 5th, by Halliday, Resnick, Walker"
+
+Repeated XML elements automatically become arrays of the same name, so to see
+all the locations this item can ship to, just do:
+
+  resp.item.shipToLocations.each { |loc| puts loc }
+
+and you will see:
+
+  US
+  CA
+
+It's that easy! (Are any Java or C# developers reading this?  Don't be
+jealous... ;)
+
+=== A Note about Case
+
+Astute readers (all of you, right?) will notice that the first letter of every
+element contained within the response object is lower-case, even though in the
+XML it is upper-case.  This is currently the way things are and you will have
+to remember to lower the first character in your code.  
+
+Ruby's convention is that only classes, modules, and constants begin with 
+upper-case letters.  The author of the SOAP4R library (which contains 
+wsdl2ruby.rb) respected this convention, and as a result, the eBay.rb 
+file I use (generated from eBay's WSDL) has this mapping.
+
+I haven't come up with any Ruby magic to dynamically allow upper-case first
+characters to work also, so if you happen to want to take a crack at it and
+get it working, please send me your patches (see "Author" section at the 
+bottom).
+
+Please note, the opposite does _not_ apply.  That is, you can *submit* a call
+using either case of the first character, and your arguments can also have
+either case letter first.  For example, this:
+
+  resp = eBay.GetItem(:DetailLevel => 'ReturnAll', :ItemID => '4503432058')
+
+is the same as:
+
+  resp = eBay.getItem(:detailLevel => 'ReturnAll', :itemID => '4503432058')
+
+
+== Debugging
+
+If "eBay" is your eBay caller object, as in:
+
+  eBay = EBay::API.new( ... )
+
+You can see XML wiredumps by doing:
+
+  eBay.debug = true
+
+before you issue any eBay API calls.  This is useful to see the raw XML of
+what eBay is sending back to you.
+
+
+== Files
+
+examples/
+  Examples of eBay API calls using this library. You will want to check out
+  these examples before making your own calls.
+
+lib/eBayAPI.rb
+  The heart of this library
+
+lib/eBayDriver.rb
+  Autogenerated by wsdl2ruby.rb
+
+lib/eBay.rb
+  Autogenerated by wsdl2ruby.rb
+
+lib/RequesterCredentialsHandler.rb
+  Helper for generating the eBay Authentication header for each call
+
+test/
+  Unit and functional tests
+
+
+== To Do
+
+* Add many more examples
+* Add more unit and functional tests
+
+
+== Author
+
+Garry C. Dolley
+
+gdolley [at] ucla.edu
+
+AIM: garry97531
+
+
+== Copyright
+
+Copyright (c) 2005 Garry C. Dolley
+
+eBay4R is free software; you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later 
+version.
+
+eBay4R is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+details.
+
+You should have received a copy of the GNU General Public License along with
+eBay4R; if not, write to the Free Software Foundation, Inc., 51 Franklin
+Street, Fifth Floor, Boston, MA  02110-1301, USA

data/examples/add_item.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require 'eBayAPI'
+
+#
+# Example of AddItem call
+#
+
+load('myCredentials.rb')
+
+eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)
+
+# New method of generating complex types, needs some more testing...
+resp = eBay.AddItem(:Item => EBay.Item(:PrimaryCategory => EBay.Category(:CategoryID => 57882),
+                                       :Title => 'Mouse Pad',
+                                       :Description => 'A really cool mouse pad, you know you want it...',
+                                       :Location => 'On Earth',
+                                       :StartPrice => 12.0,
+                                       :Quantity => 1,
+                                       :ListingDuration => "Days_7",
+                                       :Country => "US",
+                                       :Currency => "USD",
+                                       :PaymentMethods => ["VisaMC", "PersonalCheck"]))
+
+puts "New Item #" + resp.itemID + " added."
+puts "You spent:\n"
+
+
+# The fees part of the response looks like this:
+#
+# <Fees>
+#   <Fee>
+#     <Name>AuctionLengthFee</Name>
+#     <Fee currencyID="USD">0.0</Fee>
+#   </Fee>
+#   <Fee>
+#     <Name>BoldFee</Name>
+#     <Fee currencyID="USD">0.0</Fee>
+#   </Fee>
+#   ...
+#   <Fee>
+#     <Name>InsertionFee</Name>
+#     <Fee currencyID="USD">0.6</Fee>
+#   </Fee>   
+#   ...
+# </Fees>
+#
+# So this is now we traverse it:
+resp.fees.fee.each do |fee|
+  puts fee.name + ": " + fee.fee + " " + fee.fee.xmlattr_currencyID
+end
+
+# Notice how the object names reflect the XML element names, and any element
+# that is repeated automatically becomes an array, so you can run "each" on
+# it.

data/examples/get_account.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require 'eBayAPI'
+
+#
+# Example of GetAccount call requesting the last monthly statement
+#
+
+load('myCredentials.rb')
+
+eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)
+
+resp = eBay.GetAccount(:AccountHistorySelection => 'LastInvoice')
+
+puts "AccountID: " + resp.accountID
+puts "Account Summary -- Account State: " + resp.accountSummary.accountState
+
+# Not all statements will have an <AccountState>, so we only print it if present
+puts "Account Summary -- Account State: " + resp.accountSummary.accountState if resp.accountSummary.respond_to?(:accountState)
+
+# Some statements may not have any entries in them (no sales that month?), so
+# we must test to make sure "accountEntries" exists before we traverse it.
+if resp.respond_to?(:accountEntries)
+  resp.accountEntries.accountEntry.each do |entry|
+    puts "Account Entries -- Description: " + entry.description
+  end
+end
+
+# Many more fields may be present, see eBay's SOAP API Guide or GetAccountResponseType class in "../lib/eBay.rb"

data/examples/get_account2.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require 'eBayAPI'
+
+#
+# Example of GetAccount call requesting a specific monthly statement
+#
+
+load('myCredentials.rb')
+
+eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)
+
+resp = eBay.GetAccount(:AccountHistorySelection => 'SpecifiedInvoice', :InvoiceDate => '2005-11-01')
+
+puts "AccountID: " + resp.accountID
+puts "Account Summary -- Invoice Balance: " + resp.accountSummary.invoiceBalance
+
+# Not all statements will have an <AccountState>, so we only print it if present
+puts "Account Summary -- Account State: " + resp.accountSummary.accountState if resp.accountSummary.respond_to?(:accountState)
+
+# Some statements may not have any entries in them (no sales that month?), so
+# we must test to make sure "accountEntries" exists before we traverse it.
+if resp.respond_to?(:accountEntries)
+  resp.accountEntries.accountEntry.each do |entry|
+    puts "Account Entries -- Description: " + entry.description
+  end
+end
+
+# Many more fields may be present, see eBay's SOAP API Guide or GetAccountResponseType class in "../lib/eBay.rb"