ebay 0.8.0 → 1.1

data/README

@@ -1,95 +1,129 @@
+=================
+Welcome to eBay4R
+=================
 
-== Welcome to eBay4R
+:Author: Garry Dolley
+:Date: 03-28-2008
+:Version: v1.1
+:eBay API: 555
 
-eBay4R is a Ruby wrapper for eBay's Web Services SOAP API (v481). Emphasis is
+eBay4R is a Ruby wrapper for eBay's Web Services SOAP API (v555). Emphasis is
 on ease of use and small footprint.
 
 Please report bugs and other problems, see "Author" section at the bottom.
 
-Current releases and CVS snapshots can be downloaded from:
+Current release can be downloaded from:
 
 http://rubyforge.org/projects/ebay4r
 
+The latest code is in the following Git repository:
 
-== Requirements
+git://github.com/up_the_irons/ebay4r.git
 
-* 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
+Requirements
+------------
 
-  So, for example, to download the 11-06-2005 snapshot (the one I personally
-  used during development), go here:
+* SOAP4R library v1.5.7 or newer.  The specific version I'm using for testing
+  is soap4r-1.5.7.90.20070921.
 
-  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
+Optionals
+---------
 
 * RubyGems
 
 
-== Installation
+Installation
+------------
 
-=== tar/gzip
+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
+RubyGems
+~~~~~~~~
 
-* To install a gem you already downloaded:
+* To install a gem you already downloaded::
   
     gem install ebay-<version>.gem
 
-* For the latest release with no fuss (previous download not required):
+* For the latest release with no fuss (previous download not required)::
   
     gem install -r ebay
 
-=== CVS
+Git
+~~~
+
+You can download the latest and greatest code using Git, just type::
+
+  git clone git://github.com/up_the_irons/ebay4r.git
+
+
+Important Note about Using eBay4R and Ruby on Rails
+---------------------------------------------------
+
+If you installed SOAP4R as a gem you must put the following two lines at the
+very top of your config/environment.rb::
+
+  require 'rubygems'
+  gem 'soap4r'
+
+This must be done before Rails starts auto-loading things.
+
+Additionally, you have to put those two lines in *every* Rails app you have
+on your machine, even if it doesn't use SOAP4R!  This is, allegedly, because
+ActiveSupport (in dependency.rb) wrongly loads the SOAP4R included with Ruby
+instead of your Gem.  More details can be found here:
+
+  http://dev.ctor.org/soap4r/ticket/433
 
-You can download the latest and greatest code using anonymous CVS, just type:
+If you get this error, or similar, in every Rails app::
 
-  cvs -d :pserver:anonymous@rubyforge.org:/var/cvs/ebay4r login
-  cvs -d :pserver:anonymous@rubyforge.org:/var/cvs/ebay4r checkout ebay4r
+  [...]/activesupport-1.4.2/lib/active_support/dependencies.rb:477:in `const_missing': uninitialized constant XSD::NS::KNOWN_TAG (NameError?)
 
+you've hit this problem.
 
-== Getting Started
 
-If you installed eBay4R from a tarball or CVS, you will want to add the
+Getting Started
+---------------
+
+If you installed eBay4R from a tarball or git repo, you will want to add the
 ebay4r/lib directory to your Ruby include path ($RUBYLIB).  Then put
 
-  require 'eBayAPI'
+::
 
+  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'
+  gem 'ebay'
 
 at the top of your programs.
 
-=== Examples
+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!
+Hello, World!
+~~~~~~~~~~~~~
 
 The simplest eBay API call is "GeteBayOfficialTime".  Here's how to call it
-with eBay4R:
+with eBay4R::
 
   require 'rubygems'
-  require_gem 'ebay'
+  gem 'ebay'
 
   # Put your credentials in this file
   load('myCredentials.rb')
@@ -104,72 +138,60 @@ with eBay4R:
 
   # Wasn't that easy?!
 
-==== Adding an Item
+Adding an Item
+~~~~~~~~~~~~~~
 
-This is a more complex example that performs a real (useful) function:
+This is a more complex example that performs a real (useful) function::
 
   require 'rubygems'
-  require_gem 'ebay'
+  gem 'ebay'
 
   load('myCredentials.rb')
 
   eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)
 
   # Notice how we nest hashes to mimic the XML structure of an AddItem request
-  resp = eBay.AddItem(:Item => { :PrimaryCategory => { :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."
-
-The way we nest hashes in the above AddItem() call may be confusing at first. 
-It is just a short-hand way of creating the complex types we need for the 
-call.
-
-You may instead explicitly create the complex types (see "Creating Complex 
-Data Types" below) needed for the call (it makes the code longer, but a bit
-more readable):
-
   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,
+                                         :StartPrice => '12.0',
                                          :Quantity => 1,
                                          :ListingDuration => "Days_7",
                                          :Country => "US",
                                          :Currency => "USD",
                                          :PaymentMethods => ["VisaMC", "PersonalCheck"]))
 
+  puts "New Item #" + resp.itemID + " added."
+
+
+Don't worry too much about EBay.Item and EBay.Category calls for now, they are
+explained in the "Creating Complex Data Types" section below.
 
-=== Format of Requests
 
-If <tt>eBay</tt> is your caller object, then you can issue any eBay API call
-by doing:
+Format of Requests
+~~~~~~~~~~~~~~~~~~
+
+If ``eBay`` 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:
+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:
+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/].
+`SOAP Development Center <http://developer.ebay.com/soap/>`_.
 
-==== Creating Complex Data Types
+Creating 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 
@@ -177,18 +199,20 @@ 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:
+"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
+creates a new `<element_name>` element of type ``<element_name>Type``.  For
 example,
 
+::
+
   EBay.Item(:Title => 'Mouse Pad', :Description => '...')
 
-creates a new ItemType object.  Please note, these factory methods are class
+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:
+more common way to see this is::
 
   EBay::Item( ... )
 
@@ -196,27 +220,29 @@ 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.
 
-==== Setting XML Attributes
+Setting XML Attributes
+~~~~~~~~~~~~~~~~~~~~~~
 
-The symbol you use to set an XML attribute on an element is:
+The symbol you use to set an XML attribute on an element is::
 
   :xmlattr_<attribute_name>
 
 For example, to create a <Label> element (corresponding to eBay's LabelType)
-with an attribute of "visible" equal to "true", you would do:
+with an attribute of "visible" equal to "true", you would do::
 
   EBay.Label(:Name => "some string", :xmlattr_visible => true)
 
 
-=== Format of Responses
+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:
+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):
+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/" 
@@ -253,22 +279,22 @@ The "resp" object is of type
   
   SOAP::Mapping::Object
 
-and contains all the XML elements between <tt><GetItemResponse> ... </GetItemResponse></tt>.
+and contains all the XML elements between ``<GetItemResponse> ... </GetItemResponse>``.
 
-So, if you want to print the item description, just do:
+So, if you want to print the item description, just do::
 
   puts resp.item.description
 
-and you will see:
+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:
+all the locations this item can ship to, just do::
 
   resp.item.shipToLocations.each { |loc| puts loc }
 
-and you will see:
+and you will see::
 
   US
   CA
@@ -276,7 +302,8 @@ and you will see:
 It's that easy! (Are any Java or C# developers reading this?  Don't be
 jealous... ;)
 
-=== A Note about Case
+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
@@ -295,22 +322,23 @@ 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:
+either case letter first.  For example, this::
 
   resp = eBay.GetItem(:DetailLevel => 'ReturnAll', :ItemID => '4503432058')
 
-is the same as:
+is the same as::
 
   resp = eBay.getItem(:detailLevel => 'ReturnAll', :itemID => '4503432058')
 
 
-== Debugging
+Debugging
+---------
 
-If "eBay" is your eBay caller object, as in:
+If "eBay" is your eBay caller object, as in::
 
   eBay = EBay::API.new( ... )
 
-You can see XML wiredumps by doing:
+You can see XML wiredumps by doing::
 
   eBay.debug = true
 
@@ -318,7 +346,8 @@ before you issue any eBay API calls.  This is useful to see the raw XML of
 what eBay is sending back to you.
 
 
-== Files
+Files
+-----
 
 contrib/
   Extras contributed by the community (myself included)
@@ -343,13 +372,15 @@ test/
   Unit and functional tests
 
 
-== To Do
+To Do
+-----
 
 * Add many more examples
 * Add more unit and functional tests
 
 
-== Author
+Author
+------
 
 Garry C. Dolley
 
@@ -357,10 +388,27 @@ gdolley [at] NOSPAM- ucla.edu
 
 AIM: garry97531
 
+IRC: up_the_irons in #ram, #git, #caboose on Freenode (and usually many other
+channels)
+
+
+Formatting
+----------
+
+I've dropped RDoc formatting for this README.  Headings never looked like
+headings to me, which was annoying.
+
+This README is formatted in reStructredText [RST]_.  It has the best
+correlation between what a document looks like as plain text vs. its
+formatted output (HTML, LaTeX, etc...).  What I like best is, markup doesn't
+look like markup, even though it is.
+
+.. [RST] http://docutils.sourceforge.net/rst.html
 
-== Copyright
+Copyright
+---------
 
-Copyright (c) 2005,2006 Garry C. Dolley
+Copyright (c) 2005,2006,2007,2008 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
@@ -376,4 +424,3 @@ 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
 
-$Id: README,v 1.19 2006/10/10 08:39:11 garrydolley Exp $

data/contrib/ebay_platform_notifications.txt

@@ -1,3 +1,7 @@
+[Author's note: the example code for SetNotificationPreferences below is old
+and won't work with eBay4R v1.0 or above.  See 
+examples/set_notification_preferences.rb for a more up-to-date code sample]
+
 Below is a bit of documentation contributed by David Balatero regarding eBay 
 Platform Notifications: